octocode-cli 1.2.7 → 1.2.9

package/skills/{octocode-code-engineer → octocode-engineer}/src/reporting/writer.ts

@@ -8,6 +8,8 @@ import {
 } from './analysis.js';
 import {
   categoryBreakdown,
+  computeFeatureScores,
+  computeQualityAspectRatings,
   generateSummaryMd,
   severityBreakdown,
 } from './summary-md.js';
@@ -17,6 +19,7 @@ import { computeHotFiles } from '../detectors/index.js';
 import { PILLAR_CATEGORIES } from '../types/index.js';
 
 import type {
+  AgentOutputData,
   AnalysisOptions,
   DependencyState,
   DependencySummary,
@@ -24,6 +27,7 @@ import type {
   FileCriticality,
   FileEntry,
   Finding,
+  ScanSummaryData,
   TreeEntry,
 } from '../types/index.js';
 
@@ -46,12 +50,12 @@ export interface FullReport {
   repoRoot: string;
   options: Record<string, unknown>;
   parser: Record<string, unknown>;
-  summary: Record<string, unknown>;
+  summary: ScanSummaryData;
   fileInventory: FileEntry[];
   duplicateFlows: Record<string, unknown>;
   dependencyGraph: DependencySummary;
   dependencyFindings: Finding[];
-  agentOutput: Record<string, unknown>;
+  agentOutput: AgentOutputData;
   optimizationOpportunities: DuplicateFlowHint[];
   optimizationFindings: Finding[];
   parseErrors: { file: string; message: string }[];
@@ -66,7 +70,8 @@ export function writeMultiFileReport(
   options: AnalysisOptions,
   dependencyState: DependencyState,
   dependencySummary: DependencySummary,
-  fileCriticalityByPath: Map<string, FileCriticality>
+  fileCriticalityByPath: Map<string, FileCriticality>,
+  graphOpts: GraphRenderOptions = {}
 ): Record<string, string> {
   fs.mkdirSync(dir, { recursive: true });
 
@@ -129,6 +134,12 @@ export function writeMultiFileReport(
       hotFiles,
       graphAnalytics
     );
+  const qualityRating = computeQualityAspectRatings(allFindings, {
+    fileInventory: enrichedFileInventory,
+    hotFiles,
+    reportAnalysis,
+    includeTests: options.includeTests,
+  });
 
   writeJson('architecture.json', {
     schemaVersion: REPORT_SCHEMA_VERSION,
@@ -214,7 +225,8 @@ export function writeMultiFileReport(
     const graphMd = generateMermaidGraph(
       dependencyState,
       dependencySummary,
-      fileCriticalityByPath
+      fileCriticalityByPath,
+      graphOpts
     );
     fs.writeFileSync(path.join(dir, 'graph.md'), graphMd, 'utf8');
     outputFiles.graph = 'graph.md';
@@ -248,6 +260,13 @@ export function writeMultiFileReport(
     strongestGraphSignal: reportAnalysis.strongestGraphSignal,
     strongestAstSignal: reportAnalysis.strongestAstSignal,
     combinedSignals: reportAnalysis.combinedSignals,
+    featureScores: computeFeatureScores(
+      allFindings,
+      report.summary.totalFiles ?? 0,
+      options.features,
+      { hotFiles }
+    ),
+    qualityRating,
     recommendedValidation: reportAnalysis.recommendedValidation,
     investigationPrompts: reportAnalysis.investigationPrompts,
     parseErrors: report.parseErrors,
@@ -271,6 +290,7 @@ export function writeMultiFileReport(
     securityFindings,
     testQualityFindings,
     reportAnalysis,
+    fileInventory: enrichedFileInventory,
   });
   fs.writeFileSync(path.join(dir, 'summary.md'), summaryMd, 'utf8');
   outputFiles.summaryMd = 'summary.md';
@@ -280,10 +300,17 @@ export function writeMultiFileReport(
   return outputFiles;
 }
 
+export interface GraphRenderOptions {
+  focus?: string | null;
+  focusDepth?: number;
+  collapse?: number | null;
+}
+
 export function generateMermaidGraph(
   dependencyState: DependencyState,
   dependencySummary: DependencySummary,
-  _fileCriticalityByPath: Map<string, FileCriticality>
+  _fileCriticalityByPath: Map<string, FileCriticality>,
+  renderOpts: GraphRenderOptions = {}
 ): string {
   const lines: string[] = [];
   lines.push('# Dependency Graph\n');
@@ -310,14 +337,30 @@ export function generateMermaidGraph(
   const renderedNodes = new Set<string>();
   const renderedEdges = new Set<string>();
 
-  const topModules = [
-    ...(dependencySummary.outgoingTop || []).slice(0, 15),
-    ...(dependencySummary.inboundTop || []).slice(0, 15),
-    ...(dependencySummary.criticalModules || []).slice(0, 10),
-  ];
-  const moduleSet = new Set(topModules.map(m => m.file));
-  for (const cycle of (dependencySummary.cycles || []).slice(0, 5)) {
-    for (const f of cycle.path) moduleSet.add(f);
+  let moduleSet: Set<string>;
+
+  if (renderOpts.focus) {
+    moduleSet = collectFocusNeighborhood(
+      renderOpts.focus,
+      renderOpts.focusDepth ?? 1,
+      dependencyState
+    );
+    lines.push(`%% Focus: ${renderOpts.focus} (depth=${renderOpts.focusDepth ?? 1})`);
+  } else {
+    const topModules = [
+      ...(dependencySummary.outgoingTop || []).slice(0, 15),
+      ...(dependencySummary.inboundTop || []).slice(0, 15),
+      ...(dependencySummary.criticalModules || []).slice(0, 10),
+    ];
+    moduleSet = new Set(topModules.map(m => m.file));
+    for (const cycle of (dependencySummary.cycles || []).slice(0, 5)) {
+      for (const f of cycle.path) moduleSet.add(f);
+    }
+  }
+
+  if (renderOpts.collapse != null && renderOpts.collapse > 0) {
+    const collapsed = collapseToFolderDepth(moduleSet, dependencyState, renderOpts.collapse);
+    return renderCollapsedGraph(collapsed, lines);
   }
 
   for (const file of moduleSet) {
@@ -428,3 +471,83 @@ export function generateMermaidGraph(
 
   return lines.join('\n');
 }
+
+export function collectFocusNeighborhood(
+  focus: string,
+  depth: number,
+  state: DependencyState
+): Set<string> {
+  const focusKey = [...state.outgoing.keys()].find(
+    k => k === focus || k.endsWith(`/${focus}`)
+  );
+  if (!focusKey) return new Set();
+
+  const result = new Set<string>([focusKey]);
+  let frontier = new Set([focusKey]);
+
+  for (let d = 0; d < depth; d++) {
+    const next = new Set<string>();
+    for (const node of frontier) {
+      for (const neighbor of state.outgoing.get(node) || []) {
+        if (!result.has(neighbor)) { result.add(neighbor); next.add(neighbor); }
+      }
+      for (const neighbor of state.incoming.get(node) || []) {
+        if (!result.has(neighbor)) { result.add(neighbor); next.add(neighbor); }
+      }
+    }
+    frontier = next;
+    if (frontier.size === 0) break;
+  }
+  return result;
+}
+
+interface CollapsedEdge { from: string; to: string; weight: number }
+
+export function collapseToFolderDepth(
+  moduleSet: Set<string>,
+  state: DependencyState,
+  depth: number
+): { nodes: Set<string>; edges: CollapsedEdge[] } {
+  const toFolder = (f: string) => f.split('/').slice(0, depth).join('/');
+  const nodes = new Set<string>();
+  const edgeMap = new Map<string, number>();
+
+  for (const file of moduleSet) nodes.add(toFolder(file));
+
+  for (const file of moduleSet) {
+    const from = toFolder(file);
+    for (const dep of state.outgoing.get(file) || []) {
+      const to = toFolder(dep);
+      if (from === to) continue;
+      nodes.add(to);
+      const key = `${from}::${to}`;
+      edgeMap.set(key, (edgeMap.get(key) || 0) + 1);
+    }
+  }
+
+  const edges: CollapsedEdge[] = [];
+  for (const [key, weight] of edgeMap) {
+    const [from, to] = key.split('::');
+    edges.push({ from, to, weight });
+  }
+
+  return { nodes, edges };
+}
+
+function renderCollapsedGraph(
+  data: { nodes: Set<string>; edges: CollapsedEdge[] },
+  lines: string[]
+): string {
+  const sanitize = (id: string): string => id.replace(/[^a-zA-Z0-9]/g, '_');
+
+  for (const node of data.nodes) {
+    lines.push(`  ${sanitize(node)}["${node}"]`);
+  }
+  for (const edge of data.edges) {
+    const label = edge.weight > 1 ? `|${edge.weight}|` : '';
+    lines.push(`  ${sanitize(edge.from)} -->${label} ${sanitize(edge.to)}`);
+  }
+  lines.push('```\n');
+  lines.push(`> Collapsed to folder depth. ${data.nodes.size} folders, ${data.edges.length} edges.\n`);
+  return lines.join('\n');
+}

package/skills/octocode-engineer/src/run.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Bootstrap entry point for the octocode-code-engineer skill.
+ * Ensures npm dependencies are installed before loading the scanner,
+ * which requires native addons (tree-sitter, @ast-grep/napi) and
+ * pure-JS packages (typescript) that cannot be bundled.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+// When compiled, this file lives at <skill>/scripts/run.js
+// Go up one level from scripts/ to reach the skill root
+const skillDir = dirname(dirname(__filename));
+const nodeModulesDir = join(skillDir, 'node_modules');
+const require = createRequire(import.meta.url);
+
+const REQUIRED_PACKAGES = [
+  'typescript',
+  '@ast-grep/napi',
+  'tree-sitter',
+  'tree-sitter-typescript',
+];
+
+function isDependencyAvailable(pkgName: string): boolean {
+  if (existsSync(join(nodeModulesDir, pkgName))) {
+    return true;
+  }
+
+  try {
+    require.resolve(pkgName, { paths: [skillDir] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const missingPackages = REQUIRED_PACKAGES.filter(pkg => !isDependencyAvailable(pkg));
+
+if (missingPackages.length > 0) {
+  process.stderr.write(
+    `[octocode-scan] Missing dependencies (${missingPackages.join(', ')}). Installing...\n`
+  );
+  const result = spawnSync(
+    'npm',
+    ['install', '--prefix', skillDir, '--no-audit', '--no-fund'],
+    {
+      stdio: 'inherit',
+      shell: false,
+    }
+  );
+  if (result.status !== 0) {
+    process.stderr.write(
+      `[octocode-scan] Failed to install dependencies.\n` +
+      `Run manually: cd ${skillDir} && npm install\n`
+    );
+    process.exit(1);
+  }
+  process.stderr.write('[octocode-scan] Dependencies installed.\n');
+}
+
+// Dependencies are now available — load and run the main scanner
+const { main, EXIT_ERROR } = await import('./pipeline/main.js');
+const { OptionsError } = await import('./pipeline/create-options.js');
+try {
+  const exitCode = await main();
+  process.exitCode = exitCode;
+} catch (err: unknown) {
+  if (err instanceof OptionsError) {
+    process.stderr.write(`${err.message}\n`);
+  } else {
+    console.error(err);
+  }
+  process.exitCode = EXIT_ERROR;
+}

package/skills/{octocode-code-engineer → octocode-engineer}/src/sanity.test.ts

@@ -32,7 +32,7 @@ describe('sanity checks', () => {
     expect(parsed.json).toBe(true);
     expect(parsed.includeTests).toBe(true);
     expect(parsed.parser).toBe('typescript');
-    expect(parsed.minFunctionStatements).toBe(10);
+    expect(parsed.thresholds.minFunctionStatements).toBe(10);
     expect(parsed.findingsLimit).toBe(120);
     expect(parsed.packageRoot).toMatch(/packages$/);
   });

package/skills/octocode-engineer/src/types/analysis.ts

@@ -0,0 +1,25 @@
+export type AnalysisLens = 'graph' | 'ast' | 'hybrid';
+
+export interface RecommendedValidation {
+  summary: string;
+  tools: string[];
+}
+
+export interface FlowTraceStep {
+  file: string;
+  lineStart: number;
+  lineEnd: number;
+  label: string;
+}
+
+export interface AnalysisSignal {
+  kind: string;
+  lens: AnalysisLens;
+  title: string;
+  summary: string;
+  confidence: 'high' | 'medium' | 'low';
+  score: number;
+  files: string[];
+  categories: string[];
+  evidence: Record<string, unknown>;
+}

package/skills/octocode-engineer/src/types/collectors.ts

@@ -0,0 +1,134 @@
+import type { CodeLocation } from './core.js';
+
+export interface SuspiciousString {
+  lineStart: number;
+  lineEnd: number;
+  kind: 'hardcoded-secret' | 'sql-injection' | 'secret-assignment';
+  snippet?: string;
+  context?:
+    | 'literal'
+    | 'regex-definition'
+    | 'template'
+    | 'comment'
+    | 'error-message';
+}
+
+export interface TimerCall {
+  kind: 'setInterval' | 'setTimeout';
+  lineStart: number;
+  lineEnd: number;
+  hasCleanup: boolean;
+}
+
+export interface TestBlock {
+  name: string;
+  lineStart: number;
+  lineEnd: number;
+  assertionCount: number;
+}
+
+export interface FocusedTestCall {
+  kind:
+    | 'it.only'
+    | 'test.only'
+    | 'describe.only'
+    | 'it.skip'
+    | 'test.skip'
+    | 'describe.skip'
+    | 'it.todo'
+    | 'test.todo';
+  lineStart: number;
+  lineEnd: number;
+}
+
+export interface TimerControlCall {
+  kind:
+    | 'jest.useFakeTimers'
+    | 'jest.useRealTimers'
+    | 'vi.useFakeTimers'
+    | 'vi.useRealTimers'
+    | 'other';
+  lineStart: number;
+  lineEnd: number;
+}
+
+export interface MockControlCall extends CodeLocation {
+  kind: 'spy' | 'stub' | 'restore' | 'restoreAll';
+  target?: string;
+}
+
+export interface TestProfile {
+  testBlocks: TestBlock[];
+  mockCalls: CodeLocation[];
+  setupCalls: Array<{
+    kind: 'beforeAll' | 'beforeEach' | 'afterAll' | 'afterEach';
+    lineStart: number;
+  }>;
+  mutableStateDecls: CodeLocation[];
+  focusedCalls: FocusedTestCall[];
+  timerControls: TimerControlCall[];
+  mockRestores: MockControlCall[];
+  spyOrStubCalls: MockControlCall[];
+}
+
+export interface InputSourceInfo {
+  functionName: string;
+  lineStart: number;
+  lineEnd: number;
+  sourceParams: string[];
+  hasSinkInBody: boolean;
+  sinkKinds: string[];
+  hasValidation: boolean;
+  callsWithInputArgs: Array<{ callee: string; lineStart: number }>;
+  paramConfidence: 'high' | 'medium' | 'low';
+}
+
+export type TopLevelEffectKind =
+  | 'sync-io'
+  | 'exec-sync'
+  | 'eval'
+  | 'timer'
+  | 'listener'
+  | 'process-handler'
+  | 'side-effect-import'
+  | 'top-level-await'
+  | 'dynamic-import';
+
+export interface TopLevelEffect {
+  kind: TopLevelEffectKind;
+  lineStart: number;
+  lineEnd: number;
+  detail: string;
+  weight: number;
+  confidence: 'high' | 'medium' | 'low';
+}
+
+export interface EffectProfile {
+  totalEffects: number;
+  totalWeight: number;
+  byKind: Partial<Record<TopLevelEffectKind, number>>;
+  highestRisk: TopLevelEffectKind | null;
+}
+
+export interface SymbolUsageSummary {
+  declaredExportCount: number;
+  importedSymbolCount: number;
+  internalImportCount: number;
+  externalImportCount: number;
+  reExportCount: number;
+  dominantInternalDependency: string | null;
+}
+
+export interface BoundaryRoleHint {
+  role: string;
+  confidence: 'high' | 'medium' | 'low';
+  reasons: string[];
+}
+
+export interface CfgFlags {
+  hasValidationChecks: boolean;
+  hasCleanupHooks: boolean;
+  exitPointCount: number;
+  asyncBoundaryCount: number;
+  hasTopLevelEffects: boolean;
+}

package/skills/{octocode-code-engineer → octocode-engineer}/src/types/constants.ts

@@ -2,67 +2,94 @@ import path from 'node:path';
 
 import * as ts from 'typescript';
 
-import type { AnalysisOptions } from './interfaces.js';
+import type { AnalysisOptions, Thresholds } from './core.js';
 
-export const DEFAULT_OPTS: AnalysisOptions = {
-  minFunctionStatements: 6,
-  minFlowStatements: 6,
-  root: process.cwd(),
-  includeTests: false,
-  emitTree: true,
-  json: false,
-  graph: false,
-  out: null,
-  treeDepth: 4,
-  findingsLimit: Infinity,
-  parser: 'auto',
-  criticalComplexityThreshold: 30,
-  deepLinkTopN: 12,
-  packageRoot: path.join(process.cwd(), 'packages'),
-  ignoreDirs: new Set([
-    '.git',
-    '.next',
-    '.yarn',
-    '.cache',
-    '.octocode',
-    'node_modules',
-    'dist',
-    'coverage',
-    'out',
-  ]),
+export const DEFAULT_THRESHOLDS: Thresholds = {
+  // Architecture
   couplingThreshold: 15,
   fanInThreshold: 20,
   fanOutThreshold: 15,
   godModuleStatements: 500,
   godModuleExports: 20,
+  barrelSymbolThreshold: 30,
+  sdpMinDelta: 0.15,
+  sdpMaxSourceInstability: 0.6,
+  layerOrder: [],
+
+  // Code quality
+  minFunctionStatements: 6,
+  minFlowStatements: 6,
+  criticalComplexityThreshold: 30,
   godFunctionStatements: 100,
   godFunctionMiThreshold: 10,
   cognitiveComplexityThreshold: 15,
-  barrelSymbolThreshold: 30,
-  layerOrder: [],
   parameterThreshold: 5,
   halsteadEffortThreshold: 500_000,
   maintainabilityIndexThreshold: 20,
   anyThreshold: 5,
   flowDupThreshold: 3,
-  maxRecsPerCategory: 2,
-  features: null,
-  scope: null,
-  scopeSymbols: null,
-  noCache: false,
-  clearCache: false,
-  semantic: false,
+  similarityThreshold: 0.85,
+  deepNestingThreshold: 5,
+  multipleReturnThreshold: 6,
+  magicStringMinOccurrences: 3,
+  booleanParamThreshold: 3,
+
+  // Semantic
   overrideChainThreshold: 3,
   shotgunThreshold: 8,
-  sdpMinDelta: 0.15,
-  sdpMaxSourceInstability: 0.6,
+
+  // Security
   secretEntropyThreshold: 4.5,
   secretMinLength: 20,
-  similarityThreshold: 0.85,
+
+  // Test quality
   mockThreshold: 10,
-  noDiversify: false,
+};
+
+export const DEFAULT_OPTS: AnalysisOptions = {
+  root: process.cwd(),
+  out: null,
+  json: false,
+  packageRoot: path.join(process.cwd(), 'packages'),
+  parser: 'auto',
+  includeTests: false,
+  emitTree: true,
+  treeDepth: 4,
+  noCache: false,
+  clearCache: false,
+  semantic: false,
+  graph: false,
   graphAdvanced: false,
   flow: false,
+  scope: null,
+  scopeSymbols: null,
+  features: null,
+  ignoreDirs: new Set([
+    '.git',
+    '.next',
+    '.yarn',
+    '.cache',
+    '.octocode',
+    'node_modules',
+    'dist',
+    'coverage',
+    'out',
+  ]),
+  findingsLimit: Infinity,
+  noDiversify: false,
+  maxRecsPerCategory: 2,
+  deepLinkTopN: 12,
+  thresholds: { ...DEFAULT_THRESHOLDS },
+
+  affected: null,
+  saveBaseline: false,
+  ignoreKnown: null,
+  reporter: 'default',
+  focus: null,
+  focusDepth: 1,
+  collapse: null,
+  atLeast: null,
+  configFile: null,
 };
 
 export const PILLAR_CATEGORIES: Record<string, string[]> = {
@@ -123,6 +150,14 @@ export const PILLAR_CATEGORIES: Record<string, string[]> = {
     'unbounded-collection',
     'similar-function-body',
     'message-chain',
+    'deep-nesting',
+    'multiple-return-paths',
+    'catch-rethrow',
+    'magic-string',
+    'boolean-parameter-cluster',
+    'promise-all-unhandled',
+    'export-surface-density',
+    'change-risk',
   ],
   'dead-code': [
     'dead-export',
@@ -221,7 +256,6 @@ export const TS_TREE_SITTER_CONTROL_TYPES = new Set<string>([
   'for_of_statement',
   'for_await_statement',
   'conditional_expression',
-  'conditional_expression?',
   'catch_clause',
 ]);