@hegemonart/get-design-done 1.30.5 → 1.31.0

package/scripts/lib/graph/query.mjs

@@ -0,0 +1,155 @@
+// scripts/lib/graph/query.mjs — Plan 30.6-03 Task 1
+//
+// queryGraph: read .design/graph/graph.json, tokenize the query, score
+// nodes per D-04.a (+100 exact-id / +50 exact-label / +20 seed / +10
+// token-in-label / +5 token-in-type / +1 token-in-attrs), walk 1-hop
+// outbound edges to attach neighbors, then enforce a token budget
+// (D-04 chars/4 heuristic via token-estimate.mjs) by dropping
+// lowest-scored matches until the payload fits.
+//
+// Deterministic: identical (graph, query, budget) inputs produce
+// byte-identical JSON output. Ties broken by lexicographic id.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { compileValidator } from './schema.mjs';
+import { estimateTokens } from './token-estimate.mjs';
+
+const DEFAULT_GRAPH = '.design/graph/graph.json';
+const DEFAULT_BUDGET = 8000;
+const DEFAULT_TOP_K = 10;
+
+/**
+ * Query the native graph.
+ *
+ * @param {object} opts
+ * @param {string} [opts.graphPath] - default '.design/graph/graph.json'
+ * @param {string} opts.query       - search term (lowercased, tokenized)
+ * @param {number} [opts.budget]    - max estimated tokens for return payload
+ * @returns {{query:string, matches:Array<{node:object, score:number, neighbors:object[]}>, truncated:boolean}}
+ * @throws GRAPH_MISSING when graphPath does not exist
+ * @throws GRAPH_PARSE_FAILED when graph JSON cannot be parsed
+ * @throws GRAPH_SCHEMA_INVALID when graph fails schema validation
+ */
+export function queryGraph({
+  graphPath = DEFAULT_GRAPH,
+  query = '',
+  budget = DEFAULT_BUDGET,
+} = {}) {
+  if (!existsSync(graphPath)) {
+    const err = new Error(`queryGraph: graph file not found at ${graphPath}`);
+    err.code = 'GRAPH_MISSING';
+    throw err;
+  }
+
+  let graph;
+  try {
+    graph = JSON.parse(readFileSync(graphPath, 'utf8'));
+  } catch (e) {
+    const err = new Error(
+      `queryGraph: failed to parse graph JSON at ${graphPath}: ${e.message}`,
+    );
+    err.code = 'GRAPH_PARSE_FAILED';
+    err.cause = e;
+    throw err;
+  }
+
+  const validate = compileValidator();
+  if (!validate(graph)) {
+    const err = new Error('queryGraph: graph failed schema validation');
+    err.code = 'GRAPH_SCHEMA_INVALID';
+    err.schemaErrors = validate.errors;
+    throw err;
+  }
+
+  // ── Tokenize ────────────────────────────────────────────────────────
+  const lowerQuery = String(query).toLowerCase().trim();
+  const tokens = lowerQuery
+    .split(/[^a-z0-9:_\-/.]+/)
+    .filter((t) => t.length > 0);
+
+  // ── Empty / no-token query short-circuit ────────────────────────────
+  if (tokens.length === 0) {
+    return { query, matches: [], truncated: false };
+  }
+
+  // ── Score each node ─────────────────────────────────────────────────
+  // Identify seed nodes (label or id contains the full lowercase query) for the
+  // +20 seed bonus before per-token scoring.
+  const seedIds = new Set();
+  for (const n of graph.nodes) {
+    const idLower = String(n.id || '').toLowerCase();
+    const labelLower = String(n.label || '').toLowerCase();
+    if (
+      lowerQuery.length > 0 &&
+      (idLower.includes(lowerQuery) || labelLower.includes(lowerQuery))
+    ) {
+      seedIds.add(n.id);
+    }
+  }
+
+  const scored = graph.nodes
+    .map((node) => ({ node, score: scoreNode(node, tokens, lowerQuery, seedIds) }))
+    .filter((m) => m.score > 0)
+    .sort((a, b) => b.score - a.score || a.node.id.localeCompare(b.node.id));
+
+  // ── Build adjacency for 1-hop outbound walk ─────────────────────────
+  const outbound = new Map();
+  for (const e of graph.edges) {
+    if (!outbound.has(e.from)) outbound.set(e.from, []);
+    outbound.get(e.from).push(e);
+  }
+  const nodeById = new Map(graph.nodes.map((n) => [n.id, n]));
+
+  // ── Assemble matches with neighbors ─────────────────────────────────
+  const candidates = scored.slice(0, DEFAULT_TOP_K).map(({ node, score }) => {
+    const outs = outbound.get(node.id) || [];
+    const neighbors = outs
+      .map((e) => nodeById.get(e.to))
+      .filter((n) => n !== undefined);
+    return { node, score, neighbors };
+  });
+
+  // ── Budget-truncation loop ──────────────────────────────────────────
+  let payload = { query, matches: candidates.slice(), truncated: false };
+  while (
+    estimateTokens(payload) > budget &&
+    payload.matches.length > 0
+  ) {
+    payload.matches.pop(); // drop lowest-score (sorted desc → tail = lowest)
+  }
+  if (estimateTokens(payload) > budget) {
+    payload = { query, matches: [], truncated: true };
+  } else if (payload.matches.length < candidates.length) {
+    payload.truncated = true;
+  }
+
+  return payload;
+}
+
+/**
+ * Score a node per D-04.a:
+ *   +100 exact-id match (case-insensitive)
+ *   +50  exact-label match
+ *   +20  seed bonus (node contained the full query as substring)
+ *   +10  per token substring-match in label
+ *   +5   per token substring-match in type
+ *   +1   per token substring-match in attrs (JSON-stringified, lowercased)
+ */
+function scoreNode(node, tokens, lowerQuery, seedIds) {
+  let score = 0;
+  const idLower = String(node.id || '').toLowerCase();
+  const labelLower = String(node.label || '').toLowerCase();
+  const typeLower = String(node.type || '').toLowerCase();
+  const attrsLower = JSON.stringify(node.attrs || {}).toLowerCase();
+
+  if (lowerQuery && idLower === lowerQuery) score += 100;
+  if (lowerQuery && labelLower === lowerQuery) score += 50;
+  if (seedIds.has(node.id)) score += 20;
+
+  for (const t of tokens) {
+    if (labelLower.includes(t)) score += 10;
+    if (typeLower.includes(t)) score += 5;
+    if (attrsLower.includes(t)) score += 1;
+  }
+  return score;
+}

package/scripts/lib/graph/schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://get-design-done.example/schemas/graph.schema.json",
+  "title": ".design/graph/graph.json",
+  "description": "Native gdd-graph store. Schema version 1.0 — frozen at Phase 30.6 per D-03.",
+  "type": "object",
+  "required": ["schemaVersion", "metadata", "nodes", "edges"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Pinned to 1.0 at ship; future migrations bump explicitly (D-03)."
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["generatedAt", "nodeCount", "edgeCount"],
+      "additionalProperties": true,
+      "properties": {
+        "generatedAt": { "type": "string", "description": "ISO 8601 timestamp" },
+        "intelSource": { "type": "string", "description": "Path to source intel file, e.g. .design/intel/graph.json" },
+        "nodeCount": { "type": "integer", "minimum": 0 },
+        "edgeCount": { "type": "integer", "minimum": 0 },
+        "builderVersion": { "type": "string", "description": "gdd-graph version that wrote this file" }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "type"],
+        "additionalProperties": true,
+        "properties": {
+          "id":     { "type": "string", "minLength": 1, "description": "Stable globally-unique node ID" },
+          "type":   { "type": "string", "description": "Node category (component, token, decision, etc.) — lenient enum per D-03" },
+          "label":  { "type": "string", "description": "Human-readable display name" },
+          "attrs":  { "type": "object", "additionalProperties": true, "description": "Free-form node attributes" },
+          "source": {
+            "oneOf": [
+              { "type": "string", "description": "Source file path or origin marker" },
+              { "type": "object", "additionalProperties": true, "description": "Structured source descriptor per D-03.a" }
+            ]
+          }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "kind"],
+        "additionalProperties": true,
+        "properties": {
+          "from":   { "type": "string", "minLength": 1, "description": "Source node id (matches a nodes[].id)" },
+          "to":     { "type": "string", "minLength": 1, "description": "Target node id" },
+          "kind":   { "type": "string", "description": "Edge type per D-03.b" },
+          "weight": { "type": "number", "description": "Optional edge weight per D-03.c; used by query ranking + budget eviction" },
+          "attrs":  { "type": "object", "additionalProperties": true },
+          "source": {
+            "oneOf": [
+              { "type": "string" },
+              { "type": "object", "additionalProperties": true }
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/scripts/lib/graph/schema.mjs

@@ -0,0 +1,47 @@
+// scripts/lib/graph/schema.mjs — Plan 30.6-02 Task 1
+//
+// Ajv-compiled validator factory for .design/graph/graph.json (schema 1.0,
+// frozen at Phase 30.6 per D-03). Compile-once + memoized so callers can
+// invoke compileValidator() liberally without paying per-call cost.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import Ajv from 'ajv';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Read schema via fs.readFileSync rather than `import ... with { type:'json' }`
+// to keep this working on Node 22+ without flag tweaks across runtimes.
+const schemaJson = JSON.parse(
+  readFileSync(join(__dirname, 'schema.json'), 'utf8'),
+);
+
+export const SCHEMA_VERSION = '1.0';
+export const SCHEMA = schemaJson;
+
+let _validator = null;
+
+/**
+ * Returns a compiled Ajv validator function for the native graph schema.
+ * Memoized: subsequent calls return the same instance (no recompile).
+ *
+ * Strict mode is disabled so additionalProperties:true on nodes/edges is
+ * honored (forward-compat lenience per 30.6-01 RESEARCH.md).
+ *
+ * @returns {(payload: unknown) => boolean} validator with .errors after a failed call
+ */
+export function compileValidator() {
+  if (_validator) return _validator;
+  // Ajv ESM: the default export is the constructor.
+  const AjvCtor = Ajv.default || Ajv;
+  const ajv = new AjvCtor({ strict: false, allErrors: true });
+  _validator = ajv.compile(schemaJson);
+  return _validator;
+}
+
+// Test-only hook: reset the memo so test runs can verify compile-once semantics
+// without polluting other suites. Not part of the public CLI surface.
+export function _resetValidatorMemoForTests() {
+  _validator = null;
+}

package/scripts/lib/graph/status.mjs

@@ -0,0 +1,88 @@
+// scripts/lib/graph/status.mjs — Plan 30.6-02 Task 2
+//
+// statusGraph: read .design/graph/graph.json, return structured status JSON.
+// Gracefully degrades when graph file is missing — returns
+// {configured:false, exists:false} without throwing (the 6 status callsites
+// probe before issuing other commands).
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { compileValidator } from './schema.mjs';
+
+const DEFAULT_GRAPH = '.design/graph/graph.json';
+const DEFAULT_INTEL = '.design/intel/graph.json';
+
+/**
+ * Report status of the native graph store.
+ *
+ * @param {object} opts
+ * @param {string} [opts.graphPath] - default '.design/graph/graph.json'
+ * @param {string} [opts.intelPath] - default '.design/intel/graph.json' (used for staleness)
+ * @returns {object} structured status — see RESEARCH.md §Subcommand inventory
+ */
+export function statusGraph({
+  graphPath = DEFAULT_GRAPH,
+  intelPath = DEFAULT_INTEL,
+} = {}) {
+  if (!existsSync(graphPath)) {
+    return { configured: false, exists: false };
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(graphPath, 'utf8');
+  } catch (e) {
+    return {
+      configured: true,
+      exists: true,
+      schemaInvalid: true,
+      errors: [{ message: `read failed: ${e.message}` }],
+    };
+  }
+
+  let graph;
+  try {
+    graph = JSON.parse(raw);
+  } catch (e) {
+    return {
+      configured: true,
+      exists: true,
+      schemaInvalid: true,
+      errors: [{ message: `parse failed: ${e.message}` }],
+    };
+  }
+
+  const validate = compileValidator();
+  if (!validate(graph)) {
+    return {
+      configured: true,
+      exists: true,
+      schemaInvalid: true,
+      errors: validate.errors,
+    };
+  }
+
+  const lastBuiltAt = graph.metadata?.generatedAt ?? null;
+
+  let stale = false;
+  if (existsSync(intelPath) && lastBuiltAt) {
+    try {
+      const intelMtime = statSync(intelPath).mtimeMs;
+      const builtMs = Date.parse(lastBuiltAt);
+      if (Number.isFinite(builtMs) && intelMtime > builtMs) {
+        stale = true;
+      }
+    } catch {
+      // Stat failed — leave stale=false; not a hard error.
+    }
+  }
+
+  return {
+    configured: true,
+    exists: true,
+    nodeCount: graph.nodes.length,
+    edgeCount: graph.edges.length,
+    schemaVersion: graph.schemaVersion,
+    lastBuiltAt,
+    stale,
+  };
+}

package/scripts/lib/graph/token-estimate.mjs

@@ -0,0 +1,27 @@
+// scripts/lib/graph/token-estimate.mjs — Plan 30.6-03 Task 1
+//
+// Token-budget heuristic per D-04: ceil(JSON.stringify(payload).length / 4).
+// Crude approximation of the Anthropic tokenizer's chars-per-token ratio;
+// overridable via GDD_GRAPH_TOKEN_FACTOR env var for test seams (D-04 +
+// RESEARCH.md §Query algorithm).
+//
+// This module is the single place to swap heuristic for a real tokenizer
+// (tiktoken, anthropic-tokenizer, etc.) if/when we want a more faithful
+// budget calculation. All callers funnel through estimateTokens().
+
+/**
+ * Estimate the token count of a payload.
+ *
+ * @param {unknown} payload - string OR JSON-serializable value
+ * @returns {number} ceiling of chars/divisor; divisor = GDD_GRAPH_TOKEN_FACTOR
+ *                   (when finite, positive number) or 4 (default)
+ */
+export function estimateTokens(payload) {
+  const str = typeof payload === 'string' ? payload : JSON.stringify(payload);
+  // JSON.stringify can return undefined for symbol/function inputs — guard.
+  const safe = typeof str === 'string' ? str : '';
+  const envFactor = Number(process.env.GDD_GRAPH_TOKEN_FACTOR);
+  const divisor =
+    Number.isFinite(envFactor) && envFactor > 0 ? envFactor : 4;
+  return Math.ceil(safe.length / divisor);
+}

package/scripts/lib/graph/upsert.mjs

@@ -0,0 +1,210 @@
+// scripts/lib/graph/upsert.mjs — Plan 30.6-03 Task 2
+//
+// upsertNode + upsertEdge: read existing graph.json (bootstrap empty
+// schemaVersion-1.0 envelope if missing), apply mutation, schema-validate
+// the full graph BEFORE atomic write (per D-03 + D-05). Referential
+// integrity is enforced at the upsert layer (NOT in the JSON schema) per
+// 30.6-02's schema design: edges must reference nodes that already exist.
+//
+// Idempotency contract: same (id) for nodes / same (from,to,kind) for
+// edges → last-write-wins, no duplicate rows, action='updated'.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { compileValidator, SCHEMA_VERSION } from './schema.mjs';
+import { atomicWriteJson } from './atomic-write.mjs';
+
+const DEFAULT_GRAPH = '.design/graph/graph.json';
+
+/**
+ * Upsert a node into the graph (create if missing, replace by id if present).
+ *
+ * @param {object} opts
+ * @param {string} [opts.graphPath] - default '.design/graph/graph.json'
+ * @param {object} opts.node        - { id, type, label?, attrs?, source? }
+ * @returns {{ok: true, action: 'created'|'updated', nodeCount: number}}
+ * @throws GDD_GRAPH_INVALID_NODE on missing/invalid id
+ * @throws GDD_GRAPH_SCHEMA_INVALID on schema-violating input
+ */
+export function upsertNode({ graphPath = DEFAULT_GRAPH, node } = {}) {
+  if (!node || typeof node !== 'object') {
+    const err = new Error('upsertNode: node parameter is required and must be an object');
+    err.code = 'GDD_GRAPH_INVALID_NODE';
+    throw err;
+  }
+  if (typeof node.id !== 'string' || node.id.length === 0) {
+    const err = new Error('upsertNode: node.id is required and must be a non-empty string');
+    err.code = 'GDD_GRAPH_INVALID_NODE';
+    throw err;
+  }
+  if (typeof node.type !== 'string' || node.type.length === 0) {
+    const err = new Error('upsertNode: node.type is required and must be a non-empty string');
+    err.code = 'GDD_GRAPH_INVALID_NODE';
+    throw err;
+  }
+
+  const graph = loadOrBootstrap(graphPath);
+
+  const idx = graph.nodes.findIndex((n) => n.id === node.id);
+  let action;
+  if (idx === -1) {
+    graph.nodes.push(node);
+    action = 'created';
+  } else {
+    graph.nodes[idx] = node;
+    action = 'updated';
+  }
+
+  graph.metadata.nodeCount = graph.nodes.length;
+  graph.metadata.edgeCount = graph.edges.length;
+
+  validateOrThrow(graph, 'upsertNode');
+  atomicWriteJson(graphPath, graph);
+
+  return { ok: true, action, nodeCount: graph.nodes.length };
+}
+
+/**
+ * Upsert an edge into the graph. Identity = `${from}::${to}::${kind}`.
+ *
+ * Referential integrity: both `from` and `to` must reference existing nodes.
+ * Schema enforces only field-shape; the existence check is an upsert-layer
+ * concern (per 30.6-02 schema design + RESEARCH.md §upsert-edge contract).
+ *
+ * @param {object} opts
+ * @param {string} [opts.graphPath]
+ * @param {object} opts.edge - { from, to, kind, weight?, attrs?, source? }
+ * @returns {{ok: true, action: 'created'|'updated', edgeCount: number}}
+ * @throws GDD_GRAPH_INVALID_EDGE on missing required fields
+ * @throws GDD_GRAPH_MISSING when graph file does not exist (edges can't
+ *         precede nodes; create at least one node first via upsertNode)
+ * @throws GDD_GRAPH_MISSING_ENDPOINT with missingEndpoints[] when from/to
+ *         do not reference existing nodes
+ * @throws GDD_GRAPH_SCHEMA_INVALID when the mutated graph violates schema
+ */
+export function upsertEdge({ graphPath = DEFAULT_GRAPH, edge } = {}) {
+  if (!edge || typeof edge !== 'object') {
+    const err = new Error('upsertEdge: edge parameter is required and must be an object');
+    err.code = 'GDD_GRAPH_INVALID_EDGE';
+    throw err;
+  }
+  for (const field of ['from', 'to', 'kind']) {
+    if (typeof edge[field] !== 'string' || edge[field].length === 0) {
+      const err = new Error(
+        `upsertEdge: edge.${field} is required and must be a non-empty string`,
+      );
+      err.code = 'GDD_GRAPH_INVALID_EDGE';
+      throw err;
+    }
+  }
+
+  // Edges cannot exist before nodes — file-missing is a hard error.
+  if (!existsSync(graphPath)) {
+    const err = new Error(
+      `upsertEdge: graph file not found at ${graphPath} — create at least one node first via upsertNode`,
+    );
+    err.code = 'GDD_GRAPH_MISSING';
+    throw err;
+  }
+
+  const graph = loadOrBootstrap(graphPath);
+
+  // Referential integrity check.
+  const nodeIds = new Set(graph.nodes.map((n) => n.id));
+  const missingEndpoints = [];
+  if (!nodeIds.has(edge.from)) missingEndpoints.push(edge.from);
+  if (!nodeIds.has(edge.to)) missingEndpoints.push(edge.to);
+  if (missingEndpoints.length) {
+    const err = new Error(
+      `upsertEdge: missing endpoint node(s): ${missingEndpoints.join(', ')}`,
+    );
+    err.code = 'GDD_GRAPH_MISSING_ENDPOINT';
+    err.missingEndpoints = missingEndpoints;
+    throw err;
+  }
+
+  // Edge identity per D-03.b + upstream diff formula: from::to::kind.
+  const idx = graph.edges.findIndex(
+    (e) => e.from === edge.from && e.to === edge.to && e.kind === edge.kind,
+  );
+  let action;
+  if (idx === -1) {
+    graph.edges.push(edge);
+    action = 'created';
+  } else {
+    graph.edges[idx] = edge;
+    action = 'updated';
+  }
+
+  graph.metadata.nodeCount = graph.nodes.length;
+  graph.metadata.edgeCount = graph.edges.length;
+
+  validateOrThrow(graph, 'upsertEdge');
+  atomicWriteJson(graphPath, graph);
+
+  return { ok: true, action, edgeCount: graph.edges.length };
+}
+
+// ────────────────────────── helpers ──────────────────────────
+
+/**
+ * Load graph from disk, or bootstrap a schema-1.0 envelope if missing.
+ * Throws GDD_GRAPH_PARSE_FAILED on JSON parse error (manual edit broke it).
+ */
+function loadOrBootstrap(graphPath) {
+  if (!existsSync(graphPath)) {
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      metadata: {
+        generatedAt: new Date().toISOString(),
+        nodeCount: 0,
+        edgeCount: 0,
+        builderVersion: '1.30.6',
+      },
+      nodes: [],
+      edges: [],
+    };
+  }
+
+  try {
+    const graph = JSON.parse(readFileSync(graphPath, 'utf8'));
+    // Defensive: ensure metadata/nodes/edges containers exist (a hand-edited
+    // file may have shed them — upsert should not crash before the
+    // validator can flag the corruption).
+    if (!graph.metadata) graph.metadata = { generatedAt: new Date().toISOString(), nodeCount: 0, edgeCount: 0 };
+    if (!Array.isArray(graph.nodes)) graph.nodes = [];
+    if (!Array.isArray(graph.edges)) graph.edges = [];
+    return graph;
+  } catch (e) {
+    const err = new Error(
+      `upsert: failed to parse graph JSON at ${graphPath}: ${e.message}`,
+    );
+    err.code = 'GDD_GRAPH_PARSE_FAILED';
+    err.cause = e;
+    throw err;
+  }
+}
+
+/**
+ * Validate full graph against schema 1.0 before write.
+ * Distinguish input-shape errors (caller passed a bad node/edge) from
+ * GDD_GRAPH_INVALID_{NODE,EDGE} (which are pre-write field-presence checks).
+ */
+function validateOrThrow(graph, op) {
+  const validate = compileValidator();
+  if (!validate(graph)) {
+    // Map Ajv path errors back to actionable codes when possible.
+    const hasNodeError = (validate.errors || []).some((e) =>
+      String(e.instancePath || '').startsWith('/nodes'),
+    );
+    const hasEdgeError = (validate.errors || []).some((e) =>
+      String(e.instancePath || '').startsWith('/edges'),
+    );
+    let code = 'GDD_GRAPH_SCHEMA_INVALID';
+    if (op === 'upsertNode' && hasNodeError) code = 'GDD_GRAPH_INVALID_NODE';
+    if (op === 'upsertEdge' && hasEdgeError) code = 'GDD_GRAPH_INVALID_EDGE';
+    const err = new Error(`${op}: graph failed schema validation`);
+    err.code = code;
+    err.schemaErrors = validate.errors;
+    throw err;
+  }
+}