octocode-cli 1.2.6 → 1.2.8

package/skills/octocode-code-engineer/src/detectors/coupling.ts

@@ -0,0 +1,323 @@
+import { findImportLine } from './shared.js';
+import { canAddFinding } from './shared.js';
+import { isTestFile } from '../common/utils.js';
+
+import type { FindingDraft } from './shared.js';
+import type { DependencyState } from '../types/index.js';
+
+export function computeInstability(
+  inboundCount: number,
+  outboundCount: number
+): number {
+  const total = inboundCount + outboundCount;
+  if (total === 0) return 0;
+  return outboundCount / total;
+}
+
+export function detectSdpViolations(
+  dependencyState: DependencyState,
+  minDelta: number = 0.15,
+  maxSourceInstability: number = 0.6
+): FindingDraft[] {
+  const findings: FindingDraft[] = [];
+  const cache = new Map<string, number>();
+
+  const getI = (file: string): number => {
+    if (cache.has(file)) return cache.get(file)!;
+    const ca = (dependencyState.incoming.get(file) || new Set()).size;
+    const ce = (dependencyState.outgoing.get(file) || new Set()).size;
+    const i = computeInstability(ca, ce);
+    cache.set(file, i);
+    return i;
+  };
+
+  for (const file of dependencyState.files) {
+    if (isTestFile(file)) continue;
+    const deps = dependencyState.outgoing.get(file) || new Set();
+    const iSrc = getI(file);
+
+    for (const dep of deps) {
+      if (!dependencyState.files.has(dep) || isTestFile(dep)) continue;
+      const iTgt = getI(dep);
+      const delta = iTgt - iSrc;
+
+      if (delta > minDelta && iSrc < maxSourceInstability) {
+        const importRef = findImportLine(dependencyState, file, dep);
+        findings.push({
+          severity: delta > 0.3 ? 'high' : 'medium',
+          category: 'architecture-sdp-violation',
+          file,
+          lineStart: importRef.lineStart,
+          lineEnd: importRef.lineEnd,
+          title: `SDP violation: stable module depends on unstable module`,
+          reason: `"${file}" (I=${iSrc.toFixed(2)}) depends on "${dep}" (I=${iTgt.toFixed(2)}). Delta=${delta.toFixed(2)}.`,
+          files: [file, dep],
+          suggestedFix: {
+            strategy:
+              'Invert dependency via interface/abstraction or move shared code to a stable utility.',
+            steps: [
+              'Extract a stable interface that the stable module depends on.',
+              'Have the unstable module implement that interface.',
+              'Consider moving shared logic to a lower-instability utility module.',
+            ],
+          },
+          impact:
+            'Prevents cascading instability and reduces change propagation risk.',
+          tags: ['stability', 'coupling', 'architecture', 'sdp'],
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+export function detectHighCoupling(
+  dependencyState: DependencyState,
+  threshold: number = 15
+): FindingDraft[] {
+  const findings: FindingDraft[] = [];
+
+  for (const file of dependencyState.files) {
+    if (isTestFile(file)) continue;
+    const ca = (dependencyState.incoming.get(file) || new Set()).size;
+    const ce = (dependencyState.outgoing.get(file) || new Set()).size;
+    const total = ca + ce;
+
+    if (total > threshold) {
+      findings.push({
+        severity: total > 25 ? 'high' : 'medium',
+        category: 'high-coupling',
+        file,
+        lineStart: 1,
+        lineEnd: 1,
+        title: `High coupling: ${file}`,
+        reason: `Module has ${total} total connections (Ca=${ca}, Ce=${ce}). Threshold: ${threshold}.`,
+        files: [file],
+        suggestedFix: {
+          strategy:
+            'Reduce coupling by extracting interfaces or splitting module responsibilities.',
+          steps: [
+            'Identify groups of related imports/dependents that can be isolated.',
+            'Extract focused sub-modules with single responsibilities.',
+            'Use dependency inversion to reduce direct coupling.',
+          ],
+        },
+        impact:
+          'Lower coupling reduces change ripple effects and improves testability.',
+        tags: ['coupling', 'change-risk', 'architecture'],
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function detectGodModuleCoupling(
+  dependencyState: DependencyState,
+  fanInThreshold: number = 20,
+  fanOutThreshold: number = 15
+): FindingDraft[] {
+  const findings: FindingDraft[] = [];
+
+  for (const file of dependencyState.files) {
+    if (isTestFile(file)) continue;
+    const fanIn = (dependencyState.incoming.get(file) || new Set()).size;
+    const fanOut = (dependencyState.outgoing.get(file) || new Set()).size;
+
+    if (fanIn > fanInThreshold) {
+      findings.push({
+        severity: fanIn > fanInThreshold * 1.5 ? 'high' : 'medium',
+        category: 'god-module-coupling',
+        file,
+        lineStart: 1,
+        lineEnd: 1,
+        title: `High fan-in bottleneck: ${file}`,
+        reason: `Module is depended on by ${fanIn} modules (threshold: ${fanInThreshold}). Changes ripple widely.`,
+        files: [file],
+        suggestedFix: {
+          strategy:
+            'Split this module into focused sub-modules to reduce blast radius.',
+          steps: [
+            'Identify distinct groups of consumers using different parts of this module.',
+            'Extract each group into a dedicated module.',
+            'Update import paths incrementally.',
+          ],
+        },
+        impact:
+          'Reduces change blast radius and improves parallel development.',
+        tags: ['coupling', 'blast-radius', 'bottleneck'],
+      });
+    }
+
+    if (fanOut > fanOutThreshold) {
+      findings.push({
+        severity: fanOut > fanOutThreshold * 1.5 ? 'high' : 'medium',
+        category: 'god-module-coupling',
+        file,
+        lineStart: 1,
+        lineEnd: 1,
+        title: `High fan-out: ${file}`,
+        reason: `Module depends on ${fanOut} modules (threshold: ${fanOutThreshold}). It may violate single responsibility.`,
+        files: [file],
+        suggestedFix: {
+          strategy:
+            'Reduce dependencies by introducing facade or mediator patterns.',
+          steps: [
+            'Group related imports behind a single facade module.',
+            'Consider splitting this module by responsibility.',
+            'Use dependency injection to reduce direct coupling.',
+          ],
+        },
+        impact:
+          'Cleaner architecture and easier testing through reduced dependencies.',
+        tags: ['coupling', 'responsibility', 'sprawl'],
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function detectLayerViolations(
+  dependencyState: DependencyState,
+  layerOrder: string[]
+): FindingDraft[] {
+  if (layerOrder.length < 2) return [];
+
+  const findings: FindingDraft[] = [];
+
+  const getLayer = (file: string): number => {
+    for (let i = 0; i < layerOrder.length; i++) {
+      if (file.includes(layerOrder[i])) return i;
+    }
+    return -1;
+  };
+
+  for (const file of dependencyState.files) {
+    if (isTestFile(file)) continue;
+    const srcLayer = getLayer(file);
+    if (srcLayer === -1) continue;
+
+    for (const dep of dependencyState.outgoing.get(file) || new Set()) {
+      if (!dependencyState.files.has(dep) || isTestFile(dep)) continue;
+      const depLayer = getLayer(dep);
+      if (depLayer === -1) continue;
+
+      if (depLayer < srcLayer) {
+        const importRef = findImportLine(dependencyState, file, dep);
+        findings.push({
+          severity: 'high',
+          category: 'layer-violation',
+          file,
+          lineStart: importRef.lineStart,
+          lineEnd: importRef.lineEnd,
+          title: `Layer violation: ${layerOrder[srcLayer]} imports from ${layerOrder[depLayer]}`,
+          reason: `"${file}" (layer: ${layerOrder[srcLayer]}) imports "${dep}" (layer: ${layerOrder[depLayer]}). Layer order: ${layerOrder.join(' → ')}.`,
+          files: [file, dep],
+          suggestedFix: {
+            strategy:
+              'Respect layer boundaries by inverting the dependency or moving shared logic.',
+            steps: [
+              'Extract shared contracts to a lower layer that both can depend on.',
+              'Use dependency inversion: define an interface in the lower layer, implement in higher.',
+              'If the dependency is justified, reconsider your layer boundaries.',
+            ],
+          },
+          impact:
+            'Prevents architectural erosion and keeps dependency flow unidirectional.',
+          tags: ['architecture', 'layering', 'coupling'],
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+export function computeAbstractness(
+  exports: { name: string; kind: string }[]
+): number {
+  if (exports.length === 0) return 0;
+  const abstractCount = exports.filter(e => e.kind === 'type').length;
+  return abstractCount / exports.length;
+}
+
+export function detectDistanceFromMainSequence(
+  dependencyState: DependencyState,
+  distanceThreshold: number = 0.7,
+  minCoupling: number = 3
+): FindingDraft[] {
+  const findings: FindingDraft[] = [];
+
+  for (const file of dependencyState.files) {
+    if (isTestFile(file)) continue;
+
+    const exports = dependencyState.declaredExportsByFile.get(file);
+    if (!exports || exports.length === 0) continue;
+
+    const ca = (dependencyState.incoming.get(file) || new Set()).size;
+    const ce = (dependencyState.outgoing.get(file) || new Set()).size;
+    if (ca + ce < minCoupling) continue;
+
+    const I = computeInstability(ca, ce);
+    const A = computeAbstractness(exports);
+    const D = Math.abs(A + I - 1);
+
+    if (D < distanceThreshold) continue;
+
+    const isZoneOfPain = A < 0.2 && I < 0.3;
+    const isZoneOfUselessness = A > 0.7 && I > 0.7;
+
+    let zone = '';
+    if (isZoneOfPain)
+      zone =
+        'Zone of Pain (concrete + stable): hard to extend, painful to change.';
+    else if (isZoneOfUselessness)
+      zone =
+        'Zone of Uselessness (abstract + unstable): over-abstracted and unused.';
+    else
+      zone = `Far from Main Sequence: balance between abstraction and stability is off.`;
+
+    if (!canAddFinding(findings)) break;
+    findings.push({
+      severity: D > 0.85 ? 'high' : 'medium',
+      category: 'distance-from-main-sequence',
+      file,
+      lineStart: 1,
+      lineEnd: 1,
+      title: `Distance from Main Sequence: ${file} (D=${D.toFixed(2)})`,
+      reason: `${zone} A=${A.toFixed(2)}, I=${I.toFixed(2)}, D=${D.toFixed(2)} (threshold: ${distanceThreshold}).`,
+      files: [file],
+      suggestedFix: {
+        strategy: isZoneOfPain
+          ? 'Add abstractions (interfaces/types) or reduce inbound coupling.'
+          : isZoneOfUselessness
+            ? 'Add concrete implementations or remove unused abstractions.'
+            : 'Rebalance by adjusting abstraction level or dependency direction.',
+        steps: isZoneOfPain
+          ? [
+              'Extract interfaces for key behaviors to increase abstractness.',
+              'Consider splitting into abstract contracts + concrete implementations.',
+              'Reduce inbound coupling by narrowing the public API surface.',
+            ]
+          : isZoneOfUselessness
+            ? [
+                'Verify abstractions have concrete implementations.',
+                'Remove unused interfaces/types that serve no consumer.',
+                'Consider consolidating with concrete modules.',
+              ]
+            : [
+                'Review the balance between interfaces/types and concrete exports.',
+                'Adjust dependency direction to move closer to the Main Sequence.',
+                'Consider splitting responsibilities between abstract and concrete modules.',
+              ],
+      },
+      impact:
+        'Modules on the Main Sequence (D≈0) have optimal balance between stability and extensibility.',
+      tags: ['architecture', 'stability', 'abstractness', 'sdp'],
+    });
+  }
+
+  return findings;
+}

package/skills/octocode-code-engineer/src/detectors/cycle.ts

@@ -0,0 +1,349 @@
+import { findImportLine, isLikelyEntrypoint } from './shared.js';
+import { canAddFinding } from './shared.js';
+import { isTestFile } from '../common/utils.js';
+
+import type { FindingDraft } from './shared.js';
+import type {
+  DependencyState,
+  DependencySummary,
+} from '../types/index.js';
+
+export function detectTestOnlyModules(
+  dependencySummary: DependencySummary
+): FindingDraft[] {
+  const findings: FindingDraft[] = [];
+  if (dependencySummary.testOnlyModules?.length === 0) return findings;
+  for (const file of (dependencySummary.testOnlyModules || []).slice(0, 25)) {
+    if (!canAddFinding(findings)) break;
+    findings.push({
+      severity: 'medium',
+      category: 'dependency-test-only',
+      file: file.file,
+      lineStart: file.lineStart || 1,
+      lineEnd: file.lineEnd || 1,
+      title: `Module imported only from tests: ${file.file}`,
+      reason:
+        'No production file imports this module, but tests do. Verify if this module belongs in test fixtures/helpers.',
+      files: [file.file],
+      suggestedFix: {
+        strategy:
+          'Move test-only utilities to test scope or make production usage explicit.',
+        steps: [
+          'Re-run import scanning after moving test-only modules to __tests__ or helper folders.',
+          'If this is shared production utility, add a non-test entrypoint/import.',
+          'Remove dead or stale production references and delete unused module if confirmed.',
+        ],
+      },
+      impact:
+        'Reduces shipping of non-production-only modules and clarifies ownership boundaries.',
+      tags: ['testing', 'dead-code', 'dependency'],
+    });
+  }
+  return findings;
+}
+
+export function detectDependencyCycles(
+  dependencySummary: DependencySummary,
+  dependencyState: DependencyState
+): FindingDraft[] {
+  const findings: FindingDraft[] = [];
+  if (dependencySummary.cycles?.length === 0) return findings;
+  for (const cycle of (dependencySummary.cycles || []).slice(0, 15)) {
+    const cycleLine = findImportLine(
+      dependencyState,
+      cycle.path[0],
+      cycle.path[1]
+    );
+    if (!canAddFinding(findings)) break;
+    findings.push({
+      severity: 'high',
+      category: 'dependency-cycle',
+      file: cycle.path[0],
+      lineStart: cycleLine.lineStart,
+      lineEnd: cycleLine.lineEnd,
+      title: `Dependency cycle detected (${cycle.nodeCount} node cycle)`,
+      reason: `Import cycle exists across: ${cycle.path.join(' -> ')}`,
+      files: cycle.path,
+      suggestedFix: {
+        strategy:
+          'Break the cycle with a lower-level abstraction or interface module.',
+        steps: [
+          'Extract shared contracts/types to a dedicated contract/shared package.',
+          'Move implementation in one direction using dependency inversion.',
+          'Split stateful modules into protocol and runtime layers.',
+        ],
+      },
+      impact:
+        'Cycles increase coupling and make incremental loading/debugging and refactors riskier.',
+      tags: ['cycle', 'coupling', 'dependency', 'change-risk'],
+      lspHints: [
+        {
+          tool: 'lspGotoDefinition',
+          symbolName: cycle.path[1],
+          lineHint: cycleLine.lineStart,
+          file: cycle.path[0],
+          expectedResult: `navigate to the import that creates the cycle edge`,
+        },
+      ],
+    });
+  }
+  return findings;
+}
+
+function findChainHotspot(
+  chainPath: string[],
+  dependencyState: DependencyState
+): { module: string; fanOut: number; fanIn: number } {
+  let best = { module: chainPath[0], fanOut: 0, fanIn: 0 };
+  for (const mod of chainPath) {
+    const fanOut = (dependencyState.outgoing.get(mod) || new Set()).size;
+    const fanIn = (dependencyState.incoming.get(mod) || new Set()).size;
+    if (fanOut > best.fanOut) {
+      best = { module: mod, fanOut, fanIn };
+    }
+  }
+  return best;
+}
+
+export function mergeOverlappingChains(
+  findings: FindingDraft[],
+  overlapThreshold: number = 0.8
+): FindingDraft[] {
+  if (findings.length <= 1) return findings;
+
+  const merged: FindingDraft[] = [];
+  const consumed = new Set<number>();
+
+  for (let i = 0; i < findings.length; i++) {
+    if (consumed.has(i)) continue;
+    const base = findings[i];
+    const baseSet = new Set(base.files);
+    const entryPoints = [base.file];
+
+    for (let j = i + 1; j < findings.length; j++) {
+      if (consumed.has(j)) continue;
+      const other = findings[j];
+      const otherSet = new Set(other.files);
+      const intersection = [...baseSet].filter(f => otherSet.has(f)).length;
+      const union = new Set([...baseSet, ...otherSet]).size;
+      const overlap = union > 0 ? intersection / union : 0;
+
+      if (overlap >= overlapThreshold) {
+        consumed.add(j);
+        entryPoints.push(other.file);
+        for (const f of other.files) baseSet.add(f);
+      }
+    }
+
+    if (entryPoints.length > 1) {
+      const allFiles = [...baseSet];
+      merged.push({
+        ...base,
+        title: `Critical dependency chain risk: ${allFiles.length} files (${entryPoints.length} entry points)`,
+        reason:
+          base.reason +
+          ` Also reached from: ${entryPoints.slice(1).join(', ')}.`,
+        files: allFiles,
+      });
+    } else {
+      merged.push(base);
+    }
+  }
+
+  return merged;
+}
+
+export function detectCriticalPaths(
+  dependencySummary: DependencySummary,
+  dependencyState: DependencyState,
+  criticalComplexityThreshold: number
+): FindingDraft[] {
+  const rawFindings: FindingDraft[] = [];
+  if (dependencySummary.criticalPaths?.length === 0) return rawFindings;
+  for (const pathEntry of (dependencySummary.criticalPaths || []).slice(
+    0,
+    10
+  )) {
+    if (pathEntry.score < criticalComplexityThreshold * 3) continue;
+    const chainLine = findImportLine(
+      dependencyState,
+      pathEntry.path[0],
+      pathEntry.path[1]
+    );
+    const hotspot = findChainHotspot(pathEntry.path, dependencyState);
+    rawFindings.push({
+      severity:
+        pathEntry.score >= criticalComplexityThreshold * 6
+          ? 'critical'
+          : 'high',
+      category: 'dependency-critical-path',
+      file: pathEntry.path[0],
+      lineStart: chainLine.lineStart,
+      lineEnd: chainLine.lineEnd,
+      title: `Critical dependency chain risk: ${pathEntry.length} files`,
+      reason: `Potentially high-change surface: ${pathEntry.path.join(' -> ')} (${pathEntry.score} weight).`,
+      files: pathEntry.path,
+      suggestedFix: {
+        strategy: `Break chain at \`${hotspot.module}\` (fan-out: ${hotspot.fanOut}, fan-in: ${hotspot.fanIn}).`,
+        steps: [
+          `Extract interface from \`${hotspot.module}\` — it has ${hotspot.fanOut} outbound dependencies.`,
+          'Downstream modules depend on the interface, not the implementation.',
+          'This splits the chain into two independent segments.',
+        ],
+      },
+      impact:
+        'Critical refactor opportunities; shorter chains reduce blast radius of change.',
+      tags: ['change-risk', 'dependency', 'blast-radius'],
+    });
+  }
+  return mergeOverlappingChains(rawFindings);
+}
+
+export function detectDeadFiles(
+  dependencySummary: DependencySummary,
+  dependencyState: DependencyState
+): FindingDraft[] {
+  const findings: FindingDraft[] = [];
+  for (const file of dependencySummary.roots || []) {
+    if (isTestFile(file)) continue;
+    if (isLikelyEntrypoint(file)) continue;
+    const incomingCount = (dependencyState.incoming.get(file) || new Set())
+      .size;
+    const outgoingCount = (dependencyState.outgoing.get(file) || new Set())
+      .size;
+    if (incomingCount !== 0) continue;
+    if (outgoingCount > 0) continue;
+    if (!canAddFinding(findings)) break;
+    findings.push({
+      severity: 'medium',
+      category: 'dead-file',
+      file,
+      lineStart: 1,
+      lineEnd: 1,
+      title: `Potential dead file: ${file}`,
+      reason:
+        'File has no inbound imports and no outbound dependencies. It may be stale or orphaned.',
+      files: [file],
+      suggestedFix: {
+        strategy: 'Validate ownership and remove if truly unused.',
+        steps: [
+          'Confirm the file is not an explicit runtime entrypoint.',
+          'Search runtime config/router/bootstrap references for this file path.',
+          'Delete file if confirmed dead and re-run scan.',
+        ],
+      },
+      impact: 'Reduces dead surface area and maintenance overhead.',
+      tags: ['dead-code', 'cleanup', 'hygiene'],
+      lspHints: [
+        {
+          tool: 'lspFindReferences',
+          symbolName: file.split('/').pop() || file,
+          lineHint: 1,
+          file,
+          expectedResult: `confirm zero references exist before deletion`,
+        },
+      ],
+    });
+  }
+  return findings;
+}
+
+export function detectOrphanModules(
+  dependencyState: DependencyState
+): FindingDraft[] {
+  const findings: FindingDraft[] = [];
+
+  for (const file of dependencyState.files) {
+    if (isTestFile(file)) continue;
+    if (isLikelyEntrypoint(file)) continue;
+
+    const ca = (dependencyState.incoming.get(file) || new Set()).size;
+    const ce = (dependencyState.outgoing.get(file) || new Set()).size;
+
+    if (ca === 0 && ce === 0) {
+      findings.push({
+        severity: 'medium',
+        category: 'orphan-module',
+        file,
+        lineStart: 1,
+        lineEnd: 1,
+        title: `Orphan module: ${file}`,
+        reason:
+          'Module has no inbound or outbound dependencies — completely disconnected from the module graph.',
+        files: [file],
+        suggestedFix: {
+          strategy: 'Delete if truly unused, or wire into module graph.',
+          steps: [
+            'Check if the file is a runtime entrypoint, route, or config.',
+            'If truly disconnected, delete and re-run scan.',
+            'If needed, add an explicit import from the appropriate parent module.',
+          ],
+        },
+        impact: 'Removes dead surface area and clarifies module ownership.',
+        tags: ['dead-code', 'dependency', 'isolation'],
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function detectUnreachableModules(
+  dependencyState: DependencyState
+): FindingDraft[] {
+  const findings: FindingDraft[] = [];
+
+  const entrypoints = new Set<string>();
+  for (const file of dependencyState.files) {
+    if (isLikelyEntrypoint(file)) entrypoints.add(file);
+  }
+  if (entrypoints.size === 0) {
+    for (const file of dependencyState.files) {
+      if ((dependencyState.incoming.get(file) || new Set()).size === 0) {
+        entrypoints.add(file);
+      }
+    }
+  }
+
+  const reachable = new Set<string>();
+  const queue = [...entrypoints];
+  while (queue.length > 0) {
+    const current = queue.pop()!;
+    if (reachable.has(current)) continue;
+    reachable.add(current);
+    for (const dep of dependencyState.outgoing.get(current) || new Set()) {
+      if (dependencyState.files.has(dep) && !reachable.has(dep))
+        queue.push(dep);
+    }
+  }
+
+  for (const file of dependencyState.files) {
+    if (isTestFile(file) || reachable.has(file) || isLikelyEntrypoint(file))
+      continue;
+    if (!canAddFinding(findings)) break;
+    findings.push({
+      severity: 'high',
+      category: 'unreachable-module',
+      file,
+      lineStart: 1,
+      lineEnd: 1,
+      title: `Unreachable module: ${file}`,
+      reason:
+        'Module is not reachable from any entrypoint via the import graph.',
+      files: [file],
+      suggestedFix: {
+        strategy: 'Verify reachability and remove if truly dead.',
+        steps: [
+          'Check if this module is loaded dynamically or via framework conventions.',
+          'Verify it is not registered as a route, plugin, or middleware.',
+          'If confirmed unreachable, delete and re-run scan.',
+        ],
+      },
+      impact:
+        'Identifies potentially large sections of dead code missed by direct-import checks.',
+      tags: ['dead-code', 'dependency', 'reachability'],
+    });
+  }
+
+  return findings;
+}