Skip to content

feat(LLMsDocsGenerator): generate documentation based on components - #1303

Merged
ArgoZhang merged 1 commit into
masterfrom
dev-cli
Nov 15, 2026
Merged

ArgoZhang merged 1 commit into
masterfrom
dev-cli

Conversation

@ArgoZhang

@ArgoZhang ArgoZhang commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

Link issues

fixes #1302

Summary By Copilot

Regression?

  • Yes
  • No

Risk

  • High
  • Medium
  • Low

Verification

  • Manual (required)
  • Automated

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

Enable the LLM documentation generator to produce standalone core component and service documentation directly from the BootstrapBlazor source.

New Features:

  • Add core-only documentation generation that works directly from the core project or repository without Server metadata, samples, or extension sources.
  • Discover public core components and service-related APIs from source code and organize generated documentation into core component categories.

Bug Fixes:

  • Improve source path resolution and prevent documentation name collisions from silently overwriting generated files.
  • Handle optional root paths and core-only analysis without requiring extension or sample directories.

Enhancements:

  • Update the generator’s CLI behavior, index content, and output handling for core-only package documentation.

Documentation:

  • Update English and Chinese usage documentation for core-only generation, source discovery, and verification commands.

Tests:

  • Update the documented verification flow to build the generator and run the core-only integration checks.

@sourcery-ai

sourcery-ai Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

API

Extend the analyzer and generator interfaces to support core-only discovery, optional samples, and a core-only index document.

  • tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs L50-61
  • tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs L15
  • tools/BootstrapBlazor.LLMsDocsGenerator/MarkdownBuilder.cs L92

Uses of the API

Wire the new core-only mode into generation, including source discovery, service and category discovery, collision checks, and output generation.

  • tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs L50-61, L68-85, L165-199 (+4 small edits)
  • tools/BootstrapBlazor.LLMsDocsGenerator/MarkdownBuilder.cs L185-189

Discover plain-C# components and core service-related types, and adapt analyzer paths and sample lookup for core-only generation.

  • tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs L102-177, L229-300, L1059-1063 (+4 small edits)

Configuration

Make the root option optional so core-only mode can locate the core project from the current working directory while preserving validation of explicit empty values.

  • tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs L15-17, L39
  • tools/BootstrapBlazor.LLMsDocsGenerator/BootstrapBlazor.LLMsDocsGenerator.csproj L4, L26-29

Documentation

Update English and Chinese usage guidance to explain core-only discovery, invocation, and verification.

  • tools/BootstrapBlazor.LLMsDocsGenerator/README.md L148-152, L184-187 (+4 small edits)
  • tools/BootstrapBlazor.LLMsDocsGenerator/README.zh-CN.md L148-152, L184-187 (+4 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

@bb-auto bb-auto Bot added the enhancement New feature or request label Nov 15, 2026
@bb-auto bb-auto Bot added this to the v10.0.0 milestone Nov 15, 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

@ArgoZhang
ArgoZhang merged commit 2957b47 into master Nov 15, 2026
3 checks passed
@ArgoZhang
ArgoZhang deleted the dev-cli branch November 15, 2026 02:28
@sourcery-ai

sourcery-ai Bot commented Nov 15, 2026

Copy link
Copy Markdown

Linked issues

Checked at commit cbebff7

#1302 feat(LLMsDocsGenerator): generate documentation based on components · 1 of 1 met

# Requirement Status Notes
1 Generate documentation based on components. ✅ Met Core mode discovers components from source, creates a separate document for each, and derives index groups from their component directories.

@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 5 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="126" />
<code_context>
         Directory.CreateDirectory(_outputPath);
         var indexPath = Path.Combine(_outputPath, "llms.txt");
-        await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh"));
+        await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh", coreOnly));
         Logger($"Generated: {indexPath}");

</code_context>
<issue_to_address>
**Index and documents become inconsistent**

When generation fails or is interrupted after writing the index but before all document writes and stale-file cleanup finish, `GenerateAllAsync` writes the index before component and service files, so an I/O failure or interruption leaves the index paired with incomplete or stale documents, and consumers see missing or outdated documentation.

Write and clean up a complete staged output, then publish it only after all operations succeed.
</issue_to_address>

### Comment 2
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="126" />
<code_context>
         Directory.CreateDirectory(_outputPath);
         var indexPath = Path.Combine(_outputPath, "llms.txt");
-        await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh"));
+        await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh", coreOnly));
         Logger($"Generated: {indexPath}");

</code_context>
<issue_to_address>
**Concurrent runs leave broken links**

When two core-only invocations target the same output directory while analyzing different source snapshots, two generators targeting the same output can interleave writes and stale-file cleanup: one run can delete a component file the other run’s index references, leaving missing documentation in the final output. No per-output serialization or isolated publish step prevents this.

Serialize generation per output directory or publish each complete run from an isolated staging directory.
</issue_to_address>

### Comment 3
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="68-83" />
<code_context>
         }

-        var configuredPackages = coreOnly ? new List<ExtensionPackage>() : provider.ParseExtensions();
+        if (coreOnly)
+        {
+            var duplicateComponent = components.GroupBy(component => component.Name, StringComparer.OrdinalIgnoreCase)
+                .FirstOrDefault(group => group.Skip(1).Any());
+            if (duplicateComponent != null)
+            {
+                throw new InvalidDataException($"Core component names collide: {duplicateComponent.Key}");
+            }
+
+            var componentNames = components.Select(component => component.Name).ToHashSet(StringComparer.OrdinalIgnoreCase);
</code_context>
<issue_to_address>
**Default docs overwrite name collisions**

When default-mode analysis finds distinct component or service types with the same simple name, the duplicate-name checks run only in core-only mode, so default generation writes each component and service to `components/{Name}.txt` without checking collisions. Two different types with the same simple name overwrite one another, and index links resolve to the last-written file.

Validate duplicate output filenames in both modes before writing documentation.
</issue_to_address>

### Comment 4
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs" line_range="116" />
<code_context>
+            var model = _compilation.GetSemanticModel(declaration.SyntaxTree);
+            if (model.GetDeclaredSymbol(declaration) is not INamedTypeSymbol symbol ||
+                symbol.DeclaredAccessibility != Accessibility.Public || symbol.ContainingType != null ||
+                seenTypes.Contains(symbol.ToDisplayString(FullNameFormat)) || !IsComponentType(symbol))
+            {
+                continue;
</code_context>
<issue_to_address>
**Abstract bases appear as components**

When a public abstract class in a plain `.cs` file inherits `ComponentBase` or `IComponent` and has parameters, `AnalyzeAllComponentsAsync` accepts public abstract classes when `IsComponentType` succeeds; `BuildComponentInfo` collects their inherited parameters, so they are added to the component index and get documentation links even though they cannot be used as components.

Exclude abstract types from this component-discovery pass, unless abstract component bases are intentionally meant to appear as components.
</issue_to_address>

### Comment 5
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs" line_range="256" />
<code_context>
+                    symbol.DeclaringSyntaxReferences.Select(reference => reference.GetSyntax())
+                        .OfType<TypeDeclarationSyntax>().SelectMany(type => type.AttributeLists)
+                        .SelectMany(list => list.Attributes).Any(attribute =>
+                            attribute.Name.ToString().Split('.').Last() is "Obsolete" or "ObsoleteAttribute"))
+                {
+                    continue;
</code_context>
<issue_to_address>
**Obsolete services remain documented**

When a public service uses an alias for `System.ObsoleteAttribute`, `AnalyzeCoreServicesAsync` checks attribute-name text instead of the resolved attribute symbol, so it includes the obsolete service in the generated index and documentation.

Resolve each attribute and exclude services whose attribute symbol is `System.ObsoleteAttribute`.
</issue_to_address>

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

Directory.CreateDirectory(_outputPath);
var indexPath = Path.Combine(_outputPath, "llms.txt");
await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh"));
await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh", coreOnly));

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 · Index and documents become inconsistent

When generation fails or is interrupted after writing the index but before all document writes and stale-file cleanup finish, GenerateAllAsync writes the index before component and service files, so an I/O failure or interruption leaves the index paired with incomplete or stale documents, and consumers see missing or outdated documentation.

Write and clean up a complete staged output, then publish it only after all operations succeed.

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

**Index and documents become inconsistent**

When generation fails or is interrupted after writing the index but before all document writes and stale-file cleanup finish, `GenerateAllAsync` writes the index before component and service files, so an I/O failure or interruption leaves the index paired with incomplete or stale documents, and consumers see missing or outdated documentation.

Write and clean up a complete staged output, then publish it only after all operations succeed.

Directory.CreateDirectory(_outputPath);
var indexPath = Path.Combine(_outputPath, "llms.txt");
await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh"));
await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh", coreOnly));

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 leave broken links

When two core-only invocations target the same output directory while analyzing different source snapshots, two generators targeting the same output can interleave writes and stale-file cleanup: one run can delete a component file the other run’s index references, leaving missing documentation in the final output. No per-output serialization or isolated publish step prevents this.

Serialize generation per output directory or publish each complete run from an isolated staging directory.

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

**Concurrent runs leave broken links**

When two core-only invocations target the same output directory while analyzing different source snapshots, two generators targeting the same output can interleave writes and stale-file cleanup: one run can delete a component file the other run’s index references, leaving missing documentation in the final output. No per-output serialization or isolated publish step prevents this.

Serialize generation per output directory or publish each complete run from an isolated staging directory.

Comment on lines +68 to +83
if (coreOnly)
{
var duplicateComponent = components.GroupBy(component => component.Name, StringComparer.OrdinalIgnoreCase)
.FirstOrDefault(group => group.Skip(1).Any());
if (duplicateComponent != null)
{
throw new InvalidDataException($"Core component names collide: {duplicateComponent.Key}");
}

var componentNames = components.Select(component => component.Name).ToHashSet(StringComparer.OrdinalIgnoreCase);
var duplicate = services.FirstOrDefault(service => componentNames.Contains(service.Name));
if (duplicate != null)
{
throw new InvalidDataException($"Core component and service names collide: {duplicate.Name}");
}
}

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 · Default docs overwrite name collisions

When default-mode analysis finds distinct component or service types with the same simple name, the duplicate-name checks run only in core-only mode, so default generation writes each component and service to components/{Name}.txt without checking collisions. Two different types with the same simple name overwrite one another, and index links resolve to the last-written file.

Validate duplicate output filenames in both modes before writing documentation.

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

**Default docs overwrite name collisions**

When default-mode analysis finds distinct component or service types with the same simple name, the duplicate-name checks run only in core-only mode, so default generation writes each component and service to `components/{Name}.txt` without checking collisions. Two different types with the same simple name overwrite one another, and index links resolve to the last-written file.

Validate duplicate output filenames in both modes before writing documentation.

var model = _compilation.GetSemanticModel(declaration.SyntaxTree);
if (model.GetDeclaredSymbol(declaration) is not INamedTypeSymbol symbol ||
symbol.DeclaredAccessibility != Accessibility.Public || symbol.ContainingType != null ||
seenTypes.Contains(symbol.ToDisplayString(FullNameFormat)) || !IsComponentType(symbol))

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 · Abstract bases appear as components

When a public abstract class in a plain .cs file inherits ComponentBase or IComponent and has parameters, AnalyzeAllComponentsAsync accepts public abstract classes when IsComponentType succeeds; BuildComponentInfo collects their inherited parameters, so they are added to the component index and get documentation links even though they cannot be used as components.

Exclude abstract types from this component-discovery pass, unless abstract component bases are intentionally meant to appear as components.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs` at line 116:

**Abstract bases appear as components**

When a public abstract class in a plain `.cs` file inherits `ComponentBase` or `IComponent` and has parameters, `AnalyzeAllComponentsAsync` accepts public abstract classes when `IsComponentType` succeeds; `BuildComponentInfo` collects their inherited parameters, so they are added to the component index and get documentation links even though they cannot be used as components.

Exclude abstract types from this component-discovery pass, unless abstract component bases are intentionally meant to appear as components.

symbol.DeclaringSyntaxReferences.Select(reference => reference.GetSyntax())
.OfType<TypeDeclarationSyntax>().SelectMany(type => type.AttributeLists)
.SelectMany(list => list.Attributes).Any(attribute =>
attribute.Name.ToString().Split('.').Last() is "Obsolete" or "ObsoleteAttribute"))

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 · Obsolete services remain documented

When a public service uses an alias for System.ObsoleteAttribute, AnalyzeCoreServicesAsync checks attribute-name text instead of the resolved attribute symbol, so it includes the obsolete service in the generated index and documentation.

Resolve each attribute and exclude services whose attribute symbol is System.ObsoleteAttribute.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs` at line 256:

**Obsolete services remain documented**

When a public service uses an alias for `System.ObsoleteAttribute`, `AnalyzeCoreServicesAsync` checks attribute-name text instead of the resolved attribute symbol, so it includes the obsolete service in the generated index and documentation.

Resolve each attribute and exclude services whose attribute symbol is `System.ObsoleteAttribute`.

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): generate documentation based on components

1 participant