Repository navigation
feat(LLMsDocsGenerator): support core-only package generation - #1299
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Reviewer's GuideAPIExpose the
ImplementationImplement core-only output placement, skip extension discovery and configuration, and fail when core components or services are absent.
ConfigurationUpdate the generator project version for this release.
DocumentationDocument core-only output behavior, requirements, usage, cleanup semantics, and the package-generation workflow in both languages.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Linked issuesChecked at commit 1fcc4bd #1298 feat(LLMsDocsGenerator): support core-only package generation · 3 of 3 met
|
There was a problem hiding this comment.
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>| { | ||
| var _sourcePath = Path.Combine(rootFolder, "..", "BootstrapBlazor"); | ||
| var _outputPath = Path.Combine(outputFolder, "wwwroot", "llms"); | ||
| var _outputPath = coreOnly ? outputFolder : Path.Combine(outputFolder, "wwwroot", "llms"); |
There was a problem hiding this comment.
🟠 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"); |
There was a problem hiding this comment.
🟡 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"); |
There was a problem hiding this comment.
🟡 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"); |
There was a problem hiding this comment.
🟡 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.| if (services.Count == 0) | ||
| { | ||
| throw new InvalidDataException("No core services found."); | ||
| } |
There was a problem hiding this comment.
🟡 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: |
There was a problem hiding this comment.
⚪ 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`.
Link issues
fixes #1298
Summary By Copilot
--core-onlygeneration for BootstrapBlazor package documentation.--outputwhile preserving unrelated existing files.Regression?
Risk
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-onlymode 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?
☑️ Self Check before Merge
Summary by Sourcery
Add opt-in core-only documentation generation for BootstrapBlazor packaging while preserving existing full-site generation behavior.
New Features:
--core-onlymode that generates BootstrapBlazor core component and service documentation without extension sources.Enhancements:
Build:
Documentation:
Tests: