@flyingrobots/graft 0.6.1 → 0.7.1

package/src/metrics/logger.ts

@@ -1,40 +0,0 @@
-import { RotatingNdjsonLog } from "../adapters/rotating-ndjson-log.js";
-import type { FileSystem } from "../ports/filesystem.js";
-import type { JsonCodec } from "../ports/codec.js";
-import { DecisionEntry } from "./types.js";
-
-export interface MetricsLoggerOptions {
-  readonly fs: FileSystem;
-  readonly codec: JsonCodec;
-  readonly maxBytes?: number;
-}
-
-export class MetricsLogger {
-  private readonly writer: RotatingNdjsonLog;
-
-  constructor(logPath: string, options: MetricsLoggerOptions) {
-    const writerOptions = {
-      logPath,
-      fs: options.fs,
-      codec: options.codec,
-      ...(options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes }),
-    };
-    this.writer = new RotatingNdjsonLog(writerOptions);
-  }
-
-  async log(entry: Omit<DecisionEntry, "ts">): Promise<void> {
-    const full = new DecisionEntry({
-      ts: new Date().toISOString(),
-      command: entry.command,
-      path: entry.path,
-      projection: entry.projection,
-      reason: entry.reason,
-      lines: entry.lines,
-      bytes: entry.bytes,
-      estimatedBytesAvoided: entry.estimatedBytesAvoided,
-      sessionDepth: entry.sessionDepth,
-      tripwire: entry.tripwire,
-    });
-    await this.writer.append(full);
-  }
-}

package/src/metrics/types.ts

@@ -1,40 +0,0 @@
-// ---------------------------------------------------------------------------
-// DecisionEntry — runtime-backed metric event for policy decisions
-// ---------------------------------------------------------------------------
-
-export class DecisionEntry {
-  readonly ts: string;
-  readonly command: string;
-  readonly path: string;
-  readonly projection: string;
-  readonly reason: string;
-  readonly lines: number;
-  readonly bytes: number;
-  readonly estimatedBytesAvoided?: number | undefined;
-  readonly sessionDepth?: string | undefined;
-  readonly tripwire?: string | null | undefined;
-
-  constructor(fields: {
-    readonly ts: string;
-    readonly command: string;
-    readonly path: string;
-    readonly projection: string;
-    readonly reason: string;
-    readonly lines: number;
-    readonly bytes: number;
-    readonly estimatedBytesAvoided?: number | undefined;
-    readonly sessionDepth?: string | undefined;
-    readonly tripwire?: string | null | undefined;
-  }) {
-    this.ts = fields.ts;
-    this.command = fields.command;
-    this.path = fields.path;
-    this.projection = fields.projection;
-    this.reason = fields.reason;
-    this.lines = fields.lines;
-    this.bytes = fields.bytes;
-    this.estimatedBytesAvoided = fields.estimatedBytesAvoided;
-    this.sessionDepth = fields.sessionDepth;
-    this.tripwire = fields.tripwire;
-  }
-}

package/src/operations/cached-file.ts

@@ -1,40 +0,0 @@
-import { extractOutlineForFile } from "../parser/outline.js";
-import { detectStructuredFormat } from "../parser/lang.js";
-import type { SupportedStructuredFormat } from "../parser/lang.js";
-import type { OutlineEntry, JumpEntry } from "../parser/types.js";
-import { hashContent } from "./observation-cache.js";
-
-/**
- * Immutable snapshot of a file read. Built once from a single read,
- * shared by all consumers (cache, policy, outline extraction) to eliminate
- * TOCTOU races where the file changes between reads.
- */
-export class CachedFile {
-  /** @internal */
-  private readonly _brand = "CachedFile" as const;
-  readonly path: string;
-  readonly rawContent: string;
-  readonly hash: string;
-  readonly lang: SupportedStructuredFormat | null;
-  readonly supportsOutline: boolean;
-  readonly outline: readonly OutlineEntry[];
-  readonly jumpTable: readonly JumpEntry[];
-  readonly actual: { readonly lines: number; readonly bytes: number };
-
-  constructor(filePath: string, rawContent: string) {
-    this.path = filePath;
-    this.rawContent = rawContent;
-    this.hash = hashContent(rawContent);
-    this.actual = {
-      lines: rawContent.split("\n").length,
-      bytes: Buffer.byteLength(rawContent),
-    };
-    this.lang = detectStructuredFormat(filePath);
-    this.supportsOutline = this.lang !== null;
-    const result = extractOutlineForFile(filePath, rawContent);
-    this.outline = result?.entries ?? [];
-    this.jumpTable = result?.jumpTable ?? [];
-    Object.freeze(this.actual);
-    Object.freeze(this);
-  }
-}

package/src/operations/diff-identity.ts

@@ -1,127 +0,0 @@
-/**
- * Identity enrichment for structural diffs.
- *
- * When WARP indexed truth is available, projects canonical symbol
- * identity (`sid:*`) onto DiffEntry objects. Level 1 address truth
- * (name, kind, signature) is preserved — identityId is additive.
- *
- * Symbols without indexed identity keep identityId undefined.
- * This module never fabricates identity from heuristics.
- */
-
-import { DiffEntry, OutlineDiff } from "../parser/diff.js";
-import type { GraftDiffResult, FileDiff } from "./graft-diff.js";
-
-/**
- * Identity lookup: maps symbol name to identityId for a single file.
- */
-export type IdentityMap = ReadonlyMap<string, string>;
-
-/**
- * Resolves canonical symbol identities for a file path.
- * Returns an empty map when the file has no indexed symbols.
- */
-export type IdentityResolver = (filePath: string) => Promise<IdentityMap>;
-
-/**
- * Enrich a single DiffEntry with identity from the WARP index.
- * Returns a new DiffEntry with identityId when found, or the
- * original entry unchanged when no indexed identity exists.
- */
-function enrichEntry(
-  entry: DiffEntry,
-  identities: IdentityMap,
-): DiffEntry {
-  const identityId = identities.get(entry.name);
-  const enrichedChildDiff = entry.childDiff !== undefined
-    ? enrichOutlineDiff(entry.childDiff, identities)
-    : undefined;
-
-  // No identity and no child enrichment needed — return original
-  if (identityId === undefined && enrichedChildDiff === undefined) {
-    return entry;
-  }
-
-  return new DiffEntry({
-    name: entry.name,
-    kind: entry.kind,
-    ...(entry.signature !== undefined ? { signature: entry.signature } : {}),
-    ...(entry.oldSignature !== undefined ? { oldSignature: entry.oldSignature } : {}),
-    ...(enrichedChildDiff !== undefined ? { childDiff: enrichedChildDiff } : entry.childDiff !== undefined ? { childDiff: entry.childDiff } : {}),
-    ...(identityId !== undefined ? { identityId } : {}),
-  });
-}
-
-/**
- * Enrich all entries in an OutlineDiff with WARP identity.
- * Returns undefined if no entries were actually enriched (saves allocation).
- */
-function enrichOutlineDiff(
-  diff: OutlineDiff,
-  identities: IdentityMap,
-): OutlineDiff | undefined {
-  const enrichedAdded = diff.added.map((e) => enrichEntry(e, identities));
-  const enrichedRemoved = diff.removed.map((e) => enrichEntry(e, identities));
-  const enrichedChanged = diff.changed.map((e) => enrichEntry(e, identities));
-
-  const anyEnriched =
-    enrichedAdded.some((e, i) => e !== diff.added[i]) ||
-    enrichedRemoved.some((e, i) => e !== diff.removed[i]) ||
-    enrichedChanged.some((e, i) => e !== diff.changed[i]);
-
-  if (!anyEnriched) return undefined;
-
-  return new OutlineDiff({
-    added: [...enrichedAdded],
-    removed: [...enrichedRemoved],
-    changed: [...enrichedChanged],
-    continuity: [...diff.continuity],
-    unchangedCount: diff.unchangedCount,
-  });
-}
-
-/**
- * Enrich a GraftDiffResult with canonical symbol identities.
- *
- * For each file in the diff, resolves symbol identities through the
- * provided resolver and attaches them to matching DiffEntry objects.
- * Files with no indexed symbols pass through unchanged.
- *
- * This function is safe to call even when the resolver has no data —
- * it gracefully degrades to returning the original result.
- */
-export async function enrichDiffWithIdentity(
-  result: GraftDiffResult,
-  resolve: IdentityResolver,
-): Promise<GraftDiffResult> {
-  const enrichedFiles: FileDiff[] = [];
-  let anyEnriched = false;
-
-  for (const file of result.files) {
-    const identities = await resolve(file.path);
-
-    if (identities.size === 0) {
-      enrichedFiles.push(file);
-      continue;
-    }
-
-    const enrichedDiff = enrichOutlineDiff(file.diff, identities);
-    if (enrichedDiff === undefined) {
-      enrichedFiles.push(file);
-      continue;
-    }
-
-    anyEnriched = true;
-    enrichedFiles.push({
-      ...file,
-      diff: enrichedDiff,
-    });
-  }
-
-  if (!anyEnriched) return result;
-
-  return {
-    ...result,
-    files: enrichedFiles,
-  };
-}

package/src/operations/file-outline.ts

@@ -1,48 +0,0 @@
-import { extractOutlineForFile } from "../parser/outline.js";
-import type { OutlineEntry, JumpEntry } from "../parser/types.js";
-import type { FileSystem } from "../ports/filesystem.js";
-
-export interface FileOutlineResult {
-  path: string;
-  outline: OutlineEntry[];
-  jumpTable: JumpEntry[];
-  partial?: boolean | undefined;
-  cacheHit?: boolean | undefined;
-  reason?: "UNSUPPORTED_LANGUAGE" | undefined;
-  error?: string | undefined;
-}
-
-export async function fileOutline(
-  filePath: string,
-  opts: { fs: FileSystem },
-): Promise<FileOutlineResult> {
-  let content: string;
-  try {
-    content = await opts.fs.readFile(filePath, "utf-8");
-  } catch {
-    return {
-      path: filePath,
-      outline: [],
-      jumpTable: [],
-      error: "File not found",
-    };
-  }
-
-  const result = extractOutlineForFile(filePath, content);
-  if (result === null) {
-    return {
-      path: filePath,
-      outline: [],
-      jumpTable: [],
-      reason: "UNSUPPORTED_LANGUAGE",
-      error: "Unsupported file type: no parser-backed outline available",
-    };
-  }
-
-  return {
-    path: filePath,
-    outline: result.entries,
-    jumpTable: result.jumpTable ?? [],
-    ...(result.partial === true ? { partial: true } : {}),
-  };
-}

package/src/operations/graft-diff.ts

@@ -1,162 +0,0 @@
-import type { FileSystem } from "../ports/filesystem.js";
-import type { GitClient } from "../ports/git.js";
-import { getChangedFiles, getFileAtRef } from "../git/diff.js";
-import { detectLang } from "../parser/lang.js";
-import { extractOutline } from "../parser/outline.js";
-import { diffOutlines, OutlineDiff } from "../parser/diff.js";
-
-export interface FileDiff {
-  path: string;
-  status: "modified" | "added" | "deleted";
-  summary: string;
-  diff: OutlineDiff;
-}
-
-export interface GraftDiffRefusal {
-  path: string;
-  reason: string;
-  reasonDetail: string;
-  next: readonly string[];
-  actual: { lines: number; bytes: number };
-}
-
-function buildSummary(filePath: string, status: string, diff: OutlineDiff): string {
-  const parts: string[] = [];
-  if (diff.added.length > 0) parts.push(`+${String(diff.added.length)} added`);
-  if (diff.removed.length > 0) parts.push(`-${String(diff.removed.length)} removed`);
-  if (diff.changed.length > 0) parts.push(`~${String(diff.changed.length)} changed`);
-  if (diff.unchangedCount > 0) parts.push(`=${String(diff.unchangedCount)} unchanged`);
-  const stats = parts.length > 0 ? parts.join(", ") : "no structural changes";
-  return `${filePath} | ${status} | ${stats}`;
-}
-
-export interface GraftDiffResult {
-  base: string;
-  head: string;
-  files: FileDiff[];
-  refused?: GraftDiffRefusal[] | undefined;
-}
-
-export interface GraftDiffOptions {
-  cwd: string;
-  fs: FileSystem;
-  git: GitClient;
-  resolveWorkingTreePath: (filePath: string) => string;
-  base?: string | undefined;
-  head?: string | undefined;
-  path?: string | undefined;
-  refusalCheck?: ((filePath: string, actual: { lines: number; bytes: number }) => GraftDiffRefusal | null) | undefined;
-}
-
-function emptyDiff(): OutlineDiff {
-  return new OutlineDiff({ added: [], removed: [], changed: [], unchangedCount: 0 });
-}
-
-function countLines(content: string): number {
-  return content.split("\n").length;
-}
-
-function measureActual(
-  baseContent: string | null,
-  headContent: string | null,
-): { lines: number; bytes: number } {
-  const byteLengths = [baseContent, headContent]
-    .filter((content): content is string => content !== null)
-    .map((content) => Buffer.byteLength(content));
-  const lineCounts = [baseContent, headContent]
-    .filter((content): content is string => content !== null)
-    .map((content) => countLines(content));
-
-  return {
-    bytes: byteLengths.length > 0 ? Math.max(...byteLengths) : 0,
-    lines: lineCounts.length > 0 ? Math.max(...lineCounts) : 0,
-  };
-}
-
-
-/**
- * Compute structural diffs between two git refs (or working tree).
- */
-export async function graftDiff(opts: GraftDiffOptions): Promise<GraftDiffResult> {
-  const base = opts.base ?? "HEAD";
-  const headLabel = opts.head ?? "working tree";
-  const cwd = opts.cwd;
-
-  let changedFiles = await getChangedFiles({
-    cwd,
-    git: opts.git,
-    base,
-    head: opts.head,
-  });
-
-  // Filter by path if provided
-  if (opts.path !== undefined) {
-    changedFiles = changedFiles.filter((f) => f === opts.path);
-  }
-
-  const files: FileDiff[] = [];
-  const refused: GraftDiffRefusal[] = [];
-
-  for (const filePath of changedFiles) {
-    // Get content at base (null = file absent at ref)
-    const baseContent = await getFileAtRef(base, filePath, { cwd, git: opts.git });
-
-    // Get content at head (null = file absent at ref/worktree)
-    let headContent: string | null;
-    if (opts.head !== undefined) {
-      headContent = await getFileAtRef(opts.head, filePath, { cwd, git: opts.git });
-    } else {
-      try {
-        headContent = await opts.fs.readFile(opts.resolveWorkingTreePath(filePath), "utf-8");
-      } catch {
-        headContent = null;
-      }
-    }
-
-    // Determine status
-    let status: "modified" | "added" | "deleted";
-    if (baseContent === null && headContent === null) {
-      // Both absent — file listed in diff but unreadable at both refs. Skip.
-      continue;
-    } else if (baseContent === null) {
-      status = "added";
-    } else if (headContent === null) {
-      status = "deleted";
-    } else {
-      status = "modified";
-    }
-
-    const actual = measureActual(baseContent, headContent);
-    const refusal = opts.refusalCheck?.(filePath, actual) ?? null;
-    if (refusal !== null) {
-      refused.push(refusal);
-      continue;
-    }
-
-    const lang = detectLang(filePath);
-
-    // Compute structural diff (only for supported languages)
-    if (lang === null) {
-      const empty = emptyDiff();
-      files.push({ path: filePath, status, summary: buildSummary(filePath, status, empty), diff: empty });
-      continue;
-    }
-
-    const baseOutline = baseContent !== null
-      ? extractOutline(baseContent, lang).entries
-      : [];
-    const headOutline = headContent !== null
-      ? extractOutline(headContent, lang).entries
-      : [];
-
-    const diff = diffOutlines(baseOutline, headOutline);
-    files.push({ path: filePath, status, summary: buildSummary(filePath, status, diff), diff });
-  }
-
-  return {
-    base,
-    head: headLabel,
-    files,
-    ...(refused.length > 0 ? { refused } : {}),
-  };
-}

package/src/operations/observation-cache.ts

@@ -1,149 +0,0 @@
-// ---------------------------------------------------------------------------
-// Observation cache — tracks file content seen by the agent
-// ---------------------------------------------------------------------------
-
-import type { OutlineEntry, JumpEntry } from "../parser/types.js";
-
-export function hashContent(content: string): string {
-  let hash = 2166136261;
-  for (let index = 0; index < content.length; index++) {
-    hash ^= content.charCodeAt(index);
-    hash = Math.imul(hash, 16777619);
-  }
-  return (hash >>> 0).toString(16).padStart(8, "0");
-}
-
-export interface ObservationSnapshot {
-  readonly contentHash: string;
-  readonly outline: readonly OutlineEntry[];
-  readonly jumpTable: readonly JumpEntry[];
-  readonly actual: Readonly<{ lines: number; bytes: number }>;
-  readonly readCount: number;
-  readonly firstReadAt: string;
-  readonly lastReadAt: string;
-}
-
-export class Observation {
-  readonly contentHash: string;
-  readonly outline: readonly OutlineEntry[];
-  readonly jumpTable: readonly JumpEntry[];
-  readonly actual: Readonly<{ lines: number; bytes: number }>;
-  readonly firstReadAt: string;
-  private _readCount: number;
-  private _lastReadAt: string;
-
-  constructor(opts: {
-    contentHash: string;
-    outline: readonly OutlineEntry[];
-    jumpTable: readonly JumpEntry[];
-    actual: Readonly<{ lines: number; bytes: number }>;
-    readCount: number;
-    firstReadAt: string;
-    lastReadAt: string;
-  }) {
-    this.contentHash = opts.contentHash;
-    this.outline = opts.outline;
-    this.jumpTable = opts.jumpTable;
-    this.actual = opts.actual;
-    this._readCount = opts.readCount;
-    this.firstReadAt = opts.firstReadAt;
-    this._lastReadAt = opts.lastReadAt;
-  }
-
-  get readCount(): number {
-    return this._readCount;
-  }
-
-  get lastReadAt(): string {
-    return this._lastReadAt;
-  }
-
-  isStale(currentContentHash: string): boolean {
-    return this.contentHash !== currentContentHash;
-  }
-
-  touch(): void {
-    this._readCount++;
-    this._lastReadAt = new Date().toISOString();
-  }
-
-  snapshot(): ObservationSnapshot {
-    return {
-      contentHash: this.contentHash,
-      outline: this.outline,
-      jumpTable: this.jumpTable,
-      actual: this.actual,
-      readCount: this.readCount,
-      firstReadAt: this.firstReadAt,
-      lastReadAt: this.lastReadAt,
-    };
-  }
-
-  static fromSnapshot(snapshot: ObservationSnapshot): Observation {
-    return new Observation(snapshot);
-  }
-}
-
-export type CacheResult =
-  | { hit: true; obs: Observation }
-  | { hit: false; stale: Observation | null };
-
-export class ObservationCache {
-  private readonly entries = new Map<string, Observation>();
-
-  static fromSnapshots(
-    snapshots: Readonly<Record<string, ObservationSnapshot>> | undefined,
-  ): ObservationCache {
-    const cache = new ObservationCache();
-    if (snapshots === undefined) {
-      return cache;
-    }
-    for (const [filePath, snapshot] of Object.entries(snapshots)) {
-      cache.entries.set(filePath, Observation.fromSnapshot(snapshot));
-    }
-    return cache;
-  }
-
-  record(
-    filePath: string,
-    contentHash: string,
-    outline: readonly OutlineEntry[],
-    jumpTable: readonly JumpEntry[],
-    actual: Readonly<{ lines: number; bytes: number }>,
-  ): void {
-    const existing = this.entries.get(filePath);
-    const now = new Date().toISOString();
-    this.entries.set(filePath, new Observation({
-      contentHash,
-      outline,
-      jumpTable,
-      actual,
-      readCount: (existing?.readCount ?? 0) + 1,
-      firstReadAt: existing?.firstReadAt ?? now,
-      lastReadAt: now,
-    }));
-  }
-
-  check(filePath: string, currentContent: string): CacheResult {
-    const obs = this.entries.get(filePath);
-    if (obs === undefined) return { hit: false, stale: null };
-    if (!obs.isStale(hashContent(currentContent))) return { hit: true, obs };
-    return { hit: false, stale: obs };
-  }
-
-  get(filePath: string): Observation | undefined {
-    return this.entries.get(filePath);
-  }
-
-  snapshotEntry(filePath: string): ObservationSnapshot | null {
-    return this.entries.get(filePath)?.snapshot() ?? null;
-  }
-
-  applySnapshot(filePath: string, snapshot: ObservationSnapshot | null): void {
-    if (snapshot === null) {
-      this.entries.delete(filePath);
-      return;
-    }
-    this.entries.set(filePath, Observation.fromSnapshot(snapshot));
-  }
-}

package/src/operations/read-range.ts

@@ -1,64 +0,0 @@
-import type { FileSystem } from "../ports/filesystem.js";
-
-const MAX_RANGE_LINES = 250;
-
-export interface ReadRangeResult {
-  path: string;
-  content?: string | undefined;
-  startLine?: number | undefined;
-  endLine?: number | undefined;
-  reason?: string | undefined;
-  truncated?: boolean | undefined;
-  clipped?: boolean | undefined;
-}
-
-export async function readRange(
-  filePath: string,
-  start: number,
-  end: number,
-  opts: { fs: FileSystem },
-): Promise<ReadRangeResult> {
-  let raw: string;
-  try {
-    raw = await opts.fs.readFile(filePath, "utf-8");
-  } catch {
-    return { path: filePath, reason: "NOT_FOUND" };
-  }
-
-  if (start > end) {
-    return { path: filePath, reason: "INVALID_RANGE" };
-  }
-
-  const allLines = raw.split("\n");
-  const totalLines = allLines.length;
-
-  let effectiveEnd = end;
-  let truncated = false;
-  let clipped = false;
-
-  // Check if range exceeds 250 lines
-  if (effectiveEnd - start + 1 > MAX_RANGE_LINES) {
-    effectiveEnd = start + MAX_RANGE_LINES - 1;
-    truncated = true;
-  }
-
-  // Clip to EOF
-  if (effectiveEnd > totalLines) {
-    effectiveEnd = totalLines;
-    clipped = true;
-  }
-
-  // Extract lines (1-based to 0-based)
-  const selected = allLines.slice(start - 1, effectiveEnd);
-  const content = selected.join("\n");
-
-  return {
-    path: filePath,
-    content,
-    startLine: start,
-    endLine: effectiveEnd,
-    ...(truncated ? { truncated: true, reason: "RANGE_EXCEEDED" } : {}),
-    ...(clipped && !truncated ? { clipped: true } : {}),
-    ...(clipped && truncated ? { clipped: true } : {}),
-  };
-}