Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions tools/BootstrapBlazor.LLMsDocsGenerator/ArgumentsHelper.cs
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,19 @@ public static ParseResult Parse(string[] args)
};
var outputFolderOption = new Option<string>("--output")
{
Description = "Set the publish folder of project",
Description = "Set the output folder (core-only writes directly; default writes to wwwroot/llms)",
DefaultValueFactory = _ => defaultFolder
};
var coreOnlyOption = new Option<bool>("--core-only")
{
Description = "Generate only core components and services for BootstrapBlazor packaging, without extension sources"
};

var rootCommand = new RootCommand("BootstrapBlazor LLMs Documentation Generator")
{
rootFolderOption,
outputFolderOption
outputFolderOption,
coreOnlyOption
};

rootCommand.SetAction(async result =>
Expand All @@ -40,10 +45,10 @@ public static ParseResult Parse(string[] args)
var outputFolder = result.GetValue(outputFolderOption);
if (string.IsNullOrEmpty(outputFolder))
{
throw new ArgumentException("Publish folder must not be empty.");
throw new ArgumentException("Output folder must not be empty.");
}

await DocsGenerator.GenerateAllAsync(rootFolder, outputFolder);
await DocsGenerator.GenerateAllAsync(rootFolder, outputFolder, result.GetValue(coreOnlyOption));
});

return rootCommand.Parse(args);
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<Version>11.0.0</Version>
<Version>11.0.1</Version>
<OutputType>Exe</OutputType>
<SatelliteResourceLanguages>false</SatelliteResourceLanguages>
</PropertyGroup>
Expand Down
16 changes: 12 additions & 4 deletions tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ internal static class DocsGenerator
/// <summary>
/// Generate all documentation files
/// </summary>
public static async Task GenerateAllAsync(string rootFolder, string outputFolder)
public static async Task GenerateAllAsync(string rootFolder, string outputFolder, bool coreOnly = false)
{
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.

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.

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.

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.


Logger($"Source path: {_sourcePath}");
Logger($"Output path: {_outputPath}");
Expand All @@ -31,7 +31,7 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder
// <core-repo>/.. / BootstrapBlazor.Extensions / src
var coreRepoRoot = Path.GetDirectoryName(Path.GetDirectoryName(Path.GetFullPath(_sourcePath)))!;
var extensionsSrc = Path.Combine(Path.GetDirectoryName(coreRepoRoot)!, "BootstrapBlazor.Extensions", "src");
var hasExtensions = Directory.Exists(extensionsSrc);
var hasExtensions = !coreOnly && Directory.Exists(extensionsSrc);

var extensionProjects = hasExtensions
? ReadExtensionProjects(Path.GetDirectoryName(extensionsSrc)!)
Expand All @@ -40,6 +40,10 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder
extensionProjects);
var components = await _analyzer.AnalyzeAllComponentsAsync();
Logger($"Found {components.Count} components");
if (components.Count == 0)
{
throw new InvalidDataException("No core components found.");
}

// Derive index categories, injected services and extension packages from docs.json.
var serverPath = Path.Combine(Path.GetDirectoryName(Path.GetFullPath(_sourcePath))!, "BootstrapBlazor.Server");
Expand All @@ -48,8 +52,12 @@ public static async Task GenerateAllAsync(string rootFolder, string outputFolder
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.");
}
Comment on lines +55 to +58

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.


var configuredPackages = provider.ParseExtensions();
var configuredPackages = coreOnly ? new List<ExtensionPackage>() : provider.ParseExtensions();
if (!hasExtensions && configuredPackages.Count > 0)
{
throw new DirectoryNotFoundException($"Extension sources required by docs.json were not found: {extensionsSrc}");
Expand Down
27 changes: 21 additions & 6 deletions tools/BootstrapBlazor.LLMsDocsGenerator/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ AI coding assistants (Claude Code, Cursor, GitHub Copilot) often generate incorr
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Output: <output>/wwwroot/llms/ │
│ Default output: <output>/wwwroot/llms/ │
├─────────────────────────────────────────────────────────────┤
│ llms.txt → Index with quick start guide │
│ components/ → Individual component documentation │
Expand All @@ -39,6 +39,8 @@ AI coding assistants (Claude Code, Cursor, GitHub Copilot) often generate incorr
└─────────────────────────────────────────────────────────────┘
```

With `--core-only`, the output directory is `<output>` itself.

### Why One File Per Component?

This design optimizes for LLM and Code Agent consumption:
Expand Down Expand Up @@ -85,7 +87,7 @@ Components are organized in the index by category for easy navigation, but each
## Requirements

- An SDK matching the project's `TargetFrameworks` (currently .NET 11 for source builds).
- A local `BootstrapBlazor` checkout; when `docs.json` configures extension packages, also check out `BootstrapBlazor.Extensions` beside it. The generator does not clone repositories.
- A local `BootstrapBlazor` checkout; unless using `--core-only`, when `docs.json` configures extension packages, also check out `BootstrapBlazor.Extensions` beside it. The generator does not clone repositories.

## Installation

Expand Down Expand Up @@ -117,21 +119,24 @@ Once installed, the tool is invoked with the command name `llms-docs`.

## Usage

Both options are optional and independently default to the current working directory (`.`). Run `llms-docs` without arguments from BB's `src/BootstrapBlazor.Server` directory to write documentation into that project. Overriding `--root` does not change the default `--output`; specify both when using another checkout or publish directory.
Both path options independently default to the current working directory (`.`). Run `llms-docs` without arguments from BB's `src/BootstrapBlazor.Server` directory to write documentation into that project. With `--core-only`, output is written directly to the `--output` directory without clearing existing contents. Overriding `--root` does not change the default `--output`; specify both when using another checkout or publish directory.

From the Server project directory, `dotnet llms-docs --output=bin\Release\publish\` also works: the omitted `--root` defaults to `.`, and relative output paths are resolved from that same directory. MSBuild can use `dotnet llms-docs --output=$(PublishDir)` when the path contains no spaces.

| Option | Required | Description |
|--------|----------|-------------|
| `--root` | No | Project root folder. Defaults to `.`. Component source is read from `<root>/../BootstrapBlazor`. |
| `--output` | No | Publish folder. Defaults to `.`. Documentation is written to `<output>/wwwroot/llms/`. |
| `--output` | No | Output folder. Defaults to `.`. Default mode writes to `<output>/wwwroot/llms/`; `--core-only` writes directly to `<output>/`. |
| `--core-only` | No | Generate only core components and built-in services for BootstrapBlazor packaging. Defaults to `false`; extension configuration and sources are not analyzed. |

When a `BootstrapBlazor.Extensions` checkout is available beside the core `BootstrapBlazor` checkout, the generator also analyzes the extension sources. The extension types to document are configured under `extensions` in `src/BootstrapBlazor.Server/docs.json`, the only configuration location. Generation fails if the file is missing. Extension docs are written to `extensions/`.

Only source projects listed in `BootstrapBlazor.Extensions.slnx` are scanned. Package names are matched against project filenames, not directory names. Configured packages outside the solution are skipped with a diagnostic; missing solution projects are reported as errors. Leftover directories do not participate in analysis. Core Razor-only components with an `@inherits` directive are also supported. Regeneration removes obsolete `.txt` files carrying the generator's `<!-- Generated: ... -->` marker, while preserving other files.
Only source projects listed in `BootstrapBlazor.Extensions.slnx` are scanned. Package names are matched against project filenames, not directory names. Configured packages outside the solution are skipped with a diagnostic; missing solution projects are reported as errors. Leftover directories do not participate in analysis. Core Razor-only components with an `@inherits` directive are also supported. In default mode, regeneration removes obsolete `.txt` files carrying the generator's `<!-- Generated: ... -->` marker, while preserving other files.

If extension packages are configured but the sibling extension source checkout is missing, generation fails before changing existing documentation. Unresolved configured component or service types also fail generation before writing files or removing stale documents. Services shared by multiple packages retain one document listing the registration method for each configured package; choose the registration matching the package in use.

With `--core-only`, the `extensions` section is ignored without editing `docs.json`, and no extension checkout or solution is required or read, even when present. Core categories and services still come from `docs.json`, which remains required. No extension documents or extension index sections/links are generated; services also provided by extensions remain in the core service documentation. The output is `<output>/llms.txt` and `<output>/components/*.txt`, with relative index links suitable for a package. The output directory is created if needed; existing contents are not cleared. Stale files carrying the generator marker are removed while unmarked files and subdirectories are preserved.

Explicit `<Using Include="..." />` items in each source project's `.csproj` (including aliases and static imports) are applied to that project's C# files, without leaking these imports into other projects in the combined analysis.

This is source analysis, not a full MSBuild evaluation: conditions, property expansion, imported `.props`/`.targets`, and `Using Remove` are not evaluated. Razor-only support synthesizes inheritance declarations; it does not compile Razor or extract members from `@code` blocks.
Expand All @@ -140,7 +145,7 @@ Declare extension services by the types actually registered for injection. For e

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`.


```powershell
.\tools\BootstrapBlazor.LLMsDocsGenerator\tests\Verify-Generation.ps1
Expand Down Expand Up @@ -170,6 +175,16 @@ From the same `BootstrapBlazor` repository root, run the sibling source project:
dotnet run --project "..\BootstrapBlazor.Extensions\tools\BootstrapBlazor.LLMsDocsGenerator" --root "src\BootstrapBlazor.Server" --output "src\BootstrapBlazor.Server"
```

### BootstrapBlazor NuGet packaging

From the `BootstrapBlazor` repository root, generate core-only documentation directly into the skill references directory:

```powershell
dotnet llms-docs --core-only --root "src\BootstrapBlazor.Server" --output "src\BootstrapBlazor\skills\bootstrapblazor\references"
```

No staging copy of `docs.json` with extensions removed is needed. BootstrapBlazor.Server publishing must omit `--core-only` to keep the full website index, core documentation and extension documentation; its existing command and output paths are unchanged.

## CI/CD Integration

Check out both repositories as siblings and use an SDK matching the checked-out generator project. The following steps assume the workflow belongs to `dotnetcore/BootstrapBlazor`; pin compatible refs when building a release:
Expand Down
Loading
Loading