@mrclrchtr/supi-code-intelligence 1.16.1 → 2.0.1

package/src/analysis/coverage/coverage-warnings.ts

@@ -0,0 +1,224 @@
+/**
+ * Coverage warning evaluation for degraded structural and semantic coverage.
+ *
+ * Normalizes LSP startup state, Tree-sitter health, and deprecated config keys
+ * into a structured warning report consumed by chat warnings, /supi-ci-status,
+ * and code_health.
+ */
+
+import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
+import { loadSupiConfigForScope } from "@mrclrchtr/supi-core/config";
+import { getDeprecatedLspKeys, loadConfig, scanMissingServers } from "@mrclrchtr/supi-lsp/api";
+
+export interface CoverageWarning {
+  type: "deprecated-key" | "language-disabled" | "missing-server" | "structural-unavailable";
+  message: string;
+  language?: string;
+  detail?: string;
+}
+
+export interface CoverageWarningReport {
+  hasWarnings: boolean;
+  warnings: CoverageWarning[];
+}
+
+export interface CoverageMissingServerSource {
+  getMissingServers(): Array<{ name: string; command: string; foundExtensions?: string[] }>;
+}
+
+/** Input needed to evaluate coverage. */
+export interface CoverageEvalInput {
+  deprecatedKeys: ReturnType<typeof getDeprecatedLspKeys>;
+  explicitlyDisabledLanguages: string[];
+  missingServers: Array<{ name: string; command: string; foundExtensions: string[] }>;
+  structuralState: { kind: string; reason?: string };
+}
+
+// ── Evaluation ───────────────────────────────────────────────
+
+/**
+ * Evaluate the current coverage state and return a structured warning report.
+ *
+ * Does not handle deduplication or grace period — callers are responsible
+ * for managing emission timing through CoverageWarningState.
+ */
+export function evaluateCoverageWarnings(input: CoverageEvalInput): CoverageWarningReport {
+  const warnings: CoverageWarning[] = [];
+
+  // 1. Deprecated keys
+  if (input.deprecatedKeys.projectEnabled || input.deprecatedKeys.globalEnabled) {
+    warnings.push({
+      type: "deprecated-key",
+      message:
+        "lsp.enabled is deprecated and ignored. Use lsp.servers.<language>.enabled: false for per-language disable.",
+    });
+  }
+  if (input.deprecatedKeys.projectActive || input.deprecatedKeys.globalActive) {
+    warnings.push({
+      type: "deprecated-key",
+      message:
+        "lsp.active is deprecated and ignored. All detected servers are attempted unless explicitly disabled.",
+    });
+  }
+
+  // 2. Explicitly disabled languages
+  for (const lang of input.explicitlyDisabledLanguages) {
+    warnings.push({
+      type: "language-disabled",
+      language: lang,
+      message: `Semantic coverage reduced: "${lang}" servers are disabled via lsp.servers.${lang}.enabled: false`,
+    });
+  }
+
+  // 3. Missing server binaries
+  for (const server of input.missingServers) {
+    warnings.push({
+      type: "missing-server",
+      language: server.name,
+      message: `Cannot start "${server.name}" server — "${server.command}" not found on PATH`,
+      detail:
+        server.foundExtensions.length > 0
+          ? `Affected file types: ${server.foundExtensions.join(", ")}`
+          : undefined,
+    });
+  }
+
+  // 4. Structural (Tree-sitter) failure
+  if (input.structuralState.kind === "unavailable") {
+    warnings.push({
+      type: "structural-unavailable",
+      message: `Structural coverage unavailable: ${input.structuralState.reason ?? "Tree-sitter initialization failed"}`,
+    });
+  }
+
+  return { hasWarnings: warnings.length > 0, warnings };
+}
+
+// ── Session state (deduplication + grace period) ─────────────
+
+/**
+ * Per-session state for managing warning emission timing and deduplication.
+ */
+export class CoverageWarningState {
+  private lastWarningsHash: string | null = null;
+  private forceEmitted = false;
+  private readonly startedAt: number;
+
+  constructor() {
+    this.startedAt = Date.now();
+  }
+
+  /**
+   * Return warnings that should be emitted to the user now.
+   *
+   * Deduplication is hash-based rather than once-per-session: if the
+   * warning set changes (e.g., a new missing server is detected), the
+   * new warnings are emitted. Identical sets are suppressed.
+   * - Respects grace period (no warnings before `gracePeriodMs` has elapsed)
+   * - An empty report (no warnings) does not consume emission state
+   */
+  getPendingWarnings(
+    report: CoverageWarningReport,
+    gracePeriodMs: number = 5_000,
+  ): CoverageWarning[] {
+    // Grace period: don't emit during initial pending/settling state
+    if (Date.now() - this.startedAt < gracePeriodMs) {
+      return [];
+    }
+
+    if (!report.hasWarnings || report.warnings.length === 0) {
+      return [];
+    }
+
+    if (this.forceEmitted) return [];
+
+    const nextHash = this.computeHash(report);
+    if (nextHash === this.lastWarningsHash) {
+      return [];
+    }
+
+    this.lastWarningsHash = nextHash;
+    return report.warnings;
+  }
+
+  /** Check whether a warning has already been emitted this session. */
+  get hasEmitted(): boolean {
+    return this.lastWarningsHash !== null;
+  }
+
+  /** Force the state to consider warnings as already emitted. Useful for testing. */
+  markEmitted(): void {
+    this.forceEmitted = true;
+    this.lastWarningsHash = "emitted";
+  }
+
+  /** Reset the session state. */
+  reset(): void {
+    this.forceEmitted = false;
+    this.lastWarningsHash = null;
+  }
+
+  private computeHash(report: CoverageWarningReport): string {
+    return report.warnings
+      .map((w) => `${w.type}:${w.language ?? ""}:${w.message}`)
+      .sort((a, b) => a.localeCompare(b))
+      .join("|");
+  }
+}
+
+// ── Runtime state gathering ─────────────────────────────────
+
+/**
+ * Gather the coverage evaluation input from current runtime state.
+ *
+ * Reads deprecated keys from supi-lsp, structural state from the
+ * workspace runtime, and explicitly disabled languages / missing server
+ * info from the LSP controller or a config-based fallback scan.
+ */
+export function gatherCoverageEvalInput(
+  cwd: string,
+  lspController: CoverageMissingServerSource | null,
+): CoverageEvalInput {
+  const deprecatedKeys = getDeprecatedLspKeys(cwd);
+  const structuralState = getDefaultWorkspaceRuntime().getWorkspace(cwd).structural.state;
+  const explicitlyDisabledLanguages = detectExplicitlyDisabledLanguages(cwd);
+  const missingServers = lspController
+    ? normalizeMissingServers(lspController.getMissingServers())
+    : scanMissingServers(loadConfig(cwd), cwd);
+
+  return {
+    deprecatedKeys,
+    explicitlyDisabledLanguages,
+    missingServers,
+    structuralState,
+  };
+}
+
+function normalizeMissingServers(
+  raw: Array<{ name: string; command: string; foundExtensions?: string[] }>,
+): Array<{ name: string; command: string; foundExtensions: string[] }> {
+  return raw.map((entry) => ({
+    name: entry.name,
+    command: entry.command,
+    foundExtensions: entry.foundExtensions ?? [],
+  }));
+}
+
+/** Read raw scoped config to find languages with `servers.<lang>.enabled: false`. */
+function detectExplicitlyDisabledLanguages(cwd: string): string[] {
+  const disabled = new Set<string>();
+  for (const scope of ["project", "global"] as const) {
+    const raw = loadSupiConfigForScope(
+      "lsp",
+      cwd,
+      { servers: {} as Record<string, { enabled?: boolean }> },
+      { scope },
+    );
+    const servers = (raw as { servers?: Record<string, { enabled?: boolean }> }).servers;
+    if (!servers) continue;
+    for (const [name, srv] of Object.entries(servers)) {
+      if (srv.enabled === false) disabled.add(name);
+    }
+  }
+  return [...disabled].sort();
+}

package/src/analysis/evidence.ts

@@ -0,0 +1,91 @@
+export type EvidencePartialReason = "timeout" | "safety-limit" | "interrupted" | "provider-limited";
+
+export interface EvidenceListMetadata {
+  key: string;
+  totalCount: number | null;
+  shownCount: number;
+  omittedCount: number | null;
+  partialReason: EvidencePartialReason | null;
+}
+
+export interface EvidenceList<T> {
+  key: string;
+  items: T[];
+  metadata: EvidenceListMetadata;
+}
+
+export interface CreateEvidenceListParams<T> {
+  key: string;
+  items: T[];
+  maxResults?: number;
+  sort?: (a: T, b: T) => number;
+}
+
+export interface CreatePartialEvidenceListParams<T> {
+  key: string;
+  items: T[];
+  partialReason: EvidencePartialReason;
+}
+
+export interface EvidenceListSummary {
+  omittedCount: number;
+  evidenceLists: EvidenceListMetadata[];
+}
+
+export function createEvidenceList<T>(params: CreateEvidenceListParams<T>): EvidenceList<T> {
+  const ordered = params.sort ? [...params.items].sort(params.sort) : [...params.items];
+  const maxResults = params.maxResults ?? ordered.length;
+  const items = ordered.slice(0, Math.max(0, maxResults));
+  const omittedCount = Math.max(0, ordered.length - items.length);
+
+  return {
+    key: params.key,
+    items,
+    metadata: {
+      key: params.key,
+      totalCount: ordered.length,
+      shownCount: items.length,
+      omittedCount,
+      partialReason: null,
+    },
+  };
+}
+
+export function createPartialEvidenceList<T>(
+  params: CreatePartialEvidenceListParams<T>,
+): EvidenceList<T> {
+  return {
+    key: params.key,
+    items: [...params.items],
+    metadata: {
+      key: params.key,
+      totalCount: null,
+      shownCount: params.items.length,
+      omittedCount: null,
+      partialReason: params.partialReason,
+    },
+  };
+}
+
+export function renderEvidenceListDisclosure<T>(list: EvidenceList<T>): string | null {
+  return renderEvidenceListMetadataDisclosure(list.metadata);
+}
+
+export function renderEvidenceListMetadataDisclosure(
+  metadata: EvidenceListMetadata,
+): string | null {
+  if (metadata.totalCount === null) {
+    if (metadata.partialReason === null) return null;
+    return `_(showing ${metadata.shownCount}; more may exist — ${metadata.partialReason})_`;
+  }
+
+  if ((metadata.omittedCount ?? 0) <= 0) return null;
+  return `_(showing ${metadata.shownCount} of ${metadata.totalCount}; ${metadata.omittedCount} omitted)_`;
+}
+
+export function summarizeEvidenceLists(lists: EvidenceList<unknown>[]): EvidenceListSummary {
+  return {
+    omittedCount: lists.reduce((sum, list) => sum + (list.metadata.omittedCount ?? 0), 0),
+    evidenceLists: lists.map((list) => list.metadata),
+  };
+}

package/src/{semantic-action-helpers.ts → analysis/helpers.ts}

@@ -1,5 +1,5 @@
-import type { ResolvedTarget, ResolvedTargetGroup } from "./target-resolution.ts";
-import type { ConfidenceMode } from "./types.ts";
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { ResolvedTargetData, ResolvedTargetGroupData } from "./target/types.ts";
 
 interface FileLineRef {
   file: string;
@@ -7,8 +7,8 @@ interface FileLineRef {
 }
 
 export function isResolvedTargetGroup(
-  target: ResolvedTarget | ResolvedTargetGroup,
-): target is ResolvedTargetGroup {
+  target: ResolvedTargetData | ResolvedTargetGroupData,
+): target is ResolvedTargetGroupData {
   return "targets" in target;
 }
 

package/src/analysis/provider.ts

@@ -0,0 +1,186 @@
+/**
+ * Explicit analysis request context.
+ *
+ * Wraps the shared capability broker (@mrclrchtr/supi-code-runtime) and
+ * workspace-session-local caches into an explicit context object that
+ * deep analysis modules consume instead of calling getCodeProvider(cwd)
+ * on their own.
+ *
+ * This is NOT a second capability registry — it's a composite read
+ * over the canonical broker plus session-scoped state.
+ */
+
+import {
+  getDefaultWorkspaceRuntime,
+  type SemanticProvider,
+  type StructuralProvider,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { getSessionLspService, type SessionLspServiceState } from "@mrclrchtr/supi-lsp/api";
+
+/**
+ * Unified code analysis provider combining semantic (LSP-backed) and
+ * structural (tree-sitter-backed) operations.
+ */
+export interface CodeProvider extends SemanticProvider, StructuralProvider {}
+
+/** Availability state for the code provider in a workspace. */
+export type CodeProviderState =
+  | { kind: "ready"; provider: CodeProvider; lspService: SessionLspServiceState }
+  | { kind: "unavailable"; reason: string };
+
+/**
+ * Explicit context object passed to analysis services.
+ *
+ * Contains the cwd, a CodeProvider (ready or unavailable), and
+ * any session-local model state that services need.
+ */
+export interface AnalysisContext {
+  cwd: string;
+  providerState: CodeProviderState;
+}
+
+/**
+ * Build an AnalysisContext for a workspace cwd.
+ *
+ * Reads the shared capability broker from @mrclrchtr/supi-code-runtime
+ * and returns a composite provider if at least one capability is available.
+ */
+export function buildAnalysisContext(cwd: string): AnalysisContext {
+  return {
+    cwd,
+    providerState: getCodeProviderState(cwd),
+  };
+}
+
+/**
+ * Get the code provider state for a workspace cwd from the shared runtime.
+ */
+export function getCodeProviderState(cwd: string): CodeProviderState {
+  const runtime = getDefaultWorkspaceRuntime();
+  const ws = runtime.getWorkspace(cwd);
+
+  const hasSemantic =
+    (ws.semantic.state.kind === "ready" || ws.semantic.state.kind === "pending") &&
+    ws.semantic.provider !== null;
+  const hasStructural = ws.structural.state.kind === "ready" && ws.structural.provider !== null;
+
+  if (!hasSemantic && !hasStructural) {
+    return {
+      kind: "unavailable",
+      reason: "No code provider initialized for this workspace",
+    };
+  }
+
+  return {
+    kind: "ready",
+    provider: createCompositeProvider(
+      (hasSemantic ? ws.semantic.provider : null) as SemanticProvider | null,
+      (hasStructural ? ws.structural.provider : null) as StructuralProvider | null,
+    ),
+    lspService: getSessionLspService(cwd),
+  };
+}
+
+/** Alias for getCodeProviderState — kept for backward compatibility. */
+export const getCodeProvider = getCodeProviderState;
+
+/**
+ * Create a single CodeProvider that delegates semantic methods to the
+ * semantic (LSP) provider and structural methods to the structural
+ * (tree-sitter) provider.
+ *
+ * Uses `...args` spread so that new optional parameters added to
+ * provider methods are forwarded automatically — no need to update
+ * the composite wrapper.
+ */
+function createCompositeProvider(
+  semantic: SemanticProvider | null,
+  structural: StructuralProvider | null,
+): CodeProvider {
+  return {
+    // ── Semantic methods ──────────────────────────────────────────────
+    async references(...args: Parameters<SemanticProvider["references"]>) {
+      return semantic?.references(...args) ?? null;
+    },
+    async implementation(...args: Parameters<SemanticProvider["implementation"]>) {
+      return semantic?.implementation(...args) ?? null;
+    },
+    async documentSymbols(...args: Parameters<SemanticProvider["documentSymbols"]>) {
+      return semantic?.documentSymbols(...args) ?? null;
+    },
+    async workspaceSymbols(...args: Parameters<SemanticProvider["workspaceSymbols"]>) {
+      return semantic?.workspaceSymbols(...args) ?? null;
+    },
+    async hover(...args: Parameters<NonNullable<SemanticProvider["hover"]>>) {
+      return semantic?.hover?.(...args) ?? null;
+    },
+    async definition(...args: Parameters<NonNullable<SemanticProvider["definition"]>>) {
+      return semantic?.definition?.(...args) ?? null;
+    },
+    async codeActions(...args: Parameters<NonNullable<SemanticProvider["codeActions"]>>) {
+      return semantic?.codeActions?.(...args) ?? [];
+    },
+    async codeActionTitles(...args: Parameters<NonNullable<SemanticProvider["codeActionTitles"]>>) {
+      return semantic?.codeActionTitles?.(...args) ?? null;
+    },
+    async rename(...args: Parameters<NonNullable<SemanticProvider["rename"]>>) {
+      const result = await semantic?.rename?.(...args);
+      return (
+        result ?? {
+          kind: "unavailable" as const,
+          reason: "Rename not available",
+        }
+      );
+    },
+
+    // ── Structural methods ────────────────────────────────────────────
+    async calleesAt(...args: Parameters<StructuralProvider["calleesAt"]>) {
+      return (
+        structural?.calleesAt(...args) ?? {
+          kind: "unavailable" as const,
+          message: "Structural analysis not available.",
+        }
+      );
+    },
+    async exports(...args: Parameters<StructuralProvider["exports"]>) {
+      return (
+        structural?.exports(...args) ?? {
+          kind: "unavailable" as const,
+          message: "Structural analysis not available.",
+        }
+      );
+    },
+    async outline(...args: Parameters<StructuralProvider["outline"]>) {
+      return (
+        structural?.outline(...args) ?? {
+          kind: "unavailable" as const,
+          message: "Structural analysis not available.",
+        }
+      );
+    },
+    async imports(...args: Parameters<StructuralProvider["imports"]>) {
+      return (
+        structural?.imports(...args) ?? {
+          kind: "unavailable" as const,
+          message: "Structural analysis not available.",
+        }
+      );
+    },
+    async nodeAt(...args: Parameters<StructuralProvider["nodeAt"]>) {
+      return (
+        structural?.nodeAt(...args) ?? {
+          kind: "unavailable" as const,
+          message: "Structural analysis not available.",
+        }
+      );
+    },
+    async callSites(...args: Parameters<StructuralProvider["callSites"]>) {
+      return (
+        structural?.callSites(...args) ?? {
+          kind: "unavailable" as const,
+          message: "Structural analysis not available.",
+        }
+      );
+    },
+  };
+}

package/src/analysis/read-next.ts

@@ -0,0 +1,126 @@
+export interface ReadNextItem {
+  file: string;
+  startLine: number;
+  endLine: number;
+  reason: string;
+}
+
+const DEFAULT_MAX_READ_LINES = 120;
+const DEFAULT_CONTEXT_BEFORE = 5;
+const DEFAULT_CONTEXT_AFTER = 40;
+
+interface ReadNextRangeInput extends ReadNextItem {
+  maxLines?: number;
+}
+
+/** Build read-next guidance for a known source range, bounded for readable tool output. */
+export function readNextRange(input: ReadNextRangeInput): ReadNextItem {
+  const maxLines = input.maxLines ?? DEFAULT_MAX_READ_LINES;
+  const start = Math.max(1, Math.floor(input.startLine));
+  const rawEnd = Math.max(start, Math.floor(input.endLine));
+  const end = Math.min(rawEnd, start + Math.max(1, maxLines) - 1);
+  return { file: input.file, startLine: start, endLine: end, reason: input.reason };
+}
+
+/** Build read-next guidance around a known point when no precise symbol range is available. */
+export function readNextAround(
+  file: string,
+  line: number,
+  reason: string,
+  options: { before?: number; after?: number; maxLines?: number } = {},
+): ReadNextItem {
+  const before = options.before ?? DEFAULT_CONTEXT_BEFORE;
+  const after = options.after ?? DEFAULT_CONTEXT_AFTER;
+  const start = Math.max(1, Math.floor(line) - before);
+  const end = Math.max(start, Math.floor(line) + after);
+  return readNextRange({
+    file,
+    startLine: start,
+    endLine: end,
+    reason,
+    maxLines: options.maxLines,
+  });
+}
+
+/** Render guidance-chrome source ranges that should be inspected with the built-in read tool. */
+export function renderReadNextSection(items: ReadNextItem[], maxItems = 3): string[] {
+  const visible = dedupeReadNextItems(items).slice(0, maxItems);
+  if (visible.length === 0) return [];
+
+  const lines = ["## Read Next"];
+  for (const item of visible) {
+    const lineCount = item.endLine - item.startLine + 1;
+    lines.push(
+      `- \`${item.file}\` ${formatLineRange(item)} — ${item.reason} (\`read\` offset ${item.startLine}, limit ${lineCount})`,
+    );
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatLineRange(item: ReadNextItem): string {
+  if (item.startLine === item.endLine) return `L${item.startLine}`;
+  return `L${item.startLine}–L${item.endLine}`;
+}
+
+// ── Higher-level builders (used by relation collectors and tool executors) ─
+
+/**
+ * Build a single read-next item to inspect the resolved target itself.
+ *
+ * Used by code_graph relation handlers and code_orientation to guide
+ * the agent toward reading the target's source range.
+ */
+export function readNextTarget(file: string, line: number, reason?: string): ReadNextItem {
+  return readNextAround(file, line, reason ?? "inspect the target implementation");
+}
+
+/**
+ * Build read-next items for the top N reference/call/implementation sites.
+ *
+ * Used by the references and callees relation handlers in collect-relation.ts
+ * to guide the agent toward the most relevant reference sites.
+ */
+export function readNextTopSites(
+  sites: ReadonlyArray<{ file: string; line: number }>,
+  maxSites = 2,
+  label = "reference",
+): ReadNextItem[] {
+  return sites
+    .slice(0, maxSites)
+    .map((site) => readNextAround(site.file, site.line, `inspect a ${label} site`));
+}
+
+/**
+ * Build a read-next item for an enclosing scope (function/class/block).
+ *
+ * Used by the callees relation handler and code_orientation's
+ * findEnclosingOutlineItem to guide the agent toward inspecting the
+ * scope that contains the target.
+ */
+export function readNextEnclosingScope(
+  file: string,
+  scope: { name?: string; startLine?: number; endLine?: number },
+  fallbackLine: number,
+  fallbackName?: string,
+): ReadNextItem {
+  const name = scope.name ?? fallbackName ?? "scope";
+  return readNextRange({
+    file,
+    startLine: scope.startLine ?? fallbackLine,
+    endLine: scope.endLine ?? scope.startLine ?? fallbackLine,
+    reason: `inspect enclosing scope \`${name}\``,
+  });
+}
+
+function dedupeReadNextItems(items: ReadNextItem[]): ReadNextItem[] {
+  const seen = new Set<string>();
+  const result: ReadNextItem[] = [];
+  for (const item of items) {
+    const key = `${item.file}:${item.startLine}:${item.endLine}:${item.reason}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+  }
+  return result;
+}