docs(config-audit): straggler sweep for v5.0.0 — sync all badge counts
Reconcile README/CLAUDE.md/commands/agents to filesystem truth ahead of v5.0.0 release. Self-audit --check-readme now passes (counts: scanners 12, commands 18, tests 635, knowledge 8, agents 6, hooks 4). Self-audit (scanners/self-audit.mjs): - Exclude plugin-health-scanner.mjs from countScannerShape (it is a "standalone" scanner per README/CLAUDE.md taxonomy; orchestrated scanners stay at 12) - countTestCases: spawn `node --test` and parse the `tests N` line so the badge reflects test cases (635), not test files (36). countTestFiles kept as fallback when subprocess fails. README.md: - Badges: scanners 9→12, commands 17→18, tests 543→635 - Body counts updated: 8 quality scanners → 12 deterministic scanners; 8 quality areas → 10 (incl. Plugin Hygiene from N6); 9 Node.js scanners → 12 - Scanner table extended with CPS / DIS / COL rows; TOK row reflects the v5 Pattern E/F/N1 expansion (sonnet-era removed) - CLI table adds manifest, whats-active, --accurate-tokens, --with-telemetry-recipe - Knowledge table adds opus-4.7-patterns.md and cache-telemetry-recipe.md - Scanner Lib table notes WEIGHTS export, severity-weighted scoring, tokenizer-api - Action Engines table adds manifest.mjs, whats-active.mjs, token-hotspots-cli.mjs - Test count text 486→635, file count 27→36 (12 lib + 23 scanner + 1 hook) - Tokens command: 4-pattern phrasing → 6 patterns + --accurate-tokens - Adds /config-audit manifest and /config-audit whats-active to command tables CLAUDE.md: - Posture row: 8 → 10 quality areas - Tokens row: 4 patterns (incl. sonnet-era) → 6 patterns + --accurate-tokens - Adds /config-audit manifest entry - Scanner table: TOK description rewritten; CPS, DIS, COL rows added - Scanner Lib table: tokenizer-api.mjs added; v5 annotations on severity, output, scoring, active-config-reader - Action Engines table: manifest.mjs added; token-hotspots-cli.mjs flags expanded - Knowledge table: cache-telemetry-recipe.md added; configuration-best-practices notes Opus-4.7 cache-stability rewrite - Finding ID examples extended with CA-TOK-005, CA-CPS-001, CA-DIS-001, CA-COL-001 - Test count text 543→635, file count 31→36 commands/help.md: tokens/manifest added to Core commands/posture.md: 8 → 10 quality areas commands/config-audit.md: argument-hint adds tokens/manifest; router adds tokens and manifest; "Running 8 configuration scanners" → 12 agents/feature-gap-agent.md: 8 → 10 quality areas No production code paths changed beyond self-audit's badge-counting heuristic. All 635 tests still green. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
parent
17af3d55f6
commit
5bf500e1a8
7 changed files with 95 additions and 35 deletions
|
|
@ -16,8 +16,9 @@ Analyzes and optimizes Claude Code configuration across three pillars:
|
|||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/config-audit` | Full audit with auto-scope detection (no setup needed) |
|
||||
| `/config-audit posture` | Quick health scorecard (A-F grades, 8 quality areas incl. Token Efficiency) |
|
||||
| `/config-audit tokens` | Opus-4.7-aware token hotspots (4 patterns: cache-breaking, redundant perms, deep imports, sonnet-era) |
|
||||
| `/config-audit posture` | Quick health scorecard (A-F grades, 10 quality areas incl. Token Efficiency, Plugin Hygiene) |
|
||||
| `/config-audit tokens` | Opus-4.7-aware token hotspots (6 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget) — optional `--accurate-tokens` API calibration, `--with-telemetry-recipe` cache-hit recipe pointer |
|
||||
| `/config-audit manifest` | Ranked table of every system-prompt token source (CLAUDE.md, plugins, skills, MCP, hooks) sorted by estimated tokens |
|
||||
| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact |
|
||||
| `/config-audit fix` | Auto-fix deterministic issues with backup + verification |
|
||||
| `/config-audit rollback` | Restore configuration from backup |
|
||||
|
|
@ -65,24 +66,28 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs <path> [--global] [--full-mach
|
|||
| `import-resolver.mjs` | IMP | Broken @imports, circular refs, deep chains, tilde paths |
|
||||
| `conflict-detector.mjs` | CNF | Settings conflicts, permission contradictions, hook duplicates |
|
||||
| `feature-gap-scanner.mjs` | GAP | 25 feature checks across 4 tiers — shown as opportunities, not grades |
|
||||
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, sonnet-era setups (Opus 4.7 patterns) |
|
||||
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascade, bloated SKILL.md descriptions, MCP tool-schema budget (Opus 4.7 patterns) |
|
||||
| `cache-prefix-scanner.mjs` | CPS | Volatile content in lines 31–150 of CLAUDE.md cascade (beyond Pattern A's top-30 window) |
|
||||
| `disabled-in-schema-scanner.mjs` | DIS | Tools listed in BOTH `permissions.deny` AND `permissions.allow` — deny wins, allow entries are dead config |
|
||||
| `collision-scanner.mjs` | COL | Cross-plugin skill name collisions (low); user-vs-plugin overlaps (medium); `details.namespaces` payload |
|
||||
|
||||
### Scanner Lib (`scanners/lib/`)
|
||||
|
||||
| Module | Purpose |
|
||||
|--------|---------|
|
||||
| `severity.mjs` | Severity constants, risk scoring, verdict logic |
|
||||
| `output.mjs` | Finding objects (CA-XXX-NNN format), scanner results, envelope |
|
||||
| `severity.mjs` | Severity constants, risk scoring, verdict logic, `WEIGHTS` named export (v5 F3) |
|
||||
| `output.mjs` | Finding objects (CA-XXX-NNN format), scanner results, envelope, optional `details` payload (v5 N6) |
|
||||
| `file-discovery.mjs` | Config file discovery: single-path, multi-path (`discoverConfigFilesMulti`), full-machine (`discoverFullMachinePaths`) |
|
||||
| `yaml-parser.mjs` | Frontmatter parsing, JSON parsing, @import/section extraction |
|
||||
| `string-utils.mjs` | Line counting, truncation, similarity, key extraction |
|
||||
| `scoring.mjs` | Area scoring, health scorecard, legacy utilization/maturity |
|
||||
| `scoring.mjs` | Severity-weighted `scoreByArea` (v5 F3), health scorecard, dedup-by-area (v5 N3), `scoringVersion: 'v5'` |
|
||||
| `backup.mjs` | Backup creation, manifest parsing, checksum verification |
|
||||
| `diff-engine.mjs` | Drift diffing: diffEnvelopes(), formatDiffReport() |
|
||||
| `baseline.mjs` | Baseline save/load/list/delete for drift detection |
|
||||
| `report-generator.mjs` | Unified markdown reports: posture, drift, plugin health |
|
||||
| `suppression.mjs` | .config-audit-ignore parsing, finding suppression, audit trail |
|
||||
| `active-config-reader.mjs` | Read-only inventory: readActiveConfig(), detectGitRoot(), walkClaudeMdCascade(), readClaudeJsonProjectSlice() (longest-prefix match), enumeratePlugins(), enumerateSkills(), readActiveHooks(), readActiveMcpServers(), estimateTokens() |
|
||||
| `active-config-reader.mjs` | Read-only inventory: readActiveConfig(), detectGitRoot(), walkClaudeMdCascade(), readClaudeJsonProjectSlice() (longest-prefix match), enumeratePlugins(), enumerateSkills(), readActiveHooks(), readActiveMcpServers() (with cache → package.json tool-count fallback), estimateTokens() (v5: `'mcp'` kind = 500 + toolCount × 200) |
|
||||
| `tokenizer-api.mjs` | Anthropic `count_tokens` wrapper for `--accurate-tokens` (v5 N5); 5s AbortController timeout, exponential 429 backoff, key masking |
|
||||
|
||||
### Action Engines (`scanners/`)
|
||||
|
||||
|
|
@ -93,7 +98,8 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs <path> [--global] [--full-mach
|
|||
| `fix-cli.mjs` | CLI: `node fix-cli.mjs <path> [--apply] [--json] [--global]` |
|
||||
| `drift-cli.mjs` | CLI: `node drift-cli.mjs <path> [--save] [--baseline name] [--json]` |
|
||||
| `whats-active.mjs` | CLI: `node whats-active.mjs <path> [--json] [--verbose] [--suggest-disables]` — read-only active-config inventory |
|
||||
| `token-hotspots-cli.mjs` | CLI: `node token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path]` — Opus-4.7 token hotspots ranking |
|
||||
| `token-hotspots-cli.mjs` | CLI: `node token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` — Opus-4.7 token hotspots ranking with optional API calibration |
|
||||
| `manifest.mjs` | CLI: `node manifest.mjs <path> [--json]` — ranked system-prompt token-source table (v5 N2) |
|
||||
|
||||
### Standalone Scanner
|
||||
|
||||
|
|
@ -107,12 +113,13 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs <path> [--global] [--full-mach
|
|||
| File | Content |
|
||||
|------|---------|
|
||||
| `claude-code-capabilities.md` | Feature register: 18 config surfaces, Anthropic guidance, relevance table |
|
||||
| `configuration-best-practices.md` | Per-layer best practices |
|
||||
| `configuration-best-practices.md` | Per-layer best practices (v5: Opus 4.7 cache-stability guidance replaces Sonnet-era 200-line rule) |
|
||||
| `anti-patterns.md` | Common mistakes mapped to scanner IDs |
|
||||
| `hook-events-reference.md` | All 26 hook events with details |
|
||||
| `feature-evolution.md` | Feature timeline for staleness detection |
|
||||
| `gap-closure-templates.md` | Config-specific templates for closing gaps |
|
||||
| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — 4 patterns powering the TOK scanner |
|
||||
| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner |
|
||||
| `cache-telemetry-recipe.md` | Manual `jq` recipe for verifying prompt-cache hit rate from session transcripts (v5 M7) |
|
||||
|
||||
## Hooks
|
||||
|
||||
|
|
@ -150,7 +157,7 @@ Default: auto-detects scope from git context. Override with `/config-audit full|
|
|||
```
|
||||
|
||||
### Finding ID Format
|
||||
`CA-{SCANNER}-{NNN}` — e.g. `CA-CML-001`, `CA-SET-003`, `CA-HKV-002`, `CA-RUL-005`
|
||||
`CA-{SCANNER}-{NNN}` — e.g. `CA-CML-001`, `CA-SET-003`, `CA-HKV-002`, `CA-RUL-005`, `CA-TOK-005`, `CA-CPS-001`, `CA-DIS-001`, `CA-COL-001`
|
||||
|
||||
## Testing
|
||||
|
||||
|
|
@ -158,7 +165,7 @@ Default: auto-detects scope from git context. Override with `/config-audit full|
|
|||
node --test 'tests/**/*.test.mjs'
|
||||
```
|
||||
|
||||
543 tests across 31 test files (11 lib + 19 scanner + 1 hook). Test fixtures in `tests/fixtures/`.
|
||||
635 tests across 36 test files (12 lib + 23 scanner + 1 hook). Test fixtures in `tests/fixtures/`.
|
||||
|
||||
## Gotchas
|
||||
|
||||
|
|
|
|||
|
|
@ -8,14 +8,14 @@
|
|||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 8 quality scanners for correctness, context-aware feature recommendations, auto-fix with backup/rollback, plus an Opus-4.7-aware Token Hotspots scanner. Zero external dependencies.
|
||||
A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 12 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, an Opus-4.7-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, and cross-plugin collision detection. Zero external dependencies.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -50,7 +50,7 @@ Claude Code reads instructions from at least 7 different file types across multi
|
|||
|
||||
This plugin provides three layers of configuration intelligence:
|
||||
|
||||
- **Health** — 8 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, and Opus-4.7-era token waste
|
||||
- **Health** — 12 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, Opus-4.7-era token waste, cache-prefix instability, dead tool grants, and cross-plugin skill collisions
|
||||
- **Opportunities** — context-aware recommendations for Claude Code features that could benefit your specific project, backed by Anthropic's official guidance
|
||||
- **Action** — auto-fix with mandatory backups, syntax validation, rollback support, and a human-in-the-loop workflow for anything non-trivial
|
||||
|
||||
|
|
@ -248,8 +248,9 @@ Your team configuration changes over time. Track it:
|
|||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/config-audit` | Full audit with auto-scope detection (no setup needed) |
|
||||
| `/config-audit posture` | Quick health scorecard: A-F grades across 8 quality areas (incl. Token Efficiency) |
|
||||
| `/config-audit tokens` | Opus-4.7-aware token hotspots — ranked by estimated waste, with 4-pattern findings |
|
||||
| `/config-audit posture` | Quick health scorecard: A-F grades across 10 quality areas (incl. Token Efficiency, Plugin Hygiene) |
|
||||
| `/config-audit tokens` | Opus-4.7-aware token hotspots — ranked by estimated waste; 6 patterns + optional `--accurate-tokens` API calibration |
|
||||
| `/config-audit manifest` | Ranked table of every system-prompt token source (CLAUDE.md, plugins, skills, MCP, hooks) sorted by estimated tokens |
|
||||
| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact |
|
||||
| `/config-audit fix` | Auto-fix deterministic issues with backup + verification |
|
||||
| `/config-audit rollback` | Restore configuration from a previous backup |
|
||||
|
|
@ -263,6 +264,7 @@ Your team configuration changes over time. Track it:
|
|||
|---------|-------------|
|
||||
| `/config-audit drift` | Compare current config against a saved baseline |
|
||||
| `/config-audit plugin-health` | Audit plugin structure, frontmatter, cross-plugin coherence |
|
||||
| `/config-audit whats-active` | Read-only inventory of plugins, skills, MCP, hooks, CLAUDE.md active for a repo (with token estimates) |
|
||||
| `/config-audit discover` | Run discovery phase only |
|
||||
| `/config-audit analyze` | Run analysis phase only |
|
||||
| `/config-audit interview` | Set preferences for action plan _(optional)_ |
|
||||
|
|
@ -277,7 +279,7 @@ By default, `/config-audit` auto-detects scope from your git context. Override w
|
|||
|
||||
## Deterministic Scanners
|
||||
|
||||
9 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, and Opus-4.7-aware token-cost analysis. Zero external dependencies.
|
||||
12 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, Opus-4.7-aware token-cost analysis, cache-prefix stability, dead-tool detection, and cross-plugin skill collisions. Plus a standalone plugin-health scanner. Zero external dependencies.
|
||||
|
||||
**Why deterministic?** LLMs are powerful at understanding intent and context. But they cannot reliably validate JSON schemas, detect circular `@import` chains, or catch that your global `settings.json` contradicts your project-level one. These scanners fill that gap — fast, repeatable, and zero false positives on structural issues.
|
||||
|
||||
|
|
@ -291,7 +293,10 @@ By default, `/config-audit` auto-detects scope from your git context. Override w
|
|||
| `import-resolver.mjs` | IMP | Broken @imports, circular references, deep chains, tilde path issues |
|
||||
| `conflict-detector.mjs` | CNF | Settings contradictions across scopes, permission conflicts, hook duplicates |
|
||||
| `feature-gap-scanner.mjs` | GAP | 25 feature checks — shown as opportunities, not grades |
|
||||
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, sonnet-era setups |
|
||||
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascades, bloated skill descriptions, MCP tool-schema budget |
|
||||
| `cache-prefix-scanner.mjs` | CPS | Volatile content in lines 31–150 of the CLAUDE.md cascade — beyond the cache-prefix window but still re-loaded every turn |
|
||||
| `disabled-in-schema-scanner.mjs` | DIS | Tools listed in BOTH `permissions.deny` and `permissions.allow` — deny wins, allow entries are dead config |
|
||||
| `collision-scanner.mjs` | COL | Cross-plugin skill name collisions; user-vs-plugin overlaps |
|
||||
|
||||
### CLI Tools
|
||||
|
||||
|
|
@ -302,8 +307,10 @@ All tools work standalone — no Claude Code session needed:
|
|||
| **Posture** | `node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path]` |
|
||||
| **Fix** | `node scanners/fix-cli.mjs <path> [--apply] [--json] [--global]` |
|
||||
| **Drift** | `node scanners/drift-cli.mjs <path> [--save] [--baseline name] [--json]` |
|
||||
| **Tokens** | `node scanners/token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path]` |
|
||||
| **Self-audit** | `node scanners/self-audit.mjs [--json] [--fix]` |
|
||||
| **Tokens** | `node scanners/token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` |
|
||||
| **Manifest** | `node scanners/manifest.mjs <path> [--json]` — ranked system-prompt source table |
|
||||
| **What's active** | `node scanners/whats-active.mjs <path> [--json] [--verbose] [--suggest-disables]` |
|
||||
| **Self-audit** | `node scanners/self-audit.mjs [--json] [--fix] [--check-readme]` |
|
||||
| **Full scan** | `node scanners/scan-orchestrator.mjs <path> [--global] [--full-machine] [--no-suppress]` |
|
||||
|
||||
---
|
||||
|
|
@ -413,7 +420,7 @@ node scanners/posture.mjs examples/optimal-setup/
|
|||
|
||||
### Self-Audit: Scanning the Scanner
|
||||
|
||||
The plugin runs all 9 scanners on itself via `self-audit.mjs`. Current result: **Grade A, score 98, 0 real findings.** Test fixtures and example files are automatically excluded from scoring — a security plugin that ships deliberately broken examples shouldn't fail its own audit.
|
||||
The plugin runs all 12 scanners + the standalone plugin-health scanner on itself via `self-audit.mjs`. Test fixtures and example files are automatically excluded from scoring — a configuration plugin that ships deliberately broken examples shouldn't fail its own audit. Use `--check-readme` to verify badge counts are in sync with the filesystem.
|
||||
|
||||
```bash
|
||||
node scanners/self-audit.mjs
|
||||
|
|
@ -427,17 +434,19 @@ Shared modules used by all scanners — useful if you're reading the source or e
|
|||
|
||||
| Module | Purpose |
|
||||
|--------|---------|
|
||||
| `severity.mjs` | Severity constants, risk scoring, verdict logic |
|
||||
| `output.mjs` | Finding objects (`CA-XXX-NNN` format), scanner results, envelope |
|
||||
| `severity.mjs` | Severity constants, risk scoring, verdict logic, `WEIGHTS` export (v5 F3) |
|
||||
| `output.mjs` | Finding objects (`CA-XXX-NNN` format), scanner results, envelope, `details` field |
|
||||
| `file-discovery.mjs` | Config file discovery: single-path, multi-path, full-machine |
|
||||
| `yaml-parser.mjs` | Frontmatter parsing, JSON parsing, @import/section extraction |
|
||||
| `string-utils.mjs` | Line counting, truncation, similarity, key extraction |
|
||||
| `scoring.mjs` | Area scoring, health scorecard |
|
||||
| `scoring.mjs` | Area scoring (v5 severity-weighted), health scorecard, `scoringVersion: 'v5'` |
|
||||
| `backup.mjs` | Backup creation, manifest parsing, checksum verification |
|
||||
| `diff-engine.mjs` | Drift diffing: `diffEnvelopes()`, `formatDiffReport()` |
|
||||
| `baseline.mjs` | Baseline save/load/list/delete for drift detection |
|
||||
| `report-generator.mjs` | Unified markdown reports: posture, drift, plugin health |
|
||||
| `suppression.mjs` | `.config-audit-ignore` parsing, finding suppression, audit trail |
|
||||
| `active-config-reader.mjs` | Read-only inventory of plugins/skills/MCP/hooks/CLAUDE.md cascade with token estimates |
|
||||
| `tokenizer-api.mjs` | Anthropic `count_tokens` wrapper for `--accurate-tokens` (v5 N5); 5s timeout, 429 backoff, key masking |
|
||||
|
||||
### Action Engines
|
||||
|
||||
|
|
@ -447,6 +456,9 @@ Shared modules used by all scanners — useful if you're reading the source or e
|
|||
| `rollback-engine.mjs` | `listBackups()`, `restoreBackup()`, `deleteBackup()` |
|
||||
| `fix-cli.mjs` | CLI entry point for auto-fix |
|
||||
| `drift-cli.mjs` | CLI entry point for drift detection |
|
||||
| `manifest.mjs` | CLI: ranked system-prompt source table (v5 N2) |
|
||||
| `whats-active.mjs` | CLI: read-only active-config inventory (v3.1.0+) |
|
||||
| `token-hotspots-cli.mjs` | CLI: token hotspots ranking with optional `--accurate-tokens` |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -457,11 +469,13 @@ Reference documents that inform the feature-gap agent and context-aware recommen
|
|||
| File | Content |
|
||||
|------|---------|
|
||||
| `claude-code-capabilities.md` | Feature register: 18 config surfaces, Anthropic guidance, relevance table |
|
||||
| `configuration-best-practices.md` | Per-layer best practices |
|
||||
| `configuration-best-practices.md` | Per-layer best practices (Opus 4.7 cache-stability guidance) |
|
||||
| `anti-patterns.md` | Common mistakes mapped to scanner IDs |
|
||||
| `hook-events-reference.md` | All 26 hook events with details |
|
||||
| `feature-evolution.md` | Feature timeline for staleness detection |
|
||||
| `gap-closure-templates.md` | Config-specific templates for closing gaps |
|
||||
| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner |
|
||||
| `cache-telemetry-recipe.md` | `jq` recipe for verifying prompt-cache hit rate from session transcripts |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -471,7 +485,7 @@ Reference documents that inform the feature-gap agent and context-aware recommen
|
|||
node --test 'tests/**/*.test.mjs'
|
||||
```
|
||||
|
||||
486 tests across 27 test files (10 lib + 16 scanner + 1 hook). Test fixtures in `tests/fixtures/`. Requires Node.js 18+ (`node:test`).
|
||||
635 tests across 36 test files (12 lib + 23 scanner + 1 hook). Test fixtures in `tests/fixtures/`. Requires Node.js 18+ (`node:test`).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ You analyze Claude Code configuration and produce context-aware recommendations
|
|||
## Input
|
||||
|
||||
You receive posture assessment data (JSON) containing:
|
||||
- `areas` — per-scanner grades (8 quality areas incl. Token Efficiency, + Feature Coverage)
|
||||
- `areas` — per-scanner grades (10 quality areas incl. Token Efficiency, Plugin Hygiene, + Feature Coverage)
|
||||
- `overallGrade` — health grade (quality areas only)
|
||||
- `opportunityCount` — number of unused features detected
|
||||
- `scannerEnvelope` — full scanner results including GAP findings
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
name: config-audit
|
||||
description: Claude Code Configuration Intelligence - audit, analyze, and optimize your configuration
|
||||
argument-hint: "[posture|feature-gap|fix|rollback|plan|implement|help|discover|analyze|interview|drift|plugin-health|whats-active|status|cleanup]"
|
||||
argument-hint: "[posture|tokens|manifest|feature-gap|fix|rollback|plan|implement|help|discover|analyze|interview|drift|plugin-health|whats-active|status|cleanup]"
|
||||
allowed-tools: Read, Write, Glob, Grep, Bash, Agent, AskUserQuestion
|
||||
model: opus
|
||||
---
|
||||
|
|
@ -14,6 +14,8 @@ Analyze, report on, and optimize your Claude Code configuration.
|
|||
|
||||
If a subcommand is provided, route to it:
|
||||
- `posture` → `/config-audit:posture`
|
||||
- `tokens` → `/config-audit:tokens`
|
||||
- `manifest` → `/config-audit:manifest`
|
||||
- `feature-gap` → `/config-audit:feature-gap`
|
||||
- `fix` → `/config-audit:fix`
|
||||
- `rollback` → `/config-audit:rollback`
|
||||
|
|
@ -78,7 +80,7 @@ This is a silent infrastructure step — do NOT show output to the user.
|
|||
|
||||
### Step 3: Run scanners and posture assessment
|
||||
|
||||
Tell the user: **"Running 8 configuration scanners..."**
|
||||
Tell the user: **"Running 12 configuration scanners..."**
|
||||
|
||||
Run both scanners and posture in a single Bash command:
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,9 @@ Just run `/config-audit` — it auto-detects your project scope and runs a full
|
|||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/config-audit` | Full audit with auto-scope detection |
|
||||
| `/config-audit posture` | Quick scorecard with A-F grades per area |
|
||||
| `/config-audit posture` | Quick scorecard with A-F grades per area (10 areas) |
|
||||
| `/config-audit tokens` | Opus-4.7 token hotspots; optional `--accurate-tokens` API calibration |
|
||||
| `/config-audit manifest` | Ranked table of every system-prompt token source |
|
||||
| `/config-audit feature-gap` | Deep analysis of features you're not using |
|
||||
| `/config-audit fix` | Auto-fix deterministic issues with backup |
|
||||
| `/config-audit rollback` | Restore configuration from a backup |
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Quick, deterministic configuration health scorecard. No agents needed — runs a
|
|||
## What the user gets
|
||||
|
||||
- Health grade (A-F) with plain-language explanation
|
||||
- Per-area breakdown for 8 quality areas (incl. Token Efficiency) with grades and actionable notes
|
||||
- Per-area breakdown for 10 quality areas (incl. Token Efficiency, Plugin Hygiene) with grades and actionable notes
|
||||
- Opportunity count — how many features could enhance their setup (not a grade)
|
||||
- Grade-appropriate next steps
|
||||
|
||||
|
|
|
|||
|
|
@ -11,6 +11,8 @@
|
|||
import { resolve, dirname, join } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { readdir, readFile, stat } from 'node:fs/promises';
|
||||
import { execFile } from 'node:child_process';
|
||||
import { promisify } from 'node:util';
|
||||
import { runAllScanners } from './scan-orchestrator.mjs';
|
||||
import { scan as scanPluginHealth } from './plugin-health-scanner.mjs';
|
||||
import { scoreByArea } from './lib/scoring.mjs';
|
||||
|
|
@ -18,15 +20,24 @@ import { gradeFromPassRate } from './lib/severity.mjs';
|
|||
import { loadSuppressions, applySuppressions } from './lib/suppression.mjs';
|
||||
import { parseJson } from './lib/yaml-parser.mjs';
|
||||
|
||||
const execFileAsync = promisify(execFile);
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const PLUGIN_ROOT = resolve(__dirname, '..');
|
||||
|
||||
// Scanner-shape detection: files in scanners/ that export `scan` and are not
|
||||
// support modules. Matches the detection rule from v5 plan Step 16.
|
||||
//
|
||||
// `plugin-health-scanner.mjs` is excluded from the main scanner count: it has
|
||||
// `export async function scan` but it runs standalone (not via scan-orchestrator)
|
||||
// and is documented under "Standalone Scanner" in README/CLAUDE.md. The badge
|
||||
// `scanners-12` reflects the orchestrated scanners that contribute to posture
|
||||
// scoring.
|
||||
const SCANNER_EXCLUDES = new Set([
|
||||
'scan-orchestrator.mjs',
|
||||
'self-audit.mjs',
|
||||
'whats-active.mjs',
|
||||
'plugin-health-scanner.mjs',
|
||||
]);
|
||||
|
||||
function isScannerShape(name, content) {
|
||||
|
|
@ -74,6 +85,29 @@ async function countTestFiles(testsRoot) {
|
|||
return count;
|
||||
}
|
||||
|
||||
// Run the test suite in a subprocess and parse the `ℹ tests N` line emitted
|
||||
// by node:test. Used for badge accuracy under --check-readme. Slow (~15s on
|
||||
// the full plugin) but produces the canonical case count rather than an
|
||||
// approximation. Returns null on failure so the caller can fall back to
|
||||
// file count without crashing the audit.
|
||||
async function countTestCases(pluginRoot) {
|
||||
try {
|
||||
const { stdout } = await execFileAsync(
|
||||
process.execPath,
|
||||
['--test', 'tests/**/*.test.mjs'],
|
||||
{ cwd: pluginRoot, timeout: 60000, maxBuffer: 10 * 1024 * 1024 },
|
||||
);
|
||||
const match = stdout.match(/^[^\n]*tests\s+(\d+)\s*$/m);
|
||||
return match ? Number(match[1]) : null;
|
||||
} catch (err) {
|
||||
// node --test exits non-zero when tests fail; the count line is still
|
||||
// present on stdout. Re-parse it from the captured output.
|
||||
const stdout = err?.stdout || '';
|
||||
const match = stdout.match(/^[^\n]*tests\s+(\d+)\s*$/m);
|
||||
return match ? Number(match[1]) : null;
|
||||
}
|
||||
}
|
||||
|
||||
async function countHookEntries(hooksJsonPath) {
|
||||
let content;
|
||||
try { content = await readFile(hooksJsonPath, 'utf-8'); } catch { return 0; }
|
||||
|
|
@ -114,12 +148,13 @@ function parseBadgeNumber(readme, kind) {
|
|||
* @returns {Promise<{passed: boolean, mismatches: Array<{kind:string, expected:number, foundInReadme:number}>, counts: object, badges: object}>}
|
||||
*/
|
||||
export async function checkReadmeBadges(pluginDir) {
|
||||
const testCases = await countTestCases(pluginDir);
|
||||
const counts = {
|
||||
scanners: await countScannerShape(join(pluginDir, 'scanners')),
|
||||
commands: await countMdFiles(join(pluginDir, 'commands')),
|
||||
agents: await countMdFiles(join(pluginDir, 'agents')),
|
||||
hooks: await countHookEntries(join(pluginDir, 'hooks', 'hooks.json')),
|
||||
tests: await countTestFiles(join(pluginDir, 'tests')),
|
||||
tests: testCases ?? await countTestFiles(join(pluginDir, 'tests')),
|
||||
knowledge: await countMdFiles(join(pluginDir, 'knowledge')),
|
||||
};
|
||||
let readme = '';
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue