@flyingrobots/graft 0.6.1 → 0.7.1

package/src/policy/evaluate.ts

@@ -1,178 +0,0 @@
-import picomatch from "picomatch";
-import type { PolicyInput, PolicyOptions, ReasonCode, GovernorDepth } from "./types.js";
-import { ContentResult, OutlineResult, RefusedResult } from "./types.js";
-import type { PolicyResult } from "./types.js";
-
-export const STATIC_THRESHOLDS = { lines: 150, bytes: 12288 } as const;
-
-const SESSION_BYTE_CAPS: Record<string, number> = {
-  early: 20480,
-  mid: 10240,
-  late: 4096,
-};
-
-const BINARY_EXTENSIONS = new Set([
-  ".png", ".jpg", ".jpeg", ".gif", ".pdf", ".zip",
-  ".wasm", ".bin", ".sqlite", ".mp4", ".mov", ".ico",
-]);
-
-const LOCKFILE_NAMES = new Set([
-  "package-lock.json", "pnpm-lock.yaml", "yarn.lock",
-  "Gemfile.lock", "poetry.lock", "Cargo.lock",
-  "composer.lock", "Pipfile.lock",
-]);
-
-const BUILD_OUTPUT_PREFIXES = ["dist/", "build/", ".next/", "out/", "target/"];
-
-const SECRET_PATTERNS: ((name: string) => boolean)[] = [
-  (n) => n === ".env" || (n.startsWith(".env.") && !n.endsWith(".example")),
-  (n) => n.endsWith(".pem"),
-  (n) => n.endsWith(".key"),
-  (n) => n.startsWith("credentials."),
-];
-
-function basename(path: string): string {
-  const i = path.lastIndexOf("/");
-  return i === -1 ? path : path.slice(i + 1);
-}
-
-function extname(path: string): string {
-  const name = basename(path);
-  const i = name.lastIndexOf(".");
-  return i <= 0 ? "" : name.slice(i);
-}
-
-function checkBan(path: string): { reason: ReasonCode; reasonDetail: string; next: string[] } | undefined {
-  const name = basename(path);
-  const ext = extname(path).toLowerCase();
-
-  if (BINARY_EXTENSIONS.has(ext)) {
-    return {
-      reason: "BINARY",
-      reasonDetail: `Binary file (${ext}) cannot be usefully read`,
-      next: ["Use file_outline to see metadata", "Check for a text alternative"],
-    };
-  }
-
-  if (LOCKFILE_NAMES.has(name)) {
-    return {
-      reason: "LOCKFILE",
-      reasonDetail: `Lockfile ${name} is machine-generated and not useful to read`,
-      next: ["Read package.json for dependency info instead"],
-    };
-  }
-
-  if (name.endsWith(".min.js") || name.endsWith(".min.css")) {
-    return {
-      reason: "MINIFIED",
-      reasonDetail: `Minified file ${name} is not human-readable`,
-      next: ["Look for the unminified source"],
-    };
-  }
-
-  for (const prefix of BUILD_OUTPUT_PREFIXES) {
-    if (path.includes("/" + prefix) || path.startsWith(prefix)) {
-      return {
-        reason: "BUILD_OUTPUT",
-        reasonDetail: `Build output path ${prefix} contains generated files`,
-        next: ["Try reading src/ instead of dist/"],
-      };
-    }
-  }
-
-  for (const check of SECRET_PATTERNS) {
-    if (check(name)) {
-      return {
-        reason: "SECRET",
-        reasonDetail: `${name} may contain secrets and should not be read`,
-        next: ["Check for a .example or template version"],
-      };
-    }
-  }
-
-  return undefined;
-}
-
-export function evaluatePolicy(input: PolicyInput, options?: PolicyOptions): PolicyResult {
-  const { path, lines, bytes } = input;
-  const actual = { lines, bytes };
-  const thresholds = { ...STATIC_THRESHOLDS };
-  const sessionDepth: GovernorDepth | undefined = options?.sessionDepth;
-
-  // 1. Bans first
-  const ban = checkBan(path);
-  if (ban !== undefined) {
-    return new RefusedResult({
-      reason: ban.reason,
-      reasonDetail: ban.reasonDetail,
-      next: ban.next,
-      thresholds,
-      actual,
-      ...(sessionDepth !== undefined ? { sessionDepth } : {}),
-    });
-  }
-
-  // 2. Graftignore
-  const patterns = options?.graftignorePatterns;
-  if (patterns !== undefined && patterns.length > 0) {
-    const isMatch = picomatch(patterns);
-    if (isMatch(path)) {
-      return new RefusedResult({
-        reason: "GRAFTIGNORE",
-        reasonDetail: "File matches .graftignore pattern",
-        next: ["Check .graftignore if this file should be readable"],
-        thresholds,
-        actual,
-        ...(sessionDepth !== undefined ? { sessionDepth } : {}),
-      });
-    }
-  }
-
-  // 3. Determine effective byte cap
-  // When session depth is known (not "unknown"), the session cap replaces the static byte threshold.
-  // Static line threshold always applies.
-  const hasSessionCap = sessionDepth !== undefined && sessionDepth !== "unknown";
-  let effectiveByteCap = hasSessionCap
-    ? SESSION_BYTE_CAPS[sessionDepth] ?? STATIC_THRESHOLDS.bytes
-    : STATIC_THRESHOLDS.bytes;
-
-  // 4. Budget cap — no single read should exceed 5% of remaining budget
-  const MAX_READ_FRACTION = 0.05;
-  const budgetRemaining = options?.budgetRemaining;
-  const hasBudgetCap = budgetRemaining !== undefined && budgetRemaining >= 0;
-  let budgetTriggered = false;
-  if (hasBudgetCap) {
-    const budgetCap = Math.floor(budgetRemaining * MAX_READ_FRACTION);
-    if (budgetCap < effectiveByteCap) {
-      effectiveByteCap = budgetCap;
-      budgetTriggered = true;
-    }
-  }
-
-  const exceedsLines = lines > STATIC_THRESHOLDS.lines;
-  const exceedsBytes = bytes > effectiveByteCap;
-
-  if (!exceedsLines && !exceedsBytes) {
-    return new ContentResult({
-      thresholds,
-      actual,
-      ...(sessionDepth !== undefined ? { sessionDepth } : {}),
-    });
-  }
-
-  // Determine reason: BUDGET_CAP > SESSION_CAP > OUTLINE
-  const finalReason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP" = exceedsLines && !exceedsBytes
-    ? "OUTLINE"
-    : exceedsBytes && budgetTriggered
-      ? "BUDGET_CAP"
-      : exceedsBytes && hasSessionCap
-        ? "SESSION_CAP"
-        : "OUTLINE";
-
-  return new OutlineResult({
-    reason: finalReason,
-    thresholds,
-    actual,
-    ...(sessionDepth !== undefined ? { sessionDepth } : {}),
-  });
-}

package/src/policy/graftignore.ts

@@ -1,6 +0,0 @@
-export function loadGraftignore(content: string): string[] {
-  return content
-    .split("\n")
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0 && !line.startsWith("#"));
-}

package/src/policy/types.ts

@@ -1,87 +0,0 @@
-export type ReasonCode =
-  | "CONTENT"
-  | "OUTLINE"
-  | "SESSION_CAP"
-  | "BINARY"
-  | "LOCKFILE"
-  | "MINIFIED"
-  | "BUILD_OUTPUT"
-  | "SECRET"
-  | "GRAFTIGNORE"
-  | "BUDGET_CAP"
-  | "UNSUPPORTED_LANGUAGE";
-
-export type GovernorDepth = "early" | "mid" | "late" | "unknown";
-
-export interface PolicyInput {
-  path: string;
-  lines: number;
-  bytes: number;
-}
-
-export interface PolicyOptions {
-  graftignorePatterns?: string[] | undefined;
-  sessionDepth?: GovernorDepth | undefined;
-  budgetRemaining?: number | undefined;
-}
-
-// Shared fields for all results
-interface PolicyResultBase {
-  readonly thresholds: { readonly lines: number; readonly bytes: number };
-  readonly actual: { readonly lines: number; readonly bytes: number };
-  readonly sessionDepth?: GovernorDepth | undefined;
-}
-
-export class ContentResult implements PolicyResultBase {
-  readonly projection = "content" as const;
-  readonly reason = "CONTENT" as const;
-  readonly thresholds: { readonly lines: number; readonly bytes: number };
-  readonly actual: { readonly lines: number; readonly bytes: number };
-  readonly sessionDepth?: GovernorDepth | undefined;
-
-  constructor(opts: { thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: GovernorDepth | undefined }) {
-    this.thresholds = Object.freeze({ ...opts.thresholds });
-    this.actual = Object.freeze({ ...opts.actual });
-    if (opts.sessionDepth !== undefined) this.sessionDepth = opts.sessionDepth;
-    Object.freeze(this);
-  }
-}
-
-export class OutlineResult implements PolicyResultBase {
-  readonly projection = "outline" as const;
-  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?: GovernorDepth | undefined;
-
-  constructor(opts: { reason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP" | "UNSUPPORTED_LANGUAGE"; thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: GovernorDepth | undefined }) {
-    this.reason = opts.reason;
-    this.thresholds = Object.freeze({ ...opts.thresholds });
-    this.actual = Object.freeze({ ...opts.actual });
-    if (opts.sessionDepth !== undefined) this.sessionDepth = opts.sessionDepth;
-    Object.freeze(this);
-  }
-}
-
-export class RefusedResult implements PolicyResultBase {
-  readonly projection = "refused" as const;
-  readonly reason: ReasonCode;
-  readonly reasonDetail: string;
-  readonly next: readonly string[];
-  readonly thresholds: { readonly lines: number; readonly bytes: number };
-  readonly actual: { readonly lines: number; readonly bytes: number };
-  readonly sessionDepth?: GovernorDepth | undefined;
-
-  constructor(opts: { reason: ReasonCode; reasonDetail: string; next: string[]; thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: GovernorDepth | undefined }) {
-    this.reason = opts.reason;
-    this.reasonDetail = opts.reasonDetail;
-    this.next = Object.freeze([...opts.next]);
-    this.thresholds = Object.freeze({ ...opts.thresholds });
-    this.actual = Object.freeze({ ...opts.actual });
-    if (opts.sessionDepth !== undefined) this.sessionDepth = opts.sessionDepth;
-    Object.freeze(this);
-  }
-}
-
-// Union type for callers that need the general type
-export type PolicyResult = ContentResult | OutlineResult | RefusedResult;

package/src/ports/codec.ts

@@ -1,13 +0,0 @@
-// ---------------------------------------------------------------------------
-// JsonCodec port — hexagonal boundary for JSON serialization
-// ---------------------------------------------------------------------------
-
-/**
- * Portable JSON codec interface. Core logic imports this port, not
- * JSON.stringify/JSON.parse directly. Implementations control key
- * ordering, whitespace, and determinism.
- */
-export interface JsonCodec {
-  encode(value: unknown): string;
-  decode(data: string): unknown;
-}

package/src/ports/filesystem.ts

@@ -1,18 +0,0 @@
-// ---------------------------------------------------------------------------
-// FileSystem port — hexagonal boundary for file I/O
-// ---------------------------------------------------------------------------
-
-/**
- * Portable filesystem interface. Core logic imports this port, not node:fs.
- * Node adapter implements it; tests can substitute a mock.
- */
-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>;
-  stat(path: string): Promise<{ size: number }>;
-  readFileSync(path: string, encoding: "utf-8"): string;
-}

package/src/ports/git.ts

@@ -1,16 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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/guards.ts

@@ -1,68 +0,0 @@
-// ---------------------------------------------------------------------------
-// Port runtime guards — construction-time validation for port adapters
-// ---------------------------------------------------------------------------
-
-import type { FileSystem } from "./filesystem.js";
-import type { JsonCodec } from "./codec.js";
-
-const FILESYSTEM_METHODS = [
-  "readFile",
-  "readdir",
-  "writeFile",
-  "appendFile",
-  "mkdir",
-  "stat",
-  "readFileSync",
-] as const;
-
-const CODEC_METHODS = ["encode", "decode"] as const;
-
-function assertMethodsPresent(
-  portName: string,
-  impl: Record<string, unknown>,
-  methods: readonly string[],
-): void {
-  for (const method of methods) {
-    if (typeof impl[method] !== "function") {
-      throw new TypeError(
-        `${portName} adapter missing method: ${method} (got ${typeof impl[method]})`,
-      );
-    }
-  }
-}
-
-/**
- * Validate that an object satisfies the FileSystem port contract at
- * runtime. Call this at adapter construction boundaries to catch
- * broken mocks and incomplete implementations early.
- */
-export function assertFileSystem(impl: unknown): asserts impl is FileSystem {
-  if (impl === null || typeof impl !== "object") {
-    throw new TypeError(
-      `FileSystem adapter must be an object (got ${impl === null ? "null" : typeof impl})`,
-    );
-  }
-  assertMethodsPresent(
-    "FileSystem",
-    impl as Record<string, unknown>,
-    FILESYSTEM_METHODS,
-  );
-}
-
-/**
- * Validate that an object satisfies the JsonCodec port contract at
- * runtime. Call this at adapter construction boundaries to catch
- * broken mocks and incomplete implementations early.
- */
-export function assertJsonCodec(impl: unknown): asserts impl is JsonCodec {
-  if (impl === null || typeof impl !== "object") {
-    throw new TypeError(
-      `JsonCodec adapter must be an object (got ${impl === null ? "null" : typeof impl})`,
-    );
-  }
-  assertMethodsPresent(
-    "JsonCodec",
-    impl as Record<string, unknown>,
-    CODEC_METHODS,
-  );
-}

package/src/ports/process-runner.ts

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

package/src/ports/warp.ts

@@ -1,55 +0,0 @@
-// ---------------------------------------------------------------------------
-// WARP port — hexagonal boundary for graph reads and writes
-// ---------------------------------------------------------------------------
-
-export interface WarpObserverLens {
-  readonly match: string | readonly string[];
-  readonly expose?: readonly string[] | undefined;
-  readonly redact?: readonly string[] | undefined;
-}
-
-export interface WarpObserverOptions {
-  readonly source?: {
-    readonly kind: "live";
-    readonly ceiling: number | null;
-  } | undefined;
-}
-
-export interface WarpEdge {
-  readonly from: string;
-  readonly to: string;
-  readonly label: string;
-}
-
-export interface WarpObserver {
-  getNodes(): Promise<string[]>;
-  getNodeProps(nodeId: string): Promise<Record<string, unknown> | null>;
-  getEdges(): Promise<readonly WarpEdge[]>;
-}
-
-export interface WarpPatchBuilder {
-  addNode(id: string): unknown;
-  setProperty(id: string, key: string, value: unknown): unknown;
-  addEdge(from: string, to: string, label: string): unknown;
-  removeNode(id: string): unknown;
-  removeEdge(from: string, to: string, label: string): unknown;
-}
-
-export interface WarpMaterializeReceiptOp {
-  readonly op: string;
-  readonly result: string;
-  readonly target: string;
-}
-
-export interface WarpMaterializeReceipt {
-  readonly lamport: number;
-  readonly ops: readonly WarpMaterializeReceiptOp[];
-}
-
-export interface WarpHandle {
-  hasNode(nodeId: string): Promise<boolean>;
-  observer(lens: WarpObserverLens, options?: WarpObserverOptions): Promise<WarpObserver>;
-  patch(build: (patch: WarpPatchBuilder) => void | Promise<void>): Promise<string>;
-  materialize(): Promise<void>;
-  materializeReceipts(): Promise<readonly WarpMaterializeReceipt[]>;
-}

package/src/release/security-gate.ts

@@ -1,102 +0,0 @@
-import { z } from "zod";
-
-const severitySchema = z.enum([ "info", "low", "moderate", "high", "critical" ]);
-
-const auditReportSchema = z.object({
-  metadata: z.object({
-    vulnerabilities: z.object({
-      info: z.number().int().nonnegative(),
-      low: z.number().int().nonnegative(),
-      moderate: z.number().int().nonnegative(),
-      high: z.number().int().nonnegative(),
-      critical: z.number().int().nonnegative(),
-    }),
-  }),
-  advisories: z.record(z.string(), z.object({
-    id: z.number().int().nonnegative(),
-    module_name: z.string(),
-    severity: severitySchema,
-    title: z.string(),
-    recommendation: z.string(),
-    github_advisory_id: z.string().nullable().optional(),
-    findings: z.array(z.object({
-      version: z.string(),
-      paths: z.array(z.string()),
-    })).optional(),
-  })),
-});
-
-export interface SecurityGateViolation {
-  readonly id: number;
-  readonly moduleName: string;
-  readonly severity: "high" | "critical";
-  readonly title: string;
-  readonly advisoryId: string | null;
-  readonly recommendation: string;
-  readonly paths: readonly string[];
-  readonly versions: readonly string[];
-}
-
-export interface SecurityGateResult {
-  readonly blocking: boolean;
-  readonly counts: {
-    readonly info: number;
-    readonly low: number;
-    readonly moderate: number;
-    readonly high: number;
-    readonly critical: number;
-  };
-  readonly blockingFindings: readonly SecurityGateViolation[];
-}
-
-export function evaluateSecurityGate(report: unknown): SecurityGateResult {
-  const parsed = auditReportSchema.parse(report);
-  const blockingFindings: SecurityGateViolation[] = [];
-
-  for (const advisory of Object.values(parsed.advisories)) {
-    if (advisory.severity !== "high" && advisory.severity !== "critical") {
-      continue;
-    }
-    blockingFindings.push({
-      id: advisory.id,
-      moduleName: advisory.module_name,
-      severity: advisory.severity,
-      title: advisory.title,
-      advisoryId: advisory.github_advisory_id ?? null,
-      recommendation: advisory.recommendation,
-      paths: advisory.findings?.flatMap((finding) => finding.paths) ?? [],
-      versions: advisory.findings?.map((finding) => finding.version) ?? [],
-    });
-  }
-
-  return {
-    blocking: blockingFindings.length > 0,
-    counts: parsed.metadata.vulnerabilities,
-    blockingFindings,
-  };
-}
-
-export function formatSecurityGateResult(result: SecurityGateResult): string {
-  const lines = [
-    `audit summary: critical=${String(result.counts.critical)} high=${String(result.counts.high)} moderate=${String(result.counts.moderate)} low=${String(result.counts.low)} info=${String(result.counts.info)}`,
-  ];
-
-  if (!result.blocking) {
-    lines.push("release security gate: pass");
-    return lines.join("\n");
-  }
-
-  lines.push("release security gate: fail");
-  for (const finding of result.blockingFindings) {
-    const advisoryId = finding.advisoryId ?? `npm:${String(finding.id)}`;
-    const paths = finding.paths.length > 0 ? finding.paths.join(", ") : "unknown path";
-    const versions = finding.versions.length > 0 ? finding.versions.join(", ") : "unknown version";
-    lines.push(
-      `- ${finding.severity.toUpperCase()} ${advisoryId} ${finding.moduleName}@${versions} via ${paths}`,
-    );
-    lines.push(`  ${finding.title}`);
-    lines.push(`  ${finding.recommendation}`);
-  }
-
-  return lines.join("\n");
-}