@selvakumaresra/specship 0.1.3 → 0.4.0

package/dist/resolution/spec-link-resolver.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * SpecLinkResolver
+ *
+ * Mirrors the role of `ReferenceResolver` for spec → code links. Each sync
+ * cycle, this resolver:
+ *
+ *   1. For every changed file, walks spec_links whose `target_file_path`
+ *      matches and re-resolves `resolved_node_id` against the current
+ *      `nodes` table by (file_path, qualified_name, kind).
+ *   2. Compares the resolved node's signature to `node_sig_at_link`. If
+ *      changed → state transitions to `drifted (drift_axis='code')`.
+ *   3. If no matching node exists → `resolved_node_id = NULL` and the link
+ *      transitions to `orphaned` (unless already terminal-ish: `verified`,
+ *      `broken` stay; orphaned is the new resting state).
+ *   4. Spec hash drift is handled separately by the spec extraction stage
+ *      (it calls `markSpecDrifted` directly).
+ *
+ * Why this is much simpler than ReferenceResolver:
+ *   - No cross-file import / framework resolution. Links carry their own
+ *     logical target (file + qualified_name) — no name-matching required.
+ *   - No LRU caches needed: the SQLite index on
+ *     (target_file_path, target_qualified_name) makes lookups O(log N).
+ *
+ * It also handles the inbound side: applying `SpecLinkCandidate[]` produced
+ * by spec extractors (provenance='spec-declaration', confidence 0.7) and
+ * by code-comment scanning (provenance='code-comment', confidence 0.9).
+ * Highest-confidence signal wins per logical key — `upsertSpecLink` enforces
+ * this.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecLinkResolver = void 0;
+/** Pattern: `// @implements REQ-X` or `# @implements REQ-X` etc. */
+const CODE_COMMENT_IMPL = /@implements\s+([A-Za-z][A-Za-z0-9_.-]*)/g;
+/**
+ * Terminal-ish states that the resolver does NOT downgrade automatically.
+ * `verified` is the success terminal; `broken` requires explicit re-verify.
+ * `orphaned` won't become `implemented` again until the agent re-asserts.
+ */
+const STICKY_STATES = new Set(['verified', 'broken']);
+class SpecLinkResolver {
+    queries;
+    specQueries;
+    opts;
+    constructor(queries, specQueries, opts = {}) {
+        this.queries = queries;
+        this.specQueries = specQueries;
+        this.opts = opts;
+    }
+    /**
+     * Re-resolve spec_links for a set of changed files. Call this from the
+     * sync pipeline after code extraction completes for those files.
+     */
+    resolveLinksForFiles(changedFiles) {
+        const stats = this.makeStats();
+        for (const file of changedFiles) {
+            this.resolveLinksForFile(file, stats);
+        }
+        return stats;
+    }
+    /**
+     * Re-resolve every spec_link in the database. Used by `indexAll` on a
+     * fresh build, and as a paranoia pass after large refactors.
+     */
+    resolveAll() {
+        const stats = this.makeStats();
+        for (const link of this.specQueries.getAllLinks()) {
+            this.resolveOneLink(link, stats);
+        }
+        return stats;
+    }
+    /**
+     * Re-resolve all links whose logical target lives in `filePath`.
+     */
+    resolveLinksForFile(filePath, stats) {
+        const links = this.specQueries.getLinksByTargetFile(filePath);
+        for (const link of links) {
+            this.resolveOneLink(link, stats);
+        }
+    }
+    resolveOneLink(link, stats) {
+        stats.scanned++;
+        const node = this.findLogicalTarget(link.targetFilePath, link.targetQualifiedName, link.targetNodeKind);
+        const now = Date.now();
+        if (node === null) {
+            // Logical target vanished. Mark orphaned unless link is sticky.
+            this.specQueries.updateSpecLinkResolution(link.id, null, now);
+            if (!STICKY_STATES.has(link.state) && link.state !== 'orphaned') {
+                this.specQueries.updateSpecLinkState(link.id, 'orphaned', null, now);
+                stats.orphaned++;
+            }
+            return;
+        }
+        // Target found — update resolved_node_id cache.
+        this.specQueries.updateSpecLinkResolution(link.id, node.id, now);
+        stats.reresolved++;
+        // Code-side drift detection. We compare the node's current signature
+        // to the snapshot taken at link creation. If the link has no baseline
+        // (older link), don't trip drift — just adopt the current signature
+        // on the next link_verify.
+        if (link.nodeSigAtLink !== undefined &&
+            link.nodeSigAtLink !== '' &&
+            node.signature !== undefined &&
+            node.signature !== link.nodeSigAtLink &&
+            !STICKY_STATES.has(link.state)) {
+            this.specQueries.updateSpecLinkState(link.id, 'drifted', 'code', now);
+            stats.driftedCode++;
+            if (this.opts.verbose) {
+                // eslint-disable-next-line no-console
+                console.error(`[SpecLinkResolver] drift(code) ${link.targetQualifiedName} for spec ${link.specId}`);
+            }
+        }
+    }
+    /**
+     * Look up a node by logical identity: (file_path, qualified_name).
+     * `kind` is a hint, not a hard filter — we prefer an exact-kind match
+     * but fall back to any kind on the same path/qname (a function turned
+     * method is still "the same logical symbol" from the spec's POV).
+     */
+    findLogicalTarget(filePath, qualifiedName, kind) {
+        const candidates = this.queries.getNodesByQualifiedNameExact(qualifiedName);
+        if (candidates.length === 0)
+            return null;
+        // Prefer same-file matches.
+        const sameFile = candidates.filter((n) => n.filePath === filePath);
+        if (sameFile.length === 0)
+            return null;
+        // Prefer same-kind matches within the same file.
+        const sameKind = sameFile.find((n) => n.kind === kind);
+        if (sameKind)
+            return sameKind;
+        // Fall back to first same-file candidate.
+        return sameFile[0] ?? null;
+    }
+    // ===========================================================================
+    // Inbound: apply link candidates discovered during extraction
+    // ===========================================================================
+    /**
+     * Apply spec-declared `implementations:` links. Provenance = 'spec-declaration',
+     * confidence 0.7. Idempotent — upsert by logical key.
+     */
+    applyDeclarationCandidates(candidates, specsByIdForHash, stats) {
+        const now = Date.now();
+        for (const c of candidates) {
+            const spec = specsByIdForHash.get(c.specId);
+            if (!spec)
+                continue; // spec hasn't been inserted yet — skip; resolver will retry on next sync.
+            const resolvedNode = this.findLogicalTarget(c.targetFilePath, c.targetQualifiedName, c.targetNodeKind);
+            this.specQueries.upsertSpecLink({
+                specId: c.specId,
+                targetFilePath: c.targetFilePath,
+                targetQualifiedName: c.targetQualifiedName,
+                targetNodeKind: c.targetNodeKind,
+                resolvedNodeId: resolvedNode?.id,
+                kind: c.kind,
+                state: resolvedNode ? 'implemented' : 'orphaned',
+                driftAxis: null,
+                specHashAtLink: spec.contentHash,
+                nodeSigAtLink: resolvedNode?.signature,
+                provenance: 'spec-declaration',
+                confidence: 0.7,
+                createdAt: now,
+                updatedAt: now,
+            });
+            if (stats)
+                stats.candidatesApplied++;
+        }
+    }
+    /**
+     * Scan node docstrings for `@implements REQ-X` markers and emit spec links.
+     *
+     * This is the load-bearing backstop when the agent forgets to call
+     * specship_link_assert: the spec link still gets created from the
+     * `// @implements REQ-X` comment in code. Provenance = 'code-comment',
+     * confidence 0.9.
+     *
+     * Called from the sync pipeline after code extraction for changed files.
+     * Bounded by the changed-files set — full-graph scans only on indexAll.
+     */
+    applyCodeCommentLinks(changedFiles, stats) {
+        const now = Date.now();
+        for (const file of changedFiles) {
+            const nodes = this.queries.getNodesByFile(file);
+            for (const node of nodes) {
+                const sources = [node.docstring, node.signature].filter((s) => typeof s === 'string');
+                for (const source of sources) {
+                    // Reset regex state for global pattern.
+                    CODE_COMMENT_IMPL.lastIndex = 0;
+                    let match;
+                    while ((match = CODE_COMMENT_IMPL.exec(source)) !== null) {
+                        const specId = match[1];
+                        if (!specId)
+                            continue;
+                        const spec = this.specQueries.getSpecById(specId);
+                        if (!spec)
+                            continue;
+                        this.specQueries.upsertSpecLink({
+                            specId,
+                            targetFilePath: node.filePath,
+                            targetQualifiedName: node.qualifiedName,
+                            targetNodeKind: node.kind,
+                            resolvedNodeId: node.id,
+                            kind: 'implements',
+                            state: 'implemented',
+                            driftAxis: null,
+                            specHashAtLink: spec.contentHash,
+                            nodeSigAtLink: node.signature,
+                            provenance: 'code-comment',
+                            confidence: 0.9,
+                            createdAt: now,
+                            updatedAt: now,
+                        });
+                        if (stats)
+                            stats.commentLinksApplied++;
+                    }
+                }
+            }
+        }
+    }
+    // ===========================================================================
+    // Spec-side drift (called from spec extraction stage)
+    // ===========================================================================
+    /**
+     * Mark every link of `specId` as `drifted(spec)` because the spec's
+     * `contentHash` changed since the link was established. Sticky states
+     * (`verified`, `broken`) are left alone.
+     *
+     * The agent's job after seeing drift: re-read the spec, update code if
+     * needed, call specship_link_verify to take state back to `verified`.
+     */
+    markSpecDrifted(specId, newSpecHash) {
+        const now = Date.now();
+        let count = 0;
+        for (const link of this.specQueries.getLinksBySpec(specId)) {
+            if (STICKY_STATES.has(link.state))
+                continue;
+            if (link.specHashAtLink === newSpecHash)
+                continue;
+            this.specQueries.updateSpecLinkState(link.id, 'drifted', 'spec', now);
+            count++;
+        }
+        return count;
+    }
+    // ===========================================================================
+    // Helpers
+    // ===========================================================================
+    makeStats() {
+        return {
+            scanned: 0,
+            reresolved: 0,
+            orphaned: 0,
+            driftedCode: 0,
+            candidatesApplied: 0,
+            commentLinksApplied: 0,
+        };
+    }
+}
+exports.SpecLinkResolver = SpecLinkResolver;
+//# sourceMappingURL=spec-link-resolver.js.map

package/dist/resolution/spec-link-resolver.js.map

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

package/dist/resolution/strip-comments.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Per-language comment stripper for framework route extractors.
+ *
+ * Replaces comment characters and string-literal contents that hide
+ * routing-shaped text with spaces (NOT removal) so that source offsets
+ * are preserved. This means `match.index` from a regex run on the
+ * stripped output still maps to the same line in the original source.
+ *
+ * Example:
+ *   Input:  "x = 1  # path('/fake/', V)\n real = 2"
+ *   Output: "x = 1                       \n real = 2"
+ *
+ * Why strip strings/docstrings as well as comments? Python module/class
+ * docstrings are a common source of false positives — they often contain
+ * `path('/example/', View)` examples in usage docs. We treat triple-quoted
+ * strings the same as comments. Single-line strings stay intact (a `#`
+ * inside a Python string is NOT a comment).
+ *
+ * Scope: this is a pragmatic, regex-supporting helper, not a full parser.
+ * It does NOT try to detect JS regex literals, Python f-string expressions,
+ * or shell-style heredocs. Those edge cases are not load-bearing for the
+ * `path(...)`, `Route::get(...)`, `app.get(...)` style patterns that
+ * framework extractors scan for.
+ */
+export type CommentLang = 'python' | 'javascript' | 'typescript' | 'php' | 'ruby' | 'java' | 'csharp' | 'swift' | 'go' | 'rust';
+export declare function stripCommentsForRegex(content: string, lang: CommentLang): string;
+//# sourceMappingURL=strip-comments.d.ts.map

package/dist/resolution/strip-comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strip-comments.d.ts","sourceRoot":"","sources":["../../src/resolution/strip-comments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,YAAY,GACZ,YAAY,GACZ,KAAK,GACL,MAAM,GACN,MAAM,GACN,QAAQ,GACR,OAAO,GACP,IAAI,GACJ,MAAM,CAAC;AAEX,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAqBhF"}