@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/session/orientation-types.ts

@@ -0,0 +1,97 @@
+import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import type { EvidenceListMetadata } from "../analysis/evidence.ts";
+import type { InstructionFilesMetadata } from "../analysis/instruction-files.ts";
+import type { ReadNextItem } from "../analysis/read-next.ts";
+import type { OrientationTargetInput, TargetSymbolKind } from "./target-input.ts";
+import type { AnchorKind, TargetStoreEntry } from "./target-store.ts";
+
+/** Exact-one non-workspace Orientation focus. */
+export type OrientationFocusInput =
+  | { readonly path: string }
+  | { readonly module: string }
+  | { readonly target: OrientationTargetInput };
+
+export interface OrientationWorkflowInput {
+  readonly focus?: OrientationFocusInput;
+  readonly maxResults?: number;
+}
+
+/** Presentation-neutral block collected for an Orientation result. */
+export type OrientationBlock =
+  | { readonly kind: "heading"; readonly level: 1 | 2 | 3; readonly text: string }
+  | { readonly kind: "paragraph"; readonly text: string }
+  | { readonly kind: "list-item"; readonly text: string }
+  | {
+      readonly kind: "code";
+      readonly language: string | null;
+      readonly lines: readonly string[];
+    }
+  | { readonly kind: "blank" };
+
+/** Source that established one Orientation section. */
+export interface OrientationProvenance {
+  readonly source:
+    | "semantic"
+    | "structural"
+    | "filesystem"
+    | "manifest"
+    | "configuration"
+    | "runtime";
+  readonly capability?: string;
+  readonly detail?: string;
+}
+
+/** Independently collected Orientation section and its evidence metadata. */
+export interface OrientationSectionData {
+  readonly key: string;
+  readonly title: string;
+  readonly status: "complete" | "partial" | "unavailable";
+  readonly reason: string | null;
+  /** Semantic/structural confidence only; filesystem/config facts use unavailable. */
+  readonly confidence: ConfidenceMode;
+  readonly provenance: readonly OrientationProvenance[];
+  readonly evidenceLists: readonly EvidenceListMetadata[];
+}
+
+export interface OrientationCandidate {
+  readonly targetId: string;
+  readonly name: string;
+  readonly kind: string | null;
+  readonly container: string | null;
+  readonly file: string;
+  readonly line: number;
+  readonly character: number;
+  readonly rank: number;
+  readonly anchorKind?: AnchorKind;
+}
+
+/** Immutable facts returned by the session before markdown or TUI rendering. */
+export interface OrientationResultData {
+  readonly blocks: readonly OrientationBlock[];
+  readonly sections: readonly OrientationSectionData[];
+  readonly confidence: ConfidenceMode;
+  readonly focusTarget: string | null;
+  readonly requestedSections: readonly string[];
+  readonly renderedSections: readonly string[];
+  readonly omittedCount: number;
+  readonly nextQueries: readonly string[];
+  readonly readNext: readonly ReadNextItem[];
+  readonly instructions?: InstructionFilesMetadata;
+  readonly target?: Readonly<TargetStoreEntry>;
+}
+
+export type OrientationWorkflowOutcome =
+  | { readonly kind: "completed"; readonly data: OrientationResultData }
+  | {
+      readonly kind: "disambiguation";
+      readonly candidates: readonly OrientationCandidate[];
+      readonly omittedCount: number;
+    }
+  | {
+      readonly kind: "kind-mismatch";
+      readonly requestedKind: TargetSymbolKind;
+      readonly candidates: readonly OrientationCandidate[];
+      readonly omittedCount: number;
+    }
+  | { readonly kind: "invalid-input"; readonly message: string }
+  | { readonly kind: "unavailable"; readonly reason: string };

package/src/session/orientation-workflow.ts

@@ -0,0 +1,307 @@
+/** Session-owned Orientation workflow. */
+
+import { existsSync, statSync } from "node:fs";
+import { relative } from "node:path";
+import { buildArchitectureModel } from "../analysis/architecture/discovery.ts";
+import type { ArchitectureModel } from "../analysis/architecture/model.ts";
+import {
+  collectInstructionFiles,
+  findInstructionFilesForDirectory,
+} from "../analysis/instruction-files.ts";
+import { createStructuralCodeProvider } from "../analysis/provider.ts";
+import { normalizePath } from "../analysis/search/paths.ts";
+import { loadCodeIntelligenceConfig } from "../config.ts";
+import type { CapabilityAdapter } from "./capability-adapter.ts";
+import { parseOrientationWorkflowInput } from "./input/workflows.ts";
+import { executeOrientation } from "./orientation/collect.ts";
+import { formatSectionNote } from "./orientation/context-sections.ts";
+import type {
+  OrientationBlock,
+  OrientationFocusInput,
+  OrientationResultData,
+  OrientationSectionData,
+  OrientationWorkflowInput,
+  OrientationWorkflowOutcome,
+} from "./orientation-types.ts";
+import type { TargetStoreEntry } from "./target-store.ts";
+import { resolveTargetWorkflow, type TargetWorkflowDeps } from "./target-workflow.ts";
+import { reportProgress, throwIfAborted, type WorkflowControl } from "./workflow-control.ts";
+
+export interface OrientationWorkflowDeps extends TargetWorkflowDeps {
+  readonly capability: CapabilityAdapter;
+  readonly nativeInstructionPaths: Set<string>;
+  readonly surfacedInstructionDirs: Set<string>;
+  readonly markInstructionDirsSurfaced: (directories: string[]) => void;
+  /** Whether the project is trusted — controls instruction-file discovery. */
+  readonly projectTrusted: boolean;
+}
+
+/** Resolve the Orientation focus and collect immutable facts for presentation adapters. */
+export async function runOrientationWorkflow(
+  input: OrientationWorkflowInput,
+  deps: OrientationWorkflowDeps,
+  control?: WorkflowControl,
+): Promise<OrientationWorkflowOutcome> {
+  const parsed = parseOrientationWorkflowInput(input);
+  if (parsed.kind === "invalid-input") return parsed;
+  const request = parsed.value;
+  throwIfAborted(control);
+  reportProgress(control, {
+    intent: "orientation",
+    phase: "model",
+    message: "Building workspace orientation model",
+  });
+  const model = await buildArchitectureModel(deps.cwd);
+  const provider = deps.capability.getProvider(deps.cwd);
+  const lspRuntime = deps.capability.getLspRuntimeState(deps.cwd);
+  const maxResults = request.maxResults ?? 10;
+
+  if (!request.focus) {
+    const result = await executeOrientation(
+      { maxResults },
+      { model, provider, lspRuntime, cwd: deps.cwd },
+    );
+    return { kind: "completed", data: result };
+  }
+
+  if ("target" in request.focus) {
+    return orientTarget({ targetInput: request.focus.target, maxResults, model, deps, control });
+  }
+
+  const focus = resolveContextFocus(request.focus, deps.cwd, model);
+  if (focus.kind === "invalid-input") return focus;
+  const result = await executeOrientation(
+    {
+      focus: focus.path,
+      maxResults,
+    },
+    { model, provider, lspRuntime, cwd: deps.cwd },
+  );
+  const withInstructions = addInstructionFiles(result, focus.path, deps);
+  return { kind: "completed", data: withInstructions };
+}
+
+async function orientTarget(options: {
+  targetInput: Extract<OrientationFocusInput, { target: unknown }>["target"];
+  maxResults: number;
+  model: ArchitectureModel;
+  deps: OrientationWorkflowDeps;
+  control?: WorkflowControl;
+}): Promise<OrientationWorkflowOutcome> {
+  const { targetInput, maxResults, model, deps, control } = options;
+  reportProgress(control, {
+    intent: "orientation",
+    phase: "target",
+    message: "Resolving precise Orientation target",
+  });
+  const target = await resolveTargetWorkflow(
+    targetInput,
+    {
+      fileLevelAllowed: false,
+      nameAnchorRequired: false,
+      maxResults,
+    },
+    deps,
+  );
+  if (target.kind === "target-group") {
+    return {
+      kind: "invalid-input",
+      message: "Precise Orientation requires one member handle from a Target group.",
+    };
+  }
+  if (target.kind === "disambiguation" || target.kind === "kind-mismatch") {
+    const candidates = target.candidates.map((candidate) => ({
+      targetId: candidate.targetId,
+      name: candidate.name,
+      kind: candidate.kind,
+      container: candidate.container,
+      file: candidate.file,
+      line: candidate.line,
+      character: candidate.character,
+      rank: candidate.rank,
+      anchorKind: candidate.anchorKind,
+    }));
+    return target.kind === "kind-mismatch"
+      ? {
+          kind: "kind-mismatch",
+          requestedKind: target.requestedKind,
+          omittedCount: target.omittedCount,
+          candidates,
+        }
+      : { kind: "disambiguation", omittedCount: target.omittedCount, candidates };
+  }
+  if (target.kind !== "resolved") return target;
+  throwIfAborted(control);
+
+  const entry = target.entry;
+  const readiness = await deps.capability.ensureSemanticReadiness(deps.cwd, {
+    kind: "file",
+    file: entry.file,
+  });
+  const semanticReady = readiness.kind === "ready";
+  const provider = semanticReady
+    ? deps.capability.getProvider(deps.cwd)
+    : createStructuralCodeProvider(deps.capability.getStructuralProvider(deps.cwd));
+  const lspRuntime = semanticReady
+    ? deps.capability.getLspRuntimeState(deps.cwd)
+    : {
+        kind: "unavailable" as const,
+        reason: readiness.kind === "timeout" ? "Semantic readiness timed out" : readiness.reason,
+      };
+  const result = await executeOrientation(
+    {
+      target: {
+        file: entry.file,
+        line: entry.displayLine,
+        character: entry.displayCharacter,
+        name: entry.name,
+        kind: entry.kind,
+        anchorKind: entry.anchorKind,
+      },
+      maxResults,
+    },
+    {
+      model,
+      provider,
+      lspRuntime,
+      cwd: deps.cwd,
+    },
+  );
+  return {
+    kind: "completed",
+    data: addTargetSummary(result, entry, target.notes, deps.cwd),
+  };
+}
+
+function resolveContextFocus(
+  focus: Exclude<OrientationFocusInput, { target: unknown }>,
+  cwd: string,
+  model: ArchitectureModel,
+): { kind: "resolved"; path: string } | { kind: "invalid-input"; message: string } {
+  if ("path" in focus) {
+    const path = normalizePath(focus.path, cwd);
+    return existsSync(path)
+      ? { kind: "resolved", path }
+      : { kind: "invalid-input", message: `Focus path not found: \`${focus.path}\`.` };
+  }
+
+  const matches = model.modules.filter(
+    (module) =>
+      module.name === focus.module || module.name?.replace(/^@[^/]+\//, "") === focus.module,
+  );
+  if (matches.length === 1) return { kind: "resolved", path: matches[0].root };
+  if (matches.length > 1) {
+    return {
+      kind: "invalid-input",
+      message: `Module focus is ambiguous: ${matches.map((module) => module.name).join(", ")}.`,
+    };
+  }
+  return { kind: "invalid-input", message: `Module focus not found: \`${focus.module}\`.` };
+}
+
+function addInstructionFiles(
+  result: Awaited<ReturnType<typeof executeOrientation>>,
+  focusPath: string,
+  deps: OrientationWorkflowDeps,
+): Awaited<ReturnType<typeof executeOrientation>> {
+  if (!deps.projectTrusted || !isDirectory(focusPath)) return result;
+  const config = loadCodeIntelligenceConfig(deps.cwd);
+  const matches = findInstructionFilesForDirectory({
+    directory: focusPath,
+    cwd: deps.cwd,
+    fileNames: config.instructionFileNames,
+    nativeContextPaths: deps.nativeInstructionPaths,
+    surfacedDirectories: deps.surfacedInstructionDirs,
+    projectTrusted: deps.projectTrusted,
+  });
+  const collected = collectInstructionFiles(matches);
+  if (!collected) return result;
+  deps.markInstructionDirsSurfaced(collected.metadata.files.map((file) => file.directory));
+  const section: OrientationSectionData = {
+    key: "instructions",
+    title: "Instructions",
+    status: "complete",
+    reason: null,
+    confidence: "unavailable",
+    provenance: [{ source: "filesystem", detail: "configured instruction files" }],
+    evidenceLists: [
+      {
+        key: "instructions.files",
+        totalCount: collected.files.length,
+        shownCount: collected.files.length,
+        omittedCount: 0,
+        partialReason: null,
+      },
+    ],
+  };
+  return {
+    ...result,
+    blocks: insertInstructionBlocks(result.blocks, collected.files, section),
+    sections: [section, ...result.sections],
+    renderedSections: ["instructions", ...result.renderedSections],
+    instructions: collected.metadata,
+  };
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function addTargetSummary(
+  result: OrientationResultData,
+  entry: Readonly<TargetStoreEntry>,
+  notes: readonly string[],
+  cwd: string,
+): OrientationResultData {
+  const name = entry.name ? ` ${entry.name}` : "";
+  const summary: OrientationBlock[] = [
+    ...notes.map((note): OrientationBlock => ({ kind: "paragraph", text: `Note: ${note}` })),
+    {
+      kind: "paragraph",
+      text: `Resolved target${name}: ${relative(cwd, entry.file) || entry.file}:${entry.displayLine}:${entry.displayCharacter} — Target ID: ${entry.targetId}`,
+    },
+    { kind: "blank" },
+  ];
+  return { ...result, blocks: [...summary, ...result.blocks], target: { ...entry } };
+}
+
+function insertInstructionBlocks(
+  existing: readonly OrientationBlock[],
+  files: readonly {
+    path: string;
+    content: string;
+    truncated: boolean;
+    shownLines: number;
+    totalLines: number;
+  }[],
+  section: OrientationSectionData,
+): OrientationBlock[] {
+  const blocks: OrientationBlock[] = [
+    { kind: "heading", level: 2, text: "Instructions" },
+    { kind: "paragraph", text: formatSectionNote(section) },
+    { kind: "blank" },
+  ];
+  for (const file of files) {
+    blocks.push(
+      { kind: "heading", level: 3, text: file.path },
+      { kind: "code", language: null, lines: file.content.split("\n") },
+    );
+    if (file.truncated) {
+      blocks.push({
+        kind: "paragraph",
+        text: `Instruction file truncated to ${file.shownLines} of ${file.totalLines} lines. Read ${file.path} for the full file.`,
+      });
+    }
+    blocks.push({ kind: "blank" });
+  }
+
+  const insertion = existing.findIndex(
+    (block, index) => index > 0 && block.kind === "heading" && block.level === 2,
+  );
+  if (insertion < 0) return [...existing, ...blocks];
+  return [...existing.slice(0, insertion), ...blocks, ...existing.slice(insertion)];
+}

package/src/session/refactor-plans.ts

@@ -12,7 +12,7 @@ import type { RefactorOperation, WorkspaceEdit } from "@mrclrchtr/supi-code-runt
 
 export interface RefactorPlan {
   id: string;
-  operation: Exclude<RefactorOperation, "rename">;
+  operation: RefactorOperation;
   newName?: string;
   destination?: string;
   targetFile: string;

package/src/session/refactor-types.ts

@@ -0,0 +1,51 @@
+import type { RefactorResult } from "@mrclrchtr/supi-code-runtime/api";
+import type { ApplyResult } from "../analysis/refactor/apply.ts";
+import type { RefactorPlan } from "./refactor-plans.ts";
+import type { RefactorTargetInput, SourcePointInput } from "./target-input.ts";
+
+export interface PublicSourceRange {
+  readonly start: Omit<SourcePointInput, "file">;
+  readonly end: Omit<SourcePointInput, "file">;
+}
+
+export type RefactorOperationInput =
+  | { readonly rename_symbol: { readonly newName: string } }
+  | {
+      readonly extract_function: {
+        readonly newName: string;
+        readonly range: PublicSourceRange;
+      };
+    }
+  | {
+      readonly extract_variable: {
+        readonly newName: string;
+        readonly range: PublicSourceRange;
+      };
+    };
+
+export interface RefactorPlanWorkflowInput {
+  readonly target: RefactorTargetInput;
+  readonly operation: RefactorOperationInput;
+}
+
+export type RefactorPlanWorkflowOutcome =
+  | { readonly kind: "completed"; readonly plan: Readonly<RefactorPlan> }
+  | {
+      readonly kind: "ambiguous";
+      readonly candidates: Readonly<Extract<RefactorResult, { kind: "ambiguous" }>["candidates"]>;
+    }
+  | { readonly kind: "invalid-input"; readonly message: string }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+export interface RefactorApplyWorkflowInput {
+  readonly planId: string;
+}
+
+export type RefactorApplyWorkflowOutcome =
+  | {
+      readonly kind: "completed";
+      readonly plan: Readonly<RefactorPlan>;
+      readonly result: Readonly<Extract<ApplyResult, { kind: "applied" }>>;
+    }
+  | { readonly kind: "invalid-input"; readonly message: string }
+  | { readonly kind: "unavailable"; readonly reason: string };