@boyingliu01/xp-gate 0.31.3 → 0.32.0

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/baseline.ts

@@ -19,6 +19,41 @@ interface BaselineStorageConfig {
 
 type ToolValidator = (entry: BaselineEntry, file: string) => void;
 
+/** The per-tool counters a baseline entry can carry, in report order. */
+const TOOL_KEYS = ['eslint', 'principles', 'ccn', 'ruff', 'golangci', 'shellcheck'] as const;
+type ToolKey = typeof TOOL_KEYS[number];
+
+/**
+ * Build one baseline entry from a file's per-tool counts.
+ *
+ * `createFromFiles` and `initializeWithAnalyzer` each carried this six-`if`
+ * accumulator plus its six-spread object literal verbatim (#620). Beyond the
+ * duplication, the copy-paste is what made both methods read as CCN 15-18: the
+ * complexity was not in what they did, it was in how many tools they listed.
+ *
+ * The two copies differed in ONE way, and this function keeps the stricter
+ * reading: an explicit `totalWarnings` wins when it is a number (including 0).
+ * `createFromFiles` tested truthiness, so a deliberate `totalWarnings: 0` was
+ * silently replaced by the sum -- the one case where the caller was trying to
+ * override a stale per-tool count.
+ */
+function buildEntry(counts: Partial<BaselineEntry>): BaselineEntry {
+  const entry: Partial<Record<ToolKey, unknown>> = {};
+  let summed = 0;
+  for (const key of TOOL_KEYS) {
+    const tool = counts[key];
+    if (!tool) continue;
+    entry[key] = tool;
+    summed += tool.warnings;
+  }
+  const totalWarnings = typeof counts.totalWarnings === 'number' ? counts.totalWarnings : summed;
+  return {
+    ...entry,
+    totalWarnings,
+    lastAnalyzed: new Date().toISOString(),
+  } as BaselineEntry;
+}
+
 function computeSummaryStats(baseline: Record<string, BaselineEntry>) {
   let totalFiles = 0;
   let totalWarnings = 0;
@@ -48,18 +83,27 @@ function computeSummaryStats(baseline: Record<string, BaselineEntry>) {
   };
 }
 
-function aggregateTool(stats: Record<string, { totalWarnings: number; totalErrors: number }>, entry: BaselineEntry) {
-  const tools: Array<{ key: string; warnings: number; errors: number }> = [
-    { key: 'eslint', warnings: entry.eslint?.warnings ?? 0, errors: entry.eslint?.errors ?? 0 },
-    { key: 'principles', warnings: entry.principles?.warnings ?? 0, errors: entry.principles?.errors ?? 0 },
-    { key: 'ruff', warnings: entry.ruff?.warnings ?? 0, errors: entry.ruff?.errors ?? 0 },
-    { key: 'golangci', warnings: entry.golangci?.warnings ?? 0, errors: entry.golangci?.errors ?? 0 },
-    { key: 'shellcheck', warnings: entry.shellcheck?.warnings ?? 0, errors: entry.shellcheck?.errors ?? 0 },
-  ];
-  for (const t of tools) {
-    if (t.warnings > 0 || t.errors > 0) {
-      stats[t.key] = { totalWarnings: (stats[t.key]?.totalWarnings || 0) + t.warnings, totalErrors: (stats[t.key]?.totalErrors || 0) + t.errors };
-    }
+/** Tools whose counts are summed, and which shape their counter has. */
+const AGGREGATED_TOOLS = ['eslint', 'principles', 'ruff', 'golangci', 'shellcheck'] as const;
+
+function toolCounters(entry: BaselineEntry, key: typeof AGGREGATED_TOOLS[number]): { warnings: number; errors: number } {
+  const tool = entry[key];
+  if (!tool) return { warnings: 0, errors: 0 };
+  return { warnings: tool.warnings, errors: tool.errors };
+}
+
+function aggregateTool(
+  stats: Record<string, { totalWarnings: number; totalErrors: number }>,
+  entry: BaselineEntry,
+): void {
+  for (const key of AGGREGATED_TOOLS) {
+    const { warnings, errors } = toolCounters(entry, key);
+    if (warnings <= 0 && errors <= 0) continue;
+    const running = stats[key] ?? { totalWarnings: 0, totalErrors: 0 };
+    stats[key] = {
+      totalWarnings: running.totalWarnings + warnings,
+      totalErrors: running.totalErrors + errors,
+    };
   }
 }
 
@@ -148,44 +192,9 @@ class BaselineStorage {
 
   async createFromFiles(warningData: Array<{ file: string; counts: Partial<BaselineEntry> }>): Promise<Record<string, BaselineEntry>> {
     const baseline: Record<string, BaselineEntry> = {};
-    
     for (const item of warningData) {
-      let totalWarnings = 0;
-      
-      if (item.counts.eslint?.warnings) {
-        totalWarnings += item.counts.eslint.warnings;
-      }
-      if (item.counts.principles?.warnings) {
-        totalWarnings += item.counts.principles.warnings;
-      }
-      if (item.counts.ccn?.warnings) {
-        totalWarnings += item.counts.ccn.warnings;
-      }
-      if (item.counts.ruff?.warnings) {
-        totalWarnings += item.counts.ruff.warnings;
-      }
-      if (item.counts.golangci?.warnings) {
-        totalWarnings += item.counts.golangci.warnings;
-      }
-      if (item.counts.shellcheck?.warnings) {
-        totalWarnings += item.counts.shellcheck.warnings;
-      }
-      if (item.counts.totalWarnings) {
-        totalWarnings = item.counts.totalWarnings;
-      }
-      
-      baseline[item.file] = {
-        ...(item.counts.eslint && { eslint: item.counts.eslint }),
-        ...(item.counts.principles && { principles: item.counts.principles }),
-        ...(item.counts.ccn && { ccn: item.counts.ccn }),
-        ...(item.counts.ruff && { ruff: item.counts.ruff }),
-        ...(item.counts.golangci && { golangci: item.counts.golangci }),
-        ...(item.counts.shellcheck && { shellcheck: item.counts.shellcheck }),
-        totalWarnings,
-        lastAnalyzed: new Date().toISOString()
-      };
+      baseline[item.file] = buildEntry(item.counts);
     }
-    
     return baseline;
   }
 
@@ -217,28 +226,7 @@ class BaselineStorage {
         const promiseResults = await Promise.allSettled(
           batch.map(async (file) => {
             const counts = await warningCountFunction(file);
-            
-            let totalWarnings = 0;
-            if (counts.eslint?.warnings) totalWarnings += counts.eslint.warnings;
-            if (counts.principles?.warnings) totalWarnings += counts.principles.warnings;
-            if (counts.ccn?.warnings) totalWarnings += counts.ccn.warnings;
-            if (counts.ruff?.warnings) totalWarnings += counts.ruff.warnings;
-            if (counts.golangci?.warnings) totalWarnings += counts.golangci.warnings;
-            if (counts.shellcheck?.warnings) totalWarnings += counts.shellcheck.warnings;
-            if (counts.totalWarnings !== undefined) totalWarnings = counts.totalWarnings;
-
-            const baselineEntry: BaselineEntry = {
-              ...(counts.eslint && { eslint: counts.eslint }),
-              ...(counts.principles && { principles: counts.principles }),
-              ...(counts.ccn && { ccn: counts.ccn }),
-              ...(counts.ruff && { ruff: counts.ruff }),
-              ...(counts.golangci && { golangci: counts.golangci }),
-              ...(counts.shellcheck && { shellcheck: counts.shellcheck }),
-              totalWarnings,
-              lastAnalyzed: new Date().toISOString()
-            };
-
-            baseline[file] = baselineEntry;
+            baseline[file] = buildEntry(counts);
             completed.push(file);
 
             if (onProgress) {

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;
 }
 

package/principles/index.ts

@@ -15,6 +15,49 @@ interface CLIOptions {
 
 const VALID_FORMATS: readonly string[] = ['json', 'console', 'sarif'] as const;
 
+/**
+ * Split a `--files` value into paths.
+ *
+ * Splits on ANY whitespace, not just spaces. `find ... | head -50` produces a
+ * newline-separated list, and CI passed it quoted, so the whole blob arrived as
+ * one argument. `.split(' ')` kept it whole, the path could never resolve,
+ * nothing was analysed, and the run fell through to the console/empty path --
+ * writing "No violations found" into a file the workflow called
+ * principles.sarif (#623).
+ */
+function splitFileList(value: string): string[] {
+  return value.split(/\s+/).filter(f => f.trim());
+}
+
+/**
+ * The options that take a value, and what to do with it.
+ *
+ * Table-driven so adding a flag is a row rather than another `case` arm: the
+ * switch this replaces carried one branch per option, which is what pushed the
+ * measured complexity of the function past the Gate 3 threshold.
+ */
+const VALUE_OPTIONS: Record<string, (options: CLIOptions, value: string) => void> = {
+  '--files': (options, value) => {
+    options.files = splitFileList(value);
+  },
+  // An unrecognised format is ignored rather than rejected, so a typo degrades
+  // to the default console output instead of an empty SARIF file.
+  '--format': (options, value) => {
+    if (VALID_FORMATS.includes(value)) options.format = value as CLIOptions['format'];
+  },
+  // Previously absent, so `--config .principlesrc` was silently filed into
+  // `files` and the path was analysed as if it were source (#457).
+  '--config': (options, value) => {
+    options.configPath = value;
+  },
+};
+
+/** The boolean flags, and the field each one sets. */
+const FLAG_OPTIONS: Record<string, keyof CLIOptions> = {
+  '--changed-only': 'changedOnly',
+  '--show-score': 'showScore',
+};
+
 export function parseArgs(args: string[]): CLIOptions {
   const options: CLIOptions = {
     files: [],
@@ -22,34 +65,27 @@ export function parseArgs(args: string[]): CLIOptions {
     changedOnly: false,
     showScore: false
   };
-  
+
   for (let i = 0; i < args.length; i++) {
-    switch (args[i]) {
-      case '--files':
-        const next = args[++i];
-        if (next) options.files = next.split(' ').filter(f => f.trim());
-        break;
-      case '--format':
-        const fmt = args[++i];
-        if (fmt && VALID_FORMATS.includes(fmt)) options.format = fmt as 'json' | 'console' | 'sarif';
-        break;
-      case '--changed-only':
-        options.changedOnly = true;
-        break;
-      case '--show-score':
-        options.showScore = true;
-        break;
-      // Previously absent, so `--config .principlesrc` was silently filed into
-      // `files` and the path was analysed as if it were source (#457).
-      case '--config':
-        const cfg = args[++i];
-        if (cfg) options.configPath = cfg;
-        break;
-      default:
-        if (!args[i].startsWith('--')) options.files.push(args[i]);
+    const arg = args[i];
+
+    const valueOption = VALUE_OPTIONS[arg];
+    if (valueOption) {
+      const value = args[++i];
+      if (value !== undefined) valueOption(options, value);
+      continue;
     }
+
+    const flagField = FLAG_OPTIONS[arg];
+    if (flagField) {
+      (options[flagField] as boolean) = true;
+      continue;
+    }
+
+    // A bare path accumulates instead of being dropped.
+    if (!arg.startsWith('--')) options.files.push(arg);
   }
-  
+
   return options;
 }
 
@@ -59,18 +95,68 @@ function getAllRules() {
 
 export { getAllRules };
 
+/**
+ * Report a run that could not examine everything it was asked to.
+ *
+ * A file the checker could not read is not a file it found clean. Before #623,
+ * `analyze` filed read failures in `result.errors` and nothing ever read that
+ * array: the run exited 0 and printed a clean report, which CI's SARIF step then
+ * archived. That is how `Analysis failed: Could not read file: ...` appeared in
+ * the log while the step still produced a report.
+ *
+ * Naming the paths matters as much as the exit status -- an operator needs to
+ * know WHICH files were never looked at.
+ */
+function reportIncomplete(errors: string[]): void {
+  console.error(`Analysis incomplete: ${errors.length} file(s) could not be examined`);
+  for (const err of errors) console.error(`  ${err}`);
+}
+
+/**
+ * The usage error for a run that was given nothing to check.
+ *
+ * Returns 2, not 1. Under this module's contract exit 1 asserts "I examined
+ * files and found ERROR-severity violations". A gate that sees 1 with an empty
+ * report reads it as a clean pass, so returning 1 here would let a miswired hook
+ * announce PASSED having checked nothing at all.
+ */
+const USAGE_EXIT = 2;
+
+function usageMessage(): void {
+  console.error('Usage: principles-checker --files <file1> <file2> ... [--format console|json|sarif] [--changed-only] [--config <path>]');
+}
+
+/**
+ * Decide the exit status for a completed analysis.
+ *
+ * Split out of `main` so the status contract lives in one place and can be read
+ * without following the run:
+ *
+ *   2 - a file could not be examined (this module's "could not examine")
+ *   1 - the analysis completed and found ERROR-severity violations
+ *   0 - the analysis completed and found none
+ *
+ * 1 is deliberately narrow. Returning 1 for any violation made info/warning
+ * noise (e.g. magic-numbers `info`) look like a tool failure: Gate 4 treats a
+ * non-zero exit as "checker execution failed" and downgrades itself to SKIPPED,
+ * silently disabling the gate.
+ */
+function exitStatusFor(result: { errors: string[]; summary: { errorCount: number } }): number {
+  if (result.errors.length > 0) {
+    reportIncomplete(result.errors);
+    return 2;
+  }
+  return result.summary.errorCount > 0 ? 1 : 0;
+}
+
 export async function main(args: string[]): Promise<number> {
   const options = parseArgs(args);
-  
+
   if (options.files.length === 0) {
-    console.error('Usage: principles-checker --files <file1> <file2> ... [--format console|json|sarif] [--changed-only] [--config <path>]');
-    // 2, not 1. Under this module's contract exit 1 asserts "I examined files and
-    // found ERROR-severity violations". A gate that sees 1 with an empty report
-    // reads it as a clean pass, so returning 1 here would let a miswired hook
-    // announce PASSED having checked nothing at all.
-    return 2;
+    usageMessage();
+    return USAGE_EXIT;
   }
-  
+
   // Install the loaded config so rules read the PROJECT's thresholds. The
   // previous `await loadConfig();` discarded the result, so `.principlesrc` was
   // parsed and thrown away while the built-in defaults were enforced (#457).
@@ -78,19 +164,15 @@ export async function main(args: string[]): Promise<number> {
 
   const rules = getAllRules();
   const result = await analyze(options.files, rules, getAdapterForFile);
-  
+
   const formatters: Record<string, (r: typeof result) => string> = {
     json: formatJSON,
     sarif: formatSARIF,
     console: formatConsole,
   };
   console.log(formatters[options.format](result));
-  
-  // Exit 1 only for ERROR-severity violations. Returning 1 for any violation
-  // made info/warning noise (e.g. magic-numbers `info`) look like a tool
-  // failure: Gate 4 treats a non-zero exit as "checker execution failed" and
-  // downgrades itself to SKIPPED, silently disabling the gate.
-  return result.summary.errorCount > 0 ? 1 : 0;
+
+  return exitStatusFor(result);
 }
 
 // Support both CJS (require.main === module) and ESM (import.meta.url) runtimes.

package/principles/rules/clean-code/deep-nesting.ts

@@ -1,36 +1,50 @@
 import { Rule, Violation, Severity } from '../../types';
 import { getActiveConfig } from '../../config';
 
+/** One function as the adapter reports it. */
+interface FunctionFacts {
+  name?: string;
+  nestingDepth?: number;
+  startLine?: number;
+  line?: number;
+}
+
+/** The shape of the adapter we consult. */
+interface TypedAdapter {
+  extractFunctions?: () => FunctionFacts[] | undefined;
+}
+
+/** A violation when one function nests deeper than the threshold, else null. */
+function nestingViolation(
+  func: FunctionFacts, maxDepth: number, file: string, severity: Severity,
+): Violation | null {
+  const depth = func.nestingDepth;
+  if (!depth || depth <= maxDepth) return null;
+  return {
+    file,
+    line: func.startLine ?? func.line ?? 1,
+    ruleId: 'clean-code.deep-nesting',
+    severity,
+    message: `Function "${func.name}" has deep nesting: ${depth} levels (maximum: ${maxDepth})`,
+  };
+}
+
 export const deepNestingRule: Rule = {
   id: 'clean-code.deep-nesting',
   name: 'Deep Nesting Rule',
   threshold: 4,
   severity: 'warning',
   check: (file: string, adapter: unknown): Violation[] => {
-    const violations: Violation[] = [];
     // Read the ACTIVE config per invocation; a module-load snapshot was #457.
     const settings = getActiveConfig().rules['clean-code']['deep-nesting'];
-    
-    interface TypedAdapter {
-      extractFunctions?: () => Array<{name?: string, nestingDepth?: number, startLine?: number, line?: number}> | undefined;
-    }
-    const typedAdapter = adapter as TypedAdapter;
-    const functions = typedAdapter.extractFunctions?.() || [];
-    
-    for (const func of functions) {
-      if (func.nestingDepth && func.nestingDepth > (settings.threshold ?? 0)) {
-        violations.push({
-          file,
-          line: func.startLine ?? func.line ?? 1,
-          ruleId: 'clean-code.deep-nesting',
-          message: `Function "${func.name}" has deep nesting: ${func.nestingDepth} levels (maximum: ${
-            settings.threshold
-          })`,
-          severity: (settings.severity as Severity) ?? 'warning'
-        });
-      }
+    const maxDepth = settings.threshold ?? 0;
+    const severity = (settings.severity as Severity) ?? 'warning';
+
+    const violations: Violation[] = [];
+    for (const func of (adapter as TypedAdapter).extractFunctions?.() || []) {
+      const found = nestingViolation(func, maxDepth, file, severity);
+      if (found) violations.push(found);
     }
-    
     return violations;
   }
-};
+};