@flyingrobots/graft 0.3.5 → 0.5.0

package/src/operations/file-outline.ts

@@ -1,4 +1,4 @@
-import { extractOutline } from "../parser/outline.js";
+import { extractOutlineForFile } from "../parser/outline.js";
 import type { OutlineEntry, JumpEntry } from "../parser/types.js";
 import type { FileSystem } from "../ports/filesystem.js";
 
@@ -8,6 +8,7 @@ export interface FileOutlineResult {
   outline: OutlineEntry[];
   jumpTable: JumpEntry[];
   partial?: boolean | undefined;
+  reason?: "UNSUPPORTED_LANGUAGE" | undefined;
   error?: string | undefined;
 }
 
@@ -27,7 +28,16 @@ export async function fileOutline(
     };
   }
 
-  const result = extractOutline(content);
+  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,

package/src/operations/graft-diff.ts

@@ -1,5 +1,5 @@
-import * as path from "node:path";
 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";
@@ -12,6 +12,14 @@ export interface FileDiff {
   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`);
@@ -27,31 +35,57 @@ 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 function graftDiff(opts: GraftDiffOptions): GraftDiffResult {
+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 = getChangedFiles({
+  let changedFiles = await getChangedFiles({
     cwd,
+    git: opts.git,
     base,
     head: opts.head,
   });
@@ -62,21 +96,19 @@ export function graftDiff(opts: GraftDiffOptions): GraftDiffResult {
   }
 
   const files: FileDiff[] = [];
+  const refused: GraftDiffRefusal[] = [];
 
   for (const filePath of changedFiles) {
-    const lang = detectLang(filePath);
-
     // Get content at base (null = file absent at ref)
-    const baseContent = getFileAtRef(base, filePath, cwd);
+    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 = getFileAtRef(opts.head, filePath, cwd);
+      headContent = await getFileAtRef(opts.head, filePath, { cwd, git: opts.git });
     } else {
-      const fullPath = path.join(cwd, filePath);
       try {
-        headContent = opts.fs.readFileSync(fullPath, "utf-8");
+        headContent = await opts.fs.readFile(opts.resolveWorkingTreePath(filePath), "utf-8");
       } catch {
         headContent = null;
       }
@@ -95,6 +127,15 @@ export function graftDiff(opts: GraftDiffOptions): GraftDiffResult {
       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();
@@ -113,5 +154,10 @@ export function graftDiff(opts: GraftDiffOptions): GraftDiffResult {
     files.push({ path: filePath, status, summary: buildSummary(filePath, status, diff), diff });
   }
 
-  return { base, head: headLabel, files };
+  return {
+    base,
+    head: headLabel,
+    files,
+    ...(refused.length > 0 ? { refused } : {}),
+  };
 }

package/src/operations/safe-read.ts

@@ -1,7 +1,7 @@
 import { evaluatePolicy } from "../policy/evaluate.js";
 import { ContentResult, RefusedResult } from "../policy/types.js";
 import type { SessionDepth } from "../policy/types.js";
-import { extractOutline } from "../parser/outline.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";
@@ -26,6 +26,8 @@ export interface SafeReadOptions {
   codec: JsonCodec;
   content?: string | undefined;
   intent?: string | undefined;
+  policyPath?: string | undefined;
+  graftignorePatterns?: string[] | undefined;
   sessionDepth?: SessionDepth | undefined;
   budgetRemaining?: number | undefined;
 }
@@ -58,8 +60,12 @@ export async function safeRead(
   const lines = content.split("\n").length;
 
   const policy = evaluatePolicy(
-    { path: filePath, lines, bytes },
-    { sessionDepth: options.sessionDepth, budgetRemaining: options.budgetRemaining },
+    { path: options.policyPath ?? filePath, lines, bytes },
+    {
+      graftignorePatterns: options.graftignorePatterns,
+      sessionDepth: options.sessionDepth,
+      budgetRemaining: options.budgetRemaining,
+    },
   );
 
   const base: SafeReadResult = {
@@ -83,7 +89,24 @@ export async function safeRead(
   }
 
   // projection === "outline"
-  const outlineResult = extractOutline(content);
+  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");
 

package/src/operations/state.ts

@@ -1,31 +1,28 @@
-import * as path from "node:path";
 import type { FileSystem } from "../ports/filesystem.js";
 
 const MAX_STATE_BYTES = 8192;
-const STATE_FILENAME = "state.md";
+export const STATE_FILENAME = "state.md";
 
 export async function stateSave(
   content: string,
-  opts: { graftDir: string; fs: FileSystem },
+  opts: { stateDir: string; statePath: string; fs: FileSystem },
 ): Promise<{ ok: boolean; reason?: string | undefined }> {
   const bytes = Buffer.byteLength(content, "utf-8");
   if (bytes > MAX_STATE_BYTES) {
     return { ok: false, reason: `State exceeds 8 KB limit (${String(bytes)} bytes)` };
   }
 
-  const filePath = path.join(opts.graftDir, STATE_FILENAME);
-  await opts.fs.mkdir(opts.graftDir, { recursive: true });
-  await opts.fs.writeFile(filePath, content, "utf-8");
+  await opts.fs.mkdir(opts.stateDir, { recursive: true });
+  await opts.fs.writeFile(opts.statePath, content, "utf-8");
 
   return { ok: true };
 }
 
 export async function stateLoad(
-  opts: { graftDir: string; fs: FileSystem },
+  opts: { statePath: string; fs: FileSystem },
 ): Promise<{ content: string | null }> {
-  const filePath = path.join(opts.graftDir, STATE_FILENAME);
   try {
-    const content = await opts.fs.readFile(filePath, "utf-8");
+    const content = await opts.fs.readFile(opts.statePath, "utf-8");
     return { content };
   } catch {
     return { content: null };

package/src/parser/lang.ts

@@ -1,12 +1,28 @@
 import * as path from "node:path";
 
+export type SupportedLang = "ts" | "js";
+export type SupportedStructuredFormat = SupportedLang | "md";
+
 /**
  * Detect the tree-sitter language from a file extension.
  * Returns null for unsupported file types.
  */
-export function detectLang(filePath: string): "ts" | "js" | null {
+export function detectLang(filePath: string): SupportedLang | null {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === ".ts" || ext === ".tsx" || ext === ".mts" || ext === ".cts") return "ts";
+  if (ext === ".js" || ext === ".jsx" || ext === ".mjs" || ext === ".cjs") return "js";
+  return null;
+}
+
+/**
+ * Detect the supported structured format for bounded read surfaces.
+ * Returns null for file types that still have no explicit extractor.
+ */
+export function detectStructuredFormat(filePath: string): SupportedStructuredFormat | null {
+  const lang = detectLang(filePath);
+  if (lang !== null) return lang;
+
   const ext = path.extname(filePath).toLowerCase();
-  if (ext === ".ts" || ext === ".tsx") return "ts";
-  if (ext === ".js" || ext === ".jsx") return "js";
+  if (ext === ".md") return "md";
   return null;
 }

package/src/parser/outline.ts

@@ -1,5 +1,7 @@
 import Parser from "web-tree-sitter";
 import { createRequire } from "node:module";
+import { detectStructuredFormat } from "./lang.js";
+import type { SupportedStructuredFormat } from "./lang.js";
 import { OutlineEntry, JumpEntry } from "./types.js";
 import type { OutlineResult } from "./types.js";
 
@@ -53,6 +55,17 @@ interface TSNode {
   childForFieldName(name: string): TSNode | null;
 }
 
+interface MarkdownHeading {
+  level: number;
+  name: string;
+  start: number;
+  end: number;
+}
+
+interface MarkdownHeadingNode extends MarkdownHeading {
+  children: MarkdownHeadingNode[];
+}
+
 // ---------------------------------------------------------------------------
 // Node kind mapping
 // ---------------------------------------------------------------------------
@@ -210,6 +223,166 @@ function buildJumpEntry(
   });
 }
 
+function buildMarkdownJumpEntry(heading: MarkdownHeading): JumpEntry {
+  return new JumpEntry({
+    symbol: heading.name,
+    kind: "heading",
+    start: heading.start,
+    end: heading.end,
+  });
+}
+
+function isFenceLine(line: string): { marker: "`" | "~"; length: number } | null {
+  const match = /^\s*([`~])\1{2,}.*$/.exec(line);
+  if (match === null) return null;
+
+  const marker = match[1];
+  if (marker !== "`" && marker !== "~") return null;
+  const markerRun = /^([`~]+)/.exec(match[0].trimStart());
+  if (markerRun === null) return null;
+  const run = markerRun[1];
+  if (run === undefined) return null;
+  return { marker, length: run.length };
+}
+
+function isFenceClose(line: string, marker: "`" | "~", length: number): boolean {
+  const pattern = marker === "`"
+    ? new RegExp(`^\\s*\`{${String(length)},}\\s*$`)
+    : new RegExp(`^\\s*~{${String(length)},}\\s*$`);
+  return pattern.test(line);
+}
+
+function parseAtxHeading(line: string, lineNumber: number): MarkdownHeading | null {
+  const match = /^\s{0,3}(#{1,6})[ \t]+(.+?)\s*#*\s*$/.exec(line);
+  if (match === null) return null;
+
+  const hashes = match[1];
+  const rawName = match[2]?.trim() ?? "";
+  if (hashes === undefined || rawName.length === 0) return null;
+
+  return {
+    level: hashes.length,
+    name: rawName,
+    start: lineNumber,
+    end: lineNumber,
+  };
+}
+
+function parseSetextHeading(
+  currentLine: string,
+  nextLine: string | undefined,
+  lineNumber: number,
+): MarkdownHeading | null {
+  if (nextLine === undefined) return null;
+  if (currentLine.trim().length === 0) return null;
+  if (parseAtxHeading(currentLine, lineNumber) !== null) return null;
+
+  if (/^\s{0,3}=+\s*$/.test(nextLine)) {
+    return { level: 1, name: currentLine.trim(), start: lineNumber, end: lineNumber + 1 };
+  }
+  if (/^\s{0,3}-+\s*$/.test(nextLine)) {
+    return { level: 2, name: currentLine.trim(), start: lineNumber, end: lineNumber + 1 };
+  }
+
+  return null;
+}
+
+function finalizeMarkdownRanges(headings: MarkdownHeading[], totalLines: number): void {
+  for (let i = 0; i < headings.length; i++) {
+    const current = headings[i];
+    if (current === undefined) continue;
+    let end = totalLines;
+    for (let j = i + 1; j < headings.length; j++) {
+      const next = headings[j];
+      if (next === undefined) continue;
+      if (next.level <= current.level) {
+        end = next.start - 1;
+        break;
+      }
+    }
+    current.end = end;
+  }
+}
+
+function buildMarkdownHierarchy(headings: readonly MarkdownHeading[]): MarkdownHeadingNode[] {
+  const roots: MarkdownHeadingNode[] = [];
+  const stack: MarkdownHeadingNode[] = [];
+
+  for (const heading of headings) {
+    const node: MarkdownHeadingNode = { ...heading, children: [] };
+    while (stack.length > 0) {
+      const last = stack[stack.length - 1];
+      if (last === undefined || last.level < node.level) break;
+      stack.pop();
+    }
+    const parent = stack[stack.length - 1];
+    if (parent === undefined) roots.push(node);
+    else parent.children.push(node);
+    stack.push(node);
+  }
+
+  return roots;
+}
+
+function toOutlineEntry(node: MarkdownHeadingNode): OutlineEntry {
+  return new OutlineEntry({
+    kind: "heading",
+    name: node.name,
+    exported: false,
+    ...(node.children.length > 0
+      ? { children: node.children.map((child) => toOutlineEntry(child)) }
+      : {}),
+  });
+}
+
+function extractMarkdownOutline(source: string): OutlineResult {
+  const lines = source.split("\n");
+  const headings: MarkdownHeading[] = [];
+  let inFence = false;
+  let activeFence: { marker: "`" | "~"; length: number } | null = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined) continue;
+    const lineNumber = i + 1;
+    const fence = isFenceLine(line);
+
+    if (inFence) {
+      if (activeFence !== null && isFenceClose(line, activeFence.marker, activeFence.length)) {
+        inFence = false;
+        activeFence = null;
+      }
+      continue;
+    }
+
+    if (fence !== null) {
+      inFence = true;
+      activeFence = fence;
+      continue;
+    }
+
+    const atx = parseAtxHeading(line, lineNumber);
+    if (atx !== null) {
+      headings.push(atx);
+      continue;
+    }
+
+    const setext = parseSetextHeading(line, lines[i + 1], lineNumber);
+    if (setext !== null) {
+      headings.push(setext);
+      i++;
+    }
+  }
+
+  finalizeMarkdownRanges(headings, lines.length);
+  const hierarchy = buildMarkdownHierarchy(headings);
+
+  return {
+    entries: hierarchy.map((node) => toOutlineEntry(node)),
+    jumpTable: headings.map((heading) => buildMarkdownJumpEntry(heading)),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Main extraction
 // ---------------------------------------------------------------------------
@@ -218,13 +391,17 @@ function buildJumpEntry(
  * Extract a structural outline from source code.
  *
  * @param source - The source code text.
- * @param lang - Language identifier: `"ts"` or `"js"`. Defaults to `"ts"`.
+ * @param lang - Structured format identifier. Defaults to `"ts"`.
  * @returns An {@link OutlineResult} with entries, jump table, and partial flag.
  */
 export function extractOutline(
   source: string,
-  lang: "ts" | "js" = "ts",
+  lang: SupportedStructuredFormat = "ts",
 ): OutlineResult {
+  if (lang === "md") {
+    return extractMarkdownOutline(source);
+  }
+
   const parser = new Parser();
   parser.setLanguage(lang === "ts" ? tsLang : jsLang);
 
@@ -325,3 +502,15 @@ export function extractOutline(
 
   return result;
 }
+
+export function extractOutlineForFile(
+  filePath: string,
+  source: string,
+): OutlineResult | null {
+  const lang = detectStructuredFormat(filePath);
+  if (lang === null) {
+    return null;
+  }
+
+  return extractOutline(source, lang);
+}

package/src/parser/types.ts

@@ -1,5 +1,13 @@
 /** The kind of a top-level or member declaration. */
-export type EntryKind = "function" | "class" | "method" | "interface" | "type" | "enum" | "export";
+export type EntryKind =
+  | "function"
+  | "class"
+  | "method"
+  | "interface"
+  | "type"
+  | "enum"
+  | "export"
+  | "heading";
 
 /** A single entry in a file outline. */
 export class OutlineEntry {

package/src/policy/types.ts

@@ -8,7 +8,8 @@ export type ReasonCode =
   | "BUILD_OUTPUT"
   | "SECRET"
   | "GRAFTIGNORE"
-  | "BUDGET_CAP";
+  | "BUDGET_CAP"
+  | "UNSUPPORTED_LANGUAGE";
 
 export type SessionDepth = "early" | "mid" | "late" | "unknown";
 
@@ -48,12 +49,12 @@ export class ContentResult implements PolicyResultBase {
 
 export class OutlineResult implements PolicyResultBase {
   readonly projection = "outline" as const;
-  readonly reason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP";
+  readonly reason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP" | "UNSUPPORTED_LANGUAGE";
   readonly thresholds: { readonly lines: number; readonly bytes: number };
   readonly actual: { readonly lines: number; readonly bytes: number };
   readonly sessionDepth?: SessionDepth | undefined;
 
-  constructor(opts: { reason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP"; thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: SessionDepth | undefined }) {
+  constructor(opts: { reason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP" | "UNSUPPORTED_LANGUAGE"; thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: SessionDepth | undefined }) {
     this.reason = opts.reason;
     this.thresholds = Object.freeze({ ...opts.thresholds });
     this.actual = Object.freeze({ ...opts.actual });

package/src/ports/filesystem.ts

@@ -9,6 +9,7 @@
 export interface FileSystem {
   readFile(path: string, encoding: "utf-8"): Promise<string>;
   readFile(path: string): Promise<Buffer>;
+  readdir(path: string): Promise<string[]>;
   writeFile(path: string, data: string, encoding: "utf-8"): Promise<void>;
   appendFile(path: string, data: string, encoding: "utf-8"): Promise<void>;
   mkdir(path: string, options: { recursive: true }): Promise<void>;

package/src/ports/git.ts

@@ -0,0 +1,16 @@
+// ---------------------------------------------------------------------------
+// GitClient port — hexagonal boundary for git command execution
+// ---------------------------------------------------------------------------
+
+import type { ProcessRunResult } from "./process-runner.js";
+
+export interface GitRunRequest {
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly timeoutMs?: number;
+  readonly maxBufferBytes?: number;
+}
+
+export interface GitClient {
+  run(request: GitRunRequest): Promise<ProcessRunResult>;
+}

package/src/ports/process-runner.ts

@@ -0,0 +1,22 @@
+// ---------------------------------------------------------------------------
+// ProcessRunner port — hexagonal boundary for command execution
+// ---------------------------------------------------------------------------
+
+export interface ProcessRunRequest {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly timeoutMs?: number;
+  readonly maxBufferBytes?: number;
+}
+
+export interface ProcessRunResult {
+  readonly status: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly error?: Error;
+}
+
+export interface ProcessRunner {
+  run(request: ProcessRunRequest): ProcessRunResult;
+}