@mrclrchtr/supi-code-intelligence 3.2.0 → 4.0.0

package/src/session/orientation/context-facts.ts

@@ -0,0 +1,319 @@
+import { statSync } from "node:fs";
+import * as path from "node:path";
+import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
+import type {
+  ArchitectureModel,
+  DependencyEdge,
+  ManifestDependencySection,
+  ModuleInfo,
+} from "../../analysis/architecture/model.ts";
+import { findModuleForPath } from "../../analysis/architecture/model.ts";
+import type { EvidencePartialReason } from "../../analysis/evidence.ts";
+import type { CodeProvider } from "../../analysis/provider.ts";
+import type { OrientationProvenance, OrientationResultData } from "../orientation-types.ts";
+import {
+  appendDirectoryEntries,
+  appendList,
+  appendPrioritySignals,
+  appendStructuralFileFacts,
+  appendUnavailable,
+  type ContextOrientationBuilder,
+  createBuilder,
+  displayPath,
+  filesystemProvenance,
+  formatManifestValue,
+  resultData,
+} from "./context-sections.ts";
+
+interface ContextFactsInput {
+  readonly model: ArchitectureModel;
+  readonly cwd: string;
+  readonly focus?: string;
+  readonly maxResults: number;
+  readonly provider: CodeProvider | null;
+  readonly lspRuntime: WorkspaceLspRuntimeState;
+}
+
+/** Collect direct filesystem, parsed-manifest, and explicit-provider Orientation facts. */
+export async function collectContextOrientationFacts(
+  input: ContextFactsInput,
+): Promise<OrientationResultData> {
+  if (!input.focus) return collectWorkspaceFacts(input);
+
+  let stat: ReturnType<typeof statSync>;
+  try {
+    stat = statSync(input.focus);
+  } catch (error) {
+    const builder = createBuilder(input.maxResults, `Path: ${displayPath(input.cwd, input.focus)}`);
+    appendUnavailable(builder, {
+      key: "filesystem.path",
+      title: "Focused path",
+      reason: String(error),
+      provenance: [filesystemProvenance(input.cwd, input.focus)],
+    });
+    return resultData(builder, input.focus, []);
+  }
+
+  if (stat.isDirectory()) return collectDirectoryFacts(input);
+  if (stat.isFile()) return collectFileFacts(input, stat.size);
+
+  const builder = createBuilder(input.maxResults, `Path: ${displayPath(input.cwd, input.focus)}`);
+  appendUnavailable(builder, {
+    key: "filesystem.path",
+    title: "Focused path",
+    reason: "Orientation supports regular files and directories only.",
+    provenance: [filesystemProvenance(input.cwd, input.focus)],
+  });
+  return resultData(builder, input.focus, []);
+}
+
+function collectWorkspaceFacts(input: ContextFactsInput): OrientationResultData {
+  const { model } = input;
+  const builder = createBuilder(input.maxResults, "Workspace Orientation");
+  appendRootPackageFacts(builder, model);
+  appendTopologyFacts(builder, model);
+  appendDirectoryEntries(builder, model.root, input.cwd);
+  appendPrioritySignals(builder, {
+    scope: model.root,
+    isFile: false,
+    cwd: input.cwd,
+    lspRuntime: input.lspRuntime,
+  });
+  return resultData(builder, null, []);
+}
+
+function collectDirectoryFacts(input: ContextFactsInput): OrientationResultData {
+  const focus = input.focus as string;
+  const builder = createBuilder(input.maxResults, `Directory: ${displayPath(input.cwd, focus)}`);
+  appendDirectoryEntries(builder, focus, input.cwd);
+  appendTopologyWarning(builder, input.model);
+  appendPackageContext(builder, input.model, focus);
+  appendPrioritySignals(builder, {
+    scope: focus,
+    isFile: false,
+    cwd: input.cwd,
+    lspRuntime: input.lspRuntime,
+  });
+  return resultData(builder, focus, [
+    `Use code_find with an explicit query and scope ["${displayPath(input.cwd, focus)}"] for deeper structural evidence`,
+  ]);
+}
+
+async function collectFileFacts(
+  input: ContextFactsInput,
+  byteSize: number,
+): Promise<OrientationResultData> {
+  const focus = input.focus as string;
+  const builder = createBuilder(input.maxResults, `File: ${displayPath(input.cwd, focus)}`);
+  appendList(builder, {
+    key: "filesystem.file",
+    title: "Filesystem facts",
+    items: [`Size: ${byteSize} bytes`],
+    render: (item) => item,
+    confidence: "unavailable",
+    provenance: [filesystemProvenance(input.cwd, focus)],
+  });
+  appendTopologyWarning(builder, input.model);
+  appendPackageContext(builder, input.model, focus);
+  await appendStructuralFileFacts(builder, input.provider, focus);
+  appendPrioritySignals(builder, {
+    scope: focus,
+    isFile: true,
+    cwd: input.cwd,
+    lspRuntime: input.lspRuntime,
+  });
+  return resultData(builder, focus, [
+    `Use code_inspect with an anchored point in "${displayPath(input.cwd, focus)}" for exact point facts`,
+  ]);
+}
+
+function appendRootPackageFacts(
+  builder: ContextOrientationBuilder,
+  model: ArchitectureModel,
+): void {
+  const root = model.rootManifest;
+  if (!root.package) {
+    appendUnavailable(builder, {
+      key: "manifest.root",
+      title: "Root package manifest",
+      reason: root.reason ?? "Unavailable.",
+      provenance: [{ source: "manifest", detail: root.path }],
+    });
+    return;
+  }
+  appendPackageFacts(builder, root.package, "Root package manifest");
+}
+
+function appendTopologyFacts(builder: ContextOrientationBuilder, model: ArchitectureModel): void {
+  const { topology } = model;
+  if (topology.kind === "unavailable") {
+    appendUnavailable(builder, {
+      key: "topology",
+      title: "Package topology",
+      reason: topology.reason ?? "Unavailable.",
+      provenance: [topologyProvenance(topology.source)],
+    });
+    return;
+  }
+  if (topology.kind === "single-package") return;
+
+  const status = topology.status === "partial" ? "partial" : "complete";
+  const partialReason = topologyPartialReason(model);
+  appendList(builder, {
+    key: "topology.packages",
+    title: "Configuration-declared packages",
+    items: model.modules,
+    render: packageLabel,
+    confidence: "unavailable",
+    provenance: [topologyProvenance(topology.source)],
+    status,
+    reason: topology.reason,
+    unknownRemainder: topology.failedPackageManifestCount > 0,
+    partialReason,
+  });
+  appendRelationshipFacts(builder, {
+    edges: model.edges,
+    status,
+    reason: topology.reason,
+    partialReason,
+  });
+}
+
+function appendTopologyWarning(builder: ContextOrientationBuilder, model: ArchitectureModel): void {
+  if (model.topology.kind === "unavailable") {
+    appendTopologyFacts(builder, model);
+    return;
+  }
+  if (model.topology.status !== "partial") return;
+  appendList(builder, {
+    key: "topology",
+    title: "Package topology",
+    items: [],
+    render: () => "",
+    confidence: "unavailable",
+    provenance: [topologyProvenance(model.topology.source)],
+    status: "partial",
+    reason: model.topology.reason,
+    unknownRemainder: true,
+    partialReason: topologyPartialReason(model),
+  });
+}
+
+function appendPackageContext(
+  builder: ContextOrientationBuilder,
+  model: ArchitectureModel,
+  focus: string,
+): void {
+  const module = findModuleForPath(model, focus);
+  if (!module) return;
+
+  if (path.resolve(module.root) === path.resolve(focus)) {
+    appendPackageFacts(builder, module, "Package manifest");
+    appendRelationshipFacts(builder, {
+      edges: model.edges.filter((edge) => edge.from === module.name || edge.to === module.name),
+      status: model.topology.status,
+      reason: model.topology.reason,
+      partialReason: topologyPartialReason(model),
+    });
+    return;
+  }
+
+  appendList(builder, {
+    key: "package.containing",
+    title: "Containing package",
+    items: [module],
+    render: packageLabel,
+    confidence: "unavailable",
+    provenance: [{ source: "manifest", detail: module.manifestPath }],
+  });
+}
+
+function appendPackageFacts(
+  builder: ContextOrientationBuilder,
+  module: ModuleInfo,
+  title: string,
+): void {
+  const identity = [`Manifest: \`${module.manifestPath}\``];
+  if (module.name) identity.push(`name: \`${module.name}\``);
+  if (module.description) identity.push(`description: ${module.description}`);
+  appendList(builder, {
+    key: `${module.manifestPath}.identity`,
+    title,
+    items: identity,
+    render: (item) => item,
+    confidence: "unavailable",
+    provenance: [{ source: "manifest", detail: module.manifestPath }],
+  });
+
+  if (module.fields.length > 0) {
+    appendList(builder, {
+      key: `${module.manifestPath}.fields`,
+      title: "Manifest declarations",
+      items: module.fields,
+      render: (field) => `\`${field.field}\`: ${formatManifestValue(field.value)}`,
+      confidence: "unavailable",
+      provenance: [{ source: "manifest", detail: module.manifestPath }],
+    });
+  }
+  for (const section of module.dependencySections) {
+    appendDependencySection(builder, module, section);
+  }
+}
+
+function appendDependencySection(
+  builder: ContextOrientationBuilder,
+  module: ModuleInfo,
+  section: ManifestDependencySection,
+): void {
+  appendList(builder, {
+    key: `${module.manifestPath}.${section.field}`,
+    title: `Manifest ${section.field}`,
+    items: section.entries,
+    render: (dependency) => `\`${dependency.name}\`: ${formatManifestValue(dependency.specifier)}`,
+    confidence: "unavailable",
+    provenance: [{ source: "manifest", detail: `${module.manifestPath}#${section.field}` }],
+  });
+}
+
+function appendRelationshipFacts(
+  builder: ContextOrientationBuilder,
+  input: {
+    edges: readonly DependencyEdge[];
+    status: "complete" | "partial" | "unavailable";
+    reason: string | null;
+    partialReason: EvidencePartialReason | undefined;
+  },
+): void {
+  if (input.status === "unavailable") return;
+  appendList(builder, {
+    key: "topology.relationships",
+    title: "Manifest-declared package relationships",
+    items: input.edges,
+    render: (edge) =>
+      `\`${edge.from}\` → \`${edge.to}\` — \`${edge.manifestPath}#${edge.field}\`: ${formatManifestValue(edge.specifier)}`,
+    confidence: "unavailable",
+    provenance: [{ source: "manifest", detail: "package dependency fields" }],
+    status: input.status,
+    reason: input.reason,
+    unknownRemainder: input.status === "partial",
+    partialReason: input.partialReason,
+  });
+}
+
+function topologyPartialReason(model: ArchitectureModel): EvidencePartialReason | undefined {
+  if (model.topology.status !== "partial") return undefined;
+  return model.topology.failedPackageManifestCount > 0 ? "filesystem-error" : "configuration-error";
+}
+
+function topologyProvenance(
+  source: ArchitectureModel["topology"]["source"],
+): OrientationProvenance {
+  return source
+    ? { source: "configuration", detail: `${source.path}#${source.field}` }
+    : { source: "configuration", detail: "supported workspace metadata" };
+}
+
+function packageLabel(module: ModuleInfo): string {
+  const name = module.name ? `\`${module.name}\`` : "Unnamed package manifest";
+  return `${name} — \`${module.relativePath}\` (\`${module.manifestPath}\`)`;
+}

package/src/session/orientation/context-sections.ts

@@ -0,0 +1,352 @@
+import { readdirSync } from "node:fs";
+import * as path from "node:path";
+import type { CodeResult, ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
+import type { WorkspaceLspRuntimeState } from "@mrclrchtr/supi-lsp/api";
+import type { EvidenceListMetadata, EvidencePartialReason } from "../../analysis/evidence.ts";
+import { createEvidenceList } from "../../analysis/evidence.ts";
+import type { CodeProvider } from "../../analysis/provider.ts";
+import type {
+  OrientationBlock,
+  OrientationProvenance,
+  OrientationResultData,
+  OrientationSectionData,
+} from "../orientation-types.ts";
+
+/** Mutable collection state kept private to context-Oriented fact assembly. */
+export interface ContextOrientationBuilder {
+  readonly blocks: OrientationBlock[];
+  readonly sections: OrientationSectionData[];
+  readonly maxResults: number;
+}
+
+/** Inputs for one bounded Orientation evidence section. */
+export interface ListSectionInput<T> {
+  readonly key: string;
+  readonly title: string;
+  readonly items: readonly T[];
+  readonly render: (item: T) => string;
+  readonly confidence: ConfidenceMode;
+  readonly provenance: readonly OrientationProvenance[];
+  readonly status?: "complete" | "partial";
+  readonly reason?: string | null;
+  readonly unknownRemainder?: boolean;
+  readonly partialReason?: EvidencePartialReason;
+}
+
+/** Start a context-Oriented document with one factual focus heading. */
+export function createBuilder(maxResults: number, title: string): ContextOrientationBuilder {
+  return {
+    blocks: [{ kind: "heading", level: 1, text: title }, { kind: "blank" }],
+    sections: [],
+    maxResults,
+  };
+}
+
+/** Add one bounded evidence list and matching Markdown/structured metadata. */
+export function appendList<T>(
+  builder: ContextOrientationBuilder,
+  input: ListSectionInput<T>,
+): void {
+  const list = createEvidenceList({
+    key: input.key,
+    items: [...input.items],
+    maxResults: builder.maxResults,
+  });
+  const metadata: EvidenceListMetadata = input.unknownRemainder
+    ? {
+        ...list.metadata,
+        totalCount: null,
+        partialReason: input.partialReason ?? "filesystem-error",
+      }
+    : list.metadata;
+  const section: OrientationSectionData = {
+    key: input.key,
+    title: input.title,
+    status: input.status ?? "complete",
+    reason: input.reason ?? null,
+    confidence: input.confidence,
+    provenance: input.provenance,
+    evidenceLists: [{ ...metadata, key: input.key }],
+  };
+  builder.sections.push(section);
+  builder.blocks.push(
+    { kind: "heading", level: 2, text: input.title },
+    { kind: "paragraph", text: formatSectionNote(section) },
+  );
+  for (const item of list.items) {
+    builder.blocks.push({ kind: "list-item", text: input.render(item) });
+  }
+  builder.blocks.push({ kind: "blank" });
+}
+
+/** Add an unavailable section without manufacturing an absence claim. */
+export function appendUnavailable(
+  builder: ContextOrientationBuilder,
+  input: {
+    key: string;
+    title: string;
+    reason: string;
+    provenance: readonly OrientationProvenance[];
+  },
+): void {
+  const section: OrientationSectionData = {
+    key: input.key,
+    title: input.title,
+    status: "unavailable",
+    reason: input.reason,
+    confidence: "unavailable",
+    provenance: input.provenance,
+    evidenceLists: [],
+  };
+  builder.sections.push(section);
+  builder.blocks.push(
+    { kind: "heading", level: 2, text: input.title },
+    { kind: "paragraph", text: formatSectionNote(section) },
+    { kind: "blank" },
+  );
+}
+
+/** Collect direct regular-file and directory names from one filesystem level. */
+export function appendDirectoryEntries(
+  builder: ContextOrientationBuilder,
+  directory: string,
+  cwd: string,
+): void {
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(directory, { withFileTypes: true });
+  } catch (error) {
+    const provenance = [filesystemProvenance(cwd, directory)];
+    appendUnavailable(builder, {
+      key: "filesystem.files",
+      title: "Direct regular files",
+      reason: String(error),
+      provenance,
+    });
+    appendUnavailable(builder, {
+      key: "filesystem.directories",
+      title: "Direct directories",
+      reason: String(error),
+      provenance,
+    });
+    return;
+  }
+
+  const files = entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .sort();
+  const directories = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+  const provenance = [filesystemProvenance(cwd, directory)];
+  appendList(builder, {
+    key: "filesystem.files",
+    title: "Direct regular files",
+    items: files,
+    render: (file) => `\`${file}\``,
+    confidence: "unavailable",
+    provenance,
+  });
+  appendList(builder, {
+    key: "filesystem.directories",
+    title: "Direct directories",
+    items: directories,
+    render: (child) => `\`${child}/\``,
+    confidence: "unavailable",
+    provenance,
+  });
+}
+
+/** Collect explicit outline/import/export observations from the structural provider. */
+export async function appendStructuralFileFacts(
+  builder: ContextOrientationBuilder,
+  provider: CodeProvider | null,
+  file: string,
+): Promise<void> {
+  if (!provider) {
+    appendUnavailableStructuralSections(builder);
+    return;
+  }
+
+  await appendStructuralList(builder, {
+    key: "structural.outline",
+    title: "Provider outline",
+    collect: () => provider.outline(file),
+    render: (item) => `\`${item.name}\` (${item.kind}, L${item.startLine}–L${item.endLine})`,
+  });
+  await appendStructuralList(builder, {
+    key: "structural.imports",
+    title: "Provider imports",
+    collect: () => provider.imports(file),
+    render: (item) => `\`${item.moduleSpecifier}\``,
+  });
+  await appendStructuralList(builder, {
+    key: "structural.exports",
+    title: "Provider exports",
+    collect: () => provider.exports(file),
+    render: (item) => `\`${item.name}\` (${item.kind})`,
+  });
+}
+
+function appendUnavailableStructuralSections(builder: ContextOrientationBuilder): void {
+  for (const [key, title] of [
+    ["structural.outline", "Provider outline"],
+    ["structural.imports", "Provider imports"],
+    ["structural.exports", "Provider exports"],
+  ] as const) {
+    appendUnavailable(builder, {
+      key,
+      title,
+      reason: "Structural provider unavailable.",
+      provenance: [{ source: "structural", capability: "tree-sitter" }],
+    });
+  }
+}
+
+async function appendStructuralList<T>(
+  builder: ContextOrientationBuilder,
+  input: {
+    key: string;
+    title: string;
+    collect: () => Promise<CodeResult<T[]>>;
+    render: (item: T) => string;
+  },
+): Promise<void> {
+  let result: CodeResult<T[]>;
+  try {
+    result = await input.collect();
+  } catch (error) {
+    appendUnavailable(builder, {
+      key: input.key,
+      title: input.title,
+      reason: `Structural provider failed: ${String(error)}`,
+      provenance: [{ source: "structural", capability: "tree-sitter" }],
+    });
+    return;
+  }
+  if (result.kind !== "success") {
+    appendUnavailable(builder, {
+      key: input.key,
+      title: input.title,
+      reason: result.message,
+      provenance: [{ source: "structural", capability: "tree-sitter" }],
+    });
+    return;
+  }
+  appendList(builder, {
+    key: input.key,
+    title: input.title,
+    items: result.data,
+    render: input.render,
+    confidence: "structural",
+    provenance: [{ source: "structural", capability: "tree-sitter" }],
+  });
+}
+
+/** Add bounded current diagnostic snapshot facts without claiming whole-workspace coverage. */
+export function appendPrioritySignals(
+  builder: ContextOrientationBuilder,
+  input: {
+    scope: string;
+    isFile: boolean;
+    cwd: string;
+    lspRuntime: WorkspaceLspRuntimeState;
+  },
+): void {
+  if (input.lspRuntime.kind !== "ready") return;
+  const scopePath = path.resolve(input.scope);
+  const entries = input.lspRuntime.runtime.getOutstandingDiagnosticSummary(2).filter((entry) => {
+    const file = path.resolve(input.cwd, entry.file);
+    return input.isFile ? file === scopePath : isWithinOrEqual(scopePath, file);
+  });
+  if (entries.length === 0) return;
+
+  appendList(builder, {
+    key: "diagnostics.snapshot",
+    title: "Priority Signals",
+    items: entries,
+    render: (entry) => {
+      const parts = [`${entry.total} total`];
+      if (entry.errors > 0) parts.push(`${entry.errors} errors`);
+      if (entry.warnings > 0) parts.push(`${entry.warnings} warnings`);
+      return `Diagnostics: \`${displayPath(input.cwd, entry.file)}\` (${parts.join(", ")})`;
+    },
+    confidence: "semantic",
+    provenance: [{ source: "semantic", capability: "LSP diagnostic snapshot" }],
+    status: "partial",
+    reason:
+      "This is the current LSP snapshot, not a complete diagnostic scan; use code_health for diagnostic status.",
+  });
+}
+
+/** Finalize blocks and per-list omission totals into one Orientation result. */
+export function resultData(
+  builder: ContextOrientationBuilder,
+  focus: string | null,
+  nextQueries: string[],
+): OrientationResultData {
+  const omittedCount = builder.sections.reduce(
+    (total, section) =>
+      total + section.evidenceLists.reduce((sum, list) => sum + (list.omittedCount ?? 0), 0),
+    0,
+  );
+  return {
+    blocks: builder.blocks,
+    sections: builder.sections,
+    confidence: highestConfidence(builder.sections),
+    focusTarget: focus,
+    requestedSections: [],
+    renderedSections: builder.sections.map((section) => section.key),
+    omittedCount,
+    nextQueries,
+    readNext: [],
+  };
+}
+
+export function filesystemProvenance(cwd: string, target: string): OrientationProvenance {
+  return { source: "filesystem", detail: displayPath(cwd, target) };
+}
+
+export function displayPath(cwd: string, target: string): string {
+  const relative = path.relative(cwd, path.resolve(target)).replaceAll(path.sep, "/");
+  if (relative.length === 0) return ".";
+  return relative.startsWith("../") || relative === ".." ? target : relative;
+}
+
+export function formatManifestValue(value: unknown): string {
+  if (typeof value === "string") return `\`${value}\``;
+  const serialized = JSON.stringify(value);
+  return `\`${serialized ?? String(value)}\``;
+}
+
+/** Render the same section status/provenance metadata stored in result details. */
+export function formatSectionNote(section: OrientationSectionData): string {
+  const facts = section.evidenceLists.map(evidenceSummary).join("; ");
+  const provenance = section.provenance.map(formatProvenance).join(", ");
+  return `_(status: ${section.status}; provenance: ${provenance || "none"}${section.reason ? `; ${section.reason}` : ""}${facts ? `; ${facts}` : ""})_`;
+}
+
+function evidenceSummary(metadata: EvidenceListMetadata): string {
+  if (metadata.totalCount === null) {
+    const omitted = metadata.omittedCount ? `; ${metadata.omittedCount} collected omitted` : "";
+    return `showing ${metadata.shownCount}${omitted}; more may exist — ${metadata.partialReason ?? "partial"}`;
+  }
+  if ((metadata.omittedCount ?? 0) > 0) {
+    return `showing ${metadata.shownCount} of ${metadata.totalCount}; ${metadata.omittedCount} omitted`;
+  }
+  return `${metadata.totalCount} observed`;
+}
+
+function formatProvenance(provenance: OrientationProvenance): string {
+  const detail = provenance.detail ? ` \`${provenance.detail}\`` : "";
+  return `${provenance.source}${provenance.capability ? ` (${provenance.capability})` : ""}${detail}`;
+}
+
+function highestConfidence(sections: readonly OrientationSectionData[]): ConfidenceMode {
+  if (sections.some((section) => section.confidence === "semantic")) return "semantic";
+  if (sections.some((section) => section.confidence === "structural")) return "structural";
+  return "unavailable";
+}