@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/src/tool/{health → code_health}/markdown.ts

@@ -8,23 +8,14 @@
 import type { CapabilityWarningReport } from "../../analysis/capability/capability-warnings.ts";
 import type {
   HealthData,
+  HealthDiagnosticObservation,
   HealthDiagnosticScope,
   HealthRefreshAttempt,
   HealthResultAssembly,
   HealthSection,
-} from "../result/health.ts";
+} from "./result.ts";
 import { formatSemanticHealthState } from "./semantic-state.ts";
 
-export type {
-  HealthData,
-  HealthDiagnosticObservation,
-  HealthDiagnosticScope,
-  HealthRefreshAttempt,
-  HealthRefreshState,
-  HealthSection,
-  SemanticHealthState,
-} from "../result/health.ts";
-
 export function renderHealthResult(result: HealthResultAssembly, cwd: string): string {
   const data = result.data;
   const lines: string[] = ["## Code Health", ""];
@@ -51,25 +42,33 @@ function renderRefreshStatus(
 
   switch (data.refresh.kind) {
     case "completed":
-      lines.push(`**Diagnostic refresh**: ${completedRefreshText(data.refresh)}.`);
-      lines.push(`**Stale assessment**: ${staleAssessmentText(data.refresh)}.`);
+      lines.push(
+        `**${refreshAttemptLabel(data.refresh)}**: ${asSentence(completedRefreshText(data.refresh))}`,
+      );
+      lines.push(`**Stale assessment**: ${asSentence(staleAssessmentText(data.refresh))}`);
       lines.push("");
       return;
-    case "failed":
-      lines.push(`**Diagnostic refresh**: failed — ${data.refresh.reason}`);
+    case "failed": {
+      const evidence = data.refresh.diagnosticEvidence
+        ? `; ${formatDiagnosticEvidence(data.refresh.diagnosticEvidence)}`
+        : "";
+      lines.push(
+        `**${refreshAttemptLabel(data.refresh)}**: failed — ${data.refresh.reason}${evidence}`,
+      );
       lines.push("");
       return;
+    }
     case "not-attempted":
-      lines.push(`**Diagnostic refresh**: not attempted — ${data.refresh.reason}`);
+      lines.push(`**Diagnostic refresh attempt**: not started — ${data.refresh.reason}`);
       if (data.refresh.lastAttempt) renderLastAttempt(lines, data.refresh.lastAttempt, cwd);
       lines.push("");
       return;
     case "not-requested":
       if (data.refresh.lastAttempt) {
-        renderLastAttempt(lines, data.refresh.lastAttempt, cwd);
+        renderRetainedAttempt(lines, data.refresh.lastAttempt, cwd);
       } else {
         lines.push(
-          "**Diagnostic refresh**: not attempted this session. Use `refresh: true` to try one.",
+          "**Diagnostic refresh attempt**: not requested this session. Use `refresh: true` to try one.",
         );
       }
       lines.push("");
@@ -79,10 +78,19 @@ function renderRefreshStatus(
 function completedRefreshText(
   attempt: Extract<HealthRefreshAttempt, { kind: "completed" }>,
 ): string {
-  if (attempt.attemptedActiveClients === 0 && attempt.restartedClients === 0) {
-    return "completed no-op — no active clients were targeted";
-  }
-  return `completed — ${attempt.attemptedActiveClients} active client${plural(attempt.attemptedActiveClients)} targeted, ${attempt.restartedClients} restarted`;
+  const base =
+    attempt.attemptedActiveClients === 0 && attempt.restartedClients === 0
+      ? "completed no-op — no active clients were targeted"
+      : `completed — ${attempt.attemptedActiveClients} active client${plural(attempt.attemptedActiveClients)} targeted, ${attempt.restartedClients} restarted`;
+  return attempt.operationScope === "workspace-runtime"
+    ? `${base}; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
+    : base;
+}
+
+function refreshAttemptLabel(attempt: Pick<HealthRefreshAttempt, "operationScope">): string {
+  return attempt.operationScope === "file-runtime"
+    ? "File LSP maintenance attempt"
+    : "Diagnostic refresh attempt";
 }
 
 function staleAssessmentText(
@@ -90,19 +98,40 @@ function staleAssessmentText(
 ): string {
   if (attempt.staleAssessment.warning) return attempt.staleAssessment.warning;
   const matches = `${attempt.staleAssessment.matchedFileCount} file${plural(attempt.staleAssessment.matchedFileCount)} match the stale-module heuristic`;
+  if (attempt.staleAssessment.scope === "file") {
+    return `${matches} in the requested file; workspace clustering was not assessed`;
+  }
   return attempt.staleAssessment.suspected
     ? `${matches}; a clustered stale-module pattern is suspected`
     : `${matches}; no clustered stale-module pattern is suspected`;
 }
 
 function renderLastAttempt(lines: string[], attempt: HealthRefreshAttempt, cwd: string): void {
-  const outcome =
-    attempt.kind === "completed" ? completedRefreshText(attempt) : `failed — ${attempt.reason}`;
+  const outcome = refreshAttemptOutcome(attempt);
+  const label = refreshAttemptLabel(attempt);
+  lines.push(
+    `**Previous ${label.toLowerCase()}**: ${asSentence(outcome)} Started ${formatElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: ${refreshOperationScopeText(attempt)}.`,
+  );
+}
+
+function renderRetainedAttempt(lines: string[], attempt: HealthRefreshAttempt, cwd: string): void {
+  const label =
+    attempt.operationScope === "file-runtime" ? "File LSP maintenance" : "Diagnostic refresh";
   lines.push(
-    `**Last diagnostic refresh attempt**: ${outcome}, started ${formatElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: workspace runtime.`,
+    `**${label}**: not requested for this call. Previous attempt ${asSentence(refreshAttemptOutcome(attempt))} Started ${formatElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: ${refreshOperationScopeText(attempt)}.`,
   );
 }
 
+function refreshAttemptOutcome(attempt: HealthRefreshAttempt): string {
+  return attempt.kind === "completed"
+    ? completedRefreshText(attempt)
+    : `failed — ${attempt.reason}${attempt.diagnosticEvidence ? `; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}` : ""}`;
+}
+
+function refreshOperationScopeText(attempt: HealthRefreshAttempt): string {
+  return attempt.operationScope === "file-runtime" ? "file runtime" : "workspace runtime";
+}
+
 function formatElapsed(milliseconds: number): string {
   const seconds = Math.max(0, Math.round(milliseconds / 1_000));
   if (seconds < 60) return `${seconds}s ago`;
@@ -143,6 +172,12 @@ function renderDiagnosticsSection(lines: string[], data: HealthData, cwd: string
     lines.push("Diagnostics were not requested.");
   } else {
     lines.push(`**Evidence scope**: ${formatDiagnosticScope(observation.scope, cwd)}.`);
+    renderFileScopeStatus(lines, observation, cwd);
+    // The evidence line is bounded by the client's tracked documents; a file
+    // created after the last refresh is pulled on the next pass. Labeling the
+    // bound prevents misreading a first-call partial as an exclusion verdict.
+    const bound = observation.scope.kind === "tracked-files" ? " (tracked-file bound)" : "";
+    lines.push(`**Evidence coverage**: ${formatDiagnosticEvidence(observation.evidence)}${bound}.`);
     lines.push("");
     renderDiagnosticObservation(lines, data, cwd);
   }
@@ -150,15 +185,68 @@ function renderDiagnosticsSection(lines: string[], data: HealthData, cwd: string
   lines.push("");
 }
 
+/**
+ * Render the tsconfig coverage verdict for a single-file health request.
+ *
+ * Written in plain vocabulary (no basis terms) so a reader without tsconfig
+ * background can act on it: the sentence names the deciding config and states
+ * whether the file's errors are part of workspace diagnostics. The structured
+ * decision basis stays in the diagnostics.scope debug event.
+ */
+function renderFileScopeStatus(
+  lines: string[],
+  observation: Extract<
+    HealthDiagnosticObservation,
+    { kind: "completed" | "partial" | "unavailable" }
+  >,
+  cwd: string,
+): void {
+  if (observation.scope.kind !== "file" || !observation.scopeStatus) return;
+
+  const decision = observation.scopeStatus;
+  switch (decision.status) {
+    case "included":
+      lines.push(
+        `**Tsconfig**: covered by ${formatConfigPath(decision.configPath, cwd)} — part of workspace diagnostics.`,
+      );
+      return;
+    case "excluded":
+      lines.push(
+        `**Tsconfig**: NOT covered by ${formatConfigPath(decision.configPath, cwd)} — not part of workspace diagnostics.`,
+      );
+      return;
+    case "no-config":
+      lines.push("**Tsconfig**: no tsconfig.json or jsconfig.json found — nothing filtered.");
+      return;
+    case "out-of-tree":
+      lines.push("**Tsconfig**: outside the project root — not part of workspace diagnostics.");
+  }
+}
+
+function formatConfigPath(configPath: string | null, cwd: string): string {
+  if (!configPath) return "no config";
+  return `\`${makeRelative(cwd, configPath)}\``;
+}
+
+function formatDiagnosticEvidence(evidence: {
+  requested: number;
+  confirmed: number;
+  unconfirmed: number;
+  failed: number;
+  removed: number;
+}): string {
+  return `${evidence.requested} requested, ${evidence.confirmed} confirmed, ${evidence.unconfirmed} unconfirmed, ${evidence.failed} failed, ${evidence.removed} removed`;
+}
+
 function renderDiagnosticObservation(lines: string[], data: HealthData, cwd: string): void {
   const observation = data.diagnostics;
   if (observation.kind === "not-requested") return;
   if (observation.kind === "unavailable") {
-    lines.push(`Diagnostics unavailable — ${observation.reason}.`);
+    lines.push(`Diagnostics unavailable — ${asSentence(observation.reason)}`);
     return;
   }
   if (observation.kind === "partial") {
-    lines.push(`Diagnostics partially collected — ${observation.reason}.`);
+    lines.push(`Diagnostics partially collected — ${asSentence(observation.reason)}`);
     if (observation.entries.length > 0) {
       lines.push("");
       lines.push("Partial results:");
@@ -173,6 +261,10 @@ function renderDiagnosticObservation(lines: string[], data: HealthData, cwd: str
   renderDiagnosticEntries(lines, data, cwd);
 }
 
+function asSentence(text: string): string {
+  return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+
 function emptyDiagnosticText(scope: HealthDiagnosticScope, cwd: string): string {
   if (scope.kind === "file") {
     return `No errors or warnings found for \`${makeRelative(cwd, scope.path)}\`.`;

package/src/tool/code_health/refresh-status.ts

@@ -0,0 +1,105 @@
+/** Render current and retained health refresh status for the TUI. */
+
+export function readRefreshStatus(data: Record<string, unknown> | null): string | null {
+  const refresh = readRecord(data?.refresh);
+  if (!refresh) return null;
+
+  switch (refresh.kind) {
+    case "completed": {
+      const attempted = readNumber(refresh.attemptedActiveClients);
+      const restarted = readNumber(refresh.restartedClients);
+      const stale = readRecord(refresh.staleAssessment);
+      const noOp = attempted === 0 && restarted === 0;
+      const label = refreshAttemptLabel(refresh);
+      const base = noOp
+        ? `${label} completed no-op`
+        : `${label} completed: ${attempted} clients targeted, ${restarted} restarted`;
+      const evidence = formatDiagnosticEvidence(readRecord(refresh.diagnosticEvidence));
+      const withEvidence = evidence ? `${base}; ${evidence}` : base;
+      return stale?.suspected === true
+        ? `${withEvidence}; stale pattern suspected in ${readNumber(stale.matchedFileCount)} files`
+        : withEvidence;
+    }
+    case "failed": {
+      const evidence = formatDiagnosticEvidence(readRecord(refresh.diagnosticEvidence));
+      return `${refreshAttemptLabel(refresh)} failed${typeof refresh.reason === "string" ? `: ${refresh.reason}` : ""}${evidence ? `; ${evidence}` : ""}`;
+    }
+    case "not-attempted":
+      return `refresh attempt not started${formatLastRefreshSuffix(refresh)}`;
+    case "not-requested":
+      return `refresh not requested${formatLastRefreshSuffix(refresh)}`;
+    default:
+      return null;
+  }
+}
+
+export function readPreviousRefreshStatus(data: Record<string, unknown> | null): string | null {
+  const refresh = readRecord(data?.refresh);
+  if (!refresh || (refresh.kind !== "not-requested" && refresh.kind !== "not-attempted")) {
+    return null;
+  }
+  const attempt = readRecord(refresh.lastAttempt);
+  if (!attempt) return null;
+  const evidence = formatCompactDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  if (attempt.kind === "failed") {
+    return `last ${refreshAttemptLabel(attempt)} failed${evidence ? ` (${evidence})` : ""}`;
+  }
+  if (attempt.kind === "completed") {
+    return `last ${refreshAttemptLabel(attempt)} completed${evidence ? ` (${evidence})` : ""}`;
+  }
+  return null;
+}
+
+function refreshAttemptLabel(attempt: Record<string, unknown>): string {
+  return attempt.operationScope === "file-runtime" ? "file maintenance attempt" : "refresh attempt";
+}
+
+function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
+  const attempt = readRecord(refresh.lastAttempt);
+  if (!attempt) return "";
+  const evidence = formatDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  if (attempt.kind === "failed") {
+    const reason = typeof attempt.reason === "string" ? `: ${attempt.reason}` : "";
+    return `; last ${refreshAttemptLabel(attempt)} failed${reason}${evidence ? `; ${evidence}` : ""}`;
+  }
+  if (attempt.kind === "completed") {
+    return `; last ${refreshAttemptLabel(attempt)} completed${evidence ? `; ${evidence}` : ""}`;
+  }
+  return "";
+}
+
+function formatCompactDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
+  const counts = readEvidenceCounts(evidence);
+  if (!counts) return null;
+  return `req ${counts[0]} · conf ${counts[1]} · unconf ${counts[2]} · failed ${counts[3]} · removed ${counts[4]}`;
+}
+
+function formatDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
+  const counts = readEvidenceCounts(evidence);
+  if (!counts) return null;
+  return `${counts[0]} requested, ${counts[1]} confirmed, ${counts[2]} unconfirmed, ${counts[3]} failed, ${counts[4]} removed`;
+}
+
+function readEvidenceCounts(evidence: Record<string, unknown> | null): number[] | null {
+  if (!evidence) return null;
+  const counts = [
+    evidence.requested,
+    evidence.confirmed,
+    evidence.unconfirmed,
+    evidence.failed,
+    evidence.removed,
+  ];
+  return counts.every(isEvidenceCount) ? counts : null;
+}
+
+function isEvidenceCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+function readNumber(value: unknown): number {
+  return typeof value === "number" ? value : 0;
+}

package/src/tool/{result/health.ts → code_health/result.ts}

@@ -5,8 +5,9 @@ import {
   type ResultProvenance,
   type ResultSection,
   type ToolResultAssembly,
-} from "./assembly.ts";
-import type { HealthDetails, HealthSectionDetails } from "./types.ts";
+} from "../result/assembly.ts";
+import { createToolDisplaySection, truncateDisplayText } from "../result/display.ts";
+import type { HealthDetails, HealthSectionDetails, ToolDisplaySection } from "../result/types.ts";
 
 export type {
   HealthData,
@@ -20,12 +21,13 @@ export type {
   HealthStaleAssessment,
   SemanticHealthState,
 } from "../../session/health-types.ts";
-export type { HealthSectionDetails } from "./types.ts";
+export type { HealthSectionDetails } from "../result/types.ts";
 
 export interface HealthResultAssembly {
   data: HealthData;
   assembled: ToolResultAssembly<HealthData>;
   details: HealthDetails;
+  displaySections: readonly ToolDisplaySection[];
 }
 
 const SECTION_TITLES: Record<HealthSection, string> = {
@@ -53,9 +55,12 @@ export function assembleHealthResult(data: HealthData): HealthResultAssembly {
     provenance,
   });
 
+  const displaySections = buildHealthDisplaySections(data);
+
   return {
     data,
     assembled,
+    displaySections,
     details: {
       includedSections: [...data.includedSections],
       sections: sectionDetails,
@@ -78,6 +83,53 @@ export function assembleHealthResult(data: HealthData): HealthResultAssembly {
   };
 }
 
+function buildHealthDisplaySections(data: HealthData): ToolDisplaySection[] {
+  const sections: ToolDisplaySection[] = [];
+
+  if (data.includedSections.includes("diagnostics") && data.diagnostics.entries.length > 0) {
+    sections.push(
+      createToolDisplaySection({
+        key: "health.diagnostics",
+        title: "Diagnostics",
+        items: data.diagnostics.entries,
+        totalCount: data.diagnostics.kind === "completed" ? data.diagnostics.entries.length : null,
+        omittedCount: data.diagnostics.kind === "completed" ? 0 : null,
+        partialReason: diagnosticPartialReason(data),
+        format: formatDiagnosticEntry,
+      }),
+    );
+  }
+
+  if (data.includedSections.includes("servers") && data.servers.length > 0) {
+    sections.push(
+      createToolDisplaySection({
+        key: "health.servers",
+        title: "Servers",
+        items: data.servers,
+        totalCount: data.servers.length,
+        format: (server) => `${server.name} (${server.fileTypes.join(", ")}) — ${server.status}`,
+      }),
+    );
+  }
+
+  return sections;
+}
+
+function diagnosticPartialReason(data: HealthData): string | null {
+  return data.diagnostics.kind === "partial" || data.diagnostics.kind === "unavailable"
+    ? data.diagnostics.reason
+    : null;
+}
+
+function formatDiagnosticEntry(entry: HealthData["diagnostics"]["entries"][number]): string {
+  const summary = `${entry.file} — ${entry.errors} error${entry.errors === 1 ? "" : "s"}, ${entry.warnings} warning${entry.warnings === 1 ? "" : "s"}`;
+  const messages = entry.messages?.map(
+    (message) =>
+      `  ${message.severity} L${message.line}${message.source ? ` [${message.source}]` : ""}: ${truncateDisplayText(message.message, 200)}`,
+  );
+  return messages && messages.length > 0 ? [summary, ...messages].join("\n") : summary;
+}
+
 interface HealthSectionFacts {
   status: "complete" | "partial" | "unavailable";
   available: boolean;
@@ -189,3 +241,28 @@ function uniqueProvenance(provenance: readonly ResultProvenance[]): ResultProven
     return true;
   });
 }
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { healthErrorResult } from "../result/errors.ts";
+import { renderHealthResult } from "./markdown.ts";
+
+type HealthOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["health"]>>;
+
+/** Assemble the final model-visible code_health result for one workflow outcome. */
+export function finishHealthResult(outcome: HealthOutcome, cwd: string): CodeIntelResult {
+  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
+  if (outcome.kind === "invalid-input") {
+    return healthErrorResult(`**Error:** ${outcome.message}`, outcome.message);
+  }
+
+  const assembly = assembleHealthResult(outcome.data);
+  return {
+    content: renderHealthResult(assembly, cwd),
+    details: {
+      type: "health",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
+  };
+}

package/src/tool/code_health/spec.ts

@@ -0,0 +1,41 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { CodeIntelToolExecCtx } from "../../types/index.ts";
+import { ScopeParam } from "../schemas.ts";
+import { executeHealthTool } from "./execute.ts";
+import { renderHealthCall, renderHealthResult } from "./tui.ts";
+
+export const CODE_HEALTH_TOOL_NAME = "code_health";
+export const CODE_HEALTH_TOOL_LABEL = "Code Health";
+
+/** Canonical provider-facing metadata for the code_health tool. */
+export const codeHealthSpec = {
+  name: CODE_HEALTH_TOOL_NAME,
+  label: CODE_HEALTH_TOOL_LABEL,
+  parameters: Type.Object(
+    {
+      scope: Type.Optional(ScopeParam),
+      refresh: Type.Optional(
+        Type.Boolean({
+          description: "Attempt diagnostic recovery before collecting; result reports the outcome.",
+        }),
+      ),
+      include: Type.Optional(
+        Type.Array(StringEnum(["diagnostics", "servers"]), {
+          description: "Requested health-signal sections.",
+          uniqueItems: true,
+        }),
+      ),
+      level: Type.Optional(
+        StringEnum(["summary", "detailed"], {
+          description: "Detail level for the health report.",
+        }),
+      ),
+    },
+    { additionalProperties: false },
+  ),
+  run: (params: unknown, ctx: CodeIntelToolExecCtx) =>
+    executeHealthTool(params as Parameters<typeof executeHealthTool>[0], ctx),
+  renderCall: renderHealthCall,
+  renderResult: renderHealthResult,
+} as const;