mstro-app 0.5.1 → 0.5.6

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

@@ -4,7 +4,7 @@ import { extname } from 'node:path';
 import { analyzeComplexity, analyzeFunctionLength } from './quality-complexity.js';
 import { computeQualityRating, gradeFromScore } from './quality-grading.js';
 import { analyzeLinting } from './quality-linting.js';
-import { chunkFileList, collectSourceFiles, detectEcosystem, filesByExt, runCommand, type SourceFile } from './quality-tools.js';
+import { chunkFileList, collectSourceFiles, detectEcosystem, filesByExt, isTestFile, runCommand, type SourceFile } from './quality-tools.js';
 import { type CategoryPenalty, type CategoryScore, type DimensionName, type Ecosystem, FILE_LENGTH_THRESHOLD, hasInstalledToolInCategory, type QualityFinding, type QualityResults, type ScanProgress, type ScoreBreakdown, TOTAL_STEPS } from './quality-types.js';
 
 const NODE_FMT_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
@@ -112,6 +112,295 @@ async function analyzeFormatting(
   return { score, available: true, issueCount: acc.totalFiles - acc.passingFiles, findings: acc.findings.slice(0, 50) };
 }
 
+// ============================================================================
+// Build / Compile Error Detection
+// ============================================================================
+//
+// A codebase that does not compile is, by the user's spec, an automatic F.
+// We capture compile failures as `category: 'build'` findings with severity
+// `critical` so they map to the Reliability dimension and trigger the
+// "critical → F-" path through the standard severity logic — no special-
+// case branching elsewhere in the grading module.
+//
+// Per ecosystem:
+//   - Node:   tsc --noEmit (only if a tsconfig.json is present)
+//   - Rust:   cargo check (idiomatic compile-test for crates)
+//   - Other:  skipped — Python has no canonical "is it valid" check, Go
+//             projects vary too much in module structure for `go build ./...`
+//             to be reliable, and Swift/Kotlin compile via larger build
+//             systems we don't want to spawn from a quality scan.
+//
+// Findings are capped at the first 5 errors per check so a totally broken
+// codebase doesn't produce 200 individual findings — one critical finding is
+// enough to pin the grade.
+
+const BUILD_FINDING_CAP = 5;
+
+function tscOutputToFindings(output: string, dirPath: string): QualityFinding[] {
+  const findings: QualityFinding[] = [];
+  // tsc error format: `path/to/file.ts(line,col): error TS####: message`
+  const errorPattern = /^(.+?)\((\d+),\d+\):\s+error\s+TS\d+:\s+(.+)$/gm;
+  for (const match of output.matchAll(errorPattern)) {
+    if (findings.length >= BUILD_FINDING_CAP) break;
+    const filePath = match[1].replace(`${dirPath}/`, '').replace(/^\.\//, '');
+    findings.push({
+      severity: 'critical',
+      category: 'build',
+      file: filePath,
+      line: Number.parseInt(match[2], 10) || null,
+      title: `TypeScript build error`,
+      description: match[3].trim(),
+      suggestion: 'Resolve compile errors before merging — broken builds block all other quality work.',
+    });
+  }
+  return findings;
+}
+
+function cargoCheckOutputToFindings(output: string, dirPath: string): QualityFinding[] {
+  const findings: QualityFinding[] = [];
+  // cargo emits one JSON object per line in --message-format=json mode; in
+  // plain mode it emits "error[E####]: message\n  --> path:line:col"
+  const errorPattern = /^error(?:\[E\d+\])?:\s+(.+?)$\s+-->\s+([^:\s]+):(\d+):\d+/gm;
+  for (const match of output.matchAll(errorPattern)) {
+    if (findings.length >= BUILD_FINDING_CAP) break;
+    findings.push({
+      severity: 'critical',
+      category: 'build',
+      file: match[2].replace(`${dirPath}/`, ''),
+      line: Number.parseInt(match[3], 10) || null,
+      title: `Rust build error`,
+      description: match[1].trim(),
+      suggestion: 'Resolve compile errors before merging — broken builds block all other quality work.',
+    });
+  }
+  return findings;
+}
+
+async function checkNodeBuild(dirPath: string, installed: Set<string> | null): Promise<QualityFinding[]> {
+  // Only run if TypeScript is installed. Avoids npm-installing tsc on the fly
+  // (slow + side-effecting) and cleanly skips JS-only projects.
+  if (installed && !installed.has('typescript')) return [];
+
+  // Only run if a tsconfig.json exists at the project root — otherwise tsc
+  // will pick up arbitrary nearby configs in monorepos and produce confusing
+  // results.
+  let hasTsconfig = false;
+  try {
+    const { readFileSync } = await import('node:fs');
+    readFileSync(`${dirPath}/tsconfig.json`, 'utf-8');
+    hasTsconfig = true;
+  } catch {
+    return [];
+  }
+  if (!hasTsconfig) return [];
+
+  const result = await runCommand('npx', ['tsc', '--noEmit', '--pretty', 'false'], dirPath);
+  if (result.exitCode === 0) return [];
+  // Combine stdout + stderr — tsc writes errors to stdout in --pretty=false.
+  return tscOutputToFindings(`${result.stdout}\n${result.stderr}`, dirPath);
+}
+
+async function checkRustBuild(dirPath: string): Promise<QualityFinding[]> {
+  const result = await runCommand('cargo', ['check', '--message-format=human'], dirPath);
+  if (result.exitCode === 0) return [];
+  return cargoCheckOutputToFindings(`${result.stdout}\n${result.stderr}`, dirPath);
+}
+
+async function analyzeBuildErrors(
+  dirPath: string,
+  ecosystems: Ecosystem[],
+  installed: Set<string> | null,
+): Promise<{ findings: QualityFinding[]; available: boolean }> {
+  const findings: QualityFinding[] = [];
+  let ran = false;
+
+  if (ecosystems.includes('node')) {
+    const nodeFindings = await checkNodeBuild(dirPath, installed);
+    if (nodeFindings.length > 0) ran = true;
+    findings.push(...nodeFindings);
+  }
+  if (ecosystems.includes('rust')) {
+    ran = true;
+    findings.push(...(await checkRustBuild(dirPath)));
+  }
+
+  // `available` only matters for the dimension-availability heuristic; the
+  // findings drive the actual grade. For build, "available" tracks whether
+  // we ran a build check at all (so a clean tsc output still counts).
+  return { findings, available: ran || ecosystems.includes('node') || ecosystems.includes('rust') };
+}
+
+// ============================================================================
+// File Cohesion Analysis (LCOM-inspired)
+// ============================================================================
+//
+// Long files are not all equal. A 1500-line file with one focused public
+// surface (one class, one large function, several private helpers) is fine —
+// it's cohesive. A 1500-line file mixing config + parsing + rendering + IO is
+// a real maintenance hazard.
+//
+// We compute a 0-1 "mixed-concerns score" per file using cheap textual
+// signals (no AST parsing — we already have the file content in memory):
+//
+//   - Top-level export count — many independent exports = many concerns.
+//   - Distinct top-level identifier prefixes — cohesive files share a domain
+//     vocabulary (e.g., everything starts with `User…`); mixed files do not.
+//   - Distinct import roots — files that import from many unrelated modules
+//     are usually doing many unrelated things.
+//   - Section-divider density — `// ===` style dividers signal that the
+//     author is mentally separating concerns; many sections + low export
+//     overlap = mixed.
+//
+// The score then modulates the severity of any file-length violation:
+//
+//   cohesion ≤ 0.30  → SUPPRESS the finding (the file is long but focused)
+//   cohesion ≤ 0.55  → low severity
+//   cohesion ≤ 0.75  → medium severity
+//   cohesion >  0.75 → high severity
+//
+// This implements the user's requirement that a 1000-line file might be
+// "just fine" while another 1000-line file is a "severe mix of concerns."
+// ============================================================================
+
+const TOP_LEVEL_EXPORT_PATTERN = /^export\s+(?:default\s+)?(?:async\s+)?(?:function|class|const|let|var|interface|type|enum)\s+(\w+)/gm;
+const TOP_LEVEL_DECL_PATTERN = /^(?:export\s+)?(?:async\s+)?(?:function|class)\s+(\w+)/gm;
+const PY_TOP_LEVEL_PATTERN = /^(?:def|class)\s+(\w+)/gm;
+const IMPORT_PATTERN = /^(?:import\s+.+from\s+['"]([^'"]+)['"]|from\s+([^\s]+)\s+import|import\s+([^\s]+))/gm;
+const SECTION_DIVIDER_PATTERN = /^\s*(?:\/\/|#)\s*={3,}|^\s*(?:\/\/|#)\s*-{3,}/gm;
+
+/** Group identifiers by their leading word-prefix and return how many distinct groups exist. */
+function distinctIdentifierPrefixes(names: string[]): number {
+  if (names.length === 0) return 0;
+  const prefixes = new Set<string>();
+  for (const name of names) {
+    // Split on camelCase / snake_case boundaries; take the first segment.
+    const first = name.replace(/[A-Z][a-z]+|_+/g, (m, _o, _s) => `
${m.replace(/_/g, '')}`).split('
').filter(Boolean)[0] ?? name;
+    const lowered = first.toLowerCase();
+    if (lowered.length >= 2) prefixes.add(lowered);
+  }
+  return prefixes.size;
+}
+
+/** Extract the path "root" from an import specifier (the first non-dot segment). */
+function importRoot(spec: string): string {
+  const trimmed = spec.replace(/^['"]|['"]$/g, '').trim();
+  if (!trimmed) return '';
+  if (trimmed.startsWith('.')) return 'relative';
+  return trimmed.split('/')[0].replace(/^@/, '');
+}
+
+interface CohesionSignals {
+  exports: number;
+  decls: number;
+  prefixes: number;
+  importRoots: number;
+  dividers: number;
+  isJs: boolean;
+  isPy: boolean;
+}
+
+function jsDeclNames(content: string): { exports: string[]; decls: string[] } {
+  const exports: string[] = [];
+  const decls: string[] = [];
+  for (const match of content.matchAll(TOP_LEVEL_EXPORT_PATTERN)) exports.push(match[1]);
+  for (const match of content.matchAll(TOP_LEVEL_DECL_PATTERN)) decls.push(match[1]);
+  return { exports, decls };
+}
+
+function pyDeclNames(content: string): { exports: string[]; decls: string[] } {
+  const exports: string[] = [];
+  const decls: string[] = [];
+  for (const match of content.matchAll(PY_TOP_LEVEL_PATTERN)) {
+    decls.push(match[1]);
+    // Python doesn't have explicit "export" — public iff it doesn't start with "_".
+    if (!match[1].startsWith('_')) exports.push(match[1]);
+  }
+  return { exports, decls };
+}
+
+function importRootCount(content: string): number {
+  const roots = new Set<string>();
+  for (const match of content.matchAll(IMPORT_PATTERN)) {
+    const spec = match[1] ?? match[2] ?? match[3] ?? '';
+    const root = importRoot(spec);
+    if (root) roots.add(root);
+  }
+  return roots.size;
+}
+
+function collectCohesionSignals(file: SourceFile): CohesionSignals {
+  const ext = extname(file.path).toLowerCase();
+  const isJs = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].includes(ext);
+  const isPy = ['.py', '.pyi'].includes(ext);
+
+  const { exports, decls } = isJs
+    ? jsDeclNames(file.content)
+    : isPy
+      ? pyDeclNames(file.content)
+      : { exports: [], decls: [] };
+
+  const allNames = exports.length > 0 ? exports : decls;
+
+  return {
+    exports: exports.length,
+    decls: decls.length,
+    prefixes: distinctIdentifierPrefixes(allNames),
+    importRoots: importRootCount(file.content),
+    dividers: (file.content.match(SECTION_DIVIDER_PATTERN) || []).length,
+    isJs,
+    isPy,
+  };
+}
+
+/**
+ * Compute a 0-1 "mixed-concerns" score for a file. 0 = highly cohesive,
+ * 1 = many unrelated concerns. The formula combines four signals with
+ * empirically chosen weights — tuned so that:
+ *
+ *   - A 2000-line file with 1 class + helpers scores ~0.15
+ *   - A 2000-line file with 8 unrelated exports scores ~0.85
+ *   - The CLI quality-tools.ts (one domain, many helpers) scores < 0.4
+ *   - A miscellaneous "utils.ts" (string + date + DOM helpers) scores > 0.7
+ *
+ * Returns 0 for files we can't analyze (non-JS/Py), since we don't want to
+ * fabricate a violation for languages we can't introspect.
+ */
+function computeMixedConcernsScore(file: SourceFile): number {
+  const sig = collectCohesionSignals(file);
+  if (!sig.isJs && !sig.isPy) return 0;
+
+  // Each component is independently normalized to [0, 1]; the final score
+  // averages them with slight weighting toward identifier-prefix variance
+  // (the strongest cohesion signal in practice).
+  const exportComponent = sig.exports <= 2 ? 0 : Math.min(1, (sig.exports - 2) / 12);
+  const prefixComponent = sig.prefixes <= 1 ? 0 : Math.min(1, (sig.prefixes - 1) / 6);
+  const importComponent = sig.importRoots <= 4 ? 0 : Math.min(1, (sig.importRoots - 4) / 12);
+  const dividerComponent = sig.dividers <= 2 ? 0 : Math.min(1, (sig.dividers - 2) / 6);
+
+  return Math.min(
+    1,
+    0.30 * prefixComponent +
+    0.30 * exportComponent +
+    0.25 * importComponent +
+    0.15 * dividerComponent,
+  );
+}
+
+/**
+ * Map a file's mixed-concerns score to a severity for the file-length
+ * finding. Returns `null` to suppress the finding entirely when the file is
+ * cohesive enough that its length isn't a real concern.
+ */
+function severityFromCohesion(mixed: number, lines: number): QualityFinding['severity'] | null {
+  // Files that are absurdly long (>5x threshold) emit a finding regardless
+  // of cohesion — a 5000-line file is always worth flagging even if focused.
+  const isAbsurd = lines > FILE_LENGTH_THRESHOLD * 5;
+  if (mixed <= 0.30 && !isAbsurd) return null;
+  if (mixed <= 0.55) return 'low';
+  if (mixed <= 0.75) return 'medium';
+  return 'high';
+}
+
 // ============================================================================
 // File Length Analysis
 // ============================================================================
@@ -121,28 +410,53 @@ function analyzeFileLength(files: SourceFile[]): { score: number; findings: Qual
 
   const findings: QualityFinding[] = [];
   let totalScore = 0;
+  let scoredFiles = 0;
 
   for (const file of files) {
+    // Test files are exempt from structural-length checks: a long test file
+    // is normally just many independent small tests, which is a feature.
+    // Excluding them from both scoring and finding emission keeps the
+    // dimension's score honest (otherwise a clean prod codebase with a
+    // huge test file would be unfairly penalised on file-length).
+    if (isTestFile(file.relativePath)) continue;
+
     const ratio = Math.max(1, file.lines / FILE_LENGTH_THRESHOLD);
     const fileScore = 100 / ratio ** 1.5;
     totalScore += fileScore;
+    scoredFiles++;
 
     if (file.lines > FILE_LENGTH_THRESHOLD) {
+      const mixedScore = computeMixedConcernsScore(file);
+      const severity = severityFromCohesion(mixedScore, file.lines);
+      if (!severity) continue; // Cohesive long file — not actually a violation.
+
+      const cohesionPct = Math.round((1 - mixedScore) * 100);
       findings.push({
-        severity: file.lines > FILE_LENGTH_THRESHOLD * 3 ? 'high' : file.lines > FILE_LENGTH_THRESHOLD * 2 ? 'medium' : 'low',
+        severity,
         category: 'file-length',
         file: file.relativePath,
         line: null,
-        title: `File has ${file.lines} lines (threshold: ${FILE_LENGTH_THRESHOLD})`,
-        description: `This file exceeds the recommended length of ${FILE_LENGTH_THRESHOLD} lines by ${file.lines - FILE_LENGTH_THRESHOLD} lines.`,
+        title: `File has ${file.lines} lines (threshold: ${FILE_LENGTH_THRESHOLD}, cohesion: ${cohesionPct}%)`,
+        description:
+          `Exceeds the ${FILE_LENGTH_THRESHOLD}-line threshold by ${file.lines - FILE_LENGTH_THRESHOLD} lines. ` +
+          `Mixed-concerns score is ${roundOne(mixedScore)} (0 = focused, 1 = many concerns); ` +
+          `severity reflects how mixed the file's responsibilities appear. ` +
+          (mixedScore > 0.55
+            ? 'Consider splitting unrelated exports into separate modules.'
+            : 'The file is long but reasonably focused — split only if a clear seam exists.'),
       });
     }
   }
 
-  const score = Math.round(totalScore / files.length);
+  if (scoredFiles === 0) return { score: 100, findings: [], issueCount: 0 };
+  const score = Math.round(totalScore / scoredFiles);
   return { score: Math.min(100, score), findings: findings.slice(0, 50), issueCount: findings.length };
 }
 
+function roundOne(n: number): number {
+  return Math.round(n * 10) / 10;
+}
+
 // ============================================================================
 // Legacy Scoring Breakdown — produces the per-category penalty data still
 // consumed by older UI surfaces and persisted reports. The canonical grade
@@ -254,10 +568,27 @@ export function computeFormulaScore(
 
 export type ProgressCallback = (progress: ScanProgress) => void;
 
+/**
+ * Sentinel thrown when a scan is cancelled mid-flight via the `signal`
+ * argument. Callers should treat it as a clean cancellation, not a scan
+ * failure (no `qualityError` payload, no persisted partial result).
+ */
+export class QualityScanAbortedError extends Error {
+  constructor() {
+    super('Quality scan aborted');
+    this.name = 'QualityScanAbortedError';
+  }
+}
+
+function checkAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new QualityScanAbortedError();
+}
+
 export async function runQualityScan(
   dirPath: string,
   onProgress?: ProgressCallback,
   installedToolNames?: string[],
+  signal?: AbortSignal,
 ): Promise<QualityResults> {
   const ecosystems = detectEcosystem(dirPath);
 
@@ -269,10 +600,12 @@ export async function runQualityScan(
   };
 
   // Step 1: Collect source files
+  checkAborted(signal);
   progress('Collecting source files', 1);
   const files = await collectSourceFiles(dirPath, dirPath);
 
   // Step 2: Run linting (only if a linter is installed)
+  checkAborted(signal);
   progress('Running linters', 2);
   const hasLinter = !installedSet || hasInstalledToolInCategory(installedSet, ecosystems, 'linter');
   const lintResult = hasLinter
@@ -280,28 +613,39 @@ export async function runQualityScan(
     : { score: 0, findings: [], available: false, issueCount: 0 };
 
   // Step 3: Check formatting (only if a formatter is installed)
+  checkAborted(signal);
   progress('Checking formatting', 3);
   const hasFormatter = !installedSet || hasInstalledToolInCategory(installedSet, ecosystems, 'formatter');
   const fmtResult = hasFormatter
     ? await analyzeFormatting(dirPath, ecosystems, files)
     : { score: 0, available: false, issueCount: 0, findings: [] as QualityFinding[] };
 
-  // Step 4: Analyze complexity (using real tools: Biome, ESLint, radon)
-  progress('Analyzing complexity', 4);
+  // Step 4: Check for build/compile errors (auto-F if any are found)
+  checkAborted(signal);
+  progress('Checking build', 4);
+  const buildResult = await analyzeBuildErrors(dirPath, ecosystems, installedSet);
+
+  // Step 5: Analyze complexity (using real tools: Biome, ESLint, radon)
+  checkAborted(signal);
+  progress('Analyzing complexity', 5);
   const complexityResult = await analyzeComplexity(dirPath, ecosystems, files, installedToolNames);
 
-  // Step 5: Check file lengths
-  progress('Checking file lengths', 5);
+  // Step 6: Check file lengths
+  checkAborted(signal);
+  progress('Checking file lengths', 6);
   const fileLengthResult = analyzeFileLength(files);
 
-  // Step 6: Check function lengths
-  progress('Checking function lengths', 6);
+  // Step 7: Check function lengths
+  checkAborted(signal);
+  progress('Checking function lengths', 7);
   const funcLengthResult = analyzeFunctionLength(files);
 
-  // Step 7: Compute scores
-  progress('Computing scores', 7);
+  // Step 8: Compute scores
+  checkAborted(signal);
+  progress('Computing scores', 8);
 
   const allFindings = [
+    ...buildResult.findings,
     ...lintResult.findings,
     ...fmtResult.findings,
     ...complexityResult.findings,
@@ -323,7 +667,11 @@ export async function runQualityScan(
   }
   const rating = computeQualityRating(allFindings, totalLines, { forceNA });
 
+  // Build score: 100 if no compile errors, 0 if any (one error breaks everything).
+  const buildScore = buildResult.findings.length === 0 ? 100 : 0;
+
   const categories: CategoryScore[] = [
+    { name: 'Build', score: buildScore, available: buildResult.available, issueCount: buildResult.findings.length },
     { name: 'Linting', score: lintResult.score, available: lintResult.available, issueCount: lintResult.issueCount },
     { name: 'Formatting', score: fmtResult.score, available: fmtResult.available, issueCount: fmtResult.issueCount },
     { name: 'Complexity', score: complexityResult.score, available: complexityResult.available, issueCount: complexityResult.issueCount },

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

@@ -260,6 +260,57 @@ export function filesByExt(files: SourceFile[], exts: string[]): string[] {
   return out;
 }
 
+/** Folders that signal "this whole tree is test code" by convention. */
+const TEST_FOLDER_SEGMENTS = ['__tests__', '__mocks__', 'tests', 'test', 'e2e', 'spec'];
+
+/** Filename regexes that mark a single file as a test, regardless of folder. */
+const TEST_FILE_PATTERNS: RegExp[] = [
+  /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|mts|cts)$/, // JS/TS .test/.spec
+  /_test\.(go|py)$/,                                  // Go / Python *_test
+  /^test_.+\.py$/,                                    // Python test_*.py
+];
+
+function pathHasTestFolder(path: string): boolean {
+  for (const segment of TEST_FOLDER_SEGMENTS) {
+    if (path.includes(`/${segment}/`) || path.startsWith(`${segment}/`)) return true;
+  }
+  return false;
+}
+
+function fileNameLooksLikeTest(name: string): boolean {
+  for (const pattern of TEST_FILE_PATTERNS) {
+    if (pattern.test(name)) return true;
+  }
+  return false;
+}
+
+/**
+ * Identify a path as a test/spec file. Test files are exempt from
+ * structural-length checks (long-file, long-function) because:
+ *
+ *   - A 600-line test file with 50 small `it()` blocks is easy to read,
+ *     each block is independent, and "split it" yields zero maintenance
+ *     benefit while harming discoverability.
+ *   - A 200-line test function (long Arrange-Act-Assert with helpers
+ *     inlined) is normal for feature coverage and not a complexity smell.
+ *
+ * Linters and security/bug findings still apply to test files — only the
+ * structural-length heuristics defer. Pattern-matches the conventions used
+ * by Code Climate's default-exclude set:
+ *
+ *   - JS/TS:  *.test.ts, *.test.tsx, *.spec.js, *.spec.jsx, *.test.mts, ...
+ *   - Folder: __tests__/, /tests/, /test/, e2e/, spec/, __mocks__/
+ *   - Python: test_*.py, *_test.py
+ *   - Go:     *_test.go
+ *   - Rust:   files inside `tests/` are integration tests by convention
+ */
+export function isTestFile(relativePath: string): boolean {
+  const path = relativePath.replace(/\\/g, '/').toLowerCase();
+  if (pathHasTestFolder(path)) return true;
+  const name = path.split('/').pop() ?? path;
+  return fileNameLooksLikeTest(name);
+}
+
 /**
  * Split a file list into chunks so a single command invocation doesn't
  * blow past ARG_MAX. macOS ARG_MAX is ~256KB; 400 paths at ~200 chars each

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

@@ -4,7 +4,27 @@
 // Types
 // ============================================================================
 
-export type Grade = 'A' | 'B' | 'C' | 'D' | 'F' | 'N/A';
+/**
+ * Letter grades produced by the multi-dimensional quality rating.
+ *
+ * Score → grade mapping (per product spec — note: no `D`; F covers 56-69, F-
+ * covers 0-55. `D` is retained ONLY for backward compatibility with reports
+ * persisted by older versions of this module — new code never emits it):
+ *
+ *   A+  97-100   A   93-96    A-  90-92
+ *   B+  87-89    B   83-86    B-  80-82
+ *   C+  77-79    C   73-76    C-  70-72
+ *   F+  65-69    F   56-64    F-  0-55
+ *
+ * `N/A` means the dimension had no tooling available to evaluate it.
+ */
+export type Grade =
+  | 'A+' | 'A' | 'A-'
+  | 'B+' | 'B' | 'B-'
+  | 'C+' | 'C' | 'C-'
+  | 'D' // legacy — only appears on reports persisted before the +/- rollout
+  | 'F+' | 'F' | 'F-'
+  | 'N/A';
 export type DimensionName = 'security' | 'reliability' | 'maintainability';
 
 export interface DimensionScore {
@@ -80,12 +100,31 @@ export interface QualityResults {
   dimensions?: DimensionScore[];
   qualityGate?: QualityGate;
   gradeRationale?: string;
+  /** Wall-clock duration of the CLI scan that produced this report. Used to estimate ETA on subsequent scans of the same directory. */
+  scanDurationMs?: number;
+  /** Wall-clock duration of the AI code-review pass, when one ran. */
+  reviewDurationMs?: number;
 }
 
 export interface ScanProgress {
   step: string;
   current: number;
   total: number;
+  /**
+   * Wall-clock estimate of the total scan duration, in milliseconds. Sent on
+   * the first progress event of a scan and again on subsequent events so
+   * reconnecting clients still get an ETA. The web subtracts elapsed time to
+   * render "≈ X remaining".
+   */
+  etaMs?: number;
+  /**
+   * Server-side timestamp (ms since epoch) of when the scan started — paired
+   * with `etaMs` so the web can compute elapsed time without trusting its
+   * own clock alignment.
+   */
+  startedAt?: number;
+  /** Optional sub-step detail used by long-running steps (e.g. "tsc --noEmit, 18s elapsed") to keep the UI from looking stuck. */
+  detail?: string;
 }
 
 export type Ecosystem = 'node' | 'python' | 'rust' | 'go' | 'swift' | 'kotlin' | 'unknown';
@@ -161,7 +200,7 @@ export const ADDITIONAL_EXCLUDES = new Set([
 
 export const FILE_LENGTH_THRESHOLD = 300;
 export const FUNCTION_LENGTH_THRESHOLD = 50;
-export const TOTAL_STEPS = 7;
+export const TOTAL_STEPS = 8;
 
 export function hasInstalledToolInCategory(
   installedSet: Set<string>,