@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/tool/health/markdown.ts

@@ -5,218 +5,269 @@
  * readable markdown sections keyed by requested `include` values.
  */
 
-import { formatGitContext } from "../../analysis/signals/git.ts";
-import type { HealthData, HealthResultAssembly } from "../result/health.ts";
+import type { CapabilityWarningReport } from "../../analysis/capability/capability-warnings.ts";
+import type {
+  HealthData,
+  HealthDiagnosticScope,
+  HealthRefreshAttempt,
+  HealthResultAssembly,
+  HealthSection,
+} from "../result/health.ts";
+import { formatSemanticHealthState } from "./semantic-state.ts";
 
 export type {
-  CodeActionSuggestion,
-  HealthCoverageData,
   HealthData,
+  HealthDiagnosticObservation,
+  HealthDiagnosticScope,
+  HealthRefreshAttempt,
+  HealthRefreshState,
   HealthSection,
-  HealthUnusedData,
+  SemanticHealthState,
 } from "../result/health.ts";
 
 export function renderHealthResult(result: HealthResultAssembly, cwd: string): string {
   const data = result.data;
   const lines: string[] = ["## Code Health", ""];
+  const hasSection = (key: HealthSection): boolean =>
+    result.assembled.sections.some((section) => section.key === `health.${key}`);
+  const hasDiagnostics = hasSection("diagnostics");
+  const semanticRequested = hasDiagnostics || hasSection("servers");
+
+  renderStatusLine(lines, data, semanticRequested);
+  renderRefreshStatus(lines, data, hasDiagnostics, cwd);
+  if (hasDiagnostics) renderDiagnosticsSection(lines, data, cwd);
+  if (semanticRequested) renderCapabilityWarningsSection(lines, result.details.capabilityWarnings);
+  if (hasSection("servers")) renderServersSection(lines, data, sectionStatus(result, "servers"));
+  return lines.join("\n");
+}
 
-  renderStatusLine(lines, data);
-  renderStalenessBanner(lines, data);
-
-  if (data.includedSections.includes("diagnostics")) {
-    renderDiagnosticsSection(lines, data, cwd);
+function renderRefreshStatus(
+  lines: string[],
+  data: HealthData,
+  hasDiagnostics: boolean,
+  cwd: string,
+): void {
+  if (!hasDiagnostics) return;
+
+  switch (data.refresh.kind) {
+    case "completed":
+      lines.push(`**Diagnostic refresh**: ${completedRefreshText(data.refresh)}.`);
+      lines.push(`**Stale assessment**: ${staleAssessmentText(data.refresh)}.`);
+      lines.push("");
+      return;
+    case "failed":
+      lines.push(`**Diagnostic refresh**: failed — ${data.refresh.reason}`);
+      lines.push("");
+      return;
+    case "not-attempted":
+      lines.push(`**Diagnostic refresh**: not attempted — ${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);
+      } else {
+        lines.push(
+          "**Diagnostic refresh**: not attempted this session. Use `refresh: true` to try one.",
+        );
+      }
+      lines.push("");
   }
-  if (data.includedSections.includes("coverage")) {
-    renderCoverageSection(lines, data, cwd);
-  }
-  if (data.includedSections.includes("unused")) {
-    renderUnusedSection(lines, data, cwd);
-  }
-  renderDegradedCoverageSection(lines, data);
-  if (data.includedSections.includes("servers")) {
-    renderServersSection(lines, data);
-  }
-  if (data.includedSections.includes("dirty")) {
-    renderDirtySection(lines, data);
+}
+
+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`;
+}
 
-  return lines.join("\n");
+function staleAssessmentText(
+  attempt: Extract<HealthRefreshAttempt, { kind: "completed" }>,
+): string {
+  if (attempt.staleAssessment.warning) return attempt.staleAssessment.warning;
+  const matches = `${attempt.staleAssessment.matchedFileCount} file${plural(attempt.staleAssessment.matchedFileCount)} match the stale-module heuristic`;
+  return attempt.staleAssessment.suspected
+    ? `${matches}; a clustered stale-module pattern is suspected`
+    : `${matches}; no clustered stale-module pattern is suspected`;
 }
 
-function renderStalenessBanner(lines: string[], data: HealthData): void {
-  if (data.diagnosticAgeSeconds == null) {
-    lines.push("⚠ Diagnostics have not been refreshed this session. Use `refresh: true` to check.");
-    lines.push("");
-    return;
-  }
-  if (data.diagnosticAgeSeconds < 60) return;
-  const age =
-    data.diagnosticAgeSeconds < 120
-      ? `${Math.round(data.diagnosticAgeSeconds)}s ago`
-      : `${Math.round(data.diagnosticAgeSeconds / 60)}m ago`;
-  lines.push(`⚠ Diagnostics are ${age}. Use \`refresh: true\` to re-check.`);
-  lines.push("");
+function renderLastAttempt(lines: string[], attempt: HealthRefreshAttempt, cwd: string): void {
+  const outcome =
+    attempt.kind === "completed" ? completedRefreshText(attempt) : `failed — ${attempt.reason}`;
+  lines.push(
+    `**Last diagnostic refresh attempt**: ${outcome}, started ${formatElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: workspace runtime.`,
+  );
 }
 
-function renderDegradedCoverageSection(lines: string[], data: HealthData): void {
-  if (!data.degradedCoverage?.hasWarnings) return;
+function formatElapsed(milliseconds: number): string {
+  const seconds = Math.max(0, Math.round(milliseconds / 1_000));
+  if (seconds < 60) return `${seconds}s ago`;
+  return `${Math.round(seconds / 60)}m ago`;
+}
 
-  lines.push("### Degraded Coverage");
+function renderCapabilityWarningsSection(
+  lines: string[],
+  report: CapabilityWarningReport | null,
+): void {
+  if (!report?.hasWarnings) return;
+
+  lines.push("### Capability Warnings");
   lines.push("");
 
-  for (const warning of data.degradedCoverage.warnings) {
+  for (const warning of report.warnings) {
     const lang = warning.language ? `[${warning.language}] ` : "";
     lines.push(`- ⚠ ${lang}${warning.message}`);
-    if (warning.detail) {
-      lines.push(`  — ${warning.detail}`);
-    }
+    if (warning.detail) lines.push(`  — ${warning.detail}`);
   }
   lines.push("");
 }
 
-function renderStatusLine(lines: string[], data: HealthData): void {
-  lines.push(`**LSP**: ${data.lspStatus}`);
-  if (data.structuralStatus) {
-    lines.push(`**Structural**: ${data.structuralStatus}`);
-  }
-  if (data.recovered) {
-    lines.push("**Recovery**: diagnostics refreshed");
-  }
+function renderStatusLine(lines: string[], data: HealthData, semanticRequested: boolean): void {
+  if (!semanticRequested) return;
+
+  lines.push(`**LSP**: ${displaySemanticStatus(data)}`);
+  if (data.structuralStatus) lines.push(`**Structural**: ${data.structuralStatus}`);
   lines.push("");
 }
 
 function renderDiagnosticsSection(lines: string[], data: HealthData, cwd: string): void {
+  const observation = data.diagnostics;
   lines.push("### Diagnostics");
   lines.push("");
 
-  if (data.diagnostics.length === 0) {
-    lines.push("No diagnostics found.");
-  } else if (data.level === "summary") {
-    renderDiagnosticSummary(lines, data);
+  if (observation.kind === "not-requested") {
+    lines.push("Diagnostics were not requested.");
   } else {
-    renderDiagnosticDetails(lines, data, cwd);
+    lines.push(`**Evidence scope**: ${formatDiagnosticScope(observation.scope, cwd)}.`);
+    lines.push("");
+    renderDiagnosticObservation(lines, data, cwd);
   }
 
-  renderCodeActionsSection(lines, data, cwd);
   lines.push("");
 }
 
-function renderDiagnosticSummary(lines: string[], data: HealthData): void {
-  const totalErrors = data.diagnostics.reduce((sum, d) => sum + d.errors, 0);
-  const totalWarnings = data.diagnostics.reduce((sum, d) => sum + d.warnings, 0);
-  const fileCount = data.diagnostics.length;
-  const s = (n: number) => (n !== 1 ? "s" : "");
-  lines.push(
-    `${fileCount} file${s(fileCount)} with issues: ${totalErrors} error${s(totalErrors)}, ${totalWarnings} warning${s(totalWarnings)}`,
-  );
-}
-
-function renderDiagnosticDetails(lines: string[], data: HealthData, cwd: string): void {
-  for (const entry of data.diagnostics) {
-    const relPath = makeRelative(cwd, entry.file);
-    const s = (n: number) => (n !== 1 ? "s" : "");
-    lines.push(
-      `- \`${relPath}\` — ${entry.errors} error${s(entry.errors)}, ${entry.warnings} warning${s(entry.warnings)}`,
-    );
-  }
-}
-
-function renderCodeActionsSection(lines: string[], data: HealthData, cwd: string): void {
-  if (!data.codeActions || data.codeActions.length === 0) return;
-
-  if (data.level === "summary") {
-    const count = data.codeActions.length;
-    lines.push(
-      `_${count} suggested fix${count !== 1 ? "es" : ""} available. Use \`level: "detailed"\` to see them._`,
-    );
+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}.`);
     return;
   }
-
-  lines.push("");
-  lines.push("### Code Actions");
-  lines.push("");
-  lines.push("Available fixes (suggestions only — not applied):");
-  lines.push("");
-  for (const action of data.codeActions) {
-    const relPath = makeRelative(cwd, action.file);
-    const kindLabel = action.kind ? ` (${action.kind})` : "";
-    lines.push(`- \`${relPath}:${action.line}\` — "${action.title}"${kindLabel}`);
-  }
-}
-
-function renderCoverageSection(lines: string[], data: HealthData, cwd: string): void {
-  lines.push("### Coverage");
-  lines.push("");
-
-  if (!data.coverage?.available) {
-    lines.push("No coverage report found.");
-    lines.push("");
+  if (observation.kind === "partial") {
+    lines.push(`Diagnostics partially collected — ${observation.reason}.`);
+    if (observation.entries.length > 0) {
+      lines.push("");
+      lines.push("Partial results:");
+      renderDiagnosticEntries(lines, data, cwd);
+    }
     return;
   }
-
-  if (data.coverage.entries.length === 0) {
-    lines.push("No low-coverage files found.");
-    lines.push("");
+  if (observation.entries.length === 0) {
+    lines.push(emptyDiagnosticText(observation.scope, cwd));
     return;
   }
+  renderDiagnosticEntries(lines, data, cwd);
+}
 
-  for (const entry of data.coverage.entries) {
-    lines.push(`- \`${makeRelative(cwd, entry.file)}\` — ${entry.pct.toFixed(0)}%`);
+function emptyDiagnosticText(scope: HealthDiagnosticScope, cwd: string): string {
+  if (scope.kind === "file") {
+    return `No errors or warnings found for \`${makeRelative(cwd, scope.path)}\`.`;
   }
-  lines.push("");
+  return scope.filter
+    ? `No errors or warnings are reported by the tracked-file diagnostic snapshot under \`${makeRelative(cwd, scope.filter)}\`.`
+    : "No errors or warnings are reported by the tracked-file diagnostic snapshot.";
 }
 
-function renderUnusedSection(lines: string[], data: HealthData, cwd: string): void {
-  lines.push("### Unused");
-  lines.push("");
-
-  if (!data.unused?.available) {
-    lines.push("No unused report found.");
-    lines.push("");
-    return;
+function renderDiagnosticEntries(lines: string[], data: HealthData, cwd: string): void {
+  const entries = data.diagnostics.entries;
+  if (data.level === "summary") {
+    renderDiagnosticSummary(lines, entries);
+  } else {
+    renderDiagnosticDetails(lines, entries, cwd);
   }
+}
 
-  if (data.unused.files.length === 0 && data.unused.exports.length === 0) {
-    lines.push("No unused files or exports reported.");
-    lines.push("");
-    return;
-  }
+function renderDiagnosticSummary(
+  lines: string[],
+  entries: HealthData["diagnostics"]["entries"],
+): void {
+  const totalErrors = entries.reduce((sum, entry) => sum + entry.errors, 0);
+  const totalWarnings = entries.reduce((sum, entry) => sum + entry.warnings, 0);
+  lines.push(
+    `${entries.length} file${plural(entries.length)} with issues: ${totalErrors} error${plural(totalErrors)}, ${totalWarnings} warning${plural(totalWarnings)}`,
+  );
+}
 
-  for (const file of data.unused.files) {
-    lines.push(`- Unused file: \`${makeRelative(cwd, file)}\``);
-  }
-  for (const entry of data.unused.exports) {
-    lines.push(`- Unused export: \`${entry.name}\` in \`${makeRelative(cwd, entry.file)}\``);
+function renderDiagnosticDetails(
+  lines: string[],
+  entries: HealthData["diagnostics"]["entries"],
+  cwd: string,
+): void {
+  for (const entry of entries) {
+    lines.push(
+      `- \`${makeRelative(cwd, entry.file)}\` — ${entry.errors} error${plural(entry.errors)}, ${entry.warnings} warning${plural(entry.warnings)}`,
+    );
+    if (entry.messages) {
+      for (const msg of entry.messages) {
+        const source = msg.source ? ` [${msg.source}]` : "";
+        lines.push(`  - L${msg.line} ${msg.severity}${source}: ${msg.message}`);
+      }
+    }
   }
-  lines.push("");
 }
 
-function renderServersSection(lines: string[], data: HealthData): void {
+function renderServersSection(
+  lines: string[],
+  data: HealthData,
+  status: "complete" | "partial" | "unavailable" | undefined,
+): void {
   lines.push("### Servers");
   lines.push("");
+  lines.push("**Inventory scope**: workspace-wide.");
+  lines.push("");
 
-  if (data.servers.length === 0) {
+  if (status === "unavailable") {
+    lines.push(`Server status unavailable — ${displaySemanticStatus(data)}.`);
+  } else if (data.servers.length === 0) {
     lines.push("No servers found.");
-    lines.push("");
-    return;
-  }
-
-  for (const server of data.servers) {
-    const statusIcon = server.status === "running" ? "✓" : "✗";
-    const types = server.fileTypes.join(", ");
-    lines.push(`- ${statusIcon} **${server.name}** (${types}) — ${server.status}`);
+  } else {
+    for (const server of data.servers) {
+      const statusIcon = server.status === "running" ? "✓" : "✗";
+      lines.push(
+        `- ${statusIcon} **${server.name}** (${server.fileTypes.join(", ")}) — ${server.status}`,
+      );
+    }
   }
   lines.push("");
 }
 
-function renderDirtySection(lines: string[], data: HealthData): void {
-  if (!data.gitContext) return;
-  lines.push(formatGitContext(data.gitContext));
+function displaySemanticStatus(data: HealthData): string {
+  return formatSemanticHealthState(data.semanticState);
+}
+
+function sectionStatus(
+  result: HealthResultAssembly,
+  key: HealthSection,
+): "complete" | "partial" | "unavailable" | undefined {
+  return result.assembled.sections.find((section) => section.key === `health.${key}`)?.status;
+}
+
+function formatDiagnosticScope(scope: HealthDiagnosticScope, cwd: string): string {
+  if (scope.kind === "file")
+    return `live file diagnostic request for \`${makeRelative(cwd, scope.path)}\``;
+  return scope.filter
+    ? `tracked-file diagnostic snapshot under \`${makeRelative(cwd, scope.filter)}\``
+    : "tracked-file diagnostic snapshot";
+}
+
+function plural(count: number): string {
+  return count === 1 ? "" : "s";
 }
 
 function makeRelative(cwd: string, file: string): string {
-  if (file.startsWith(cwd)) {
-    return file.slice(cwd.length + 1);
-  }
-  return file;
+  return file.startsWith(cwd) ? file.slice(cwd.length + 1) : file;
 }

package/src/tool/health/semantic-state.ts

@@ -0,0 +1,24 @@
+import type { SemanticHealthState } from "../../session/health-types.ts";
+
+/** Format the authoritative semantic-health state for Markdown and TUI status chrome. */
+export function formatSemanticHealthState(state: SemanticHealthState | null): string {
+  if (!state) return "not evaluated";
+  return state.kind === "ready" ? "ready" : `${state.kind} — ${state.reason}`;
+}
+
+/** Read semantic-health state from untyped PI result details. */
+export function readSemanticHealthState(value: unknown): SemanticHealthState | null {
+  if (typeof value !== "object" || value === null) return null;
+  const record = value as Record<string, unknown>;
+  if (record.kind === "ready") return { kind: "ready" };
+  if (
+    (record.kind === "pending" ||
+      record.kind === "inactive" ||
+      record.kind === "disabled" ||
+      record.kind === "unavailable") &&
+    typeof record.reason === "string"
+  ) {
+    return { kind: record.kind, reason: record.reason };
+  }
+  return null;
+}