@flyingrobots/graft 0.6.1 → 0.7.0

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

@@ -0,0 +1,143 @@
+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

@@ -0,0 +1,96 @@
+// ---------------------------------------------------------------------------
+// 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

@@ -62,9 +62,9 @@ export class Observation {
     return this.contentHash !== currentContentHash;
   }
 
-  touch(): void {
+  touch(now: string): void {
     this._readCount++;
-    this._lastReadAt = new Date().toISOString();
+    this._lastReadAt = now;
   }
 
   snapshot(): ObservationSnapshot {
@@ -90,11 +90,17 @@ export type CacheResult =
 
 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();
+    const cache = new ObservationCache(now);
     if (snapshots === undefined) {
       return cache;
     }
@@ -112,7 +118,7 @@ export class ObservationCache {
     actual: Readonly<{ lines: number; bytes: number }>,
   ): void {
     const existing = this.entries.get(filePath);
-    const now = new Date().toISOString();
+    const now = this.now();
     this.entries.set(filePath, new Observation({
       contentHash,
       outline,
@@ -146,4 +152,14 @@ export class ObservationCache {
     }
     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;
+  }
 }

package/src/operations/projection-safety.ts

@@ -0,0 +1,111 @@
+// ---------------------------------------------------------------------------
+// Projection Safety Classes — what can each projection level answer?
+// ---------------------------------------------------------------------------
+
+/** Question classes ordered by information requirement. */
+export type QuestionClass = "existence" | "structure" | "signature" | "behavior";
+
+/** Projection levels ordered by detail. */
+export type ProjectionLevel = "outline" | "signature" | "content";
+
+/** Warning when a projection is insufficient for the inferred question. */
+export interface SafetyWarning {
+  readonly questionClass: QuestionClass;
+  readonly currentProjection: ProjectionLevel;
+  readonly requiredProjection: ProjectionLevel;
+  readonly message: string;
+}
+
+/** Metadata about what a projection level can answer. */
+export interface SafetyClassMetadata {
+  readonly projection: ProjectionLevel;
+  readonly answerable: readonly QuestionClass[];
+}
+
+// ---------------------------------------------------------------------------
+// Question class taxonomy
+// ---------------------------------------------------------------------------
+
+/** What each projection level can safely answer. */
+const ANSWERABLE: Readonly<Record<ProjectionLevel, readonly QuestionClass[]>> = {
+  outline: ["existence", "structure"],
+  signature: ["existence", "structure", "signature"],
+  content: ["existence", "structure", "signature", "behavior"],
+};
+
+/** Minimum projection needed for each question class. */
+const MINIMUM_PROJECTION: Readonly<Record<QuestionClass, ProjectionLevel>> = {
+  existence: "outline",
+  structure: "outline",
+  signature: "signature",
+  behavior: "content",
+};
+
+// ---------------------------------------------------------------------------
+// Tool → question class mapping
+// ---------------------------------------------------------------------------
+
+const TOOL_QUESTION_CLASS: Readonly<Record<string, QuestionClass>> = {
+  code_find: "existence",
+  graft_map: "structure",
+  file_outline: "structure",
+  code_refs: "existence",
+  code_show: "behavior",
+  safe_read: "behavior",
+  read_range: "behavior",
+  graft_diff: "structure",
+  graft_review: "structure",
+  changed_since: "structure",
+};
+
+/**
+ * Infer the question class from a tool name.
+ * Defaults to "behavior" for unknown tools (conservative).
+ */
+export function getQuestionClass(toolName: string): QuestionClass {
+  return TOOL_QUESTION_CLASS[toolName] ?? "behavior";
+}
+
+// ---------------------------------------------------------------------------
+// Safety check
+// ---------------------------------------------------------------------------
+
+/** Projection detail ordering for comparison. */
+const LEVEL_ORDER: Readonly<Record<ProjectionLevel, number>> = {
+  outline: 0,
+  signature: 1,
+  content: 2,
+};
+
+/**
+ * Check whether a projection is sufficient for the question implied
+ * by a tool call. Returns null if safe, or a warning if insufficient.
+ */
+export function checkProjectionSafety(
+  toolName: string,
+  currentProjection: ProjectionLevel,
+): SafetyWarning | null {
+  const questionClass = getQuestionClass(toolName);
+  const required = MINIMUM_PROJECTION[questionClass];
+
+  if (LEVEL_ORDER[currentProjection] >= LEVEL_ORDER[required]) {
+    return null;
+  }
+
+  return {
+    questionClass,
+    currentProjection,
+    requiredProjection: required,
+    message: `${toolName} asks a "${questionClass}" question which requires "${required}" projection, but current projection is "${currentProjection}".`,
+  };
+}
+
+/**
+ * Get metadata about what question classes a projection level can answer.
+ */
+export function getSafetyClassMetadata(projection: ProjectionLevel): SafetyClassMetadata {
+  return {
+    projection,
+    answerable: ANSWERABLE[projection],
+  };
+}

package/src/operations/repo-workspace.ts

@@ -163,7 +163,7 @@ export class RepoWorkspace {
     if (snapshot?.supportsOutline === true) {
       const cacheResult = this.cache.check(filePath, snapshot.rawContent);
       if (cacheResult.hit) {
-        cacheResult.obs.touch();
+        cacheResult.obs.touch(this.cache.now());
         return {
           path: filePath,
           projection: "cache_hit",
@@ -193,7 +193,7 @@ export class RepoWorkspace {
           jumpTable: snapshot.jumpTable,
           actual: snapshot.actual,
           readCount: cacheResult.stale.readCount + 1,
-          lastReadAt: updated?.lastReadAt ?? new Date().toISOString(),
+          lastReadAt: updated?.lastReadAt ?? this.cache.now(),
         };
       }
     }
@@ -243,7 +243,7 @@ export class RepoWorkspace {
       }
       const cacheResult = this.cache.check(filePath, rawContent);
       if (cacheResult.hit) {
-        cacheResult.obs.touch();
+        cacheResult.obs.touch(this.cache.now());
         return {
           path: filePath,
           outline: [...cacheResult.obs.outline],

package/src/operations/semantic-drift.ts

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// Semantic Drift Detection — flag interpretation shift during reading
+// ---------------------------------------------------------------------------
+
+/** A single entry in the reading path. */
+export interface ReadingPathEntry {
+  readonly filePath: string;
+  readonly timestamp: string;
+}
+
+/** Warning about potential interpretation shift. */
+export interface DriftWarning {
+  readonly filePath: string;
+  readonly firstReadIndex: number;
+  readonly reReadIndex: number;
+  readonly intervening: readonly string[];
+  readonly message: string;
+}
+
+/**
+ * Detect semantic drift in a reading path.
+ *
+ * When an agent re-reads a file after reading structurally related
+ * files (files with cross-file reference edges), the re-read may
+ * yield different understanding because the agent's context has
+ * shifted. This is holonomy: translating through a chain of
+ * observers and returning does not return to the same understanding.
+ *
+ * @param readingPath - Ordered sequence of file reads in the session
+ * @param relatedFiles - Map of file → related files (from reference edges)
+ */
+export function detectSemanticDrift(
+  readingPath: readonly ReadingPathEntry[],
+  relatedFiles: ReadonlyMap<string, readonly string[]>,
+): DriftWarning[] {
+  const warnings: DriftWarning[] = [];
+  const lastReadIndex = new Map<string, number>();
+
+  for (let i = 0; i < readingPath.length; i++) {
+    const entry = readingPath[i] ?? { filePath: "", timestamp: "" };
+    const prevIndex = lastReadIndex.get(entry.filePath);
+
+    if (prevIndex !== undefined) {
+      // This is a re-read — check if related files were read in between
+      const related = relatedFiles.get(entry.filePath) ?? [];
+      const intervening: string[] = [];
+
+      for (let j = prevIndex + 1; j < i; j++) {
+        const interveningFile = (readingPath[j] ?? { filePath: "" }).filePath;
+        if (related.includes(interveningFile)) {
+          intervening.push(interveningFile);
+        }
+      }
+
+      if (intervening.length > 0) {
+        warnings.push({
+          filePath: entry.filePath,
+          firstReadIndex: prevIndex,
+          reReadIndex: i,
+          intervening,
+          message: `Re-reading ${entry.filePath} after reading related files (${intervening.join(", ")}) may shift interpretation.`,
+        });
+      }
+    }
+
+    lastReadIndex.set(entry.filePath, i);
+  }
+
+  return warnings;
+}

package/src/operations/session-filtration.ts

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// Session Filtration — accumulation-aware projection escalation
+// ---------------------------------------------------------------------------
+
+/** Input for filtration level computation. */
+export interface FiltrationInput {
+  readonly observedFiles: number;
+  readonly totalFiles: number;
+  readonly reReadCount: number;
+}
+
+/** Input for escalation decision. */
+export interface EscalationInput {
+  readonly filtrationLevel: number;
+  readonly previousProjection: "outline" | "content";
+  readonly readCount: number;
+}
+
+/** Result of escalation check. */
+export interface EscalationResult {
+  readonly escalate: boolean;
+  readonly suggestedProjection: "outline" | "content";
+  readonly reason?: string;
+}
+
+const ESCALATION_THRESHOLD = 0.5;
+
+/**
+ * Compute the filtration level for the current session.
+ *
+ * Ranges from 0 (fresh session) to 1 (fully saturated). Based on
+ * the fraction of files observed and the number of re-reads.
+ * As filtration grows, graft escalates detail — an agent that has
+ * already explored the codebase should get richer projections.
+ */
+export function computeFiltrationLevel(input: FiltrationInput): number {
+  const { observedFiles, totalFiles, reReadCount } = input;
+  if (totalFiles === 0) return 0;
+
+  const coverageFraction = observedFiles / totalFiles;
+  const reReadBoost = Math.min(reReadCount / 20, 0.3);
+
+  return Math.min(coverageFraction + reReadBoost, 1);
+}
+
+/**
+ * Determine whether to escalate projection detail for a re-read.
+ *
+ * Monotone accumulation: as filtration grows, graft escalates.
+ * An agent that outlined a directory and is now re-reading a file
+ * in that directory should get content instead of another outline.
+ */
+export function shouldEscalateDetail(input: EscalationInput): EscalationResult {
+  const { filtrationLevel, previousProjection, readCount } = input;
+
+  // Never escalate on first read
+  if (readCount <= 1) {
+    return { escalate: false, suggestedProjection: previousProjection };
+  }
+
+  // Already at content — nothing to escalate to
+  if (previousProjection === "content") {
+    return { escalate: false, suggestedProjection: "content" };
+  }
+
+  // Escalate when filtration is high enough and this is a re-read
+  if (filtrationLevel >= ESCALATION_THRESHOLD) {
+    return {
+      escalate: true,
+      suggestedProjection: "content",
+      reason: `Filtration level ${String(Math.round(filtrationLevel * 100))}% — escalating from outline to content for re-read.`,
+    };
+  }
+
+  return { escalate: false, suggestedProjection: previousProjection };
+}

package/src/operations/session-replay.ts

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// Structural Session Replay — render a session as a structural walkthrough
+// ---------------------------------------------------------------------------
+
+/** A single tool call extracted from NDJSON receipts. */
+export interface ReplayEntry {
+  readonly tool: string;
+  readonly path?: string;
+  readonly symbol?: string;
+  readonly ts: string;
+  readonly sessionId: string;
+}
+
+/**
+ * Parse NDJSON receipt lines into replay entries for a given session.
+ */
+export function parseReceiptsForReplay(ndjson: string, sessionId: string): ReplayEntry[] {
+  const entries: ReplayEntry[] = [];
+
+  for (const line of ndjson.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+
+    let parsed: Record<string, unknown>;
+    try {
+      parsed = JSON.parse(trimmed) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+
+    if (parsed["sessionId"] !== sessionId) continue;
+    if (typeof parsed["tool"] !== "string") continue;
+
+    entries.push({
+      tool: parsed["tool"],
+      ...(typeof parsed["path"] === "string" ? { path: parsed["path"] } : {}),
+      ...(typeof parsed["symbol"] === "string" ? { symbol: parsed["symbol"] } : {}),
+      ts: typeof parsed["ts"] === "string" ? parsed["ts"] : "",
+      sessionId,
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Render replay entries as a Markdown summary.
+ */
+export function renderReplayMarkdown(entries: readonly ReplayEntry[]): string {
+  if (entries.length === 0) {
+    return "# Session Replay\n\nNo activity recorded for this session.\n";
+  }
+
+  const lines: string[] = [
+    "# Session Replay",
+    "",
+    `**${String(entries.length)} tool calls**`,
+    "",
+    "| # | Tool | Target | Time |",
+    "|---|------|--------|------|",
+  ];
+
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i] ?? { tool: "", ts: "", sessionId: "" };
+    const target = e.symbol !== undefined
+      ? `${e.path ?? ""}:${e.symbol}`
+      : (e.path ?? "—");
+    lines.push(`| ${String(i + 1)} | ${e.tool} | ${target} | ${e.ts} |`);
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}