@flyingrobots/graft 0.7.0 → 0.8.0

package/src/operations/semantic-drift.ts

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

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

@@ -1,73 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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");
-}

package/src/operations/sludge-detector.ts

@@ -1,356 +0,0 @@
-import type { SyntaxNode } from "web-tree-sitter";
-import { detectLang } from "../parser/lang.js";
-import { extractOutlineForFile } from "../parser/outline.js";
-import { parseStructuredTreeForFile } from "../parser/runtime.js";
-import type { OutlineEntry } from "../parser/types.js";
-import type { FileSystem } from "../ports/filesystem.js";
-import type { GitClient } from "../ports/git.js";
-
-export type SludgeSignalKind =
-  | "phantom_shape"
-  | "cast_density"
-  | "homeless_constructor"
-  | "free_function_data_behavior"
-  | "god_file";
-
-export type SludgeSeverity = "low" | "medium" | "high";
-
-export interface SludgeSignal {
-  readonly kind: SludgeSignalKind;
-  readonly severity: SludgeSeverity;
-  readonly message: string;
-  readonly line?: number;
-  readonly symbol?: string;
-  readonly evidence: string;
-}
-
-export interface SludgeMetrics {
-  readonly typedefCount: number;
-  readonly typeCastCount: number;
-  readonly classCount: number;
-  readonly functionCount: number;
-  readonly symbolCount: number;
-  readonly homelessConstructorCount: number;
-  readonly freeFunctionDataBehaviorCount: number;
-}
-
-export interface SludgeFileReport {
-  readonly path: string;
-  readonly score: number;
-  readonly metrics: SludgeMetrics;
-  readonly signals: readonly SludgeSignal[];
-}
-
-export interface SludgeReport {
-  readonly scannedFiles: number;
-  readonly filesWithSignals: number;
-  readonly totalSignals: number;
-  readonly score: number;
-  readonly files: readonly SludgeFileReport[];
-  readonly summary: string;
-}
-
-export interface DetectSludgeOptions {
-  readonly cwd: string;
-  readonly fs: FileSystem;
-  readonly git: GitClient;
-  readonly resolvePath: (filePath: string) => string;
-  readonly path?: string;
-}
-
-interface FunctionFact {
-  readonly name: string;
-  readonly line: number;
-  readonly firstParameterType: string | null;
-  readonly returnsPlainObject: boolean;
-}
-
-const CONSTRUCTOR_PREFIXES = ["build", "create", "make", "assemble"] as const;
-
-function walk(node: SyntaxNode, visit: (node: SyntaxNode) => void): void {
-  visit(node);
-  for (const child of node.namedChildren) {
-    walk(child, visit);
-  }
-}
-
-function countOutlineEntries(
-  entries: readonly OutlineEntry[],
-  predicate: (entry: OutlineEntry) => boolean,
-): number {
-  let count = 0;
-  for (const entry of entries) {
-    if (predicate(entry)) count++;
-    if (entry.children !== undefined) {
-      count += countOutlineEntries(entry.children, predicate);
-    }
-  }
-  return count;
-}
-
-function collectTypeNames(entries: readonly OutlineEntry[]): Set<string> {
-  const names = new Set<string>();
-  for (const entry of entries) {
-    if (entry.kind === "class" || entry.kind === "interface" || entry.kind === "type") {
-      names.add(entry.name);
-    }
-    if (entry.children !== undefined) {
-      for (const childName of collectTypeNames(entry.children)) {
-        names.add(childName);
-      }
-    }
-  }
-  return names;
-}
-
-function startsWithConstructorPrefix(name: string): boolean {
-  const lower = name.toLowerCase();
-  return CONSTRUCTOR_PREFIXES.some((prefix) => lower.startsWith(prefix) && lower.length > prefix.length);
-}
-
-function isPlainObjectExpression(node: SyntaxNode | null): boolean {
-  if (node === null) return false;
-  if (node.type === "object") return true;
-  if (node.type !== "parenthesized_expression") return false;
-  return node.namedChildren.some((child) => child.type === "object");
-}
-
-function returnsPlainObject(node: SyntaxNode): boolean {
-  const body = node.childForFieldName("body");
-  if (isPlainObjectExpression(body)) return true;
-
-  let found = false;
-  const searchRoot = body ?? node;
-  walk(searchRoot, (child) => {
-    if (found || child.type !== "return_statement") return;
-    found = isPlainObjectExpression(child.namedChildren[0] ?? null);
-  });
-  return found;
-}
-
-function normalizedTypeName(typeAnnotation: SyntaxNode | null): string | null {
-  if (typeAnnotation === null) return null;
-  let text = typeAnnotation.text.trim();
-  if (text.startsWith(":")) {
-    text = text.slice(1).trim();
-  }
-  let end = text.length;
-  for (let index = 0; index < text.length; index++) {
-    const char = text[index];
-    if (char === "<" || char === " " || char === "|" || char === "&" || char === "[" || char === ".") {
-      end = index;
-      break;
-    }
-  }
-  const name = text.slice(0, end).trim();
-  return name.length > 0 ? name : null;
-}
-
-function firstParameterType(functionNode: SyntaxNode): string | null {
-  const parameters = functionNode.childForFieldName("parameters");
-  const firstParameter = parameters?.namedChildren[0];
-  if (firstParameter === undefined) return null;
-  return normalizedTypeName(firstParameter.childForFieldName("type"));
-}
-
-function functionFact(name: string, node: SyntaxNode): FunctionFact {
-  return {
-    name,
-    line: node.startPosition.row + 1,
-    firstParameterType: firstParameterType(node),
-    returnsPlainObject: returnsPlainObject(node),
-  };
-}
-
-function declarationFunctionFacts(node: SyntaxNode): FunctionFact[] {
-  if (node.type === "function_declaration" || node.type === "generator_function_declaration") {
-    const name = node.childForFieldName("name")?.text;
-    return name !== undefined ? [functionFact(name, node)] : [];
-  }
-
-  if (node.type !== "lexical_declaration") return [];
-
-  const facts: FunctionFact[] = [];
-  for (const declarator of node.namedChildren) {
-    if (declarator.type !== "variable_declarator") continue;
-    const name = declarator.childForFieldName("name")?.text;
-    const value = declarator.childForFieldName("value");
-    if (name === undefined || value === null) continue;
-    if (value.type === "arrow_function" || value.type === "function") {
-      facts.push(functionFact(name, value));
-    }
-  }
-  return facts;
-}
-
-function topLevelFunctionFacts(root: SyntaxNode): FunctionFact[] {
-  const facts: FunctionFact[] = [];
-  for (const child of root.namedChildren) {
-    if (child.type === "export_statement") {
-      for (const exportedChild of child.namedChildren) {
-        facts.push(...declarationFunctionFacts(exportedChild));
-      }
-      continue;
-    }
-    facts.push(...declarationFunctionFacts(child));
-  }
-  return facts;
-}
-
-function severityScore(severity: SludgeSeverity): number {
-  if (severity === "high") return 3;
-  if (severity === "medium") return 2;
-  return 1;
-}
-
-function containsTypeTag(comment: string): boolean {
-  return comment.includes("@type ") || comment.includes("@type{") || comment.includes("@type\t");
-}
-
-function buildSummary(report: Omit<SludgeReport, "summary">): string {
-  if (report.scannedFiles === 0) {
-    return "No supported source files scanned.";
-  }
-  if (report.totalSignals === 0) {
-    return `No sludge signals found across ${String(report.scannedFiles)} files.`;
-  }
-  return `${String(report.totalSignals)} sludge signals across ${String(report.filesWithSignals)} of ${String(report.scannedFiles)} scanned files.`;
-}
-
-export function analyzeSludgeFile(filePath: string, source: string): SludgeFileReport | null {
-  if (detectLang(filePath) === null) return null;
-
-  const outline = extractOutlineForFile(filePath, source);
-  const parsed = parseStructuredTreeForFile(filePath, source);
-  if (outline === null || parsed === null) return null;
-
-  try {
-    let typedefCount = 0;
-    let typeCastCount = 0;
-    for (const child of parsed.root.children) {
-      walk(child, (node) => {
-        if (node.type !== "comment") return;
-        if (node.text.includes("@typedef")) typedefCount++;
-        if (containsTypeTag(node.text)) typeCastCount++;
-      });
-    }
-
-    const typeNames = collectTypeNames(outline.entries);
-    const classCount = countOutlineEntries(outline.entries, (entry) => entry.kind === "class");
-    const functionCount = countOutlineEntries(outline.entries, (entry) => entry.kind === "function");
-    const symbolCount = countOutlineEntries(outline.entries, () => true);
-    const functions = topLevelFunctionFacts(parsed.root);
-    const signals: SludgeSignal[] = [];
-
-    if (typedefCount > 0 && typedefCount >= classCount) {
-      const severity: SludgeSeverity = typedefCount >= 3 && classCount === 0 ? "high" : "medium";
-      signals.push({
-        kind: "phantom_shape",
-        severity,
-        message: "JSDoc typedefs outnumber class declarations.",
-        evidence: `${String(typedefCount)} typedefs, ${String(classCount)} classes`,
-      });
-    }
-
-    if (typeCastCount >= 3) {
-      signals.push({
-        kind: "cast_density",
-        severity: typeCastCount >= 6 ? "high" : "medium",
-        message: "Dense JSDoc type casts suggest the type system is being hand-held.",
-        evidence: `${String(typeCastCount)} @type comments`,
-      });
-    }
-
-    let homelessConstructorCount = 0;
-    let freeFunctionDataBehaviorCount = 0;
-    for (const fact of functions) {
-      if (startsWithConstructorPrefix(fact.name) && fact.returnsPlainObject) {
-        homelessConstructorCount++;
-        signals.push({
-          kind: "homeless_constructor",
-          severity: "medium",
-          message: "Factory-like free function returns a plain object instead of owning behavior on a type.",
-          line: fact.line,
-          symbol: fact.name,
-          evidence: "returns object literal",
-        });
-      }
-
-      if (fact.firstParameterType !== null && typeNames.has(fact.firstParameterType)) {
-        freeFunctionDataBehaviorCount++;
-        signals.push({
-          kind: "free_function_data_behavior",
-          severity: "low",
-          message: "Free function takes a project type as its first parameter.",
-          line: fact.line,
-          symbol: fact.name,
-          evidence: `first parameter type ${fact.firstParameterType}`,
-        });
-      }
-    }
-
-    if (symbolCount > 30) {
-      signals.push({
-        kind: "god_file",
-        severity: symbolCount > 60 ? "high" : "medium",
-        message: "Single file exposes a large number of structural symbols.",
-        evidence: `${String(symbolCount)} outline entries`,
-      });
-    }
-
-    const score = signals.reduce((sum, signal) => sum + severityScore(signal.severity), 0);
-    return {
-      path: filePath,
-      score,
-      metrics: {
-        typedefCount,
-        typeCastCount,
-        classCount,
-        functionCount,
-        symbolCount,
-        homelessConstructorCount,
-        freeFunctionDataBehaviorCount,
-      },
-      signals,
-    };
-  } finally {
-    parsed.delete();
-  }
-}
-
-export async function detectSludge(options: DetectSludgeOptions): Promise<SludgeReport> {
-  const args = ["ls-files"];
-  if (options.path !== undefined) {
-    args.push("--", options.path);
-  }
-
-  const result = await options.git.run({ cwd: options.cwd, args });
-  const candidatePaths = result.status === 0
-    ? result.stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0)
-    : [];
-
-  const supportedPaths = candidatePaths.filter((filePath) => detectLang(filePath) !== null);
-  const files: SludgeFileReport[] = [];
-  for (const filePath of supportedPaths) {
-    const source = await options.fs.readFile(options.resolvePath(filePath), "utf-8").catch(() => null);
-    if (source === null) continue;
-    const report = analyzeSludgeFile(filePath, source);
-    if (report !== null && report.signals.length > 0) {
-      files.push(report);
-    }
-  }
-
-  files.sort((left, right) => right.score - left.score || left.path.localeCompare(right.path));
-  const withoutSummary = {
-    scannedFiles: supportedPaths.length,
-    filesWithSignals: files.length,
-    totalSignals: files.reduce((sum, file) => sum + file.signals.length, 0),
-    score: files.reduce((sum, file) => sum + file.score, 0),
-    files,
-  };
-
-  return {
-    ...withoutSummary,
-    summary: buildSummary(withoutSummary),
-  };
-}

package/src/operations/state.ts

@@ -1,66 +0,0 @@
-import type { FileSystem } from "../ports/filesystem.js";
-
-const MAX_STATE_BYTES = 8192;
-export const STATE_FILENAME = "state.md";
-
-export class StateSaveResult {
-  readonly ok: boolean;
-  readonly reason?: string | undefined;
-
-  private constructor(ok: boolean, reason?: string) {
-    this.ok = ok;
-    this.reason = reason;
-  }
-
-  static success(): StateSaveResult {
-    return new StateSaveResult(true);
-  }
-
-  static rejected(reason: string): StateSaveResult {
-    return new StateSaveResult(false, reason);
-  }
-}
-
-export class StateLoadResult {
-  readonly content: string | null;
-
-  private constructor(content: string | null) {
-    this.content = content;
-  }
-
-  static found(content: string): StateLoadResult {
-    return new StateLoadResult(content);
-  }
-
-  static empty(): StateLoadResult {
-    return new StateLoadResult(null);
-  }
-}
-
-export async function stateSave(
-  content: string,
-  opts: { stateDir: string; statePath: string; fs: FileSystem },
-): Promise<StateSaveResult> {
-  const bytes = Buffer.byteLength(content, "utf-8");
-  if (bytes > MAX_STATE_BYTES) {
-    return StateSaveResult.rejected(
-      `State exceeds 8 KB limit (${String(bytes)} bytes)`,
-    );
-  }
-
-  await opts.fs.mkdir(opts.stateDir, { recursive: true });
-  await opts.fs.writeFile(opts.statePath, content, "utf-8");
-
-  return StateSaveResult.success();
-}
-
-export async function stateLoad(
-  opts: { statePath: string; fs: FileSystem },
-): Promise<StateLoadResult> {
-  try {
-    const content = await opts.fs.readFile(opts.statePath, "utf-8");
-    return StateLoadResult.found(content);
-  } catch {
-    return StateLoadResult.empty();
-  }
-}