@specferret/core 0.1.3 → 0.2.0

package/README.md

@@ -1,62 +1,62 @@
-# @specferret/core
-
-Core engine for SpecFerret contract extraction, validation, graph reconciliation, and drift analysis.
-
-[![npm version](https://img.shields.io/npm/v/@specferret/core)](https://www.npmjs.com/package/@specferret/core)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
-
-## What this package is for
-
-`@specferret/core` is the runtime library behind the CLI. Use it when you want to embed SpecFerret behavior in scripts, custom tooling, or internal workflows.
-
-It includes:
-
-- Store implementations (`sqlite`, `postgres`)
-- Frontmatter extraction and schema validation
-- Reconciler logic for direct/transitive impact
-- Context graph generation utilities
-
-## Install
-
-```bash
-npm i @specferret/core
-```
-
-## Runtime requirements
-
-- Bun 1.0+
-
-SpecFerret core is Bun-first and uses Bun-compatible runtime behavior.
-
-## Typical consumers
-
-- Internal platform tooling that needs drift checks in-process
-- CI wrappers that need machine-readable drift metadata
-- Custom developer workflows on top of SpecFerret reconciliation data
-
-## Validation status
-
-Core behavior is validated through the Sprint 5 external branch-matrix harness (spec-kit + BMAD), including explicit assertions for:
-
-- S40 transitive depth thresholds
-- S41 review proof artifacts
-- S42 extract determinism
-
-Latest green runs:
-
-- spec-kit: https://github.com/BenGardiner123/spec-ferret-validation-spec-kit/actions/runs/23962649755
-- BMAD: https://github.com/BenGardiner123/specferret-validation-bmad/actions/runs/23962652352
-
-## Looking for the CLI?
-
-Install `@specferret/cli` if you want the end-user command interface:
-
-```bash
-bun install -g @specferret/cli
-```
-
-## Links
-
-- Source: https://github.com/BenGardiner123/spec-ferret
-- Docs: https://specferret.dev
-- CLI package: https://www.npmjs.com/package/@specferret/cli
+# @specferret/core
+
+Core engine for SpecFerret contract extraction, validation, graph reconciliation, and drift analysis.
+
+[![npm version](https://img.shields.io/npm/v/@specferret/core)](https://www.npmjs.com/package/@specferret/core)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+
+## What this package is for
+
+`@specferret/core` is the runtime library behind the CLI. Use it when you want to embed SpecFerret behavior in scripts, custom tooling, or internal workflows.
+
+It includes:
+
+- Store implementations (`sqlite`, `postgres`)
+- Frontmatter extraction and schema validation
+- Reconciler logic for direct/transitive impact
+- Context graph generation utilities
+
+## Install
+
+```bash
+npm i @specferret/core
+```
+
+## Runtime requirements
+
+- Bun 1.0+
+
+SpecFerret core is Bun-first and uses Bun-compatible runtime behavior.
+
+## Typical consumers
+
+- Internal platform tooling that needs drift checks in-process
+- CI wrappers that need machine-readable drift metadata
+- Custom developer workflows on top of SpecFerret reconciliation data
+
+## Validation status
+
+Core behavior is validated through the Sprint 5 external branch-matrix harness (spec-kit + BMAD), including explicit assertions for:
+
+- S40 transitive depth thresholds
+- S41 review proof artifacts
+- S42 extract determinism
+
+Latest green runs:
+
+- spec-kit: https://github.com/BenGardiner123/spec-ferret-validation-spec-kit/actions/runs/23962649755
+- BMAD: https://github.com/BenGardiner123/specferret-validation-bmad/actions/runs/23962652352
+
+## Looking for the CLI?
+
+Install `@specferret/cli` if you want the end-user command interface:
+
+```bash
+bun install -g @specferret/cli
+```
+
+## Links
+
+- Source: https://github.com/BenGardiner123/spec-ferret
+- Docs: https://specferret.dev
+- CLI package: https://www.npmjs.com/package/@specferret/cli

package/dist/context/index.d.ts

@@ -1,4 +1,6 @@
 import type { DBStore } from "../store/types.js";
+export declare const CONTEXT_VERSION: "2.0";
+export declare const CONTEXT_SCHEMA_VERSION: "1.0.0";
 export interface ContextContract {
     id: string;
     type: string;
@@ -12,12 +14,14 @@ export interface ContextEdge {
     to: string;
 }
 export interface FerretContext {
-    version: "2.0";
+    version: typeof CONTEXT_VERSION;
+    schemaVersion: typeof CONTEXT_SCHEMA_VERSION;
     generated: string;
     contracts: ContextContract[];
     edges: ContextEdge[];
     needsReview: string[];
 }
+export declare function readContextFile(contextPath: string): FerretContext;
 /**
  * Reads the full graph from the store and writes .ferret/context.json.
  * Called automatically at the end of every ferret scan.

package/dist/context/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CA4Ef"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,eAAO,MAAM,eAAe,EAAG,KAAc,CAAC;AAC9C,eAAO,MAAM,sBAAsB,EAAG,OAAgB,CAAC;AAUvD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,eAAe,CAAC;IAChC,aAAa,EAAE,OAAO,sBAAsB,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAyCD,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAalE;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Ef"}

package/dist/context/index.js

@@ -1,5 +1,50 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+export const CONTEXT_VERSION = "2.0";
+export const CONTEXT_SCHEMA_VERSION = "1.0.0";
+function normalizeContext(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new Error("ferret: invalid context.json format. Run 'ferret scan' to regenerate .ferret/context.json.");
+    }
+    const candidate = raw;
+    const contextVersion = candidate.version;
+    if (contextVersion !== CONTEXT_VERSION) {
+        throw new Error(`ferret: unsupported context.json version '${String(contextVersion)}'. Run 'ferret scan' with the current CLI to regenerate .ferret/context.json.`);
+    }
+    const schemaVersion = candidate.schemaVersion;
+    if (schemaVersion !== undefined && schemaVersion !== CONTEXT_SCHEMA_VERSION) {
+        throw new Error(`ferret: unsupported context schemaVersion '${String(schemaVersion)}'. Run 'ferret scan' with the current CLI to migrate .ferret/context.json.`);
+    }
+    // Known migration path: V2 payloads created before schemaVersion was introduced.
+    const legacy = candidate;
+    return {
+        version: CONTEXT_VERSION,
+        schemaVersion: CONTEXT_SCHEMA_VERSION,
+        generated: typeof legacy.generated === "string"
+            ? legacy.generated
+            : new Date(0).toISOString(),
+        contracts: Array.isArray(legacy.contracts)
+            ? legacy.contracts
+            : [],
+        edges: Array.isArray(legacy.edges) ? legacy.edges : [],
+        needsReview: Array.isArray(legacy.needsReview)
+            ? legacy.needsReview
+            : [],
+    };
+}
+export function readContextFile(contextPath) {
+    try {
+        const raw = fs.readFileSync(contextPath, "utf-8");
+        return normalizeContext(JSON.parse(raw));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith("ferret:")) {
+            throw error;
+        }
+        throw new Error(`ferret: unable to read .ferret/context.json (${message}). Run 'ferret scan' to regenerate it.`);
+    }
+}
 /**
  * Reads the full graph from the store and writes .ferret/context.json.
  * Called automatically at the end of every ferret scan.
@@ -51,7 +96,8 @@ export async function writeContext(store, projectRoot) {
         .filter((c) => needsReviewNodeIds.has(c.node_id) || c.status === "needs-review")
         .map((c) => c.id);
     const context = {
-        version: "2.0",
+        version: CONTEXT_VERSION,
+        schemaVersion: CONTEXT_SCHEMA_VERSION,
         generated: new Date().toISOString(),
         contracts: contextContracts,
         edges,

package/dist/context/index.js.map

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

package/dist/extractor/__fixtures__/typescript/generics.d.ts

@@ -0,0 +1,6 @@
+export interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    nextCursor?: string;
+}
+//# sourceMappingURL=generics.d.ts.map

package/dist/extractor/__fixtures__/typescript/generics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generics.d.ts","sourceRoot":"","sources":["../../../../src/extractor/__fixtures__/typescript/generics.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/extractor/__fixtures__/typescript/generics.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=generics.js.map

package/dist/extractor/__fixtures__/typescript/generics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generics.js","sourceRoot":"","sources":["../../../../src/extractor/__fixtures__/typescript/generics.ts"],"names":[],"mappings":""}

package/dist/extractor/__fixtures__/typescript/intersections.d.ts

@@ -0,0 +1,6 @@
+export type UserIdentity = {
+    id: string;
+} & {
+    tenantId: string;
+};
+//# sourceMappingURL=intersections.d.ts.map

package/dist/extractor/__fixtures__/typescript/intersections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intersections.d.ts","sourceRoot":"","sources":["../../../../src/extractor/__fixtures__/typescript/intersections.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG;IACF,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC"}

package/dist/extractor/__fixtures__/typescript/intersections.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=intersections.js.map

package/dist/extractor/__fixtures__/typescript/intersections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intersections.js","sourceRoot":"","sources":["../../../../src/extractor/__fixtures__/typescript/intersections.ts"],"names":[],"mappings":""}

package/dist/extractor/__fixtures__/typescript/optional-nested.d.ts

@@ -0,0 +1,8 @@
+export interface SearchResult {
+    id: string;
+    metadata?: {
+        tags?: string[];
+        score: number;
+    };
+}
+//# sourceMappingURL=optional-nested.d.ts.map

package/dist/extractor/__fixtures__/typescript/optional-nested.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-nested.d.ts","sourceRoot":"","sources":["../../../../src/extractor/__fixtures__/typescript/optional-nested.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH"}

package/dist/extractor/__fixtures__/typescript/optional-nested.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=optional-nested.js.map

package/dist/extractor/__fixtures__/typescript/optional-nested.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-nested.js","sourceRoot":"","sources":["../../../../src/extractor/__fixtures__/typescript/optional-nested.ts"],"names":[],"mappings":""}

package/dist/extractor/__fixtures__/typescript/unions.d.ts

@@ -0,0 +1,5 @@
+export interface MaybeUser {
+    id: string | null;
+    displayName?: string | null;
+}
+//# sourceMappingURL=unions.d.ts.map

package/dist/extractor/__fixtures__/typescript/unions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unions.d.ts","sourceRoot":"","sources":["../../../../src/extractor/__fixtures__/typescript/unions.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B"}

package/dist/extractor/__fixtures__/typescript/unions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=unions.js.map

package/dist/extractor/__fixtures__/typescript/unions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unions.js","sourceRoot":"","sources":["../../../../src/extractor/__fixtures__/typescript/unions.ts"],"names":[],"mappings":""}

package/dist/extractor/__fixtures__/typescript/unsupported-syntax.d.ts

@@ -0,0 +1,7 @@
+export type RouteMap<T extends string> = {
+    [K in T]: {
+        method: 'GET' | 'POST';
+        secured?: boolean;
+    };
+};
+//# sourceMappingURL=unsupported-syntax.d.ts.map

package/dist/extractor/__fixtures__/typescript/unsupported-syntax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsupported-syntax.d.ts","sourceRoot":"","sources":["../../../../src/extractor/__fixtures__/typescript/unsupported-syntax.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI;KACtC,CAAC,IAAI,CAAC,GAAG;QACR,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB;CACF,CAAC"}

package/dist/extractor/__fixtures__/typescript/unsupported-syntax.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=unsupported-syntax.js.map

package/dist/extractor/__fixtures__/typescript/unsupported-syntax.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsupported-syntax.js","sourceRoot":"","sources":["../../../../src/extractor/__fixtures__/typescript/unsupported-syntax.ts"],"names":[],"mappings":""}

package/dist/extractor/contract-types.d.ts

@@ -0,0 +1,5 @@
+export declare const CONTRACT_TYPES: readonly ["api", "table", "type", "event", "flow", "config"];
+export type ContractType = (typeof CONTRACT_TYPES)[number];
+export declare function isContractType(value: unknown): value is ContractType;
+export declare function formatAllowedContractTypes(): string;
+//# sourceMappingURL=contract-types.d.ts.map

package/dist/extractor/contract-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-types.d.ts","sourceRoot":"","sources":["../../src/extractor/contract-types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,8DAA+D,CAAC;AAE3F,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD"}

package/dist/extractor/contract-types.js

@@ -0,0 +1,8 @@
+export const CONTRACT_TYPES = ['api', 'table', 'type', 'event', 'flow', 'config'];
+export function isContractType(value) {
+    return typeof value === 'string' && CONTRACT_TYPES.includes(value);
+}
+export function formatAllowedContractTypes() {
+    return CONTRACT_TYPES.join(', ');
+}
+//# sourceMappingURL=contract-types.js.map

package/dist/extractor/contract-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-types.js","sourceRoot":"","sources":["../../src/extractor/contract-types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAI3F,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,cAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,0BAA0B;IACxC,OAAO,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/extractor/frontmatter.d.ts

@@ -1,12 +1,17 @@
+import type { ContractType } from './contract-types.js';
 export interface ExtractionResult {
     filePath: string;
     fileType: 'spec' | 'code';
     contracts: Array<{
         id: string;
-        type: string;
+        type: ContractType;
         shape: object;
         shape_hash: string;
         imports: string[];
+        /** Path to the TypeScript source file (code-first contracts only). */
+        sourceFile?: string;
+        /** TypeScript symbol name (code-first contracts only). */
+        sourceSymbol?: string;
     }>;
     extractedBy: 'gray-matter' | 'tree-sitter';
     extractedAt: number;

package/dist/extractor/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/extractor/frontmatter.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,SAAS,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC,CAAC;IACH,WAAW,EAAE,aAAa,GAAG,aAAa,CAAC;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAuClB"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/extractor/frontmatter.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,SAAS,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,YAAY,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,sEAAsE;QACtE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,0DAA0D;QAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;IACH,WAAW,EAAE,aAAa,GAAG,aAAa,CAAC;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAkD3F"}

package/dist/extractor/frontmatter.js

@@ -1,7 +1,7 @@
 // Synchronous only. No async. No await. Anywhere in this file.
 // Extractor layer — turns a spec file into an ExtractionResult using gray-matter.
 import matter from 'gray-matter';
-import { validateFerretSchema } from './validator.js';
+import { validateContractType, validateFerretSchema } from './validator.js';
 import { hashSchema } from './hash.js';
 /**
  * Extracts a FerretContract from a spec file's YAML frontmatter.
@@ -25,23 +25,34 @@ export function extractFromSpecFile(filePath, fileContent) {
             warning: 'no-frontmatter',
         };
     }
-    const missingFields = ['id', 'type', 'shape'].filter(f => !ferret[f]);
+    const missingFields = ['id', 'type', 'shape'].filter((f) => !ferret[f]);
     if (missingFields.length > 0) {
         throw new Error(`Missing required frontmatter fields in ${filePath}: ${missingFields.join(', ')}`);
     }
+    const typeValidation = validateContractType(ferret.type, filePath);
+    if (!typeValidation.valid) {
+        throw new Error(typeValidation.error);
+    }
     // validateFerretSchema never throws — only warns on unsupported keywords
     const validation = validateFerretSchema(ferret.shape, filePath);
-    validation.warnings.forEach(w => process.stderr.write(w + '\n'));
+    validation.warnings.forEach((w) => process.stderr.write(w + '\n'));
+    const source = ferret.source;
+    const sourceFile = typeof source?.file === 'string' ? source.file : undefined;
+    const sourceSymbol = typeof source?.symbol === 'string' ? source.symbol : undefined;
     return {
         filePath,
         fileType: 'spec',
-        contracts: [{
+        contracts: [
+            {
                 id: ferret.id,
-                type: ferret.type,
+                type: typeValidation.value,
                 shape: ferret.shape,
                 shape_hash: hashSchema(ferret.shape),
                 imports: Array.isArray(ferret.imports) ? ferret.imports : [],
-            }],
+                ...(sourceFile !== undefined && { sourceFile }),
+                ...(sourceSymbol !== undefined && { sourceSymbol }),
+            },
+        ],
         extractedBy: 'gray-matter',
         extractedAt: Date.now(),
     };

package/dist/extractor/frontmatter.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/extractor/frontmatter.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,kFAAkF;AAElF,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAiBvC;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,WAAmB;IAEnB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;IAE5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,QAAQ;YACR,QAAQ,EAAE,MAAM;YAChB,SAAS,EAAE,EAAE;YACb,WAAW,EAAE,aAAa;YAC1B,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;YACvB,OAAO,EAAE,gBAAgB;SAC1B,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,0CAA0C,QAAQ,KAAK,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAClF,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,MAAM,UAAU,GAAG,oBAAoB,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAChE,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAEjE,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE,MAAM;QAChB,SAAS,EAAE,CAAC;gBACV,EAAE,EAAE,MAAM,CAAC,EAAY;gBACvB,IAAI,EAAE,MAAM,CAAC,IAAc;gBAC3B,KAAK,EAAE,MAAM,CAAC,KAAe;gBAC7B,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC;gBACpC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAmB,CAAC,CAAC,CAAC,EAAE;aACzE,CAAC;QACF,WAAW,EAAE,aAAa;QAC1B,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;KACxB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/extractor/frontmatter.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,kFAAkF;AAElF,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAsBvC;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,WAAmB;IACvE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;IAE5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,QAAQ;YACR,QAAQ,EAAE,MAAM;YAChB,SAAS,EAAE,EAAE;YACb,WAAW,EAAE,aAAa;YAC1B,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;YACvB,OAAO,EAAE,gBAAgB;SAC1B,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,0CAA0C,QAAQ,KAAK,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrG,CAAC;IAED,MAAM,cAAc,GAAG,oBAAoB,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACnE,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,yEAAyE;IACzE,MAAM,UAAU,GAAG,oBAAoB,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAChE,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAEnE,MAAM,MAAM,GAAG,MAAM,CAAC,MAA0D,CAAC;IACjF,MAAM,UAAU,GAAG,OAAO,MAAM,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,MAAM,YAAY,GAAG,OAAO,MAAM,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAEpF,OAAO;QACL,QAAQ;QACR,QAAQ,EAAE,MAAM;QAChB,SAAS,EAAE;YACT;gBACE,EAAE,EAAE,MAAM,CAAC,EAAY;gBACvB,IAAI,EAAE,cAAc,CAAC,KAAK;gBAC1B,KAAK,EAAE,MAAM,CAAC,KAAe;gBAC7B,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC;gBACpC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAE,MAAM,CAAC,OAAoB,CAAC,CAAC,CAAC,EAAE;gBAC1E,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,CAAC;gBAC/C,GAAG,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,CAAC;aACpD;SACF;QACD,WAAW,EAAE,aAAa;QAC1B,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;KACxB,CAAC;AACJ,CAAC"}

package/dist/extractor/typescript.d.ts

@@ -1,13 +1,18 @@
-export type ContractType = "api" | "table" | "type" | "event" | "flow" | "config";
+import { type ContractType } from './contract-types.js';
+export type { ContractType } from './contract-types.js';
 export interface ExtractedCodeContract {
     id: string;
     type: ContractType;
     shape: Record<string, unknown>;
     sourceSymbol: string;
     filePath: string;
+    idSource?: 'inferred' | 'annotated';
 }
 export interface TypeScriptExtractionResult {
     contracts: ExtractedCodeContract[];
+    /** Hard failures — annotation parse errors, unmatched annotations, tree-sitter parse failures. */
+    errors: string[];
+    /** Soft warnings — unsupported type fallbacks, partial extractions. Detection succeeded but schema is approximate. */
     diagnostics: string[];
 }
 export declare function extractContractsFromTypeScript(filePath: string, content: string): TypeScriptExtractionResult;

package/dist/extractor/typescript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../src/extractor/typescript.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACpB,KAAK,GACL,OAAO,GACP,MAAM,GACN,OAAO,GACP,MAAM,GACN,QAAQ,CAAC;AAEb,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AA4PD,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,0BAA0B,CAgC5B"}
+{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../src/extractor/typescript.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;CACrC;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,kGAAkG;IAClG,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sHAAsH;IACtH,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAggBD,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,0BAA0B,CA+D5G"}