@flyingrobots/graft 0.3.5 → 0.5.0

package/src/warp/observers.ts

@@ -0,0 +1,105 @@
+/**
+ * WARP Observer Factory — canonical observer lenses for graft queries.
+ *
+ * Observer Law: this module READS through observers. It never
+ * walks the graph directly, maintains shadow state, or implements
+ * traversal algorithms.
+ *
+ * Each function returns an observer with a focused lens. The lens
+ * determines the aperture — what the observer can see.
+ */
+
+import type WarpApp from "@git-stunts/git-warp";
+import type { Observer } from "@git-stunts/git-warp";
+
+/** Lens config for creating focused observers. */
+export interface Lens {
+  match: string;
+  expose?: string[];
+  redact?: string[];
+}
+
+/**
+ * Observe all symbols in a specific file.
+ * Aperture: sym:<path>:*
+ */
+export function fileSymbolsLens(filePath: string): Lens {
+  return {
+    match: `sym:${filePath}:*`,
+    expose: ["name", "kind", "signature", "exported", "startLine", "endLine"],
+  };
+}
+
+/**
+ * Observe all symbols in the project.
+ * Aperture: sym:*
+ */
+export function allSymbolsLens(): Lens {
+  return {
+    match: "sym:*",
+    expose: ["name", "kind", "signature", "exported", "startLine", "endLine"],
+  };
+}
+
+/**
+ * Observe all files in the project.
+ * Aperture: file:*
+ */
+export function allFilesLens(): Lens {
+  return {
+    match: "file:*",
+    expose: ["path", "lang"],
+  };
+}
+
+/**
+ * Observe a single symbol by name across all files.
+ * Aperture: sym:*:<name>
+ */
+export function symbolByNameLens(symbolName: string): Lens {
+  return {
+    match: `sym:*:${symbolName}`,
+    expose: ["name", "kind", "signature", "exported", "startLine", "endLine"],
+  };
+}
+
+/**
+ * Observe a directory subtree.
+ * Aperture: dir:<path>*
+ */
+export function directoryLens(dirPath: string): Lens {
+  return {
+    match: `dir:${dirPath}*`,
+    expose: ["path"],
+  };
+}
+
+/**
+ * Observe all files under a directory.
+ * Aperture: file:<path>/*
+ */
+export function directoryFilesLens(dirPath: string): Lens {
+  return {
+    match: `file:${dirPath}/*`,
+    expose: ["path", "lang"],
+  };
+}
+
+/**
+ * Observe commit metadata.
+ * Aperture: commit:*
+ */
+export function commitsLens(): Lens {
+  return {
+    match: "commit:*",
+    expose: ["sha", "message", "timestamp", "author", "email"],
+  };
+}
+
+/**
+ * Create an observer on the current frontier with a given lens.
+ * Observers are static snapshots — create a new one after writes.
+ */
+export function observe(warp: WarpApp, lens: Lens): Promise<Observer> {
+  return warp.observer(lens);
+}

package/src/warp/open.ts

@@ -0,0 +1,31 @@
+/**
+ * WARP graph initialization — opens the graft-ast graph backed by
+ * the repo's own .git directory.
+ *
+ * Single entry point. Returns a WarpApp instance ready for patch
+ * writes and observer reads.
+ */
+
+import WarpApp, { GitGraphAdapter } from "@git-stunts/git-warp";
+import GitPlumbing from "@git-stunts/plumbing";
+import { DEFAULT_WARP_WRITER_ID } from "./writer-id.js";
+
+export const GRAPH_NAME = "graft-ast";
+
+export interface OpenWarpOptions {
+  readonly cwd: string;
+  readonly writerId?: string;
+}
+
+export async function openWarp(options: OpenWarpOptions): Promise<WarpApp> {
+  // createDefault() wires the ShellRunnerFactory (required port)
+  const plumbing = GitPlumbing.createDefault({ cwd: options.cwd });
+  const persistence = new GitGraphAdapter({ plumbing });
+
+  return WarpApp.open({
+    persistence,
+    graphName: GRAPH_NAME,
+    writerId: options.writerId ?? DEFAULT_WARP_WRITER_ID,
+    onDeleteWithData: "cascade",
+  });
+}

package/src/warp/plumbing.d.ts

@@ -0,0 +1,15 @@
+declare module "@git-stunts/plumbing" {
+  import type { GitPlumbing as GitPlumbingInterface } from "@git-stunts/git-warp";
+
+  export default class GitPlumbing implements GitPlumbingInterface {
+    readonly emptyTree: string;
+    constructor(options: { runner: unknown; cwd?: string });
+    static createDefault(options?: { cwd?: string; env?: string }): GitPlumbing;
+    execute(options: { args: string[]; input?: string | Uint8Array }): Promise<string>;
+    executeStream(options: { args: string[] }): Promise<{
+      finished: Promise<{ code: number; stderr: string; error?: Error }>;
+      collect(opts?: { maxBytes?: number; asString?: boolean; encoding?: string }): Promise<Uint8Array | string>;
+      [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+    }>;
+  }
+}

package/src/warp/writer-id.ts

@@ -0,0 +1,30 @@
+import * as crypto from "node:crypto";
+
+export const DEFAULT_WARP_WRITER_ID = "graft";
+
+function sanitizeSegment(input: string): string {
+  const normalized = input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return normalized.length > 0 ? normalized : "lane";
+}
+
+export function buildWarpWriterId(kind: string, scope?: string): string {
+  const lane = sanitizeSegment(kind);
+  if (scope === undefined || scope.trim().length === 0) {
+    return `graft_${lane}`;
+  }
+
+  const digest = crypto.createHash("sha256").update(scope).digest("hex").slice(0, 12);
+  return `graft_${lane}_${digest}`;
+}
+
+export function buildSessionWarpWriterId(sessionId: string): string {
+  return buildWarpWriterId("session", sessionId);
+}
+
+export function buildMonitorWarpWriterId(repoId: string): string {
+  return buildWarpWriterId("monitor", repoId);
+}