Skip to content

feat(LLMsDocsGenerator): support core-only package generation - #1299

Merged
ArgoZhang merged 4 commits into
masterfrom
argozhang-llms-docs-pack-mode
Nov 14, 2026
Merged

ArgoZhang merged 4 commits into
masterfrom
argozhang-llms-docs-pack-mode

Conversation

@ArgoZhang

@ArgoZhang ArgoZhang commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Link issues

fixes #1298

Summary By Copilot

  • Add --core-only generation for BootstrapBlazor package documentation.
  • Write package docs directly to --output while preserving unrelated existing files.
  • Skip extension sources and update package version and bilingual usage docs.

Regression?

  • Yes
  • No

Risk

  • High
  • Medium
  • Low

The default website output layout remains unchanged; core-only is opt-in.

Verification

  • Manual (required)

  • Automated

  • dotnet build tools\BootstrapBlazor.LLMsDocsGenerator\BootstrapBlazor.LLMsDocsGenerator.csproj --no-restore — passed with 0 warnings/errors.

  • Ran the CLI in --core-only mode against the sibling BootstrapBlazor checkout — generated 236 component and 52 service documents directly under the selected output and preserved existing files/directories.

Packaging changes reviewed?

  • Yes
  • No
  • N/A

☑️ Self Check before Merge

⚠️ Please check all items below before review. ⚠️

  • Doc is updated/provided or not needed
  • Demo is updated/provided or not needed
  • Merge the latest code from the main branch

Summary by Sourcery

Add opt-in core-only documentation generation for BootstrapBlazor packaging while preserving existing full-site generation behavior.

New Features:

  • Add an opt-in --core-only mode that generates BootstrapBlazor core component and service documentation without extension sources.

Enhancements:

  • Write core-only documentation directly to the selected output directory while preserving unrelated existing files and retaining the default website layout.
  • Validate that core components and services are discovered before generation proceeds.

Build:

  • Update the documentation generator package version.

Documentation:

  • Document core-only usage, output behavior, packaging workflow, and requirements in English and Chinese.

Tests:

  • Update integration verification to cover core-only packaging and full website generation.

ArgoZhang and others added 4 commits November 13, 2026 16:01
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@bb-auto bb-auto Bot added the enhancement New feature or request label Nov 14, 2026

@bb-auto bb-auto Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto approved by bb-auto

@bb-auto bb-auto Bot added this to the v10.0.0 milestone Nov 14, 2026
@sourcery-ai

sourcery-ai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

API

Expose the --core-only CLI option and pass its value into documentation generation, while updating the output-path validation message.

  • tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs L22-28, L33-34, L48-51

Implementation

Implement core-only output placement, skip extension discovery and configuration, and fail when core components or services are absent.

  • tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs L15-18, L43-46, L55-60 (+1 small edits)

Configuration

Update the generator project version for this release.

  • tools/BootstrapBlazor.LLMsDocsGenerator/BootstrapBlazor.LLMsDocsGenerator.csproj L4

Documentation

Document core-only output behavior, requirements, usage, cleanup semantics, and the package-generation workflow in both languages.

  • tools/BootstrapBlazor.LLMsDocsGenerator/README.md L129-139, L178-187 (+5 small edits)
  • tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md L129-139, L178-187 (+5 small edits)

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@ArgoZhang
ArgoZhang merged commit aaf1123 into master Nov 14, 2026
3 checks passed
@ArgoZhang
ArgoZhang deleted the argozhang-llms-docs-pack-mode branch November 14, 2026 09:05
@sourcery-ai

sourcery-ai Bot commented Nov 14, 2026

Copy link
Copy Markdown

Linked issues

Checked at commit 1fcc4bd

#1298 feat(LLMsDocsGenerator): support core-only package generation · 3 of 3 met

# Requirement Status Notes
1 Add a core-only packaging mode that skips extension sources. ✅ Met The --core-only option disables extension discovery and parsing, and leaves extension documents and index sections out of the generated output.
2 Write directly to the configured output directory. ✅ Met Core-only mode uses outputFolder as the output path; generated index links remain relative to that directory.
3 Preserve existing unrelated contents. ✅ Met Generation does not clear the output directory; it writes the generated files and removes only stale marked documentation files.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 6 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="18" />
<code_context>
     {
         var _sourcePath = Path.Combine(rootFolder, "..", "BootstrapBlazor");
-        var _outputPath = Path.Combine(outputFolder, "wwwroot", "llms");
+        var _outputPath = coreOnly ? outputFolder : Path.Combine(outputFolder, "wwwroot", "llms");

         Logger($"Source path: {_sourcePath}");
</code_context>
<issue_to_address>
**Symlinked outputs overwrite targets**

When the output tree contains a symlink at a generated filename pointing to another writable file, a contributor who controls the core-only output tree can place a symlink at `llms.txt` or a generated component filename; the subsequent `File.WriteAllTextAsync` follows it and overwrites the symlink target, including files outside the output tree that the generator can write.

Reject symlinked generated destinations and symlinked output subdirectories before writing.
</issue_to_address>

### Comment 2
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="18" />
<code_context>
     {
         var _sourcePath = Path.Combine(rootFolder, "..", "BootstrapBlazor");
-        var _outputPath = Path.Combine(outputFolder, "wwwroot", "llms");
+        var _outputPath = coreOnly ? outputFolder : Path.Combine(outputFolder, "wwwroot", "llms");

         Logger($"Source path: {_sourcePath}");
</code_context>
<issue_to_address>
**Concurrent runs mix generated docs**

When two core-only invocations target the same output directory while analyzing different source snapshots, both generator processes write the same paths, and `RemoveStaleDocuments` removes files based on each run's snapshot. An older run can overwrite newer files or remove files referenced by the newer index, leaving inconsistent package output.

Coordinate generation for each output directory so concurrent runs cannot overwrite or clean up one another's files.
</issue_to_address>

### Comment 3
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="18" />
<code_context>
     {
         var _sourcePath = Path.Combine(rootFolder, "..", "BootstrapBlazor");
-        var _outputPath = Path.Combine(outputFolder, "wwwroot", "llms");
+        var _outputPath = coreOnly ? outputFolder : Path.Combine(outputFolder, "wwwroot", "llms");

         Logger($"Source path: {_sourcePath}");
</code_context>
<issue_to_address>
**Failed generation leaves mixed docs**

When a write fails or the process stops after the index is written but before all documents and cleanup complete, `File.WriteAllTextAsync` overwrites files in place, so the new `llms.txt` remains alongside missing, outdated, or mixed-generation documents when generation stops before completion. Consumers see broken links or inconsistent documentation.

Write the index and documents to a staging location and publish them only after generation completes successfully.
</issue_to_address>

### Comment 4
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="18" />
<code_context>
     {
         var _sourcePath = Path.Combine(rootFolder, "..", "BootstrapBlazor");
-        var _outputPath = Path.Combine(outputFolder, "wwwroot", "llms");
+        var _outputPath = coreOnly ? outputFolder : Path.Combine(outputFolder, "wwwroot", "llms");

         Logger($"Source path: {_sourcePath}");
</code_context>
<issue_to_address>
**User-authored files are overwritten**

When a pre-existing unmarked file occupies a generated path, `File.WriteAllTextAsync` replaces the file without checking its marker, so the user's contents are lost.

Check whether an existing file is marked as generated and preserve it when it is unmarked.
</issue_to_address>

### Comment 5
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="55-58" />
<code_context>
         Logger($"Found {categories.Count} categories");
         var services = await _analyzer.AnalyzeServicesAsync(provider.ParseServices());
         Logger($"Found {services.Count} services");
+        if (services.Count == 0)
+        {
+            throw new InvalidDataException("No core services found.");
+        }

-        var configuredPackages = provider.ParseExtensions();
</code_context>
<issue_to_address>
**Website generation rejects empty services**

When `docs.json` omits `services` or configures it as an empty array, the unconditional check throws `InvalidDataException` before writing documentation, so otherwise valid default website generation fails instead of producing an index without a services section.

Apply the nonempty-services validation only in core-only mode, or allow empty services in default mode.
</issue_to_address>

### Comment 6
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/README.md" line_range="148" />
<code_context>
 Generation errors and explicitly empty paths return a nonzero process exit code so MSBuild and CI can stop.

-Run the integration checks with PowerShell:
+Run the integration checks with PowerShell 7. They build the tool and invoke its actual CLI against isolated source fixtures for core-only packaging and full website generation:

 ```powershell
</code_context>
<issue_to_address>
**Documented verification script is missing**

When a reader tries to run the documented integration checks, readers following the stated integration-check instructions run `tools/BootstrapBlazor.LLMsDocsGenerator/tests/Verify-Generation.ps1`, but that script and the `tests` directory are absent, so the documented core-only and website verification cannot run.

Add the referenced verification script, or remove the claims and command from both READMEs until it exists.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md:148`.
</issue_to_address>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

{
var _sourcePath = Path.Combine(rootFolder, "..", "BootstrapBlazor");
var _outputPath = Path.Combine(outputFolder, "wwwroot", "llms");
var _outputPath = coreOnly ? outputFolder : Path.Combine(outputFolder, "wwwroot", "llms");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 High · Symlinked outputs overwrite targets

When the output tree contains a symlink at a generated filename pointing to another writable file, a contributor who controls the core-only output tree can place a symlink at llms.txt or a generated component filename; the subsequent File.WriteAllTextAsync follows it and overwrites the symlink target, including files outside the output tree that the generator can write.

Reject symlinked generated destinations and symlinked output subdirectories before writing.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 18:

**Symlinked outputs overwrite targets**

When the output tree contains a symlink at a generated filename pointing to another writable file, a contributor who controls the core-only output tree can place a symlink at `llms.txt` or a generated component filename; the subsequent `File.WriteAllTextAsync` follows it and overwrites the symlink target, including files outside the output tree that the generator can write.

Reject symlinked generated destinations and symlinked output subdirectories before writing.

{
var _sourcePath = Path.Combine(rootFolder, "..", "BootstrapBlazor");
var _outputPath = Path.Combine(outputFolder, "wwwroot", "llms");
var _outputPath = coreOnly ? outputFolder : Path.Combine(outputFolder, "wwwroot", "llms");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Concurrent runs mix generated docs

When two core-only invocations target the same output directory while analyzing different source snapshots, both generator processes write the same paths, and RemoveStaleDocuments removes files based on each run's snapshot. An older run can overwrite newer files or remove files referenced by the newer index, leaving inconsistent package output.

Coordinate generation for each output directory so concurrent runs cannot overwrite or clean up one another's files.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 18:

**Concurrent runs mix generated docs**

When two core-only invocations target the same output directory while analyzing different source snapshots, both generator processes write the same paths, and `RemoveStaleDocuments` removes files based on each run's snapshot. An older run can overwrite newer files or remove files referenced by the newer index, leaving inconsistent package output.

Coordinate generation for each output directory so concurrent runs cannot overwrite or clean up one another's files.

{
var _sourcePath = Path.Combine(rootFolder, "..", "BootstrapBlazor");
var _outputPath = Path.Combine(outputFolder, "wwwroot", "llms");
var _outputPath = coreOnly ? outputFolder : Path.Combine(outputFolder, "wwwroot", "llms");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Failed generation leaves mixed docs

When a write fails or the process stops after the index is written but before all documents and cleanup complete, File.WriteAllTextAsync overwrites files in place, so the new llms.txt remains alongside missing, outdated, or mixed-generation documents when generation stops before completion. Consumers see broken links or inconsistent documentation.

Write the index and documents to a staging location and publish them only after generation completes successfully.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 18:

**Failed generation leaves mixed docs**

When a write fails or the process stops after the index is written but before all documents and cleanup complete, `File.WriteAllTextAsync` overwrites files in place, so the new `llms.txt` remains alongside missing, outdated, or mixed-generation documents when generation stops before completion. Consumers see broken links or inconsistent documentation.

Write the index and documents to a staging location and publish them only after generation completes successfully.

{
var _sourcePath = Path.Combine(rootFolder, "..", "BootstrapBlazor");
var _outputPath = Path.Combine(outputFolder, "wwwroot", "llms");
var _outputPath = coreOnly ? outputFolder : Path.Combine(outputFolder, "wwwroot", "llms");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · User-authored files are overwritten

When a pre-existing unmarked file occupies a generated path, File.WriteAllTextAsync replaces the file without checking its marker, so the user's contents are lost.

Check whether an existing file is marked as generated and preserve it when it is unmarked.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 18:

**User-authored files are overwritten**

When a pre-existing unmarked file occupies a generated path, `File.WriteAllTextAsync` replaces the file without checking its marker, so the user's contents are lost.

Check whether an existing file is marked as generated and preserve it when it is unmarked.

Comment on lines +55 to +58
if (services.Count == 0)
{
throw new InvalidDataException("No core services found.");
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Website generation rejects empty services

When docs.json omits services or configures it as an empty array, the unconditional check throws InvalidDataException before writing documentation, so otherwise valid default website generation fails instead of producing an index without a services section.

Apply the nonempty-services validation only in core-only mode, or allow empty services in default mode.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at lines 55-58:

**Website generation rejects empty services**

When `docs.json` omits `services` or configures it as an empty array, the unconditional check throws `InvalidDataException` before writing documentation, so otherwise valid default website generation fails instead of producing an index without a services section.

Apply the nonempty-services validation only in core-only mode, or allow empty services in default mode.

Generation errors and explicitly empty paths return a nonzero process exit code so MSBuild and CI can stop.

Run the integration checks with PowerShell:
Run the integration checks with PowerShell 7. They build the tool and invoke its actual CLI against isolated source fixtures for core-only packaging and full website generation:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ Low · Documented verification script is missing

When a reader tries to run the documented integration checks, readers following the stated integration-check instructions run tools/BootstrapBlazor.LLMsDocsGenerator/tests/Verify-Generation.ps1, but that script and the tests directory are absent, so the documented core-only and website verification cannot run.

Add the referenced verification script, or remove the claims and command from both READMEs until it exists.

Also at tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md:148.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/README.md` at line 148:

**Documented verification script is missing**

When a reader tries to run the documented integration checks, readers following the stated integration-check instructions run `tools/BootstrapBlazor.LLMsDocsGenerator/tests/Verify-Generation.ps1`, but that script and the `tests` directory are absent, so the documented core-only and website verification cannot run.

Add the referenced verification script, or remove the claims and command from both READMEs until it exists.

Also at `tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md:148`.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(LLMsDocsGenerator): support core-only package generation

1 participant