@mrclrchtr/supi-code-intelligence 1.16.1 → 2.0.0

package/src/session/session.ts

@@ -0,0 +1,300 @@
+/**
+ * Workspace code-intelligence session facade.
+ *
+ * Per-workspace facade that owns session-scoped state (targets, plans,
+ * coverage warnings) and provides typed workflow methods for all
+ * public code_* tools. Tool executors receive this session explicitly
+ * through their execution context; the session centralizes provider
+ * access, target resolution, plan management, and readiness policy.
+ *
+ * The session does NOT own the shared capability broker in
+ * @mrclrchtr/supi-code-runtime — it reads from it. It does NOT
+ * render markdown or manage TUI state — executors and rendering
+ * modules keep that.
+ *
+ * @mrclrchtr/supi-code-intelligence — internal, not exported via api.ts
+ */
+
+import {
+  getDefaultWorkspaceRuntime,
+  type SemanticProvider,
+  type StructuralProvider,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type { LspRuntimeController } from "@mrclrchtr/supi-lsp/api";
+import { CoverageWarningState } from "../analysis/coverage/coverage-warnings.ts";
+import type { CodeProvider } from "../analysis/provider.ts";
+import { getCodeProvider } from "../analysis/provider.ts";
+import { getPlan, type RefactorPlan, removePlan, storePlan } from "./refactor-plans.ts";
+import {
+  getWorkflowTarget,
+  registerWorkflowTarget,
+  type TargetLookupResult,
+  type TargetRegistrationInput,
+  type TargetRegistrationOutput,
+  type TargetStoreEntry,
+} from "./target-store.ts";
+
+// ── Re-export types consumed by callers ───────────────────────────────
+
+export type { CoverageWarningState } from "../analysis/coverage/coverage-warnings.ts";
+export type { CodeProvider, CodeProviderState } from "../analysis/provider.ts";
+export type { RefactorPlan } from "./refactor-plans.ts";
+export type {
+  TargetLookupResult,
+  TargetRegistrationInput,
+  TargetRegistrationOutput,
+  TargetStoreEntry,
+} from "./target-store.ts";
+
+// ── Target ID expansion result ────────────────────────────────────────
+
+export type TargetIdExpansionResult =
+  | {
+      kind: "ok";
+      file: string;
+      line: number;
+      character: number;
+      targetName: string | null;
+      targetKind: string | null;
+      entry: TargetStoreEntry;
+    }
+  | { kind: "not-provided" }
+  | { kind: "error"; message: string };
+
+// ── Session class ─────────────────────────────────────────────────────
+
+/**
+ * Per-cwd workspace code-intelligence session.
+ *
+ * Owns session-scoped state and provides centralized methods for
+ * provider access, target resolution, plan management, and readiness
+ * policy. Lifecycle modules attach controller references.
+ */
+export class WorkspaceCodeIntelligenceSession {
+  /** Canonical workspace directory for this session. */
+  readonly cwd: string;
+
+  /** Whether the hidden architecture overview has been injected. */
+  hasInjectedOverview = false;
+
+  /** Session-scoped workflow target storage (targetId → entry). */
+  readonly #workflowTargets = new Map<string, TargetStoreEntry>();
+
+  /** Session-scoped refactor plan storage (planId → plan). */
+  readonly #refactorPlans = new Map<string, RefactorPlan>();
+
+  /**
+   * Coverage warning state for deduplication and grace-period timing.
+   */
+  readonly coverageWarningState = new CoverageWarningState();
+
+  /**
+   * Optional LSP controller reference — attached by LSP lifecycle module
+   * for coverage evaluation and server management.
+   */
+  lspController: LspRuntimeController | null = null;
+
+  /**
+   * Optional Tree-sitter controller reference — attached by TS lifecycle
+   * module for structural provider lifecycle management.
+   */
+  tsController: import("@mrclrchtr/supi-tree-sitter/api").TreeSitterRuntimeController | null = null;
+
+  constructor(cwd: string) {
+    this.cwd = cwd;
+  }
+
+  // ── Provider access ───────────────────────────────────────────────
+
+  /**
+   * Get the composite code provider state for this workspace.
+   * Combines semantic (LSP) and structural (tree-sitter) capabilities
+   * along with LSP service state.
+   */
+  getProviders(): import("../analysis/provider.ts").CodeProviderState {
+    return getCodeProvider(this.cwd);
+  }
+
+  /**
+   * Get the ready composite code provider, or null if unavailable.
+   */
+  getProvider(): CodeProvider | null {
+    const state = this.getProviders();
+    return state.kind === "ready" ? state.provider : null;
+  }
+
+  /**
+   * Get the semantic provider from the shared runtime.
+   */
+  getSemanticProvider(): SemanticProvider | null {
+    const ws = getDefaultWorkspaceRuntime().getWorkspace(this.cwd);
+    if (
+      (ws.semantic.state.kind === "ready" || ws.semantic.state.kind === "pending") &&
+      ws.semantic.provider !== null
+    ) {
+      return ws.semantic.provider as SemanticProvider;
+    }
+    return null;
+  }
+
+  /**
+   * Get the structural provider from the shared runtime.
+   */
+  getStructuralProvider(): StructuralProvider | null {
+    const ws = getDefaultWorkspaceRuntime().getWorkspace(this.cwd);
+    if (ws.structural.state.kind === "ready" && ws.structural.provider !== null) {
+      return ws.structural.provider as StructuralProvider;
+    }
+    return null;
+  }
+
+  /**
+   * Get the raw workspace state from the shared runtime.
+   *
+   * Exposes semantic/structural state and provider refs for tools
+   * that need detailed status (e.g. code_health). Prefer higher-level
+   * methods (`getProvider()`, `getSemanticProvider()`) when you only
+   * need a ready provider reference.
+   */
+  getWorkspaceState() {
+    return getDefaultWorkspaceRuntime().getWorkspace(this.cwd);
+  }
+
+  // ── Target resolution ─────────────────────────────────────────────
+
+  /**
+   * Look up a stored target by targetId in this session's store.
+   */
+  lookupTargetId(targetId: string): TargetLookupResult {
+    return getWorkflowTarget(this.#workflowTargets, targetId);
+  }
+
+  /**
+   * Register a resolved target in this session's store and return
+   * stable session-scoped handles.
+   */
+  registerTarget(input: TargetRegistrationInput): TargetRegistrationOutput {
+    return registerWorkflowTarget(this.#workflowTargets, this.cwd, input);
+  }
+
+  /**
+   * Expand an optional targetId from tool params into anchored
+   * file/line/character.
+   *
+   * Usage at the top of each target-oriented executor:
+   *
+   * ```ts
+   * const expansion = session.expandTargetId(params);
+   * if (expansion.kind === "error") return errorResult(expansion.message);
+   * if (expansion.kind === "ok") {
+   *   params.file = expansion.file;
+   *   params.line = expansion.line;
+   *   params.character = expansion.character;
+   * }
+   * ```
+   */
+  expandTargetId(params: {
+    targetId?: string;
+    file?: string;
+    line?: number;
+    character?: number;
+    symbol?: string;
+  }): TargetIdExpansionResult {
+    return expandSessionTargetId(this, params);
+  }
+
+  /**
+   * Look up a targetId without expanding into file/line/character.
+   * Returns the raw store entry or an error.
+   */
+  lookupTargetEntry(targetId: string): TargetLookupResult {
+    return getWorkflowTarget(this.#workflowTargets, targetId);
+  }
+
+  // ── Plan store ────────────────────────────────────────────────────
+
+  /**
+   * Store a refactor plan and return its planId.
+   */
+  storePlan(plan: RefactorPlan): string {
+    return storePlan(this.#refactorPlans, plan);
+  }
+
+  /**
+   * Retrieve a plan by id, or undefined.
+   */
+  getPlan(id: string): RefactorPlan | undefined {
+    return getPlan(this.#refactorPlans, id);
+  }
+
+  /**
+   * Remove a plan after successful apply.
+   */
+  removePlan(id: string): void {
+    removePlan(this.#refactorPlans, id);
+  }
+
+  // ── Introspection (for tests / debugging) ───────────────────────
+
+  /** Number of stored targets (for test isolation checks). */
+  get targetCount(): number {
+    return this.#workflowTargets.size;
+  }
+
+  /** Number of stored refactor plans (for test isolation checks). */
+  get planCount(): number {
+    return this.#refactorPlans.size;
+  }
+
+  // ── Cleanup ───────────────────────────────────────────────────────
+
+  /** Clear all session-scoped stores. */
+  clearStores(): void {
+    this.#refactorPlans.clear();
+    this.#workflowTargets.clear();
+  }
+}
+
+// ── Standalone target-id expansion helper ─────────────────────────────
+
+/**
+ * Expand an optional targetId into anchored file/line/character params
+ * using the given session's store.
+ *
+ * Exported separately so executors that already hold a session ref
+ * can call it directly, without going through an ad-hoc session factory.
+ */
+export function expandSessionTargetId(
+  session: WorkspaceCodeIntelligenceSession,
+  params: {
+    targetId?: string;
+    file?: string;
+    line?: number;
+    character?: number;
+    symbol?: string;
+  },
+): TargetIdExpansionResult {
+  const targetId = params.targetId;
+  if (targetId === undefined || targetId === null) {
+    return { kind: "not-provided" };
+  }
+
+  const result = session.lookupTargetEntry(targetId);
+  if (result.kind === "unavailable") {
+    return {
+      kind: "error",
+      message: `**Error:** ${result.reason}`,
+    };
+  }
+
+  const { entry } = result;
+  return {
+    kind: "ok",
+    file: entry.file,
+    line: entry.displayLine,
+    character: entry.displayCharacter,
+    targetName: entry.name,
+    targetKind: entry.kind,
+    entry,
+  };
+}

package/src/session/target-store.ts

@@ -0,0 +1,293 @@
+/**
+ * Workflow target store — per-session target and span handle registry.
+ *
+ * Provides deterministic opaque IDs derived from cwd, file, position,
+ * metadata, and file fingerprint. Re-resolving the same target with
+ * unchanged file contents reuses the same IDs.
+ *
+ * The store map is passed in from the caller; this module provides pure
+ * functions without module-level state.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+
+// ── Public types ──────────────────────────────────────────────────────
+
+/**
+ * Which anchor a resolved target carries, per ADR 0003.
+ * - `name` — the identifier token (preferred by position-strict substrates).
+ * - `declaration` — the defining node start (export/modifiers); a fallback
+ *   when the name anchor could not be derived. Position-strict consumers
+ *   (rename, callees) must refuse rather than silently use it.
+ */
+export type AnchorKind = "name" | "declaration";
+
+/**
+ * A stored resolved target entry with handles and metadata.
+ *
+ * This is the canonical post-registration target type — all tool layers
+ * (executors, renderers, details) use it directly. Computed fields like
+ * relative paths are derived at the rendering boundary.
+ */
+export interface TargetStoreEntry {
+  targetId: string;
+  spanId: string;
+  /** Absolute filesystem path. Compute relative paths at render time with `path.relative(cwd, file)`. */
+  file: string;
+  /** 0-based position for LSP calls. */
+  position: { line: number; character: number };
+  /** 1-based position for user display. */
+  displayLine: number;
+  displayCharacter: number;
+  name: string | null;
+  kind: string | null;
+  confidence: ConfidenceMode;
+  provenance: string;
+  /** Which anchor this target carries — drives strict-consumer enforcement (ADR 0003). */
+  anchorKind: AnchorKind;
+  fileFingerprint: string;
+  /** Symbolic container (class/namespace/module name), or null for top-level. */
+  container: string | null;
+  /**
+   * Resolution provenance — present when the target was resolved from
+   * anchored coordinates. Carries requested/resolved coordinates, whether
+   * the anchor was snapped, and the provider-backed evidence source.
+   */
+  resolution?: import("../types/index.ts").AnchoredResolutionMetadata;
+}
+
+/** Input shape for registering a resolved target. */
+export interface TargetRegistrationInput {
+  file: string;
+  position: { line: number; character: number };
+  displayLine: number;
+  displayCharacter: number;
+  name: string | null;
+  kind: string | null;
+  confidence: ConfidenceMode;
+  provenance: string;
+  /** Which anchor this target carries — drives strict-consumer enforcement (ADR 0003). */
+  anchorKind: AnchorKind;
+  /** Symbolic container (class/namespace/module name), or null for top-level (ADR 0003 — disambiguates same-file collisions in the identity hash). */
+  container: string | null;
+  /**
+   * Resolution provenance — present when the target was resolved from
+   * anchored coordinates. Carries requested/resolved coordinates, whether
+   * the anchor was snapped, and the provider-backed evidence source.
+   */
+  resolution?: import("../types/index.ts").AnchoredResolutionMetadata;
+}
+
+/** Output from registering a target: stable session-scoped handles and the full stored entry. */
+export interface TargetRegistrationOutput {
+  targetId: string;
+  spanId: string;
+  entry: TargetStoreEntry;
+}
+
+/** Lookup result for a target ID query. */
+export type TargetLookupResult =
+  | { kind: "available"; entry: TargetStoreEntry }
+  | { kind: "unavailable"; reason: string };
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function normalizeCwd(cwd: string): string {
+  return cwd.replace(/\\/g, "/").replace(/\/$/, "");
+}
+
+// ── File fingerprinting ───────────────────────────────────────────────
+
+/**
+ * Compute a full-file SHA-256 fingerprint for staleness detection.
+ * Returns an error result when the file is missing or unreadable.
+ */
+export function computeFileFingerprint(
+  file: string,
+): { kind: "ok"; fingerprint: string } | { kind: "error"; message: string } {
+  try {
+    if (!existsSync(file)) {
+      return { kind: "error", message: `File not found: \`${file}\`` };
+    }
+    const content = readFileSync(file, { flag: "r" });
+    const hash = createHash("sha256").update(content).digest("hex");
+    return { kind: "ok", fingerprint: hash };
+  } catch {
+    return { kind: "error", message: `Cannot read file: \`${file}\`` };
+  }
+}
+
+// ── ID generation ─────────────────────────────────────────────────────
+
+/**
+ * Build a deterministic target handle from target identity fields.
+ *
+ * Per ADR 0003, position is intentionally excluded from symbol identity:
+ * nameAnchor is best-effort, so the same symbol can resolve to a name
+ * anchor or fall back to the declaration anchor across calls; including
+ * position would break the "re-resolve reuses the same IDs" invariant.
+ * Identity is cwd, file path, name, kind, container, and fingerprint.
+ */
+function computeTargetId(opts: {
+  cwd: string;
+  file: string;
+  position: { line: number; character: number };
+  name: string | null;
+  kind: string | null;
+  container: string | null;
+  fingerprint: string;
+}): string {
+  const hash = createHash("sha256");
+  hash.update(normalizeCwd(opts.cwd));
+  hash.update("\0");
+  hash.update(resolve(opts.cwd, opts.file));
+  hash.update("\0");
+  hash.update(opts.name ?? "");
+  hash.update("\0");
+  hash.update(opts.kind ?? "");
+  hash.update("\0");
+  hash.update(opts.container ?? "");
+  hash.update("\0");
+  hash.update(opts.fingerprint);
+  return `tg-${hash.digest("hex").slice(0, 28)}`;
+}
+
+/**
+ * Build a deterministic span handle from the file and 0-based range.
+ */
+function computeSpanId(
+  cwd: string,
+  file: string,
+  position: { line: number; character: number },
+  fingerprint: string,
+): string {
+  const hash = createHash("sha256");
+  hash.update(normalizeCwd(cwd));
+  hash.update("\0");
+  hash.update(resolve(cwd, file));
+  hash.update("\0");
+  hash.update(`${position.line}:${position.character}`);
+  hash.update("\0");
+  hash.update(fingerprint);
+  return `sp-${hash.digest("hex").slice(0, 24)}`;
+}
+
+// ── Public API ────────────────────────────────────────────────────────
+
+/**
+ * Register a resolved target in the given session-scoped store and return
+ * stable session-scoped handles.
+ *
+ * If the same target (same file, position, name, kind) is registered
+ * and the file fingerprint matches, the same IDs are returned.
+ *
+ * Returns an error when the backing file cannot be read for fingerprinting.
+ */
+export function registerWorkflowTarget(
+  store: Map<string, TargetStoreEntry>,
+  cwd: string,
+  input: TargetRegistrationInput,
+): TargetRegistrationOutput {
+  const key = normalizeCwd(cwd);
+  const absFile = resolve(cwd, input.file);
+
+  // Compute fingerprint; if unavailable, still allow registration but
+  // mark as unfingerprinted so stale checks know the fingerprint is absent
+  const fingerprintResult = computeFileFingerprint(absFile);
+  const fingerprint =
+    fingerprintResult.kind === "ok" ? fingerprintResult.fingerprint : "unfingerprinted";
+
+  const targetId = computeTargetId({
+    cwd: key,
+    file: input.file,
+    position: input.position,
+    name: input.name,
+    kind: input.kind,
+    container: input.container,
+    fingerprint,
+  });
+  const spanId = computeSpanId(key, input.file, input.position, fingerprint);
+
+  // Check for existing entry with same targetId
+  const existing = store.get(targetId);
+  if (existing) {
+    return { targetId: existing.targetId, spanId: existing.spanId, entry: existing };
+  }
+
+  const entry: TargetStoreEntry = {
+    targetId,
+    spanId,
+    file: absFile,
+    position: { line: input.position.line, character: input.position.character },
+    displayLine: input.displayLine,
+    displayCharacter: input.displayCharacter,
+    name: input.name,
+    kind: input.kind,
+    confidence: input.confidence,
+    provenance: input.provenance,
+    anchorKind: input.anchorKind,
+    fileFingerprint: fingerprint,
+    container: input.container,
+    resolution: input.resolution,
+  };
+
+  store.set(targetId, entry);
+
+  return { targetId, spanId, entry };
+}
+
+/**
+ * Look up a stored target by targetId in the given session-scoped store.
+ *
+ * Returns `{ kind: "available", entry }` when found.
+ * Returns `{ kind: "unavailable", reason }` when unknown or stale.
+ *
+ * Staleness is detected by comparing the stored fileFingerprint
+ * against the current file contents. If the fingerprint was
+ * "unfingerprinted" (file was unreadable at registration time),
+ * staleness cannot be confirmed and the entry is returned as-is.
+ */
+export function getWorkflowTarget(
+  store: Map<string, TargetStoreEntry>,
+  targetId: string,
+): TargetLookupResult {
+  const entry = store.get(targetId);
+  if (!entry) {
+    return {
+      kind: "unavailable",
+      reason: `Target \`${targetId}\` not found. It may have been cleared or never registered.`,
+    };
+  }
+
+  // Check staleness: re-fingerprint unfingerprinted entries and
+  // compare fingerprints for entries with known fingerprints.
+  const current = computeFileFingerprint(entry.file);
+  if (current.kind === "error") {
+    // File is gone or unreadable — remove and report unavailable
+    store.delete(targetId);
+    return {
+      kind: "unavailable",
+      reason: `${current.message} — target \`${targetId}\` is no longer available.`,
+    };
+  }
+
+  if (entry.fileFingerprint === "unfingerprinted") {
+    // Entry was registered without a fingerprint — update it now
+    entry.fileFingerprint = current.fingerprint;
+    return { kind: "available", entry };
+  }
+
+  if (current.fingerprint !== entry.fileFingerprint) {
+    // Stale — remove and report unavailable
+    store.delete(targetId);
+    return {
+      kind: "unavailable",
+      reason: `Target \`${targetId}\` (\`${entry.name ?? entry.file}\`) is stale — the backing file has been modified since resolution. Re-resolve with \`code_resolve\`.`,
+    };
+  }
+
+  return { kind: "available", entry };
+}