vibepro 0.1.0-alpha.0

package/src/spec-schema.json

@@ -0,0 +1,219 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://vibepro.local/schemas/spec.json",
+  "title": "VibePro Inferred Spec",
+  "description": "AI-authored spec produced from Story+Code+Test fingerprints. VibePro CLI validates and stores this artifact; humans do not edit it directly.",
+  "type": "object",
+  "required": ["schema_version", "story_id", "clauses"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "0.1.0"
+    },
+    "story_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "generated_at": {
+      "type": "string",
+      "description": "ISO 8601 timestamp. Filled by validator if absent."
+    },
+    "generated_by": {
+      "type": "object",
+      "properties": {
+        "caller": {
+          "type": "string",
+          "description": "claude-code | codex | other identifier"
+        },
+        "stage": {
+          "type": "string",
+          "enum": ["ai_synthesis", "static_fallback"]
+        }
+      }
+    },
+    "inputs_digest": {
+      "type": "object",
+      "properties": {
+        "story_sha": { "type": "string" },
+        "code_sha": { "type": "string" },
+        "test_sha": { "type": "string" }
+      }
+    },
+    "previous_spec_id": {
+      "type": ["string", "null"]
+    },
+    "clauses": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/clause" }
+    },
+    "diagrams": {
+      "type": "array",
+      "description": "Design diagrams required by the change type. See diagram-requirement-resolver for which kinds are mandatory.",
+      "items": { "$ref": "#/$defs/diagram" }
+    },
+    "open_questions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "question"],
+        "properties": {
+          "id": { "type": "string" },
+          "question": { "type": "string", "minLength": 1 },
+          "blocker": { "type": "boolean" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "clause": {
+      "type": "object",
+      "required": ["id", "type", "statement", "origin"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Clause id. Use INV-<n>, S-<n>, C-<n>, SLA-<n>. New clauses may use INV-NEW-<n> placeholders; validator assigns stable ids."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["invariant", "scenario", "contract", "sla"]
+        },
+        "statement": {
+          "type": "string",
+          "minLength": 4,
+          "description": "One-sentence machine-checkable statement. Avoid ambiguity."
+        },
+        "rationale": {
+          "type": "string",
+          "description": "Why this clause exists. Cite story acceptance criterion / code anchor."
+        },
+        "origin": {
+          "type": "object",
+          "description": "Where this clause was derived from. At least one of story_refs / architecture_refs / code_refs / test_refs must be non-empty.",
+          "properties": {
+            "story_refs": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["kind"],
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "enum": ["acceptance_criteria", "background", "policy", "frontmatter", "other"]
+                  },
+                  "index": { "type": "integer", "minimum": 0 },
+                  "text_snippet": { "type": "string" }
+                }
+              }
+            },
+            "architecture_refs": {
+              "type": "array",
+              "description": "Architecture, IA, route-flow, state, or boundary evidence that shaped this clause.",
+              "items": {
+                "type": "object",
+                "required": ["file"],
+                "properties": {
+                  "file": { "type": "string", "minLength": 1 },
+                  "section": { "type": "string" },
+                  "text_snippet": { "type": "string" }
+                }
+              }
+            },
+            "code_refs": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["file"],
+                "properties": {
+                  "file": { "type": "string", "minLength": 1 },
+                  "anchor": {
+                    "type": "string",
+                    "description": "Identifier or substring that should appear in the file."
+                  },
+                  "line": { "type": "integer", "minimum": 1 }
+                }
+              }
+            },
+            "test_refs": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["file"],
+                "properties": {
+                  "file": { "type": "string", "minLength": 1 },
+                  "case": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "verifiable_by": {
+          "type": "object",
+          "description": "Deterministic patterns the drift detector uses. Optional but recommended.",
+          "properties": {
+            "code_pattern": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/pattern" }
+            },
+            "test_pattern": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/pattern" }
+            }
+          }
+        },
+        "first_seen_at": { "type": "string" },
+        "last_revised_at": { "type": "string" }
+      }
+    },
+    "diagram": {
+      "type": "object",
+      "required": ["kind", "mermaid"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["er", "state", "sequence", "flow", "c4_context", "deployment", "threat_model", "dfd"]
+        },
+        "mermaid": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Mermaid source. First non-empty line must match the kind-specific prefix."
+        },
+        "entities": {
+          "type": "array",
+          "description": "Names that appear in the diagram. Required non-empty for er/state/sequence/c4_context.",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "rationale": {
+          "type": "string",
+          "description": "Why this diagram exists. Cite story acceptance criterion / code anchor."
+        }
+      }
+    },
+    "pattern": {
+      "type": "object",
+      "required": ["file_glob"],
+      "properties": {
+        "file_glob": {
+          "type": "string",
+          "description": "Glob relative to repo root. Examples: src/**/billing*.ts, test/**/*.test.{js,ts}"
+        },
+        "must_contain": {
+          "type": "string",
+          "description": "Substring (case-sensitive) that must appear in at least one matched file."
+        },
+        "must_not_contain": {
+          "type": "string",
+          "description": "Substring (case-sensitive) that must not appear in any matched file."
+        },
+        "must_cover": {
+          "type": "string",
+          "description": "Identifier or substring that must appear in test names or assertion text across matched files."
+        }
+      }
+    }
+  }
+}

package/src/spec-store.js

@@ -0,0 +1,258 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { WORKSPACE_DIR } from './workspace.js';
+
+export const SPEC_SCHEMA_VERSION = '0.1.0';
+const HISTORY_KEEP = 10;
+const SIMILARITY_THRESHOLD = 0.7;
+
+export function getSpecDir(repoRoot, storyId) {
+  if (!storyId) throw new Error('storyId is required');
+  return path.join(path.resolve(repoRoot), WORKSPACE_DIR, 'spec', storyId);
+}
+
+export function getSpecFile(repoRoot, storyId) {
+  return path.join(getSpecDir(repoRoot, storyId), 'spec.json');
+}
+
+export function getDriftFile(repoRoot, storyId) {
+  return path.join(getSpecDir(repoRoot, storyId), 'drift.json');
+}
+
+export function getDriftMarkdownFile(repoRoot, storyId) {
+  return path.join(getSpecDir(repoRoot, storyId), 'drift.md');
+}
+
+export function getSuppressionsFile(repoRoot, storyId) {
+  return path.join(getSpecDir(repoRoot, storyId), 'suppressions.json');
+}
+
+export async function ensureSpecDir(repoRoot, storyId) {
+  const dir = getSpecDir(repoRoot, storyId);
+  await mkdir(path.join(dir, 'spec.history'), { recursive: true });
+  return dir;
+}
+
+export async function readInferredSpec(repoRoot, storyId) {
+  if (!storyId) return null;
+  try {
+    return JSON.parse(await readFile(getSpecFile(repoRoot, storyId), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function readDrift(repoRoot, storyId) {
+  if (!storyId) return null;
+  try {
+    return JSON.parse(await readFile(getDriftFile(repoRoot, storyId), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function readSuppressions(repoRoot, storyId) {
+  try {
+    return JSON.parse(await readFile(getSuppressionsFile(repoRoot, storyId), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return { schema_version: SPEC_SCHEMA_VERSION, items: [] };
+    throw error;
+  }
+}
+
+export async function writeInferredSpec(repoRoot, storyId, spec) {
+  await ensureSpecDir(repoRoot, storyId);
+  const specPath = getSpecFile(repoRoot, storyId);
+  await writeFile(specPath, `${JSON.stringify(spec, null, 2)}\n`);
+
+  const historyDir = path.join(getSpecDir(repoRoot, storyId), 'spec.history');
+  const stamp = spec.generated_at?.replace(/[:.]/g, '-') ?? new Date().toISOString().replace(/[:.]/g, '-');
+  const historyPath = path.join(historyDir, `spec-${stamp}.json`);
+  await writeFile(historyPath, `${JSON.stringify(spec, null, 2)}\n`);
+  await pruneHistory(historyDir);
+  return specPath;
+}
+
+export async function writeDrift(repoRoot, storyId, drift) {
+  await ensureSpecDir(repoRoot, storyId);
+  const driftPath = getDriftFile(repoRoot, storyId);
+  await writeFile(driftPath, `${JSON.stringify(drift, null, 2)}\n`);
+  return driftPath;
+}
+
+export async function writeDriftMarkdown(repoRoot, storyId, markdown) {
+  await ensureSpecDir(repoRoot, storyId);
+  const driftPath = getDriftMarkdownFile(repoRoot, storyId);
+  await writeFile(driftPath, markdown.endsWith('\n') ? markdown : `${markdown}\n`);
+  return driftPath;
+}
+
+export async function writeSuppressions(repoRoot, storyId, suppressions) {
+  await ensureSpecDir(repoRoot, storyId);
+  const target = getSuppressionsFile(repoRoot, storyId);
+  await writeFile(target, `${JSON.stringify(suppressions, null, 2)}\n`);
+  return target;
+}
+
+async function pruneHistory(historyDir) {
+  let entries;
+  try {
+    entries = await readdir(historyDir);
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+  const sorted = entries
+    .filter((name) => name.startsWith('spec-') && name.endsWith('.json'))
+    .sort()
+    .reverse();
+  const stale = sorted.slice(HISTORY_KEEP);
+  if (stale.length === 0) return;
+  const { rm } = await import('node:fs/promises');
+  await Promise.all(stale.map((name) => rm(path.join(historyDir, name), { force: true })));
+}
+
+export function stabilizeClauseIds(newSpec, previousSpec) {
+  if (!previousSpec || !Array.isArray(previousSpec.clauses)) {
+    return assignFreshIds(newSpec);
+  }
+
+  const usedPreviousIds = new Set();
+  const usedNewIds = new Set();
+  const issuedAt = new Date().toISOString();
+
+  const claimMatch = (clause) => {
+    let best = null;
+    for (const prev of previousSpec.clauses) {
+      if (usedPreviousIds.has(prev.id)) continue;
+      if (prev.type !== clause.type) continue;
+      const score = similarity(clause.statement, prev.statement);
+      if (!best || score > best.score) best = { clause: prev, score };
+    }
+    if (best && best.score >= SIMILARITY_THRESHOLD) {
+      usedPreviousIds.add(best.clause.id);
+      return best.clause;
+    }
+    return null;
+  };
+
+  const clauses = newSpec.clauses.map((clause) => {
+    const match = claimMatch(clause);
+    if (match) {
+      usedNewIds.add(match.id);
+      return {
+        ...clause,
+        id: match.id,
+        first_seen_at: match.first_seen_at ?? issuedAt,
+        last_revised_at: issuedAt
+      };
+    }
+    return {
+      ...clause,
+      id: nextFreshId(clause, usedNewIds, previousSpec, issuedAt),
+      first_seen_at: issuedAt,
+      last_revised_at: issuedAt
+    };
+  });
+
+  return { ...newSpec, clauses };
+}
+
+function assignFreshIds(spec) {
+  const usedIds = new Set();
+  const issuedAt = new Date().toISOString();
+  const clauses = (spec.clauses ?? []).map((clause) => ({
+    ...clause,
+    id: nextFreshId(clause, usedIds, null, issuedAt),
+    first_seen_at: clause.first_seen_at ?? issuedAt,
+    last_revised_at: issuedAt
+  }));
+  return { ...spec, clauses };
+}
+
+function nextFreshId(clause, usedIds, previousSpec, issuedAt) {
+  const prefix = clausePrefix(clause.type);
+  const reserved = new Set(usedIds);
+  if (previousSpec && Array.isArray(previousSpec.clauses)) {
+    for (const prev of previousSpec.clauses) reserved.add(prev.id);
+  }
+  let n = 1;
+  while (reserved.has(`${prefix}-${pad3(n)}`)) n += 1;
+  const id = `${prefix}-${pad3(n)}`;
+  usedIds.add(id);
+  return id;
+}
+
+function clausePrefix(type) {
+  switch (type) {
+    case 'invariant': return 'INV';
+    case 'scenario': return 'S';
+    case 'contract': return 'C';
+    case 'sla': return 'SLA';
+    default: return 'X';
+  }
+}
+
+function pad3(n) {
+  return String(n).padStart(3, '0');
+}
+
+export function similarity(a, b) {
+  const sa = normalizeStatement(a);
+  const sb = normalizeStatement(b);
+  if (!sa || !sb) return 0;
+  if (sa === sb) return 1;
+  const tokenSim = jaccardTokens(sa, sb);
+  const editSim = 1 - levenshteinNormalized(sa, sb);
+  return tokenSim * 0.6 + editSim * 0.4;
+}
+
+function normalizeStatement(text) {
+  if (typeof text !== 'string') return '';
+  return text.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function jaccardTokens(a, b) {
+  const ta = new Set(tokenize(a));
+  const tb = new Set(tokenize(b));
+  if (ta.size === 0 && tb.size === 0) return 1;
+  let intersection = 0;
+  for (const t of ta) if (tb.has(t)) intersection += 1;
+  const union = ta.size + tb.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+function tokenize(text) {
+  return text
+    .replace(/[\p{P}\p{S}]/gu, ' ')
+    .split(/\s+/)
+    .filter((token) => token.length >= 2);
+}
+
+function levenshteinNormalized(a, b) {
+  const max = Math.max(a.length, b.length);
+  if (max === 0) return 0;
+  return levenshtein(a, b) / max;
+}
+
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array(n + 1);
+  let curr = new Array(n + 1);
+  for (let j = 0; j <= n; j += 1) prev[j] = j;
+  for (let i = 1; i <= m; i += 1) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j += 1) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}