whygraph 0.1.0

package/dist/server/schema.js

@@ -0,0 +1,362 @@
+import * as path from "node:path";
+import { createSchema, createPubSub } from "graphql-yoga";
+import { isStructuralNode, isDecisionNode } from "../entity/types.js";
+import { generateId } from "../entity/id.js";
+import { writeEntity } from "../entity/writer.js";
+import { getContext } from "../graph/query.js";
+import { getDecisions } from "../graph/decisions.js";
+import { getGaps } from "../graph/gaps.js";
+import { listNodes } from "../graph/nodes.js";
+import { searchDecisions } from "../graph/search.js";
+import { computeDerivedState } from "./derived.js";
+const typeDefs = /* GraphQL */ `
+  type StructuralNode {
+    id: ID!
+    label: String!
+    name: String!
+    status: String!
+    parent: String
+    refs: [SymbolRef!]
+    description: String
+    created_at: String!
+    updated_at: String!
+    removed_at: String
+  }
+
+  type DecisionNode {
+    id: ID!
+    label: String!
+    title: String!
+    status: String!
+    date: String!
+    affects: [String!]!
+    tags: [String!]!
+    supersedes: String
+    context: String!
+    decision: String!
+    tradeoffs: String!
+    alternatives: String!
+    created_at: String!
+    updated_at: String!
+    removed_at: String
+  }
+
+  type SymbolRef {
+    file: String!
+    symbol: String
+  }
+
+  input SymbolRefInput {
+    file: String!
+    symbol: String
+  }
+
+  union Entity = StructuralNode | DecisionNode
+
+  type ContextNodeResult {
+    id: ID!
+    label: String!
+    name: String!
+    parentChain: [String!]!
+  }
+
+  type ContextResult {
+    nodes: [ContextNodeResult!]!
+    decisions: [DecisionNode!]!
+  }
+
+  type NodeSummary {
+    id: ID!
+    label: String!
+    name: String!
+    parent: String
+  }
+
+  type ValidationErrorEntry {
+    field: String!
+    message: String!
+    severity: String!
+  }
+
+  type EntityValidationError {
+    entityId: ID!
+    errors: [ValidationErrorEntry!]!
+  }
+
+  type SupersedeCandidate {
+    newDecisionId: ID!
+    existingDecisionId: ID!
+    sharedNodeIds: [String!]!
+  }
+
+  type Query {
+    entities: [Entity!]!
+    entity(id: ID!): Entity
+    status: ServerStatus!
+    context(file: String!, symbol: String): ContextResult!
+    decisions(status: String, tags: [String!], dateFrom: String, dateTo: String): [DecisionNode!]!
+    gaps(limit: Int): [StructuralNode!]!
+    nodes(label: String, parent: String, search: String): [NodeSummary!]!
+    search(query: String!): [DecisionNode!]!
+    validationErrors: [EntityValidationError!]!
+    supersedeCandidates: [SupersedeCandidate!]!
+  }
+
+  type ServerStatus {
+    running: Boolean!
+    entityCount: Int!
+    nodeCount: Int!
+    decisionCount: Int!
+  }
+
+  type Mutation {
+    ping: Boolean!
+    createNode(
+      label: String!
+      name: String!
+      parent: String
+      refs: [SymbolRefInput!]
+      description: String
+    ): StructuralNode!
+    createDecision(
+      title: String!
+      date: String!
+      affects: [String!]!
+      tags: [String!]!
+      context: String!
+      decision: String!
+      tradeoffs: String!
+      alternatives: String!
+      supersedes: String
+    ): DecisionNode!
+    updateEntity(
+      id: ID!
+      status: String
+      removed_at: String
+      refs: [SymbolRefInput!]
+    ): Entity!
+  }
+
+  enum EntityChangeType {
+    CREATED
+    UPDATED
+    DELETED
+    INITIAL_SNAPSHOT
+  }
+
+  type EntityChangeEvent {
+    type: EntityChangeType!
+    entities: [Entity!]
+    entity: Entity
+    entityId: String
+  }
+
+  type Subscription {
+    entityChanged(includeInitial: Boolean): EntityChangeEvent!
+  }
+`;
+export function buildSchema(core) {
+    const yogaPubSub = createPubSub();
+    // Wire ServerCore's PubSub to Yoga's PubSub for subscriptions
+    core.pubsub.subscribe((event) => {
+        if (event.type === "entity_created") {
+            yogaPubSub.publish("entityChanged", {
+                type: "CREATED",
+                entity: event.entity,
+                entityId: event.entityId,
+            });
+        }
+        else if (event.type === "entity_updated") {
+            yogaPubSub.publish("entityChanged", {
+                type: "UPDATED",
+                entity: event.entity,
+                entityId: event.entityId,
+            });
+            /* v8 ignore next 5 */
+        }
+        else if (event.type === "entity_deleted") {
+            yogaPubSub.publish("entityChanged", {
+                type: "DELETED",
+                entityId: event.entityId,
+            });
+        }
+    });
+    return createSchema({
+        typeDefs,
+        resolvers: {
+            Entity: {
+                __resolveType(obj) {
+                    if (isDecisionNode(obj))
+                        return "DecisionNode";
+                    return "StructuralNode";
+                },
+            },
+            Query: {
+                entities: () => core.getAllEntities(),
+                entity: (_, args) => core.getEntity(args.id) ?? null,
+                status: () => {
+                    const all = core.getAllEntities();
+                    const decisions = all.filter(isDecisionNode);
+                    const nodes = all.filter(isStructuralNode);
+                    return {
+                        running: true,
+                        entityCount: all.length,
+                        nodeCount: nodes.length,
+                        decisionCount: decisions.length,
+                    };
+                },
+                context: (_, args) => {
+                    const result = getContext(core.getGraph(), args.file, args.symbol ?? undefined);
+                    return result;
+                },
+                decisions: (_, args) => {
+                    const filters = {};
+                    if (args.status !== undefined && args.status !== null) {
+                        filters.status = args.status;
+                    }
+                    if (args.tags !== undefined && args.tags !== null) {
+                        filters.tags = args.tags;
+                    }
+                    if (args.dateFrom !== undefined && args.dateFrom !== null) {
+                        filters.dateFrom = args.dateFrom;
+                    }
+                    if (args.dateTo !== undefined && args.dateTo !== null) {
+                        filters.dateTo = args.dateTo;
+                    }
+                    return getDecisions(core.getGraph(), filters);
+                },
+                gaps: (_, args) => {
+                    return getGaps(core.getGraph(), args.limit ?? undefined);
+                },
+                nodes: (_, args) => {
+                    const filters = {};
+                    if (args.label !== undefined && args.label !== null) {
+                        filters.label = args.label;
+                    }
+                    if (args.parent !== undefined && args.parent !== null) {
+                        filters.parent = args.parent;
+                    }
+                    if (args.search !== undefined && args.search !== null) {
+                        filters.search = args.search;
+                    }
+                    return listNodes(core.getGraph(), filters);
+                },
+                search: (_, args) => {
+                    return searchDecisions(core.getEntityMap(), args.query);
+                },
+                validationErrors: () => {
+                    return core.getIssues().map((issue) => ({
+                        entityId: issue.entityId,
+                        errors: issue.errors,
+                    }));
+                },
+                supersedeCandidates: () => {
+                    const derived = computeDerivedState(core.getEntityMap());
+                    return derived.supersedeCandidates;
+                },
+            },
+            Mutation: {
+                ping: () => true,
+                createNode: (_, args) => {
+                    const now = new Date().toISOString();
+                    const id = generateId();
+                    const graphDir = path.join(core.getWhygraphDir(), "graph");
+                    const node = {
+                        id,
+                        label: args.label,
+                        name: args.name,
+                        status: "active",
+                        created_at: now,
+                        updated_at: now,
+                    };
+                    if (args.parent !== undefined)
+                        node.parent = args.parent;
+                    if (args.refs !== undefined)
+                        node.refs = args.refs;
+                    if (args.description !== undefined)
+                        node.description = args.description;
+                    writeEntity(graphDir, node);
+                    core.addOrUpdateEntity(id, node);
+                    return node;
+                },
+                createDecision: (_, args) => {
+                    const now = new Date().toISOString();
+                    const id = generateId();
+                    const graphDir = path.join(core.getWhygraphDir(), "graph");
+                    const decision = {
+                        id,
+                        label: "Decision",
+                        title: args.title,
+                        status: "active",
+                        date: args.date,
+                        affects: args.affects,
+                        tags: args.tags,
+                        context: args.context,
+                        decision: args.decision,
+                        tradeoffs: args.tradeoffs,
+                        alternatives: args.alternatives,
+                        created_at: now,
+                        updated_at: now,
+                    };
+                    if (args.supersedes !== undefined)
+                        decision.supersedes = args.supersedes;
+                    writeEntity(graphDir, decision);
+                    core.addOrUpdateEntity(id, decision);
+                    return decision;
+                },
+                updateEntity: (_, args) => {
+                    const existing = core.getEntity(args.id);
+                    if (!existing) {
+                        throw new Error(`Entity not found: ${args.id}`);
+                    }
+                    const now = new Date().toISOString();
+                    const graphDir = path.join(core.getWhygraphDir(), "graph");
+                    const updated = { ...existing, updated_at: now };
+                    if (args.status !== undefined) {
+                        updated.status = args.status;
+                    }
+                    if (args.removed_at !== undefined) {
+                        updated.removed_at = args.removed_at;
+                    }
+                    if (args.refs !== undefined && isStructuralNode(updated)) {
+                        updated.refs = args.refs;
+                    }
+                    writeEntity(graphDir, updated);
+                    core.addOrUpdateEntity(args.id, updated);
+                    return updated;
+                },
+            },
+            Subscription: {
+                entityChanged: {
+                    subscribe: (_, args) => {
+                        const baseIterator = yogaPubSub.subscribe("entityChanged");
+                        if (!args.includeInitial) {
+                            return baseIterator;
+                        }
+                        // Wrap with initial snapshot
+                        async function* withInitialSnapshot() {
+                            const allEntities = core.getAllEntities();
+                            yield {
+                                entityChanged: {
+                                    type: "INITIAL_SNAPSHOT",
+                                    entities: allEntities,
+                                },
+                            };
+                            for await (const event of baseIterator) {
+                                yield event;
+                            }
+                        }
+                        return withInitialSnapshot();
+                    },
+                    resolve: (event) => {
+                        // Events from yogaPubSub come wrapped, initial snapshot comes unwrapped
+                        if ("entityChanged" in event) {
+                            return event.entityChanged;
+                        }
+                        return event;
+                    },
+                },
+            },
+        },
+    });
+}

package/dist/server/stale-refs.d.ts

@@ -0,0 +1,7 @@
+import type { Entity, SymbolRef } from "../entity/types.js";
+export interface StaleRef {
+    entityId: string;
+    entityName: string;
+    ref: SymbolRef;
+}
+export declare function detectStaleRefs(entities: Map<string, Entity>, basePath: string): StaleRef[];

package/dist/server/stale-refs.js

@@ -0,0 +1,23 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isStructuralNode } from "../entity/types.js";
+export function detectStaleRefs(entities, basePath) {
+    const staleRefs = [];
+    for (const [id, entity] of entities) {
+        if (!isStructuralNode(entity))
+            continue;
+        if (!entity.refs || entity.refs.length === 0)
+            continue;
+        for (const ref of entity.refs) {
+            const absolutePath = path.resolve(basePath, ref.file);
+            if (!fs.existsSync(absolutePath)) {
+                staleRefs.push({
+                    entityId: id,
+                    entityName: entity.name,
+                    ref,
+                });
+            }
+        }
+    }
+    return staleRefs;
+}

package/dist/server/watcher.d.ts

@@ -0,0 +1,21 @@
+export interface WatcherEvent {
+    type: "created" | "updated" | "deleted";
+    filePath: string;
+    entityId?: string;
+}
+export type WatcherCallback = (events: WatcherEvent[]) => void;
+export declare class FileWatcher {
+    private readonly dirPath;
+    private watcher;
+    private pendingEvents;
+    private debounceTimer;
+    private callback;
+    private knownFiles;
+    constructor(dirPath: string);
+    start(callback: WatcherCallback): void;
+    stop(): Promise<void>;
+    private handleFileChange;
+    private enqueue;
+    private scheduleBatch;
+    private flush;
+}

package/dist/server/watcher.js

@@ -0,0 +1,98 @@
+import * as fs from "node:fs/promises";
+import { watch } from "chokidar";
+import { parseEntity } from "../entity/parser.js";
+import { parseFilename } from "../entity/id.js";
+export class FileWatcher {
+    dirPath;
+    watcher = null;
+    pendingEvents = [];
+    debounceTimer = null;
+    callback = null;
+    knownFiles = new Set();
+    constructor(dirPath) {
+        this.dirPath = dirPath;
+    }
+    start(callback) {
+        this.callback = callback;
+        this.watcher = watch(this.dirPath, {
+            ignoreInitial: true,
+            awaitWriteFinish: false,
+        });
+        this.watcher.on("add", (filePath) => {
+            if (!filePath.endsWith(".md"))
+                return;
+            this.knownFiles.add(filePath);
+            this.handleFileChange(filePath, "created");
+        });
+        this.watcher.on("change", (filePath) => {
+            /* v8 ignore next 1 */
+            if (!filePath.endsWith(".md"))
+                return;
+            this.handleFileChange(filePath, "updated");
+        });
+        this.watcher.on("unlink", (filePath) => {
+            /* v8 ignore next 1 */
+            if (!filePath.endsWith(".md"))
+                return;
+            this.knownFiles.delete(filePath);
+            /* v8 ignore next 1 */
+            const entityId = parseFilename(filePath) ?? undefined;
+            this.enqueue({
+                type: "deleted",
+                filePath,
+                entityId,
+            });
+        });
+    }
+    async stop() {
+        /* v8 ignore next 4 */
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+        this.pendingEvents = [];
+        this.callback = null;
+        this.knownFiles.clear();
+    }
+    handleFileChange(filePath, type) {
+        fs.readFile(filePath, "utf-8")
+            .then((content) => {
+            const entity = parseEntity(content);
+            this.enqueue({
+                type,
+                filePath,
+                entityId: entity?.id,
+            });
+        })
+            /* v8 ignore start */
+            .catch(() => {
+            // File may have been deleted between event and read — ignore
+        });
+        /* v8 ignore stop */
+    }
+    enqueue(event) {
+        this.pendingEvents.push(event);
+        this.scheduleBatch();
+    }
+    scheduleBatch() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.flush();
+        }, 100);
+    }
+    flush() {
+        /* v8 ignore next 1 */
+        if (this.pendingEvents.length === 0 || !this.callback)
+            return;
+        const events = this.pendingEvents;
+        this.pendingEvents = [];
+        this.debounceTimer = null;
+        this.callback(events);
+    }
+}

package/dist/server/worktree-watcher.d.ts

@@ -0,0 +1,20 @@
+import { ServerCore } from "./core.js";
+import { type DetectDeps, type WorktreeInfo } from "./worktree.js";
+export interface WorktreeWatcherDeps {
+    detectWorktrees: (repoDir: string, deps?: DetectDeps) => Promise<WorktreeInfo[]>;
+}
+export declare class WorktreeWatcher {
+    private readonly core;
+    private readonly repoDir;
+    private readonly watchers;
+    private readonly worktreeEntities;
+    private readonly dirtyEntities;
+    private readonly deps;
+    constructor(core: ServerCore, repoDir: string, deps?: WorktreeWatcherDeps);
+    startWatching(): Promise<void>;
+    stop(): Promise<void>;
+    getWatchedWorktrees(): string[];
+    isWorktreeEntity(id: string): boolean;
+    getDirtyIds(): string[];
+    private handleEvents;
+}

package/dist/server/worktree-watcher.js

@@ -0,0 +1,79 @@
+import * as fs from "node:fs/promises";
+import { FileWatcher } from "./watcher.js";
+import { detectWorktrees } from "./worktree.js";
+import { parseEntity } from "../entity/parser.js";
+import { computeETag } from "./etag.js";
+export class WorktreeWatcher {
+    core;
+    repoDir;
+    watchers = new Map();
+    worktreeEntities = new Set();
+    dirtyEntities = new Set();
+    deps;
+    constructor(core, repoDir, deps) {
+        this.core = core;
+        this.repoDir = repoDir;
+        this.deps = deps ?? { detectWorktrees };
+    }
+    async startWatching() {
+        const worktrees = await this.deps.detectWorktrees(this.repoDir);
+        for (const wt of worktrees) {
+            const watcher = new FileWatcher(wt.graphDir);
+            this.watchers.set(wt.path, watcher);
+            watcher.start((events) => {
+                this.handleEvents(events, wt);
+            });
+        }
+    }
+    async stop() {
+        const stops = Array.from(this.watchers.values()).map((w) => w.stop());
+        await Promise.all(stops);
+        this.watchers.clear();
+    }
+    getWatchedWorktrees() {
+        return Array.from(this.watchers.keys());
+    }
+    isWorktreeEntity(id) {
+        return this.worktreeEntities.has(id);
+    }
+    getDirtyIds() {
+        return Array.from(this.dirtyEntities);
+    }
+    handleEvents(events, wt) {
+        for (const event of events) {
+            if (event.type === "deleted" && event.entityId) {
+                this.worktreeEntities.delete(event.entityId);
+                this.dirtyEntities.delete(event.entityId);
+                this.core.removeEntity(event.entityId);
+                /* v8 ignore next 1 */
+            }
+            else if (event.entityId) {
+                this.worktreeEntities.add(event.entityId);
+                // Read the file to get the full entity
+                fs.readFile(event.filePath, "utf-8")
+                    .then((content) => {
+                    const entity = parseEntity(content);
+                    /* v8 ignore next 1 */
+                    if (entity) {
+                        // Track dirty state via ETag comparison with main entity
+                        const mainEntity = this.core.getEntity(entity.id);
+                        if (mainEntity && computeETag(entity) === computeETag(mainEntity)) {
+                            this.dirtyEntities.delete(entity.id);
+                        }
+                        else {
+                            this.dirtyEntities.add(entity.id);
+                        }
+                        // Mark entity as coming from a worktree
+                        const tagged = { ...entity, _worktree: wt.path };
+                        this.core.addOrUpdateEntity(entity.id, tagged);
+                    }
+                })
+                    /* v8 ignore start */
+                    .catch(() => {
+                    // File may have been deleted between event and read
+                });
+                /* v8 ignore stop */
+            }
+        }
+    }
+}

package/dist/server/worktree.d.ts

@@ -0,0 +1,22 @@
+export interface WorktreeInfo {
+    path: string;
+    branch: string;
+    graphDir: string;
+}
+export interface ParsedWorktree {
+    path: string;
+    branch: string | null;
+    isMain: boolean;
+}
+/** Dependency injection for testing. */
+export interface DetectDeps {
+    execFile: (cmd: string, args: string[], opts: {
+        cwd: string;
+    }) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    access: (p: string) => Promise<void>;
+}
+export declare function parseWorktreeList(output: string): ParsedWorktree[];
+export declare function detectWorktrees(repoDir: string, deps?: DetectDeps): Promise<WorktreeInfo[]>;