@flyingrobots/graft 0.4.0 → 0.6.0

package/src/operations/structured-buffer.ts

@@ -0,0 +1,181 @@
+import type {
+  AnchorAffinityResult,
+  BufferOutlineResult,
+  BufferPoint,
+  BufferRange,
+  BufferSelection,
+  DiagnosticsResult,
+  FoldRegionsResult,
+  InjectionResult,
+  NodeLookupResult,
+  RenamePreviewResult,
+  SelectionStepResult,
+  SemanticSummaryResult,
+  StructuredBufferSnapshot,
+  StructuredBufferDiffResult,
+  SymbolOccurrencesResult,
+  SyntaxSpanResult,
+  WarmProjectionBundleResult,
+  WarmProjectionBasis,
+} from "./structured-buffer-model.js";
+import { createStructuredBufferSnapshot } from "./structured-buffer-model.js";
+import {
+  buildDiagnosticsResult,
+  buildFoldRegionsResult,
+  buildInjectionResult,
+  buildNodeLookupResult,
+  buildOutlineResult,
+  buildRenamePreviewResult,
+  buildSelectionExpandResult,
+  buildSelectionShrinkResult,
+  buildSymbolOccurrencesResult,
+  buildSyntaxSpansResult,
+  buildWarmProjectionBundleResult,
+} from "./structured-buffer-query.js";
+import {
+  buildAnchorAffinityResult,
+  buildDiffResult,
+  buildSemanticSummaryResult,
+} from "./structured-buffer-compare.js";
+
+export type {
+  AnchorAffinityResult,
+  BufferDiagnostic,
+  BufferOutlineResult,
+  BufferPoint,
+  BufferRange,
+  BufferSelection,
+  ChangedRegion,
+  DiagnosticsResult,
+  FoldRegion,
+  FoldRegionsResult,
+  InjectionRegion,
+  InjectionResult,
+  NodeLookupResult,
+  NodeSummary,
+  RenameEditPreview,
+  RenamePreviewResult,
+  SelectionStepResult,
+  SemanticSummaryKind,
+  SemanticSummaryResult,
+  StructuredBufferDiffResult,
+  SymbolOccurrence,
+  SymbolOccurrencesResult,
+  SyntaxClass,
+  SyntaxSpan,
+  SyntaxSpanResult,
+  WarmProjectionBundleResult,
+  WarmProjectionParseStatus,
+  WarmProjectionBasis,
+} from "./structured-buffer-model.js";
+
+export class StructuredBuffer {
+  readonly path: string;
+  readonly content: string;
+  readonly format: StructuredBufferSnapshot["format"];
+  readonly basis: WarmProjectionBasis | null;
+  readonly partial: boolean;
+  #disposed = false;
+  #snapshot: StructuredBufferSnapshot;
+
+  constructor(opts: { path: string; content: string; basis?: WarmProjectionBasis | undefined }) {
+    this.#snapshot = createStructuredBufferSnapshot(opts);
+    this.path = this.#snapshot.path;
+    this.content = this.#snapshot.content;
+    this.format = this.#snapshot.format;
+    this.basis = this.#snapshot.basis;
+    this.partial = this.#snapshot.partial;
+  }
+
+  dispose(): void {
+    if (this.#disposed) {
+      return;
+    }
+    this.#snapshot.parsed?.delete();
+    this.#disposed = true;
+  }
+
+  basisIdentity(): WarmProjectionBasis | null {
+    this.#assertLive();
+    return this.basis;
+  }
+
+  outline(): BufferOutlineResult {
+    this.#assertLive();
+    return buildOutlineResult(this.#snapshot);
+  }
+
+  syntaxSpans(opts: { viewport?: BufferRange | undefined } = {}): SyntaxSpanResult {
+    this.#assertLive();
+    return buildSyntaxSpansResult(this.#snapshot, opts);
+  }
+
+  diagnostics(): DiagnosticsResult {
+    this.#assertLive();
+    return buildDiagnosticsResult(this.#snapshot);
+  }
+
+  nodeAt(position: BufferPoint): NodeLookupResult {
+    this.#assertLive();
+    return buildNodeLookupResult(this.#snapshot, position);
+  }
+
+  injections(): InjectionResult {
+    this.#assertLive();
+    return buildInjectionResult(this.#snapshot);
+  }
+
+  foldRegions(): FoldRegionsResult {
+    this.#assertLive();
+    return buildFoldRegionsResult(this.#snapshot);
+  }
+
+  projectionBundle(opts: { viewport?: BufferRange | undefined } = {}): WarmProjectionBundleResult {
+    this.#assertLive();
+    return buildWarmProjectionBundleResult(this.#snapshot, opts);
+  }
+
+  selectionExpand(selection: BufferSelection): SelectionStepResult {
+    this.#assertLive();
+    return buildSelectionExpandResult(this.#snapshot, selection);
+  }
+
+  selectionShrink(selection: BufferRange): SelectionStepResult {
+    this.#assertLive();
+    return buildSelectionShrinkResult(this.#snapshot, selection);
+  }
+
+  symbolOccurrences(opts: { position?: BufferPoint | undefined; symbol?: string | undefined } = {}): SymbolOccurrencesResult {
+    this.#assertLive();
+    return buildSymbolOccurrencesResult(this.#snapshot, opts);
+  }
+
+  renamePreview(opts: { nextName: string; position?: BufferPoint | undefined; symbol?: string | undefined }): RenamePreviewResult {
+    this.#assertLive();
+    return buildRenamePreviewResult(this.#snapshot, opts);
+  }
+
+  diff(next: StructuredBuffer): StructuredBufferDiffResult {
+    this.#assertLive();
+    next.#assertLive();
+    return buildDiffResult(this.#snapshot, next.#snapshot);
+  }
+
+  semanticSummary(next: StructuredBuffer): SemanticSummaryResult {
+    this.#assertLive();
+    next.#assertLive();
+    return buildSemanticSummaryResult(this.#snapshot, next.#snapshot);
+  }
+
+  mapRangeTo(next: StructuredBuffer, selection: BufferRange): AnchorAffinityResult {
+    this.#assertLive();
+    next.#assertLive();
+    return buildAnchorAffinityResult(this.#snapshot, next.#snapshot, selection);
+  }
+
+  #assertLive(): void {
+    if (this.#disposed) {
+      throw new Error("StructuredBuffer has been disposed");
+    }
+  }
+}

package/src/parser/diff.ts

@@ -1,5 +1,48 @@
 import { OutlineEntry } from "./types.js";
 
+export type DiffContinuityKind = "rename";
+export type DiffContinuityConfidence = "likely";
+export type DiffContinuityBasis =
+  | "matching_signature_shape"
+  | "matching_child_structure";
+
+export class DiffContinuity {
+  /** @internal */
+  private readonly _brand = "DiffContinuity" as const;
+  readonly kind: DiffContinuityKind;
+  readonly confidence: DiffContinuityConfidence;
+  readonly basis: DiffContinuityBasis;
+  readonly symbolKind: OutlineEntry["kind"];
+  readonly oldName: string;
+  readonly newName: string;
+  readonly oldSignature?: string;
+  readonly newSignature?: string;
+
+  constructor(opts: {
+    kind: DiffContinuityKind;
+    confidence: DiffContinuityConfidence;
+    basis: DiffContinuityBasis;
+    symbolKind: OutlineEntry["kind"];
+    oldName: string;
+    newName: string;
+    oldSignature?: string;
+    newSignature?: string;
+  }) {
+    if (opts.oldName.trim().length === 0 || opts.newName.trim().length === 0) {
+      throw new Error("DiffContinuity: names must be non-empty");
+    }
+    this.kind = opts.kind;
+    this.confidence = opts.confidence;
+    this.basis = opts.basis;
+    this.symbolKind = opts.symbolKind;
+    this.oldName = opts.oldName.trim();
+    this.newName = opts.newName.trim();
+    if (opts.oldSignature !== undefined) this.oldSignature = opts.oldSignature;
+    if (opts.newSignature !== undefined) this.newSignature = opts.newSignature;
+    Object.freeze(this);
+  }
+}
+
 export class DiffEntry {
   /** @internal */
   private readonly _brand = "DiffEntry" as const;
@@ -8,6 +51,8 @@ export class DiffEntry {
   readonly signature?: string;
   readonly oldSignature?: string;
   readonly childDiff?: OutlineDiff;
+  /** Canonical WARP symbol identity — present only when indexed truth is available. */
+  readonly identityId?: string;
 
   constructor(opts: {
     name: string;
@@ -15,6 +60,7 @@ export class DiffEntry {
     signature?: string;
     oldSignature?: string;
     childDiff?: OutlineDiff;
+    identityId?: string;
   }) {
     if (opts.name.trim().length === 0) {
       throw new Error("DiffEntry: name must be non-empty");
@@ -24,6 +70,7 @@ export class DiffEntry {
     if (opts.signature !== undefined) this.signature = opts.signature;
     if (opts.oldSignature !== undefined) this.oldSignature = opts.oldSignature;
     if (opts.childDiff !== undefined) this.childDiff = opts.childDiff;
+    if (opts.identityId !== undefined) this.identityId = opts.identityId;
     Object.freeze(this);
   }
 }
@@ -34,12 +81,14 @@ export class OutlineDiff {
   readonly added: readonly DiffEntry[];
   readonly removed: readonly DiffEntry[];
   readonly changed: readonly DiffEntry[];
+  readonly continuity: readonly DiffContinuity[];
   readonly unchangedCount: number;
 
   constructor(opts: {
     added: DiffEntry[];
     removed: DiffEntry[];
     changed: DiffEntry[];
+    continuity?: DiffContinuity[];
     unchangedCount: number;
   }) {
     if (!Number.isInteger(opts.unchangedCount) || opts.unchangedCount < 0) {
@@ -48,6 +97,7 @@ export class OutlineDiff {
     this.added = Object.freeze([...opts.added]);
     this.removed = Object.freeze([...opts.removed]);
     this.changed = Object.freeze([...opts.changed]);
+    this.continuity = Object.freeze([...(opts.continuity ?? [])]);
     this.unchangedCount = opts.unchangedCount;
     Object.freeze(this);
   }
@@ -62,6 +112,117 @@ function entrySignature(entry: OutlineEntry): string {
   return entry.signature ?? entry.name;
 }
 
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function normalizedSignatureShape(entry: OutlineEntry): string | null {
+  if (entry.signature === undefined) {
+    return null;
+  }
+  return entry.signature
+    .replace(new RegExp(`\\b${escapeRegExp(entry.name)}\\b`, "g"), "<name>")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function childStructureFingerprint(children: readonly OutlineEntry[] | undefined): string | null {
+  if (children === undefined || children.length === 0) {
+    return null;
+  }
+  return children.map((child) => {
+    const signatureShape = normalizedSignatureShape(child) ?? child.name;
+    const childFingerprint = childStructureFingerprint(child.children);
+    return `${child.kind}:${String(child.exported)}:${signatureShape}:${childFingerprint ?? ""}`;
+  }).join("|");
+}
+
+function continuityFingerprint(entry: OutlineEntry): {
+  basis: DiffContinuityBasis;
+  key: string;
+} | null {
+  const signatureShape = normalizedSignatureShape(entry);
+  if (signatureShape !== null) {
+    return {
+      basis: "matching_signature_shape",
+      key: `${entry.kind}:${String(entry.exported)}:${signatureShape}`,
+    };
+  }
+
+  const childFingerprint = childStructureFingerprint(entry.children);
+  if (childFingerprint !== null) {
+    return {
+      basis: "matching_child_structure",
+      key: `${entry.kind}:${String(entry.exported)}:${childFingerprint}`,
+    };
+  }
+
+  return null;
+}
+
+function detectContinuity(
+  removedEntries: readonly OutlineEntry[],
+  addedEntries: readonly OutlineEntry[],
+): DiffContinuity[] {
+  const groups = new Map<string, {
+    basis: DiffContinuityBasis;
+    removed: OutlineEntry[];
+    added: OutlineEntry[];
+  }>();
+
+  for (const entry of removedEntries) {
+    const fingerprint = continuityFingerprint(entry);
+    if (fingerprint === null) continue;
+    const group = groups.get(fingerprint.key) ?? {
+      basis: fingerprint.basis,
+      removed: [],
+      added: [],
+    };
+    group.removed.push(entry);
+    groups.set(fingerprint.key, group);
+  }
+
+  for (const entry of addedEntries) {
+    const fingerprint = continuityFingerprint(entry);
+    if (fingerprint === null) continue;
+    const group = groups.get(fingerprint.key) ?? {
+      basis: fingerprint.basis,
+      removed: [],
+      added: [],
+    };
+    group.added.push(entry);
+    groups.set(fingerprint.key, group);
+  }
+
+  const continuity: DiffContinuity[] = [];
+  for (const group of groups.values()) {
+    if (group.removed.length !== 1 || group.added.length !== 1) {
+      continue;
+    }
+
+    const removed = group.removed[0];
+    const added = group.added[0];
+    if (removed === undefined || added === undefined) {
+      continue;
+    }
+
+    continuity.push(new DiffContinuity({
+      kind: "rename",
+      confidence: "likely",
+      basis: group.basis,
+      symbolKind: added.kind,
+      oldName: removed.name,
+      newName: added.name,
+      ...(removed.signature !== undefined ? { oldSignature: removed.signature } : {}),
+      ...(added.signature !== undefined ? { newSignature: added.signature } : {}),
+    }));
+  }
+
+  return continuity.sort((left, right) => {
+    return `${left.oldName}:${left.newName}`.localeCompare(`${right.oldName}:${right.newName}`);
+  });
+}
+
 export function diffOutlines(
   oldEntries: readonly OutlineEntry[],
   newEntries: readonly OutlineEntry[],
@@ -83,6 +244,8 @@ export function diffOutlines(
   const added: DiffEntry[] = [];
   const removed: DiffEntry[] = [];
   const changed: DiffEntry[] = [];
+  const addedEntries: OutlineEntry[] = [];
+  const removedEntries: OutlineEntry[] = [];
   let unchangedCount = 0;
 
   // Check new entries against old
@@ -94,6 +257,7 @@ export function diffOutlines(
         kind: newEntry.kind,
         ...(newEntry.signature !== undefined ? { signature: newEntry.signature } : {}),
       }));
+      addedEntries.push(newEntry);
     } else {
       const oldSig = entrySignature(oldEntry);
       const newSig = entrySignature(newEntry);
@@ -135,8 +299,15 @@ export function diffOutlines(
         kind: oldEntry.kind,
         ...(oldEntry.signature !== undefined ? { signature: oldEntry.signature } : {}),
       }));
+      removedEntries.push(oldEntry);
     }
   }
 
-  return new OutlineDiff({ added, removed, changed, unchangedCount });
+  return new OutlineDiff({
+    added,
+    removed,
+    changed,
+    continuity: detectContinuity(removedEntries, addedEntries),
+    unchangedCount,
+  });
 }

package/src/parser/lang.ts

@@ -1,12 +1,71 @@
-import * as path from "node:path";
+export const SUPPORTED_LANGS = ["ts", "tsx", "js"] as const;
+export type SupportedLang = typeof SUPPORTED_LANGS[number];
+
+export const SUPPORTED_STRUCTURED_FORMATS = [
+  ...SUPPORTED_LANGS,
+  "md",
+] as const;
+export type SupportedStructuredFormat = typeof SUPPORTED_STRUCTURED_FORMATS[number];
+
+const LANGUAGE_SUFFIXES: Readonly<Record<SupportedLang, readonly string[]>> = {
+  ts: [".ts", ".mts", ".cts"],
+  tsx: [".tsx", ".jsx"],
+  js: [".js", ".mjs", ".cjs"],
+};
+
+const STRUCTURED_FORMAT_SUFFIXES: Readonly<Record<SupportedStructuredFormat, readonly string[]>> = {
+  ...LANGUAGE_SUFFIXES,
+  md: [".md"],
+};
+
+function normalizedSuffix(filePath: string): string {
+  const normalized = filePath.trim().toLowerCase();
+  const lastSeparator = Math.max(
+    normalized.lastIndexOf("/"),
+    normalized.lastIndexOf("\\"),
+  );
+  const basename = lastSeparator >= 0 ? normalized.slice(lastSeparator + 1) : normalized;
+  const lastDot = basename.lastIndexOf(".");
+  return lastDot >= 0 ? basename.slice(lastDot) : "";
+}
+
+function detectBySuffix<TFormat extends string>(
+  filePath: string,
+  suffixes: Readonly<Record<TFormat, readonly string[]>>,
+): TFormat | null {
+  const suffix = normalizedSuffix(filePath);
+  for (const [format, supportedSuffixes] of Object.entries(suffixes) as [TFormat, readonly string[]][]) {
+    if (supportedSuffixes.includes(suffix)) {
+      return format;
+    }
+  }
+  return null;
+}
+
+export function isSupportedLang(value: string): value is SupportedLang {
+  return (SUPPORTED_LANGS as readonly string[]).includes(value);
+}
+
+export function isSupportedStructuredFormat(
+  value: string,
+): value is SupportedStructuredFormat {
+  return (SUPPORTED_STRUCTURED_FORMATS as readonly string[]).includes(value);
+}
 
 /**
- * Detect the tree-sitter language from a file extension.
+ * Detect the tree-sitter language from a file suffix.
  * Returns null for unsupported file types.
  */
-export function detectLang(filePath: string): "ts" | "js" | null {
-  const ext = path.extname(filePath).toLowerCase();
-  if (ext === ".ts" || ext === ".tsx") return "ts";
-  if (ext === ".js" || ext === ".jsx") return "js";
-  return null;
+export function detectLang(filePath: string): SupportedLang | null {
+  return detectBySuffix(filePath, LANGUAGE_SUFFIXES);
+}
+
+/**
+ * Detect the supported structured format for bounded read surfaces.
+ * Returns null for file types that still have no explicit extractor.
+ */
+export function detectStructuredFormat(
+  filePath: string,
+): SupportedStructuredFormat | null {
+  return detectBySuffix(filePath, STRUCTURED_FORMAT_SUFFIXES);
 }

package/src/parser/markdown.ts

@@ -0,0 +1,197 @@
+// ---------------------------------------------------------------------------
+// Markdown outline extraction — heading-based structural summary
+// ---------------------------------------------------------------------------
+
+import { OutlineEntry, JumpEntry } from "./types.js";
+import type { OutlineResult } from "./types.js";
+
+interface MarkdownHeading {
+  level: number;
+  name: string;
+  start: number;
+  end: number;
+}
+
+interface MarkdownHeadingNode extends MarkdownHeading {
+  children: MarkdownHeadingNode[];
+}
+
+// ---------------------------------------------------------------------------
+// Fence detection
+// ---------------------------------------------------------------------------
+
+function isFenceLine(line: string): { marker: "`" | "~"; length: number } | null {
+  const match = /^\s*([`~])\1{2,}.*$/.exec(line);
+  if (match === null) return null;
+
+  const marker = match[1];
+  if (marker !== "`" && marker !== "~") return null;
+  const markerRun = /^([`~]+)/.exec(match[0].trimStart());
+  if (markerRun === null) return null;
+  const run = markerRun[1];
+  if (run === undefined) return null;
+  return { marker, length: run.length };
+}
+
+function isFenceClose(line: string, marker: "`" | "~", length: number): boolean {
+  const pattern = marker === "`"
+    ? new RegExp(`^\\s*\`{${String(length)},}\\s*$`)
+    : new RegExp(`^\\s*~{${String(length)},}\\s*$`);
+  return pattern.test(line);
+}
+
+// ---------------------------------------------------------------------------
+// Heading parsing
+// ---------------------------------------------------------------------------
+
+function parseAtxHeading(line: string, lineNumber: number): MarkdownHeading | null {
+  const match = /^\s{0,3}(#{1,6})[ \t]+(.+?)\s*#*\s*$/.exec(line);
+  if (match === null) return null;
+
+  const hashes = match[1];
+  const rawName = match[2]?.trim() ?? "";
+  if (hashes === undefined || rawName.length === 0) return null;
+
+  return {
+    level: hashes.length,
+    name: rawName,
+    start: lineNumber,
+    end: lineNumber,
+  };
+}
+
+function parseSetextHeading(
+  currentLine: string,
+  nextLine: string | undefined,
+  lineNumber: number,
+): MarkdownHeading | null {
+  if (nextLine === undefined) return null;
+  if (currentLine.trim().length === 0) return null;
+  if (parseAtxHeading(currentLine, lineNumber) !== null) return null;
+
+  if (/^\s{0,3}=+\s*$/.test(nextLine)) {
+    return { level: 1, name: currentLine.trim(), start: lineNumber, end: lineNumber + 1 };
+  }
+  if (/^\s{0,3}-+\s*$/.test(nextLine)) {
+    return { level: 2, name: currentLine.trim(), start: lineNumber, end: lineNumber + 1 };
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Hierarchy and range finalization
+// ---------------------------------------------------------------------------
+
+function finalizeMarkdownRanges(headings: MarkdownHeading[], totalLines: number): void {
+  for (let i = 0; i < headings.length; i++) {
+    const current = headings[i];
+    if (current === undefined) continue;
+    let end = totalLines;
+    for (let j = i + 1; j < headings.length; j++) {
+      const next = headings[j];
+      if (next === undefined) continue;
+      if (next.level <= current.level) {
+        end = next.start - 1;
+        break;
+      }
+    }
+    current.end = end;
+  }
+}
+
+function buildMarkdownHierarchy(headings: readonly MarkdownHeading[]): MarkdownHeadingNode[] {
+  const roots: MarkdownHeadingNode[] = [];
+  const stack: MarkdownHeadingNode[] = [];
+
+  for (const heading of headings) {
+    const node: MarkdownHeadingNode = { ...heading, children: [] };
+    while (stack.length > 0) {
+      const last = stack[stack.length - 1];
+      if (last === undefined || last.level < node.level) break;
+      stack.pop();
+    }
+    const parent = stack[stack.length - 1];
+    if (parent === undefined) roots.push(node);
+    else parent.children.push(node);
+    stack.push(node);
+  }
+
+  return roots;
+}
+
+// ---------------------------------------------------------------------------
+// Conversion
+// ---------------------------------------------------------------------------
+
+function toOutlineEntry(node: MarkdownHeadingNode): OutlineEntry {
+  return new OutlineEntry({
+    kind: "heading",
+    name: node.name,
+    exported: false,
+    ...(node.children.length > 0
+      ? { children: node.children.map((child) => toOutlineEntry(child)) }
+      : {}),
+  });
+}
+
+function buildMarkdownJumpEntry(heading: MarkdownHeading): JumpEntry {
+  return new JumpEntry({
+    symbol: heading.name,
+    kind: "heading",
+    start: heading.start,
+    end: heading.end,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function extractMarkdownOutline(source: string): OutlineResult {
+  const lines = source.split("\n");
+  const headings: MarkdownHeading[] = [];
+  let inFence = false;
+  let activeFence: { marker: "`" | "~"; length: number } | null = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined) continue;
+    const lineNumber = i + 1;
+    const fence = isFenceLine(line);
+
+    if (inFence) {
+      if (activeFence !== null && isFenceClose(line, activeFence.marker, activeFence.length)) {
+        inFence = false;
+        activeFence = null;
+      }
+      continue;
+    }
+
+    if (fence !== null) {
+      inFence = true;
+      activeFence = fence;
+      continue;
+    }
+
+    const atx = parseAtxHeading(line, lineNumber);
+    if (atx !== null) {
+      headings.push(atx);
+      continue;
+    }
+
+    const setext = parseSetextHeading(line, lines[i + 1], lineNumber);
+    if (setext !== null) {
+      headings.push(setext);
+      i++;
+    }
+  }
+
+  finalizeMarkdownRanges(headings, lines.length);
+  const hierarchy = buildMarkdownHierarchy(headings);
+
+  return {
+    entries: hierarchy.map((node) => toOutlineEntry(node)),
+    jumpTable: headings.map((heading) => buildMarkdownJumpEntry(heading)),
+  };
+}