@flyingrobots/graft 0.7.0 → 0.8.0

package/src/operations/graft-diff.ts

@@ -1,169 +0,0 @@
-import type { FileSystem } from "../ports/filesystem.js";
-import type { GitClient } from "../ports/git.js";
-import { getChangedFilesWithStatus, 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 changedEntries = await getChangedFilesWithStatus({
-    cwd,
-    git: opts.git,
-    base,
-    head: opts.head,
-  });
-
-  // Filter by path if provided
-  if (opts.path !== undefined) {
-    changedEntries = changedEntries.filter((f) => f.path === opts.path);
-  }
-
-  const files: FileDiff[] = [];
-  const refused: GraftDiffRefusal[] = [];
-
-  for (const entry of changedEntries) {
-    const filePath = entry.path;
-    // For renames, read base content from the old path
-    const basePath = entry.oldPath ?? filePath;
-
-    // Get content at base (null = file absent at ref)
-    const baseContent = await getFileAtRef(base, basePath, { 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 — trust git's rename detection for renames,
-    // fall back to content-based detection for other statuses
-    let status: "modified" | "added" | "deleted";
-    if (entry.status === "renamed") {
-      status = "modified";
-    } else 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/horizon-of-readability.ts

@@ -1,60 +0,0 @@
-// ---------------------------------------------------------------------------
-// Horizon of Readability — detect when projection can't reduce further
-// ---------------------------------------------------------------------------
-
-/** Input metrics for horizon detection. */
-export interface HorizonInput {
-  readonly contentLines: number;
-  readonly contentBytes: number;
-  readonly outlineLines: number;
-  readonly outlineBytes: number;
-}
-
-/** Result of horizon detection. */
-export interface HorizonResult {
-  readonly horizonReached: boolean;
-  readonly compressionRatio: number;
-  readonly recommendation: "outline" | "content";
-  readonly message?: string;
-}
-
-/** Compression ratio threshold above which outline provides negligible savings. */
-const HORIZON_THRESHOLD = 0.7;
-
-/**
- * Detect whether the readability horizon has been reached.
- *
- * When the outline is nearly as large as the content (compression
- * ratio > threshold), the file is irreducibly complex for the
- * outline representation. Return full content instead.
- */
-export function detectReadabilityHorizon(input: HorizonInput): HorizonResult {
-  const { contentBytes, outlineBytes } = input;
-
-  // Zero-size files are at the horizon (nothing to simplify)
-  if (contentBytes === 0) {
-    return {
-      horizonReached: true,
-      compressionRatio: 1,
-      recommendation: "content",
-      message: "Empty file — full content provided.",
-    };
-  }
-
-  const compressionRatio = outlineBytes / contentBytes;
-
-  if (compressionRatio >= HORIZON_THRESHOLD) {
-    return {
-      horizonReached: true,
-      compressionRatio,
-      recommendation: "content",
-      message: `Outline is ${String(Math.round(compressionRatio * 100))}% of content — cannot simplify further. Full content provided.`,
-    };
-  }
-
-  return {
-    horizonReached: false,
-    compressionRatio,
-    recommendation: "outline",
-  };
-}

package/src/operations/import-reference-impact.ts

@@ -1,143 +0,0 @@
-import { getFileAtRef } from "../git/diff.js";
-import { detectLang } from "../parser/lang.js";
-import type { GitClient } from "../ports/git.js";
-import type { PathOps } from "../ports/paths.js";
-import type { ReferenceCountResult } from "./structural-review.js";
-
-const NAMED_IMPORT_OR_REEXPORT =
-  /\b(?:import|export)\s+(?:type\s+)?\{([\s\S]*?)\}\s+from\s+["']([^"']+)["']/g;
-
-export interface ImportReferenceImpactOptions {
-  readonly cwd: string;
-  readonly git: GitClient;
-  readonly pathOps: PathOps;
-  readonly symbolName: string;
-  readonly filePath: string;
-  readonly ref: string;
-}
-
-async function listFilesAtRef(opts: Pick<ImportReferenceImpactOptions, "cwd" | "git" | "ref">): Promise<readonly string[]> {
-  const result = await opts.git.run({
-    args: ["ls-tree", "-r", "--name-only", opts.ref],
-    cwd: opts.cwd,
-  });
-  if (result.error !== undefined || result.status !== 0) {
-    throw result.error ?? new Error(result.stderr.trim() || `git ls-tree failed with status ${String(result.status)}`);
-  }
-  const output = result.stdout.trim();
-  return output.length === 0 ? [] : output.split("\n");
-}
-
-function compiledSpecifierSourceCandidates(resolvedImportSource: string): readonly string[] {
-  const compiledToSourceExtensions: readonly [string, readonly string[]][] = [
-    [".js", [".ts", ".tsx"]],
-    [".jsx", [".tsx", ".ts"]],
-    [".mjs", [".mts", ".ts"]],
-    [".cjs", [".cts", ".ts"]],
-  ];
-
-  for (const [compiledExtension, sourceExtensions] of compiledToSourceExtensions) {
-    if (!resolvedImportSource.endsWith(compiledExtension)) continue;
-
-    const base = resolvedImportSource.slice(0, -compiledExtension.length);
-    return sourceExtensions.map((sourceExtension) => `${base}${sourceExtension}`);
-  }
-
-  return [];
-}
-
-function resolveModulePath(
-  importSource: string,
-  importingFilePath: string,
-  knownFiles: ReadonlySet<string>,
-  pathOps: PathOps,
-): string | null {
-  if (!importSource.startsWith(".") && !importSource.startsWith("/")) {
-    return null;
-  }
-
-  const dir = importingFilePath.includes("/")
-    ? importingFilePath.slice(0, importingFilePath.lastIndexOf("/"))
-    : "";
-  const raw = dir.length > 0
-    ? pathOps.join(dir, importSource)
-    : pathOps.normalize(importSource);
-  const sourceExtensionCandidates = compiledSpecifierSourceCandidates(raw);
-  const candidates = [
-    raw,
-    ...sourceExtensionCandidates,
-    `${raw}.ts`,
-    `${raw}.tsx`,
-    `${raw}.js`,
-    `${raw}.jsx`,
-    `${raw}/index.ts`,
-    `${raw}/index.tsx`,
-    `${raw}/index.js`,
-  ];
-
-  return candidates.find((candidate) => knownFiles.has(candidate)) ?? null;
-}
-
-function importsSymbol(namedImports: string, symbolName: string): boolean {
-  return namedImports
-    .split(",")
-    .map((part) => part.trim().replace(/^type\s+/, ""))
-    .some((part) => {
-      const importedName = part.split(/\s+as\s+/u)[0]?.trim();
-      return importedName === symbolName;
-    });
-}
-
-function fileImportsSymbolFromTarget(
-  content: string,
-  importingFilePath: string,
-  symbolName: string,
-  targetFilePath: string,
-  knownFiles: ReadonlySet<string>,
-  pathOps: PathOps,
-): boolean {
-  NAMED_IMPORT_OR_REEXPORT.lastIndex = 0;
-  let match: RegExpExecArray | null;
-  while ((match = NAMED_IMPORT_OR_REEXPORT.exec(content)) !== null) {
-    const namedImports = match[1];
-    const importSource = match[2];
-    if (namedImports === undefined || importSource === undefined) continue;
-    if (!importsSymbol(namedImports, symbolName)) continue;
-    if (resolveModulePath(importSource, importingFilePath, knownFiles, pathOps) === targetFilePath) {
-      return true;
-    }
-  }
-  return false;
-}
-
-export async function countNamedImportReferencesAtRef(
-  opts: ImportReferenceImpactOptions,
-): Promise<ReferenceCountResult> {
-  const files = await listFilesAtRef(opts);
-  const knownFiles = new Set(files);
-  const referencingFiles: string[] = [];
-
-  for (const candidate of files) {
-    if (candidate === opts.filePath || detectLang(candidate) === null) continue;
-    const content = await getFileAtRef(opts.ref, candidate, {
-      cwd: opts.cwd,
-      git: opts.git,
-    });
-    if (content === null) continue;
-    if (fileImportsSymbolFromTarget(
-      content,
-      candidate,
-      opts.symbolName,
-      opts.filePath,
-      knownFiles,
-      opts.pathOps,
-    )) {
-      referencingFiles.push(candidate);
-    }
-  }
-
-  return {
-    referenceCount: referencingFiles.length,
-    referencingFiles,
-  };
-}

package/src/operations/knowledge-map.ts

@@ -1,96 +0,0 @@
-// ---------------------------------------------------------------------------
-// Knowledge map — "what do I already know?" query over the observation cache
-// ---------------------------------------------------------------------------
-
-import type { ObservationCache } from "./observation-cache.js";
-import { hashContent } from "./observation-cache.js";
-import type { FileSystem } from "../ports/filesystem.js";
-
-export interface KnowledgeFileEntry {
-  readonly path: string;
-  readonly symbols: readonly string[];
-  readonly readCount: number;
-  readonly lastReadAt: string;
-  readonly stale: boolean;
-}
-
-export interface KnowledgeMapResult {
-  readonly totalFiles: number;
-  readonly totalSymbols: number;
-  readonly files: readonly KnowledgeFileEntry[];
-  readonly staleFiles: readonly string[];
-  readonly directoryCoverage: Readonly<Record<string, number>>;
-}
-
-export interface KnowledgeMapOptions {
-  readonly cache: ObservationCache;
-  readonly fs: FileSystem;
-  readonly projectRoot: string;
-}
-
-/**
- * Build a knowledge map from the current observation cache.
- *
- * For each observed file, checks whether the file has changed on disk
- * since it was last read (staleness). Aggregates symbols and directory
- * coverage.
- */
-export async function buildKnowledgeMap(options: KnowledgeMapOptions): Promise<KnowledgeMapResult> {
-  const { cache, fs: fileSystem, projectRoot } = options;
-  const files: KnowledgeFileEntry[] = [];
-  const staleFiles: string[] = [];
-  const dirCounts = new Map<string, number>();
-  let totalSymbols = 0;
-
-  for (const [filePath, observation] of cache.allEntries()) {
-    const symbols = observation.outline.map((entry) => entry.name);
-    totalSymbols += symbols.length;
-
-    // Check staleness by reading current content and comparing hash
-    let stale: boolean;
-    try {
-      const currentContent = await fileSystem.readFile(filePath, "utf-8");
-      stale = observation.isStale(hashContent(currentContent));
-    } catch {
-      // File no longer exists — mark as stale
-      stale = true;
-    }
-
-    if (stale) {
-      staleFiles.push(filePath);
-    }
-
-    files.push({
-      path: filePath,
-      symbols,
-      readCount: observation.readCount,
-      lastReadAt: observation.lastReadAt,
-      stale,
-    });
-
-    // Directory coverage — use relative path from project root
-    const relative = filePath.startsWith(projectRoot + "/")
-      ? filePath.slice(projectRoot.length + 1)
-      : filePath;
-    const lastSlash = relative.lastIndexOf("/");
-    const dir = lastSlash === -1 ? "." : relative.slice(0, lastSlash);
-    dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
-  }
-
-  // Sort files by path for deterministic output
-  files.sort((a, b) => a.path.localeCompare(b.path));
-  staleFiles.sort();
-
-  const directoryCoverage: Record<string, number> = {};
-  for (const [dir, count] of [...dirCounts.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-    directoryCoverage[dir] = count;
-  }
-
-  return {
-    totalFiles: files.length,
-    totalSymbols,
-    files,
-    staleFiles,
-    directoryCoverage,
-  };
-}

package/src/operations/observation-cache.ts

@@ -1,165 +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(now: string): void {
-    this._readCount++;
-    this._lastReadAt = now;
-  }
-
-  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>();
-  readonly now: () => string;
-
-  constructor(now?: () => string) {
-    this.now = now ?? (() => new Date().toISOString());
-  }
-
-  static fromSnapshots(
-    snapshots: Readonly<Record<string, ObservationSnapshot>> | undefined,
-    now?: () => string,
-  ): ObservationCache {
-    const cache = new ObservationCache(now);
-    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 = this.now();
-    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));
-  }
-
-  /** Iterate all observed file paths and their observations. */
-  allEntries(): IterableIterator<[string, Observation]> {
-    return this.entries.entries();
-  }
-
-  /** Number of observed files. */
-  get size(): number {
-    return this.entries.size;
-  }
-}