@njeybe/nativ 2.0.0

package/dist/core/test-generator-types.js

@@ -0,0 +1,179 @@
+/**
+ * Contract-to-test generator types (nativ test gen).
+ * Result/request shapes conform to POST /api/tests/generate in .ai/api_contracts.json.
+ * Endpoint suites are built from .ai/api_contracts.json, database integrity suites from .ai/db_schema.json.
+ */
+export const TEST_FRAMEWORKS = ['vitest', 'jest', 'node:test', 'pytest', 'go'];
+export function isTestFramework(value) {
+    return TEST_FRAMEWORKS.includes(value);
+}
+export const DEFAULT_TEST_OUTPUT_DIR = 'tests/contract';
+export const DEFAULT_TEST_FRAMEWORK = 'vitest';
+export const DEFAULT_TEST_BASE_URL = 'http://localhost:3000';
+const PRIMITIVES = {
+    string: 'string',
+    number: 'number',
+    integer: 'integer',
+    int: 'integer',
+    boolean: 'boolean',
+    bool: 'boolean',
+    null: 'null',
+    any: 'any',
+    unknown: 'any',
+};
+/** Splits on `separator` only outside (), {}, [] and quotes. */
+function splitTopLevel(input, separator) {
+    const parts = [];
+    let depth = 0;
+    let quote = null;
+    let start = 0;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"')
+            quote = ch;
+        else if (ch === '(' || ch === '{' || ch === '[')
+            depth++;
+        else if (ch === ')' || ch === '}' || ch === ']')
+            depth--;
+        else if (depth === 0 && input.startsWith(separator, i)) {
+            parts.push(input.slice(start, i));
+            start = i + separator.length;
+            i += separator.length - 1;
+        }
+    }
+    parts.push(input.slice(start));
+    return parts.map((p) => p.trim()).filter((p) => p.length > 0);
+}
+/** Separates "head (note)" when the parenthetical is top-level and trailing. */
+function splitNote(descriptor) {
+    if (!descriptor.endsWith(')'))
+        return { head: descriptor, note: null };
+    let depth = 0;
+    for (let i = descriptor.length - 1; i >= 0; i--) {
+        const ch = descriptor[i];
+        if (ch === ')')
+            depth++;
+        else if (ch === '(') {
+            depth--;
+            if (depth === 0) {
+                const head = descriptor.slice(0, i).trim();
+                return head ? { head, note: descriptor.slice(i + 1, -1).trim() } : { head: descriptor, note: null };
+            }
+        }
+    }
+    return { head: descriptor, note: null };
+}
+const LITERAL_UNION = /^(?:'[^']*'|-?\d+(?:\.\d+)?)(?:\s*\|\s*(?:'[^']*'|-?\d+(?:\.\d+)?))*$/;
+function parseLiteral(token) {
+    const t = token.trim();
+    return t.startsWith("'") ? t.slice(1, -1) : Number(t);
+}
+function parseHead(head) {
+    const variants = splitTopLevel(head, '|');
+    if (variants.length > 1) {
+        return { kind: 'union', variants: variants.map((v) => parseHead(v)) };
+    }
+    const h = head.trim();
+    const arrayMatch = /^array of\s+(.+)$/i.exec(h);
+    if (arrayMatch)
+        return { kind: 'array', items: parseHead(arrayMatch[1]) };
+    if (h.endsWith('[]'))
+        return { kind: 'array', items: parseHead(h.slice(0, -2)) };
+    if (h.startsWith('{') && h.endsWith('}'))
+        return parseInlineObject(h.slice(1, -1));
+    if (/^object$/i.test(h))
+        return { kind: 'object', properties: {}, open: true };
+    if (LITERAL_UNION.test(h)) {
+        const value = parseLiteral(h);
+        return { kind: 'enum', base: typeof value === 'number' ? 'number' : 'string', values: [value] };
+    }
+    const primitive = PRIMITIVES[h.toLowerCase()];
+    if (primitive)
+        return { kind: 'primitive', type: primitive };
+    if (/^[A-Z][A-Za-z0-9_]*$/.test(h))
+        return { kind: 'ref', name: h };
+    return { kind: 'primitive', type: 'any', note: h };
+}
+/** Parses "key: type, key2: 'a' | 'b'" (the inside of an inline `{ ... }` descriptor). */
+function parseInlineObject(body) {
+    const properties = {};
+    for (const entry of splitTopLevel(body, ',')) {
+        const colon = entry.indexOf(':');
+        if (colon === -1)
+            continue;
+        let key = entry.slice(0, colon).trim();
+        const optional = key.endsWith('?');
+        if (optional)
+            key = key.slice(0, -1).trim();
+        const node = parseFieldDescriptor(entry.slice(colon + 1).trim());
+        properties[key] = optional ? { ...node, optional: true } : node;
+    }
+    return { kind: 'object', properties, open: false };
+}
+/** Collapses "T | null" style unions of literals into one enum node. */
+function mergeLiteralUnion(node) {
+    if (node.kind !== 'union' || !node.variants.every((v) => v.kind === 'enum'))
+        return node;
+    const values = node.variants.flatMap((v) => v.values);
+    const base = values.every((v) => typeof v === 'number') ? 'number' : 'string';
+    return { kind: 'enum', base, values };
+}
+/**
+ * Parses a contract descriptor string into a SchemaNode.
+ * Examples: "boolean", "string | null", "integer (optional, default 25, max 100)",
+ * "string ('dev' | 'prod')", "boolean (required if env === 'prod')", "array of TableSchema",
+ * "array of { key: string, targetEnv: 'dev' | 'prod' }".
+ */
+export function parseFieldDescriptor(descriptor) {
+    const { head, note } = splitNote(descriptor.trim());
+    let node = mergeLiteralUnion(parseHead(head));
+    if (note === null)
+        return node;
+    const extras = {};
+    let rest = note;
+    const requiredIf = /^required if\s+(.+)$/i.exec(rest);
+    if (requiredIf) {
+        extras.optional = true;
+        extras.requiredIf = requiredIf[1].trim();
+        rest = '';
+    }
+    else if (/^optional\b/i.test(rest)) {
+        extras.optional = true;
+        rest = rest.replace(/^optional\b\s*[:,]?\s*/i, '');
+    }
+    // "string ('dev' | 'prod')" or "string (optional: 'asc' | 'desc')" narrows to an enum.
+    if (rest && LITERAL_UNION.test(rest) && (node.kind === 'primitive' || node.kind === 'enum')) {
+        const values = splitTopLevel(rest, '|').map(parseLiteral);
+        const base = values.every((v) => typeof v === 'number') ? 'number' : 'string';
+        node = { kind: 'enum', base, values };
+        rest = '';
+    }
+    if (rest)
+        extras.note = node.note ? `${node.note}; ${rest}` : rest;
+    return { ...node, ...extras };
+}
+/** Builds a SchemaNode from a contract body value (nested objects, descriptor strings, or null). */
+export function buildSchemaNode(value) {
+    if (value === null || value === undefined)
+        return { kind: 'primitive', type: 'null' };
+    if (typeof value === 'string')
+        return parseFieldDescriptor(value);
+    const properties = {};
+    for (const [key, child] of Object.entries(value)) {
+        properties[key] = buildSchemaNode(child);
+    }
+    return { kind: 'object', properties, open: false };
+}
+/** True when a schema node accepts null (nullable union or explicit null). */
+export function isNullableNode(node) {
+    if (node.kind === 'primitive')
+        return node.type === 'null' || node.type === 'any';
+    if (node.kind === 'union')
+        return node.variants.some(isNullableNode);
+    return false;
+}

package/dist/core/test-generator.d.ts

@@ -0,0 +1,34 @@
+import { type DatabaseEngine, type TableSchema } from '../db/types.js';
+import { type ApiContractsDocument, type ApiEndpointContract, type DbSchemaDocument, type ResolvedTestGenOptions, type SchemaNode, type TestFramework, type TestFrameworkAdapter, type TestGenOptions, type TestGenResult, type TestSuiteSpec } from './test-generator-types.js';
+/**
+ * Contract-to-test generator (nativ test gen).
+ *
+ * Contracts are compiled into framework-agnostic TestSuiteSpecs, then rendered by a
+ * TestFrameworkAdapter. Generated endpoint tests never send a well-formed request to a
+ * mutating endpoint: POST/PUT/PATCH/DELETE are only exercised with invalid or anonymous
+ * requests, so running the suite cannot write data or trigger side effects.
+ */
+/** Present in the header of every generated file; files without it are never overwritten. */
+export declare const GENERATED_MARKER = "Code generated by nativ test gen";
+export declare class TestGenError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function resolveTestGenOptions(options: TestGenOptions): ResolvedTestGenOptions;
+export declare function loadApiContracts(targetDir: string): ApiContractsDocument | null;
+/** .ai/db_schema.json with tables normalized the same way `nativ db diff --target contract` reads them. */
+export declare function loadDbSchemaContract(targetDir: string): DbSchemaDocument | null;
+/** Same semantics as the generated shapeErrors helpers: true when `value` conforms to `node`. */
+export declare function matchesSchema(value: unknown, node: SchemaNode): boolean;
+export declare function buildEndpointSuite(endpoint: ApiEndpointContract): TestSuiteSpec;
+export declare function buildEndpointSuites(doc: ApiContractsDocument): TestSuiteSpec[];
+/**
+ * Integrity checks for one contract table: existence, columns, primary key, nullability and
+ * unique constraints. Collections only get required-field checks, because sampled document
+ * stores report a field as nullable whenever some sampled document lacks it.
+ */
+export declare function buildTableSuite(table: TableSchema, engine: DatabaseEngine | null): TestSuiteSpec;
+export declare function buildDbSuites(doc: DbSchemaDocument): TestSuiteSpec[];
+export declare const TEST_FRAMEWORK_ADAPTERS: Record<TestFramework, TestFrameworkAdapter>;
+/** Compiles .ai contracts into test files for the chosen framework (written unless dryRun). */
+export declare function generateContractTests(options: TestGenOptions): TestGenResult;