Add TypeScript quality feedback APIs

README.md

@@ -96,7 +96,9 @@ The same operations are exported for direct library use:
 ```ts
 import {
   analyzeTypeScriptImportGraph,
+  compareTypeScriptQualitySnapshots,
   planTypeScriptBulkRewrite,
+  readTypeScriptQualitySnapshot,
   traceTypeScriptDiagnostics,
   traceTypeScriptProjectStatus,
 } from "@evref-bl/dev-nexus-typescript";
@@ -116,6 +118,18 @@ const rewritePlan = planTypeScriptBulkRewrite({
     to: "newName",
   },
 });
+const before = readTypeScriptQualitySnapshot({
+  projectRoot,
+  sonarIssuesPath: ".quality/sonar/issues.json",
+  sonarQualityGatePath: ".quality/sonar/quality-gate.json",
+  sonarSecurityHotspotsPath: ".quality/sonar/security-hotspots.json",
+});
+const after = readTypeScriptQualitySnapshot({ projectRoot });
+const delta = compareTypeScriptQualitySnapshots({
+  before,
+  after,
+  touchedFiles: ["src/index.ts"],
+});
 ```
 
 The project-status operation reports setup inventory, available scripts,
@@ -139,6 +153,16 @@ categories, risks, and verification commands. Current policy records
 `applyAllowed: false`; agents can cite the plan before manual edits or future
 human-approved apply workflows, but this package does not write files.
 
+The quality snapshot operation combines TypeScript diagnostics, import cycles,
+and optional Sonar JSON exports from `api/issues/search`,
+`api/qualitygates/project_status`, and `api/hotspots/search`. Findings are
+grouped by file, rule, and severity. The quality delta operation compares two
+snapshots and highlights new or resolved findings on touched files, with special
+attention to new bugs, vulnerabilities, security hotspots, and critical or
+blocker findings. Rule playbooks cover `typescript:S3776`, `typescript:S5852`,
+and `typescript:S4036`; their references point to SonarSource guidance on
+cognitive complexity, regex backtracking, quality gates, and PATH trust review.
+
 ## Boundaries
 
 - The plugin does not run `npm install`, `pnpm install`, `yarn install`, or

src/index.ts

@@ -5,5 +5,6 @@ export * from "./typeScriptMcpDiagnosticsTracer.js";
 export * from "./typeScriptMcpServer.js";
 export * from "./typeScriptMcpServerConfig.js";
 export * from "./typeScriptProjectSetupInventory.js";
+export * from "./typeScriptQualityFeedback.js";
 export * from "./typeScriptWorkerGuidance.js";
 export * from "./typeScriptWorkflowSkills.js";

src/typeScriptMcpServer.test.ts

@@ -22,10 +22,12 @@ describe("DevNexus TypeScript MCP server", () => {
           { name: "typescript.diagnostics" },
           { name: "typescript.importGraph" },
           { name: "typescript.bulkRewritePlan" },
+          { name: "typescript.qualitySnapshot" },
+          { name: "typescript.qualityDelta" },
         ],
       },
     });
-    expect(devNexusTypeScriptMcpTools).toHaveLength(4);
+    expect(devNexusTypeScriptMcpTools).toHaveLength(6);
   });
 
   it("returns project status through tools/call", async () => {
@@ -63,6 +65,64 @@ describe("DevNexus TypeScript MCP server", () => {
     });
   });
 
+  it("returns a quality delta through tools/call", async () => {
+    const snapshot = {
+      operation: "typescript.qualitySnapshot",
+      readOnly: true,
+      status: "ok",
+      projectRoot: process.cwd(),
+      setup: {
+        blockerCount: 0,
+        blockers: [],
+      },
+      inputs: {
+        diagnostics: true,
+        importGraph: true,
+        sonarIssues: false,
+        sonarQualityGate: false,
+        sonarSecurityHotspots: false,
+      },
+      summary: {
+        findingCount: 0,
+        fileCount: 0,
+        ruleCount: 0,
+        criticalOrBlockerCount: 0,
+        bugCount: 0,
+        vulnerabilityCount: 0,
+        securityHotspotCount: 0,
+        importCycleCount: 0,
+        qualityGateFailed: false,
+      },
+      findings: [],
+      findingsByFile: [],
+      findingsByRule: [],
+      findingsBySeverity: [],
+    };
+    const response = await handleDevNexusTypeScriptMcpJsonRpcMessage({
+      jsonrpc: "2.0",
+      id: "quality-delta",
+      method: "tools/call",
+      params: {
+        name: "typescript.qualityDelta",
+        arguments: {
+          before: snapshot,
+          after: snapshot,
+          touchedFiles: [],
+        },
+      },
+    });
+
+    const result = response as {
+      result: {
+        content: Array<{ text: string }>;
+      };
+    };
+    expect(JSON.parse(result.result.content[0]!.text)).toMatchObject({
+      operation: "typescript.qualityDelta",
+      status: "unchanged",
+    });
+  });
+
   it("initializes with a stable server identity", async () => {
     const response = await handleDevNexusTypeScriptMcpJsonRpcMessage({
       jsonrpc: "2.0",

src/typeScriptMcpServer.ts

@@ -17,6 +17,12 @@ import {
   type TypeScriptMcpTraceInput,
 } from "./typeScriptMcpDiagnosticsTracer.js";
 import { devNexusTypeScriptMcpServerName } from "./typeScriptMcpServerConfig.js";
+import {
+  compareTypeScriptQualitySnapshots,
+  readTypeScriptQualitySnapshot,
+  type TypeScriptQualityDeltaInput,
+  type TypeScriptQualitySnapshotInput,
+} from "./typeScriptQualityFeedback.js";
 
 type JsonRpcId = string | number | null;
 
@@ -114,6 +120,70 @@ export const devNexusTypeScriptMcpTools: readonly McpTool[] = [
       additionalProperties: true,
     },
   },
+  {
+    name: "typescript.qualitySnapshot",
+    description:
+      "Read TypeScript diagnostics, import cycles, and Sonar JSON into one quality snapshot.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectRoot: projectRootProperty,
+        tsconfigPath: tsconfigPathProperty,
+        include: {
+          type: "array",
+          items: { type: "string" },
+        },
+        ignore: {
+          type: "array",
+          items: { type: "string" },
+        },
+        sonarIssuesPath: {
+          type: "string",
+          description: "Optional project-relative Sonar api/issues/search JSON path.",
+        },
+        sonarQualityGatePath: {
+          type: "string",
+          description:
+            "Optional project-relative Sonar api/qualitygates/project_status JSON path.",
+        },
+        sonarSecurityHotspotsPath: {
+          type: "string",
+          description:
+            "Optional project-relative Sonar api/hotspots/search JSON path.",
+        },
+        sonar: {
+          type: "object",
+          description: "Optional inline Sonar JSON objects for tests or callers.",
+        },
+      },
+      required: ["projectRoot"],
+      additionalProperties: true,
+    },
+  },
+  {
+    name: "typescript.qualityDelta",
+    description:
+      "Compare two TypeScript quality snapshots and highlight touched-file regressions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        before: {
+          type: "object",
+          description: "Baseline quality snapshot.",
+        },
+        after: {
+          type: "object",
+          description: "Current quality snapshot.",
+        },
+        touchedFiles: {
+          type: "array",
+          items: { type: "string" },
+        },
+      },
+      required: ["before", "after"],
+      additionalProperties: true,
+    },
+  },
 ];
 
 export async function handleDevNexusTypeScriptMcpJsonRpcMessage(
@@ -185,6 +255,18 @@ async function callDevNexusTypeScriptMcpTool(
             params.arguments as unknown as TypeScriptBulkRewritePlanInput,
           ),
         );
+      case "typescript.qualitySnapshot":
+        return toolResult(
+          readTypeScriptQualitySnapshot(
+            params.arguments as unknown as TypeScriptQualitySnapshotInput,
+          ),
+        );
+      case "typescript.qualityDelta":
+        return toolResult(
+          compareTypeScriptQualitySnapshots(
+            params.arguments as unknown as TypeScriptQualityDeltaInput,
+          ),
+        );
       default:
         return toolResult({ error: `Unknown tool: ${params.name}` }, true);
     }