homegraph 1.1.2 → 1.2.0

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"}

package/dist/spec/utils.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Spec utility functions — replaces `file_utils.py`, `meta.py`, and
+ * `truncate.py` from Python Commit4Spec.
+ *
+ * Covers file I/O, meta.json read/write, text/diff truncation, and budget
+ * computation. All functions are synchronous and use Node.js built-ins.
+ *
+ * @module spec/utils
+ */
+export interface SpecEntry {
+    specId: string;
+    entryType: 'directory' | 'file';
+    path: string;
+}
+export interface SpecMeta {
+    repoPath: string;
+    specStoragePath: string;
+    currentCommitID?: string;
+    createdAt?: string;
+    updatedAt: string;
+}
+export interface BudgetProfile {
+    tier: 'tiny' | 'small' | 'medium' | 'large' | 'vlarge';
+    maxFragments: number;
+    maxContents: number;
+    contentBudget: number;
+}
+/** Root directory for spec data, relative to the repository root. */
+export declare const SPEC_DATA_DIR = ".homegraph/commit4spec";
+/**
+ * Read a UTF-8 file synchronously.
+ *
+ * Returns `null` for ENOENT (not found), EISDIR (is a directory), or EACCES
+ * (permission denied). Other errors propagate.
+ */
+export declare function readFileContent(filePath: string): string | null;
+/**
+ * Write a UTF-8 file synchronously, creating parent directories as needed.
+ *
+ * Parent directories are created with `fs.mkdirSync({ recursive: true })`.
+ * If the parent exists but is not a directory the underlying error propagates.
+ */
+export declare function writeFileContent(filePath: string, content: string): void;
+/**
+ * Parse commit-info.md content for a commit hash.
+ *
+ * Searches line by line for one of:
+ * - `commit: HASH`
+ * - `commit-id: HASH`
+ * - `commit_id: HASH`
+ * - a bare 40-char hex hash on its own line
+ *
+ * Returns the first matched hash (7–40 hex chars), or `null` if no hash is
+ * found. Empty or whitespace-only input returns `null`.
+ */
+export declare function parseCommitInfoMd(content: string): string | null;
+/**
+ * Discover specs in a storage directory.
+ *
+ * A "spec" is any `.md` file OR any subdirectory. For `.md` files the
+ * `specId` is the basename without the extension. For subdirectories the
+ * `specId` is the directory name.
+ *
+ * Returns an empty array when `specStoragePath` does not exist or is not a
+ * directory.
+ */
+export declare function discoverSpecs(specStoragePath: string): SpecEntry[];
+/**
+ * Resolve the database path.
+ *
+ * Priority:
+ * 1. If `explicitDbPath` is given, return it as-is (no side effects).
+ * 2. If `repoPath` is given, default to `{repoPath}/${SPEC_DATA_DIR}/commit4spec.db`
+ *    and ensure `${SPEC_DATA_DIR}/.gitignore` exists containing `"*"`.
+ * 3. If neither is given, return `"./commit4spec.db"`.
+ */
+export declare function resolveDbPath(repoPath?: string, explicitDbPath?: string): string;
+/**
+ * Read `${SPEC_DATA_DIR}/meta.json` from `repoPath`.
+ *
+ * Returns `null` when the file is missing, unreadable, or contains invalid
+ * JSON or a JSON value that is not a plain object.
+ */
+export declare function readMeta(repoPath: string): SpecMeta | null;
+/**
+ * Write `${SPEC_DATA_DIR}/meta.json` to `repoPath`.
+ *
+ * If existing meta has a `createdAt` field it is preserved; otherwise a new
+ * ISO-8601 timestamp is generated. `updatedAt` is always set to the current
+ * time. The `${SPEC_DATA_DIR}` directory is created if it does not exist.
+ *
+ * Returns the full `SpecMeta` that was written.
+ */
+export declare function writeMeta(repoPath: string, specStoragePath: string, currentCommitID?: string): SpecMeta;
+/**
+ * Truncate a unified diff at a sensible boundary.
+ *
+ * The algorithm prefers semantic boundaries to keep diffs readable:
+ *
+ * 1. If the diff is shorter than `maxChars` (default 3800), return it unchanged.
+ * 2. Try: find the **last** `@@` hunk header in the trailing 50% portion of
+ *    the diff and cut right before it.
+ * 3. Fallback: find the **last** newline in the trailing 80% portion and cut
+ *    after it.
+ * 4. Hard fallback: cut exactly at `maxChars`.
+ *
+ * Always appends `"  …(truncated)"` when truncation occurs.
+ *
+ * @param diff    - The unified diff text to truncate.
+ * @param maxChars - Maximum allowed characters (including suffix). Default 3800.
+ * @returns The (possibly truncated) diff text.
+ */
+export declare function truncateCodeDiff(diff: string, maxChars?: number): string;
+/**
+ * Truncate plain text with newline-awareness.
+ *
+ * When the text is longer than `maxChars`, it is cut at the last newline
+ * found before `maxChars` (minus the suffix length). If no suitable newline
+ * exists, a hard cut is made.
+ *
+ * The suffix `"  …(truncated)"` is appended only when truncation occurs.
+ *
+ * @param text     - The text to truncate.
+ * @param maxChars - Maximum allowed characters (including suffix).
+ * @returns The (possibly truncated) text.
+ */
+export declare function truncateText(text: string, maxChars: number): string;
+/**
+ * Truncate a subtitles array.
+ *
+ * 1. If the array has more than `maxEntries`, it is sliced to `maxEntries`.
+ * 2. Each remaining entry that exceeds `maxChars` is individually truncated
+ *    via `truncateText`.
+ *
+ * Entries that already fit within both limits are left unchanged.
+ *
+ * @param subtitles  - Array of subtitle strings.
+ * @param maxChars   - Maximum characters per entry (including suffix).
+ * @param maxEntries - Maximum number of entries to keep.
+ * @returns The truncated subtitles array (always a new array).
+ */
+export declare function truncateSubtitles(subtitles: string[], maxChars: number, maxEntries: number): string[];
+/**
+ * Compute a budget profile based on spec and optional fragment counts.
+ *
+ * The profile determines how many fragments, contents, and characters the
+ * pipeline should budget when building LLM prompts. Higher counts produce
+ * tighter budgets to keep prompts manageable.
+ *
+ * Thresholds (matching `truncate.py:38-57`):
+ *
+ * | specCount | tier    | maxFragments | maxContents | contentBudget |
+ * |-----------|---------|--------------|-------------|---------------|
+ * | ≤ 3       | tiny    | 12           | 16          | 48000         |
+ * | ≤ 8       | small   | 10           | 14          | 40000         |
+ * | ≤ 15      | medium  | 8            | 12          | 32000         |
+ * | ≤ 30      | large   | 6            | 10          | 24000         |
+ * | > 30      | vlarge  | 0            | 0           | 16000         |
+ *
+ * The `vlarge` tier disables fragment/contents inclusion entirely (0 values).
+ *
+ * @param specCount     - Number of specs in the knowledge graph.
+ * @param fragmentCount - (Unused) reserved for future per-fragment weighting.
+ * @returns The budget profile for the given scale.
+ */
+export declare function computeBudgetProfile(specCount: number, _fragmentCount?: number): BudgetProfile;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/spec/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,WAAW,GAAG,MAAM,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,qEAAqE;AACrE,eAAO,MAAM,aAAa,2BAA2B,CAAC;AAStD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAMxE;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuBhE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,EAAE,CA6BlE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAiChF;AAMD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CA8C1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,eAAe,CAAC,EAAE,MAAM,GACvB,QAAQ,CAyBV;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAa,GAAG,MAAM,CA6C9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBnE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAMV;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB,aAAa,CAcf"}