@reprova/sdk 0.4.0 → 0.6.0

package/dist/cjs/invariantRules.js

@@ -0,0 +1,142 @@
+"use strict";
+// Dashboard-authored business-invariant rules: CEL (Common Expression
+// Language) expressions evaluated in-process against real Prisma query
+// results (not just the footprint's PKs/counts — actual field values), so
+// bugs that never throw and never return a 5xx (an invoice total that
+// silently drifted from its line items, negative inventory, an order marked
+// shipped with no shipment row) can still produce a reproduction.
+//
+// Replaces an earlier JSON condition-tree evaluator (see git history) — CEL
+// gives the same same-row-comparison-and-relation-aggregate expressiveness
+// with a much friendlier authoring surface (`total ==
+// lineItems.map(x, x.total).sum()` instead of a nested op/field/right tree),
+// using the actively-maintained, zero-dependency @marcbachmann/cel-js.
+//
+// `expr` is the INVARIANT itself — what should always be true — not the
+// violation condition: a rule fires when `expr` evaluates to exactly
+// `false`. This is the opposite polarity from the old JSON tree (which
+// encoded the violation, e.g. `not: eq(...)`), but reads naturally in CEL
+// and matches how an admin would actually describe the rule out loud.
+//
+// A field or relation the app's own query didn't `include` simply isn't a
+// key on the row object, which CEL reports as a runtime "no such attribute"
+// error rather than `false` — evaluateInvariant treats any evaluation error,
+// and any non-boolean result (an author mistake, e.g. forgetting a
+// comparison operator), as "can't evaluate" and skips, never firing a false
+// violation on data the query simply didn't load. Same principle
+// `invariantInference.ts`/`distributionDrift.ts` use: never guess.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BusinessInvariantViolation = void 0;
+exports.operationMatchesHook = operationMatchesHook;
+exports.compileInvariant = compileInvariant;
+exports.evaluateInvariant = evaluateInvariant;
+let envPromise = null;
+function loadEnv() {
+    if (!envPromise) {
+        envPromise = Promise.resolve().then(() => __importStar(require('@marcbachmann/cel-js'))).then(({ Environment }) => new Environment({ unlistedVariablesAreDyn: true }).registerFunction({
+            name: 'sum',
+            receiverType: 'list',
+            returnType: 'double',
+            handler: (list) => list.reduce((a, b) => a + b, 0),
+            params: [],
+        }))
+            .catch(() => null); // can't load the CEL engine at all — every rule silently never fires, never crashes the host app
+    }
+    return envPromise;
+}
+const READ_OPS = new Set(['findUnique', 'findUniqueOrThrow', 'findFirst', 'findFirstOrThrow', 'findMany']);
+const WRITE_OPS = new Set(['create', 'createMany', 'update', 'updateMany', 'upsert', 'delete', 'deleteMany']);
+// Whether a Prisma operation name belongs to the read/write class a rule's
+// when_hook asks to run on. Anything neither (e.g. $queryRaw, aggregate,
+// count, groupBy) never matches — a rule needs real field values on a real
+// row, which those don't uniformly provide.
+function operationMatchesHook(op, whenHook) {
+    return whenHook === 'after_read' ? READ_OPS.has(op) : WRITE_OPS.has(op);
+}
+// Compiled programs are cached by (rule id, expr) so an edited rule
+// recompiles (new expr under the same id misses the cache) while an
+// unchanged one is parsed exactly once for the life of the process — CEL
+// parsing is not free, and this runs on every matching query result.
+// Invalid CEL syntax caches a `null` miss rather than re-attempting the
+// same broken parse on every request. A CEL-engine load failure (see
+// loadEnv's own doc comment) is deliberately NOT cached here — that's a
+// process-wide condition already memoized by envPromise itself, not a
+// per-rule outcome, so a later rule with valid syntax isn't punished by an
+// earlier one's transient load timing.
+const compileCache = new Map();
+async function compileInvariant(rule) {
+    const key = `${rule.id}\x00${rule.expr}`;
+    if (compileCache.has(key))
+        return compileCache.get(key);
+    const env = await loadEnv();
+    if (!env)
+        return null;
+    let compiled;
+    try {
+        compiled = env.parse(rule.expr);
+    }
+    catch {
+        compiled = null; // invalid CEL — never crash the host app on a bad admin-authored rule
+    }
+    compileCache.set(key, compiled);
+    return compiled;
+}
+// Runs a compiled invariant against one row. Returns `false` only for a
+// genuine, cleanly-evaluated violation; `undefined` for anything else
+// (evaluation error from a missing field/relation, or a non-boolean result
+// from a malformed expression) so the caller never mistakes "couldn't tell"
+// for "violated".
+function evaluateInvariant(compiled, row) {
+    let result;
+    try {
+        result = compiled(row);
+    }
+    catch {
+        return undefined;
+    }
+    return typeof result === 'boolean' ? result : undefined;
+}
+// One reusable Error class for every rule violation. Per-rule identity comes
+// from capture()'s extra.errorType override (see sdk.ts), not from a
+// per-rule subclass — many rules can share this class without collapsing
+// into one issue, since fingerprinting keys off errorType, not the class
+// name, once errorType is supplied explicitly.
+class BusinessInvariantViolation extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+exports.BusinessInvariantViolation = BusinessInvariantViolation;

package/dist/cjs/knex.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installKnexHooks = installKnexHooks;
+const context_js_1 = require("./context.js");
+const OP_BY_METHOD = {
+    select: 'select',
+    first: 'select',
+    pluck: 'select',
+    insert: 'insert',
+    update: 'update',
+    del: 'delete',
+    delete: 'delete',
+};
+function isRowArray(v) {
+    return Array.isArray(v) && v.length > 0 && typeof v[0] === 'object' && v[0] !== null;
+}
+function distinct(values) {
+    const seen = new Set();
+    const out = [];
+    for (const v of values) {
+        if (!seen.has(v)) {
+            seen.add(v);
+            out.push(v);
+        }
+    }
+    return out;
+}
+function extractRowPks(rows, pkCols) {
+    if (pkCols.length === 0)
+        return [];
+    const out = [];
+    for (const row of rows) {
+        const vals = pkCols.map((c) => row[c]);
+        if (vals.some((v) => v === undefined || v === null))
+            continue;
+        out.push(vals.map((v) => String(v)).join(':'));
+    }
+    return distinct(out);
+}
+// Installs a footprint listener on a Knex instance. Also covers Objection.js
+// models bound to this same instance.
+function installKnexHooks(knex, opts = {}) {
+    const primaryKey = opts.primaryKey ?? (() => ['id']);
+    try {
+        knex.on('query-response', (response, obj, builder) => {
+            try {
+                const ctx = context_js_1.contextStorage.getStore();
+                if (!ctx)
+                    return;
+                const method = obj?.method ?? builder?._method;
+                const op = method ? OP_BY_METHOD[method] : undefined;
+                if (!op)
+                    return; // schema/DDL/raw — skip
+                const table = builder?._single?.table;
+                if (typeof table !== 'string' || !table)
+                    return;
+                let pks = [];
+                let count = 0;
+                if (isRowArray(response)) {
+                    pks = extractRowPks(response, primaryKey(table));
+                    count = response.length;
+                }
+                else if (Array.isArray(response)) {
+                    // Primitive array — insert returning ids (partial on sqlite/mysql).
+                    if (op === 'insert')
+                        pks = distinct(response.filter((v) => v != null).map((v) => String(v)));
+                    count = response.length;
+                }
+                else if (typeof response === 'number') {
+                    count = response; // affected-row count from update/delete
+                }
+                const entry = {
+                    model: table,
+                    op,
+                    pks,
+                    count,
+                    note: count === 0 ? 'returned 0 rows' : undefined,
+                    resolved: true,
+                };
+                ctx.footprint.push(entry);
+            }
+            catch { /* never break the query pipeline */ }
+        });
+    }
+    catch { /* never throw from install */ }
+}

package/dist/cjs/kysely.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKyselyPlugin = createKyselyPlugin;
+const context_js_1 = require("./context.js");
+const OP_BY_KIND = {
+    SelectQueryNode: 'select',
+    InsertQueryNode: 'insert',
+    UpdateQueryNode: 'update',
+    DeleteQueryNode: 'delete',
+    MergeQueryNode: 'merge',
+};
+// TableNode → its identifier name; unwraps an AliasNode (`from('t as x')`).
+function tableName(node) {
+    const n = node;
+    if (!n || typeof n !== 'object')
+        return undefined;
+    if (n.kind === 'AliasNode')
+        return tableName(n.node);
+    if (n.kind === 'TableNode') {
+        const table = n.table;
+        return table?.identifier?.name;
+    }
+    return undefined;
+}
+// The operation's principal table, read from the op-specific field.
+function primaryTable(node) {
+    switch (node.kind) {
+        case 'SelectQueryNode':
+        case 'DeleteQueryNode': {
+            const from = node.from;
+            return tableName(from?.froms?.[0]);
+        }
+        case 'InsertQueryNode':
+            return tableName(node.into);
+        case 'UpdateQueryNode':
+            return tableName(node.table);
+        default:
+            return undefined;
+    }
+}
+// Every table referenced anywhere in the query (joins, subqueries, CTEs, …),
+// in first-seen order. A bounded deep-walk — instrumentation must not blow the
+// stack or hang on a pathological tree.
+function collectTables(root) {
+    const found = [];
+    const seen = new Set();
+    const stack = [root];
+    let budget = 5000;
+    while (stack.length && budget-- > 0) {
+        const cur = stack.pop();
+        if (!cur || typeof cur !== 'object')
+            continue;
+        const name = tableName(cur);
+        if (name && !seen.has(name)) {
+            seen.add(name);
+            found.push(name);
+        }
+        for (const v of Object.values(cur)) {
+            if (v && typeof v === 'object')
+                stack.push(v);
+        }
+    }
+    return found;
+}
+// Column NAMES referenced inside a WhereNode subtree — never values.
+function whereColumns(whereNode) {
+    const cols = new Set();
+    const stack = [whereNode];
+    let budget = 5000;
+    while (stack.length && budget-- > 0) {
+        const cur = stack.pop();
+        if (!cur || typeof cur !== 'object')
+            continue;
+        const n = cur;
+        if (n.kind === 'ColumnNode') {
+            const col = n.column;
+            if (col?.name)
+                cols.add(col.name);
+        }
+        for (const v of Object.values(n)) {
+            if (v && typeof v === 'object')
+                stack.push(v);
+        }
+    }
+    return [...cols].sort();
+}
+function extractPks(rows, pkCols) {
+    if (pkCols.length === 0)
+        return [];
+    // A set: a join can return the same primary-table row many times, but the
+    // footprint records which DISTINCT rows were touched.
+    const seen = new Set();
+    const pks = [];
+    for (const row of rows) {
+        const vals = pkCols.map((c) => row[c]);
+        if (vals.some((v) => v === undefined))
+            continue; // column not selected — can't form a PK
+        const pk = vals.map((v) => String(v)).join(':');
+        if (!seen.has(pk)) {
+            seen.add(pk);
+            pks.push(pk);
+        }
+    }
+    return pks;
+}
+// Creates the Reprova Kysely footprint plugin.
+// Usage: new Kysely({ dialect, plugins: [createKyselyPlugin()] })
+function createKyselyPlugin(opts = {}) {
+    const primaryKey = opts.primaryKey ?? (() => ['id']);
+    const captureWhereShape = opts.captureWhereShape !== false;
+    // Keyed by the queryId OBJECT shared across both hooks; a compiled-but-never-
+    // executed query is GC'd without leaking.
+    const pending = new WeakMap();
+    return {
+        transformQuery(args) {
+            try {
+                const node = args.node;
+                const op = OP_BY_KIND[node.kind];
+                if (op) {
+                    const whereShape = captureWhereShape && node.where
+                        ? whereColumns(node.where).join(',') || undefined
+                        : undefined;
+                    pending.set(args.queryId, {
+                        op,
+                        primary: primaryTable(node),
+                        tables: collectTables(node),
+                        whereShape,
+                    });
+                }
+            }
+            catch {
+                // A footprint failure must never alter the query — fall through.
+            }
+            return args.node;
+        },
+        async transformResult(args) {
+            try {
+                const meta = pending.get(args.queryId);
+                if (meta) {
+                    pending.delete(args.queryId);
+                    const ctx = context_js_1.contextStorage.getStore();
+                    if (ctx) {
+                        const result = args.result;
+                        const rows = result.rows ?? [];
+                        const affected = result.numAffectedRows != null ? Number(result.numAffectedRows) : undefined;
+                        const count = rows.length || affected || 0;
+                        const primary = meta.primary ?? '$unknown';
+                        const entry = {
+                            model: primary,
+                            op: meta.op,
+                            pks: extractPks(rows, primaryKey(primary)),
+                            where_shape: meta.whereShape,
+                            count,
+                            note: count === 0 ? 'returned 0 rows' : undefined,
+                            resolved: true,
+                        };
+                        ctx.footprint.push(entry);
+                        // Joined / subquery tables: recorded so the extractor knows they
+                        // were touched, but without PKs (result columns can't be reliably
+                        // attributed across a join).
+                        for (const t of meta.tables) {
+                            if (t === primary)
+                                continue;
+                            ctx.footprint.push({ model: t, op: meta.op, pks: [], count: 0, note: 'referenced (join/subquery)', resolved: true });
+                        }
+                    }
+                }
+            }
+            catch {
+                // Never break the result pipeline over a footprint error.
+            }
+            return args.result;
+        },
+    };
+}

package/dist/cjs/legacyPrisma.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instrumentLegacyPrismaClient = instrumentLegacyPrismaClient;
+const context_js_1 = require("./context.js");
+const prisma_js_1 = require("./prisma.js");
+// Older Prisma clients have no query-lifecycle hook at all — confirmed live
+// against a real @prisma/client@2.0.0-beta.4 (2020): $extends (introduced
+// 4.16, 2023), $use (Prisma's earlier middleware API, introduced ~2.something
+// and itself later deprecated in favor of $extends), and even $queryRaw are
+// all `undefined` on that client. createPrismaExtension's $allOperations has
+// nothing to attach to on a client like this.
+//
+// What IS there, on every Prisma client generator back to the very first
+// one: a plain per-model delegate object (client.article, client.user, ...)
+// whose CRUD methods (findMany, create, update, ...) are ordinary
+// own-property functions — directly reassignable, the same monkey-patch
+// shape this SDK already uses for TypeORM's QueryRunner.prototype.query and
+// Mongoose's already-compiled models (instrumentAlreadyCompiledModels). This
+// wraps each one directly instead of relying on any official extension
+// point, so footprint capture and every detector built on recordPrismaOperation
+// work identically regardless of how old the installed client is.
+//
+// Also captures DB-rejected writes the same way typeorm.ts does for a
+// TypeORM app: create/update/upsert/delete/updateMany/deleteMany record an
+// `<op>_failed` footprint entry on rejection — column NAMES only (from the
+// call's own `data`/`where` argument keys), never the bound values, per the
+// metadata-only rule. A read failing has no "what would have been written"
+// story, so only write ops get this treatment, matching typeorm.ts's scope.
+const READ_OPS = new Set(['findOne', 'findUnique', 'findUniqueOrThrow', 'findFirst', 'findFirstOrThrow', 'findMany', 'count', 'aggregate', 'groupBy']);
+const WRITE_OPS = new Set(['create', 'createMany', 'update', 'updateMany', 'upsert', 'delete', 'deleteMany']);
+// `findOne` is Prisma's own deprecated alias for `findUnique` (renamed
+// well before $extends existed, still present on clients this old) —
+// normalized before recording so the footprint's `op` field and
+// operationMatchesHook's after_read gating (invariantRules.ts's READ_OPS,
+// which only lists modern names) both see the same vocabulary regardless
+// of which Prisma version actually captured it.
+function normalizeOperation(method) {
+    return method === 'findOne' ? 'findUnique' : method;
+}
+// Reassigns each detected model delegate's own CRUD methods exactly once —
+// re-instrumenting an already-patched delegate (e.g. instrumentPrisma called
+// twice) would double-record every footprint entry.
+const patchedDelegates = new WeakSet();
+function instrumentLegacyPrismaClient(client, opts = {}) {
+    try {
+        const dmmf = opts.dmmf ?? client.dmmf;
+        const hooks = {
+            dmmf,
+            getRules: opts.getRules,
+            inferenceReporter: opts.inferenceReporter,
+            writeCountDriftReporter: opts.writeCountDriftReporter,
+            writeCountBaselinePoller: opts.writeCountBaselinePoller,
+        };
+        const modelNameFor = buildModelNameResolver(dmmf);
+        for (const [key, delegate] of Object.entries(client)) {
+            if (!isModelDelegate(delegate))
+                continue;
+            if (patchedDelegates.has(delegate))
+                continue;
+            patchedDelegates.add(delegate);
+            const modelName = modelNameFor(key);
+            for (const method of Object.keys(delegate)) {
+                if (READ_OPS.has(method)) {
+                    patchReadMethod(delegate, method, modelName, hooks);
+                }
+                else if (WRITE_OPS.has(method)) {
+                    patchWriteMethod(delegate, method, modelName, hooks);
+                }
+            }
+        }
+    }
+    catch {
+        /* never throw from install */
+    }
+}
+function isModelDelegate(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const d = value;
+    return typeof d.findMany === 'function' || typeof d.create === 'function';
+}
+// Prisma's own convention: a model named `Article` gets a delegate property
+// named `article` (first letter lowercased) — true on every version this
+// adapter targets. Falls back to that convention when dmmf isn't available
+// at all; uses the real dmmf model list when it is, so an unconventional
+// name still resolves correctly.
+function buildModelNameResolver(dmmf) {
+    if (!dmmf) {
+        return (key) => key.charAt(0).toUpperCase() + key.slice(1);
+    }
+    const byLowerFirst = new Map();
+    for (const model of dmmf.datamodel.models) {
+        byLowerFirst.set(model.name.charAt(0).toLowerCase() + model.name.slice(1), model.name);
+    }
+    return (key) => byLowerFirst.get(key) ?? key.charAt(0).toUpperCase() + key.slice(1);
+}
+function patchReadMethod(delegate, method, modelName, hooks) {
+    const original = delegate[method];
+    const operation = normalizeOperation(method);
+    delegate[method] = async function (...args) {
+        const result = await original.apply(this, args);
+        const ctx = context_js_1.contextStorage.getStore();
+        if (ctx) {
+            const callArgs = args[0] ?? {};
+            await (0, prisma_js_1.recordPrismaOperation)(ctx, modelName, operation, callArgs, result, hooks);
+        }
+        return result;
+    };
+}
+function patchWriteMethod(delegate, method, modelName, hooks) {
+    const original = delegate[method];
+    delegate[method] = async function (...args) {
+        const callArgs = args[0] ?? {};
+        let result;
+        try {
+            result = await original.apply(this, args);
+        }
+        catch (err) {
+            const ctx = context_js_1.contextStorage.getStore();
+            if (ctx)
+                (0, prisma_js_1.recordFailedWrite)(ctx, modelName, method, callArgs);
+            throw err;
+        }
+        const ctx = context_js_1.contextStorage.getStore();
+        if (ctx) {
+            await (0, prisma_js_1.recordPrismaOperation)(ctx, modelName, method, callArgs, result, hooks);
+        }
+        return result;
+    };
+}

package/dist/cjs/mikroorm.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installMikroOrmSubscriber = installMikroOrmSubscriber;
+const context_js_1 = require("./context.js");
+function pkOf(entity, meta) {
+    const keys = meta?.primaryKeys ?? [];
+    if (!entity || keys.length === 0)
+        return null;
+    const vals = keys.map((k) => entity[k]);
+    if (vals.some((v) => v === undefined || v === null))
+        return null;
+    return vals.map((v) => String(v)).join(':');
+}
+// Find-or-create the (table, op) entry for this request and fold in the PK.
+function recordPk(table, op, pk) {
+    const ctx = context_js_1.contextStorage.getStore();
+    if (!ctx || !table)
+        return;
+    let entry = ctx.footprint.find((f) => f.model === table && f.op === op);
+    if (!entry) {
+        entry = { model: table, op, pks: [], count: 0 };
+        ctx.footprint.push(entry);
+    }
+    if (pk !== null && !entry.pks.includes(pk))
+        entry.pks.push(pk);
+    entry.count = entry.pks.length;
+}
+// Accepts either a MikroORM instance (orm.em.getEventManager()) or an
+// EntityManager directly (em.getEventManager()) — Reprova has no way to
+// know which one a given host app kept a reference to.
+function getEventManager(orm) {
+    const o = orm;
+    if (typeof o.getEventManager === 'function')
+        return o.getEventManager();
+    if (o.em && typeof o.em.getEventManager === 'function')
+        return o.em.getEventManager();
+    return undefined;
+}
+// Installs a footprint subscriber on an initialized MikroORM instance (or
+// EntityManager). Call AFTER MikroORM.init() — the EventManager only
+// exists once the ORM is initialized. Registers a plain object, so the
+// host needs no @Subscriber()-decorated class.
+function installMikroOrmSubscriber(orm) {
+    const subscriber = {
+        onLoad(args) {
+            try {
+                recordPk(args?.meta?.className, 'select', pkOf(args?.entity, args?.meta));
+            }
+            catch { /* never break */ }
+        },
+        afterCreate(args) {
+            try {
+                recordPk(args?.meta?.className, 'insert', pkOf(args?.entity, args?.meta));
+            }
+            catch { /* ignore */ }
+        },
+        afterUpdate(args) {
+            try {
+                recordPk(args?.meta?.className, 'update', pkOf(args?.entity, args?.meta));
+            }
+            catch { /* ignore */ }
+        },
+        afterDelete(args) {
+            try {
+                recordPk(args?.meta?.className, 'delete', pkOf(args?.entity, args?.meta));
+            }
+            catch { /* ignore */ }
+        },
+    };
+    try {
+        getEventManager(orm)?.registerSubscriber(subscriber);
+    }
+    catch { /* never throw from install */ }
+}