@specship/specship 0.11.0

package/dist/db/spec-queries.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Spec & Workflow Database Queries
+ *
+ * Prepared statements for CRUD on the v5 spec + workflow tables.
+ * Mirrors the pattern used by `QueryBuilder` in `./queries.ts`: lazy
+ * prepared statements cached per instance.
+ *
+ * Kept separate from QueryBuilder to avoid bloating that class —
+ * it's already ~1900 lines.
+ */
+import { SqliteDatabase } from './sqlite-adapter';
+import { Spec, SpecFile, SpecLink, SpecLinkState, SpecLinkKind, SpecLinkDriftAxis, WorkflowRun, WorkflowRunStatus, WorkflowEvent, IsolationEnvironment } from '../types';
+/**
+ * One ranked hit from {@link SpecQueries.searchSpecs}. Carries enough to act on
+ * without a follow-up fetch (REQ-TRIAGE-001.A1): the spec, a relevance score,
+ * and a matched snippet from the body.
+ */
+export interface SpecSearchResult {
+    spec: Spec;
+    /** Relevance score (higher = better; bm25 magnitude, normalized positive). */
+    score: number;
+    /** A short matched excerpt from the body, with `…` ellipses around the hit. */
+    snippet: string;
+}
+export declare class SpecQueries {
+    private db;
+    private stmts;
+    constructor(db: SqliteDatabase);
+    /**
+     * Insert or replace a spec row. Also inserts a virtual node projection
+     * into `nodes` with kind='spec' so graph traversal sees the spec.
+     *
+     * The virtual node's `id` is `spec:${spec.id}` (kind:hash convention from
+     * tree-sitter-helpers, but hand-built — specs don't go through tree-sitter).
+     * `qualified_name = spec.id` so SpecLinkResolver and specship_explore can
+     * find specs by their stable ID.
+     */
+    insertSpec(spec: Spec): void;
+    /**
+     * Batch-insert specs in a transaction.
+     */
+    insertSpecsBatch(specs: Spec[]): void;
+    /**
+     * Delete all specs for a given source file. CASCADE removes children
+     * (parent_id FK) and any spec_links to those specs.
+     */
+    deleteSpecsByFile(sourcePath: string): void;
+    /** Look up a spec by its embedded ID. */
+    getSpecById(id: string): Spec | null;
+    /** All specs from a given source file, sorted by start_line. */
+    getSpecsByFile(sourcePath: string): Spec[];
+    /** Child specs of a given parent (requirements under a document, etc.). */
+    getSpecsByParent(parentId: string): Spec[];
+    /**
+     * All specs of one kind. Used to surface the (small) `domain` fact layer
+     * cheaply without scanning every requirement/acceptance row (REQ-DOMAIN-005).
+     */
+    getSpecsByKind(kind: Spec['kind']): Spec[];
+    /** All specs (small projects only; large repos should filter). */
+    getAllSpecs(): Spec[];
+    /**
+     * Full-text search over specs (REQ-TRIAGE-001). Returns scored, ranked specs
+     * matched against `specs_fts` (id/title/body), each with a body snippet.
+     *
+     * Mirrors `QueryBuilder.searchNodes`: term sanitization strips FTS5 special
+     * chars + boolean operators, prefix-matches each term, and OR-joins them.
+     * `title` is weighted heavily so a name match outranks an incidental body
+     * mention. On any FTS failure (or an all-noise query) it returns `[]` rather
+     * than throwing — callers distinguish "no specs indexed" from "no match" via
+     * {@link getAllSpecs}.
+     */
+    searchSpecs(query: string, limit?: number): SpecSearchResult[];
+    upsertSpecFile(file: SpecFile): void;
+    deleteSpecFile(path: string): void;
+    getSpecFileByPath(path: string): SpecFile | null;
+    getAllSpecFiles(): SpecFile[];
+    /**
+     * Insert a fresh link. Most callers want `upsertSpecLink` (idempotent).
+     */
+    insertSpecLink(link: Omit<SpecLink, 'id'>): number;
+    /**
+     * Idempotent upsert keyed on logical identity
+     * (spec_id, target_file_path, target_qualified_name, kind). If a link
+     * with the same logical key exists, update it; otherwise insert. Higher
+     * provenance/confidence wins (agent-asserted overrides code-comment, etc.).
+     *
+     * Returns the link row's id.
+     */
+    upsertSpecLink(link: Omit<SpecLink, 'id'>): number;
+    /** Find a link by its logical identity (no node_id involved). */
+    findLogicalLink(specId: string, targetFilePath: string, targetQualifiedName: string, kind: SpecLinkKind): SpecLink | null;
+    deleteSpecLink(id: number): void;
+    updateSpecLinkState(id: number, state: SpecLinkState, driftAxis?: SpecLinkDriftAxis, updatedAt?: number): void;
+    /**
+     * Update the resolved_node_id cache. Called by SpecLinkResolver after
+     * each sync. NULL means the logical target doesn't currently exist
+     * (caller should set state='orphaned' separately).
+     */
+    updateSpecLinkResolution(id: number, resolvedNodeId: string | null, updatedAt?: number): void;
+    getLinkById(id: number): SpecLink | null;
+    /** All links for a spec (e.g., for specship_spec response). */
+    getLinksBySpec(specId: string): SpecLink[];
+    /** All links pointing at a given resolved node (e.g., for specship_node response). */
+    getLinksByNode(nodeId: string): SpecLink[];
+    /**
+     * Links whose logical target lives in a particular file. Used by
+     * SpecLinkResolver after a file is re-extracted to know which links
+     * need re-resolution.
+     */
+    getLinksByTargetFile(filePath: string): SpecLink[];
+    /** Links by logical target identity (file + qualified_name). */
+    getLinksByLogicalTarget(filePath: string, qualifiedName: string): SpecLink[];
+    /** Links in one or more states — drives specship_drifted. */
+    getLinksByState(states: SpecLinkState[]): SpecLink[];
+    getAllLinks(): SpecLink[];
+    insertWorkflowRun(run: WorkflowRun): void;
+    updateWorkflowRun(run: WorkflowRun): void;
+    getWorkflowRunById(id: string): WorkflowRun | null;
+    getWorkflowRunsByStatus(statuses: WorkflowRunStatus[]): WorkflowRun[];
+    getWorkflowRunsByName(workflowName: string): WorkflowRun[];
+    getAllWorkflowRuns(limit?: number): WorkflowRun[];
+    insertWorkflowEvent(event: Omit<WorkflowEvent, 'id'>): void;
+    getEventsByRun(workflowRunId: string, limit?: number): WorkflowEvent[];
+    insertIsolationEnv(env: IsolationEnvironment): void;
+    updateIsolationEnv(env: IsolationEnvironment): void;
+    getIsolationEnvById(id: string): IsolationEnvironment | null;
+    getActiveIsolationEnvByRun(workflowRunId: string): IsolationEnvironment | null;
+    getAllActiveIsolationEnvs(): IsolationEnvironment[];
+}
+//# sourceMappingURL=spec-queries.d.ts.map

package/dist/db/spec-queries.d.ts.map

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