Enhance Ignite UI documentation tools - #1778
Open
dkalinovInfra wants to merge 2 commits into
Open
Conversation
- Updated the `list_components` constant to provide clearer descriptions and usage instructions. - Added a new `render-components.ts` file for improved component rendering functionality. - Created new test fixtures for filtering, flat listing, grouped indexing, single group retrieval, and handling unknown groups in the documentation. - Included expected output files for various scenarios to ensure accurate documentation generation.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Ignite UI documentation MCP tooling (and the docs-backend it can proxy to) so list_components is TOC-grouped by default, drastically reducing response size while adding targeted narrowing via group, filter, and detail: "docs" for the legacy flat output. It also introduces TOC sidecar ingestion + group summaries into the DB build pipeline, and adds shared fixtures to keep the TypeScript and C# renderers byte-identical.
Changes:
- Add TOC-driven grouping (new
doc_toc/doc_groups) and renderer modes forlist_components(grouped index, single-group, legacy flat). - Add exporter-side TOC walker + sidecar generation, plus cached group summary generation and release/validation gates.
- Add comprehensive cross-runtime tests (Vitest + .NET) pinned to shared fixtures, and CI wiring to ship sidecar/summaries.
Reviewed changes
Copilot reviewed 53 out of 56 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| packages/igniteui-mcp/shared-fixtures/list-components/unknown-group/input.json | Shared fixture input for unknown-group behavior. |
| packages/igniteui-mcp/shared-fixtures/list-components/unknown-group/expected.txt | Expected unknown-group rendering text. |
| packages/igniteui-mcp/shared-fixtures/list-components/single-group/input.json | Shared fixture input for single-group mode. |
| packages/igniteui-mcp/shared-fixtures/list-components/single-group/expected.txt | Expected single-group rendering text. |
| packages/igniteui-mcp/shared-fixtures/list-components/grouped-index/input.json | Shared fixture input for grouped index mode. |
| packages/igniteui-mcp/shared-fixtures/list-components/grouped-index/expected.txt | Expected grouped index rendering text. |
| packages/igniteui-mcp/shared-fixtures/list-components/flat/input.json | Shared fixture input for legacy flat mode (detail: "docs"). |
| packages/igniteui-mcp/shared-fixtures/list-components/flat/expected.txt | Expected legacy flat rendering text. |
| packages/igniteui-mcp/shared-fixtures/list-components/filtered/input.json | Shared fixture input for grouped filtering behavior. |
| packages/igniteui-mcp/shared-fixtures/list-components/filtered/expected.txt | Expected grouped filtering rendering text. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/tools/constants.ts | Update tool help text to describe new grouped behaviors/args. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/providers/RemoteDocsProvider.ts | Forward filter/group/detail to remote backend /api/docs. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/providers/LocalDocsProvider.ts | Implement grouped/flat modes locally with TOC-table presence guards. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/providers/DocsProvider.ts | Introduce ListComponentsOptions and update provider interface. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/index.ts | Expose new list_components arguments via MCP tool schema/handler. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/tests/tools/render-components.test.ts | Unit tests for grouped renderer behavior and thresholds. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/tests/shared/list-fixtures.ts | Helper to render shared fixtures through LocalDocsProvider. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/tests/shared/list-fixtures.test.ts | Shared fixture golden tests (ordinal compare). |
| packages/igniteui-mcp/igniteui-doc-mcp/src/tests/scripts/toc-sidecar.test.ts | Tests for sidecar writing and collision handling. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/tests/scripts/toc-index.test.ts | Tests for TOC walking/grouping rules (yaml/json, exclusions). |
| packages/igniteui-mcp/igniteui-doc-mcp/src/tests/scripts/build-db.test.ts | Destructive-path tests for build-db staging, rollback, gates. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/tests/providers/RemoteDocsProvider.test.ts | Tests for remote query param forwarding. |
| packages/igniteui-mcp/igniteui-doc-mcp/src/tests/providers/LocalDocsProvider.list.test.ts | Tests for local grouped modes + flat-mode byte fidelity. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/validate-package.ts | Add validation that shipped DB is fully grouped + summaries present. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/restore-docs-final.ts | Add --toc-stubs support to restore TOC sidecar from committed DB. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/report-toc-coverage.ts | Add reporting tool for per-framework TOC coverage and summary gaps. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/lib/toc-sidecar.ts | Add sidecar writer + safer filename collision resolution. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/lib/toc-index.ts | Add shared TOC walker implementing grouping derivation rules. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/lib/list-fixtures.ts | Loader utilities for shared list-components fixtures. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/lib/frontmatter.ts | Shared frontmatter parser used by build-group-summaries/build-db. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/export-wc-docs.ts | Export WC docs via TOC walker + write sidecar records. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/export-react-docs.ts | Export React docs via TOC walker + write sidecar records. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/export-blazor-docs.ts | Export Blazor docs via TOC walker + write sidecar records. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/export-angular-docs.ts | Export Angular docs via TOC walker + write sidecar records. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/build-group-summaries.ts | Generate/cached one-line summaries per TOC group. |
| packages/igniteui-mcp/igniteui-doc-mcp/scripts/build-db.ts | Ingest TOC sidecar + summaries; harden build with staging + gates. |
| packages/igniteui-mcp/igniteui-doc-mcp/package.json | Add scripts for release DB build, toc coverage, and summaries. |
| packages/igniteui-mcp/igniteui-doc-mcp/docs/knowledgebase.md | Document the TOC-grouping rules and build-db invariants. |
| packages/igniteui-mcp/igniteui-doc-mcp/data/group-summaries/webcomponents.json | Cached group summaries (WC). |
| packages/igniteui-mcp/igniteui-doc-mcp/data/group-summaries/react.json | Cached group summaries (React). |
| packages/igniteui-mcp/igniteui-doc-mcp/data/group-summaries/blazor.json | Cached group summaries (Blazor). |
| packages/igniteui-mcp/igniteui-doc-mcp/data/group-summaries/angular.json | Cached group summaries (Angular). |
| packages/igniteui-mcp/igniteui-doc-mcp/CLAUDE.md | Update internal repo guidance to include grouping + new scripts. |
| packages/igniteui-mcp/igniteui-doc-mcp/CHANGELOG.md | Document the breaking/default output change and new build gates. |
| packages/igniteui-mcp/docs-backend/tests-docs-backend/tests-docs-backend.csproj | Include shared fixtures in test output for backend comparisons. |
| packages/igniteui-mcp/docs-backend/tests-docs-backend/ListFixtureTests.cs | Add shared fixture golden tests for backend renderer. |
| packages/igniteui-mcp/docs-backend/tests-docs-backend/DocsControllerTests.cs | Update controller tests for new flat output strings/behavior. |
| packages/igniteui-mcp/docs-backend/docs-backend/Controllers/DocsController.cs | Implement grouped list endpoint (filter/group/detail) with fallback. |
| packages/igniteui-mcp/docs-backend/docs-backend/ComponentRenderer.cs | Add C# renderer port intended to match TS output exactly. |
| packages/igniteui-mcp/.gitattributes | Pin LF line endings for shared fixture files. |
| eslint.config.mjs | Exclude doc-mcp test tree from typed linting (no project). |
| .github/workflows/build-docs-db.yml | Download toc-index/summaries artifacts; build via release:db; publish summaries. |
| .github/actions/build-framework-docs/action.yml | Generate summaries and upload toc-index + summaries artifacts per framework. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
coverage: 87.816%. remained the same — dkalinov/list_components_optimization into master |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
list_componentsreturned every doc as a flat list with a full summary each — 17–24k tokens per unfiltered call, 77% of it thesummarycolumn, spent before any documentation is read.This groups docs by the published documentation TOC that Infragistics already maintains (
toc.ymlfor Angular,toc.jsonfor the xplat platforms) and pays for one group summary instead of hundreds of per-doc ones.Coverage is 100% — every doc is reachable from the TOC in all four frameworks, so there is no "Other" bucket and no hand-curated family map. 118 groups total.
New arguments:
groupreturns one group's docs with summaries in documentation order (an unknown value returns the valid headings, not an error);filteralso matches group names;detail: "docs"reproduces the old flat list byte-for-byte. Every heading the index prints is a legalgroupvalue.Data model: two additive tables,
doc_tocanddoc_groups, derived from a newdist/toc-index/<fw>.jsonsidecar written by the exporters.docsanddocs_ftsare unchanged — no reindex, no content churn.build-db.tsis also hardened: a full rebuild now preflights all four frameworks, one transaction spans the schema changes, deletes, inserts, FTS rebuild and gates, and it builds into a temp file and renamesdist/→ backend →db/last, so any failure leaves the committed DB byte-for-byte intact.npm run release:dbadds the whole-DB gates.Related Issue
Closes #
Type of Change
What breaks: the default
list_componentsshape (recoverable withdetail: "docs"), and the docs-backendGET /api/docsbody — the MCP renderer is now canonical and ported to C#, so local and remote return identical text. Not breaking: updating the server without the database. Verified against the published 15.5.1 DB — it renders flat everywhere,group/detailignored.Affected Packages
igniteui-cli(packages/cli)@igniteui/cli-core(packages/core)@igniteui/angular-templates(packages/igx-templates)@igniteui/angular-schematics(packages/ng-schematics)@igniteui/mcp-server(packages/igniteui-mcp)Includes
packages/igniteui-mcp/docs-backendand the shared fixtures between them.Checklist
npm run test)npm run build)npm run lint)vitest276 passed ·dotnet test26 passed ·npm run jasmine570 specs, 11 failed — all pre-existingig-migrateschematic failures ·release:db→build→validate:packageall green ·report:toc-coverage0 uncovered.Two caveats: a full
npm run lintreports 12,058 errors, all from checked-out doc submodules that are in no tsconfig project — 0 in repo-owned files, pre-existing. And two jasmine failures were introduced by the widerlistComponentssignature (spec/unit/mcp-runtime-spec.tscalled it positionally); both are fixed here.Tests added cover the walker (the six worked examples as exact tuples, including the
grid/grid.mdvsaccordion.mdpair any depth-based implementation fails), the sidecar and collision resolver, the renderer, per-framework fallback against legacy/migrated/mixed DBs, flat-mode byte-fidelity, andbuild-db's destructive path (preflight, rollback, staged-validation abort, artifact preservation). Five shared fixtures are rendered by both the vitest suite anddotnet testand compared to the sameexpected.txtwith ordinal equality — that is what stops the two renderers drifting.Additional Context
componentchangesRebuilding surfaced that the local
dist/docs_finaldisagrees with the shipped DB on thecomponentcolumn for 125 docs — e.g.excel-library-working-with-charts:WorksheetChart→IgxColumnComponent. Several look like regressions from an earlierderive-componentsrun. Unrelated to grouping, but it rides along in the committed DB. The delta is confined to that one column: row count unchanged at 1,232, no change tocontent,toc_name,summary,keywordsorpremium. Worth settling with a pipeline rerun before merge.Other notes
data/group-summaries/<fw>.json. The hash covers the member list, prompt version and model, so a prompt revision cannot silently pin old output. A second run regenerated 0. Tracked, so they are reviewable and hand-editable here.pipeline:*), the two new per-framework files uploaded/downloaded/flattened,assembleswitched torelease:db,data/group-summaries/carried into the PR, andrestore-docs-final.ts --toc-stubsround-trips a non-rebuilt framework's sidecar from the committed DB. The preflight, the release gate and the migrated DB must land together — preflight alone would break every subset rebuild.