Skip to content

feat(LLMsDocsCli): resolve API docs from package skills - #1325

Merged
ArgoZhang merged 2 commits into
masterfrom
dev-cli
Nov 17, 2026
Merged

ArgoZhang merged 2 commits into
masterfrom
dev-cli

Conversation

@ArgoZhang

@ArgoZhang ArgoZhang commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Link issues

fixes #1324

Summary By Copilot

Read API documentation from every BootstrapBlazor package restored by the selected project, using each package skill's references/llms.txt to resolve component names and document paths. Support multiple skills per package, retain legacy extension docs and online fallback, and update CLI guidance. Bump the CLI to 11.0.2.

Regression?

  • Yes
  • No

Existing source precedence and online fallback remain; package-local lookups now include skill-based docs.

Risk

  • High
  • Medium
  • Low

Automatic local lookup now covers all restored BootstrapBlazor packages. Legacy extension documentation remains supported, and unrelated packages in the global NuGet cache are not selected.

Verification

  • Manual (required)

  • Automated

  • dotnet pack .\tools\BootstrapBlazor.LLMsDocs.Cli\BootstrapBlazor.LLMsDocs.Cli.csproj -c Release --no-restore -v:q — passed.

  • dotnet new classlib --framework net11.0 --no-restore -o $temp --force — passed; temporary consumer project created.

  • dotnet add (Join-Path $temp 'bb-llms-pr-smoke.csproj') package BootstrapBlazor.DockView --version 11.0.1 — passed.

  • dotnet run --project .\tools\BootstrapBlazor.LLMsDocs.Cli\BootstrapBlazor.LLMsDocs.Cli.csproj -c Release --no-build -- get DockViewV2 --project (Join-Path $temp 'bb-llms-pr-smoke.csproj') --framework net11.0 — passed; resolved DockViewV2.txt from BootstrapBlazor.DockView 11.0.1.

  • git diff --check origin/master...HEAD — passed.

No dedicated automated test project was run.

Packaging changes reviewed?

  • Yes
  • No
  • N/A

Updated the CLI package version to 11.0.2 and verified dotnet pack.

☑️ 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

Resolve BootstrapBlazor API documentation from the skills shipped with packages restored by the current project while retaining legacy documentation and online fallbacks.

New Features:

  • Resolve API documentation from skills and references/llms.txt files in the BootstrapBlazor packages restored by the selected project, including extension packages and multiple skills per package.

Bug Fixes:

  • Prevent duplicate package and component entries while preserving package-local lookup precedence and online fallback.

Enhancements:

  • Retain compatibility with legacy core skill names and extension docs/llms documentation when skill indexes are unavailable.

Build:

  • Bump the CLI package version to 11.0.2.

Documentation:

  • Update CLI usage guidance to explain project package discovery, skill-based documentation resolution, package ownership, and fallback behavior.

Tests:

  • Verify CLI packaging and package-local documentation resolution with a restored BootstrapBlazor extension package.

@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Implementation

Resolve package-local component documentation from every restored package's skill indexes, support multiple skills and legacy extension docs, and avoid duplicate package entries.

  • tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs L102, L132, L137-138
  • tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs L102-117

Configuration

Bump the CLI package version to 11.0.2 alongside the feature release.

  • tools/BootstrapBlazor.LLMsDocs.Cli/BootstrapBlazor.LLMsDocs.Cli.csproj L4

Documentation

Document package-skill lookup behavior, source precedence and fallback, and update the agent guidance for querying component APIs.

  • tools/BootstrapBlazor.LLMsDocs.Cli/README.md L53, L109-111
  • tools/BootstrapBlazor.LLMsDocs.Cli/Templates/SKILL.md L3, L8-28, L33-35
  • tools/BootstrapBlazor.LLMsDocs.Cli/Templates/instructions.md L3-9

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 17, 2026
@bb-auto bb-auto Bot added this to the v11.0.0 milestone Nov 17, 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 64903da into master Nov 17, 2026
3 checks passed
@ArgoZhang
ArgoZhang deleted the dev-cli branch November 17, 2026 05:20
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026

Copy link
Copy Markdown

Linked issues

Checked at commit 0ee2c22

#1324 feat(LLMsDocsCli): resolve API docs from package skills · 5 of 5 met

# Requirement Status Notes
1 Discover BootstrapBlazor packages from the selected project's restored target, not from unrelated global-cache packages. ✅ Met The resolver selects the project's assets target and uses its package libraries and package folders to locate BootstrapBlazor packages.
2 Read valid skill indexes and use them to resolve component names to their package documentation. ✅ Met The resolver accepts skill directories containing both SKILL.md and references/llms.txt; local entries retain the package-specific document path parsed from the index.
3 Support multiple skills per package. ✅ Met All qualifying skill directories are read in sorted directory order, with same-name entries deduplicated within a package.
4 Retain legacy extension documentation and online fallback behavior. ✅ Met Extensions use docs/llms when no valid skill index is found, and missing local entries fall back to the online client.
5 Update CLI guidance to explain package-aware lookup. ✅ Met The README and skill/instructions templates describe project package discovery, package ownership via indexes, and fallback behavior.

@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 4 issues

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

## Individual Comments

### Comment 1
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs" line_range="138" />
<code_context>
             {
-                entries.AddRange(ReadPackageEntries(package));
+                entries.AddRange(ReadPackageEntries(package)
+                    .Where(entry => names.Add($"{package.Package}/{entry.Entry.Name}")));
             }
             catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
</code_context>
<issue_to_address>
**Package documentation is indistinguishable**

When two or more restored packages index an entry with the same name, `GetAsync` selects the first matching extension entry in assets order, and `SearchAsync` collapses entries that share a generated `DocumentPath`. Callers cannot identify or select the other package’s documentation and may receive the wrong package’s API docs.

Preserve package identity in lookups and generated document paths so callers can distinguish and select entries from different packages.

Also at `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs:104`, `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs:118`.
</issue_to_address>

### Comment 2
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs" line_range="104" />
<code_context>
-                if (docs is not null)
+                var skillsRoot = Path.Combine(packageRoot, "skills");
+                var docs = Directory.Exists(skillsRoot)
+                    ? Directory.GetDirectories(skillsRoot).Order(StringComparer.Ordinal)
+                        .Where(p => File.Exists(Path.Combine(p, "SKILL.md"))
+                            && File.Exists(Path.Combine(p, "references", "llms.txt")))
</code_context>
<issue_to_address>
**One package’s docs hide all local docs**

When enumerating a package’s skills directory fails, including after another package has already been resolved, `Directory.GetDirectories` throws, and `Resolve` catches the exception around the entire `ReadPackages` call and returns an empty package list. Lookups then use online docs instead of local docs.

Handle skills-directory enumeration errors per package so one failure does not discard packages already resolved or prevent resolving others.
</issue_to_address>

### Comment 3
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs" line_range="109-118" />
<code_context>
+                            && File.Exists(Path.Combine(p, "references", "llms.txt")))
+                        .Select(p => Path.Combine(p, "references")).ToArray()
+                    : [];
+                if (docs.Length == 0 && !core)
                 {
-                    packages.Add(new PackageDocs(name, item.Name[(separator + 1)..], docs, !core));
+                    var legacyDocs = Path.Combine(packageRoot, "docs", "llms");
+                    if (File.Exists(Path.Combine(legacyDocs, "llms.txt")))
+                    {
+                        docs = [legacyDocs];
+                    }
                 }
+                packages.AddRange(docs.Select(directory => new PackageDocs(name, item.Name[(separator + 1)..], directory, !core)));
                 break;
             }
         }
</code_context>
<issue_to_address>
**Later package docs are skipped**

When the same package path exists in multiple package folders and the first copy has no usable docs, the unconditional `break` stops the package-folder scan before later copies are checked, so local lookup falls back online instead of using the later copy’s docs.

Continue scanning when the current copy yields no usable docs, and break only after usable docs are found.
</issue_to_address>

### Comment 4
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs" line_range="118" />
<code_context>
+                    }
                 }
+                packages.AddRange(docs.Select(directory => new PackageDocs(name, item.Name[(separator + 1)..], directory, !core)));
                 break;
             }
         }
</code_context>
<issue_to_address>
**Package index links point nowhere**

When a caller runs `bb-llms index` with a project package that supplies skill-based docs and follows one of its links, `IndexAsync` emits each local entry’s `DocumentPath`, but `ReadPackageEntries` sets that path to `components/<name>.txt` or `extensions/<name>.txt` rather than the skill document’s path under `references`. Following links in the printed index therefore fails for entries newly discovered from package skills.

Preserve a usable relative document path for each local entry, or emit links that point to the actual package documentation files.
</issue_to_address>

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

{
entries.AddRange(ReadPackageEntries(package));
entries.AddRange(ReadPackageEntries(package)
.Where(entry => names.Add($"{package.Package}/{entry.Entry.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 · Package documentation is indistinguishable

When two or more restored packages index an entry with the same name, GetAsync selects the first matching extension entry in assets order, and SearchAsync collapses entries that share a generated DocumentPath. Callers cannot identify or select the other package’s documentation and may receive the wrong package’s API docs.

Preserve package identity in lookups and generated document paths so callers can distinguish and select entries from different packages.

Also at tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs:104, tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs:118.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs` at line 138:

**Package documentation is indistinguishable**

When two or more restored packages index an entry with the same name, `GetAsync` selects the first matching extension entry in assets order, and `SearchAsync` collapses entries that share a generated `DocumentPath`. Callers cannot identify or select the other package’s documentation and may receive the wrong package’s API docs.

Preserve package identity in lookups and generated document paths so callers can distinguish and select entries from different packages.

Also at `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs:104`, `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs:118`.

if (docs is not null)
var skillsRoot = Path.Combine(packageRoot, "skills");
var docs = Directory.Exists(skillsRoot)
? Directory.GetDirectories(skillsRoot).Order(StringComparer.Ordinal)

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 · One package’s docs hide all local docs

When enumerating a package’s skills directory fails, including after another package has already been resolved, Directory.GetDirectories throws, and Resolve catches the exception around the entire ReadPackages call and returns an empty package list. Lookups then use online docs instead of local docs.

Handle skills-directory enumeration errors per package so one failure does not discard packages already resolved or prevent resolving others.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs` at line 104:

**One package’s docs hide all local docs**

When enumerating a package’s skills directory fails, including after another package has already been resolved, `Directory.GetDirectories` throws, and `Resolve` catches the exception around the entire `ReadPackages` call and returns an empty package list. Lookups then use online docs instead of local docs.

Handle skills-directory enumeration errors per package so one failure does not discard packages already resolved or prevent resolving others.

Comment on lines +109 to 118
if (docs.Length == 0 && !core)
{
packages.Add(new PackageDocs(name, item.Name[(separator + 1)..], docs, !core));
var legacyDocs = Path.Combine(packageRoot, "docs", "llms");
if (File.Exists(Path.Combine(legacyDocs, "llms.txt")))
{
docs = [legacyDocs];
}
}
packages.AddRange(docs.Select(directory => new PackageDocs(name, item.Name[(separator + 1)..], directory, !core)));
break;

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 · Later package docs are skipped

When the same package path exists in multiple package folders and the first copy has no usable docs, the unconditional break stops the package-folder scan before later copies are checked, so local lookup falls back online instead of using the later copy’s docs.

Continue scanning when the current copy yields no usable docs, and break only after usable docs are found.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs` at lines 109-118:

**Later package docs are skipped**

When the same package path exists in multiple package folders and the first copy has no usable docs, the unconditional `break` stops the package-folder scan before later copies are checked, so local lookup falls back online instead of using the later copy’s docs.

Continue scanning when the current copy yields no usable docs, and break only after usable docs are found.

}
}
packages.AddRange(docs.Select(directory => new PackageDocs(name, item.Name[(separator + 1)..], directory, !core)));
break;

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 · Package index links point nowhere

When a caller runs bb-llms index with a project package that supplies skill-based docs and follows one of its links, IndexAsync emits each local entry’s DocumentPath, but ReadPackageEntries sets that path to components/<name>.txt or extensions/<name>.txt rather than the skill document’s path under references. Following links in the printed index therefore fails for entries newly discovered from package skills.

Preserve a usable relative document path for each local entry, or emit links that point to the actual package documentation files.

Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs` at line 118:

**Package index links point nowhere**

When a caller runs `bb-llms index` with a project package that supplies skill-based docs and follows one of its links, `IndexAsync` emits each local entry’s `DocumentPath`, but `ReadPackageEntries` sets that path to `components/<name>.txt` or `extensions/<name>.txt` rather than the skill document’s path under `references`. Following links in the printed index therefore fails for entries newly discovered from package skills.

Preserve a usable relative document path for each local entry, or emit links that point to the actual package documentation files.

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(LLMsDocsCli): resolve API docs from package skills

1 participant