@specverse/engines 6.21.4 → 6.27.10

package/dist/audit/verify-checks.js

@@ -0,0 +1,202 @@
+/**
+ * Structural-check library for the verify stage. Each check is a
+ * (parsedSpec) -> StructuralCheckResult function. Checks are SpecVerse-
+ * semantic invariants that go beyond schema validation: things that
+ * are syntactically valid YAML matching the JSON schema, but
+ * semantically odd (e.g. an action with no steps and no cured shorthand).
+ *
+ * Design: each check is pure, fast, and reads only the parsed spec.
+ * No filesystem I/O, no LLM calls.
+ *
+ * Adding a new check:
+ *   1. Define the check function below
+ *   2. Add it to ALL_CHECKS at the bottom
+ *   3. Add a unit test in __tests__/verify-checks.test.ts
+ */
+function* iterateActions(spec) {
+    const components = spec.components || {};
+    for (const [componentName, comp] of Object.entries(components)) {
+        for (const ownerKind of ['controllers', 'services']) {
+            const owners = comp[ownerKind] || {};
+            for (const [ownerName, owner] of Object.entries(owners)) {
+                const actions = owner.actions || {};
+                for (const [actionName, action] of Object.entries(actions)) {
+                    yield {
+                        componentName,
+                        ownerName,
+                        ownerKind: ownerKind === 'controllers' ? 'controller' : 'service',
+                        actionName,
+                        action,
+                        path: `components.${componentName}.${ownerKind}.${ownerName}.actions.${actionName}`,
+                    };
+                }
+            }
+        }
+    }
+}
+function* iterateModels(spec) {
+    const components = spec.components || {};
+    for (const [componentName, comp] of Object.entries(components)) {
+        const models = comp.models || {};
+        for (const [modelName, model] of Object.entries(models)) {
+            yield {
+                componentName,
+                modelName,
+                model,
+                path: `components.${componentName}.models.${modelName}`,
+            };
+        }
+    }
+}
+/** Each action either declares step bullets or is shorthand-mapped via cured. */
+export function checkActionsHaveStepsOrCured(spec) {
+    const violations = [];
+    for (const { action, path } of iterateActions(spec)) {
+        const hasSteps = Array.isArray(action.steps) && action.steps.length > 0;
+        const hasCured = action.cured && typeof action.cured === 'object';
+        const hasInline = typeof action.implementation === 'string' || action.body;
+        if (!hasSteps && !hasCured && !hasInline) {
+            violations.push({ path, issue: 'action declares no steps, cured shorthand, or inline body' });
+        }
+    }
+    return {
+        name: 'every-action-has-steps-or-cured',
+        description: 'Each action declares either an explicit steps list or a cured shorthand or an inline body.',
+        ok: violations.length === 0,
+        violations,
+    };
+}
+/** Every model has at least one attribute marked as primary key (id, isPrimary, or auto). */
+export function checkModelsHavePrimaryKey(spec) {
+    const violations = [];
+    for (const { model, path, modelName } of iterateModels(spec)) {
+        const attrs = model.attributes || {};
+        let hasPk = false;
+        for (const [attrName, attrSpec] of Object.entries(attrs)) {
+            // Primary if name is 'id' OR attrSpec contains 'isPrimary' OR 'auto=' modifier.
+            const text = typeof attrSpec === 'string' ? attrSpec : (attrSpec?.modifiers?.join?.(' ') ?? '');
+            if (attrName === 'id') {
+                hasPk = true;
+                break;
+            }
+            if (/\bisPrimary\b/.test(text)) {
+                hasPk = true;
+                break;
+            }
+            if (/\bauto\s*=\s*(uuid|nanoid|cuid|increment)/.test(text)) {
+                hasPk = true;
+                break;
+            }
+        }
+        // Composite-key shape (`keys: [a, b]` on the model itself).
+        if (!hasPk && Array.isArray(model.keys) && model.keys.length > 0)
+            hasPk = true;
+        if (!hasPk) {
+            violations.push({ path, issue: `model ${modelName} has no detectable primary key` });
+        }
+    }
+    return {
+        name: 'every-model-has-primary-key',
+        description: 'Every model declares a primary key (id attribute, isPrimary modifier, auto-id, or composite keys).',
+        ok: violations.length === 0,
+        violations,
+    };
+}
+/** Every emit references a declared event. */
+export function checkEmitsReferenceDeclaredEvents(spec) {
+    const violations = [];
+    // Build the set of declared event names from `events:` blocks across components.
+    const declaredEvents = new Set();
+    const components = spec.components || {};
+    for (const comp of Object.values(components)) {
+        const events = comp.events || {};
+        for (const eventName of Object.keys(events))
+            declaredEvents.add(eventName);
+    }
+    // Top-level events: block too (some specs declare globally).
+    for (const eventName of Object.keys(spec.events || {}))
+        declaredEvents.add(eventName);
+    for (const { action, path } of iterateActions(spec)) {
+        const emits = action.emits || action.publishes || [];
+        if (!Array.isArray(emits))
+            continue;
+        for (const emit of emits) {
+            const eventName = typeof emit === 'string' ? emit : emit?.event ?? emit?.name;
+            if (!eventName)
+                continue;
+            // Strip any qualifier prefix (e.g. 'on.UserCreated' -> 'UserCreated').
+            const cleanName = eventName.replace(/^[a-z]+\./, '');
+            if (!declaredEvents.has(cleanName)) {
+                violations.push({
+                    path: `${path}.emits`,
+                    issue: `event '${cleanName}' is emitted but not declared in any events: block`,
+                });
+            }
+        }
+    }
+    return {
+        name: 'every-emit-references-declared-event',
+        description: 'Every action that emits an event references a declared event in events: blocks.',
+        ok: violations.length === 0,
+        violations,
+    };
+}
+/** No two model declarations with the same name across components (collision risk at realize). */
+export function checkNoDuplicateModelNames(spec) {
+    const violations = [];
+    const seen = new Map();
+    for (const { componentName, modelName, path } of iterateModels(spec)) {
+        if (!seen.has(modelName))
+            seen.set(modelName, []);
+        seen.get(modelName).push(componentName);
+    }
+    for (const [modelName, components] of seen.entries()) {
+        if (components.length > 1) {
+            violations.push({
+                path: `models.${modelName}`,
+                issue: `model '${modelName}' declared in multiple components: ${components.join(', ')}`,
+            });
+        }
+    }
+    return {
+        name: 'no-duplicate-model-names',
+        description: 'No model name is declared in more than one component.',
+        ok: violations.length === 0,
+        violations,
+    };
+}
+/** Every action has at least one step bullet OR explicit cured shorthand. Also checks step bullets are non-empty strings. */
+export function checkStepBulletsWellFormed(spec) {
+    const violations = [];
+    for (const { action, path } of iterateActions(spec)) {
+        const steps = Array.isArray(action.steps) ? action.steps : [];
+        for (let i = 0; i < steps.length; i++) {
+            const s = steps[i];
+            const text = typeof s === 'string' ? s : s?.step;
+            if (typeof text !== 'string' || text.trim() === '') {
+                violations.push({ path: `${path}.steps[${i}]`, issue: 'step bullet is empty or non-string' });
+            }
+            else if (text.length > 250) {
+                violations.push({ path: `${path}.steps[${i}]`, issue: `step bullet is unusually long (${text.length} chars) — likely should be split into multiple steps` });
+            }
+        }
+    }
+    return {
+        name: 'step-bullets-well-formed',
+        description: 'Each step bullet is a non-empty string of reasonable length (<250 chars).',
+        ok: violations.length === 0,
+        violations,
+    };
+}
+export const ALL_CHECKS = [
+    checkActionsHaveStepsOrCured,
+    checkModelsHavePrimaryKey,
+    checkEmitsReferenceDeclaredEvents,
+    checkNoDuplicateModelNames,
+    checkStepBulletsWellFormed,
+];
+/** Run every check against the parsed spec and return all results. */
+export function runAllChecks(spec) {
+    return ALL_CHECKS.map((check) => check(spec));
+}
+//# sourceMappingURL=verify-checks.js.map

package/dist/audit/verify-checks.js.map

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

package/dist/audit/verify-recorder.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Verify-phase audit recorder. Captures schema-validation passes,
+ * structural-check results, and retry events at the moments they happen
+ * during analyse-runner execution.
+ *
+ * Forward-logging discipline (engines 6.22.x+): validation results are
+ * recorded by the runValidate wrapper at the moment of validation;
+ * structural-check results are recorded by the check pass after each
+ * successful schema validation; retry events are recorded by the retry
+ * loop when it triggers. No backward inference.
+ *
+ * Sidecars produced (by analyse-runner at end of run):
+ *   - verify/invariants.json: each check + result + items requiring review
+ *   - verify/retries.json: retry events with error categories and deltas
+ */
+export interface ValidationPass {
+    /** Sequence ordinal across validate calls in this run. */
+    ordinal: number;
+    /** What kind of validation. schema-validation = spv-validate; infer = spv infer; structural = invariant library. */
+    kind: 'schema-validation' | 'infer' | 'structural';
+    ok: boolean;
+    errorCount: number;
+    errors: string[];
+    /** Optional: timing in ms. */
+    durationMs?: number;
+}
+export interface StructuralCheckResult {
+    name: string;
+    description: string;
+    ok: boolean;
+    violations: Array<{
+        path: string;
+        issue: string;
+    }>;
+}
+export interface HumanReviewItem {
+    severity: 'error' | 'warning' | 'info';
+    kind: string;
+    path?: string;
+    message: string;
+}
+export interface RetryEvent {
+    ordinal: number;
+    trigger: string;
+    errorCount: number;
+    errorCategories: Record<string, number>;
+    tokenCountIn?: number;
+    tokenCountOut?: number;
+    latencyMs?: number;
+    /** A short summary of the diff between before/after. Full diff lives in
+     *  the retry's prompt + draft files, not in this sidecar. */
+    itemsChangedSummary?: string;
+    ok: boolean;
+}
+export interface VerifyInvariantsDocument {
+    schemaVersion: '1.0';
+    stage: 'verify';
+    passes: ValidationPass[];
+    structuralChecks: StructuralCheckResult[];
+    humanReviewItems: HumanReviewItem[];
+}
+export interface VerifyRetriesDocument {
+    schemaVersion: '1.0';
+    stage: 'verify';
+    retries: RetryEvent[];
+}
+export declare class InMemoryVerifyRecorder {
+    private passes;
+    private structuralChecks;
+    private humanReviewItems;
+    private retries;
+    private nextPassOrdinal;
+    private nextRetryOrdinal;
+    recordPass(args: Omit<ValidationPass, 'ordinal'>): ValidationPass;
+    recordStructuralCheck(check: StructuralCheckResult): void;
+    recordHumanReviewItem(item: HumanReviewItem): void;
+    recordRetry(args: Omit<RetryEvent, 'ordinal'>): RetryEvent;
+    buildInvariants(): VerifyInvariantsDocument;
+    buildRetries(): VerifyRetriesDocument;
+}
+/** Categorise a validation error string by pattern match. Used for
+ *  retry-event analytics. */
+export declare function categoriseValidationError(errorText: string): Record<string, number>;
+//# sourceMappingURL=verify-recorder.d.ts.map

package/dist/audit/verify-recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-recorder.d.ts","sourceRoot":"","sources":["../../src/audit/verify-recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,oHAAoH;IACpH,IAAI,EAAE,mBAAmB,GAAG,OAAO,GAAG,YAAY,CAAC;IACnD,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;iEAC6D;IAC7D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,KAAK,CAAC;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,gBAAgB,EAAE,qBAAqB,EAAE,CAAC;IAC1C,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,KAAK,CAAC;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,gBAAgB,CAAyB;IACjD,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,gBAAgB,CAAK;IAE7B,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG,cAAc;IAMjE,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI;IAazD,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;IAIlD,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,GAAG,UAAU;IAM1D,eAAe,IAAI,wBAAwB;IAU3C,YAAY,IAAI,qBAAqB;CAOtC;AAED;6BAC6B;AAC7B,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAenF"}

package/dist/audit/verify-recorder.js

@@ -0,0 +1,90 @@
+/**
+ * Verify-phase audit recorder. Captures schema-validation passes,
+ * structural-check results, and retry events at the moments they happen
+ * during analyse-runner execution.
+ *
+ * Forward-logging discipline (engines 6.22.x+): validation results are
+ * recorded by the runValidate wrapper at the moment of validation;
+ * structural-check results are recorded by the check pass after each
+ * successful schema validation; retry events are recorded by the retry
+ * loop when it triggers. No backward inference.
+ *
+ * Sidecars produced (by analyse-runner at end of run):
+ *   - verify/invariants.json: each check + result + items requiring review
+ *   - verify/retries.json: retry events with error categories and deltas
+ */
+export class InMemoryVerifyRecorder {
+    passes = [];
+    structuralChecks = [];
+    humanReviewItems = [];
+    retries = [];
+    nextPassOrdinal = 1;
+    nextRetryOrdinal = 1;
+    recordPass(args) {
+        const pass = { ordinal: this.nextPassOrdinal++, ...args };
+        this.passes.push(pass);
+        return pass;
+    }
+    recordStructuralCheck(check) {
+        this.structuralChecks.push(check);
+        // Promote violations to human-review items for visibility.
+        for (const v of check.violations) {
+            this.humanReviewItems.push({
+                severity: check.ok ? 'info' : 'warning',
+                kind: check.name,
+                path: v.path,
+                message: v.issue,
+            });
+        }
+    }
+    recordHumanReviewItem(item) {
+        this.humanReviewItems.push(item);
+    }
+    recordRetry(args) {
+        const r = { ordinal: this.nextRetryOrdinal++, ...args };
+        this.retries.push(r);
+        return r;
+    }
+    buildInvariants() {
+        return {
+            schemaVersion: '1.0',
+            stage: 'verify',
+            passes: this.passes,
+            structuralChecks: this.structuralChecks,
+            humanReviewItems: this.humanReviewItems,
+        };
+    }
+    buildRetries() {
+        return {
+            schemaVersion: '1.0',
+            stage: 'verify',
+            retries: this.retries,
+        };
+    }
+}
+/** Categorise a validation error string by pattern match. Used for
+ *  retry-event analytics. */
+export function categoriseValidationError(errorText) {
+    const categories = {};
+    const lines = errorText.split('\n').filter((l) => l.trim());
+    for (const line of lines) {
+        let cat = 'other';
+        if (/Unknown property/i.test(line))
+            cat = 'unknown-property';
+        else if (/must have required property/i.test(line))
+            cat = 'missing-required';
+        else if (/must be string|must be number|must be boolean/i.test(line))
+            cat = 'wrong-type';
+        else if (/must match pattern/i.test(line))
+            cat = 'pattern-mismatch';
+        else if (/must match a schema in anyOf|must match exactly one schema in oneOf/i.test(line))
+            cat = 'schema-shape-mismatch';
+        else if (/must be equal to one of/i.test(line))
+            cat = 'enum-violation';
+        else if (/realize:|name collision/i.test(line))
+            cat = 'realize-collision';
+        categories[cat] = (categories[cat] ?? 0) + 1;
+    }
+    return categories;
+}
+//# sourceMappingURL=verify-recorder.js.map

package/dist/audit/verify-recorder.js.map

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

package/dist/inference/core/specly-converter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specly-converter.d.ts","sourceRoot":"","sources":["../../../src/inference/core/specly-converter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAiClD,qBAAa,eAAe;IAE1B;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM;IA2G3E;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAkB7B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAuBjC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAuBpC,OAAO,CAAC,MAAM,CAAC,YAAY;IAsK3B,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAgChC,OAAO,CAAC,MAAM,CAAC,aAAa;IAsF5B,OAAO,CAAC,MAAM,CAAC,cAAc;IA4B7B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAwC/B,OAAO,CAAC,MAAM,CAAC,YAAY;IAoB3B,OAAO,CAAC,MAAM,CAAC,WAAW;IAmL1B,OAAO,CAAC,MAAM,CAAC,WAAW;IAyB1B,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAkBjC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAgB9B,OAAO,CAAC,MAAM,CAAC,cAAc;IAgD7B,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAkBlC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAyCpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;CAiC/B"}
+{"version":3,"file":"specly-converter.d.ts","sourceRoot":"","sources":["../../../src/inference/core/specly-converter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAmDlD,qBAAa,eAAe;IAE1B;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM;IA2G3E;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAkB7B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAuBjC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAuBpC,OAAO,CAAC,MAAM,CAAC,YAAY;IAyK3B,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAgChC,OAAO,CAAC,MAAM,CAAC,aAAa;IAyF5B,OAAO,CAAC,MAAM,CAAC,cAAc;IA4B7B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAwC/B,OAAO,CAAC,MAAM,CAAC,YAAY;IAoB3B,OAAO,CAAC,MAAM,CAAC,WAAW;IAmL1B,OAAO,CAAC,MAAM,CAAC,WAAW;IAgC1B,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAkBjC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAgB9B,OAAO,CAAC,MAAM,CAAC,cAAc;IAgD7B,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAkBlC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAyCpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;CAiC/B"}