octocode-cli 1.2.8 → 1.2.9

package/skills/{octocode-code-engineer → octocode-engineer}/src/pipeline/cli.ts

@@ -1,8 +1,9 @@
 import path from 'node:path';
 
 import { ALL_CATEGORIES, DEFAULT_OPTS, PILLAR_CATEGORIES } from '../types/index.js';
+import { OptionsError, resolveExcludeToFeatures } from './create-options.js';
 
-import type { AnalysisOptions } from '../types/index.js';
+import type { AnalysisOptions, Thresholds } from '../types/index.js';
 
 function parseNumeric(raw: string | undefined, fallback: number): number {
   const n = parseInt(raw ?? '', 10);
@@ -14,6 +15,24 @@ function parseDecimal(raw: string | undefined, fallback: number): number {
   return Number.isNaN(n) ? fallback : n;
 }
 
+function setIntOpt(
+  target: Record<string, number>,
+  key: string,
+  raw: string,
+  defaults: Record<string, number>
+): void {
+  target[key] = parseNumeric(raw, defaults[key]);
+}
+
+function setFloatOpt(
+  target: Record<string, number>,
+  key: string,
+  raw: string,
+  defaults: Record<string, number>
+): void {
+  target[key] = parseDecimal(raw, defaults[key]);
+}
+
 function resolveCategories(val: string, flagName: string): Set<string> {
   const tokens = val
     .split(',')
@@ -39,22 +58,35 @@ function parseScope(
   val: string,
   root: string
 ): { paths: string[]; symbols: Map<string, string[]> } {
+  const splitScopeToken = (
+    token: string
+  ): { filePath: string; symbolName: string | null } => {
+    const colonIdx = token.lastIndexOf(':');
+    if (colonIdx <= 0 || colonIdx === token.length - 1) {
+      return { filePath: token, symbolName: null };
+    }
+    const symbolName = token.substring(colonIdx + 1);
+    if (symbolName.includes('/') || symbolName.includes('\\')) {
+      return { filePath: token, symbolName: null };
+    }
+    return {
+      filePath: token.substring(0, colonIdx),
+      symbolName,
+    };
+  };
+
   const paths: string[] = [];
   const symbols = new Map<string, string[]>();
   for (const token of val
     .split(',')
     .map(s => s.trim())
     .filter(Boolean)) {
-    const colonIdx = token.lastIndexOf(':');
-    if (colonIdx > 0 && !token.substring(0, colonIdx).includes(':')) {
-      const filePart = token.substring(0, colonIdx);
-      const symbolPart = token.substring(colonIdx + 1);
-      const absFile = path.resolve(root, filePart);
-      paths.push(absFile);
+    const { filePath, symbolName } = splitScopeToken(token);
+    const absFile = path.resolve(root, filePath);
+    paths.push(absFile);
+    if (symbolName) {
       if (!symbols.has(absFile)) symbols.set(absFile, []);
-      symbols.get(absFile)!.push(symbolPart);
-    } else {
-      paths.push(path.resolve(root, token));
+      symbols.get(absFile)!.push(symbolName);
     }
   }
   return { paths, symbols };
@@ -103,15 +135,23 @@ const BOOL_FLAGS: Record<
     o.includeTests = true;
     o.semantic = true;
   },
+  '--save-baseline': o => {
+    o.saveBaseline = true;
+  },
 };
 
-const INT_FLAGS: Record<string, keyof AnalysisOptions> = {
+const CORE_INT_FLAGS: Record<string, keyof AnalysisOptions> = {
   '--findings-limit': 'findingsLimit',
+  '--deep-link-topn': 'deepLinkTopN',
+  '--tree-depth': 'treeDepth',
+  '--max-recs-per-category': 'maxRecsPerCategory',
+  '--focus-depth': 'focusDepth',
+};
+
+const THRESHOLD_INT_FLAGS: Record<string, keyof Thresholds> = {
   '--min-function-statements': 'minFunctionStatements',
   '--min-flow-statements': 'minFlowStatements',
   '--critical-complexity-threshold': 'criticalComplexityThreshold',
-  '--deep-link-topn': 'deepLinkTopN',
-  '--tree-depth': 'treeDepth',
   '--coupling-threshold': 'couplingThreshold',
   '--fan-in-threshold': 'fanInThreshold',
   '--fan-out-threshold': 'fanOutThreshold',
@@ -126,14 +166,17 @@ const INT_FLAGS: Record<string, keyof AnalysisOptions> = {
   '--maintainability-index-threshold': 'maintainabilityIndexThreshold',
   '--any-threshold': 'anyThreshold',
   '--flow-dup-threshold': 'flowDupThreshold',
-  '--max-recs-per-category': 'maxRecsPerCategory',
   '--override-chain-threshold': 'overrideChainThreshold',
   '--shotgun-threshold': 'shotgunThreshold',
   '--secret-min-length': 'secretMinLength',
   '--mock-threshold': 'mockThreshold',
+  '--deep-nesting-threshold': 'deepNestingThreshold',
+  '--multiple-return-threshold': 'multipleReturnThreshold',
+  '--magic-string-min-occurrences': 'magicStringMinOccurrences',
+  '--boolean-param-threshold': 'booleanParamThreshold',
 };
 
-const FLOAT_FLAGS: Record<string, keyof AnalysisOptions> = {
+const THRESHOLD_FLOAT_FLAGS: Record<string, keyof Thresholds> = {
   '--secret-entropy-threshold': 'secretEntropyThreshold',
   '--similarity-threshold': 'similarityThreshold',
   '--sdp-min-delta': 'sdpMinDelta',
@@ -161,7 +204,20 @@ const SPECIAL_FLAGS: Record<string, FlagHandler> = {
     return i + 1;
   },
   '--layer-order': (opts, argv, i) => {
-    opts.layerOrder = argv[i + 1].split(',').map(s => s.trim());
+    opts.thresholds.layerOrder = argv[i + 1].split(',').map(s => s.trim());
+    return i + 1;
+  },
+  '--reporter': (opts, argv, i) => {
+    const next = argv[i + 1];
+    if (!['default', 'compact', 'github-actions'].includes(next)) {
+      console.error(`Unsupported reporter: ${next}. Use default|compact|github-actions`);
+      process.exit(1);
+    }
+    opts.reporter = next as AnalysisOptions['reporter'];
+    return i + 1;
+  },
+  '--config': (opts, argv, i) => {
+    opts.configFile = argv[i + 1];
     return i + 1;
   },
   '--help': () => {
@@ -175,7 +231,7 @@ const SPECIAL_FLAGS: Record<string, FlagHandler> = {
 };
 
 export function parseArgs(argv: string[]): AnalysisOptions {
-  const opts: AnalysisOptions = { ...DEFAULT_OPTS };
+  const opts: AnalysisOptions = { ...DEFAULT_OPTS, thresholds: { ...DEFAULT_OPTS.thresholds } };
   let excludeSet: Set<string> | null = null;
 
   for (let i = 0; i < argv.length; i++) {
@@ -186,17 +242,33 @@ export function parseArgs(argv: string[]): AnalysisOptions {
       continue;
     }
 
-    if (INT_FLAGS[arg]) {
-      const key = INT_FLAGS[arg];
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      (opts as any)[key] = parseNumeric(argv[++i], (DEFAULT_OPTS as any)[key]);
+    if (CORE_INT_FLAGS[arg]) {
+      const key = CORE_INT_FLAGS[arg];
+      setIntOpt(
+        opts as unknown as Record<string, number>,
+        key, argv[++i],
+        DEFAULT_OPTS as unknown as Record<string, number>
+      );
+      continue;
+    }
+
+    if (THRESHOLD_INT_FLAGS[arg]) {
+      const key = THRESHOLD_INT_FLAGS[arg];
+      setIntOpt(
+        opts.thresholds as unknown as Record<string, number>,
+        key, argv[++i],
+        DEFAULT_OPTS.thresholds as unknown as Record<string, number>
+      );
       continue;
     }
 
-    if (FLOAT_FLAGS[arg]) {
-      const key = FLOAT_FLAGS[arg];
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      (opts as any)[key] = parseDecimal(argv[++i], (DEFAULT_OPTS as any)[key]);
+    if (THRESHOLD_FLOAT_FLAGS[arg]) {
+      const key = THRESHOLD_FLOAT_FLAGS[arg];
+      setFloatOpt(
+        opts.thresholds as unknown as Record<string, number>,
+        key, argv[++i],
+        DEFAULT_OPTS.thresholds as unknown as Record<string, number>
+      );
       continue;
     }
 
@@ -211,7 +283,9 @@ export function parseArgs(argv: string[]): AnalysisOptions {
     }
 
     if (arg === '--scope' || arg.startsWith('--scope=')) {
-      const val = arg.includes('=') ? arg.split('=')[1] : argv[++i];
+      const val = arg.startsWith('--scope=')
+        ? arg.slice('--scope='.length)
+        : argv[++i];
       const { paths, symbols } = parseScope(val, opts.root);
       opts.scope = paths;
       if (symbols.size > 0) opts.scopeSymbols = symbols;
@@ -233,20 +307,58 @@ export function parseArgs(argv: string[]): AnalysisOptions {
       excludeSet = resolveCategories(val, 'exclude');
       continue;
     }
+
+    if (arg === '--affected' || arg.startsWith('--affected=')) {
+      opts.affected = arg.startsWith('--affected=')
+        ? arg.slice('--affected='.length)
+        : (argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : 'HEAD');
+      continue;
+    }
+
+    if (arg === '--ignore-known' || arg.startsWith('--ignore-known=')) {
+      opts.ignoreKnown = arg.startsWith('--ignore-known=')
+        ? arg.slice('--ignore-known='.length)
+        : (argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : '.octocode/baseline.json');
+      continue;
+    }
+
+    if (arg === '--focus' || arg.startsWith('--focus=')) {
+      opts.focus = arg.startsWith('--focus=')
+        ? arg.slice('--focus='.length)
+        : argv[++i];
+      continue;
+    }
+
+    if (arg === '--collapse' || arg.startsWith('--collapse=')) {
+      const val = arg.startsWith('--collapse=')
+        ? arg.slice('--collapse='.length)
+        : argv[++i];
+      opts.collapse = parseNumeric(val, 2);
+      continue;
+    }
+
+    if (arg === '--at-least' || arg.startsWith('--at-least=')) {
+      const val = arg.startsWith('--at-least=')
+        ? arg.slice('--at-least='.length)
+        : argv[++i];
+      opts.atLeast = parseNumeric(val, 0);
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      console.warn(`Warning: unknown flag "${arg}" — ignored.`);
+    }
   }
 
   opts.packageRoot = path.join(opts.root, 'packages');
 
   if (opts.features !== null && excludeSet !== null) {
-    console.error(
+    throw new OptionsError(
       '--features and --exclude are mutually exclusive. Use one or the other.'
     );
-    process.exit(1);
   }
   if (excludeSet !== null) {
-    opts.features = new Set(
-      [...ALL_CATEGORIES].filter(c => !excludeSet!.has(c))
-    );
+    opts.features = resolveExcludeToFeatures(excludeSet);
   }
 
   if (opts.features !== null) {
@@ -259,10 +371,9 @@ export function parseArgs(argv: string[]): AnalysisOptions {
   return opts;
 }
 
-export function printHelp(): void {
-  console.log(`
+export const HELP_TEXT = `
 Usage:
-  node scripts/index.js [options]
+  node scripts/run.js [options]
 
 Options:
   --root <path>                 Analyze a different repo root (default: cwd)
@@ -320,7 +431,7 @@ Options:
                                 Examples: --exclude=architecture
                                           --exclude=dead-export,unsafe-any
   --semantic                    Enable semantic analysis phase (TypeChecker + LanguageService).
-                                Adds 14 categories: over-abstraction, concrete-dependency,
+                                Adds 12 categories: over-abstraction, concrete-dependency,
                                 circular-type-dependency, unused-parameter,
                                 deep-override-chain, interface-compliance, unused-import,
                                 orphan-implementation, shotgun-surgery, move-to-caller,
@@ -332,6 +443,11 @@ Options:
   --secret-entropy-threshold N  Shannon entropy threshold for secret detection (default 4.5)
   --secret-min-length N         Min string length for entropy-based secret detection (default 20)
   --similarity-threshold N      Jaccard similarity threshold for near-clone detection (default 0.85)
+  --deep-nesting-threshold N    Max branch/loop nesting depth before flagging (default 5)
+  --multiple-return-threshold N Max return/throw paths per function before flagging (default 6)
+  --magic-string-min-occurrences N
+                                Min repeated string comparisons to flag as magic string (default 3)
+  --boolean-param-threshold N   Min boolean params per function to flag as cluster (default 3)
   --mock-threshold N            Max mock/spy calls per test file (default 10)
   --no-diversify                Disable category-aware diversification when truncating findings.
                                 By default, --findings-limit interleaves categories so the
@@ -339,6 +455,34 @@ Options:
   --no-cache                    Disable incremental cache; re-parse all files
   --clear-cache                 Delete the analysis cache and exit (no scan)
   --all                         Enable all features: --include-tests --semantic
+
+  --affected [revision]         Scope to files changed since git revision (default: HEAD) plus
+                                their transitive dependents. Like dep-cruiser's --affected flag.
+                                Examples: --affected
+                                          --affected HEAD~3
+                                          --affected main
+  --save-baseline               Save current findings to .octocode/baseline.json for future
+                                comparison. Use with --ignore-known for progressive adoption.
+  --ignore-known [file]         Suppress findings matching a baseline file (default:
+                                .octocode/baseline.json). Findings are matched by (category, file).
+  --reporter <format>           Output format: default|compact|github-actions (default: default)
+                                compact: one-line per finding for terminal/CI logs
+                                github-actions: ::warning annotations for GitHub Actions
+  --focus <module>              Show only this module and its neighbors in the dependency graph.
+                                Requires --graph. Use with --focus-depth to control neighbor hops.
+                                Examples: --focus src/session.ts
+                                          --focus=src/session.ts
+                                          --focus packages/octocode-mcp/src/tools
+  --focus-depth N               Neighbor depth for --focus (default 1). 2 = friends-of-friends.
+  --collapse N                  Collapse graph nodes to folder depth N. Reduces large graphs to
+                                high-level architecture view. Example: --collapse 2
+  --at-least N                  Fail (exit 1) if health score drops below N (0-100). Use in CI
+                                to enforce a quality floor. Example: --at-least 60
+  --config <file>               Path to config file. Also auto-discovers .octocode-scan.json,
+                                .octocode-scan.jsonc, or package.json#octocode in the project root.
   --help                        Show this message
-`);
+`;
+
+export function printHelp(): void {
+  console.log(HELP_TEXT);
 }

package/skills/octocode-engineer/src/pipeline/config-loader.test.ts

@@ -0,0 +1,264 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { loadConfigFile, mergeConfigIntoDefaults } from './config-loader.js';
+import { DEFAULT_OPTS } from '../types/index.js';
+
+describe('config-loader', () => {
+  const tmpDirs: string[] = [];
+
+  function makeTmpDir(): string {
+    const d = fs.mkdtempSync(path.join(os.tmpdir(), 'config-test-'));
+    tmpDirs.push(d);
+    return d;
+  }
+
+  afterEach(() => {
+    for (const d of tmpDirs) {
+      fs.rmSync(d, { recursive: true, force: true });
+    }
+    tmpDirs.length = 0;
+  });
+
+  describe('loadConfigFile', () => {
+    it('loads explicit config file', () => {
+      const root = makeTmpDir();
+      const cfgPath = path.join(root, 'my-config.json');
+      fs.writeFileSync(cfgPath, JSON.stringify({ graph: true, semantic: true }));
+
+      const config = loadConfigFile(root, cfgPath);
+      expect(config).toBeDefined();
+      expect(config!.graph).toBe(true);
+      expect(config!.semantic).toBe(true);
+    });
+
+    it('auto-discovers .octocode-scan.json', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.json'),
+        JSON.stringify({ flow: true })
+      );
+
+      const config = loadConfigFile(root, null);
+      expect(config).toBeDefined();
+      expect(config!.flow).toBe(true);
+    });
+
+    it('auto-discovers .octocode-scan.jsonc', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.jsonc'),
+        '// comment\n{ "graph": true }\n'
+      );
+
+      const config = loadConfigFile(root, null);
+      expect(config).toBeDefined();
+      expect(config!.graph).toBe(true);
+    });
+
+    it('reads from package.json#octocode', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, 'package.json'),
+        JSON.stringify({ name: 'test', octocode: { includeTests: true } })
+      );
+
+      const config = loadConfigFile(root, null);
+      expect(config).toBeDefined();
+      expect(config!.includeTests).toBe(true);
+    });
+
+    it('returns null when no config found', () => {
+      const root = makeTmpDir();
+      expect(loadConfigFile(root, null)).toBeNull();
+    });
+
+    it('converts kebab-case keys to camelCase', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.json'),
+        JSON.stringify({ 'include-tests': true, 'graph-advanced': true })
+      );
+
+      const config = loadConfigFile(root, null);
+      expect(config!.includeTests).toBe(true);
+      expect(config!.graphAdvanced).toBe(true);
+    });
+
+    it('prefers .octocode-scan.json over package.json', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.json'),
+        JSON.stringify({ graph: true })
+      );
+      fs.writeFileSync(
+        path.join(root, 'package.json'),
+        JSON.stringify({ name: 'x', octocode: { graph: false, flow: true } })
+      );
+
+      const config = loadConfigFile(root, null);
+      expect(config!.graph).toBe(true);
+      expect(config!.flow).toBeUndefined();
+    });
+
+    it('converts features string to Set', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.json'),
+        JSON.stringify({ features: 'architecture, dead-code' })
+      );
+
+      const config = loadConfigFile(root, null);
+      expect(config!.features).toBeInstanceOf(Set);
+      expect((config!.features as Set<string>).has('architecture')).toBe(true);
+      expect((config!.features as Set<string>).has('dead-code')).toBe(true);
+    });
+
+    it('converts scope string to array', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.json'),
+        JSON.stringify({ scope: 'packages/foo,packages/bar' })
+      );
+
+      const config = loadConfigFile(root, null);
+      expect(config!.scope).toEqual(['packages/foo', 'packages/bar']);
+    });
+
+    it('converts ignoreDirs array to Set', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.json'),
+        JSON.stringify({ 'ignore-dirs': ['vendor', 'generated'] })
+      );
+
+      const config = loadConfigFile(root, null);
+      const dirs = config!.ignoreDirs as Set<string>;
+      expect(dirs).toBeInstanceOf(Set);
+      expect(dirs.has('vendor')).toBe(true);
+      expect(dirs.has('generated')).toBe(true);
+    });
+
+    it('returns null for invalid JSON', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.json'),
+        'not { valid json !!!'
+      );
+      expect(loadConfigFile(root, null)).toBeNull();
+    });
+
+    it('resolves relative explicit path against root', () => {
+      const root = makeTmpDir();
+      const cfgPath = path.join(root, 'configs', 'scan.json');
+      fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+      fs.writeFileSync(cfgPath, JSON.stringify({ semantic: true }));
+
+      const config = loadConfigFile(root, 'configs/scan.json');
+      expect(config).toBeDefined();
+      expect(config!.semantic).toBe(true);
+    });
+
+    it('strips single-line comments in JSONC', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.json'),
+        `{
+  // Enable graph
+  "graph": true,
+  "flow": false // Not yet
+}`
+      );
+      const config = loadConfigFile(root, null);
+      expect(config!.graph).toBe(true);
+      expect(config!.flow).toBe(false);
+    });
+
+    it('strips block comments in JSONC', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.json'),
+        `{
+  /* This enables the semantic phase */
+  "semantic": true
+}`
+      );
+      const config = loadConfigFile(root, null);
+      expect(config!.semantic).toBe(true);
+    });
+
+    it('passes through threshold objects', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, '.octocode-scan.json'),
+        JSON.stringify({ thresholds: { minFunctionStatements: 10 } })
+      );
+
+      const config = loadConfigFile(root, null);
+      const t = config!.thresholds as Record<string, number>;
+      expect(t.minFunctionStatements).toBe(10);
+    });
+
+    it('ignores package.json without octocode key', () => {
+      const root = makeTmpDir();
+      fs.writeFileSync(
+        path.join(root, 'package.json'),
+        JSON.stringify({ name: 'test', version: '1.0.0' })
+      );
+      expect(loadConfigFile(root, null)).toBeNull();
+    });
+  });
+
+  describe('mergeConfigIntoDefaults', () => {
+    it('config values override defaults', () => {
+      const config = { graph: true, semantic: true };
+      const cliArgs = { ...DEFAULT_OPTS };
+
+      const result = mergeConfigIntoDefaults(DEFAULT_OPTS, config, cliArgs);
+      expect(result.graph).toBe(true);
+      expect(result.semantic).toBe(true);
+    });
+
+    it('CLI args override config when they differ from defaults', () => {
+      const config = { graph: true, semantic: true };
+      const cliArgs = { ...DEFAULT_OPTS, findingsLimit: 50 };
+
+      const result = mergeConfigIntoDefaults(DEFAULT_OPTS, config, cliArgs);
+      expect(result.graph).toBe(true);
+      expect(result.semantic).toBe(true);
+      expect(result.findingsLimit).toBe(50);
+    });
+
+    it('merges threshold overrides', () => {
+      const config = { thresholds: { minFunctionStatements: 10 } };
+      const cliArgs = { ...DEFAULT_OPTS };
+
+      const result = mergeConfigIntoDefaults(DEFAULT_OPTS, config, cliArgs);
+      expect(result.thresholds.minFunctionStatements).toBe(10);
+      expect(result.thresholds.minFlowStatements).toBe(
+        DEFAULT_OPTS.thresholds.minFlowStatements
+      );
+    });
+
+    it('preserves defaults when config and CLI are empty', () => {
+      const result = mergeConfigIntoDefaults(
+        DEFAULT_OPTS,
+        {},
+        { ...DEFAULT_OPTS }
+      );
+      expect(result).toEqual(DEFAULT_OPTS);
+    });
+
+    it('config does not override root or packageRoot', () => {
+      const config = { json: true };
+      const cliArgs = { ...DEFAULT_OPTS };
+
+      const result = mergeConfigIntoDefaults(DEFAULT_OPTS, config, cliArgs);
+      expect(result.root).toBe(DEFAULT_OPTS.root);
+      expect(result.json).toBe(true);
+    });
+  });
+});