mstro-app 0.4.52 → 0.5.1

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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Quality Persistence — Persists quality config, reports, and history
@@ -13,6 +12,7 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { gradeFromScore } from './quality-grading.js';
 import type { QualityResults } from './quality-service.js';
 
 // ============================================================================
@@ -46,6 +46,11 @@ export interface QualityHistoryEntry {
   grade: string;
   issueDensity?: number;
   categoryScores?: HistoryCategoryScore[];
+  dimensionScores?: {
+    security: { score: number; grade: string };
+    reliability: { score: number; grade: string };
+    maintainability: { score: number; grade: string };
+  };
   directories: HistoryDirectoryEntry[];
 }
 
@@ -232,6 +237,7 @@ export class QualityPersistence {
       : undefined;
 
     const issueDensity = results.scoreBreakdown?.issueDensity;
+    const dimensionScores = extractDimensionScores(results);
 
     if (lastEntry && now.getTime() - lastTime < mergeWindow) {
       const existing = lastEntry.directories.findIndex((d) => d.path === dirPath);
@@ -242,10 +248,15 @@ export class QualityPersistence {
       }
       const totalScore = lastEntry.directories.reduce((sum, d) => sum + d.score, 0);
       lastEntry.overall = Math.round(totalScore / lastEntry.directories.length);
-      lastEntry.grade = gradeFromScore(lastEntry.overall);
+      // Preserve N/A when every directory is N/A; otherwise map averaged score
+      // back to a letter. `gradeFromScore` returns A-F only, so this is the
+      // only place the N/A signal could be lost during multi-directory merges.
+      const allNA = lastEntry.directories.every((d) => d.grade === 'N/A');
+      lastEntry.grade = allNA ? 'N/A' : gradeFromScore(lastEntry.overall);
       lastEntry.timestamp = now.toISOString();
       if (categoryScores) lastEntry.categoryScores = categoryScores;
       if (issueDensity !== undefined) lastEntry.issueDensity = issueDensity;
+      if (dimensionScores) lastEntry.dimensionScores = dimensionScores;
     } else {
       history.push({
         timestamp: now.toISOString(),
@@ -253,6 +264,7 @@ export class QualityPersistence {
         grade: results.grade,
         issueDensity,
         categoryScores,
+        dimensionScores,
         directories: [dirEntry],
       });
     }
@@ -361,10 +373,20 @@ export class QualityPersistence {
   }
 }
 
-function gradeFromScore(score: number): string {
-  if (score >= 90) return 'A';
-  if (score >= 80) return 'B';
-  if (score >= 70) return 'C';
-  if (score >= 60) return 'D';
-  return 'F';
+// Snapshot per-dimension scores when the new rating fields are present.
+// Older `QualityResults` objects (e.g., loaded from pre-redesign reports)
+// omit `dimensions`, in which case we return undefined so old history rows
+// continue to round-trip without synthesized data.
+function extractDimensionScores(results: QualityResults): QualityHistoryEntry['dimensionScores'] | undefined {
+  if (!results.dimensions) return undefined;
+  const byName = new Map(results.dimensions.map((d) => [d.name, d]));
+  const sec = byName.get('security');
+  const rel = byName.get('reliability');
+  const maint = byName.get('maintainability');
+  if (!sec || !rel || !maint) return undefined;
+  return {
+    security: { score: sec.score, grade: sec.grade },
+    reliability: { score: rel.score, grade: rel.grade },
+    maintainability: { score: maint.score, grade: maint.grade },
+  };
 }

package/server/services/websocket/quality-review-agent.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Quality Review Agent — AI-powered code review using Claude Code headless runner.
@@ -428,7 +427,7 @@ async function runVerificationPass(
       policy: 'STANDARD',
       stallWarningMs: 300_000,
       stallKillMs: 900_000,
-      stallHardCapMs: 1_200_000,
+      stallHardCapMs: 3_600_000,
       toolUseCallback: makeToolCallback(send, 'Verifying: '),
       logLabel: 'code-review-verify',
     });
@@ -505,7 +504,7 @@ export async function handleCodeReview(
       policy: 'STANDARD',
       stallWarningMs: 300_000,
       stallKillMs: 1_200_000,
-      stallHardCapMs: 1_800_000,
+      stallHardCapMs: 7_200_000,
       toolUseCallback: makeToolCallback(send),
       logLabel: 'code-review',
     });

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

@@ -1,11 +1,11 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 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 { type CategoryPenalty, type CategoryScore, type Ecosystem, FILE_LENGTH_THRESHOLD, hasInstalledToolInCategory, type QualityFinding, type QualityResults, type ScanProgress, type ScoreBreakdown, TOTAL_STEPS } from './quality-types.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'];
 const PY_FMT_EXTS = ['.py', '.pyi'];
@@ -144,15 +144,20 @@ function analyzeFileLength(files: SourceFile[]): { score: number; findings: Qual
 }
 
 // ============================================================================
-// Deterministic Scoring — penalty-density exponential decay
+// Legacy Scoring Breakdown — produces the per-category penalty data still
+// consumed by older UI surfaces and persisted reports. The canonical grade
+// now comes from the multi-dimensional `computeQualityRating`; this function
+// only fills in `scoreBreakdown` so existing dashboards keep rendering.
 // ============================================================================
 
+/**
+ * Score-to-grade conversion for legacy callers. Delegates to the shared
+ * grading module so there is one source of truth. Returns `string` to satisfy
+ * the wider `QualityResults.grade` field — `gradeFromScore` itself never
+ * returns the `'N/A'` variant of the shared `Grade` union.
+ */
 function computeGrade(score: number): string {
-  if (score >= 90) return 'A';
-  if (score >= 80) return 'B';
-  if (score >= 70) return 'C';
-  if (score >= 60) return 'D';
-  return 'F';
+  return gradeFromScore(score);
 }
 
 const SEVERITY_WEIGHT: Record<string, number> = {
@@ -305,54 +310,30 @@ export async function runQualityScan(
   ];
 
   const totalLines = files.reduce((sum, f) => sum + f.lines, 0);
-  const { score: overall, breakdown } = computeFormulaScore(allFindings, totalLines);
+  // Legacy breakdown — drives the per-category panels and persisted `scoreBreakdown`.
+  const { breakdown } = computeFormulaScore(allFindings, totalLines);
+  // Canonical multi-dimensional rating — drives `overall`, `grade`, and the
+  // new dimensions/qualityGate/gradeRationale fields. Force Maintainability
+  // to N/A when no real maintainability tool ran (file/function length alone
+  // would otherwise let a clean codebase claim grade A even though linting
+  // was never checked).
+  const forceNA = new Set<DimensionName>();
+  if (!hasLinter && !hasFormatter && !complexityResult.available) {
+    forceNA.add('maintainability');
+  }
+  const rating = computeQualityRating(allFindings, totalLines, { forceNA });
 
   const categories: CategoryScore[] = [
-    {
-      name: 'Linting',
-      score: lintResult.score,
-      weight: 0,
-      effectiveWeight: 0,
-      available: lintResult.available,
-      issueCount: lintResult.issueCount,
-    },
-    {
-      name: 'Formatting',
-      score: fmtResult.score,
-      weight: 0,
-      effectiveWeight: 0,
-      available: fmtResult.available,
-      issueCount: fmtResult.issueCount,
-    },
-    {
-      name: 'Complexity',
-      score: complexityResult.score,
-      weight: 0,
-      effectiveWeight: 0,
-      available: complexityResult.available,
-      issueCount: complexityResult.issueCount,
-    },
-    {
-      name: 'File Length',
-      score: fileLengthResult.score,
-      weight: 0,
-      effectiveWeight: 0,
-      available: true,
-      issueCount: fileLengthResult.issueCount,
-    },
-    {
-      name: 'Function Length',
-      score: funcLengthResult.score,
-      weight: 0,
-      effectiveWeight: 0,
-      available: true,
-      issueCount: funcLengthResult.issueCount,
-    },
+    { 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 },
+    { name: 'File Length', score: fileLengthResult.score, available: true, issueCount: fileLengthResult.issueCount },
+    { name: 'Function Length', score: funcLengthResult.score, available: true, issueCount: funcLengthResult.issueCount },
   ];
 
   return {
-    overall,
-    grade: computeGrade(overall),
+    overall: rating.overall.score,
+    grade: rating.overall.grade,
     categories,
     findings: allFindings.slice(0, 200),
     codeReview: [],
@@ -361,6 +342,9 @@ export async function runQualityScan(
     timestamp: new Date().toISOString(),
     ecosystem: ecosystems,
     scoreBreakdown: breakdown,
+    dimensions: rating.dimensions,
+    qualityGate: rating.qualityGate,
+    gradeRationale: rating.gradeRationale,
   };
 }
 
@@ -370,20 +354,35 @@ export async function runQualityScan(
 
 /**
  * Recompute the overall score after AI code review findings become available.
- * Merges CLI + AI findings and runs the deterministic penalty-density formula.
+ * Merges CLI + AI findings, runs the canonical multi-dimensional rating, and
+ * recomputes the legacy `scoreBreakdown` so both new and old UI surfaces stay
+ * in sync after the merge.
  */
 export function recomputeWithAiReview(
   results: QualityResults,
   aiFindings: Array<{ severity: string; category: string }>,
 ): QualityResults {
   const allFindings = [...results.findings, ...aiFindings];
-  const { score: overall, breakdown } = computeFormulaScore(allFindings, results.totalLines);
+  const { breakdown } = computeFormulaScore(allFindings, results.totalLines);
+  // Preserve the Maintainability N/A signal across AI re-merges by deriving
+  // forceNA from category availability snapshotted in the original scan.
+  const forceNA = new Set<DimensionName>();
+  const linting = results.categories.find((c) => c.name === 'Linting');
+  const formatting = results.categories.find((c) => c.name === 'Formatting');
+  const complexity = results.categories.find((c) => c.name === 'Complexity');
+  if (!linting?.available && !formatting?.available && !complexity?.available) {
+    forceNA.add('maintainability');
+  }
+  const rating = computeQualityRating(allFindings, results.totalLines, { forceNA });
 
   return {
     ...results,
-    overall,
-    grade: computeGrade(overall),
+    overall: rating.overall.score,
+    grade: rating.overall.grade,
     codeReview: results.codeReview,
     scoreBreakdown: breakdown,
+    dimensions: rating.dimensions,
+    qualityGate: rating.qualityGate,
+    gradeRationale: rating.gradeRationale,
   };
 }

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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { spawn } from 'node:child_process';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
@@ -104,7 +103,10 @@ async function tryInstallCommands(tool: QualityTool, dirPath: string): Promise<s
   let lastStderr = '';
   for (const cmd of commands) {
     const parts = cmd.trim().split(' ');
-    const result = await runCommand(parts[0], parts.slice(1), dirPath);
+    // Force NODE_ENV=development for install: npm/yarn/pnpm silently skip
+    // devDependencies under NODE_ENV=production, making `-D` installs no-op
+    // (exit 0, nothing installed) so the post-install detection re-fails.
+    const result = await runCommand(parts[0], parts.slice(1), dirPath, { NODE_ENV: 'development' });
     if (result.exitCode === 0) return null;
     lastStderr = result.stderr;
   }
@@ -276,13 +278,19 @@ export function chunkFileList(paths: string[], size = 400): string[][] {
 // Command Runner
 // ============================================================================
 
-export function runCommand(cmd: string, args: string[], cwd: string): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+export function runCommand(
+  cmd: string,
+  args: string[],
+  cwd: string,
+  envOverrides?: Record<string, string>,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   return new Promise((resolve) => {
     const proc = spawn(cmd, args, {
       cwd,
       shell: true,
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 120000,
+      env: envOverrides ? { ...process.env, ...envOverrides } : undefined,
     });
     let stdout = '';
     let stderr = '';

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

@@ -1,10 +1,27 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 // ============================================================================
 // Types
 // ============================================================================
 
+export type Grade = 'A' | 'B' | 'C' | 'D' | 'F' | 'N/A';
+export type DimensionName = 'security' | 'reliability' | 'maintainability';
+
+export interface DimensionScore {
+  name: DimensionName;
+  score: number;
+  grade: Grade;
+  rationale: string;
+  available: boolean;
+  findingCount: number;
+  worstSeverity: 'critical' | 'high' | 'medium' | 'low' | null;
+}
+
+export interface QualityGate {
+  passed: boolean;
+  failingConditions: string[];
+}
+
 export interface QualityTool {
   name: string;
   installed: boolean;
@@ -15,8 +32,6 @@ export interface QualityTool {
 export interface CategoryScore {
   name: string;
   score: number;
-  weight: number;
-  effectiveWeight: number;
   available: boolean;
   issueCount?: number;
   details?: Record<string, unknown>;
@@ -62,6 +77,9 @@ export interface QualityResults {
   timestamp: string;
   ecosystem: string[];
   scoreBreakdown?: ScoreBreakdown;
+  dimensions?: DimensionScore[];
+  qualityGate?: QualityGate;
+  gradeRationale?: string;
 }
 
 export interface ScanProgress {