config-audit/docs/scanner-internals.md

Config-Audit — Scanner internals

Detailed scanner inventory, lib modules, action engines, knowledge base. Imported from CLAUDE.md via pointer.

Deterministic Scanners

Node.js scanners (zero external dependencies), run via node scanners/scan-orchestrator.mjs <path>. Posture CLI: node scanners/posture.mjs <path> [--json] [--global] [--full-machine] [--output-file path]. Scanner CLI: node scanners/scan-orchestrator.mjs <path> [--global] [--full-machine] [--no-suppress].

Scanner	Prefix	Detects
claude-md-linter.mjs	CML	Structure, length, sections, @imports, duplicates, TODOs
settings-validator.mjs	SET	Schema, unknown/deprecated keys, type mismatches, permissions
hook-validator.mjs	HKV	Format, script existence, event validity, timeouts
rules-validator.mjs	RUL	Glob matching, orphan rules, deprecated fields, unscoped rules
mcp-config-validator.mjs	MCP	Server types, env vars, unknown fields
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, oversized cascade, bloated SKILL.md descriptions, MCP tool-schema budget (prompt-cache 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	Dead/ineffective permission entries (low). (1) Tools in BOTH permissions.deny AND permissions.allow — deny wins; dominance is param-aware and treats the Tool(*) deny-all glob as equivalent to a bare deny (covers a bare allow). (2) Unanchored allow wildcards (*, B*, mcp__*) that Claude Code silently skips — CC accepts allow globs only after a literal glob-free mcp__<server>__ prefix. Predicates shared with CNF live in lib/permission-rules.mjs
collision-scanner.mjs	COL	Cross-plugin skill name collisions (low); user-vs-plugin overlaps (medium); details.namespaces payload
skill-listing-scanner.mjs	SKL	(1) CA-SKL-001 (medium): active skill descriptions over the verified 1,536-char listing cap (CC 2.1.105) → silently truncated in the model's skill listing. (2) CA-SKL-002 (low): sum of active descriptions (each counted up to the cap) over the listing budget (~2% of context, CC 2.1.32), anchored on a conservative 200k window with a calibration note that the budget scales 5× on 1M-context models — leads with the measured sum, an estimate not telemetry. HOME-scoped (all user + plugin skills). Remediation surfaces disableBundledSkills / skillOverrides / trim. Distinct lens from TOK pattern F (project-local 500-char bloat heuristic)
output-style-scanner.mjs	OST	(1) CA-OST-001 (medium): a user/project custom output style not setting keep-coding-instructions: true (defaults false) → silently strips Claude Code's built-in software-engineering instructions when active (V10). (2) CA-OST-002 (low): a plugin style with force-for-plugin: true auto-applies and overrides the user's outputStyle (V11; plugin-styles-only per docs). (3) CA-OST-003 (medium): a settings outputStyle matching no built-in (Default/Explanatory/Learning/Proactive, case-insensitive) nor discovered custom style → dead config (CC falls back to default). Reads each style's frontmatter via parseFrontmatter; fixture-gated (silent with no output styles). New scanner family in v5.6 C (count 13→14)
optimization-lens-scanner.mjs	OPT	CA-OPT-001 (low, Missed opportunity): a CLAUDE.md procedure (≥6 consecutive numbered steps) that belongs in a skill (mechanism-fit, BP-MECH-003). Reads the machine-readable best-practices register (best-practices-register.mjs) for recommendation + provenance. Conservative — negative corpus proves null false-positive; prose-judgment cases (lifecycle→hook, "never"→permission) deferred to the Chunk 2b opus analyzer. Scoring area CLAUDE.md (existing → byte-stable). New scanner family in v5.7 Fase 1 Chunk 2a (count 14→15)

Scanner Lib (scanners/lib/)

Module	Purpose
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	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() (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
humanizer.mjs	Plain-language output translator (v5.1.0): humanizeFinding, humanizeFindings, humanizeEnvelope, computeRelevanceContext. Pure functions; never mutate inputs. Adds userImpactCategory, userActionLanguage, relevanceContext fields and replaces title/description/recommendation when a translation exists. Bypassed by --raw and --json paths.
humanizer-data.mjs	TRANSLATIONS table for 16 scanner prefixes (CML/SET/HKV/RUL/MCP/IMP/CNF/COL/TOK/CPS/DIS/GAP/PLH/SKL/OST/OPT). Three-step lookup: exact title → regex pattern → _default → fall through to original

Action Engines (scanners/)

Module	Purpose
fix-engine.mjs	planFixes(), applyFixes(), verifyFixes() — 9 fix types
rollback-engine.mjs	listBackups(), restoreBackup(), deleteBackup()
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] [--accurate-tokens] [--with-telemetry-recipe] — prompt-cache token hotspots ranking (each hotspot tagged with its load pattern, v5.6 B2) with optional API calibration
manifest.mjs	CLI: node manifest.mjs <path> [--json] — ranked component-level token-source table, each source tagged with its load pattern + an always-loaded subtotal (v5 N2; load-pattern accounting v5.6 B)

Standalone Scanner

Module	Prefix	Purpose
plugin-health-scanner.mjs	PLH	Plugin structure, frontmatter, cross-plugin conflicts (runs independently)
self-audit.mjs	—	Runs all scanners + plugin health on this plugin itself

Knowledge Base (knowledge/)

File	Content
claude-code-capabilities.md	Feature register: 18 config surfaces, Anthropic guidance, relevance table
configuration-best-practices.md	Per-layer best practices (v5: cache-stability guidance replaces Sonnet-era 200-line rule)
anti-patterns.md	Common mistakes mapped to scanner IDs
hook-events-reference.md	All 28 hook events with details
feature-evolution.md	Feature timeline for staleness detection
gap-closure-templates.md	Config-specific templates for closing gaps
prompt-cache-patterns.md	Token-cost dynamics (prompt-cache patterns) — patterns powering the TOK scanner
cache-telemetry-recipe.md	Manual jq recipe for verifying prompt-cache hit rate from session transcripts (v5 M7)