@lyku/lockstep-core 1.4.0 → 1.5.1

package/versionCheck.js

@@ -0,0 +1,137 @@
+/* eslint-disable security/detect-object-injection -- keys come from Object.keys of the same object; no external-input indexing */
+// Pure core of the schema-version biconditional check (SCHEMA-VERSIONING.md).
+//
+// Asserts, per versioned model: schema-bytes-changed ⟺ version-changed — in
+// BOTH directions. A change without a bump ships a stale reconcile key; a bump
+// without a change ("phantom bump") needlessly invalidates every client's
+// replicas of that model. Doc-metadata edits must NOT count as schema changes
+// (or they'd trigger false bumps and refetch storms).
+//
+// This module is pure and deterministic — no git, no fs, no process. The bin
+// (version-check.ts) is a thin shell that loads the two model maps (current
+// working tree + a base git ref) and feeds them here. All the correctness lives
+// here so it can be unit-tested without git.
+import { stringifyBON } from './tson/stringifyBON';
+import { createHash } from 'node:crypto';
+/**
+ * Keys excluded from the structure hash:
+ *  - documentation metadata (title/description/examples/notes/docs) — editing a
+ *    doc string must not look like a schema change.
+ *  - `version` itself — it is compared separately; including it would make every
+ *    bump also register as a structure change, defeating the biconditional.
+ * `default` is deliberately NOT excluded: a column default is a real DDL/schema
+ * change that should require a bump.
+ */
+export const HASH_EXCLUDED_KEYS = new Set([
+    'version',
+    'title',
+    'description',
+    'examples',
+    'notes',
+    'docs',
+]);
+/**
+ * Canonical form: recursively drop excluded keys and sort object keys. Array
+ * ORDER is preserved (arrays are treated as ordered — reordering `required` or
+ * `enum` is conservatively treated as a change rather than risk equating
+ * genuinely-ordered arrays).
+ */
+export function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value !== null && typeof value === 'object') {
+        const src = value;
+        const out = {};
+        for (const key of Object.keys(src).sort()) {
+            if (HASH_EXCLUDED_KEYS.has(key))
+                continue;
+            out[key] = canonicalize(src[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/** Deterministic structure hash of a model (docs + version excluded). */
+export function structureHash(model) {
+    return createHash('sha256')
+        .update(stringifyBON(canonicalize(model)))
+        .digest('hex');
+}
+/** The model's authored version string, or undefined if it has none. */
+export function modelVersion(model) {
+    if (model !== null && typeof model === 'object' && 'version' in model) {
+        const v = model.version;
+        return typeof v === 'string' ? v : undefined;
+    }
+    return undefined;
+}
+/** A model-like value: an object carrying a `properties` map (record model). */
+export function isModelLike(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        'properties' in value);
+}
+/**
+ * Decide one model present in BOTH base and current. The biconditional is
+ * enforced only once a model is versioned on BOTH sides — first-time adoption
+ * (no base version → current version) and not-yet-adopted models are exempt, so
+ * the check doesn't fire on the rollout itself.
+ */
+export function decideExisting(name, base, current) {
+    const baseV = modelVersion(base);
+    const curV = modelVersion(current);
+    // Not policed unless versioned on both sides (adoption/un-adoption exempt).
+    if (baseV === undefined || curV === undefined)
+        return null;
+    const structureChanged = structureHash(base) !== structureHash(current);
+    const versionChanged = baseV !== curV;
+    if (structureChanged && !versionChanged)
+        return {
+            model: name,
+            kind: 'changed-not-bumped',
+            detail: `schema changed but version is still ${JSON.stringify(curV)} — bump it (minor for a compatible addition, major for a breaking change)`,
+        };
+    if (!structureChanged && versionChanged)
+        return {
+            model: name,
+            kind: 'bumped-not-changed',
+            detail: `version changed ${JSON.stringify(baseV)} → ${JSON.stringify(curV)} but the schema is byte-identical — a phantom bump needlessly invalidates every client's replicas of "${name}"`,
+        };
+    return null;
+}
+/**
+ * Run the biconditional over two model maps (name → model definition). Only
+ * model-like entries are considered (exported helpers/constants are ignored).
+ *
+ * @param opts.requireVersionOnNew  flag a newly-added model that has no version.
+ */
+export function checkModels(base, current, opts = {}) {
+    const violations = [];
+    const added = [];
+    const removed = [];
+    let checked = 0;
+    for (const name of Object.keys(current)) {
+        if (!isModelLike(current[name]))
+            continue;
+        if (!(name in base) || !isModelLike(base[name])) {
+            added.push(name);
+            if (opts.requireVersionOnNew && modelVersion(current[name]) === undefined)
+                violations.push({
+                    model: name,
+                    kind: 'missing-version-on-new',
+                    detail: `new model "${name}" has no version — declare one (e.g. "1.0")`,
+                });
+            continue;
+        }
+        checked++;
+        const v = decideExisting(name, base[name], current[name]);
+        if (v)
+            violations.push(v);
+    }
+    for (const name of Object.keys(base)) {
+        if (isModelLike(base[name]) && !(name in current))
+            removed.push(name);
+    }
+    return { violations, checked, added, removed };
+}
+//# sourceMappingURL=versionCheck.js.map

package/versionCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versionCheck.js","sourceRoot":"","sources":["../../../libs/lockstep-core/versionCheck.ts"],"names":[],"mappings":"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"}