homegraph 1.1.2 → 1.2.0

package/dist/spec/mining/scope-resolver.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Commit message scope parsing and resolution.
+ *
+ * Replaces `commit4spec/reverse_engineer/scope_resolver.py`.
+ * Extracts conventional-commit scopes, normalizes them, and resolves them to
+ * spec IDs found on disk.
+ *
+ * @module spec/mining/scope-resolver
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractScope = extractScope;
+exports.normalizeScope = normalizeScope;
+exports.resolveScopeToSpec = resolveScopeToSpec;
+const utils_1 = require("../utils");
+const errors_1 = require("../../errors");
+// ---------------------------------------------------------------------------
+// extractScope
+// ---------------------------------------------------------------------------
+/**
+ * Extract a scope from a commit message using the configured regex.
+ *
+ * Only searches the **first line** of the commit message.  Returns the
+ * contents of the first capture group (the scope), or `null` when there is
+ * no match or the regex has no capture group.
+ */
+function extractScope(message, scopeRegex) {
+    const firstLine = message.split('\n', 1)[0] ?? '';
+    let regex;
+    try {
+        regex = new RegExp(scopeRegex);
+    }
+    catch {
+        (0, errors_1.logDebug)('extractScope: invalid regex from config, returning null', {
+            scopeRegex,
+        });
+        return null;
+    }
+    const match = regex.exec(firstLine);
+    if (match && match[1] !== undefined) {
+        return match[1];
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// normalizeScope
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a scope string.
+ *
+ * Steps applied in order:
+ *
+ * 1. **Strip prefixes** — for each prefix in `stripPrefixes`, if `scope`
+ *    starts with it, remove it and stop (only the first matching prefix is
+ *    stripped).
+ * 2. **Lowercase** — if `lowercase` is `true`, convert to lower case.
+ * 3. **Pad spec number** — if `padSpecNumber` is `true`, match the pattern
+ *    `/^spec(\d+)$/i` and zero-pad the numeric portion to 2 digits
+ *    (e.g. `spec3` → `spec03`).
+ */
+function normalizeScope(scope, config) {
+    let normalized = scope;
+    // Step 1: strip the first matching prefix
+    for (const prefix of config.stripPrefixes) {
+        if (normalized.startsWith(prefix)) {
+            normalized = normalized.slice(prefix.length);
+            break;
+        }
+    }
+    // Step 2: lowercase
+    if (config.lowercase) {
+        normalized = normalized.toLowerCase();
+    }
+    // Step 3: pad spec number (e.g. spec3 → spec03)
+    if (config.padSpecNumber) {
+        const m = /^spec(\d+)$/i.exec(normalized);
+        if (m && m[1] !== undefined) {
+            normalized = `spec${m[1].padStart(2, '0')}`;
+        }
+    }
+    return normalized;
+}
+// ---------------------------------------------------------------------------
+// resolveScopeToSpec
+// ---------------------------------------------------------------------------
+/**
+ * Extract a scope from a commit message, normalize it, then check whether the
+ * resulting spec ID exists on disk in `specStoragePath`.
+ *
+ * Returns the normalized spec ID when the scope resolves to an existing spec,
+ * otherwise `null`.
+ */
+function resolveScopeToSpec(message, specStoragePath, config) {
+    const scope = extractScope(message, config.commitScope.scopeRegex);
+    if (!scope) {
+        return null;
+    }
+    const normalized = normalizeScope(scope, config.commitScope.normalize);
+    const entries = (0, utils_1.discoverSpecs)(specStoragePath);
+    const specIds = new Set(entries.map((e) => e.specId));
+    return specIds.has(normalized) ? normalized : null;
+}
+//# sourceMappingURL=scope-resolver.js.map

package/dist/spec/mining/scope-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-resolver.js","sourceRoot":"","sources":["../../../src/spec/mining/scope-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAiBH,oCAkBC;AAmBD,wCA4BC;AAaD,gDAgBC;AA5GD,oCAAyC;AACzC,yCAAwC;AAExC,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;;;;GAMG;AACH,SAAgB,YAAY,CAAC,OAAe,EAAE,UAAkB;IAC9D,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,MAAM,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,IAAA,iBAAQ,EAAC,yDAAyD,EAAE;YAClE,UAAU;SACX,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEpC,IAAI,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,SAAgB,cAAc,CAC5B,KAAa,EACb,MAA+E;IAE/E,IAAI,UAAU,GAAG,KAAK,CAAC;IAEvB,0CAA0C;IAC1C,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;QAC1C,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC7C,MAAM;QACR,CAAC;IACH,CAAC;IAED,oBAAoB;IACpB,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACrB,UAAU,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IACxC,CAAC;IAED,gDAAgD;IAChD,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YAC5B,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAChC,OAAe,EACf,eAAuB,EACvB,MAAkB;IAElB,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IACnE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAEvE,MAAM,OAAO,GAAG,IAAA,qBAAa,EAAC,eAAe,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAEtD,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC"}

package/dist/spec/mining/spec-extractor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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
+ */
+import { SpecConfig } from '../config';
+export interface SpecMetadata {
+    specId: string;
+    title: string;
+    subtitles: string[];
+    commitHash: string | null;
+    filePath: string;
+    type: 'directory' | 'flat-file';
+}
+export interface SupplementaryDoc {
+    path: string;
+    content: string;
+}
+/**
+ * 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.
+ */
+export declare function extractMarkdownHeadings(content: string, maxContentLen?: number): string[];
+/**
+ * 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).
+ */
+export declare function extractSpecMetadata(specStoragePath: string, specDirName: string, config?: SpecConfig): SpecMetadata | null;
+//# sourceMappingURL=spec-extractor.d.ts.map

package/dist/spec/mining/spec-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-extractor.d.ts","sourceRoot":"","sources":["../../../src/spec/mining/spec-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,UAAU,EAAuC,MAAM,WAAW,CAAC;AAQ5E,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAYD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,aAAa,GAAE,MAAY,GAC1B,MAAM,EAAE,CAyFV;AA0JD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CACjC,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,UAAU,GAClB,YAAY,GAAG,IAAI,CAiFrB"}

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