sdlc-agent-4-enterprise-server 1.0.0

package/src/engine/analyzers/complexity/ComplexityStore.ts

@@ -0,0 +1,177 @@
+/**
+ * KSA-161: SQLite CRUD for complexity results.
+ */
+
+import Database from 'better-sqlite3';
+import type { ComplexityResult, ComplexityFilters, ComplexityQueryResult, Grade } from './types.js';
+
+const CREATE_TABLE = `
+CREATE TABLE IF NOT EXISTS complexity (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  symbol_id INTEGER NOT NULL,
+  cyclomatic_complexity INTEGER NOT NULL DEFAULT 1,
+  branches INTEGER NOT NULL DEFAULT 0,
+  loops INTEGER NOT NULL DEFAULT 0,
+  logical_ops INTEGER NOT NULL DEFAULT 0,
+  nesting_depth INTEGER NOT NULL DEFAULT 0,
+  early_returns INTEGER NOT NULL DEFAULT 0,
+  exception_handlers INTEGER NOT NULL DEFAULT 0,
+  grade TEXT NOT NULL DEFAULT 'A',
+  computed_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (symbol_id) REFERENCES symbols(id) ON DELETE CASCADE,
+  UNIQUE(symbol_id)
+);
+CREATE INDEX IF NOT EXISTS idx_complexity_grade ON complexity(grade);
+CREATE INDEX IF NOT EXISTS idx_complexity_cc ON complexity(cyclomatic_complexity DESC);
+CREATE INDEX IF NOT EXISTS idx_complexity_symbol ON complexity(symbol_id);
+`;
+
+export class ComplexityStore {
+  private db: Database.Database;
+  private stmts!: {
+    upsert: Database.Statement;
+    getBySymbol: Database.Statement;
+    deleteBySymbol: Database.Statement;
+  };
+
+  constructor(db: Database.Database) {
+    this.db = db;
+    this.ensureTable();
+    this.prepareStatements();
+  }
+
+  /** Store or update complexity result for a symbol. */
+  upsert(result: ComplexityResult): void {
+    this.stmts.upsert.run(
+      result.symbol_id,
+      result.cyclomatic_complexity,
+      result.branches,
+      result.loops,
+      result.logical_ops,
+      result.nesting_depth,
+      result.early_returns,
+      result.exception_handlers,
+      result.grade
+    );
+  }
+
+  /** Batch upsert complexity results. */
+  upsertBatch(results: ComplexityResult[]): void {
+    const transaction = this.db.transaction((items: ComplexityResult[]) => {
+      for (const r of items) this.upsert(r);
+    });
+    transaction(results);
+  }
+
+  /** Get complexity for a specific symbol. */
+  getBySymbol(symbolId: number): ComplexityResult | null {
+    return (this.stmts.getBySymbol.get(symbolId) as ComplexityResult) ?? null;
+  }
+
+  /** Query complexity results with filters. */
+  query(filters: ComplexityFilters): ComplexityQueryResult {
+    let sql = `
+      SELECT c.*, s.name as symbol_name, f.relative_path as file_path,
+             s.start_line, s.end_line
+      FROM complexity c
+      JOIN symbols s ON s.id = c.symbol_id
+      JOIN files f ON f.id = s.file_id
+      WHERE 1=1
+    `;
+    const params: unknown[] = [];
+
+    if (filters.filePath) {
+      sql += ' AND f.relative_path LIKE ?';
+      params.push(`%${filters.filePath}%`);
+    }
+    if (filters.symbolName) {
+      sql += ' AND s.name LIKE ?';
+      params.push(`%${filters.symbolName}%`);
+    }
+    if (filters.minComplexity !== undefined) {
+      sql += ' AND c.cyclomatic_complexity >= ?';
+      params.push(filters.minComplexity);
+    }
+    if (filters.gradeFilter && filters.gradeFilter.length > 0) {
+      const placeholders = filters.gradeFilter.map(() => '?').join(',');
+      sql += ` AND c.grade IN (${placeholders})`;
+      params.push(...filters.gradeFilter);
+    }
+    if (filters.module) {
+      sql += ' AND f.module = ?';
+      params.push(filters.module);
+    }
+
+    // Count total before limit
+    const countSql = sql.replace(/SELECT c\.\*.*?FROM/, 'SELECT COUNT(*) as total FROM');
+    const totalRow = this.db.prepare(countSql).get(...params) as { total: number } | undefined;
+    const total = totalRow?.total ?? 0;
+
+    // Sort and limit
+    switch (filters.sortBy) {
+      case 'name': sql += ' ORDER BY s.name ASC'; break;
+      case 'file': sql += ' ORDER BY f.relative_path ASC, s.start_line ASC'; break;
+      default: sql += ' ORDER BY c.cyclomatic_complexity DESC'; break;
+    }
+    sql += ' LIMIT ?';
+    params.push(filters.limit);
+
+    const results = this.db.prepare(sql).all(...params) as ComplexityResult[];
+
+    // Grade distribution
+    const distSql = `
+      SELECT c.grade, COUNT(*) as count
+      FROM complexity c
+      JOIN symbols s ON s.id = c.symbol_id
+      JOIN files f ON f.id = s.file_id
+      WHERE 1=1 ${filters.module ? 'AND f.module = ?' : ''}
+      GROUP BY c.grade
+    `;
+    const distParams = filters.module ? [filters.module] : [];
+    const distRows = this.db.prepare(distSql).all(...distParams) as { grade: Grade; count: number }[];
+    const gradeDistribution: Record<Grade, number> = { A: 0, B: 0, C: 0, D: 0, F: 0 };
+    for (const row of distRows) gradeDistribution[row.grade] = row.count;
+
+    // Average
+    const avgSql = `SELECT AVG(cyclomatic_complexity) as avg FROM complexity`;
+    const avgRow = this.db.prepare(avgSql).get() as { avg: number | null };
+
+    return {
+      results,
+      total,
+      summary: {
+        average: avgRow?.avg ?? 0,
+        gradeDistribution,
+      },
+    };
+  }
+
+  /** Delete complexity data for a symbol. */
+  deleteBySymbol(symbolId: number): void {
+    this.stmts.deleteBySymbol.run(symbolId);
+  }
+
+  private ensureTable(): void {
+    this.db.exec(CREATE_TABLE);
+  }
+
+  private prepareStatements(): void {
+    this.stmts = {
+      upsert: this.db.prepare(`
+        INSERT OR REPLACE INTO complexity
+          (symbol_id, cyclomatic_complexity, branches, loops, logical_ops,
+           nesting_depth, early_returns, exception_handlers, grade, computed_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+      `),
+      getBySymbol: this.db.prepare(`
+        SELECT c.*, s.name as symbol_name, f.relative_path as file_path,
+               s.start_line, s.end_line
+        FROM complexity c
+        JOIN symbols s ON s.id = c.symbol_id
+        JOIN files f ON f.id = s.file_id
+        WHERE c.symbol_id = ?
+      `),
+      deleteBySymbol: this.db.prepare('DELETE FROM complexity WHERE symbol_id = ?'),
+    };
+  }
+}

package/src/engine/analyzers/complexity/ComplexityTool.ts

@@ -0,0 +1,71 @@
+/**
+ * KSA-161: MCP Tool registration for complexity_analysis.
+ */
+
+import Database from 'better-sqlite3';
+import { ComplexityAnalyzer } from './ComplexityAnalyzer.js';
+import type { Grade } from './types.js';
+
+export const COMPLEXITY_TOOL_DEFINITION = {
+  name: 'complexity_analysis',
+  description: 'Analyze cyclomatic complexity of functions with breakdown and A-F grading. Query by file, symbol, grade, or module.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      file_path: { type: 'string', description: 'Filter by file path (partial match)' },
+      symbol_name: { type: 'string', description: 'Filter by function/method name' },
+      min_complexity: { type: 'number', description: 'Minimum CC threshold (default: 1)' },
+      grade_filter: { type: 'string', description: 'Comma-separated grades to include (e.g. "C,D,F")' },
+      module: { type: 'string', description: 'Filter by module name' },
+      limit: { type: 'number', description: 'Max results (default: 20)' },
+      sort_by: { type: 'string', description: 'Sort by: complexity (default), name, file' },
+    },
+  },
+};
+
+/** Handle complexity_analysis tool call. */
+export function handleComplexityTool(args: Record<string, unknown>, db: Database.Database): string {
+  const analyzer = new ComplexityAnalyzer(db);
+
+  const filters = {
+    filePath: args.file_path as string | undefined,
+    symbolName: args.symbol_name as string | undefined,
+    minComplexity: args.min_complexity as number | undefined,
+    gradeFilter: args.grade_filter
+      ? (args.grade_filter as string).split(',').map(g => g.trim() as Grade)
+      : undefined,
+    module: args.module as string | undefined,
+    limit: (args.limit as number) ?? 20,
+    sortBy: (args.sort_by as 'complexity' | 'name' | 'file') ?? 'complexity',
+  };
+
+  const result = analyzer.query(filters);
+
+  if (result.results.length === 0) {
+    return 'No complexity data found. Run indexing first to compute complexity metrics.';
+  }
+
+  const lines: string[] = [
+    `Complexity Analysis — ${result.total} functions found\n`,
+    `Average CC: ${result.summary.average.toFixed(1)} | Grade Distribution: ` +
+    `A=${result.summary.gradeDistribution.A} B=${result.summary.gradeDistribution.B} ` +
+    `C=${result.summary.gradeDistribution.C} D=${result.summary.gradeDistribution.D} ` +
+    `F=${result.summary.gradeDistribution.F}\n`,
+  ];
+
+  for (const r of result.results) {
+    lines.push(
+      `[${r.grade}] ${r.symbol_name} — CC=${r.cyclomatic_complexity} ` +
+      `(branches=${r.branches} loops=${r.loops} logic=${r.logical_ops} ` +
+      `exceptions=${r.exception_handlers} depth=${r.nesting_depth})`
+    );
+    lines.push(`    ${r.file_path}:${r.start_line}-${r.end_line}`);
+  }
+
+  return lines.join('\n');
+}
+
+/** Register the complexity tool in the dispatch system. */
+export function registerComplexityTool(): typeof COMPLEXITY_TOOL_DEFINITION {
+  return COMPLEXITY_TOOL_DEFINITION;
+}

package/src/engine/analyzers/complexity/GradeAssigner.ts

@@ -0,0 +1,34 @@
+/**
+ * KSA-161: Grade assignment based on cyclomatic complexity thresholds.
+ */
+
+import type { Grade, GradeThresholds } from './types.js';
+
+const DEFAULT_THRESHOLDS: GradeThresholds = {
+  A: 5,
+  B: 10,
+  C: 20,
+  D: 50,
+};
+
+export class GradeAssigner {
+  private thresholds: GradeThresholds;
+
+  constructor(thresholds?: Partial<GradeThresholds>) {
+    this.thresholds = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  }
+
+  /** Assign a letter grade based on cyclomatic complexity score. */
+  assignGrade(cc: number): Grade {
+    if (cc <= this.thresholds.A) return 'A';
+    if (cc <= this.thresholds.B) return 'B';
+    if (cc <= this.thresholds.C) return 'C';
+    if (cc <= this.thresholds.D) return 'D';
+    return 'F';
+  }
+
+  /** Get the current thresholds. */
+  getThresholds(): GradeThresholds {
+    return { ...this.thresholds };
+  }
+}

package/src/engine/analyzers/complexity/counters/BaseNodeCounter.ts

@@ -0,0 +1,94 @@
+/**
+ * KSA-161: Abstract base class for language-specific AST node counters.
+ * Each language subclass defines which node types represent decision points.
+ */
+
+import type { SyntaxNode } from '../../../parsers/types.js';
+import type { DecisionPointCounts } from '../types.js';
+
+export abstract class BaseNodeCounter {
+  abstract readonly language: string;
+  abstract readonly branchNodeTypes: string[];
+  abstract readonly loopNodeTypes: string[];
+  abstract readonly logicalOperators: string[];
+  abstract readonly exceptionNodeTypes: string[];
+
+  /** Count all decision points in an AST subtree (single pass). */
+  countDecisionPoints(node: SyntaxNode): DecisionPointCounts {
+    const counts: DecisionPointCounts = {
+      branches: 0,
+      loops: 0,
+      logical_ops: 0,
+      exception_handlers: 0,
+    };
+    this.walkTree(node, (child) => {
+      if (this.branchNodeTypes.includes(child.type)) {
+        counts.branches++;
+      } else if (this.loopNodeTypes.includes(child.type)) {
+        counts.loops++;
+      } else if (this.exceptionNodeTypes.includes(child.type)) {
+        counts.exception_handlers++;
+      }
+      // Check for logical operators in binary expressions
+      if (this.isLogicalOp(child)) {
+        counts.logical_ops++;
+      }
+    });
+    return counts;
+  }
+
+  /** Calculate maximum nesting depth of control structures. */
+  calculateNestingDepth(node: SyntaxNode): number {
+    const controlTypes = [...this.branchNodeTypes, ...this.loopNodeTypes];
+    let maxDepth = 0;
+
+    const walk = (n: SyntaxNode, depth: number): void => {
+      if (controlTypes.includes(n.type)) {
+        depth++;
+        if (depth > maxDepth) maxDepth = depth;
+      }
+      for (let i = 0; i < n.childCount; i++) {
+        const child = n.child(i);
+        if (child) walk(child, depth);
+      }
+    };
+    walk(node, 0);
+    return maxDepth;
+  }
+
+  /** Count early return statements in a function body. */
+  countEarlyReturns(node: SyntaxNode): number {
+    let count = 0;
+    const returnTypes = this.getReturnNodeTypes();
+    this.walkTree(node, (child) => {
+      if (returnTypes.includes(child.type)) {
+        count++;
+      }
+    });
+    // The last return doesn't count as "early"
+    return Math.max(0, count - 1);
+  }
+
+  /** Override in subclass to check if a node represents a logical operator. */
+  protected isLogicalOp(node: SyntaxNode): boolean {
+    if (node.type === 'binary_expression' || node.type === 'logical_expression') {
+      const op = node.childForFieldName('operator');
+      if (op && this.logicalOperators.includes(op.text)) return true;
+    }
+    return false;
+  }
+
+  /** Override in subclass for language-specific return node types. */
+  protected getReturnNodeTypes(): string[] {
+    return ['return_statement'];
+  }
+
+  /** Walk all nodes in the tree, calling visitor for each. */
+  protected walkTree(node: SyntaxNode, visitor: (n: SyntaxNode) => void): void {
+    visitor(node);
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child) this.walkTree(child, visitor);
+    }
+  }
+}

package/src/engine/analyzers/complexity/counters/GoCounter.ts

@@ -0,0 +1,34 @@
+/**
+ * KSA-161: Go decision point counter.
+ */
+
+import type { SyntaxNode } from '../../../parsers/types.js';
+import { BaseNodeCounter } from './BaseNodeCounter.js';
+
+export class GoCounter extends BaseNodeCounter {
+  readonly language = 'go';
+  readonly branchNodeTypes = [
+    'if_statement',
+    'expression_case',       // switch case
+    'type_case',             // type switch case
+    'select_statement',
+    'communication_case',
+  ];
+  readonly loopNodeTypes = [
+    'for_statement',
+  ];
+  readonly logicalOperators = ['&&', '||'];
+  readonly exceptionNodeTypes: string[] = []; // Go uses error returns, not exceptions
+
+  protected isLogicalOp(node: SyntaxNode): boolean {
+    if (node.type === 'binary_expression') {
+      const op = node.childForFieldName('operator');
+      if (op && this.logicalOperators.includes(op.text)) return true;
+    }
+    return false;
+  }
+
+  protected getReturnNodeTypes(): string[] {
+    return ['return_statement'];
+  }
+}

package/src/engine/analyzers/complexity/counters/JavaCounter.ts

@@ -0,0 +1,31 @@
+/**
+ * KSA-161: Java decision point counter.
+ */
+
+import type { SyntaxNode } from '../../../parsers/types.js';
+import { BaseNodeCounter } from './BaseNodeCounter.js';
+
+export class JavaCounter extends BaseNodeCounter {
+  readonly language = 'java';
+  readonly branchNodeTypes = [
+    'if_statement',
+    'switch_expression',
+    'ternary_expression',
+  ];
+  readonly loopNodeTypes = [
+    'for_statement',
+    'enhanced_for_statement',
+    'while_statement',
+    'do_statement',
+  ];
+  readonly logicalOperators = ['&&', '||'];
+  readonly exceptionNodeTypes = ['catch_clause'];
+
+  protected isLogicalOp(node: SyntaxNode): boolean {
+    if (node.type === 'binary_expression') {
+      const op = node.childForFieldName('operator');
+      if (op && this.logicalOperators.includes(op.text)) return true;
+    }
+    return false;
+  }
+}

package/src/engine/analyzers/complexity/counters/KotlinCounter.ts

@@ -0,0 +1,37 @@
+/**
+ * KSA-161: Kotlin decision point counter.
+ */
+
+import type { SyntaxNode } from '../../../parsers/types.js';
+import { BaseNodeCounter } from './BaseNodeCounter.js';
+
+export class KotlinCounter extends BaseNodeCounter {
+  readonly language = 'kotlin';
+  readonly branchNodeTypes = [
+    'if_expression',
+    'when_entry',
+    'elvis_expression',
+  ];
+  readonly loopNodeTypes = [
+    'for_statement',
+    'while_statement',
+    'do_while_statement',
+  ];
+  readonly logicalOperators = ['&&', '||'];
+  readonly exceptionNodeTypes = ['catch_block'];
+
+  protected isLogicalOp(node: SyntaxNode): boolean {
+    if (node.type === 'conjunction_expression' || node.type === 'disjunction_expression') {
+      return true;
+    }
+    if (node.type === 'binary_expression') {
+      const op = node.childForFieldName('operator');
+      if (op && this.logicalOperators.includes(op.text)) return true;
+    }
+    return false;
+  }
+
+  protected getReturnNodeTypes(): string[] {
+    return ['jump_expression']; // Kotlin uses jump_expression for return
+  }
+}

package/src/engine/analyzers/complexity/counters/PythonCounter.ts

@@ -0,0 +1,38 @@
+/**
+ * KSA-161: Python decision point counter.
+ */
+
+import type { SyntaxNode } from '../../../parsers/types.js';
+import { BaseNodeCounter } from './BaseNodeCounter.js';
+
+export class PythonCounter extends BaseNodeCounter {
+  readonly language = 'python';
+  readonly branchNodeTypes = [
+    'if_statement',
+    'elif_clause',
+    'conditional_expression',  // ternary: x if cond else y
+  ];
+  readonly loopNodeTypes = [
+    'for_statement',
+    'while_statement',
+  ];
+  readonly logicalOperators = ['and', 'or'];
+  readonly exceptionNodeTypes = ['except_clause'];
+
+  protected isLogicalOp(node: SyntaxNode): boolean {
+    if (node.type === 'boolean_operator') {
+      const op = node.childForFieldName('operator');
+      if (op && this.logicalOperators.includes(op.text)) return true;
+      // Fallback: check children for 'and'/'or' keywords
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (child && (child.text === 'and' || child.text === 'or')) return true;
+      }
+    }
+    return false;
+  }
+
+  protected getReturnNodeTypes(): string[] {
+    return ['return_statement'];
+  }
+}

package/src/engine/analyzers/complexity/counters/TypeScriptCounter.ts

@@ -0,0 +1,34 @@
+/**
+ * KSA-161: TypeScript/JavaScript decision point counter.
+ */
+
+import type { SyntaxNode } from '../../../parsers/types.js';
+import { BaseNodeCounter } from './BaseNodeCounter.js';
+
+export class TypeScriptCounter extends BaseNodeCounter {
+  readonly language = 'typescript';
+  readonly branchNodeTypes = [
+    'if_statement',
+    'switch_case',
+    'ternary_expression',
+  ];
+  readonly loopNodeTypes = [
+    'for_statement',
+    'for_in_statement',
+    'while_statement',
+    'do_statement',
+  ];
+  readonly logicalOperators = ['&&', '||', '??'];
+  readonly exceptionNodeTypes = ['catch_clause'];
+
+  protected isLogicalOp(node: SyntaxNode): boolean {
+    // TypeScript uses binary_expression for && and ||
+    if (node.type === 'binary_expression') {
+      const op = node.childForFieldName('operator');
+      if (op && this.logicalOperators.includes(op.text)) return true;
+    }
+    // Optional chaining counted as a branch decision
+    if (node.type === 'optional_chain_expression') return true;
+    return false;
+  }
+}

package/src/engine/analyzers/complexity/index.ts

@@ -0,0 +1,25 @@
+/**
+ * KSA-161: Cyclomatic Complexity Analyzer — Module exports.
+ * Provides AST-based complexity grading (A-F) for functions across languages.
+ */
+
+export { ComplexityAnalyzer } from './ComplexityAnalyzer.js';
+export { ComplexityCalculator } from './ComplexityCalculator.js';
+export { GradeAssigner } from './GradeAssigner.js';
+export { ComplexityStore } from './ComplexityStore.js';
+export { registerComplexityTool } from './ComplexityTool.js';
+export { BaseNodeCounter } from './counters/BaseNodeCounter.js';
+export { TypeScriptCounter } from './counters/TypeScriptCounter.js';
+export { PythonCounter } from './counters/PythonCounter.js';
+export { JavaCounter } from './counters/JavaCounter.js';
+export { KotlinCounter } from './counters/KotlinCounter.js';
+export { GoCounter } from './counters/GoCounter.js';
+
+export type {
+  ComplexityResult,
+  ComplexityBreakdown,
+  ComplexityFilters,
+  FileComplexityResult,
+  Grade,
+  DecisionPointCounts,
+} from './types.js';

package/src/engine/analyzers/complexity/types.ts

@@ -0,0 +1,62 @@
+/**
+ * KSA-161: Complexity Analyzer — Type definitions.
+ */
+
+export type Grade = 'A' | 'B' | 'C' | 'D' | 'F';
+
+export interface DecisionPointCounts {
+  branches: number;
+  loops: number;
+  logical_ops: number;
+  exception_handlers: number;
+}
+
+export interface ComplexityBreakdown extends DecisionPointCounts {
+  cyclomatic_complexity: number;
+  nesting_depth: number;
+  early_returns: number;
+}
+
+export interface ComplexityResult extends ComplexityBreakdown {
+  symbol_id: number;
+  symbol_name: string;
+  file_path: string;
+  start_line: number;
+  end_line: number;
+  grade: Grade;
+}
+
+export interface FileComplexityResult {
+  file_path: string;
+  functions: ComplexityResult[];
+  average_complexity: number;
+  max_complexity: number;
+  total_functions: number;
+}
+
+export interface ComplexityFilters {
+  filePath?: string;
+  symbolName?: string;
+  minComplexity?: number;
+  gradeFilter?: Grade[];
+  module?: string;
+  limit: number;
+  sortBy: 'complexity' | 'name' | 'file';
+}
+
+export interface ComplexityQueryResult {
+  results: ComplexityResult[];
+  total: number;
+  summary: {
+    average: number;
+    gradeDistribution: Record<Grade, number>;
+  };
+}
+
+export interface GradeThresholds {
+  A: number; // max CC for grade A (default: 5)
+  B: number; // max CC for grade B (default: 10)
+  C: number; // max CC for grade C (default: 20)
+  D: number; // max CC for grade D (default: 50)
+  // F: anything above D threshold
+}