From 3633571c7ef041a8fb8d6109d2a5015242da1815 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 19 Jun 2026 22:14:26 +0200 Subject: [PATCH] feat(set): validate autoMode structure + flag it in shared settings (CA-SET) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit settings-validator now validates the autoMode block (auto-mode classifier config). Structure (medium): autoMode must be an object whose only keys are environment/allow/soft_deny/hard_deny, each a string array ("$defaults" is a valid entry); flags not-an-object, unknown-subkey, not-string-array. Dead-config (low): Claude Code does not read autoMode from shared project settings (.claude/settings.json), so an autoMode block committed there has no effect — keyed on file.scope === 'project'. Both premises primary-source-verified (code.claude.com/docs/en/auto-mode-config). The plan's "test per-file scope first" gate passed: ConfigFile already carries scope. SET is in the orchestrator; SC-5 re-checked, byte-equal (snapshot fixture has no autoMode). Fixtures force-added (.claude/ is gitignored). Tests +5 (944->949). Scanner count unchanged (13). --json/--raw byte-stable. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8 --- CLAUDE.md | 22 ++++++ README.md | 13 +++- scanners/lib/humanizer-data.mjs | 22 +++++- scanners/settings-validator.mjs | 74 ++++++++++++++++++ .../.claude/settings.local.json | 4 + .../automode-shared/.claude/settings.json | 7 ++ .../.claude/settings.local.json | 9 +++ tests/scanners/settings-validator.test.mjs | 76 +++++++++++++++++++ 8 files changed, 225 insertions(+), 2 deletions(-) create mode 100644 tests/fixtures/automode-nonobject/.claude/settings.local.json create mode 100644 tests/fixtures/automode-shared/.claude/settings.json create mode 100644 tests/fixtures/automode-structure/.claude/settings.local.json diff --git a/CLAUDE.md b/CLAUDE.md index c11c39e..c176ffc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -221,6 +221,28 @@ claimed CC "suggests the parent directory when an entry points at a file"; that primary-source-verified conditions. `skills` is deliberately *not* in `SHADOWING_PATH_FIELDS` (it adds to the default scan, never shadows). +### SET scanner — autoMode validation (`CA-SET`) + +Per-file check in `settings-validator.mjs` (`autoMode` was in `KNOWN_KEYS` but had no nested +validation). Two sub-checks, both primary-source-verified against +`code.claude.com/docs/en/auto-mode-config`: + +1. **Structure** (severity **MEDIUM**): `autoMode`, if present, must be an object whose only keys + are `environment`/`allow`/`soft_deny`/`hard_deny` (`AUTO_MODE_SUBKEYS`), each a **string + array** (the literal `"$defaults"` is a valid entry, so it passes the string check for free). + `problem` ∈ `not-an-object` / `unknown-subkey` / `not-string-array` in `details`. +2. **Dead-config** (severity **LOW**): Claude Code does **not** read `autoMode` from *shared* + project settings — verbatim: *"The classifier does not read `autoMode` from shared project + settings in `.claude/settings.json`, so a checked-in repo cannot inject its own allow rules."* + The check keys on **`file.scope === 'project'`** (file-discovery's `classifyScope` returns + `'project'` for a committed `.claude/settings.json`; `'local'`/`'user'`/`'managed'` are read and + not flagged). `problem: 'shared-project-scope'`. This is why the plan's "test per-file scope + first" gate passed — `ConfigFile` already carries `scope`. + +The two sub-checks are independent (a malformed autoMode in shared scope yields both). SET is in the +orchestrator, so SC-5 was re-checked after this change — byte-equal (the snapshot fixture has no +`autoMode`, so the block never fires there). + ## Gotchas - Session directories accumulate — use `/config-audit cleanup` to manage diff --git a/README.md b/README.md index 4b7364e..3d97e72 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ ![Commands](https://img.shields.io/badge/commands-18-green) ![Agents](https://img.shields.io/badge/agents-6-orange) ![Hooks](https://img.shields.io/badge/hooks-4-red) -![Tests](https://img.shields.io/badge/tests-944+-brightgreen) +![Tests](https://img.shields.io/badge/tests-949+-brightgreen) ![License](https://img.shields.io/badge/license-MIT-lightgrey) 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. 13 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, a prompt-cache-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. @@ -393,6 +393,17 @@ By default, `/config-audit` auto-detects scope from your git context. Override w > `claude plugin validate`. Note `skills` *adds to* the default `skills/` scan, so a custom path > here is never a shadow — it just has to resolve to a real folder. +> **`autoMode` validation — structure and the shared-settings blind spot.** The SET scanner +> checks the auto-mode classifier config two ways. **Structure:** `autoMode` must be an object +> whose only keys are `environment`, `allow`, `soft_deny`, and `hard_deny`, each a list of +> plain-text rule strings (the literal `"$defaults"` is allowed). An unknown sub-key (e.g. a +> typo'd `hard_denies`), a non-object value, or a sub-key that isn't a string array is flagged +> **medium** — a typo'd key silently drops those rules. **Scope:** Claude Code does **not** read +> `autoMode` from *shared* project settings (`.claude/settings.json`) — "a checked-in repo cannot +> inject its own allow rules" — so an `autoMode` block committed there is dead config (**low**); +> it only takes effect in user (`~/.claude/settings.json`), local (`.claude/settings.local.json`), +> or managed settings. + ### CLI Tools All tools work standalone — no Claude Code session needed: diff --git a/scanners/lib/humanizer-data.mjs b/scanners/lib/humanizer-data.mjs index f550b7a..1eb64d2 100644 --- a/scanners/lib/humanizer-data.mjs +++ b/scanners/lib/humanizer-data.mjs @@ -142,7 +142,27 @@ export const TRANSLATIONS = { recommendation: 'Open the file and fix the JSON syntax shown in the details (often a missing comma or quote).', }, }, - patterns: [], + patterns: [ + { + // Specific case first: well-formed autoMode placed in the wrong scope. + regex: /^autoMode in shared project settings/, + translation: { + title: 'Your auto-mode rules are in a file Claude Code ignores', + description: 'Claude Code doesn\'t read `autoMode` from shared project settings (`.claude/settings.json`), so a checked-in repo can\'t grant itself auto-approval rules. The block has no effect where it is.', + recommendation: 'Move `autoMode` to your user settings (`~/.claude/settings.json`), the local (gitignored) project settings (`.claude/settings.local.json`), or managed settings.', + }, + }, + { + // Catch-all for autoMode structure problems (not-an-object, unknown + // sub-key, sub-key not a string array). + regex: /^autoMode/, + translation: { + title: 'Your `autoMode` block is malformed', + description: '`autoMode` must be an object with `environment`, `allow`, `soft_deny`, and `hard_deny`, each a list of plain-text rules. Part of it doesn\'t match that shape, so those rules may not apply.', + recommendation: 'Fix the `autoMode` entry shown in the details — use only the four known keys, each set to a list of strings.', + }, + }, + ], _default: { title: 'Your settings file has an issue', description: 'A check on your settings file flagged something worth a look.', diff --git a/scanners/settings-validator.mjs b/scanners/settings-validator.mjs index f220f7a..03a52ec 100644 --- a/scanners/settings-validator.mjs +++ b/scanners/settings-validator.mjs @@ -75,6 +75,11 @@ const VALID_EFFORT_LEVELS = new Set(['low', 'medium', 'high', 'xhigh', 'max']); * a project root to walks/discovery, inflating per-turn cost and confusing scope. */ const ADDITIONAL_DIRS_THRESHOLD = 2; +/** The only valid sub-keys of `autoMode`, each a prose-rule string array + * (the literal "$defaults" is a valid entry). Verified against + * code.claude.com/docs/en/auto-mode-config. */ +const AUTO_MODE_SUBKEYS = new Set(['environment', 'allow', 'soft_deny', 'hard_deny']); + /** * Scan all settings.json files discovered. * @param {string} targetPath @@ -234,6 +239,75 @@ export async function scan(targetPath, discovery) { })); } + // autoMode validation (auto-mode classifier config). + // Structure: must be an object whose only keys are the four documented + // prose-rule arrays (each an array of strings; "$defaults" is a valid entry). + // Dead-config: Claude Code does NOT read autoMode from SHARED project settings + // (.claude/settings.json) — "a checked-in repo cannot inject its own allow + // rules" — so it is only honored in user/local/managed scopes. + if (parsed.autoMode !== undefined) { + const am = parsed.autoMode; + if (typeof am !== 'object' || am === null || Array.isArray(am)) { + findings.push(finding({ + scanner: SCANNER, + severity: SEVERITY.medium, + title: 'autoMode must be an object', + description: `${file.relPath}: "autoMode" must be an object with environment/allow/soft_deny/hard_deny arrays, got ${Array.isArray(am) ? 'array' : typeof am}.`, + file: file.absPath, + evidence: `autoMode: ${JSON.stringify(am)}`, + recommendation: 'Set autoMode to an object, e.g. { "environment": ["$defaults"] }.', + autoFixable: false, + details: { key: 'autoMode', problem: 'not-an-object' }, + })); + } else { + for (const subKey of Object.keys(am)) { + if (!AUTO_MODE_SUBKEYS.has(subKey)) { + findings.push(finding({ + scanner: SCANNER, + severity: SEVERITY.medium, + title: `autoMode has an unknown sub-key: ${subKey}`, + description: `${file.relPath}: "autoMode.${subKey}" is not a recognized sub-key. Valid keys are environment, allow, soft_deny, hard_deny. It is silently ignored — a typo of a real key (e.g. "hard_denies") means those rules never apply.`, + file: file.absPath, + evidence: `autoMode.${subKey}`, + recommendation: 'Use only environment, allow, soft_deny, hard_deny. Check for typos.', + autoFixable: false, + details: { key: 'autoMode', subKey, problem: 'unknown-subkey' }, + })); + continue; + } + const val = am[subKey]; + const isStringArray = Array.isArray(val) && val.every(e => typeof e === 'string'); + if (!isStringArray) { + findings.push(finding({ + scanner: SCANNER, + severity: SEVERITY.medium, + title: `autoMode.${subKey} must be an array of strings`, + description: `${file.relPath}: "autoMode.${subKey}" must be an array of prose-rule strings (the literal "$defaults" is allowed), got ${Array.isArray(val) ? 'an array with a non-string entry' : typeof val}.`, + file: file.absPath, + evidence: `autoMode.${subKey}: ${JSON.stringify(val)}`, + recommendation: `Set "autoMode.${subKey}" to an array of strings, e.g. ["$defaults"].`, + autoFixable: false, + details: { key: 'autoMode', subKey, problem: 'not-string-array' }, + })); + } + } + } + // Dead-config: shared project settings (.claude/settings.json) is not read. + if (file.scope === 'project') { + findings.push(finding({ + scanner: SCANNER, + severity: SEVERITY.low, + title: 'autoMode in shared project settings is ignored by Claude Code', + description: `${file.relPath}: Claude Code does not read "autoMode" from shared project settings (.claude/settings.json), so a checked-in repo cannot inject its own rules. This autoMode block has no effect where it is.`, + file: file.absPath, + evidence: 'autoMode in shared .claude/settings.json (project scope)', + recommendation: 'Move autoMode to user settings (~/.claude/settings.json), local settings (.claude/settings.local.json), or managed settings.', + autoFixable: false, + details: { key: 'autoMode', problem: 'shared-project-scope' }, + })); + } + } + // hooks checks (basic — detailed in hook-validator) if (parsed.hooks) { if (Array.isArray(parsed.hooks)) { diff --git a/tests/fixtures/automode-nonobject/.claude/settings.local.json b/tests/fixtures/automode-nonobject/.claude/settings.local.json new file mode 100644 index 0000000..ac16e46 --- /dev/null +++ b/tests/fixtures/automode-nonobject/.claude/settings.local.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "autoMode": "on" +} diff --git a/tests/fixtures/automode-shared/.claude/settings.json b/tests/fixtures/automode-shared/.claude/settings.json new file mode 100644 index 0000000..2e9d890 --- /dev/null +++ b/tests/fixtures/automode-shared/.claude/settings.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "autoMode": { + "environment": ["$defaults", "Org: acme"], + "hard_deny": ["$defaults"] + } +} diff --git a/tests/fixtures/automode-structure/.claude/settings.local.json b/tests/fixtures/automode-structure/.claude/settings.local.json new file mode 100644 index 0000000..38a93f8 --- /dev/null +++ b/tests/fixtures/automode-structure/.claude/settings.local.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "autoMode": { + "environment": ["$defaults"], + "allow": "oops-not-an-array", + "soft_deny": ["ok", 7], + "bogus": ["x"] + } +} diff --git a/tests/scanners/settings-validator.test.mjs b/tests/scanners/settings-validator.test.mjs index 1af2d61..5aac01a 100644 --- a/tests/scanners/settings-validator.test.mjs +++ b/tests/scanners/settings-validator.test.mjs @@ -208,3 +208,79 @@ describe('SET scanner — empty project', () => { assert.strictEqual(result.findings.length, 0); }); }); + +describe('SET scanner — autoMode validation (CA-SET-NNN)', () => { + // All autoMode findings have a title starting with "autoMode". + const AM_RE = /^autoMode/; + const amFindings = (result) => result.findings.filter(f => f.scanner === 'SET' && AM_RE.test(f.title || '')); + + it('flags structural problems: wrong sub-key type, non-string array entry, unknown sub-key', async () => { + resetCounter(); + // automode-structure/.claude/settings.local.json (scope=local → no dead-config): + // environment valid; allow not-array; soft_deny ["ok",7]; bogus unknown sub-key. + const path = resolve(FIXTURES, 'automode-structure'); + const discovery = await discoverConfigFiles(path); + const result = await scan(path, discovery); + const am = amFindings(result); + const problems = am.map(f => f.details && f.details.problem).sort(); + assert.deepEqual( + problems, + ['not-string-array', 'not-string-array', 'unknown-subkey'], + `Expected 2 not-string-array + 1 unknown-subkey, got ${am.map(f => f.title).join(' | ')}` + ); + for (const f of am) { + assert.equal(f.severity, 'medium', `structure problem is medium: ${f.title}`); + assert.ok(/settings\.local\.json$/.test(f.file || ''), `points at the settings file: ${f.file}`); + assert.ok(f.details && f.details.key === 'autoMode', 'details.key === autoMode'); + } + }); + + it('does NOT flag a valid string-array sub-key (incl. "$defaults")', async () => { + resetCounter(); + const path = resolve(FIXTURES, 'automode-structure'); + const discovery = await discoverConfigFiles(path); + const result = await scan(path, discovery); + // environment: ["$defaults"] is valid → must not appear. + const envFlagged = amFindings(result).some(f => /environment/.test(f.title || '')); + assert.equal(envFlagged, false, 'a valid string array (with $defaults) is not flagged'); + }); + + it('flags autoMode that is not an object', async () => { + resetCounter(); + const path = resolve(FIXTURES, 'automode-nonobject'); + const discovery = await discoverConfigFiles(path); + const result = await scan(path, discovery); + const am = amFindings(result); + assert.equal(am.length, 1, `Expected one not-an-object finding, got ${am.map(f => f.title).join(' | ')}`); + assert.equal(am[0].details.problem, 'not-an-object'); + assert.equal(am[0].severity, 'medium'); + }); + + it('flags autoMode in shared project settings as dead config (and not in local scope)', async () => { + resetCounter(); + // automode-shared/.claude/settings.json → scope=project → dead-config. + const sharedPath = resolve(FIXTURES, 'automode-shared'); + const sharedResult = await scan(sharedPath, await discoverConfigFiles(sharedPath)); + const dead = amFindings(sharedResult).filter(f => f.details && f.details.problem === 'shared-project-scope'); + assert.equal(dead.length, 1, 'autoMode in shared .claude/settings.json is dead config'); + assert.equal(dead[0].severity, 'low', 'dead-config is low severity'); + // valid structure → no structure findings, only the dead-config one. + assert.equal(amFindings(sharedResult).length, 1, 'valid structure in shared scope yields only the dead-config finding'); + + // The same-shaped autoMode in LOCAL scope (automode-structure) must NOT be dead config. + resetCounter(); + const localPath = resolve(FIXTURES, 'automode-structure'); + const localResult = await scan(localPath, await discoverConfigFiles(localPath)); + const localDead = amFindings(localResult).filter(f => f.details && f.details.problem === 'shared-project-scope'); + assert.equal(localDead.length, 0, 'autoMode in settings.local.json is read by CC → not dead config'); + }); + + it('does NOT flag a settings file without autoMode', async () => { + resetCounter(); + // healthy-project has .claude/settings.json but no autoMode. + const path = resolve(FIXTURES, 'healthy-project'); + const discovery = await discoverConfigFiles(path); + const result = await scan(path, discovery); + assert.equal(amFindings(result).length, 0, 'no autoMode key → no autoMode findings'); + }); +});