@boyingliu01/xp-gate 0.31.4 → 0.32.1

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

package/principles/rules/clean-code/unused-imports.ts

@@ -1,31 +1,42 @@
 import { Rule, Violation, Severity } from '../../types';
 import { getActiveConfig } from '../../config';
 
+/** One import as the adapter reports it. */
+interface ImportFacts {
+  name?: string;
+  line?: number;
+  used?: boolean;
+  type?: string;
+}
+
+/**
+ * An import is unused when nothing references it. A `import type` is exempt: it
+ * is erased at compile time, so an unused type import is not dead code in the
+ * shipped output.
+ */
+function isUnusedValueImport(imp: ImportFacts): boolean {
+  return !imp.used && imp.type !== 'type';
+}
+
 export const unusedImportsRule: Rule = {
   id: 'clean-code.unused-imports',
   name: 'Unused Imports Rule',
   threshold: 1,
   severity: 'info',
   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']['unused-imports'];
-    
-    const typedAdapter = adapter as { imports?: Array<{name?: string; line?: number; used?: boolean; type?: string;}> | undefined };
-    const imports = typedAdapter.imports || [];
-    
-    for (const imp of imports) {
-      if (!imp.used && imp.type !== 'type') {
-        violations.push({
-          file,
-          line: imp.line ?? 1,
-          ruleId: 'clean-code.unused-imports',
-          message: `Unused import "${imp.name}" - consider removing`,
-          severity: (settings.severity as Severity) ?? 'info'
-        });
-      }
-    }
-    
-    return violations;
+    const severity = (settings.severity as Severity) ?? 'info';
+
+    const imports = (adapter as { imports?: ImportFacts[] }).imports || [];
+    return imports
+      .filter(isUnusedValueImport)
+      .map((imp) => ({
+        file,
+        line: imp.line ?? 1,
+        ruleId: 'clean-code.unused-imports',
+        message: `Unused import "${imp.name}" - consider removing`,
+        severity,
+      }));
   }
-};
+};

package/principles/rules/solid/dip.ts

@@ -21,35 +21,45 @@ function shouldSkipInstantiation(className: string): boolean {
   return false;
 }
 
+/** `new Foo(` -> `Foo`. */
+function classNameFromNewMatch(match: string): string {
+  return match.replace(/new\s+/, '').replace(/\s*\(/, '');
+}
+
+/** Violations for one class body: each `new X(` that is not exempt. */
+function instantiationViolations(
+  code: string, line: number, file: string, severity: Severity,
+): Violation[] {
+  const violations: Violation[] = [];
+  for (const match of code.match(/new\s+(\w+)\s*\(/g) || []) {
+    const className = classNameFromNewMatch(match);
+    if (shouldSkipInstantiation(className)) continue;
+    violations.push({
+      file,
+      line,
+      ruleId: 'solid.dip',
+      severity,
+      message: `Direct instantiation detected: new ${className}(). Prefer dependency injection for flexibility.`,
+    });
+  }
+  return violations;
+}
+
 export const dipRule: Rule = {
   id: 'solid.dip',
   name: 'Dependency Inversion Principle Rule',
   threshold: 0,
   severity: 'warning',
   check: (file: string, adapter: import('../../types').Adapter): Violation[] => {
-    const violations: Violation[] = [];
     const settings = getActiveConfig().rules['solid']['dip'];
     const severity = (settings.severity as Severity) ?? 'warning';
 
-    for (const cls_any of adapter.extractClasses() || []) {
-      const cls = cls_any as {code?: string; line?: number};
-      const code = cls.code;
-      if (!code) continue;
-
-      const newMatches = code.match(/new\s+(\w+)\s*\(/g) || [];
-      for (const match of newMatches) {
-        const className = match.replace(/new\s+/, '').replace(/\s*\(/, '');
-        if (shouldSkipInstantiation(className)) continue;
-
-        violations.push({
-          file,
-          line: cls.line || 0,
-          ruleId: 'solid.dip',
-          severity,
-          message: `Direct instantiation detected: new ${className}(). Prefer dependency injection for flexibility.`,
-        });
-      }
+    const violations: Violation[] = [];
+    for (const clsAny of adapter.extractClasses() || []) {
+      const cls = clsAny as { code?: string; line?: number };
+      if (!cls.code) continue;
+      violations.push(...instantiationViolations(cls.code, cls.line || 0, file, severity));
     }
     return violations;
   }
-};
+};

package/principles/rules/solid/lsp.ts

@@ -170,13 +170,28 @@ function undetermined(): Violation[] {
  * @param paramsText parameter list without surrounding parens
  * @returns parameter fragments
  */
+/** Delimiters that nest inside a parameter list (generics included). */
+const PARAM_OPENERS = '<([{';
+const PARAM_CLOSERS = '>)]}';
+
+/**
+ * Depth delta contributed by one character.
+ *
+ * Kept separate from the splitter so the nesting rule is stated once instead of
+ * being folded into the loop's condition (#620).
+ */
+function paramDepthDelta(ch: string): number {
+  if (PARAM_OPENERS.includes(ch)) return 1;
+  if (PARAM_CLOSERS.includes(ch)) return -1;
+  return 0;
+}
+
 function splitParams(paramsText: string): string[] {
   const parts: string[] = [];
   let depth = 0;
   let current = '';
   for (const ch of paramsText) {
-    if (ch === '<' || ch === '(' || ch === '[' || ch === '{') depth += 1;
-    else if (ch === '>' || ch === ')' || ch === ']' || ch === '}') depth -= 1;
+    depth += paramDepthDelta(ch);
     if (ch === ',' && depth <= 0) {
       parts.push(current);
       current = '';

package/principles/rules/solid/ocp.ts

@@ -1,39 +1,49 @@
 import { Rule, Violation } from '../../types';
 import { getActiveConfig } from '../../config';
 
+/** The base class named in `extends X`, or null when the class extends nothing. */
+function baseClassOf(code: string): string | null {
+  const match = code.match(/extends\s+(\w+)/);
+  return match ? match[1] : null;
+}
+
+/**
+ * OCP is violated when a class, in the same body, both extends a base class and
+ * redeclares it — a local extension that had to reach back into the base.
+ */
+function ocpViolation(
+  code: string, name: string | undefined, line: number, file: string,
+  severity: 'error' | 'warning' | 'info',
+): Violation | null {
+  const baseClass = baseClassOf(code);
+  if (baseClass === null) return null;
+  if (!code.includes(`class ${baseClass}`)) return null;
+  return {
+    file,
+    line,
+    ruleId: 'solid.ocp',
+    message: `Possible modification of base class "${baseClass}" while extending. Extension should not require modifying the base.`,
+    severity,
+  };
+}
+
 export const ocpRule: Rule = {
   id: 'solid.ocp',
   name: 'Open/Closed Principle Rule',
   threshold: 0,
   severity: 'info',
   check: (file: string, adapter: import('../../types').Adapter): Violation[] => {
-    const violations: Violation[] = [];
     // Read the ACTIVE config per invocation; a module-load snapshot was #457.
     const settings = getActiveConfig().rules['solid']['ocp'];
-    const severity = (settings.severity as "error" | "warning" | "info") ?? 'info';
-    
-    const classes = adapter.extractClasses() || [];
-    
-    for (const raw of classes) {
+    const severity = (settings.severity as 'error' | 'warning' | 'info') ?? 'info';
+
+    const violations: Violation[] = [];
+    for (const raw of adapter.extractClasses() || []) {
       const cls = raw as { code?: string; line?: number; name?: string };
       if (!cls.code) continue;
-      
-      const extendsMatch = cls.code.match(/extends\s+(\w+)/);
-      if (extendsMatch) {
-        const baseClass = extendsMatch[1];
-        
-        if (cls.code.includes(`class ${baseClass}`)) {
-          violations.push({
-            file,
-            line: cls.line ?? 1,
-            ruleId: 'solid.ocp',
-            message: `Possible modification of base class "${baseClass}" while extending. Extension should not require modifying the base.`,
-            severity: severity
-          });
-        }
-      }
+      const found = ocpViolation(cls.code, cls.name, cls.line ?? 1, file, severity);
+      if (found) violations.push(found);
     }
-    
     return violations;
   }
-};
+};

package/principles/rules/solid/srp.ts

@@ -1,41 +1,83 @@
 import { Rule, Violation } from '../../types';
 import { getActiveConfig } from '../../config';
 
+/** The shape the adapter hands us for one class. */
+interface RawClass {
+  code?: string;
+  line?: number;
+  name?: string;
+  methodCount?: number;
+  imports?: Record<string, unknown>;
+}
+
+/** A class, normalized for the checks below. */
+interface ClassFacts {
+  name: string | undefined;
+  line: number;
+  methodCount: number;
+  importCategories: number;
+}
+
+/** Read the (optional) fields of a raw class once, with sane defaults. */
+function readClass(raw: unknown): ClassFacts {
+  const cls = raw as RawClass;
+  return {
+    name: cls.name,
+    line: cls.line ?? 1,
+    methodCount: cls.methodCount || 0,
+    importCategories: cls.imports ? Object.keys(cls.imports).length : 0,
+  };
+}
+
+/** Too many methods in one class. */
+function methodViolation(
+  facts: ClassFacts, file: string, maxMethods: number, severity: 'error' | 'warning' | 'info',
+): Violation | null {
+  if (facts.methodCount <= maxMethods) return null;
+  return {
+    file,
+    line: facts.line,
+    ruleId: 'solid.srp',
+    severity,
+    message: `Class "${facts.name}" has too many methods: ${facts.methodCount} (maximum: ${maxMethods}). Consider splitting into focused classes.`,
+  };
+}
+
+/** Imports reaching across too many domains. */
+function importViolation(
+  facts: ClassFacts, file: string, severity: 'error' | 'warning' | 'info',
+): Violation | null {
+  if (facts.importCategories <= 3) return null;
+  return {
+    file,
+    line: facts.line,
+    ruleId: 'solid.srp',
+    severity,
+    message: `Class "${facts.name}" imports from ${facts.importCategories} different domains. Each class should focus on one responsibility.`,
+  };
+}
+
 export const srpRule: Rule = {
   id: 'solid.srp',
   name: 'Single Responsibility Principle Rule',
   threshold: 15,
   severity: 'warning',
   check: (file: string, adapter: import('../../types').Adapter): Violation[] => {
-    const violations: Violation[] = [];
     // Read the ACTIVE config per invocation; a module-load snapshot was #457.
     const settings = getActiveConfig().rules['solid']['srp'];
-
-    const classes = adapter.extractClasses() || [];
     const maxMethods = settings.methodThreshold as number;
     const sev = (settings.severity as 'error' | 'warning' | 'info') ?? 'warning';
 
-    for (const raw of classes) {
-      const cls = raw as { code?: string; line?: number; name?: string; methodCount?: number; imports?: Record<string, unknown> };
-      const methodCount = cls.methodCount || 0;
-      const importCategories = cls.imports ? Object.keys(cls.imports).length : 0;
-      const line = cls.line ?? 1;
-
-      if (methodCount > maxMethods) {
-        violations.push({
-          file, line, ruleId: 'solid.srp', severity: sev,
-          message: `Class "${cls.name}" has too many methods: ${methodCount} (maximum: ${maxMethods}). Consider splitting into focused classes.`,
-        });
-      }
-
-      if (importCategories > 3) {
-        violations.push({
-          file, line, ruleId: 'solid.srp', severity: sev,
-          message: `Class "${cls.name}" imports from ${importCategories} different domains. Each class should focus on one responsibility.`,
-        });
+    const violations: Violation[] = [];
+    for (const raw of adapter.extractClasses() || []) {
+      const facts = readClass(raw);
+      for (const found of [
+        methodViolation(facts, file, maxMethods, sev),
+        importViolation(facts, file, sev),
+      ]) {
+        if (found) violations.push(found);
       }
     }
-
     return violations;
   },
-};
+};

package/scripts/delphi-external-review.cjs

@@ -152,8 +152,8 @@ function readConfig(configPath, profileOverride) {
     // pins ~/.config/xp-gate — overriding only this loader would make the two
     // disagree. On Linux, $HOME/.config IS the XDG default, so behaviour there
     // is identical; the env var only matters for non-default setups.
-    const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-    const globalPath = path.join(configHome, 'xp-gate', '.delphi-config.json');
+    // Extracted so all three resolution points share one definition (REQ-636).
+    const globalPath = globalConfigPath(process.env);
     if (fs.existsSync(globalPath)) {
       console.error(`[delphi-review] ${configPath} not found here — using global config ${globalPath}`);
       configPath = globalPath;
@@ -958,6 +958,7 @@ if (require.main !== module) {
   module.exports = {
     parseArgs,
     readConfig,
+    globalConfigPath,
     validateDistinctModels,
     extractJsonFromResponse,
     buildSystemPrompt,
@@ -985,3 +986,25 @@ if (require.main !== module) {
     process.exit(1);
   });
 }
+
+/**
+ * Machine-wide `.delphi-config.json` path: `$XDG_CONFIG_HOME/xp-gate/`, or
+ * `~/.config/xp-gate/` when the variable is unset.
+ *
+ * Exported so the path-parity test can hold this loader, the Gate MW validator
+ * and the DSH plugin to one definition instead of three restatements.
+ *
+ * Deliberately declared at the END of the file. Function declarations hoist, so
+ * readConfig above can call it, but placing it here keeps every line before the
+ * old EOF byte-identical — which matters because `.ccn-baseline.json` anchors
+ * anonymous functions by line number (`file::(anonymous)@657`). Adding these
+ * lines near the top shifted that anchor to 676 and Gate 3 then read a
+ * pre-existing CCN=24 function as a brand-new violation.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+function globalConfigPath(env) {
+  const configHome = env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(configHome, 'xp-gate', '.delphi-config.json');
+}