@davesheffer/hunch 0.1.0

package/dist/store/jsonStore.js

@@ -0,0 +1,268 @@
+/**
+ * The JSON source of truth under .hunch/. One file per entity (human-reviewable
+ * in PRs, diffable, mergeable). This layer never touches SQLite — it is the
+ * authoritative read/write surface; SQLite is rebuilt from it.
+ */
+import { mkdirSync, readdirSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
+import { migrateRaw, readManifest, writeManifest, SCHEMA_VERSION } from "../core/migrate.js";
+import { writeFileAtomic } from "../core/io.js";
+/** High-cardinality collections (symbols, edges) are stored as a single
+ *  index.json array — there can be thousands, and one file per edge would create
+ *  enormous git noise. Curated, low-volume entities (components, decisions, bugs,
+ *  constraints) are one file per record so they're cleanly reviewable in PRs. */
+const SINGLE_FILE = { symbols: "index.json", edges: "index.json" };
+const encode = (v) => JSON.stringify(v, null, 2) + "\n";
+export class JsonStore {
+    paths;
+    _warnedForward = false;
+    constructor(paths) {
+        this.paths = paths;
+    }
+    /** Create .hunch/<kind>/ directories. Stamp the manifest at the CURRENT version
+     *  only when scaffolding a FRESH .hunch/ (so `hunch index`/`sync` on a brand-new
+     *  repo records the version too, not just `init`). A pre-existing .hunch/ without
+     *  a manifest is LEGACY — left unstamped so it defaults to the baseline and
+     *  `hunch migrate` upgrades it. */
+    ensureDirs() {
+        const fresh = !existsSync(this.paths.hunch);
+        mkdirSync(this.paths.hunch, { recursive: true });
+        for (const kind of ENTITY_KINDS)
+            mkdirSync(this.paths.dir(kind), { recursive: true });
+        if (fresh && !existsSync(this.paths.manifest))
+            writeManifest(this.paths, SCHEMA_VERSION);
+    }
+    /** The on-disk schema version (from the manifest), read FRESH each call so a
+     *  long-lived process (the MCP server) reflects an out-of-band `hunch migrate`. */
+    schemaVersion() {
+        const v = readManifest(this.paths).schema_version;
+        if (v > SCHEMA_VERSION && !this._warnedForward) {
+            this._warnedForward = true;
+            console.warn(`[hunch] .hunch/ was written by a newer schema (v${v} > v${SCHEMA_VERSION}); ` +
+                `records may not load correctly — upgrade hunch.`);
+        }
+        return v;
+    }
+    /** Migrate one raw record UP to the current schema before validation, so a
+     *  schema bump never makes the loader silently skip (drop) old records. The
+     *  on-disk `version` is read ONCE per load (not per record) by the caller. */
+    migrate(kind, raw, version) {
+        return migrateRaw(kind, raw, version);
+    }
+    fileFor(kind, id) {
+        const single = SINGLE_FILE[kind];
+        if (single)
+            return join(this.paths.dir(kind), single);
+        return join(this.paths.dir(kind), `${id}.json`);
+    }
+    /** Load every record of a kind, validated against its schema. Invalid records
+     *  are skipped with a warning rather than crashing the whole load. */
+    loadAll(kind) {
+        const dir = this.paths.dir(kind);
+        if (!existsSync(dir))
+            return [];
+        const schema = SCHEMAS[kind];
+        const out = [];
+        const version = this.schemaVersion(); // read the manifest ONCE per load, not per record
+        const single = SINGLE_FILE[kind];
+        if (single) {
+            const f = join(dir, single);
+            if (!existsSync(f))
+                return [];
+            let arr;
+            try {
+                arr = JSON.parse(readFileSync(f, "utf8"));
+            }
+            catch (e) {
+                console.warn(`[hunch] skipping corrupt ${kind}/${single}: ${e.message}`);
+                return out;
+            }
+            for (const raw of Array.isArray(arr) ? arr : []) {
+                const r = schema.safeParse(this.migrate(kind, raw, version));
+                if (r.success)
+                    out.push(r.data);
+                else
+                    console.warn(`[hunch] skipping invalid ${kind} record: ${r.error.issues[0]?.message}`);
+            }
+            return out;
+        }
+        for (const name of readdirSync(dir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            let raw;
+            try {
+                raw = JSON.parse(readFileSync(join(dir, name), "utf8"));
+            }
+            catch (e) {
+                console.warn(`[hunch] skipping corrupt ${kind}/${name}: ${e.message}`);
+                continue;
+            }
+            const r = schema.safeParse(this.migrate(kind, raw, version));
+            if (r.success)
+                out.push(r.data);
+            else
+                console.warn(`[hunch] skipping invalid ${kind}/${name}: ${r.error.issues[0]?.message}`);
+        }
+        return out;
+    }
+    /** Write a single record (validated) to its JSON file / into the index array. */
+    put(kind, record) {
+        const schema = SCHEMAS[kind];
+        const validated = schema.parse(record);
+        mkdirSync(this.paths.dir(kind), { recursive: true });
+        const single = SINGLE_FILE[kind];
+        if (single) {
+            // Operate on the RAW array (NOT the validating loadAll) so updating one
+            // record can't silently drop schema-invalid / future-schema siblings — the
+            // same reason delete() reads raw. Keep the index sorted by id (stable diff,
+            // and agrees with the merge driver so a re-index after a merge is a no-op).
+            const f = this.fileFor(kind, validated.id);
+            const arr = this.readRawArray(f).filter((r) => r?.id !== validated.id);
+            arr.push(validated);
+            arr.sort((a, b) => String(a?.id).localeCompare(String(b?.id)));
+            writeFileAtomic(f, encode(arr));
+        }
+        else {
+            writeFileAtomic(this.fileFor(kind, validated.id), encode(validated));
+        }
+        return validated;
+    }
+    /** Bulk replace all records of a kind (used by the extractor for symbols/edges). */
+    replaceAll(kind, records) {
+        const schema = SCHEMAS[kind];
+        const validated = records.map((r) => schema.parse(r));
+        mkdirSync(this.paths.dir(kind), { recursive: true });
+        const single = SINGLE_FILE[kind];
+        if (single) {
+            // Sorted by id so the index has ONE canonical order — re-indexing after a
+            // git merge (which the driver also id-sorts) doesn't churn the whole file.
+            validated.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+            writeFileAtomic(this.fileFor(kind, "index"), encode(validated));
+            return;
+        }
+        // one file per record: clear stale files, then write
+        for (const name of existsSync(this.paths.dir(kind)) ? readdirSync(this.paths.dir(kind)) : []) {
+            if (name.endsWith(".json"))
+                rmSync(join(this.paths.dir(kind), name));
+        }
+        for (const r of validated) {
+            writeFileAtomic(this.fileFor(kind, r.id), encode(r));
+        }
+    }
+    /** Read a single-file index as a raw array (no validation). Missing/empty → [].
+     *  A non-empty file that fails to parse THROWS — we must never silently treat a
+     *  corrupt index as empty and then rewrite it, which would flatten every existing
+     *  record. (`hunch index` rebuilds from scratch via replaceAll to recover.) */
+    readRawArray(f) {
+        if (!existsSync(f))
+            return [];
+        const text = readFileSync(f, "utf8");
+        if (!text.trim())
+            return [];
+        let v;
+        try {
+            v = JSON.parse(text);
+        }
+        catch (e) {
+            throw new Error(`refusing to rewrite ${f}: the existing index is not valid JSON (${e.message}). Fix or remove it, then re-run \`hunch index\`.`);
+        }
+        return Array.isArray(v) ? v : [];
+    }
+    get(kind, id) {
+        return this.loadAll(kind).find((r) => r.id === id);
+    }
+    /** Remove a record (used by the curate/reject flow). Returns true if removed.
+     *  For single-file kinds we operate on the RAW JSON array (not the validating
+     *  loader) so deleting one record can't silently drop schema-invalid siblings. */
+    delete(kind, id) {
+        const single = SINGLE_FILE[kind];
+        if (single) {
+            const f = this.fileFor(kind, "index");
+            if (!existsSync(f))
+                return false;
+            const arr = this.readRawArray(f);
+            const next = arr.filter((r) => r?.id !== id);
+            if (next.length === arr.length)
+                return false;
+            writeFileAtomic(f, encode(next));
+            return true;
+        }
+        const f = this.fileFor(kind, id);
+        if (!existsSync(f))
+            return false;
+        rmSync(f);
+        return true;
+    }
+    /** Persist a schema migration: rewrite every LOADABLE record in its current shape.
+     *  A record that still fails validation after migration is kept untouched (never
+     *  deleted) and counted as `skipped`, so migration can't lose data. The caller
+     *  bumps the manifest afterward. */
+    persistMigration() {
+        let migrated = 0;
+        let skipped = 0;
+        const version = this.schemaVersion(); // read once; we're migrating FROM this
+        for (const kind of ENTITY_KINDS) {
+            const dir = this.paths.dir(kind);
+            if (!existsSync(dir))
+                continue;
+            const schema = SCHEMAS[kind];
+            const single = SINGLE_FILE[kind];
+            if (single) {
+                const f = join(dir, single);
+                if (!existsSync(f))
+                    continue;
+                let arr;
+                try {
+                    arr = JSON.parse(readFileSync(f, "utf8"));
+                }
+                catch {
+                    skipped++;
+                    continue;
+                }
+                if (!Array.isArray(arr)) {
+                    skipped++;
+                    continue;
+                }
+                const kept = [];
+                for (const raw of arr) {
+                    const r = schema.safeParse(this.migrate(kind, raw, version));
+                    if (r.success) {
+                        kept.push(r.data);
+                        migrated++;
+                    }
+                    else {
+                        kept.push(raw); // preserve unmigratable records rather than drop them
+                        skipped++;
+                    }
+                }
+                writeFileAtomic(f, encode(kept));
+            }
+            else {
+                for (const name of readdirSync(dir)) {
+                    if (!name.endsWith(".json"))
+                        continue;
+                    const p = join(dir, name);
+                    let raw;
+                    try {
+                        raw = JSON.parse(readFileSync(p, "utf8"));
+                    }
+                    catch {
+                        skipped++;
+                        continue;
+                    }
+                    const r = schema.safeParse(this.migrate(kind, raw, version));
+                    if (r.success) {
+                        writeFileAtomic(p, encode(r.data));
+                        migrated++;
+                    }
+                    else {
+                        skipped++; // leave the file as-is
+                    }
+                }
+            }
+        }
+        return { migrated, skipped };
+    }
+}
+//# sourceMappingURL=jsonStore.js.map

package/dist/store/merge.js

@@ -0,0 +1,179 @@
+/**
+ * Structured three-way merge of `.hunch/` JSON for TEAM workflows.
+ *
+ * Concurrent branches both writing the Hunch conflict on `git merge`: the
+ * single-file symbols/edges index is rewritten wholesale by `hunch index`, and two
+ * people can touch the same decision/bug/constraint. A registered git merge driver
+ * (`hunch merge-driver`, wired up by `hunch init`) calls mergeHunchJson per
+ * conflicted file so records merge BY ID instead of leaving conflict markers.
+ *
+ * Scope: git only invokes a content merge driver when the SAME path differs on both
+ * sides — so this resolves (a) the symbols/edges index ARRAY and (b) edits to the
+ * same id in the same per-record file. Per-record ADD/DELETE across branches are
+ * distinct files and git handles them at the tree level (the driver isn't called).
+ *
+ * Resolution for a record changed on BOTH sides: human-confirmed beats auto, then
+ * higher provenance.confidence, then the more recently verified, then a deterministic
+ * content tiebreak (so both developers' merges converge on the same result). Records
+ * are pure data here — no filesystem access; the CLI reads/writes the files.
+ */
+/** Merge three versions of one `.hunch` JSON file (an index array OR a single
+ *  record object). Returns the merged text, or conflict=true to fall back. */
+export function mergeHunchJson(baseText, oursText, theirsText) {
+    const ours = parseSide(oursText);
+    const theirs = parseSide(theirsText);
+    const base = parseSide(baseText);
+    // Can't structurally merge non-JSON or id-less records → let git handle it.
+    if (!ours.ok || !theirs.ok)
+        return { text: oursText, conflict: true };
+    if (!hasIds(ours.records) || !hasIds(theirs.records))
+        return { text: oursText, conflict: true };
+    const merged = mergeRecordsById(base.ok ? base.records : [], ours.records, theirs.records);
+    merged.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+    // An index file stays an array; a per-record file stays a single object.
+    const asArray = ours.isArray || theirs.isArray;
+    if (asArray)
+        return { text: serialize(merged), conflict: false };
+    if (merged.length === 0)
+        return { text: "", conflict: false }; // both deleted the record
+    // A single-record file that produced >1 record means a side rewrote the `id`
+    // (a logical rename). Don't silently drop one — fall back so git surfaces it.
+    if (merged.length > 1)
+        return { text: oursText, conflict: true };
+    return { text: serialize(merged[0]), conflict: false };
+}
+/** Three-way merge of record arrays keyed by `id`. Additions on either side are
+ *  kept; a record changed on one side only takes that side; a delete is honored
+ *  only if the other side left the record unchanged (a modification beats a delete);
+ *  a both-sides change is resolved by `pickWinner`. */
+export function mergeRecordsById(base, ours, theirs) {
+    const b = byId(base);
+    const o = byId(ours);
+    const t = byId(theirs);
+    const ids = new Set([...o.keys(), ...t.keys(), ...b.keys()]);
+    const out = [];
+    for (const id of ids) {
+        const bv = b.get(id);
+        const ov = o.get(id);
+        const tv = t.get(id);
+        if (ov && tv) {
+            if (canon(ov) === canon(tv))
+                out.push(ov);
+            else if (bv && canon(ov) === canon(bv))
+                out.push(tv); // only theirs changed
+            else if (bv && canon(tv) === canon(bv))
+                out.push(ov); // only ours changed
+            else
+                out.push(pickWinner(ov, tv)); // both changed (or both added differently)
+        }
+        else if (ov && !tv) {
+            // theirs lacks it: a delete (bv present & ours unchanged) loses to a keep/modify
+            if (bv && canon(ov) === canon(bv))
+                continue; // theirs deleted, ours unchanged → drop
+            out.push(ov); // ours added, or ours modified vs a theirs-delete → keep ours
+        }
+        else if (!ov && tv) {
+            if (bv && canon(tv) === canon(bv))
+                continue; // ours deleted, theirs unchanged → drop
+            out.push(tv);
+        }
+        // neither side has it → both deleted → drop
+    }
+    return out;
+}
+/** Both sides changed the same record: pick the one to keep. */
+export function pickWinner(ours, theirs) {
+    const oc = humanConfirmed(ours);
+    const tc = humanConfirmed(theirs);
+    if (oc !== tc)
+        return oc ? ours : theirs; // human-confirmed beats auto
+    const od = confidence(ours);
+    const td = confidence(theirs);
+    if (od !== td)
+        return od > td ? ours : theirs;
+    const orr = recency(ours);
+    const tr = recency(theirs);
+    if (orr !== tr)
+        return orr > tr ? ours : theirs;
+    // Deterministic, side-independent tiebreak so A-merges-B and B-merges-A agree.
+    return canon(ours) >= canon(theirs) ? ours : theirs;
+}
+function parseSide(text) {
+    const trimmed = (text ?? "").trim();
+    if (!trimmed)
+        return { ok: true, isArray: false, records: [] }; // empty (e.g. deleted) side
+    let v;
+    try {
+        v = JSON.parse(trimmed);
+    }
+    catch {
+        return { ok: false, isArray: false, records: [] };
+    }
+    if (Array.isArray(v))
+        return { ok: true, isArray: true, records: v.filter(isRec) };
+    if (isRec(v))
+        return { ok: true, isArray: false, records: [v] };
+    return { ok: false, isArray: false, records: [] };
+}
+function isRec(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function hasIds(records) {
+    return records.every((r) => typeof r.id === "string" && r.id.length > 0);
+}
+function byId(records) {
+    const m = new Map();
+    for (const r of records)
+        if (typeof r.id === "string")
+            m.set(r.id, r);
+    return m;
+}
+function humanConfirmed(r) {
+    return /human_confirmed/.test(provSource(r));
+}
+function provSource(r) {
+    const p = r.provenance;
+    return isRec(p) && typeof p.source === "string" ? p.source : "";
+}
+function confidence(r) {
+    const p = r.provenance;
+    return isRec(p) && typeof p.confidence === "number" ? p.confidence : 0;
+}
+/** Most recent timestamp on the record (verified / decided / updated), epoch ms. */
+function recency(r) {
+    const p = r.provenance;
+    const cands = [
+        isRec(p) ? p.last_verified : undefined,
+        r.date,
+        r.updated_at,
+    ];
+    let best = 0;
+    for (const c of cands) {
+        if (typeof c === "string") {
+            const t = Date.parse(c);
+            if (!Number.isNaN(t) && t > best)
+                best = t;
+        }
+    }
+    return best;
+}
+/** Stable JSON with recursively SORTED keys, so equality/compare ignore key order. */
+export function canon(v) {
+    return JSON.stringify(sortKeys(v));
+}
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v !== null && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort())
+            out[k] = sortKeys(v[k]);
+        return out;
+    }
+    return v;
+}
+/** Match the store's on-disk format (2-space indent + trailing newline). */
+function serialize(v) {
+    return JSON.stringify(v, null, 2) + "\n";
+}
+//# sourceMappingURL=merge.js.map

package/dist/store/schema.js

@@ -0,0 +1,100 @@
+/**
+ * SQLite schema for the DERIVED index (DESIGN.md §2.1 / §6).
+ *
+ * The JSON files under .hunch/ are the source of truth; this database is rebuilt
+ * from them by `hunch index`. JSON-array/object fields are stored as TEXT (JSON)
+ * — we only need them indexed where we query them. Search is a single unified
+ * FTS5 table; the graph is plain tables walked with recursive CTEs.
+ */
+import { createHash } from "node:crypto";
+/** Canonical content hash of the exact title+body that fed both FTS and the
+ *  embedding for a doc. Stored in `embeddings.doc_hash` so reindex can tell, with
+ *  NO model loaded, whether a stored vector is stale (its source text changed).
+ *  The NUL separator keeps the title/body boundary unambiguous. */
+export function embedHash(title, body) {
+    return createHash("sha1").update(title).update("\x00").update(body ?? "").digest("hex").slice(0, 16);
+}
+export const SCHEMA_SQL = /* sql */ `
+PRAGMA journal_mode = WAL;
+PRAGMA foreign_keys = OFF;
+
+CREATE TABLE IF NOT EXISTS components (
+  id TEXT PRIMARY KEY,
+  kind TEXT, name TEXT, responsibility TEXT,
+  paths TEXT, status TEXT, owners TEXT,
+  fragility REAL,
+  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT,
+  created_at TEXT, updated_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  id TEXT PRIMARY KEY,
+  "from" TEXT, "to" TEXT, type TEXT, reason TEXT, strength REAL,
+  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges("from");
+CREATE INDEX IF NOT EXISTS idx_edges_to ON edges("to");
+CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type);
+
+CREATE TABLE IF NOT EXISTS symbols (
+  id TEXT PRIMARY KEY,
+  file TEXT, name TEXT, kind TEXT, signature_hash TEXT,
+  calls TEXT, called_by TEXT,
+  loc INTEGER, churn_90d INTEGER, bug_count INTEGER, fan_in INTEGER, fan_out INTEGER,
+  last_changed TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file);
+CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
+
+CREATE TABLE IF NOT EXISTS decisions (
+  id TEXT PRIMARY KEY,
+  title TEXT, status TEXT, context TEXT, decision TEXT,
+  consequences TEXT, alternatives_rejected TEXT,
+  related_components TEXT, related_files TEXT,
+  supersedes TEXT, caused_by_bug TEXT, "commit" TEXT,
+  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT,
+  date TEXT
+);
+
+CREATE TABLE IF NOT EXISTS bugs (
+  id TEXT PRIMARY KEY,
+  title TEXT, symptom TEXT, root_cause TEXT, severity TEXT, status TEXT,
+  affected_files TEXT, affected_symbols TEXT, lineage TEXT,
+  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT
+);
+
+CREATE TABLE IF NOT EXISTS constraints (
+  id TEXT PRIMARY KEY,
+  type TEXT, statement TEXT, scope TEXT, severity TEXT, enforcement TEXT,
+  rationale TEXT, source_decision TEXT, violations TEXT,
+  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT
+);
+
+-- Unified full-text search across every entity. Rebuilt on index; bm25-ranked.
+CREATE VIRTUAL TABLE IF NOT EXISTS search USING fts5(
+  ref UNINDEXED,   -- entity id
+  kind UNINDEXED,  -- components | edges | symbols | decisions | bugs | constraints
+  title,
+  body,
+  tokenize = 'porter unicode61'
+);
+
+-- Local semantic-search vectors (opt-in; written by \`hunch embed\`). One row per
+-- (ref, model); vec is a Float32 BLOB. DELIBERATELY NOT in RESET_SQL: reindex()
+-- runs RESET on nearly every path (MCP startup, every query/context), so resetting
+-- embeddings here would wipe them constantly and make the feature a no-op. Staleness
+-- is tracked by doc_hash and reconciled by pruneStaleEmbeddings() instead. Recall is
+-- exact brute-force cosine in JS (graphs are small); sqlite-vec only past ~100k rows.
+CREATE TABLE IF NOT EXISTS embeddings (
+  ref TEXT, kind TEXT, model TEXT, dim INTEGER, doc_hash TEXT, vec BLOB,
+  PRIMARY KEY (ref, model)
+);
+`;
+/** Drop derived data (used before a full reindex). NOTE: embeddings is omitted on
+ *  purpose — see the embeddings table comment above. */
+export const RESET_SQL = /* sql */ `
+DELETE FROM components; DELETE FROM edges; DELETE FROM symbols;
+DELETE FROM decisions; DELETE FROM bugs; DELETE FROM constraints;
+DELETE FROM search;
+`;
+//# sourceMappingURL=schema.js.map