@selvakumaresra/specship 0.1.3 → 0.3.0

package/dist/extraction/specs/markdown-spec-extractor.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * Markdown Spec Extractor
+ *
+ * Parses Markdown spec files where each addressable section carries an
+ * embedded ID via `<!-- id: REQ-X -->` immediately above its heading.
+ * Per locked v1 design: **embedded IDs are mandatory**. A heading without
+ * an embedded ID produces an `error`-severity ExtractionError so the spec
+ * author fixes the file; no path-derived fallback.
+ *
+ * Spec format:
+ *   ---
+ *   format: markdown
+ *   owner: security
+ *   ---
+ *   <!-- id: REQ-AUTH-005 -->
+ *   # Failed login attempts must be rate-limited
+ *
+ *   The login endpoint rejects more than 5 failed attempts per IP per minute.
+ *
+ *   implementations:
+ *     - src/auth/login.ts:authenticate
+ *     - src/auth/rate-limit.ts:enforce
+ *
+ *   ## Acceptance
+ *   <!-- id: REQ-AUTH-005.A1 -->
+ *   - A 6th failed attempt within 60s from the same IP returns 429.
+ *
+ * Hierarchy is heading depth: a deeper heading becomes a child of the most
+ * recent enclosing heading. The document spec (kind='document') has no
+ * parent and gets ID from the first H1 with an embedded ID — OR a
+ * document-level `id:` field in the frontmatter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarkdownSpecExtractor = void 0;
+const crypto_1 = require("crypto");
+/** Pattern: <!-- id: SOMETHING --> (whitespace tolerant) */
+const ID_COMMENT = /<!--\s*id\s*:\s*([^\s-][^\s]*)\s*-->/;
+/** Pattern: heading line (# .. ###### ..) */
+const HEADING = /^(#{1,6})\s+(.+?)\s*$/;
+/** Pattern: implementation reference inside an `implementations:` block */
+const IMPL_REF = /^[-*]\s+([^\s:]+)\s*:\s*([A-Za-z0-9_$.]+)\s*$/;
+/**
+ * Heuristic: guess the target node kind from a qualified name. Used only
+ * for the `target_node_kind` hint on SpecLinkCandidate — the resolver
+ * matches loosely on (file_path, qualified_name).
+ */
+function guessNodeKind(qualifiedName) {
+    if (/[A-Z]/.test(qualifiedName[0] ?? ''))
+        return 'class';
+    if (qualifiedName.includes('.'))
+        return 'method';
+    return 'function';
+}
+class MarkdownSpecExtractor {
+    filePath;
+    source;
+    constructor(filePath, source) {
+        this.filePath = filePath;
+        this.source = source;
+    }
+    extract() {
+        const start = Date.now();
+        const specs = [];
+        const linkCandidates = [];
+        const errors = [];
+        const lines = this.source.split(/\r?\n/);
+        const now = Date.now();
+        // 1. Frontmatter (optional)
+        const { frontmatter, firstContentLine } = this.parseFrontmatter(lines, errors);
+        const pendingSections = [];
+        let pendingId = null;
+        let pendingIdLine = -1;
+        for (let i = firstContentLine; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined)
+                continue;
+            const idMatch = line.match(ID_COMMENT);
+            if (idMatch) {
+                if (pendingId !== null) {
+                    // Two consecutive ID comments with no heading between them — the
+                    // earlier one is stranded. Surface it but don't fail extraction.
+                    errors.push({
+                        message: `Stranded <!-- id: ${pendingId} --> on line ${pendingIdLine + 1} (no heading followed)`,
+                        filePath: this.filePath,
+                        line: pendingIdLine + 1,
+                        severity: 'warning',
+                        code: 'spec_stranded_id',
+                    });
+                }
+                pendingId = idMatch[1] ?? null;
+                pendingIdLine = i;
+                continue;
+            }
+            const headingMatch = line.match(HEADING);
+            if (headingMatch && headingMatch[1] && headingMatch[2]) {
+                const level = headingMatch[1].length;
+                const title = headingMatch[2];
+                if (pendingId === null) {
+                    // A heading without an embedded ID — load-bearing error per v1.
+                    errors.push({
+                        message: `Heading "${title}" lacks an embedded ID. Add <!-- id: REQ-X --> immediately above it.`,
+                        filePath: this.filePath,
+                        line: i + 1,
+                        severity: 'error',
+                        code: 'spec_missing_id',
+                    });
+                    continue;
+                }
+                pendingSections.push({
+                    id: pendingId,
+                    level,
+                    title,
+                    startLine: i + 1, // 1-indexed
+                    headingLineIdx: i,
+                });
+                pendingId = null;
+                pendingIdLine = -1;
+            }
+        }
+        // 3. Resolve parent IDs via heading-level nesting.
+        const docId = typeof frontmatter.id === 'string' && frontmatter.id.length > 0
+            ? frontmatter.id
+            : undefined;
+        // The document is its own spec entity. If frontmatter declared `id:`,
+        // use it; otherwise the file produces no top-level document node (just
+        // its requirements). Most authors will either declare frontmatter or
+        // use a single H1 as the document.
+        if (docId !== undefined) {
+            const firstSection = pendingSections[0];
+            const docBodyEnd = firstSection !== undefined ? firstSection.headingLineIdx : lines.length;
+            const docBody = lines.slice(firstContentLine, docBodyEnd).join('\n').trim();
+            const docTitle = typeof frontmatter.title === 'string' && frontmatter.title.length > 0
+                ? frontmatter.title
+                : this.filePath;
+            specs.push({
+                id: docId,
+                kind: 'document',
+                title: docTitle,
+                body: docBody,
+                format: 'markdown',
+                sourcePath: this.filePath,
+                startLine: firstContentLine + 1,
+                endLine: docBodyEnd,
+                parentId: undefined,
+                contentHash: hash(docBody),
+                version: typeof frontmatter.version === 'number' ? frontmatter.version : 1,
+                owner: typeof frontmatter.owner === 'string' ? frontmatter.owner : undefined,
+                priority: typeof frontmatter.priority === 'string' ? frontmatter.priority : undefined,
+                metadata: frontmatter.metadata && typeof frontmatter.metadata === 'object'
+                    ? frontmatter.metadata
+                    : undefined,
+                createdAt: now,
+                updatedAt: now,
+            });
+        }
+        // For each section: determine its body range + parent.
+        // Body: from line after the heading to the line before the next heading
+        //       at the same-or-shallower level.
+        // Parent: the most recent earlier section with a SHALLOWER level (or
+        //         the document if none).
+        for (let s = 0; s < pendingSections.length; s++) {
+            const section = pendingSections[s];
+            if (section === undefined)
+                continue;
+            // Find body end: next section at level <= section.level, else EOF.
+            let bodyEndLine = lines.length;
+            for (let t = s + 1; t < pendingSections.length; t++) {
+                const next = pendingSections[t];
+                if (next !== undefined && next.level <= section.level) {
+                    bodyEndLine = next.headingLineIdx;
+                    break;
+                }
+            }
+            // The body excludes the heading line itself.
+            const bodyLines = lines.slice(section.headingLineIdx + 1, bodyEndLine);
+            const body = bodyLines.join('\n').trim();
+            // Find parent: nearest earlier section with shallower level.
+            let parentId = docId;
+            for (let p = s - 1; p >= 0; p--) {
+                const earlier = pendingSections[p];
+                if (earlier !== undefined && earlier.level < section.level) {
+                    parentId = earlier.id;
+                    break;
+                }
+            }
+            // Classify kind by content / title — `## Acceptance` is the canonical
+            // acceptance container; bullet lists under it are individual criteria.
+            // For v1 we keep it simple: H1/H2 = 'requirement', deeper = 'acceptance'.
+            const kind = section.level >= 3 ? 'acceptance' : 'requirement';
+            specs.push({
+                id: section.id,
+                kind,
+                title: section.title,
+                body,
+                format: 'markdown',
+                sourcePath: this.filePath,
+                startLine: section.startLine,
+                endLine: bodyEndLine,
+                parentId,
+                contentHash: hash(body),
+                version: 1,
+                createdAt: now,
+                updatedAt: now,
+            });
+            // Scan the body for `implementations:` blocks — bullet-list refs.
+            const candidates = this.extractImplementationRefs(section.id, bodyLines);
+            linkCandidates.push(...candidates);
+        }
+        return {
+            specs,
+            linkCandidates,
+            errors,
+            format: 'markdown',
+            durationMs: Date.now() - start,
+        };
+    }
+    /**
+     * Parse YAML-ish frontmatter. We only extract a handful of known keys
+     * (`id`, `title`, `owner`, `priority`, `version`); arbitrary structure
+     * goes into `metadata`. Keeps the v1 extractor dependency-free — full
+     * YAML can come later when YAML/Gherkin extractors land.
+     */
+    parseFrontmatter(lines, errors) {
+        const frontmatter = {};
+        if (lines.length === 0 || (lines[0] ?? '').trim() !== '---') {
+            return { frontmatter, firstContentLine: 0 };
+        }
+        let closingIdx = -1;
+        for (let i = 1; i < lines.length; i++) {
+            if ((lines[i] ?? '').trim() === '---') {
+                closingIdx = i;
+                break;
+            }
+        }
+        if (closingIdx === -1) {
+            errors.push({
+                message: 'Unterminated frontmatter block (missing closing ---)',
+                filePath: this.filePath,
+                line: 1,
+                severity: 'warning',
+                code: 'spec_unterminated_frontmatter',
+            });
+            return { frontmatter, firstContentLine: 0 };
+        }
+        // Simple `key: value` parser. Known keys are extracted; rest goes to
+        // metadata.
+        const knownKeys = new Set(['id', 'title', 'owner', 'priority', 'version']);
+        const metadata = {};
+        for (let i = 1; i < closingIdx; i++) {
+            const line = (lines[i] ?? '').trim();
+            if (!line || line.startsWith('#'))
+                continue;
+            const colonIdx = line.indexOf(':');
+            if (colonIdx <= 0)
+                continue;
+            const key = line.slice(0, colonIdx).trim();
+            let value = line.slice(colonIdx + 1).trim();
+            // Strip surrounding quotes
+            if (typeof value === 'string') {
+                if ((value.startsWith('"') && value.endsWith('"')) ||
+                    (value.startsWith("'") && value.endsWith("'"))) {
+                    value = value.slice(1, -1);
+                }
+                if (/^\d+$/.test(value))
+                    value = parseInt(value, 10);
+            }
+            if (knownKeys.has(key)) {
+                frontmatter[key] = value;
+            }
+            else {
+                metadata[key] = value;
+            }
+        }
+        if (Object.keys(metadata).length > 0) {
+            frontmatter.metadata = metadata;
+        }
+        return { frontmatter, firstContentLine: closingIdx + 1 };
+    }
+    /**
+     * Scan a body block for a bullet-list `implementations:` declaration.
+     * Format:
+     *
+     *   implementations:
+     *     - src/auth/login.ts:authenticate
+     *     - src/auth/rate-limit.ts:enforce
+     *
+     * Each match becomes a SpecLinkCandidate with kind='implements'.
+     * Tolerant of indentation; stops at the first non-bullet, non-blank line.
+     */
+    extractImplementationRefs(specId, bodyLines) {
+        const out = [];
+        for (let i = 0; i < bodyLines.length; i++) {
+            const line = (bodyLines[i] ?? '').trim();
+            if (line !== 'implementations:' && !line.startsWith('implementations:'))
+                continue;
+            // Walk subsequent lines collecting `- path:symbol` entries.
+            for (let j = i + 1; j < bodyLines.length; j++) {
+                const subline = (bodyLines[j] ?? '').trim();
+                if (subline === '')
+                    continue;
+                const m = subline.match(IMPL_REF);
+                if (!m)
+                    break;
+                const refPath = m[1];
+                const refSymbol = m[2];
+                if (!refPath || !refSymbol)
+                    continue;
+                out.push({
+                    specId,
+                    targetFilePath: refPath,
+                    targetQualifiedName: refSymbol,
+                    targetNodeKind: guessNodeKind(refSymbol),
+                    kind: 'implements',
+                });
+            }
+            // Stop after first `implementations:` block — no need to find more.
+            break;
+        }
+        return out;
+    }
+}
+exports.MarkdownSpecExtractor = MarkdownSpecExtractor;
+function hash(s) {
+    return (0, crypto_1.createHash)('sha256').update(s).digest('hex').substring(0, 32);
+}
+//# sourceMappingURL=markdown-spec-extractor.js.map

package/dist/extraction/specs/markdown-spec-extractor.js.map

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

package/dist/extraction/specs/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Spec extraction types — shared by all per-format spec extractors
+ * (Markdown, YAML, Gherkin, OpenAPI). Each extractor consumes a source file
+ * and returns these shapes; the orchestrator persists them via SpecQueries.
+ */
+import { ExtractionError, Spec, SpecFormat, SpecLinkKind, NodeKind } from '../../types';
+/**
+ * A pending spec→code link discovered during spec extraction (e.g., from
+ * `implementations:` frontmatter). The extractor doesn't know whether the
+ * target node currently exists in the graph — that's SpecLinkResolver's job.
+ * Provenance is 'spec-declaration' (confidence 0.7).
+ */
+export interface SpecLinkCandidate {
+    specId: string;
+    targetFilePath: string;
+    targetQualifiedName: string;
+    /**
+     * Best-effort guess at the target node kind. The resolver matches on
+     * (file_path, qualified_name) loosely; this is a hint, not a hard filter.
+     */
+    targetNodeKind: NodeKind;
+    kind: SpecLinkKind;
+}
+/**
+ * Result of extracting from a single spec file.
+ */
+export interface SpecExtractionResult {
+    /** All extracted spec entities (document + children) */
+    specs: Spec[];
+    /** Pending links declared by the spec author (provenance='spec-declaration') */
+    linkCandidates: SpecLinkCandidate[];
+    /** Parse errors. Missing-ID-on-heading is the most common — surfaced as 'error' severity. */
+    errors: ExtractionError[];
+    /** Source format */
+    format: SpecFormat;
+    /** Extraction wall-clock duration */
+    durationMs: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/extraction/specs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/extraction/specs/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAExF;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,cAAc,EAAE,QAAQ,CAAC;IACzB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,KAAK,EAAE,IAAI,EAAE,CAAC;IAEd,gFAAgF;IAChF,cAAc,EAAE,iBAAiB,EAAE,CAAC;IAEpC,6FAA6F;IAC7F,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B,oBAAoB;IACpB,MAAM,EAAE,UAAU,CAAC;IAEnB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/extraction/specs/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Spec extraction types — shared by all per-format spec extractors
+ * (Markdown, YAML, Gherkin, OpenAPI). Each extractor consumes a source file
+ * and returns these shapes; the orchestrator persists them via SpecQueries.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/extraction/specs/types.js.map

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

package/dist/extraction/svelte-extractor.d.ts

@@ -0,0 +1,56 @@
+import { ExtractionResult } from '../types';
+/**
+ * SvelteExtractor - Extracts code relationships from Svelte component files
+ *
+ * Svelte files are multi-language (script + template + style). Rather than
+ * parsing the full Svelte grammar, we extract the <script> block content
+ * and delegate it to the TypeScript/JavaScript TreeSitterExtractor.
+ *
+ * Also extracts function calls from template expressions (`{fn(...)}`) so
+ * cross-file call edges are captured even when calls live in markup.
+ *
+ * Every .svelte file produces a component node (Svelte components are always importable).
+ */
+export declare class SvelteExtractor {
+    private filePath;
+    private source;
+    private nodes;
+    private edges;
+    private unresolvedReferences;
+    private errors;
+    constructor(filePath: string, source: string);
+    /**
+     * Extract from Svelte source
+     */
+    extract(): ExtractionResult;
+    /**
+     * Create a component node for the .svelte file
+     */
+    private createComponentNode;
+    /**
+     * Extract <script> blocks from the Svelte source
+     */
+    private extractScriptBlocks;
+    /**
+     * Process a script block by delegating to TreeSitterExtractor
+     */
+    private processScriptBlock;
+    /**
+     * Extract function calls from Svelte template expressions.
+     *
+     * In Svelte, many function calls happen in markup (e.g., `class={cn(...)}`),
+     * not inside `<script>` blocks. We scan the template portion for `{expression}`
+     * blocks and extract call patterns from them.
+     */
+    private extractTemplateCalls;
+    /**
+     * Extract component usages from the Svelte template.
+     *
+     * PascalCase tags like <Modal>, <Button />, <DevServerPreview> represent
+     * component instantiations — analogous to function calls in imperative code.
+     * Capturing these creates graph edges from parent to child components and
+     * gives specship_explore anchor points in the template markup.
+     */
+    private extractTemplateComponents;
+}
+//# sourceMappingURL=svelte-extractor.d.ts.map

package/dist/extraction/svelte-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svelte-extractor.d.ts","sourceRoot":"","sources":["../../src/extraction/svelte-extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,gBAAgB,EAAkD,MAAM,UAAU,CAAC;AAWxG;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,MAAM,CAAyB;gBAE3B,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK5C;;OAEG;IACH,OAAO,IAAI,gBAAgB;IAyC3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA6C3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA4D1B;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAqD5B;;;;;;;OAOG;IACH,OAAO,CAAC,yBAAyB;CAmClC"}