homegraph 1.1.2 → 1.1.3

package/dist/spec/mining/spec-extractor.js

@@ -0,0 +1,369 @@
+"use strict";
+/**
+ * Spec file discovery and metadata extraction.
+ *
+ * Replaces `commit4spec/reverse_engineer/spec_extractor.py`.
+ * Discovers spec files in a storage directory and extracts structured
+ * metadata (title, subtitles, commit hash from commit-info.md).
+ *
+ * @module spec/mining/spec-extractor
+ */
+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.extractMarkdownHeadings = extractMarkdownHeadings;
+exports.extractSpecMetadata = extractSpecMetadata;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+const utils_1 = require("../utils");
+const errors_1 = require("../../errors");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const HEADING_RE = /^(#{1,6})\s+(.*)/;
+// ---------------------------------------------------------------------------
+// extractMarkdownHeadings
+// ---------------------------------------------------------------------------
+/**
+ * Parse ATX headings from markdown content and build breadcrumb-path strings
+ * with content previews.
+ *
+ * Algorithm (ported from `spec_extractor.py:50-88`):
+ *
+ * 1. Find all `#` … `######` headings (ATX-style) and their line positions.
+ * 2. Walk through headings, maintaining a breadcrumb stack — pop until the
+ *    stack is shorter than the current heading's level, then push the new
+ *    heading text.
+ * 3. For each heading, collect the "direct content" lines — non-heading,
+ *    non-empty lines between this heading and the next heading of equal or
+ *    higher level (or EOF).
+ * 4. Skip headings that have sub-headings but no direct content.
+ * 5. Build a display string: `breadcrumb_path - first_direct_content_line`.
+ * 6. Strip `SPEC` suffix from level-1 (root) breadcrumb parts.
+ * 7. Truncate the preview to `maxContentLen` characters, appending `…`
+ *    when truncated.
+ *
+ * @param content       - Raw markdown string.
+ * @param maxContentLen - Max characters for the content preview (default 200).
+ * @returns Array of formatted heading strings.
+ */
+function extractMarkdownHeadings(content, maxContentLen = 200) {
+    const lines = content.split('\n');
+    const headings = [];
+    for (let i = 0; i < lines.length; i++) {
+        const match = HEADING_RE.exec(lines[i]);
+        if (!match)
+            continue;
+        const text = match[2].trim();
+        if (!text)
+            continue;
+        headings.push({
+            lineIndex: i,
+            level: match[1].length,
+            text,
+        });
+    }
+    // Second pass: build breadcrumb and collect direct content.
+    const breadcrumb = [];
+    const result = [];
+    for (let hi = 0; hi < headings.length; hi++) {
+        const h = headings[hi];
+        // Adjust breadcrumb: pop until we're at the right depth.
+        while (breadcrumb.length >= h.level) {
+            breadcrumb.pop();
+        }
+        breadcrumb.push(h.text);
+        // Determine the end line of this heading's content section.
+        // The section ends at the next heading of equal or higher level (or EOF).
+        let endLine = lines.length;
+        for (let hj = hi + 1; hj < headings.length; hj++) {
+            const nextH = headings[hj];
+            if (nextH.level <= h.level) {
+                endLine = nextH.lineIndex;
+                break;
+            }
+        }
+        // Collect direct content: non-heading, non-empty lines within this section.
+        const directLines = [];
+        let hasSubHeadings = false;
+        for (let li = h.lineIndex + 1; li < endLine; li++) {
+            const line = lines[li].trim();
+            if (!line)
+                continue;
+            if (HEADING_RE.test(line)) {
+                hasSubHeadings = true;
+                continue;
+            }
+            directLines.push(line);
+        }
+        // Skip headings that only contain sub-headings (no direct text).
+        if (hasSubHeadings && directLines.length === 0) {
+            continue;
+        }
+        // Build the display path.
+        let display = breadcrumb.join(' → ');
+        // Strip trailing SPEC from level-1 (root) headings.
+        if (breadcrumb.length === 1) {
+            display = display.replace(/\s*SPEC\s*$/i, '');
+        }
+        // Append content preview (first direct line, truncated).
+        if (directLines.length > 0) {
+            let preview = directLines[0];
+            if (preview.length > maxContentLen) {
+                preview = preview.slice(0, maxContentLen) + '…';
+            }
+            display += ' - ' + preview;
+        }
+        result.push(display);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// _findPrimaryDoc
+// ---------------------------------------------------------------------------
+/**
+ * Find the primary spec document by trying each candidate name.
+ *
+ * Replaces the `{spec_dir}` placeholder in each candidate with `specDirName`,
+ * then checks whether the resolved file exists in `specDirPath`.  Returns the
+ * first match as `[resolvedName, absolutePath]`, or `null` when no candidate
+ * matches.
+ *
+ * Ported from `spec_extractor.py:94-114`.
+ */
+function _findPrimaryDoc(specDirPath, specDirName, candidates) {
+    for (const candidate of candidates) {
+        const resolved = candidate.replace(/\{spec_dir\}/g, specDirName);
+        const absPath = path.join(specDirPath, resolved);
+        if (fs.existsSync(absPath)) {
+            return [resolved, absPath];
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Glob helper
+// ---------------------------------------------------------------------------
+/**
+ * Simple glob-to-regex conversion for supplementary document matching.
+ *
+ * Only handles `*` (any non-separator characters) and literal text.
+ * Does not support `**`, `?`, or character classes — sufficient for
+ * patterns like `"*.md"` or `"changelog-*.md"`.
+ */
+function globToRegex(glob) {
+    // Escape regex-special characters except *
+    let pattern = '';
+    for (const ch of glob) {
+        if (ch === '*') {
+            pattern += '[^/]*';
+        }
+        else if ('.+^${}()|[]\\'.includes(ch)) {
+            pattern += '\\' + ch;
+        }
+        else {
+            pattern += ch;
+        }
+    }
+    return new RegExp('^' + pattern + '$');
+}
+// ---------------------------------------------------------------------------
+// _buildMetadata
+// ---------------------------------------------------------------------------
+/**
+ * Build `SpecMetadata` from raw spec content and supplementary documents.
+ *
+ * Ported from `spec_extractor.py:120-171`.
+ *
+ * 1. Extract a title from the first `# ` heading (stripping a trailing
+ *    `SPEC` suffix); fallback to `specId`.
+ * 2. Collect subtitles via `extractMarkdownHeadings`.
+ * 3. Discover supplementary `.md` files in `specDirPath` that match
+ *    `config.supplementaryGlobs` (excluding the primary doc) and merge
+ *    their headings into the subtitle list.
+ * 4. Resolve a commit hash from `commit-info.md` content in `specDirPath`
+ *    (using `config.commitInfoCandidates`).
+ */
+function _buildMetadata(specId, content, filePath, specDirPath, config) {
+    // ---- title ----
+    let title = specId;
+    const firstH1Match = content.match(/^#\s+(.*)/m);
+    if (firstH1Match && firstH1Match[1]) {
+        title = firstH1Match[1].trim().replace(/\s*SPEC\s*$/i, '');
+        if (!title) {
+            title = specId;
+        }
+    }
+    // ---- subtitles from primary doc ----
+    const subtitles = extractMarkdownHeadings(content);
+    // ---- supplementary docs ----
+    // Find the primary doc's filename so we can skip it.
+    const primaryDocName = path.basename(filePath);
+    let dirEntries;
+    try {
+        dirEntries = fs.readdirSync(specDirPath, { withFileTypes: true });
+    }
+    catch {
+        dirEntries = [];
+    }
+    const globRegexes = config.supplementaryGlobs.map((g) => globToRegex(g));
+    for (const entry of dirEntries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.md'))
+            continue;
+        if (entry.name === primaryDocName)
+            continue;
+        // Check if the file name matches any supplementary glob.
+        const matchesGlob = globRegexes.some((re) => re.test(entry.name));
+        if (!matchesGlob)
+            continue;
+        const suppPath = path.join(specDirPath, entry.name);
+        const suppContent = (0, utils_1.readFileContent)(suppPath);
+        if (suppContent === null)
+            continue;
+        const suppHeadings = extractMarkdownHeadings(suppContent);
+        for (const heading of suppHeadings) {
+            subtitles.push(heading);
+        }
+    }
+    // ---- commit hash ----
+    let commitHash = null;
+    for (const candidate of config.commitInfoCandidates) {
+        const ciPath = path.join(specDirPath, candidate);
+        const ciContent = (0, utils_1.readFileContent)(ciPath);
+        if (ciContent !== null) {
+            commitHash = (0, utils_1.parseCommitInfoMd)(ciContent);
+            break;
+        }
+    }
+    (0, errors_1.logDebug)('Built spec metadata', { specId, title, subtitleCount: subtitles.length, commitHash });
+    return {
+        specId,
+        title,
+        subtitles,
+        commitHash,
+        filePath,
+        type: 'directory',
+    };
+}
+// ---------------------------------------------------------------------------
+// extractSpecMetadata (public)
+// ---------------------------------------------------------------------------
+/**
+ * Discover and extract metadata for a single spec, given its storage location
+ * and directory name.
+ *
+ * Ported from `spec_extractor.py:177-237`.
+ *
+ * Two discovery branches are attempted in order:
+ *
+ * - **Flat-file**: checks `{specStoragePath}/{specDirName}.md`.  If it exists,
+ *   reads it and produces metadata with `type: 'flat-file'`.
+ * - **Directory**: checks `{specStoragePath}/{specDirName}/`.  If it exists,
+ *   searches for a primary document using `config.discovery.primaryDocCandidates`,
+ *   reads it, and produces metadata with `type: 'directory'`.
+ *
+ * Returns `null` when neither branch yields a readable spec.
+ *
+ * @param specStoragePath - Root directory where specs are stored.
+ * @param specDirName     - Name of the spec (e.g. "spec03", "auth-module").
+ * @param config          - Optional full `SpecConfig`; falls back to defaults
+ *                          when omitted (discovery config resolved at call site).
+ */
+function extractSpecMetadata(specStoragePath, specDirName, config) {
+    // Resolve discovery config — use provided config or the built-in defaults.
+    const discoveryConfig = config?.discovery ?? config_1.DEFAULT_CONFIG.discovery;
+    // Branch A: flat-file
+    const flatFilePath = path.join(specStoragePath, `${specDirName}.md`);
+    if (fs.existsSync(flatFilePath) && fs.statSync(flatFilePath).isFile()) {
+        const content = (0, utils_1.readFileContent)(flatFilePath);
+        if (content !== null) {
+            (0, errors_1.logDebug)('Discovered flat-file spec', { specDirName, path: flatFilePath });
+            // Build metadata manually for flat-file (no supplementary docs or
+            // commit-info in the same directory — those live alongside the flat
+            // file's parent, which is specStoragePath itself).
+            let title = specDirName;
+            const firstH1Match = content.match(/^#\s+(.*)/m);
+            if (firstH1Match && firstH1Match[1]) {
+                title = firstH1Match[1].trim().replace(/\s*SPEC\s*$/i, '');
+                if (!title)
+                    title = specDirName;
+            }
+            const subtitles = extractMarkdownHeadings(content);
+            // Attempt to read commit-info from specStoragePath for supplementary
+            // context (though flat-file specs rarely have one).
+            let commitHash = null;
+            for (const candidate of discoveryConfig.commitInfoCandidates) {
+                const ciPath = path.join(specStoragePath, candidate);
+                const ciContent = (0, utils_1.readFileContent)(ciPath);
+                if (ciContent !== null) {
+                    commitHash = (0, utils_1.parseCommitInfoMd)(ciContent);
+                    break;
+                }
+            }
+            return {
+                specId: specDirName,
+                title,
+                subtitles,
+                commitHash,
+                filePath: flatFilePath,
+                type: 'flat-file',
+            };
+        }
+    }
+    // Branch B: directory
+    const specDirPath = path.join(specStoragePath, specDirName);
+    if (fs.existsSync(specDirPath) && fs.statSync(specDirPath).isDirectory()) {
+        const primary = _findPrimaryDoc(specDirPath, specDirName, discoveryConfig.primaryDocCandidates);
+        if (primary) {
+            const [, primaryAbsPath] = primary;
+            const content = (0, utils_1.readFileContent)(primaryAbsPath);
+            if (content !== null) {
+                (0, errors_1.logDebug)('Discovered directory spec', { specDirName, primaryDoc: primaryAbsPath });
+                const meta = _buildMetadata(specDirName, content, primaryAbsPath, specDirPath, discoveryConfig);
+                return { ...meta, type: 'directory' };
+            }
+        }
+        // Directory exists but no primary doc was found or it was unreadable.
+        (0, errors_1.logWarn)('Spec directory exists but no primary doc found', {
+            specDirName,
+            specDirPath,
+            candidates: discoveryConfig.primaryDocCandidates,
+        });
+    }
+    return null;
+}
+//# sourceMappingURL=spec-extractor.js.map

package/dist/spec/mining/spec-extractor.js.map

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

package/dist/spec/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Commit4Spec Type Definitions
+ *
+ * Core types for the Spec knowledge graph — a higher-level semantic overlay
+ * on top of HomeGraph's code-symbol graph. Tracks design documents (Specs),
+ * Git commits, and code-change fragments, linked through a three-layer
+ * relationship model.
+ *
+ * These types mirror the Python dataclasses in Commit4Spec's
+ * `db/models/*.py` and are stored in separate SQLite tables from
+ * HomeGraph's `nodes` / `edges` core graph.
+ */
+/**
+ * A design Spec — a higher-level document describing system behavior,
+ * discovered from either commit-message scopes or spec files on disk.
+ */
+export interface SpecNode {
+    /** Unique spec identifier (e.g. "spec28", "auth-module") */
+    id: string;
+    /** Title extracted from the spec document's first heading */
+    title: string;
+    /** Subtitle entries — markdown headings with content previews */
+    subtitles: string[];
+    /** Lifecycle status */
+    status: 'active' | 'deprecated';
+    /** Version number (incremented on each self-evolution rewrite) */
+    version: number;
+    /** Filesystem path to the spec document */
+    filePath: string;
+    /** Unix epoch millisecond timestamp of last update */
+    timestamp: number;
+}
+/**
+ * A Git commit — metadata extracted from the repository history.
+ */
+export interface CommitNode {
+    /** Full commit hash (40-char hex) */
+    hash: string;
+    /** Commit message (first line) */
+    message: string;
+    /** Commit author name */
+    author: string;
+    /** Unix epoch millisecond timestamp */
+    timestamp: number;
+}
+/**
+ * A code-change fragment — a single file's diff from a commit,
+ * tracked as a coarse-grained range (not AST-level).
+ */
+export interface CodeFragmentNode {
+    /** 12-character hex identifier (auto-generated UUID prefix) */
+    id: string;
+    /** Kind of change */
+    changeType: 'ADD' | 'MODIFY' | 'DELETE';
+    /** Changed file path relative to repo root */
+    filePath: string;
+    /** First changed line (1-indexed) */
+    startLine: number;
+    /** Last changed line (1-indexed) */
+    endLine: number;
+    /** Unified diff text for this fragment */
+    codeDiff: string;
+}
+/**
+ * Relationship types between Spec entities.
+ *
+ *  - GENERATE:       commit → spec (parsed from commit message scope)
+ *  - SUMMARIZED_FROM: spec → commit (discovered during mining)
+ *  - SIMILAR_TO:      spec ↔ spec  (semantic similarity match)
+ *  - EVOLVED_FROM:    new spec → old/deprecated spec (self-evolve)
+ *  - CONTAINS:        commit → code fragment
+ */
+export type RelationType = 'GENERATE' | 'SUMMARIZED_FROM' | 'SIMILAR_TO' | 'EVOLVED_FROM' | 'CONTAINS';
+/**
+ * A link between a Spec and a Commit.
+ */
+export interface SpecCommitRelation {
+    specId: string;
+    commitHash: string;
+    relationType: RelationType;
+}
+/**
+ * A link between a Commit and a CodeFragment.
+ */
+export interface CommitFragmentRelation {
+    commitHash: string;
+    fragmentId: string;
+}
+/**
+ * A link between two Specs.
+ */
+export interface SpecSpecRelation {
+    sourceId: string;
+    targetId: string;
+    relationType: RelationType;
+}
+/**
+ * Full context for a Spec — the spec itself, all linked commits,
+ * and the code fragments each commit touched.
+ */
+export interface SpecContext {
+    spec: SpecNode;
+    commits: SpecCommitContext[];
+}
+/**
+ * A commit with its relation type and code fragments, all bound
+ * to a specific spec.
+ */
+export interface SpecCommitContext {
+    commit: CommitNode;
+    relationType: RelationType;
+    fragments: CodeFragmentNode[];
+}
+/**
+ * A compact commit reference (hash + message only) for lightweight
+ * context serialisation.
+ */
+export interface CommitReference {
+    hash: string;
+    message: string;
+    timestamp: number;
+}
+/**
+ * A search result for a spec with scoring metadata.
+ */
+export interface SpecSearchResult {
+    /** Matching spec */
+    id: string;
+    title: string;
+    subtitles: string[];
+    /** Relevance score — 3.0 (exact title) → 1.0 (subtitles-only match) */
+    _score: number;
+    /** Which search stage produced this result */
+    _method?: 'fts5' | 'like' | 'all' | 'discovery';
+    /** LIKE tier label (only for LIKE results) */
+    _tier?: 'exact_title' | 'starts_with_title' | 'contains_title' | 'contains_subtitle';
+}
+/**
+ * Statistics about the Spec knowledge graph.
+ */
+export interface SpecStats {
+    specCount: number;
+    commitCount: number;
+    fragmentCount: number;
+    relationCount: number;
+    activeSpecCount: number;
+    deprecatedSpecCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/spec/types.d.ts.map

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

package/dist/spec/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Commit4Spec Type Definitions
+ *
+ * Core types for the Spec knowledge graph — a higher-level semantic overlay
+ * on top of HomeGraph's code-symbol graph. Tracks design documents (Specs),
+ * Git commits, and code-change fragments, linked through a three-layer
+ * relationship model.
+ *
+ * These types mirror the Python dataclasses in Commit4Spec's
+ * `db/models/*.py` and are stored in separate SQLite tables from
+ * HomeGraph's `nodes` / `edges` core graph.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/spec/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/spec/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}