feat: add report-audit-token-usage MCP tool

[poltorak]

New tool for auditing design token health in consumer style files. Two modes — validate (typo detection with suggestions) and overrides (token re-declaration detection).

Validate mode

• Checks var() references against the loaded token dataset
• Suggests corrections for invalid tokens using Levenshtein distance (threshold ≤ 3)
• Supports multiple token prefixes — derives all distinct prefixes (--semantic-, --ds-, etc.) from the dataset automatically when propertyPrefix is null
• Optional brand-specific warnings for tokens not available in all brands

Overrides mode

• Detects token re-declarations via :host, ::ng-deep, class selectors, :root[data-theme]
• Detects !important on token-consuming declarations
• Works without token data (detection-only / zero-config mode)
• Optional classification when token dataset is available: legitimate, component-override, deep-override, important-override, inline-override, scope-violation

Supporting changes

• styles-ast-utils: ScssPropertyEntry now exposes important: boolean from PostCSS (PostCSS strips !important from decl.value into decl.important)
• glob-utils: new tests for glob-to-regex conversion
• token-dataset-loader: minor adjustments for token loading
• docs: added tool entry in tools.md, clarified propertyPrefix behaviour in architecture-internal-design.md

Files added

Path	Purpose
audit-token-usage.tool.ts	Main handler, formatter, prefix derivation, persistence
models/schema.ts	MCP tool schema definition
models/types.ts	Input/output type definitions
utils/validate-mode.ts	Validate pipeline — var() extraction, prefix matching, typo suggestions
utils/overrides-mode.ts	Overrides pipeline — declaration/consumption scanning
utils/override-classifier.ts	Mechanism detection and override classification
utils/edit-distance.ts	Levenshtein distance (Wagner-Fischer, O(min(m,n)) space)
index.ts	Public API exports

Test coverage

• audit-token-usage.tool.spec.ts — output structure, summary counts, formatter
• graceful-degradation.spec.ts — missing config, empty dataset, detection-only mode
• edit-distance.spec.ts — identity, symmetry, empty string, known distances
• overrides-mode.spec.ts — mechanism detection, classification, runOverridesMode pipeline
• validate-mode.spec.ts — prefix filtering, suggestion threshold, invalid token report fields

[Copilot]

Pull request overview

Adds a new MCP tool (report-audit-token-usage) to audit design token health in consumer style files, supporting both token reference validation (typo detection + suggestions) and token override detection (including mechanism/classification reporting).

Changes:

• Introduces report-audit-token-usage tool (schema, handler, validate/overrides pipelines, formatter, persistence) plus comprehensive Vitest coverage.
• Extends token infrastructure to support multiple ds.tokens.filePattern glob patterns and improves glob-to-regex conversion (brace expansion + tests).
• Updates styles AST parsing to expose decl.important as ScssPropertyEntry.important, and updates docs/config wiring accordingly.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/shared/utils/src/lib/file/glob-utils.ts	Adds brace-expansion support to globToRegex via sentinel extraction/restoration.
packages/shared/utils/src/lib/file/glob-utils.spec.ts	Adds unit tests for glob-to-regex behavior including brace expansion and escaping regressions.
packages/shared/styles-ast-utils/src/lib/scss-value-parser.ts	Extends ScssPropertyEntry with important: boolean sourced from PostCSS decl.important.
packages/angular-mcp/src/main.ts	Updates CLI option parsing to allow ds.tokens.filePattern to be provided multiple times (array).
packages/angular-mcp-server/tsconfig.lib.json	Adjusts project references (ordering + adds typescript-ast-utils reference).
packages/angular-mcp-server/tsconfig.json	Adjusts project references (ordering + adds typescript-ast-utils reference).
packages/angular-mcp-server/src/lib/validation/angular-mcp-server-options.schema.ts	Updates TokensConfigSchema.filePattern to accept `string
packages/angular-mcp-server/src/lib/tools/ds/tools.ts	Registers the new audit-token-usage tool in DS tool list.
packages/angular-mcp-server/src/lib/tools/ds/shared/utils/token-dataset-loader.ts	Updates token file discovery to accept multiple file patterns and improves “no files matched” messaging.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/utils/validate-mode.ts	Implements validate pipeline: var() extraction, prefix matching, dataset lookup, Levenshtein suggestions, optional brand warnings.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/utils/spec/validate-mode.spec.ts	Adds unit tests for validate-mode helpers/behavior.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/utils/spec/overrides-mode.spec.ts	Adds tests for override mechanism detection/classification + pipeline behavior including !important.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/utils/spec/edit-distance.spec.ts	Adds correctness tests for Levenshtein implementation.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/utils/overrides-mode.ts	Implements overrides pipeline: declaration overrides + !important consumption detection, plus counts.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/utils/override-classifier.ts	Adds mechanism detection + intent classification logic.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/utils/edit-distance.ts	Adds Levenshtein distance implementation (Wagner–Fischer).
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/spec/graceful-degradation.spec.ts	Adds tests for degraded operation when config/dataset is missing or empty.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/spec/audit-token-usage.tool.spec.ts	Adds tool-level tests for active mode resolution, summary correctness, formatting/output structure.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/models/types.ts	Defines input/options and output result types for the tool.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/models/schema.ts	Defines the MCP tool schema for report-audit-token-usage.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/index.ts	Public exports for the new tool module.
packages/angular-mcp-server/src/lib/tools/ds/audit-token-usage/audit-token-usage.tool.ts	Main handler, summary builder, prefix derivation, exclude filtering, persistence, and pretty formatting.
docs/tools.md	Documents the new MCP tool usage and parameters.
docs/architecture-internal-design.md	Clarifies propertyPrefix behavior in relation to the new tool.
.nvmrc	Updates the pinned Node version.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.