@boyingliu01/xp-gate 0.31.4 → 0.32.1

package/principles/__tests__/baseline-prune.test.ts

@@ -336,3 +336,64 @@ describe('#452 REQ-3 stale baseline entries are pruned', () => {
     }
   });
 });
+
+/**
+ * @test REQ-628
+ * @intent `parseBaselineFiles` accepts two shapes: the FLAT map that
+ *         `saveBaseline` writes, and a legacy `{files: {...}}` wrapper kept for
+ *         forwards compatibility. The wrapper branch had no test, so deleting it
+ *         left the whole suite green — a silent regression that would make every
+ *         real baseline look empty (all entries filtered out as non-objects,
+ *         since the only top-level key is `files`). These cases pin both shapes
+ *         plus the scalar-filtering rule that follows from them.
+ * @covers AC-628-01, AC-628-02, AC-628-03
+ */
+describe('#628 REQ-3 parseBaselineFiles shape handling', () => {
+  it('AC-628-01: a flat map is read entry-for-entry', () => {
+    const { root } = makeRepoWithCommit();
+    const flat = JSON.stringify({
+      'src/a.ts': { totalWarnings: 2, lastAnalyzed: '2026-01-01T00:00:00Z' },
+      'src/gone.ts': { totalWarnings: 1, lastAnalyzed: '2026-01-01T00:00:00Z' },
+    });
+    stageIndexOnly(root, ['src/a.ts']);
+
+    const result = pruneBaselineEntries(flat, root);
+    expect(result.kept).toContain('src/a.ts');
+    expect(result.removed).toContain('src/gone.ts');
+    expect(result.error).toBeUndefined();
+  });
+
+  it('AC-628-02: a {files:{...}} wrapper is unwrapped, not treated as one entry', () => {
+    const { root } = makeRepoWithCommit();
+    // Without the unwrap, the sole top-level key `files` is an object, so the
+    // flat path would yield ONE entry called "files" and silently lose every
+    // real path. Assert the real paths surface.
+    const wrapped = JSON.stringify({
+      files: {
+        'src/a.ts': { totalWarnings: 2, lastAnalyzed: '2026-01-01T00:00:00Z' },
+        'src/gone.ts': { totalWarnings: 1, lastAnalyzed: '2026-01-01T00:00:00Z' },
+      },
+    });
+    stageIndexOnly(root, ['src/a.ts']);
+
+    const result = pruneBaselineEntries(wrapped, root);
+    expect(result.kept).toContain('src/a.ts');
+    expect(result.removed).toContain('src/gone.ts');
+    expect(result.kept).not.toContain('files');
+  });
+
+  it('AC-628-03: scalar top-level keys are metadata and are dropped, not kept as entries', () => {
+    const { root } = makeRepoWithCommit();
+    const withMeta = JSON.stringify({
+      version: 2,
+      generatedAt: '2026-01-01T00:00:00Z',
+      'src/a.ts': { totalWarnings: 2, lastAnalyzed: '2026-01-01T00:00:00Z' },
+    });
+    stageIndexOnly(root, ['src/a.ts']);
+
+    const result = pruneBaselineEntries(withMeta, root);
+    expect(result.kept).toEqual(['src/a.ts']);
+    expect(result.kept).not.toContain('version');
+    expect(result.kept).not.toContain('generatedAt');
+  });
+});

package/principles/__tests__/cli-files-separators.test.ts

@@ -0,0 +1,69 @@
+/**
+ * @test REQ-623
+ * @intent `--files` must accept the shapes a shell actually produces. CI passed
+ *         `--files "$SRC_FILES"` -- one argument containing newline-separated
+ *         paths -- and parseArgs split on spaces only, so the whole blob became
+ *         a single impossible path. The run then had nothing to analyse and fell
+ *         through to the console/empty path, writing "✓ No violations found"
+ *         into a file named principles.sarif. The step exited 0, so for months
+ *         the GitHub Security tab received a text file where SARIF was expected.
+ *
+ *         These tests pin the separator handling, not one call site: a fix that
+ *         only changes the workflow leaves the next caller to hit the same trap.
+ * @covers AC-623-01, AC-623-02, AC-623-03
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseArgs } from '../index';
+
+describe('AC-623-01: --files separates on any whitespace, not just spaces', () => {
+  it('splits a newline-separated list (the CI shape)', () => {
+    const opts = parseArgs(['--files', 'a.ts\nb.ts\nc.ts']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts', 'c.ts']);
+  });
+
+  it('splits a space-separated list', () => {
+    const opts = parseArgs(['--files', 'a.ts b.ts']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('splits a tab-separated list', () => {
+    const opts = parseArgs(['--files', 'a.ts\tb.ts']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('drops the blank entries a trailing separators leave behind', () => {
+    const opts = parseArgs(['--files', 'a.ts\n\nb.ts\n']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('keeps a single path intact', () => {
+    const opts = parseArgs(['--files', 'src/one.ts']);
+    expect(opts.files).toEqual(['src/one.ts']);
+  });
+});
+
+describe('AC-623-02: a flag after --files is still parsed', () => {
+  it('reads --format sarif that follows a multi-line --files value', () => {
+    const opts = parseArgs(['--files', 'a.ts\nb.ts', '--format', 'sarif']);
+    expect(opts.format).toBe('sarif');
+    expect(opts.files).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('reads --format when it comes before --files', () => {
+    const opts = parseArgs(['--format', 'sarif', '--files', 'a.ts\nb.ts']);
+    expect(opts.format).toBe('sarif');
+  });
+});
+
+describe('AC-623-03: positional paths still accumulate', () => {
+  it('collects bare paths given without --files', () => {
+    const opts = parseArgs(['a.ts', 'b.ts']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts']);
+  });
+
+  it('accepts --files alongside positional paths', () => {
+    const opts = parseArgs(['--files', 'a.ts\nb.ts', 'c.ts']);
+    expect(opts.files).toEqual(['a.ts', 'b.ts', 'c.ts']);
+  });
+});

package/principles/__tests__/config-merge-warnings.test.ts

@@ -0,0 +1,148 @@
+/**
+ * @test REQ-620
+ * @intent Pin mergeRule's mistyped-override handling, which had NO coverage
+ *         before this change: nothing asserted the warning text or the
+ *         keep-the-default outcome for a bad .principlesrc value. That gap
+ *         meant the four per-key loops could be consolidated into one guarded
+ *         loop without any test noticing, so these tests are what makes the
+ *         consolidation verifiable rather than merely plausible.
+ *
+ *         Two properties per key category:
+ *           1. a correctly-typed override is applied;
+ *           2. a mistyped one is REJECTED and the default survives, with a
+ *              warning naming the rule and the key.
+ *         Property 2 is the one with teeth: silently accepting a bad value
+ *         would let a project believe it tightened a gate.
+ *
+ *         .principlesrc is JSON (config.ts parses it with JSON.parse), so the
+ *         fixtures are JSON objects rather than YAML text.
+ * @covers AC-620-05
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadConfig, getDefaultConfig } from '../config';
+
+let tmpDirs: string[] = [];
+let warnings: string[];
+
+beforeEach(() => {
+  tmpDirs = [];
+  warnings = [];
+  // config.ts reports through process.stderr.write, not console.warn, so the
+  // spy has to sit on the stream. (Mocking console.warn instead silently
+  // captured nothing and made every "must warn" assertion look like a bug.)
+  vi.spyOn(process.stderr, 'write').mockImplementation((chunk: unknown) => {
+    warnings.push(String(chunk));
+    return true;
+  });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function warnText(): string {
+  return warnings.join('\n');
+}
+
+/** Default value of one key on `clean-code.long-function`. */
+function defaultFor(key: string): unknown {
+  const rule = getDefaultConfig().rules['clean-code']['long-function'] as unknown as Record<string, unknown>;
+  return rule[key];
+}
+
+/** Write a .principlesrc from RAW JSON text and load it unchanged. */
+async function loadRaw(jsonText: string) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'xp-gate-cfg-'));
+  tmpDirs.push(dir);
+  const cfgPath = path.join(dir, '.principlesrc');
+  fs.writeFileSync(cfgPath, jsonText, 'utf8');
+  return loadConfig(cfgPath);
+}
+
+/** Write a .principlesrc overriding `clean-code.long-function` and load it. */
+async function loadWithRule(overrides: Record<string, unknown>) {
+  return loadRaw(JSON.stringify({ rules: { 'clean-code': { 'long-function': overrides } } }));
+}
+
+describe('AC-620-05: a mistyped rule override keeps the default and warns', () => {
+  it('accepts a well-typed numeric override (threshold)', async () => {
+    const merged = await loadWithRule({ threshold: 12 });
+    expect(merged.rules['clean-code']['long-function'].threshold).toBe(12);
+    expect(warnText()).not.toMatch(/threshold/);
+  });
+
+  it('rejects a non-numeric threshold and keeps the default', async () => {
+    const merged = await loadWithRule({ threshold: 'not-a-number' });
+    expect(merged.rules['clean-code']['long-function'].threshold).toBe(defaultFor('threshold'));
+    expect(warnText()).toMatch(/threshold/);
+  });
+
+  it('rejects a non-finite threshold and keeps the default', async () => {
+    // A guard that only checks `typeof value === 'number'` would accept these
+    // and compare every function against NaN (or Infinity, which nothing ever
+    // exceeds -- silently disabling the rule).
+    //
+    // These literals have to be written as raw JSON TEXT: JSON.stringify turns
+    // NaN and Infinity into `null`, so handing them to the object-based helper
+    // would inject null and the test would pass against a broken guard. That
+    // exact mistake made the first version of this test vacuous.
+    const fallback = defaultFor('threshold');
+    for (const literal of ['1e999', '-1e999']) {
+      warnings = [];
+      const merged = await loadRaw(
+        `{"rules":{"clean-code":{"long-function":{"threshold":${literal}}}}}`,
+      );
+      expect(merged.rules['clean-code']['long-function'].threshold).toBe(fallback);
+      expect(warnText()).toMatch(/threshold/);
+    }
+  });
+
+  it('accepts a well-typed array override (exclude)', async () => {
+    const merged = await loadWithRule({ exclude: ['**/skip.ts'] });
+    expect(merged.rules['clean-code']['long-function'].exclude).toEqual(['**/skip.ts']);
+  });
+
+  it('rejects a scalar where an array is expected and keeps the default', async () => {
+    const merged = await loadWithRule({ exclude: '**/skip.ts' });
+    expect(merged.rules['clean-code']['long-function'].exclude).toEqual(defaultFor('exclude'));
+    expect(warnText()).toMatch(/exclude/);
+  });
+
+  it('copies the accepted array instead of aliasing the parsed one', async () => {
+    // mergeRule spreads array candidates; sharing the reference would let a
+    // later mutation of the caller's array leak into the active config.
+    const source = ['**/skip.ts'];
+    const merged = await loadWithRule({ exclude: source });
+    expect(merged.rules['clean-code']['long-function'].exclude).not.toBe(source);
+    expect(merged.rules['clean-code']['long-function'].exclude).toEqual(source);
+  });
+
+  it('accepts a well-typed enum override (severity)', async () => {
+    const merged = await loadWithRule({ severity: 'error' });
+    expect(merged.rules['clean-code']['long-function'].severity).toBe('error');
+  });
+
+  it('rejects an out-of-vocabulary severity and keeps the default', async () => {
+    // The dangerous case: a project writes a severity it believes is blocking
+    // but misspells it. Silently keeping the default would let that belief stand.
+    const merged = await loadWithRule({ severity: 'fatal' });
+    expect(merged.rules['clean-code']['long-function'].severity).toBe(defaultFor('severity'));
+    expect(warnText()).toMatch(/severity/);
+  });
+
+  it('rejects a non-boolean enabled flag and keeps the default', async () => {
+    const merged = await loadWithRule({ enabled: 'yes' });
+    expect(typeof merged.rules['clean-code']['long-function'].enabled).toBe('boolean');
+    expect(warnText()).toMatch(/enabled/);
+  });
+
+  it('names the offending rule and key in the warning', async () => {
+    await loadWithRule({ severity: 'fatal' });
+    expect(warnText()).toContain('long-function');
+    expect(warnText()).toContain('severity');
+  });
+});

package/principles/adapters/java.ts

@@ -1,6 +1,19 @@
 import { BaseAdapter } from './base';
 import { Adapter } from '../types';
 
+/**
+ * Depth change per nesting delimiter in a Java parameter list.
+ *
+ * Angular and square brackets nest exactly like parentheses here: the only thing
+ * that matters is whether a comma sits at depth 0, because that is the only
+ * place it separates parameters.
+ */
+const PARAM_NESTING: Record<string, number> = {
+  '(': 1, ')': -1,
+  '<': 1, '>': -1,
+  '[': 1, ']': -1,
+};
+
 /**
  * Structural fields the clean-code rules consume (mirror of the TypeScript
  * adapter's function shape). Before #507 this adapter returned only
@@ -213,12 +226,18 @@ export const javaParse = {
   countParams(paramList: string): number {
     const trimmed = paramList.trim();
     if (!trimmed) return 0;
+    // Generic and array brackets nest too: `Map<String, List<Integer>>` is ONE
+    // parameter, so the commas inside its arguments must not be counted.
+    // Which characters change depth and which separate is data, not control
+    // flow -- table lookups keep the scan to a single conditional.
     let depth = 0;
     let count = 1;
     for (const ch of trimmed) {
-      if (ch === '(' || ch === '<' || ch === '[') depth += 1;
-      else if (ch === ')' || ch === '>' || ch === ']') depth -= 1;
-      else if (ch === ',' && depth === 0) count += 1;
+      if (ch === ',') {
+        if (depth === 0) count += 1;
+        continue;
+      }
+      depth += PARAM_NESTING[ch] ?? 0;
     }
     return count;
   },

package/principles/adapters/typescript.ts

@@ -195,6 +195,13 @@ function inQuotedState(state: QuoteState): boolean {
   return state.inSingle || state.inDouble || state.inTemplate;
 }
 
+/** The three quote kinds tracked by QuoteState, with the flag that marks each. */
+const QUOTE_KINDS: ReadonlyArray<{ quote: string; flag: 'inSingle' | 'inDouble' | 'inTemplate' }> = [
+  { quote: "'", flag: 'inSingle' },
+  { quote: '"', flag: 'inDouble' },
+  { quote: '`', flag: 'inTemplate' },
+];
+
 /**
  * Advance one character of quote tracking.
  *
@@ -202,28 +209,25 @@ function inQuotedState(state: QuoteState): boolean {
  * six-branch block verbatim (#602): both must ignore delimiters that appear
  * inside a string, and neither may treat an escape as a closing quote.
  *
+ * Table-driven (#620): all three quote kinds behave identically -- an escape
+ * skips two characters, the matching quote closes the literal -- so they are one
+ * rule applied to a list rather than three copies of it.
+ *
  * @returns the number of characters consumed (2 when the next char is escaped).
  */
 function advanceQuoteState(src: string, i: number, state: QuoteState): number {
   const c = src[i];
-  if (state.inSingle) {
-    if (c === '\\') return 2;
-    if (c === "'") state.inSingle = false;
-    return 1;
-  }
-  if (state.inDouble) {
-    if (c === '\\') return 2;
-    if (c === '"') state.inDouble = false;
-    return 1;
-  }
-  if (state.inTemplate) {
+
+  for (const kind of QUOTE_KINDS) {
+    if (!state[kind.flag]) continue;
     if (c === '\\') return 2;
-    if (c === '`') state.inTemplate = false;
+    if (c === kind.quote) state[kind.flag] = false;
     return 1;
   }
-  if (c === "'") state.inSingle = true;
-  else if (c === '"') state.inDouble = true;
-  else if (c === '`') state.inTemplate = true;
+
+  // Not inside any literal: open the one this character starts, if any.
+  const opener = QUOTE_KINDS.find(kind => kind.quote === c);
+  if (opener) state[opener.flag] = true;
   return 1;
 }
 
@@ -273,29 +277,66 @@ function countParams(rawList: string): number {
   return count;
 }
 
+/** What one step of the paren-group scan did, so the caller can react. */
+type ParenStep =
+  | { kind: 'consumed'; next: number }
+  | { kind: 'closed'; end: number };
+
+/**
+ * Advance one step through a paren group.
+ *
+ * Extracted from `readParenGroup` (#620) so the three-way decision -- inside a
+ * literal, opening a literal, or structural bracket -- reads as one rule instead
+ * of being folded into the loop that also owns depth and substring slicing.
+ *
+ * A literal is entered through `advanceQuoteState` at the SAME index rather than
+ * consumed: that call flips the state on the opening quote and reports one
+ * character consumed, so re-scans resume one past the quote with the state set.
+ *
+ * @param depth running paren depth, updated in place for structural brackets
+ * @returns the next index to read, or the offset just past the closing paren
+ */
+function stepParenGroup(
+  src: string,
+  i: number,
+  state: QuoteState,
+  depth: { value: number },
+): ParenStep {
+  if (inQuotedState(state)) {
+    return { kind: 'consumed', next: i + advanceQuoteState(src, i, state) };
+  }
+
+  const c = src[i];
+  if (isQuote(c)) {
+    // Entering a literal: flip state here, resume at the next character.
+    advanceQuoteState(src, i, state);
+    return { kind: 'consumed', next: i + 1 };
+  }
+  if (c === '(') {
+    depth.value++;
+    return { kind: 'consumed', next: i + 1 };
+  }
+  if (c === ')') {
+    depth.value--;
+    if (depth.value === 0) return { kind: 'closed', end: i + 1 };
+  }
+  return { kind: 'consumed', next: i + 1 };
+}
+
 /**
  * Extract the balanced `( ... )` group that starts at `open`.
  * Returns the inner text and the index just past the closing paren.
  */
 function readParenGroup(src: string, open: number): { inner: string; end: number } {
-  let depth = 0;
   const state = newQuoteState();
+  const depth = { value: 0 };
 
   for (let i = open; i < src.length;) {
-    if (inQuotedState(state)) {
-      i += advanceQuoteState(src, i, state);
-      continue;
+    const step = stepParenGroup(src, i, state, depth);
+    if (step.kind === 'closed') {
+      return { inner: src.substring(open + 1, step.end - 1), end: step.end };
     }
-    const c = src[i];
-    if (c === "'" || c === '"' || c === '`') {
-      advanceQuoteState(src, i, state);
-    } else if (c === '(') {
-      depth++;
-    } else if (c === ')') {
-      depth--;
-      if (depth === 0) return { inner: src.substring(open + 1, i), end: i + 1 };
-    }
-    i++;
+    i = step.next;
   }
   return { inner: src.substring(open + 1), end: src.length };
 }

package/principles/analyzer.ts

@@ -131,7 +131,11 @@ function runRuleOnFile(ctx: RunRuleContext): void {
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    errors.push(`Rule ${rule.id} failed on ${file}: ${msg}`);
+    // A file that cannot be READ failed for every rule that touched it, so the
+    // same message would arrive once per rule. Dedupe to one entry per file: the
+    // caller acts on "this file was not examined", not on how many rules noticed.
+    const entry = `Rule ${rule.id} failed on ${file}: ${msg}`;
+    if (!errors.includes(entry)) errors.push(entry);
   }
 }
 
@@ -160,6 +164,35 @@ interface RunRuleContext {
   errors: string[];
 }
 
+/**
+ * Resolve the adapter for one path, reporting rather than throwing on failure.
+ *
+ * Resolving and probing an adapter can itself READ the file (adapters parse on
+ * construction), so an unreadable path throws here -- before any rule runs and
+ * outside runRuleOnFile's guard. Recorded as an error rather than allowed to
+ * abort the whole run: one bad path must not hide the findings for the good
+ * ones, but it must never be invisible either (#623).
+ *
+ * @returns the adapter, or null when the file cannot be examined at all
+ */
+function resolveAdapterReporting(
+  file: string,
+  adapterOrFactory: Adapter | AdapterFactory,
+  errors: string[],
+): Adapter | null {
+  try {
+    const adapter = resolveAdapter(file, adapterOrFactory);
+    if (!adapter || adapter.detectLanguage() === 'unknown') return null;
+    return adapter;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // One entry per file: the failure belongs to the file, not to however many
+    // rules happened to touch it.
+    if (!errors.includes(msg)) errors.push(msg);
+    return null;
+  }
+}
+
 export async function analyze(
   files: string[],
   rules: Rule[],
@@ -180,8 +213,8 @@ export async function analyze(
   }
 
   for (const file of files) {
-    const adapter = resolveAdapter(file, adapterOrFactory);
-    if (!adapter || adapter.detectLanguage() === 'unknown') continue;
+    const adapter = resolveAdapterReporting(file, adapterOrFactory, errors);
+    if (!adapter) continue;
 
     const fileResult: FileResult = { violations: [], ruleIds: [] };
     fileResults[file] = fileResult;

package/principles/baseline-prune.ts

@@ -107,6 +107,19 @@ export function pruneBaselineEntries(
   return { kept, removed };
 }
 
+/**
+ * A non-null, non-array object — the only shape a baseline map or a nested
+ * `files` wrapper can legally take.
+ *
+ * The three checks in `parseBaselineFiles` were the same predicate written out
+ * three times (once positively for the wrapper, once negated for the root, once
+ * positively per entry), which is most of its CCN. Naming it once removes the
+ * repetition and makes the intent legible.
+ */
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
 /**
  * Extract the path -> entry map, or a string describing why it is unusable.
  *
@@ -125,22 +138,21 @@ function parseBaselineFiles(baselineJson: string): Record<string, unknown> | str
     return `could not parse baseline: ${detail}`;
   }
 
-  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+  if (!isJsonObject(parsed)) {
     return 'baseline is not a JSON object';
   }
 
-  const record = parsed as Record<string, unknown>;
-  const nested = record.files;
-  if (nested !== null && typeof nested === 'object' && !Array.isArray(nested)) {
-    return nested as Record<string, unknown>;
+  // A `files` wrapper is unwrapped rather than merged, matching the old shape.
+  if (isJsonObject(parsed.files)) {
+    return parsed.files;
   }
 
   // Keep only object-valued keys: scalars at the top level are metadata, not
   // path entries, and a path whose entry is a bare number is the malformed shape
   // that assertValidEntry rejects elsewhere (#455).
   const entries: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(record)) {
-    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+  for (const [key, value] of Object.entries(parsed)) {
+    if (isJsonObject(value)) {
       entries[key] = value;
     }
   }

package/principles/config.ts

@@ -283,6 +283,43 @@ function mergeGroup<T extends Record<string, RuleConfig>>(
   return result;
 }
 
+/**
+ * How each key category is type-checked, and what the warning says when it is not.
+ *
+ * Every category follows the same shape -- skip when undefined, assign when the
+ * value passes its guard, warn otherwise (#620). Stating the guard and the
+ * expectation once per category lets one loop enforce all of them, instead of
+ * four near-identical loops that each have to be kept in step by hand.
+ */
+type ValueGuard = {
+  accepts: (value: unknown) => boolean;
+  expectation: string;
+  /** Coerce the accepted value before assignment (arrays are copied to detach). */
+  coerce?: (value: unknown) => unknown;
+};
+
+const NUMERIC_GUARD: ValueGuard = {
+  accepts: value => typeof value === 'number' && Number.isFinite(value),
+  expectation: 'a finite number',
+};
+
+const ARRAY_GUARD: ValueGuard = {
+  // Arrays REPLACE rather than concatenate, matching how .principlesrc is
+  // written today (an exclude list is the project's complete list).
+  accepts: value => Array.isArray(value),
+  expectation: 'an array',
+  coerce: value => [...(value as unknown[])],
+};
+
+function enumGuard(allowed: readonly string[]): ValueGuard {
+  return {
+    accepts: value => typeof value === 'string' && allowed.includes(value),
+    // Loud on purpose: silently keeping the default would let a project believe
+    // it raised a rule to blocking when it did not.
+    expectation: `one of ${allowed.join(', ')}`,
+  };
+}
+
 /** Merge one rule, keeping the default for any key whose override is mistyped. */
 function mergeRule(
   base: RuleConfig,
@@ -290,48 +327,32 @@ function mergeRule(
   ruleId: string
 ): RuleConfig {
   const merged: RuleConfig = { ...base };
+  const guarded: Array<[string, ValueGuard]> = [
+    ...NUMERIC_KEYS.map((key): [string, ValueGuard] => [key, NUMERIC_GUARD]),
+    ...ARRAY_KEYS.map((key): [string, ValueGuard] => [key, ARRAY_GUARD]),
+    ...Object.entries(ENUM_KEYS).map(([key, allowed]): [string, ValueGuard] => [
+      key,
+      enumGuard(allowed as readonly string[]),
+    ]),
+  ];
+
+  for (const [key, guard] of guarded) {
+    const value = override[key as keyof RuleConfig];
+    if (value === undefined) continue;
+    if (!guard.accepts(value)) {
+      warn(`rules.${ruleId}.${key} must be ${guard.expectation} — keeping default`);
+      continue;
+    }
+    merged[key as keyof RuleConfig] = (guard.coerce ? guard.coerce(value) : value) as never;
+  }
 
+  // `enabled` is a bare boolean, not one of the value categories above.
   if (typeof override.enabled === 'boolean') {
     merged.enabled = override.enabled;
   } else if (override.enabled !== undefined) {
     warn(`rules.${ruleId}.enabled must be a boolean — keeping default`);
   }
 
-  for (const key of NUMERIC_KEYS) {
-    const value = override[key];
-    if (value === undefined) continue;
-    if (typeof value === 'number' && Number.isFinite(value)) {
-      merged[key] = value;
-    } else {
-      warn(`rules.${ruleId}.${key} must be a finite number — keeping default`);
-    }
-  }
-
-  for (const key of ARRAY_KEYS) {
-    const value = override[key];
-    if (value === undefined) continue;
-    // Arrays REPLACE rather than concatenate, matching how .principlesrc is
-    // written today (an exclude list is the project's complete list).
-    if (Array.isArray(value)) {
-      merged[key] = [...value] as RuleConfig[typeof key];
-    } else {
-      warn(`rules.${ruleId}.${key} must be an array — keeping default`);
-    }
-  }
-
-  for (const key of Object.keys(ENUM_KEYS) as (keyof typeof ENUM_KEYS)[]) {
-    const allowed: readonly string[] = ENUM_KEYS[key];
-    const value = override[key];
-    if (value === undefined) continue;
-    if (typeof value === 'string' && allowed.includes(value)) {
-      merged[key] = value;
-    } else {
-      // Loud on purpose: silently keeping the default would let a project believe
-      // it raised a rule to blocking when it did not.
-      warn(`rules.${ruleId}.${key} must be one of ${allowed.join(', ')} — keeping default`);
-    }
-  }
-
   return merged;
 }