@mrclrchtr/supi-code-intelligence 1.16.1 → 2.0.0

package/src/tool/health/markdown.ts

@@ -0,0 +1,280 @@
+/**
+ * Markdown renderer for code_health results.
+ *
+ * Renders structured health data from the code_health executor into
+ * readable markdown sections keyed by requested `include` values.
+ */
+
+import type { CoverageWarningReport } from "../../analysis/coverage/coverage-warnings.ts";
+import type { GitContext } from "../../analysis/signals/git.ts";
+import { formatGitContext } from "../../analysis/signals/git.ts";
+
+export type HealthSection = "diagnostics" | "servers" | "dirty" | "coverage" | "unused";
+
+export interface HealthServerInfo {
+  name: string;
+  root: string;
+  fileTypes: string[];
+  status: string;
+}
+
+export interface HealthDiagnosticEntry {
+  file: string;
+  errors: number;
+  warnings: number;
+}
+
+export interface HealthCoverageEntry {
+  file: string;
+  pct: number;
+}
+
+export interface HealthCoverageData {
+  available: boolean;
+  entries: HealthCoverageEntry[];
+}
+
+export interface HealthUnusedExportEntry {
+  file: string;
+  name: string;
+}
+
+export interface HealthUnusedData {
+  available: boolean;
+  files: string[];
+  exports: HealthUnusedExportEntry[];
+}
+
+/** A suggested code action at a specific diagnostic location. */
+export interface CodeActionSuggestion {
+  file: string;
+  line: number;
+  title: string;
+  kind?: string;
+}
+
+export interface HealthData {
+  includedSections: HealthSection[];
+  lspAvailable: boolean;
+  lspStatus: string;
+  recovered: boolean;
+  /** Structural (tree-sitter) substrate readiness. Undefined when not evaluated. */
+  structuralStatus?: string;
+  diagnostics: HealthDiagnosticEntry[];
+  servers: HealthServerInfo[];
+  gitContext: GitContext | null;
+  scopeFilter: string | null;
+  level: "summary" | "detailed";
+  /** Code action suggestions collected from LSP (only populated in detailed mode). */
+  codeActions: CodeActionSuggestion[] | null;
+  coverage: HealthCoverageData | null;
+  unused: HealthUnusedData | null;
+  /** Coverage warnings for degraded semantic/structural substrate. Undefined when fully healthy. */
+  degradedCoverage?: CoverageWarningReport;
+  /** Seconds since diagnostics were last refreshed, or undefined if never refreshed. */
+  diagnosticAgeSeconds?: number;
+}
+
+export function renderHealthResult(data: HealthData, cwd: string): string {
+  const lines: string[] = ["## Code Health", ""];
+
+  renderStatusLine(lines, data);
+  renderStalenessBanner(lines, data);
+
+  if (data.includedSections.includes("diagnostics")) {
+    renderDiagnosticsSection(lines, data, cwd);
+  }
+  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);
+  }
+
+  return lines.join("\n");
+}
+
+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 renderDegradedCoverageSection(lines: string[], data: HealthData): void {
+  if (!data.degradedCoverage?.hasWarnings) return;
+
+  lines.push("### Degraded Coverage");
+  lines.push("");
+
+  for (const warning of data.degradedCoverage.warnings) {
+    const lang = warning.language ? `[${warning.language}] ` : "";
+    lines.push(`- ⚠ ${lang}${warning.message}`);
+    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");
+  }
+  lines.push("");
+}
+
+function renderDiagnosticsSection(lines: string[], data: HealthData, cwd: string): void {
+  lines.push("### Diagnostics");
+  lines.push("");
+
+  if (data.diagnostics.length === 0) {
+    lines.push("No diagnostics found.");
+  } else if (data.level === "summary") {
+    renderDiagnosticSummary(lines, data);
+  } else {
+    renderDiagnosticDetails(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._`,
+    );
+    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("");
+    return;
+  }
+
+  if (data.coverage.entries.length === 0) {
+    lines.push("No low-coverage files found.");
+    lines.push("");
+    return;
+  }
+
+  for (const entry of data.coverage.entries) {
+    lines.push(`- \`${makeRelative(cwd, entry.file)}\` — ${entry.pct.toFixed(0)}%`);
+  }
+  lines.push("");
+}
+
+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;
+  }
+
+  if (data.unused.files.length === 0 && data.unused.exports.length === 0) {
+    lines.push("No unused files or exports reported.");
+    lines.push("");
+    return;
+  }
+
+  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)}\``);
+  }
+  lines.push("");
+}
+
+function renderServersSection(lines: string[], data: HealthData): void {
+  lines.push("### Servers");
+  lines.push("");
+
+  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}`);
+  }
+  lines.push("");
+}
+
+function renderDirtySection(lines: string[], data: HealthData): void {
+  if (!data.gitContext) return;
+  lines.push(formatGitContext(data.gitContext));
+}
+
+function makeRelative(cwd: string, file: string): string {
+  if (file.startsWith(cwd)) {
+    return file.slice(cwd.length + 1);
+  }
+  return file;
+}

package/src/tool/health/orchestrate.ts

@@ -0,0 +1,159 @@
+/**
+ * Health orchestration use-case — gathers workspace health data and
+ * returns a rendered CodeIntelResult with structured details.
+ *
+ * Thin dispatcher: collects all requested sections, assembles the
+ * HealthData object, and delegates rendering to the markdown module.
+ * Section-specific collection lives in ./sections/.
+ */
+
+import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
+import type { CapabilityState } from "@mrclrchtr/supi-code-runtime/api";
+import type { SessionLspServiceState } from "@mrclrchtr/supi-lsp/api";
+import {
+  evaluateCoverageWarnings,
+  gatherCoverageEvalInput,
+} from "../../analysis/coverage/coverage-warnings.ts";
+import { loadPrioritizationSignals } from "../../analysis/signals/project.ts";
+import type { CodeIntelResult, HealthDetails } from "../../types/index.ts";
+import type { HealthData, HealthSection } from "./markdown.ts";
+import { renderHealthResult } from "./markdown.ts";
+import { collectCodeActions, collectDiagnostics } from "./sections/diagnostics.ts";
+import {
+  buildHealthEvidenceLists,
+  describeStructuralState,
+  maybeRecover,
+} from "./sections/recovery.ts";
+import {
+  collectCoverageSection,
+  collectGitContext,
+  collectServers,
+  collectUnusedSection,
+  needsPrioritizationSignals,
+} from "./sections/signals.ts";
+
+export interface HealthInput {
+  scope?: string;
+  refresh?: boolean;
+  include?: string[];
+  level?: "summary" | "detailed";
+  coveragePath?: string;
+  unusedPath?: string;
+}
+
+export interface HealthDeps {
+  cwd: string;
+  lspState: SessionLspServiceState;
+  providerAvailable: boolean;
+  semanticStateKind: "pending" | "ready" | "inactive" | "disabled" | "unavailable";
+  structuralState: CapabilityState;
+  lspController: import("@mrclrchtr/supi-lsp/api").LspRuntimeController | null;
+  onUpdate?: AgentToolUpdateCallback;
+  scopeFilter: string | null;
+  lastRefresh: number | undefined;
+}
+
+const DEFAULT_INCLUDE: HealthSection[] = ["diagnostics", "servers"];
+
+/** Last diagnostic refresh time by workspace path (for staleness banner). */
+const lastRefreshByWorkspace = new Map<string, number>();
+
+/** Track a diagnostic refresh for the given workspace. */
+export function trackHealthRefresh(cwd: string): void {
+  lastRefreshByWorkspace.set(cwd, Date.now());
+}
+
+/** Get the last refresh time for a workspace. */
+export function getLastHealthRefresh(cwd: string): number | undefined {
+  return lastRefreshByWorkspace.get(cwd);
+}
+
+/**
+ * Execute the health gathering use-case.
+ */
+export async function executeHealth(
+  input: HealthInput,
+  deps: HealthDeps,
+): Promise<CodeIntelResult> {
+  const cwd = deps.cwd;
+  const included = (
+    input.include && input.include.length > 0 ? input.include : DEFAULT_INCLUDE
+  ) as HealthSection[];
+  const level = input.level ?? "summary";
+
+  const service = deps.lspState.kind === "ready" ? deps.lspState.service : null;
+
+  const { recovered, lspStatus } = await maybeRecover({
+    service,
+    refresh: input.refresh,
+    lspState: deps.lspState,
+    semanticStateKind: deps.semanticStateKind,
+    onUpdate: deps.onUpdate,
+  });
+  const structuralStatus = describeStructuralState(deps.structuralState);
+
+  const diagnostics = await collectDiagnostics(service, included, deps.scopeFilter, cwd);
+  const servers = collectServers(service, included);
+  const gitContext = collectGitContext(included, cwd);
+  const prioritizationSignals = needsPrioritizationSignals(included)
+    ? loadPrioritizationSignals(cwd, deps.lspState, {
+        coveragePath: input.coveragePath,
+        unusedPath: input.unusedPath,
+      })
+    : null;
+  const coverage = included.includes("coverage")
+    ? collectCoverageSection(prioritizationSignals, cwd, deps.scopeFilter, input.coveragePath)
+    : null;
+  const unused = included.includes("unused")
+    ? collectUnusedSection(prioritizationSignals, cwd, deps.scopeFilter, input.unusedPath)
+    : null;
+
+  const codeActions =
+    level === "detailed" && included.includes("diagnostics")
+      ? await collectCodeActions(service, deps.scopeFilter, cwd)
+      : null;
+
+  const degradedCoverage = evaluateCoverageWarnings(
+    gatherCoverageEvalInput(cwd, deps.lspController),
+  );
+
+  const diagnosticAgeSeconds =
+    deps.lastRefresh != null ? Math.round((Date.now() - deps.lastRefresh) / 1000) : undefined;
+
+  const data: HealthData = {
+    includedSections: included,
+    lspAvailable: service !== null,
+    lspStatus,
+    recovered,
+    structuralStatus,
+    diagnostics,
+    servers,
+    gitContext,
+    scopeFilter: input.scope ? deps.scopeFilter : null,
+    level,
+    codeActions,
+    coverage,
+    unused,
+    degradedCoverage: degradedCoverage.hasWarnings ? degradedCoverage : undefined,
+    diagnosticAgeSeconds,
+  };
+
+  const evidenceLists = buildHealthEvidenceLists(gitContext);
+  const content = renderHealthResult(data, cwd);
+
+  return {
+    content,
+    details: {
+      type: "health",
+      data: {
+        lspAvailable: data.lspAvailable,
+        lspStatus: data.lspStatus,
+        recovered: data.recovered,
+        structuralStatus: data.structuralStatus,
+        diagnosticFileCount: data.diagnostics.length,
+        serverCount: data.servers.length,
+        evidenceLists,
+      } satisfies HealthDetails,
+    },
+  };
+}

package/src/tool/health/sections/diagnostics.ts

@@ -0,0 +1,182 @@
+// Diagnostics collection and code-action gathering for code_health.
+// Extracted from orchestrate.ts.
+
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
+import type { SessionLspService } from "@mrclrchtr/supi-lsp/api";
+import type { CodeActionSuggestion, HealthData } from "../markdown.ts";
+
+// ── Diagnostics ───────────────────────────────────────────────────────
+
+export function isScopedFile(scopeFilter: string | null): scopeFilter is string {
+  return scopeFilter !== null && existsSync(scopeFilter) && !isDirectory(scopeFilter);
+}
+
+export async function collectDiagnostics(
+  service: SessionLspService | null,
+  included: string[],
+  scopeFilter: string | null,
+  cwd: string,
+): Promise<HealthData["diagnostics"]> {
+  if (!included.includes("diagnostics") || !service) return [];
+
+  if (isScopedFile(scopeFilter)) {
+    return collectScopedFileDiagnostics(service, scopeFilter);
+  }
+
+  return collectWorkspaceDiagnostics(service, scopeFilter, cwd);
+}
+
+async function collectScopedFileDiagnostics(
+  service: SessionLspService,
+  scopeFilter: string,
+): Promise<HealthData["diagnostics"]> {
+  const diags = await service.fileDiagnostics(scopeFilter, 4);
+  if (!diags || diags.length === 0) {
+    return [];
+  }
+
+  const errors = diags.filter((d) => (d.severity ?? 1) === 1).length;
+  const warnings = diags.filter((d) => (d.severity ?? 1) === 2).length;
+  if (!hasIssueCounts(errors, warnings)) {
+    return [];
+  }
+
+  return [{ file: scopeFilter, errors, warnings }];
+}
+
+function collectWorkspaceDiagnostics(
+  service: SessionLspService,
+  scopeFilter: string | null,
+  cwd: string,
+): HealthData["diagnostics"] {
+  const summary = service.getWorkspaceDiagnosticSummary();
+  const result: HealthData["diagnostics"] = [];
+
+  for (const entry of summary) {
+    const filePath = resolve(cwd, entry.file);
+    if (scopeFilter && !isWithinOrEqual(scopeFilter, filePath)) continue;
+    if (!hasIssueCounts(entry.errors, entry.warnings)) continue;
+    result.push({ file: filePath, errors: entry.errors, warnings: entry.warnings });
+  }
+
+  return result;
+}
+
+function hasIssueCounts(errors: number, warnings: number): boolean {
+  return errors > 0 || warnings > 0;
+}
+
+// ── Code actions ──────────────────────────────────────────────────────
+
+/** Max files to query for code actions in detailed health mode. */
+const MAX_CODE_ACTION_FILES = 5;
+/** Max total code action suggestions to return. */
+const MAX_CODE_ACTION_SUGGESTIONS = 10;
+
+export async function collectCodeActions(
+  service: SessionLspService | null,
+  scopeFilter: string | null,
+  cwd: string,
+): Promise<CodeActionSuggestion[]> {
+  if (!service) return [];
+
+  try {
+    const outstanding = service.getOutstandingDiagnostics(1);
+    const suggestions = await collectFromOutstanding(service, outstanding, scopeFilter, cwd);
+    return suggestions.slice(0, MAX_CODE_ACTION_SUGGESTIONS);
+  } catch {
+    return [];
+  }
+}
+
+async function collectFromOutstanding(
+  service: SessionLspService,
+  outstanding: ReturnType<SessionLspService["getOutstandingDiagnostics"]>,
+  scopeFilter: string | null,
+  cwd: string,
+): Promise<CodeActionSuggestion[]> {
+  const suggestions: CodeActionSuggestion[] = [];
+  let filesQueried = 0;
+
+  for (const entry of outstanding) {
+    if (suggestions.length >= MAX_CODE_ACTION_SUGGESTIONS) break;
+    if (filesQueried >= MAX_CODE_ACTION_FILES) break;
+    if (scopeFilter && !isWithinScope(scopeFilter, entry.file, cwd)) continue;
+
+    const newSuggestions = await collectFileCodeActions(service, entry);
+    if (newSuggestions.length === 0) continue;
+
+    filesQueried++;
+    mergeSuggestions(suggestions, newSuggestions);
+  }
+
+  return suggestions;
+}
+
+function mergeSuggestions(
+  existing: CodeActionSuggestion[],
+  incoming: CodeActionSuggestion[],
+): void {
+  const seen = new Set(existing.map((s) => `${s.file}:${s.title}`));
+  for (const s of incoming) {
+    const key = `${s.file}:${s.title}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      existing.push(s);
+    }
+  }
+}
+
+async function collectFileCodeActions(
+  service: SessionLspService,
+  entry: {
+    file: string;
+    diagnostics: Array<{
+      severity?: number;
+      range: {
+        start: { line: number; character: number };
+        end: { line: number; character: number };
+      };
+    }>;
+  },
+): Promise<CodeActionSuggestion[]> {
+  const errorDiag = entry.diagnostics.find((d) => (d.severity ?? 1) <= 1);
+  if (!errorDiag) return [];
+
+  try {
+    const actions = await service.codeActions(entry.file, {
+      line: errorDiag.range.start.line,
+      character: errorDiag.range.start.character,
+    });
+    if (!actions || actions.length === 0) return [];
+
+    const result: CodeActionSuggestion[] = [];
+    for (const a of actions) {
+      if (!a.title) continue;
+      result.push({
+        file: entry.file,
+        line: errorDiag.range.start.line + 1,
+        title: a.title,
+        kind: a.kind ?? undefined,
+      });
+    }
+    return result;
+  } catch {
+    return [];
+  }
+}
+
+function isWithinScope(scopeFilter: string, file: string, cwd: string): boolean {
+  const absPath = resolve(cwd, file);
+  return isWithinOrEqual(scopeFilter, absPath);
+}
+
+export function isDirectory(filePath: string): boolean {
+  try {
+    return statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/tool/health/sections/recovery.ts

@@ -0,0 +1,89 @@
+// Recovery, state description, and evidence helpers for code_health.
+// Extracted from orchestrate.ts.
+
+import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
+import type { CapabilityState } from "@mrclrchtr/supi-code-runtime/api";
+import type { SessionLspService, SessionLspServiceState } from "@mrclrchtr/supi-lsp/api";
+import { createEvidenceList, type EvidenceListMetadata } from "../../../analysis/evidence.ts";
+import type { GitContext } from "../../../analysis/signals/git.ts";
+import { emitToolProgress } from "../../infra/progress.ts";
+
+// ── Recovery ──────────────────────────────────────────────────────────
+
+interface RecoverOptions {
+  service: SessionLspService | null;
+  refresh: boolean | undefined;
+  lspState: SessionLspServiceState;
+  semanticStateKind?: "pending" | "ready" | "inactive" | "disabled" | "unavailable";
+  onUpdate?: AgentToolUpdateCallback;
+}
+
+export async function maybeRecover(
+  opts: RecoverOptions,
+): Promise<{ recovered: boolean; lspStatus: string }> {
+  const { service, refresh, lspState, semanticStateKind, onUpdate } = opts;
+  let recovered = false;
+  let lspStatus = semanticStateKind === "pending" ? "warming…" : describeLspState(lspState);
+
+  if (refresh && service) {
+    emitToolProgress(onUpdate, "code_health: refreshing diagnostics (may restart LSP)...");
+    try {
+      await service.recoverDiagnostics({ restartIfStillStale: true });
+      recovered = true;
+      lspStatus = "ready (recovered)";
+    } catch {
+      // Recovery failed but we continue
+    }
+  }
+
+  return { recovered, lspStatus };
+}
+
+// ── Evidence lists ────────────────────────────────────────────────────
+
+export function buildHealthEvidenceLists(gitContext: GitContext | null): EvidenceListMetadata[] {
+  if (!gitContext) return [];
+  return [
+    createEvidenceList({
+      key: "health.dirtyFiles",
+      items: gitContext.dirtyFiles,
+      maxResults: 5,
+    }).metadata,
+  ];
+}
+
+// ── State description helpers ─────────────────────────────────────────
+
+export function describeLspState(state: SessionLspServiceState): string {
+  switch (state.kind) {
+    case "ready":
+      return "ready";
+    case "pending":
+      return "starting…";
+    case "inactive":
+      return "inactive on current session branch";
+    case "disabled":
+      return "disabled by configuration";
+    case "unavailable":
+      return `unavailable — ${state.reason}`;
+    default:
+      return "unknown state";
+  }
+}
+
+export function describeStructuralState(state: CapabilityState): string {
+  switch (state.kind) {
+    case "ready":
+      return "ready";
+    case "pending":
+      return "starting…";
+    case "inactive":
+      return "inactive";
+    case "disabled":
+      return "disabled by configuration";
+    case "unavailable":
+      return `unavailable — ${state.reason}`;
+    default:
+      return "unknown state";
+  }
+}