@flyingrobots/graft 0.7.0 → 0.8.0

package/src/operations/structured-buffer.ts

@@ -1,181 +0,0 @@
-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/operations/teaching-hints.ts

@@ -1,52 +0,0 @@
-// ---------------------------------------------------------------------------
-// Teaching Hints — contextual guidance for suboptimal read decisions
-// ---------------------------------------------------------------------------
-
-/** Context about a projection decision for hint generation. */
-export interface ProjectionContext {
-  readonly projection: "content" | "outline" | "refused";
-  readonly reason: string;
-  readonly filePath: string;
-  readonly fileLines: number;
-  readonly fileBytes: number;
-  readonly readCount: number;
-  readonly changedSinceLastRead?: boolean;
-}
-
-const LARGE_FILE_THRESHOLD = 150;
-const BUILD_OUTPUT_DIRS = ["dist/", "build/", "out/", ".next/", "coverage/"];
-
-/**
- * Generate a teaching hint for a projection decision.
- *
- * Returns undefined when the decision was already optimal (no noise).
- * Pure function — no I/O, no latency impact.
- */
-export function generateTeachingHint(ctx: ProjectionContext): string | undefined {
-  // Refused — suggest the source location
-  if (ctx.projection === "refused") {
-    if (BUILD_OUTPUT_DIRS.some((dir) => ctx.filePath.startsWith(dir))) {
-      return `This build output was refused. Source lives in src/, not ${ctx.filePath.split("/")[0] ?? "dist"}/. Read the source instead.`;
-    }
-    return `This file was refused (${ctx.reason}). Check if the content you need lives elsewhere.`;
-  }
-
-  // Outline-projected — suggest file_outline + read_range
-  if (ctx.projection === "outline") {
-    return `This file was outline-projected (${ctx.reason}). Try file_outline first to see the jump table, then read_range for the specific symbol you need.`;
-  }
-
-
-  // Re-read of unchanged file
-  if (ctx.readCount > 1 && ctx.changedSinceLastRead === false) {
-    return `You already read this file ${String(ctx.readCount)} times and it hasn't changed. Use changed_since to check before re-reading.`;
-  }
-
-  // Large file that could benefit from outline-first
-  if (ctx.fileLines > LARGE_FILE_THRESHOLD) {
-    return `This file is ${String(ctx.fileLines)} lines. Consider file_outline first for orientation, then read_range for the specific section you need.`;
-  }
-
-  // Optimal decision — no hint needed
-  return undefined;
-}

package/src/parser/diff.ts

@@ -1,320 +0,0 @@
-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;
-  readonly name: string;
-  readonly kind: OutlineEntry["kind"];
-  readonly exported?: boolean;
-  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;
-    kind: OutlineEntry["kind"];
-    exported?: boolean;
-    signature?: string;
-    oldSignature?: string;
-    childDiff?: OutlineDiff;
-    identityId?: string;
-  }) {
-    if (opts.name.trim().length === 0) {
-      throw new Error("DiffEntry: name must be non-empty");
-    }
-    this.name = opts.name.trim();
-    this.kind = opts.kind;
-    if (opts.exported !== undefined) this.exported = opts.exported;
-    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);
-  }
-}
-
-export class OutlineDiff {
-  /** @internal */
-  private readonly _brand = "OutlineDiff" as const;
-  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) {
-      throw new Error("OutlineDiff: unchangedCount must be a non-negative integer");
-    }
-    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);
-  }
-}
-
-/**
- * Returns the effective signature for comparison and reporting.
- * Falls back to the entry's name when no explicit signature exists
- * (e.g., for classes, interfaces, and plain exports).
- */
-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[],
-): OutlineDiff {
-  // Note: duplicate names are clobbered by Map.set — only the last
-  // entry with a given name survives. This is acceptable because
-  // tree-sitter outlines rarely produce duplicate top-level names,
-  // and symbol identity tracking (WARP Level 2+) will handle that case.
-  const oldByName = new Map<string, OutlineEntry>();
-  for (const entry of oldEntries) {
-    oldByName.set(entry.name, entry);
-  }
-
-  const newByName = new Map<string, OutlineEntry>();
-  for (const entry of newEntries) {
-    newByName.set(entry.name, entry);
-  }
-
-  const added: DiffEntry[] = [];
-  const removed: DiffEntry[] = [];
-  const changed: DiffEntry[] = [];
-  const addedEntries: OutlineEntry[] = [];
-  const removedEntries: OutlineEntry[] = [];
-  let unchangedCount = 0;
-
-  // Check new entries against old
-  for (const [name, newEntry] of newByName) {
-    const oldEntry = oldByName.get(name);
-    if (oldEntry === undefined) {
-      added.push(new DiffEntry({
-        name,
-        kind: newEntry.kind,
-        exported: newEntry.exported,
-        ...(newEntry.signature !== undefined ? { signature: newEntry.signature } : {}),
-      }));
-      addedEntries.push(newEntry);
-    } else {
-      const oldSig = entrySignature(oldEntry);
-      const newSig = entrySignature(newEntry);
-      if (oldSig !== newSig) {
-        changed.push(new DiffEntry({
-          name,
-          kind: newEntry.kind,
-          exported: newEntry.exported,
-          oldSignature: entrySignature(oldEntry),
-          ...(newEntry.signature !== undefined ? { signature: newEntry.signature } : {}),
-        }));
-      } else {
-        // Same name and signature — check children recursively
-        const oldChildren = oldEntry.children ?? [];
-        const newChildren = newEntry.children ?? [];
-        if (oldChildren.length > 0 || newChildren.length > 0) {
-          const childDiff = diffOutlines(oldChildren, newChildren);
-          if (childDiff.added.length > 0 || childDiff.removed.length > 0 || childDiff.changed.length > 0) {
-            changed.push(new DiffEntry({
-              exported: newEntry.exported,
-              name,
-              kind: newEntry.kind,
-              childDiff,
-              ...(newEntry.signature !== undefined ? { signature: newEntry.signature } : {}),
-            }));
-          } else {
-            unchangedCount++;
-          }
-        } else {
-          unchangedCount++;
-        }
-      }
-    }
-  }
-
-  // Check for removed (in old but not in new)
-  for (const [name, oldEntry] of oldByName) {
-    if (!newByName.has(name)) {
-      removed.push(new DiffEntry({
-        name,
-        kind: oldEntry.kind,
-        exported: oldEntry.exported,
-        ...(oldEntry.signature !== undefined ? { signature: oldEntry.signature } : {}),
-      }));
-      removedEntries.push(oldEntry);
-    }
-  }
-
-  return new OutlineDiff({
-    added,
-    removed,
-    changed,
-    continuity: detectContinuity(removedEntries, addedEntries),
-    unchangedCount,
-  });
-}

package/src/parser/lang.ts

@@ -1,71 +0,0 @@
-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 suffix.
- * Returns null for unsupported file types.
- */
-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);
-}