@specferret/core 0.1.3 → 0.1.4

package/src/extractor/validator.test.ts

@@ -0,0 +1,228 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'bun:test';
+import { validateFerretSchema, compareSchemas, validateContractType } from './validator.js';
+import { CONTRACT_TYPES } from './contract-types.js';
+
+// ─── validateFerretSchema ────────────────────────────────────────────────────
+
+describe('validateFerretSchema', () => {
+  it('warns on every unsupported keyword when present', () => {
+    const UNSUPPORTED = ['$ref', 'allOf', 'anyOf', 'oneOf', 'not', 'if', 'then', 'else', '$defs', 'definitions', 'patternProperties', 'dependencies'];
+
+    for (const keyword of UNSUPPORTED) {
+      const shape = { type: 'object', [keyword]: {} };
+      const result = validateFerretSchema(shape, 'contracts/test.contract.md');
+      assert.equal(result.warnings.length, 1);
+      assert.match(result.warnings[0], new RegExp(keyword.replace('$', '\\$')));
+      assert.match(result.warnings[0], /contracts\/test\.contract\.md/);
+      assert.equal(result.valid, true);
+    }
+  });
+
+  it('does not warn on valid supported keywords', () => {
+    const shape = {
+      type: 'object',
+      properties: {
+        id: { type: 'string', format: 'uuid' },
+        name: { type: 'string' },
+        score: { type: 'number' },
+        active: { type: 'boolean' },
+        tags: { type: 'array', items: { type: 'string' } },
+        status: { type: 'string', enum: ['pending', 'active', 'cancelled'] },
+      },
+      required: ['id', 'name'],
+      additionalProperties: false,
+    };
+    const result = validateFerretSchema(shape, 'contracts/valid.contract.md');
+    assert.equal(result.warnings.length, 0);
+    assert.equal(result.valid, true);
+  });
+
+  it('warns on multiple unsupported keywords in a single schema', () => {
+    const shape = {
+      type: 'object',
+      allOf: [{}],
+      anyOf: [{}],
+      $ref: '#/definitions/Foo',
+    };
+    const result = validateFerretSchema(shape, 'contracts/complex.contract.md');
+    assert.ok(result.warnings.length >= 3);
+    assert.equal(result.valid, true);
+  });
+
+  it('does not warn on null or primitive shape', () => {
+    assert.equal(validateFerretSchema(null, 'f.md').warnings.length, 0);
+    assert.equal(validateFerretSchema('string shape', 'f.md').warnings.length, 0);
+    assert.equal(validateFerretSchema(42, 'f.md').warnings.length, 0);
+  });
+});
+
+describe('validateContractType', () => {
+  it('accepts all six supported contract types', () => {
+    for (const contractType of CONTRACT_TYPES) {
+      const result = validateContractType(contractType, 'contracts/test.contract.md');
+      assert.equal(result.valid, true);
+      if (result.valid) {
+        assert.equal(result.value, contractType);
+      }
+    }
+  });
+
+  it('rejects unknown contract types and lists allowed values', () => {
+    const result = validateContractType('service', 'contracts/test.contract.md');
+    assert.equal(result.valid, false);
+    assert.match(result.error ?? '', /Invalid contract type 'service'/);
+    assert.match(result.error ?? '', /Allowed types: api, table, type, event, flow, config/);
+  });
+
+  it('keeps shared constants aligned with expected six core types', () => {
+    assert.deepEqual(CONTRACT_TYPES, ['api', 'table', 'type', 'event', 'flow', 'config']);
+  });
+});
+
+// ─── compareSchemas ──────────────────────────────────────────────────────────
+
+describe('compareSchemas — breaking changes', () => {
+  it('required field removed → breaking', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' }, email: { type: 'string' } },
+      required: ['id', 'email'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { id: { type: 'string' }, email: { type: 'string' } },
+      required: ['id'],
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+    assert.match(result.reason, /email/);
+  });
+
+  it('field type changed → breaking', () => {
+    const prev = { type: 'object', properties: { count: { type: 'string' } } };
+    const curr = { type: 'object', properties: { count: { type: 'integer' } } };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+  });
+
+  it('required field added → breaking', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' }, name: { type: 'string' } },
+      required: ['id'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { id: { type: 'string' }, name: { type: 'string' } },
+      required: ['id', 'name'],
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+    assert.match(result.reason, /name/);
+  });
+
+  it('enum value removed → breaking', () => {
+    const prev = { type: 'string', enum: ['pending', 'active', 'cancelled'] };
+    const curr = { type: 'string', enum: ['pending', 'active'] };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+    assert.match(result.reason, /cancelled/);
+  });
+
+  it('response type changed → breaking', () => {
+    const prev = { response: { type: 'array', items: { type: 'string' } } };
+    const curr = { response: { type: 'object', properties: {} } };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+  });
+
+  it('property removed → breaking', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' }, secret: { type: 'string' } },
+      required: ['id'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'breaking');
+    assert.match(result.reason, /secret/);
+  });
+});
+
+describe('compareSchemas — non-breaking changes', () => {
+  it('optional field added → non-breaking', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { id: { type: 'string' }, description: { type: 'string' } },
+      required: ['id'],
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'non-breaking');
+    assert.match(result.reason, /description/);
+  });
+
+  it('enum value added → non-breaking', () => {
+    const prev = { type: 'string', enum: ['pending', 'active'] };
+    const curr = { type: 'string', enum: ['pending', 'active', 'cancelled'] };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'non-breaking');
+    assert.match(result.reason, /cancelled/);
+  });
+});
+
+describe('compareSchemas — no-change', () => {
+  it('property order changed → no-change', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' }, name: { type: 'string' } },
+      required: ['id', 'name'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { name: { type: 'string' }, id: { type: 'string' } }, // order swapped
+      required: ['id', 'name'],
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'no-change');
+  });
+
+  it('required array reordered → no-change', () => {
+    const prev = {
+      type: 'object',
+      properties: { id: { type: 'string' }, email: { type: 'string' } },
+      required: ['id', 'email'],
+    };
+    const curr = {
+      type: 'object',
+      properties: { id: { type: 'string' }, email: { type: 'string' } },
+      required: ['email', 'id'], // same fields, different order
+    };
+    const result = compareSchemas(prev, curr);
+    assert.equal(result.classification, 'no-change');
+  });
+
+  it('identical schemas → no-change', () => {
+    const schema = {
+      type: 'object',
+      properties: { id: { type: 'string', format: 'uuid' } },
+      required: ['id'],
+    };
+    const result = compareSchemas(schema, { ...schema });
+    assert.equal(result.classification, 'no-change');
+  });
+
+  it('empty schemas compared → no-change', () => {
+    const result = compareSchemas({}, {});
+    assert.equal(result.classification, 'no-change');
+  });
+});

package/src/extractor/validator.ts

@@ -0,0 +1,199 @@
+// Pure function. No I/O. No side effects. Ever.
+// Validator layer — validates JSON Schema subset, classifies breaking/non-breaking/no-change.
+
+import { CONTRACT_TYPES, formatAllowedContractTypes, isContractType, type ContractType } from './contract-types.js';
+
+export type ChangeClassification = 'breaking' | 'non-breaking' | 'no-change';
+
+export interface SchemaValidationResult {
+  valid: boolean;
+  warnings: string[];
+}
+
+export interface SchemaComparisonResult {
+  classification: ChangeClassification;
+  reason: string;
+}
+
+export type ContractTypeValidationResult = { valid: true; value: ContractType } | { valid: false; error: string };
+
+export function validateContractType(contractType: unknown, filePath: string): ContractTypeValidationResult {
+  if (isContractType(contractType)) {
+    return { valid: true, value: contractType };
+  }
+
+  return {
+    valid: false,
+    error: `Invalid contract type '${String(contractType)}' in ${filePath}. Allowed types: ${formatAllowedContractTypes()}.`,
+  };
+}
+
+/**
+ * JSON Schema keywords that are explicitly NOT supported by Ferret.
+ * If any appear in a schema, a warning is emitted but the schema is still accepted.
+ * See: spec/CONTRACT-SCHEMA.md — Part 3
+ */
+const UNSUPPORTED_KEYWORDS = [
+  '$ref',
+  'allOf',
+  'anyOf',
+  'oneOf',
+  'not',
+  'if',
+  'then',
+  'else',
+  '$defs',
+  'definitions',
+  'patternProperties',
+  'dependencies',
+];
+
+/**
+ * Validates a schema object against the Ferret JSON Schema subset.
+ * Always returns valid: true — unsupported keywords produce warnings, not errors.
+ */
+export function validateFerretSchema(shape: unknown, filePath: string): SchemaValidationResult {
+  const warnings: string[] = [];
+
+  if (shape === null || typeof shape !== 'object') {
+    return { valid: true, warnings };
+  }
+
+  const serialised = JSON.stringify(shape);
+
+  for (const keyword of UNSUPPORTED_KEYWORDS) {
+    // Match the keyword as a JSON object key (surrounded by quotes)
+    if (serialised.includes(`"${keyword}"`)) {
+      warnings.push(
+        `⚠ Unsupported JSON Schema keyword: ${keyword} in ${filePath}\n` +
+          `  Ferret supports a subset of JSON Schema.\n` +
+          `  See: spec/CONTRACT-SCHEMA.md — Part 3`,
+      );
+    }
+  }
+
+  return { valid: true, warnings };
+}
+
+/**
+ * Compares two schema objects and classifies the change.
+ *
+ * Breaking:     required field removed, field type changed, enum value removed,
+ *               response/array type changed, required field added
+ * Non-breaking: optional field added, enum value added
+ * No-change:    property order changed, whitespace, required array reordered
+ */
+export function compareSchemas(previous: unknown, current: unknown): SchemaComparisonResult {
+  // Normalise: work with plain objects only
+  const prev = (typeof previous === 'object' && previous !== null ? previous : {}) as Record<string, unknown>;
+  const curr = (typeof current === 'object' && current !== null ? current : {}) as Record<string, unknown>;
+
+  // 1. Check type change at this level
+  if (prev.type !== undefined && curr.type !== undefined && prev.type !== curr.type) {
+    return { classification: 'breaking', reason: `type changed from '${prev.type}' to '${curr.type}'` };
+  }
+
+  // 2. Check required fields
+  const prevRequired = normaliseRequired(prev.required);
+  const currRequired = normaliseRequired(curr.required);
+
+  const removedRequired = prevRequired.filter((f) => !currRequired.includes(f));
+  if (removedRequired.length > 0) {
+    return { classification: 'breaking', reason: `required field(s) removed: ${removedRequired.join(', ')}` };
+  }
+
+  const addedRequired = currRequired.filter((f) => !prevRequired.includes(f));
+  if (addedRequired.length > 0) {
+    return { classification: 'breaking', reason: `required field(s) added: ${addedRequired.join(', ')}` };
+  }
+
+  // 3. Check enum changes
+  const prevEnum = normaliseEnum(prev.enum);
+  const currEnum = normaliseEnum(curr.enum);
+
+  if (prevEnum !== null && currEnum !== null) {
+    const removedEnum = prevEnum.filter((v) => !currEnum.includes(v));
+    if (removedEnum.length > 0) {
+      return { classification: 'breaking', reason: `enum value(s) removed: ${removedEnum.join(', ')}` };
+    }
+    const addedEnum = currEnum.filter((v) => !prevEnum.includes(v));
+    if (addedEnum.length > 0) {
+      return { classification: 'non-breaking', reason: `enum value(s) added: ${addedEnum.join(', ')}` };
+    }
+  }
+
+  // 4. Check properties — look for type changes in existing properties, or optional additions
+  const prevProps = (prev.properties ?? {}) as Record<string, unknown>;
+  const currProps = (curr.properties ?? {}) as Record<string, unknown>;
+
+  for (const key of Object.keys(currProps)) {
+    if (!(key in prevProps)) {
+      // New property — only breaking if it's also in required (already caught above)
+      if (currRequired.includes(key)) {
+        return { classification: 'breaking', reason: `required field added: ${key}` };
+      }
+      // Not required — non-breaking addition
+      continue;
+    }
+    // Property exists in both — check for type change recursively
+    const nested = compareSchemas(prevProps[key], currProps[key]);
+    if (nested.classification === 'breaking') {
+      return { classification: 'breaking', reason: `property '${key}': ${nested.reason}` };
+    }
+    if (nested.classification === 'non-breaking') {
+      return { classification: 'non-breaking', reason: `property '${key}': ${nested.reason}` };
+    }
+  }
+
+  // 5. Check for property removals (any removal is breaking — even "optional" fields
+  //    that consumers may depend on)
+  for (const key of Object.keys(prevProps)) {
+    if (!(key in currProps)) {
+      return { classification: 'breaking', reason: `property '${key}' removed` };
+    }
+  }
+
+  // 6. Check request/response top-level wrappers (Ferret API extension)
+  for (const wrapper of ['request', 'response'] as const) {
+    if (prev[wrapper] !== undefined || curr[wrapper] !== undefined) {
+      const nested = compareSchemas(prev[wrapper] ?? {}, curr[wrapper] ?? {});
+      if (nested.classification === 'breaking') {
+        return { classification: 'breaking', reason: `${wrapper}: ${nested.reason}` };
+      }
+      if (nested.classification === 'non-breaking') {
+        return { classification: 'non-breaking', reason: `${wrapper}: ${nested.reason}` };
+      }
+    }
+  }
+
+  // 7. Check array items type change
+  if (prev.items !== undefined && curr.items !== undefined) {
+    const nested = compareSchemas(prev.items, curr.items);
+    if (nested.classification === 'breaking') {
+      return { classification: 'breaking', reason: `array items: ${nested.reason}` };
+    }
+    if (nested.classification === 'non-breaking') {
+      return { classification: 'non-breaking', reason: `array items: ${nested.reason}` };
+    }
+  }
+
+  // 8. Check if a new optional property was added (non-breaking)
+  const newOptionalKeys = Object.keys(currProps).filter((k) => !(k in prevProps) && !currRequired.includes(k));
+  if (newOptionalKeys.length > 0) {
+    return { classification: 'non-breaking', reason: `optional field(s) added: ${newOptionalKeys.join(', ')}` };
+  }
+
+  return { classification: 'no-change', reason: 'schemas are semantically identical' };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function normaliseRequired(required: unknown): string[] {
+  if (!Array.isArray(required)) return [];
+  return required.filter((v): v is string => typeof v === 'string');
+}
+
+function normaliseEnum(enumVal: unknown): string[] | null {
+  if (!Array.isArray(enumVal)) return null;
+  return enumVal.map((v) => String(v));
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+// @specferret/core public API
+// Do not export llm-fallback — dynamic import only, never a default export.
+
+export * from './extractor/frontmatter.js';
+export * from './extractor/typescript.js';
+export * from './extractor/validator.js';
+export * from './extractor/contract-types.js';
+export * from './extractor/hash.js';
+export * from './context/index.js';
+export * from './store/types.js';
+export * from './store/sqlite.js';
+export * from './store/factory.js';
+export * from './reconciler/index.js';
+export * from './reconciler/import-suggestions.js';
+export * from './config.js';
+export * from './utils/paths.js';

package/src/reconciler/import-suggestions.test.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import { describe, it } from "bun:test";
+import { suggestMissingImports } from "./import-suggestions.js";
+import type {
+  FerretContract,
+  FerretDependency,
+  FerretNode,
+} from "../store/types.js";
+
+function makeNode(id: string, filePath: string): FerretNode {
+  return {
+    id,
+    file_path: filePath,
+    hash: id,
+    status: "stable",
+  };
+}
+
+function makeContract(
+  nodeId: string,
+  id: string,
+  shapeSchema: unknown,
+): FerretContract {
+  return {
+    id,
+    node_id: nodeId,
+    shape_hash: id,
+    shape_schema: JSON.stringify(shapeSchema),
+    type: "api",
+    status: "stable",
+  };
+}
+
+describe("suggestMissingImports — S31 acceptance criteria", () => {
+  it("suggests likely missing imports using shape overlap evidence", () => {
+    const nodes: FerretNode[] = [
+      makeNode("node-a", "contracts/a.contract.md"),
+      makeNode("node-b", "contracts/b.contract.md"),
+    ];
+
+    const contracts: FerretContract[] = [
+      makeContract("node-a", "api.GET/a", {
+        type: "object",
+        properties: {
+          token: { type: "string" },
+          userId: { type: "string" },
+        },
+      }),
+      makeContract("node-b", "auth.jwt", {
+        type: "object",
+        properties: {
+          token: { type: "string" },
+          userId: { type: "string" },
+          expiresAt: { type: "string" },
+        },
+      }),
+    ];
+
+    const suggestions = suggestMissingImports(nodes, contracts, []);
+    assert.equal(suggestions.length, 1);
+    assert.equal(suggestions[0].sourceContractId, "api.GET/a");
+    assert.equal(suggestions[0].suggestedImportId, "auth.jwt");
+    assert.match(suggestions[0].evidence, /shared shape keys/);
+  });
+
+  it("does not suggest imports that already exist in dependencies", () => {
+    const nodes: FerretNode[] = [
+      makeNode("node-a", "contracts/a.contract.md"),
+      makeNode("node-b", "contracts/b.contract.md"),
+    ];
+
+    const contracts: FerretContract[] = [
+      makeContract("node-a", "api.GET/a", {
+        type: "object",
+        properties: {
+          token: { type: "string" },
+          userId: { type: "string" },
+        },
+      }),
+      makeContract("node-b", "auth.jwt", {
+        type: "object",
+        properties: {
+          token: { type: "string" },
+          userId: { type: "string" },
+          expiresAt: { type: "string" },
+        },
+      }),
+    ];
+
+    const dependencies: FerretDependency[] = [
+      {
+        id: "dep-a",
+        source_node_id: "node-a",
+        target_contract_id: "auth.jwt",
+      },
+    ];
+
+    const suggestions = suggestMissingImports(nodes, contracts, dependencies);
+    assert.equal(suggestions.length, 0);
+  });
+});