homegraph 1.1.2 → 1.2.0

package/dist/spec/evolve/spec-rewriter.js

@@ -0,0 +1,230 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateSpec = evaluateSpec;
+exports.applyUpdate = applyUpdate;
+exports.applyDeprecate = applyDeprecate;
+/**
+ * Spec rewriter — evaluates a commit's impact on a design spec and applies
+ * UPDATE / DEPRECATE decisions.
+ *
+ * Replaces `commit4spec/self_evolve/spec_rewriter.py` (lines 1-231).
+ *
+ * @module spec/evolve/spec-rewriter
+ */
+const fs = __importStar(require("fs"));
+const utils_1 = require("../utils");
+const spec_node_1 = require("../db/spec-node");
+const relations_1 = require("../db/relations");
+const spec_extractor_1 = require("../mining/spec-extractor");
+const prompts_1 = require("../llm/prompts");
+const errors_1 = require("../../errors");
+// =============================================================================
+// evaluateSpec
+// =============================================================================
+/**
+ * Ask the LLM whether a commit requires updating, deprecating, or leaving
+ * a spec unchanged.
+ *
+ * @param specId            - The spec identifier (for logging / context).
+ * @param specStoragePath   - Root spec storage directory.
+ * @param specFilePath      - Absolute path to the plan.md file.
+ * @param commitMessage     - First line of the commit message.
+ * @param commitDiff        - Full unified diff of the commit.
+ * @param scheduleNextSpecs - Remaining spec IDs to be processed (for context).
+ * @param client            - Optional LLM client; if absent, returns UNCHANGED.
+ */
+async function evaluateSpec(specId, _specStoragePath, specFilePath, commitMessage, commitDiff, scheduleNextSpecs, client) {
+    // 1. Read plan content
+    const planContent = (0, utils_1.readFileContent)(specFilePath);
+    if (planContent === null) {
+        (0, errors_1.logDebug)('evaluateSpec: plan file not found, returning UNCHANGED', {
+            specId,
+            specFilePath,
+        });
+        return { action: 'UNCHANGED' };
+    }
+    // 2. Truncate commitDiff to 6000 chars
+    const truncatedDiff = (0, utils_1.truncateText)(commitDiff, 6000);
+    // 3. Build user prompt
+    const userPrompt = (0, prompts_1.buildSpecEvaluationUserPrompt)(planContent, commitMessage, truncatedDiff, scheduleNextSpecs);
+    // 4. Call LLM
+    if (!client) {
+        (0, errors_1.logDebug)('evaluateSpec: no LLM client, returning UNCHANGED', { specId });
+        return { action: 'UNCHANGED' };
+    }
+    const result = await client.chatJson(prompts_1.SPEC_EVALUATION_SYSTEM_PROMPT, userPrompt);
+    // 5. Validate action
+    const rawAction = result.action;
+    let action = 'UNCHANGED';
+    if (rawAction === 'UPDATE' || rawAction === 'DEPRECATE' || rawAction === 'UNCHANGED') {
+        action = rawAction;
+    }
+    else {
+        (0, errors_1.logWarn)('evaluateSpec: unknown action from LLM, defaulting to UNCHANGED', {
+            specId,
+            rawAction: String(rawAction),
+        });
+    }
+    // 6. Return EvolveDecision
+    return {
+        action,
+        title: typeof result.title === 'string' ? result.title : undefined,
+        subtitles: Array.isArray(result.subtitles)
+            ? result.subtitles.filter((s) => typeof s === 'string')
+            : undefined,
+        plan_content: typeof result.plan_content === 'string' ? result.plan_content : undefined,
+    };
+}
+// =============================================================================
+// applyUpdate
+// =============================================================================
+/**
+ * Apply an UPDATE decision: backup the old plan, write the new plan, version
+ * the spec in the database, and transfer relations.
+ *
+ * 10-step process (ported from spec_rewriter.py:79-178).
+ *
+ * @returns The new spec ID (same as old) and bumped version number.
+ */
+function applyUpdate(db, specStoragePath, oldSpecId, oldFilePath, oldVersion, decision, commitHash) {
+    // ---- Step 1: Write new plan content to temp file ----
+    // We write to a temp file first so the original is preserved until every
+    // DB operation succeeds.  If the caller's transaction rolls back, the
+    // temp file is harmless garbage — the original plan.md is untouched.
+    const tmpPath = oldFilePath + '.new';
+    (0, utils_1.writeFileContent)(tmpPath, decision.plan_content || '');
+    // ---- Step 2: Extract new metadata from the temp file ----
+    const metadata = (0, spec_extractor_1.extractSpecMetadata)(specStoragePath, oldSpecId);
+    const metadataTitle = metadata?.title;
+    const metadataSubtitles = metadata?.subtitles;
+    // ---- Step 3: Read old spec data ----
+    const oldSpec = (0, spec_node_1.findSpecById)(db, oldSpecId);
+    if (!oldSpec) {
+        (0, errors_1.logDebug)('applyUpdate: old spec not found in DB, returning early', {
+            oldSpecId,
+        });
+        // Clean up the temp file — no DB changes were made.
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { /* best-effort */ }
+        return { newSpecId: oldSpecId, newVersion: oldVersion + 1 };
+    }
+    // ---- Step 4: Insert deprecated record ----
+    const bakPath = oldFilePath + '.bak';
+    const deprecatedId = `${oldSpecId}_v${oldVersion}`;
+    (0, spec_node_1.insertSpecNode)(db, {
+        id: deprecatedId,
+        title: oldSpec.title,
+        subtitles: oldSpec.subtitles,
+        status: 'deprecated',
+        version: oldVersion,
+        filePath: bakPath,
+        timestamp: Date.now(),
+    });
+    // ---- Step 5: Transfer relations from old active to deprecated ----
+    (0, relations_1.transferSpecCommitRelations)(db, oldSpecId, deprecatedId);
+    (0, relations_1.transferSpecSpecRelations)(db, oldSpecId, deprecatedId);
+    // ---- Step 6: Delete old active spec ----
+    (0, spec_node_1.deleteSpec)(db, oldSpecId);
+    // ---- Step 7: Insert new active spec ----
+    const newVersion = oldVersion + 1;
+    (0, spec_node_1.insertSpecNode)(db, {
+        id: oldSpecId,
+        title: decision.title || metadataTitle || oldSpecId,
+        subtitles: decision.subtitles || metadataSubtitles || [],
+        status: 'active',
+        version: newVersion,
+        filePath: oldFilePath,
+        timestamp: Date.now(),
+    });
+    // ---- Step 8: Create EVOLVED_FROM relation ----
+    (0, relations_1.insertSpecSpecRelation)(db, oldSpecId, deprecatedId, 'EVOLVED_FROM');
+    // ---- Step 9: Create GENERATE relation ----
+    (0, relations_1.insertSpecCommitRelation)(db, oldSpecId, commitHash, 'GENERATE');
+    // ---- Step 10: File system finalisation ----
+    // Only now — after all DB ops succeeded — do we touch the original disk
+    // files.  rename() is atomic on the same filesystem.
+    try {
+        fs.renameSync(oldFilePath, bakPath);
+    }
+    catch {
+        (0, errors_1.logDebug)('applyUpdate: backup rename failed (file may be missing), continuing', {
+            oldFilePath,
+            bakPath,
+        });
+    }
+    try {
+        fs.renameSync(tmpPath, oldFilePath);
+    }
+    catch {
+        (0, errors_1.logDebug)('applyUpdate: temp rename failed, leaving .new in place', {
+            tmpPath,
+            oldFilePath,
+        });
+    }
+    return { newSpecId: oldSpecId, newVersion };
+}
+// =============================================================================
+// applyDeprecate
+// =============================================================================
+/**
+ * Apply a DEPRECATE decision: mark the spec as deprecated, create a
+ * deprecated target node, create the EVOLVED_FROM relation, and clean
+ * SIMILAR_TO relations.
+ *
+ * Ported from spec_rewriter.py:181-231.
+ */
+function applyDeprecate(db, oldSpecId) {
+    // 1. Mark the spec as deprecated
+    (0, spec_node_1.updateSpecStatus)(db, oldSpecId, 'deprecated');
+    // 2. Create deprecated target node
+    const deprecatedTargetId = `${oldSpecId}_deprecated`;
+    (0, spec_node_1.insertSpecNode)(db, {
+        id: deprecatedTargetId,
+        status: 'deprecated',
+        version: 1,
+        title: oldSpecId,
+        subtitles: [],
+        filePath: '', // Synthetic deprecated node — no on-disk file.
+        timestamp: Date.now(),
+    });
+    // 3. Create EVOLVED_FROM relation
+    (0, relations_1.insertSpecSpecRelation)(db, oldSpecId, deprecatedTargetId, 'EVOLVED_FROM');
+    // 4. Clean SIMILAR_TO relations
+    (0, relations_1.deleteSimilarToRelations)(db, oldSpecId);
+}
+//# sourceMappingURL=spec-rewriter.js.map

package/dist/spec/evolve/spec-rewriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-rewriter.js","sourceRoot":"","sources":["../../../src/spec/evolve/spec-rewriter.ts"],"names":[],"mappings":"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"}

package/dist/spec/graph/queries.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Graph traversal queries for the Spec→Commit→CodeFragment knowledge graph.
+ *
+ * Replaces `commit4spec/graph/queries.py`. Provides spec context retrieval,
+ * stats, and search+traverse functionality.
+ */
+import { SqliteDatabase } from '../../db/sqlite-adapter';
+import { SpecContext, SpecStats } from '../types';
+/**
+ * Retrieve full context for a Spec — the spec node itself, all linked
+ * commits (with their relation types), and optionally the code fragments
+ * each commit touched.
+ *
+ * Commits are ordered by relation-type priority (GENERATE first, then
+ * SUMMARIZED_FROM, then others) and then by timestamp descending within
+ * each priority tier.
+ *
+ * @param db           Active SQLite database handle.
+ * @param specId       Spec identifier to look up.
+ * @param maxCommits   Maximum number of linked commits to return (default 5).
+ * @param includeFragments  Whether to load code fragments for each commit (default true).
+ * @returns SpecContext on success, or null when the spec is not found.
+ */
+export declare function getSpecContext(db: SqliteDatabase, specId: string, maxCommits?: number, includeFragments?: boolean): SpecContext | null;
+/**
+ * Find all spec IDs related to code fragments whose file path matches
+ * the given substring.
+ *
+ * @param db       Active SQLite database handle.
+ * @param filePath  File path substring to search for (LIKE-wrapped).
+ * @returns Array of distinct spec IDs.
+ */
+export declare function findSpecsByFragmentPath(db: SqliteDatabase, filePath: string): string[];
+/** Result container returned by findSpecsByFilePath. */
+export interface FindSpecsByFilePathResult {
+    /** Matching spec entries (capped at maxResults). */
+    results: Array<{
+        id: string;
+        title: string;
+        status: string;
+        version: number;
+        filePath: string;
+    }>;
+    /** Number of results actually returned (<= maxResults). */
+    matched_count: number;
+    /** True when more results exist beyond the cap. */
+    truncated: boolean;
+}
+/**
+ * Find specs whose code fragments reference the given file path.
+ *
+ * Traverses: filePath -> code_fragment_nodes -> commit_fragment_relations
+ * -> commit_nodes -> spec_commit_relations -> spec_nodes.
+ *
+ * Uses LIKE matching against code_fragment_nodes.file_path, so partial
+ * paths work (e.g. `src/auth.ts` matches `src/auth/login.ts` and
+ * `app/src/auth.ts`).  LIKE metacharacters (`%`, `_`, `\`) in the
+ * filePath are automatically escaped.
+ *
+ * An empty or whitespace-only filePath is rejected with an error
+ * (it would match every spec in the graph).
+ *
+ * @param db         Active SQLite database handle.
+ * @param filePath   File path to search for (substring LIKE match).
+ * @param maxResults Maximum number of results to return (default 100).
+ * @returns FindSpecsByFilePathResult with .results, .matched_count, and .truncated.
+ */
+export declare function findSpecsByFilePath(db: SqliteDatabase, filePath: string, maxResults?: number): FindSpecsByFilePathResult;
+/**
+ * Compute statistics about the Spec knowledge graph.
+ *
+ * @param db  Active SQLite database handle.
+ * @returns SpecStats with entity counts and relation totals.
+ */
+export declare function getSpecStats(db: SqliteDatabase): SpecStats;
+/**
+ * Full-text search for specs and return full context for each match.
+ *
+ * Combines FTS5 + LIKE fallback search with graph traversal so callers
+ * get everything in one call: spec metadata, linked commits, and
+ * optionally code fragments.
+ *
+ * Results are sorted by `_score` descending, then by spec timestamp
+ * descending as a tiebreaker.
+ *
+ * @param db                Active SQLite database handle.
+ * @param query             Search query string.
+ * @param topK              Maximum number of results to return (default 10).
+ * @param includeFragments  Whether to load code fragments per commit (default true).
+ * @returns Array of SpecContext (null results filtered out).
+ */
+export declare function searchAndGetContext(db: SqliteDatabase, query: string, topK?: number, includeFragments?: boolean): SpecContext[];
+/**
+ * Metadata about a code entity for which we want to find associated Specs.
+ * Typically sourced from a homegraph.db ``nodes`` row.
+ */
+export interface CodeEntityInfo {
+    name: string;
+    qualifiedName: string;
+    kind: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+}
+/** A single scored match between a code entity and a Spec. */
+export interface CodeEntitySpecMatch {
+    spec: {
+        id: string;
+        title: string;
+        status: string;
+        version: number;
+        filePath: string;
+        timestamp: number;
+    };
+    /** Five-dimension weighted score (0.0–1.0). */
+    score: number;
+    /** Score breakdown for transparency. */
+    scoreDetail: {
+        filePathScore: number;
+        contentScore: number;
+        nameScore: number;
+        recencyScore: number;
+        overlapScore: number;
+    };
+    /** Number of overlapping code fragments for this spec. */
+    fragmentCount: number;
+    /** Total commits linking this spec to the entity's file. */
+    commitCount: number;
+}
+/** Result container for findSpecsByCodeSymbol. */
+export interface FindSpecsByCodeSymbolResult {
+    entity: CodeEntityInfo;
+    matches: CodeEntitySpecMatch[];
+    totalCandidates: number;
+}
+/**
+ * Find Specs associated with a code entity by multi-dimensional scoring:
+ *
+ * 1. File path match (weight 0.30) — most stable anchor; function rarely changes file
+ * 2. Code-diff content match via FTS5 (weight 0.25) — catches entity names in diff text
+ *    that never appear in Spec titles
+ * 3. Spec title/subtitle name match via FTS5 (weight 0.15) — semantic alignment
+ * 4. Recency (weight 0.20) — newer Specs are more likely to describe current code
+ * 5. Line-range overlap (weight 0.10) — soft signal; code drifts over time
+ *
+ * All five dimensions contribute even when some are zero — a spec without line
+ * overlap can still rank first if its content/name/recency scores are high.
+ *
+ * @param specDb       commit4spec.db connection
+ * @param entity       Code entity info (from homegraph.db nodes)
+ * @param topK         Maximum matches to return (default 10)
+ * @returns Ranked, scored matches with score breakdowns
+ */
+export declare function findSpecsByCodeSymbol(specDb: SqliteDatabase, entity: CodeEntityInfo, topK?: number): FindSpecsByCodeSymbolResult;
+//# sourceMappingURL=queries.d.ts.map

package/dist/spec/graph/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/spec/graph/queries.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAIL,WAAW,EAEX,SAAS,EACV,MAAM,UAAU,CAAC;AAoElB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,MAAU,EACtB,gBAAgB,GAAE,OAAc,GAC/B,WAAW,GAAG,IAAI,CAyEpB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,cAAc,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,EAAE,CAaV;AASD,wDAAwD;AACxD,MAAM,WAAW,yBAAyB;IACxC,oDAAoD;IACpD,OAAO,EAAE,KAAK,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,cAAc,EAClB,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAAsC,GACjD,yBAAyB,CAkD3B;AAGD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,cAAc,GAAG,SAAS,CAqD1D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAW,EACjB,gBAAgB,GAAE,OAAc,GAC/B,WAAW,EAAE,CAwBf;AAMD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,WAAW,EAAE;QACX,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;CACzB;AAwBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,cAAc,EACtB,IAAI,GAAE,MAAW,GAChB,2BAA2B,CA0J7B"}