@flyingrobots/graft 0.7.0 → 0.8.0

package/src/operations/projection-safety.ts

@@ -1,111 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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/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 } : {}),
-  };
-}

package/src/operations/repo-workspace.ts

@@ -1,339 +0,0 @@
-import { safeRead, type SafeReadResult } from "./safe-read.js";
-import { fileOutline, type FileOutlineResult } from "./file-outline.js";
-import { readRange, type ReadRangeResult } from "./read-range.js";
-import { CachedFile } from "./cached-file.js";
-import { ObservationCache, hashContent } from "./observation-cache.js";
-import { GovernorTracker } from "../session/tracker.js";
-import { diffOutlines, type OutlineDiff } from "../parser/diff.js";
-import { extractOutlineForFile } from "../parser/outline.js";
-import type { JumpEntry, OutlineEntry } from "../parser/types.js";
-import { evaluatePolicy } from "../policy/evaluate.js";
-import { RefusedResult } from "../policy/types.js";
-import { loadGraftignore } from "../policy/graftignore.js";
-import type { FileSystem } from "../ports/filesystem.js";
-import type { JsonCodec } from "../ports/codec.js";
-
-export interface RepoWorkspaceRefusedResult {
-  readonly path: string;
-  readonly projection: "refused";
-  readonly reason: string;
-  readonly reasonDetail: string;
-  readonly next: string[];
-  readonly actual: { readonly lines: number; readonly bytes: number };
-}
-
-export interface RepoWorkspaceSafeReadCacheHitResult {
-  readonly path: string;
-  readonly projection: "cache_hit";
-  readonly reason: "REREAD_UNCHANGED";
-  readonly outline: readonly OutlineEntry[];
-  readonly jumpTable: readonly JumpEntry[];
-  readonly actual: Readonly<{ lines: number; bytes: number }>;
-  readonly readCount: number;
-  readonly estimatedBytesAvoided: number;
-  readonly lastReadAt: string;
-}
-
-export interface RepoWorkspaceSafeReadDiffResult {
-  readonly path: string;
-  readonly projection: "diff";
-  readonly reason: "CHANGED_SINCE_LAST_READ";
-  readonly diff: OutlineDiff;
-  readonly outline: readonly OutlineEntry[];
-  readonly jumpTable: readonly JumpEntry[];
-  readonly actual: Readonly<{ lines: number; bytes: number }>;
-  readonly readCount: number;
-  readonly lastReadAt: string;
-}
-
-export type RepoWorkspaceSafeReadResult =
-  | SafeReadResult
-  | RepoWorkspaceSafeReadCacheHitResult
-  | RepoWorkspaceSafeReadDiffResult;
-
-export type RepoWorkspaceFileOutlineResult = FileOutlineResult | RepoWorkspaceRefusedResult;
-
-export type RepoWorkspaceReadRangeResult = ReadRangeResult | RepoWorkspaceRefusedResult;
-
-export type RepoWorkspaceChangedSinceResult =
-  | { readonly status: "file_not_found" }
-  | { readonly status: "refused"; readonly reason: string }
-  | { readonly status: "unsupported"; readonly reason: "UNSUPPORTED_LANGUAGE" }
-  | { readonly status: "unchanged" }
-  | { readonly status: "no_previous_observation" }
-  | { readonly diff: OutlineDiff; readonly consumed: boolean };
-
-export interface RepoWorkspaceOptions {
-  readonly projectRoot: string;
-  readonly fs: FileSystem;
-  readonly codec: JsonCodec;
-  readonly graftignorePatterns?: readonly string[] | undefined;
-  readonly resolvePath?: ((input: string) => string) | undefined;
-  readonly toPolicyPath?: ((resolvedPath: string) => string) | undefined;
-  readonly governor?: GovernorTracker | undefined;
-  readonly cache?: ObservationCache | undefined;
-}
-
-async function loadWorkspaceGraftignore(
-  fs: Pick<FileSystem, "readFile">,
-  projectRoot: string,
-): Promise<string[]> {
-  try {
-    return loadGraftignore(await fs.readFile(`${projectRoot}/.graftignore`, "utf-8"));
-  } catch {
-    return [];
-  }
-}
-
-export class RepoWorkspace {
-  private readonly resolveWorkspacePath: (input: string) => string;
-  private readonly policyPathForWorkspaceFile: (resolvedPath: string) => string;
-  readonly projectRoot: string;
-  readonly fs: FileSystem;
-  readonly codec: JsonCodec;
-  readonly graftignorePatterns: readonly string[];
-  readonly governor: GovernorTracker;
-  readonly cache: ObservationCache;
-
-  constructor(options: RepoWorkspaceOptions) {
-    this.projectRoot = options.projectRoot;
-    this.fs = options.fs;
-    this.codec = options.codec;
-    this.graftignorePatterns = options.graftignorePatterns ?? [];
-    this.governor = options.governor ?? new GovernorTracker();
-    this.cache = options.cache ?? new ObservationCache();
-    this.resolveWorkspacePath = options.resolvePath ?? ((input) => input);
-    this.policyPathForWorkspaceFile = options.toPolicyPath ?? ((resolvedPath) => resolvedPath);
-  }
-
-  static async loadGraftignorePatterns(
-    fs: Pick<FileSystem, "readFile">,
-    projectRoot: string,
-  ): Promise<string[]> {
-    return loadWorkspaceGraftignore(fs, projectRoot);
-  }
-
-  setBudget(bytes: number): void {
-    this.governor.setBudget(bytes);
-  }
-
-  getBudget(): { total: number; consumed: number; remaining: number; fraction: number } | null {
-    return this.governor.getBudget();
-  }
-
-  private evaluateRefusal(
-    filePath: string,
-    actual: { readonly lines: number; readonly bytes: number },
-  ): RepoWorkspaceRefusedResult | null {
-    const policy = evaluatePolicy(
-      {
-        path: this.policyPathForWorkspaceFile(filePath),
-        lines: actual.lines,
-        bytes: actual.bytes,
-      },
-      {
-        graftignorePatterns: this.graftignorePatterns.length > 0 ? [...this.graftignorePatterns] : undefined,
-        sessionDepth: this.governor.getGovernorDepth(),
-        budgetRemaining: this.governor.getBudget()?.remaining,
-      },
-    );
-    if (!(policy instanceof RefusedResult)) {
-      return null;
-    }
-    return {
-      path: filePath,
-      projection: "refused",
-      reason: policy.reason,
-      reasonDetail: policy.reasonDetail,
-      next: [...policy.next],
-      actual,
-    };
-  }
-
-  async safeRead(args: { readonly path: string; readonly intent?: string | undefined }): Promise<RepoWorkspaceSafeReadResult> {
-    const filePath = this.resolveWorkspacePath(args.path);
-
-    let snapshot: CachedFile | null = null;
-    try {
-      snapshot = new CachedFile(filePath, await this.fs.readFile(filePath, "utf-8"));
-    } catch {
-      // Let safeRead produce the not-found error shape.
-    }
-
-    if (snapshot?.supportsOutline === true) {
-      const cacheResult = this.cache.check(filePath, snapshot.rawContent);
-      if (cacheResult.hit) {
-        cacheResult.obs.touch(this.cache.now());
-        return {
-          path: filePath,
-          projection: "cache_hit",
-          reason: "REREAD_UNCHANGED",
-          outline: cacheResult.obs.outline,
-          jumpTable: cacheResult.obs.jumpTable,
-          actual: cacheResult.obs.actual,
-          readCount: cacheResult.obs.readCount,
-          estimatedBytesAvoided: snapshot.actual.bytes,
-          lastReadAt: cacheResult.obs.lastReadAt,
-        };
-      }
-
-      if (cacheResult.stale !== null) {
-        const refusal = this.evaluateRefusal(filePath, snapshot.actual);
-        if (refusal !== null) {
-          return refusal;
-        }
-        this.cache.record(filePath, snapshot.hash, snapshot.outline, snapshot.jumpTable, snapshot.actual);
-        const updated = this.cache.get(filePath);
-        return {
-          path: filePath,
-          projection: "diff",
-          reason: "CHANGED_SINCE_LAST_READ",
-          diff: diffOutlines(cacheResult.stale.outline, snapshot.outline),
-          outline: snapshot.outline,
-          jumpTable: snapshot.jumpTable,
-          actual: snapshot.actual,
-          readCount: cacheResult.stale.readCount + 1,
-          lastReadAt: updated?.lastReadAt ?? this.cache.now(),
-        };
-      }
-    }
-
-    const result = await safeRead(filePath, {
-      fs: this.fs,
-      codec: this.codec,
-      content: snapshot?.rawContent,
-      intent: args.intent,
-      policyPath: this.policyPathForWorkspaceFile(filePath),
-      graftignorePatterns: [...this.graftignorePatterns],
-      sessionDepth: this.governor.getGovernorDepth(),
-      budgetRemaining: this.governor.getBudget()?.remaining,
-    });
-
-    if (
-      snapshot !== null &&
-      snapshot.supportsOutline &&
-      result.actual !== undefined &&
-      (result.projection === "content" || result.projection === "outline") &&
-      result.reason !== "UNSUPPORTED_LANGUAGE"
-    ) {
-      this.cache.record(filePath, snapshot.hash, snapshot.outline, snapshot.jumpTable, result.actual);
-    }
-
-    return result;
-  }
-
-  async fileOutline(args: { readonly path: string }): Promise<RepoWorkspaceFileOutlineResult> {
-    const filePath = this.resolveWorkspacePath(args.path);
-
-    let rawContent: string | null = null;
-    try {
-      rawContent = await this.fs.readFile(filePath, "utf-8");
-    } catch {
-      // Let fileOutline shape the not-found result.
-    }
-
-    if (rawContent !== null) {
-      const actual = {
-        lines: rawContent.split("\n").length,
-        bytes: Buffer.byteLength(rawContent),
-      };
-      const refusal = this.evaluateRefusal(filePath, actual);
-      if (refusal !== null) {
-        return refusal;
-      }
-      const cacheResult = this.cache.check(filePath, rawContent);
-      if (cacheResult.hit) {
-        cacheResult.obs.touch(this.cache.now());
-        return {
-          path: filePath,
-          outline: [...cacheResult.obs.outline],
-          jumpTable: [...cacheResult.obs.jumpTable],
-          cacheHit: true,
-        };
-      }
-    }
-
-    const result = await fileOutline(filePath, { fs: this.fs });
-    if (rawContent !== null && result.reason !== "UNSUPPORTED_LANGUAGE") {
-      this.cache.record(
-        filePath,
-        hashContent(rawContent),
-        result.outline,
-        result.jumpTable,
-        { lines: rawContent.split("\n").length, bytes: Buffer.byteLength(rawContent) },
-      );
-    }
-    return result;
-  }
-
-  async readRange(args: { readonly path: string; readonly start: number; readonly end: number }): Promise<RepoWorkspaceReadRangeResult> {
-    const filePath = this.resolveWorkspacePath(args.path);
-    let rawContent: string | null = null;
-    try {
-      rawContent = await this.fs.readFile(filePath, "utf-8");
-    } catch {
-      // Let readRange shape the not-found result.
-    }
-    if (rawContent !== null) {
-      const refusal = this.evaluateRefusal(filePath, {
-        lines: rawContent.split("\n").length,
-        bytes: Buffer.byteLength(rawContent),
-      });
-      if (refusal !== null) {
-        return refusal;
-      }
-    }
-    return readRange(filePath, args.start, args.end, { fs: this.fs });
-  }
-
-  async changedSince(args: { readonly path: string; readonly consume?: boolean | undefined }): Promise<RepoWorkspaceChangedSinceResult> {
-    const filePath = this.resolveWorkspacePath(args.path);
-    const consume = args.consume === true;
-
-    let rawContent: string;
-    try {
-      rawContent = await this.fs.readFile(filePath, "utf-8");
-    } catch {
-      return { status: "file_not_found" };
-    }
-
-    const actual = {
-      lines: rawContent.split("\n").length,
-      bytes: Buffer.byteLength(rawContent),
-    };
-    const refusal = this.evaluateRefusal(filePath, actual);
-    if (refusal !== null) {
-      return { status: "refused", reason: refusal.reason };
-    }
-
-    const newOutlineResult = extractOutlineForFile(filePath, rawContent);
-    if (newOutlineResult === null) {
-      return {
-        status: "unsupported",
-        reason: "UNSUPPORTED_LANGUAGE",
-      };
-    }
-
-    const cacheResult = this.cache.check(filePath, rawContent);
-    if (cacheResult.hit) {
-      return { status: "unchanged" };
-    }
-    if (cacheResult.stale === null) {
-      return { status: "no_previous_observation" };
-    }
-
-    const diff = diffOutlines(cacheResult.stale.outline, newOutlineResult.entries);
-
-    if (consume) {
-      this.cache.record(
-        filePath,
-        hashContent(rawContent),
-        newOutlineResult.entries,
-        newOutlineResult.jumpTable ?? [],
-        actual,
-      );
-    }
-
-    return { diff, consumed: consume };
-  }
-}

package/src/operations/result-dto.ts

@@ -1,23 +0,0 @@
-// ---------------------------------------------------------------------------
-// Result DTO — converts runtime result objects to JSON-serializable records
-// ---------------------------------------------------------------------------
-
-import type { JsonObject } from "../contracts/json-object.js";
-
-/**
- * Convert any result object with known fields into a plain JsonObject
- * suitable for ctx.respond(). Strips class identity, prototype chain,
- * and index signatures — the result is a clean { ...fields } record.
- *
- * Skips undefined values to keep the serialized output compact.
- */
-export function toJsonObject(result: object): JsonObject {
-  const obj: JsonObject = {};
-  const source = result as Record<string, unknown>;
-  for (const key of Object.keys(source)) {
-    if (source[key] !== undefined) {
-      obj[key] = source[key];
-    }
-  }
-  return obj;
-}

package/src/operations/safe-read.ts

@@ -1,118 +0,0 @@
-import { evaluatePolicy } from "../policy/evaluate.js";
-import { ContentResult, RefusedResult } from "../policy/types.js";
-import type { GovernorDepth } from "../policy/types.js";
-import { extractOutlineForFile } from "../parser/outline.js";
-import type { OutlineEntry, JumpEntry } from "../parser/types.js";
-import type { FileSystem } from "../ports/filesystem.js";
-import type { JsonCodec } from "../ports/codec.js";
-
-export interface SafeReadResult {
-  path: string;
-  projection: "content" | "outline" | "refused" | "error";
-  reason: string;
-  content?: string | undefined;
-  outline?: OutlineEntry[] | undefined;
-  jumpTable?: JumpEntry[] | undefined;
-  estimatedBytesAvoided?: number | undefined;
-  next?: string[] | undefined;
-  actual?: { lines: number; bytes: number } | undefined;
-  thresholds?: { lines: number; bytes: number } | undefined;
-  sessionDepth?: GovernorDepth | undefined;
-}
-
-export interface SafeReadOptions {
-  fs: FileSystem;
-  codec: JsonCodec;
-  content?: string | undefined;
-  intent?: string | undefined;
-  policyPath?: string | undefined;
-  graftignorePatterns?: string[] | undefined;
-  sessionDepth?: GovernorDepth | undefined;
-  budgetRemaining?: number | undefined;
-}
-
-export async function safeRead(
-  filePath: string,
-  options: SafeReadOptions,
-): Promise<SafeReadResult> {
-  let content: string;
-  let bytes: number;
-
-  if (options.content !== undefined) {
-    content = options.content;
-    bytes = Buffer.byteLength(content, "utf-8");
-  } else {
-    let raw: Buffer;
-    try {
-      raw = await options.fs.readFile(filePath);
-    } catch {
-      return {
-        path: filePath,
-        projection: "error",
-        reason: "NOT_FOUND",
-      };
-    }
-    content = raw.toString("utf-8");
-    bytes = raw.byteLength;
-  }
-
-  const lines = content.split("\n").length;
-
-  const policy = evaluatePolicy(
-    { path: options.policyPath ?? filePath, lines, bytes },
-    {
-      graftignorePatterns: options.graftignorePatterns,
-      sessionDepth: options.sessionDepth,
-      budgetRemaining: options.budgetRemaining,
-    },
-  );
-
-  const base: SafeReadResult = {
-    path: filePath,
-    projection: policy.projection,
-    reason: policy.reason,
-    actual: policy.actual,
-    thresholds: policy.thresholds,
-    ...(policy.sessionDepth !== undefined ? { sessionDepth: policy.sessionDepth } : {}),
-  };
-
-  if (policy instanceof ContentResult) {
-    return { ...base, content };
-  }
-
-  if (policy instanceof RefusedResult) {
-    return {
-      ...base,
-      next: [...policy.next],
-    };
-  }
-
-  // projection === "outline"
-  const outlineResult = extractOutlineForFile(filePath, content);
-  if (outlineResult === null) {
-    const emptyOutlineJson = options.codec.encode({ entries: [], jumpTable: [] });
-    const estimatedBytesAvoided = bytes - Buffer.byteLength(emptyOutlineJson, "utf-8");
-
-    return {
-      ...base,
-      reason: "UNSUPPORTED_LANGUAGE",
-      outline: [],
-      jumpTable: [],
-      estimatedBytesAvoided: estimatedBytesAvoided > 0 ? estimatedBytesAvoided : 0,
-      next: [
-        "No parser-backed outline is available for this file type.",
-        "Use read_range for targeted reads if you know the section you need.",
-      ],
-    };
-  }
-
-  const outlineJson = options.codec.encode(outlineResult);
-  const estimatedBytesAvoided = bytes - Buffer.byteLength(outlineJson, "utf-8");
-
-  return {
-    ...base,
-    outline: outlineResult.entries,
-    jumpTable: outlineResult.jumpTable,
-    estimatedBytesAvoided: estimatedBytesAvoided > 0 ? estimatedBytesAvoided : 0,
-  };
-}