mstro-app 0.5.0 → 0.5.5

package/server/services/websocket/quality-complexity.ts

@@ -1,8 +1,7 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { extname, relative } from 'node:path';
-import { chunkFileList, filesByExt, runCommand, type SourceFile } from './quality-tools.js';
+import { chunkFileList, filesByExt, isTestFile, runCommand, type SourceFile } from './quality-tools.js';
 import { biomeDiagToFinding, type Ecosystem, FUNCTION_LENGTH_THRESHOLD, isBiomeComplexityDiagnostic, isEslintComplexityRule, type QualityFinding } from './quality-types.js';
 
 const NODE_COMPLEXITY_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
@@ -17,6 +16,26 @@ interface FunctionInfo {
   file: string;
   startLine: number;
   lines: number;
+  /** Approximate cyclomatic complexity (count of decision points). */
+  branches: number;
+}
+
+/**
+ * Decision-point keywords that approximate cyclomatic complexity. We count
+ * occurrences as a cheap proxy — McCabe's exact metric requires AST parsing,
+ * but the keyword count is highly correlated and good enough to distinguish
+ * "long but linear" (a flat sequence of statements) from "long and branchy"
+ * (deeply nested control flow).
+ *
+ * The user's task 2 requirement: "a 1000 line file might be just fine, not
+ * a violation at all, while another 1000 line file might be a severe mix of
+ * concerns" — same applies to functions. A long config-builder with one
+ * return statement is fine; a long monster with 40 if-branches is not.
+ */
+const BRANCH_KEYWORDS = /\b(?:if|else if|elif|for|while|case|catch|\?\s*\w|&&|\|\||\?\?)\b/g;
+
+function countBranches(body: string): number {
+  return (body.match(BRANCH_KEYWORDS) || []).length;
 }
 
 const JS_FUNC_PATTERN = /^(\s*)(export\s+)?(async\s+)?function\s+(\w+)|^(\s*)(export\s+)?(const|let|var)\s+(\w+)\s*=\s*(async\s+)?\(|^(\s*)(public|private|protected)?\s*(async\s+)?(\w+)\s*\(/;
@@ -57,11 +76,15 @@ function extractJsFunctions(file: SourceFile): FunctionInfo[] {
     braceDepth += countBraceDeltas(lines[i]);
 
     if (currentFunc && braceDepth <= funcStartBraceDepth && i > currentFunc.startLine - 1) {
+      const startLine = currentFunc.startLine;
+      const endLine = i + 1;
+      const body = lines.slice(startLine - 1, endLine).join('\n');
       functions.push({
         name: currentFunc.name,
         file: file.relativePath,
-        startLine: currentFunc.startLine,
-        lines: i + 1 - currentFunc.startLine + 1,
+        startLine,
+        lines: endLine - startLine + 1,
+        branches: countBranches(body),
       });
       currentFunc = null;
     }
@@ -76,35 +99,29 @@ function extractPyFunctions(file: SourceFile): FunctionInfo[] {
   const defPattern = /^(\s*)(async\s+)?def\s+(\w+)/;
   let currentFunc: { name: string; startLine: number; indent: number } | null = null;
 
+  const recordFunction = (name: string, startLine: number, endLine: number) => {
+    const body = lines.slice(startLine - 1, endLine).join('\n');
+    functions.push({
+      name,
+      file: file.relativePath,
+      startLine,
+      lines: endLine - startLine + 1,
+      branches: countBranches(body),
+    });
+  };
+
   for (let i = 0; i < lines.length; i++) {
     const match = defPattern.exec(lines[i]);
     if (match) {
-      if (currentFunc) {
-        functions.push({
-          name: currentFunc.name,
-          file: file.relativePath,
-          startLine: currentFunc.startLine,
-          lines: i - currentFunc.startLine + 1,
-        });
-      }
+      if (currentFunc) recordFunction(currentFunc.name, currentFunc.startLine, i);
       currentFunc = { name: match[3], startLine: i + 1, indent: match[1].length };
     } else if (currentFunc && lines[i].trim() && !lines[i].startsWith(' '.repeat(currentFunc.indent + 1)) && !lines[i].startsWith('\t')) {
-      functions.push({
-        name: currentFunc.name,
-        file: file.relativePath,
-        startLine: currentFunc.startLine,
-        lines: i - currentFunc.startLine + 1,
-      });
+      recordFunction(currentFunc.name, currentFunc.startLine, i);
       currentFunc = null;
     }
   }
   if (currentFunc) {
-    functions.push({
-      name: currentFunc.name,
-      file: file.relativePath,
-      startLine: currentFunc.startLine,
-      lines: lines.length - currentFunc.startLine + 1,
-    });
+    recordFunction(currentFunc.name, currentFunc.startLine, lines.length);
   }
 
   return functions;
@@ -117,9 +134,37 @@ function extractFunctions(file: SourceFile): FunctionInfo[] {
   return [];
 }
 
+/**
+ * Map a function's branch density (decision points per N lines) to a
+ * severity level for the function-length finding. Returns `null` to suppress
+ * the finding for a long but linear function — e.g., a config-builder with
+ * one return statement and 200 lines of property assignments.
+ *
+ * Heuristic: McCabe's cyclomatic complexity threshold is ~10. Above that,
+ * functions are hard to test. We grade severity by branches-per-50-lines so
+ * a 100-line function with 5 branches looks the same as a 50-line function
+ * with 5 branches (both ~industry "consider refactoring" zone).
+ *
+ * Functions absurdly long (>5x threshold) emit a finding regardless of
+ * branchiness — a 250-line function is too much to read in one sitting even
+ * if it's "linear."
+ */
+function severityFromBranchiness(branches: number, lines: number): QualityFinding['severity'] | null {
+  const branchesPer50 = (branches * 50) / Math.max(1, lines);
+  const isAbsurd = lines > FUNCTION_LENGTH_THRESHOLD * 5;
+  if (branchesPer50 < 3 && !isAbsurd) return null; // Long but linear — not really a violation.
+  if (branchesPer50 < 6) return 'low';
+  if (branchesPer50 < 10) return 'medium';
+  return 'high';
+}
+
 export function analyzeFunctionLength(files: SourceFile[]): { score: number; findings: QualityFinding[]; issueCount: number } {
   const allFunctions: FunctionInfo[] = [];
   for (const file of files) {
+    // Test files are exempt: a long `it()`/`describe()` body is normal and
+    // splitting it produces churn without improving readability. Linting
+    // and other quality checks still apply — only structural-length defers.
+    if (isTestFile(file.relativePath)) continue;
     allFunctions.push(...extractFunctions(file));
   }
 
@@ -134,13 +179,21 @@ export function analyzeFunctionLength(files: SourceFile[]): { score: number; fin
     totalScore += funcScore;
 
     if (func.lines > FUNCTION_LENGTH_THRESHOLD) {
+      const severity = severityFromBranchiness(func.branches, func.lines);
+      if (!severity) continue; // Long but linear — not flagged.
+
       findings.push({
-        severity: func.lines > FUNCTION_LENGTH_THRESHOLD * 3 ? 'high' : func.lines > FUNCTION_LENGTH_THRESHOLD * 2 ? 'medium' : 'low',
+        severity,
         category: 'function-length',
         file: func.file,
         line: func.startLine,
-        title: `${func.name}() has ${func.lines} lines (threshold: ${FUNCTION_LENGTH_THRESHOLD})`,
-        description: `Function "${func.name}" exceeds the recommended length by ${func.lines - FUNCTION_LENGTH_THRESHOLD} lines.`,
+        title: `${func.name}() has ${func.lines} lines, ~${func.branches} branches`,
+        description:
+          `Function "${func.name}" exceeds the ${FUNCTION_LENGTH_THRESHOLD}-line threshold by ${func.lines - FUNCTION_LENGTH_THRESHOLD} lines ` +
+          `with approximately ${func.branches} decision points (cyclomatic complexity proxy). ` +
+          (severity === 'high'
+            ? 'High branchiness makes this hard to test and review — extract sub-functions or simplify control flow.'
+            : 'Long but with manageable branching — consider extracting helpers if the function does multiple things.'),
       });
     }
   }

package/server/services/websocket/quality-eta.ts

@@ -0,0 +1,155 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Quality ETA — duration estimation for scan + AI review operations.
+ *
+ * Uses persisted history when available (most accurate), falls back to a
+ * simple heuristic derived from file count + line count when there is no
+ * history yet (cold start).
+ *
+ * Estimates are intentionally conservative: better to over-estimate by a bit
+ * and have the bar finish "early" than to under-estimate and have the bar
+ * sit at 100% while work continues — the latter destroys trust in the ETA.
+ */
+
+import type { QualityHistoryEntry } from './quality-persistence.js';
+
+// ── Heuristic constants ──────────────────────────────────────
+//
+// Numbers tuned against typical TypeScript codebases (mstro cli/server/web)
+// observed in the wild — see history.json for the corpus. Treat them as
+// reasonable defaults that the history-based path will quickly correct once
+// real durations land in storage.
+
+/** Per-file overhead for a CLI scan (linting, formatting, file/function-length checks). */
+const SCAN_PER_FILE_MS = 250;
+/** Per-1000-LOC overhead for a CLI scan, dominated by `tsc --noEmit` on TS projects. */
+const SCAN_PER_KLOC_MS = 800;
+/** Fixed overhead per scan: tool detection, file collection, score computation. */
+const SCAN_FIXED_MS = 8_000;
+/** Floor — the smallest "I'm doing something" we should ever show. */
+const SCAN_MIN_MS = 5_000;
+
+/** Per-file overhead for the AI code-review agent (Claude Read calls, validation). */
+const REVIEW_PER_FILE_MS = 1_200;
+/** Per-1000-LOC overhead for the AI code-review agent. */
+const REVIEW_PER_KLOC_MS = 2_500;
+/** Fixed overhead per review: Claude spawn, prompt building, persistence. */
+const REVIEW_FIXED_MS = 25_000;
+/** Floor for the review estimate. */
+const REVIEW_MIN_MS = 30_000;
+
+// ── History smoothing ────────────────────────────────────────
+//
+// Use the last few real durations for the same directory and weight them by
+// recency. A single one-off slow run shouldn't dominate the estimate, but
+// fresh data should outweigh stale data (codebase grew, machine got faster,
+// etc.).
+const MAX_HISTORY_SAMPLES = 5;
+
+interface HistoryEntryWithTimings extends QualityHistoryEntry {
+  scanDurationMs?: number;
+  reviewDurationMs?: number;
+}
+
+function recentDurations(
+  history: HistoryEntryWithTimings[],
+  dirPath: string,
+  field: 'scanDurationMs' | 'reviewDurationMs',
+): number[] {
+  const values: number[] = [];
+  // Walk newest → oldest; only consider entries that actually touched this directory.
+  for (let i = history.length - 1; i >= 0 && values.length < MAX_HISTORY_SAMPLES; i--) {
+    const entry = history[i];
+    if (!entry.directories.some((d) => d.path === dirPath)) continue;
+    const v = entry[field];
+    if (typeof v === 'number' && v > 0) values.push(v);
+  }
+  return values;
+}
+
+/**
+ * Weighted average favouring newer samples. Weights are 1, 2, 3, 4, 5 for the
+ * 5 most-recent runs (newest first → highest weight) — a "this run mostly
+ * matters" curve that still smooths over a single anomaly.
+ */
+function weightedRecentAverage(values: number[]): number | null {
+  if (values.length === 0) return null;
+  let weightSum = 0;
+  let valueSum = 0;
+  // values[0] is newest, so its weight is `values.length`.
+  for (let i = 0; i < values.length; i++) {
+    const w = values.length - i;
+    valueSum += values[i] * w;
+    weightSum += w;
+  }
+  return weightSum > 0 ? valueSum / weightSum : null;
+}
+
+// ── Public API ────────────────────────────────────────────────
+
+export interface CodebaseSize {
+  /** Number of source files the scan/review will analyse. */
+  files: number;
+  /** Total lines across those files. */
+  lines: number;
+}
+
+/**
+ * Heuristic estimate for a CLI scan when we have no history. Combines a fixed
+ * floor with per-file + per-KLOC components — `tsc --noEmit` and lint scale
+ * with codebase size, so scaling on both files and lines maps reality better
+ * than scaling on either alone.
+ */
+export function heuristicScanMs({ files, lines }: CodebaseSize): number {
+  const kloc = Math.max(0, lines) / 1_000;
+  const raw = SCAN_FIXED_MS + files * SCAN_PER_FILE_MS + kloc * SCAN_PER_KLOC_MS;
+  return Math.max(SCAN_MIN_MS, Math.round(raw));
+}
+
+/** Heuristic estimate for the AI review agent when we have no history. */
+export function heuristicReviewMs({ files, lines }: CodebaseSize): number {
+  const kloc = Math.max(0, lines) / 1_000;
+  const raw = REVIEW_FIXED_MS + files * REVIEW_PER_FILE_MS + kloc * REVIEW_PER_KLOC_MS;
+  return Math.max(REVIEW_MIN_MS, Math.round(raw));
+}
+
+/**
+ * Best-available ETA for a CLI scan. Prefers a weighted average of recent
+ * durations for this exact directory; falls back to the heuristic when no
+ * timing history exists.
+ */
+export function estimateScanMs(
+  size: CodebaseSize,
+  history: HistoryEntryWithTimings[],
+  dirPath: string,
+): number {
+  const recent = recentDurations(history, dirPath, 'scanDurationMs');
+  const fromHistory = weightedRecentAverage(recent);
+  if (fromHistory !== null) return Math.max(SCAN_MIN_MS, Math.round(fromHistory));
+  return heuristicScanMs(size);
+}
+
+/** Best-available ETA for the AI code-review agent. Same fallback shape as `estimateScanMs`. */
+export function estimateReviewMs(
+  size: CodebaseSize,
+  history: HistoryEntryWithTimings[],
+  dirPath: string,
+): number {
+  const recent = recentDurations(history, dirPath, 'reviewDurationMs');
+  const fromHistory = weightedRecentAverage(recent);
+  if (fromHistory !== null) return Math.max(REVIEW_MIN_MS, Math.round(fromHistory));
+  return heuristicReviewMs(size);
+}
+
+/**
+ * Estimate codebase size from a directory using the same fast traversal the
+ * scan itself uses. Pulled out as a thin wrapper so the handler can call it
+ * before kicking off the scan to compute an initial ETA.
+ */
+export async function estimateCodebaseSize(dirPath: string): Promise<CodebaseSize> {
+  const { collectSourceFiles } = await import('./quality-tools.js');
+  const files = await collectSourceFiles(dirPath, dirPath);
+  const lines = files.reduce((sum, f) => sum + f.lines, 0);
+  return { files: files.length, lines };
+}