@skmtc/core 0.27.0 → 0.28.1

package/script/enrichments/EnrichmentAudit.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * @fileoverview The enrichment consumption audit.
+ *
+ * The engine already performs every enrichment lookup during the generate
+ * walk — the dispatch loops read each `[generatorId][...subject]` block to
+ * enumerate variants, the projection statics read each subject leaf and
+ * the run-constant scopes, and the Drivers read peer blocks for the
+ * variant guard. `EnrichmentAudit` records those lookups (every read is
+ * routed through `GenerateContext.readEnrichment`, the single choke
+ * point) and, post-walk, diffs them against the paths actually present in
+ * `settings.enrichments`. A configured path no lookup touched is dead
+ * config — a typo'd generator id / path / method / model name, or an
+ * entry orphaned by spec evolution — and becomes an
+ * `UNCONSUMED_ENRICHMENT` warning on the manifest.
+ *
+ * Consumption is recorded prefix-closed: consuming
+ * `[id, '/pets', 'post', 'main']` also marks `[id, '/pets', 'post']`,
+ * `[id, '/pets']`, and `[id]`. The present-path enumeration walks each
+ * generator's slice to the block depth its entry type dictates (model:
+ * `[refName]`; operation / webhook / GQL: two segments), so the diff
+ * compares like with like. Reserved keys (`_generator`, `_stack`) are
+ * engine-owned constants and never flagged.
+ *
+ * Everything here is warn-level and fail-open — the audit can only add
+ * warnings to the manifest, never change generation output.
+ *
+ * @module EnrichmentAudit
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _EnrichmentAudit_instances, _EnrichmentAudit_consumed, _EnrichmentAudit_children, _EnrichmentAudit_warnings, _EnrichmentAudit_reported, _EnrichmentAudit_isConsumed, _EnrichmentAudit_divergenceSuggestion, _EnrichmentAudit_checkBlock;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasVariantEnrichment = exports.EnrichmentAudit = void 0;
+const Enrichments_js_1 = require("../types/Enrichments.js");
+const EnrichmentWarning_js_1 = require("./EnrichmentWarning.js");
+const nearestKey_js_1 = require("../helpers/nearestKey.js");
+const toPathKey = (segments) => JSON.stringify(segments);
+const isRecord = (input) => typeof input === 'object' && input !== null && !Array.isArray(input);
+class EnrichmentAudit {
+    constructor() {
+        _EnrichmentAudit_instances.add(this);
+        /** Prefix-closed set of consumed routing paths, keyed by {@link toPathKey}. */
+        _EnrichmentAudit_consumed.set(this, new Set()
+        /** Consumed child segments per parent path — the suggestion candidates. */
+        );
+        /** Consumed child segments per parent path — the suggestion candidates. */
+        _EnrichmentAudit_children.set(this, new Map());
+        _EnrichmentAudit_warnings.set(this, []
+        /** Identity keys of reported warnings — reads repeat, warnings must not. */
+        );
+        /** Identity keys of reported warnings — reads repeat, warnings must not. */
+        _EnrichmentAudit_reported.set(this, new Set()
+        /**
+         * Record one enrichment lookup. Every prefix of `segments` is marked
+         * consumed, so block-level and leaf-level reads land in one namespace.
+         */
+        );
+    }
+    /**
+     * Record one enrichment lookup. Every prefix of `segments` is marked
+     * consumed, so block-level and leaf-level reads land in one namespace.
+     */
+    consume(segments) {
+        let parentKey = toPathKey([]);
+        for (let end = 1; end <= segments.length; end++) {
+            const key = toPathKey(segments.slice(0, end));
+            __classPrivateFieldGet(this, _EnrichmentAudit_consumed, "f").add(key);
+            const siblings = __classPrivateFieldGet(this, _EnrichmentAudit_children, "f").get(parentKey);
+            if (siblings) {
+                siblings.add(segments[end - 1]);
+            }
+            else {
+                __classPrivateFieldGet(this, _EnrichmentAudit_children, "f").set(parentKey, new Set([segments[end - 1]]));
+            }
+            parentKey = key;
+        }
+    }
+    /**
+     * Add a warning, deduplicated on `(type, path)` — the same lookup can
+     * repeat many times per run (one per insert call) and must produce one
+     * warning.
+     */
+    report(warning) {
+        const key = toPathKey([warning.type, ...warning.path]);
+        if (__classPrivateFieldGet(this, _EnrichmentAudit_reported, "f").has(key))
+            return;
+        __classPrivateFieldGet(this, _EnrichmentAudit_reported, "f").add(key);
+        __classPrivateFieldGet(this, _EnrichmentAudit_warnings, "f").push(warning);
+    }
+    /**
+     * Diff the configured enrichment paths against the consumed set and
+     * return every warning gathered during the run plus the addressing
+     * misses found here. Called once, after the generate walk.
+     */
+    finalize({ enrichments, generators, skippedGeneratorIds }) {
+        if (!isRecord(enrichments))
+            return [...__classPrivateFieldGet(this, _EnrichmentAudit_warnings, "f")];
+        const generatorsById = new Map(generators.map(generator => [generator.id, generator]));
+        const skipped = new Set(skippedGeneratorIds);
+        for (const [generatorId, slot] of Object.entries(enrichments)) {
+            if (generatorId === Enrichments_js_1.STACK_ENRICHMENT_KEY)
+                continue;
+            // Other `_`-prefixed keys are structurally invalid — the
+            // `generatorEnrichments` schema flags those at config load.
+            if ((0, Enrichments_js_1.isReservedEnrichmentKey)(generatorId))
+                continue;
+            if (skipped.has(generatorId)) {
+                this.report({
+                    level: 'info',
+                    type: 'SKIPPED_GENERATOR_ENRICHMENT',
+                    path: [generatorId],
+                    message: `generator '${generatorId}' is skipped in this run — ` +
+                        `its enrichments were not applied`
+                });
+                continue;
+            }
+            const generator = generatorsById.get(generatorId);
+            if (!generator) {
+                // An insert-only peer (reached via insertOperation / insertModel
+                // without an entry of its own) still consumes its slice through
+                // the projection statics — a consumed prefix means the slice is
+                // live, and without an entry type its depth is unknowable, so the
+                // audit leaves it alone.
+                if (__classPrivateFieldGet(this, _EnrichmentAudit_instances, "m", _EnrichmentAudit_isConsumed).call(this, [generatorId]))
+                    continue;
+                const suggestion = (0, nearestKey_js_1.nearestKey)(generatorId, generatorsById.keys());
+                this.report({
+                    level: 'warning',
+                    type: 'UNKNOWN_GENERATOR_ID',
+                    path: [generatorId],
+                    message: `enrichments are configured for '${generatorId}' but no generator ` +
+                        `with that id is in this run` +
+                        (suggestion !== undefined ? ` (did you mean '${suggestion}'?)` : ''),
+                    ...(suggestion !== undefined ? { suggestion } : {})
+                });
+                continue;
+            }
+            if (!isRecord(slot))
+                continue;
+            // The generator is in the run but consumed nothing at all — the
+            // document has no subjects of its type (or the wrong protocol).
+            // Per-entry warnings would fall back to cross-generator siblings for
+            // their "did you mean …?" and could name an unrelated generator, so
+            // collapse to one generator-level warning that says what happened.
+            const hasSubjectEntries = Object.keys(slot).some(key => !(0, Enrichments_js_1.isReservedEnrichmentKey)(key));
+            if (!__classPrivateFieldGet(this, _EnrichmentAudit_instances, "m", _EnrichmentAudit_isConsumed).call(this, [generatorId]) && hasSubjectEntries) {
+                this.report({
+                    level: 'warning',
+                    type: 'UNCONSUMED_ENRICHMENT',
+                    path: [generatorId],
+                    message: `enrichments are configured for '${generatorId}' but it matched ` +
+                        `no subjects in this run — its enrichments were never read`
+                });
+                continue;
+            }
+            // Block depth per entry type: `[refName]` for models,
+            // `[path][method]` / `[name][method]` / `[rootKind][fieldName]`
+            // for the operation-shaped types.
+            const subjectDepth = generator.type === 'model' ? 1 : 2;
+            for (const [subjectKey, subjectValue] of Object.entries(slot)) {
+                // `_generator` (and any other reserved key) is engine-owned — read
+                // through the dedicated helpers by known key, always consumed.
+                if ((0, Enrichments_js_1.isReservedEnrichmentKey)(subjectKey))
+                    continue;
+                if (subjectDepth === 1 ||
+                    !isRecord(subjectValue) ||
+                    Object.keys(subjectValue).length === 0) {
+                    __classPrivateFieldGet(this, _EnrichmentAudit_instances, "m", _EnrichmentAudit_checkBlock).call(this, [generatorId, subjectKey]);
+                    continue;
+                }
+                for (const methodKey of Object.keys(subjectValue)) {
+                    __classPrivateFieldGet(this, _EnrichmentAudit_instances, "m", _EnrichmentAudit_checkBlock).call(this, [generatorId, subjectKey, methodKey]);
+                }
+            }
+        }
+        return [...__classPrivateFieldGet(this, _EnrichmentAudit_warnings, "f")];
+    }
+}
+exports.EnrichmentAudit = EnrichmentAudit;
+_EnrichmentAudit_consumed = new WeakMap(), _EnrichmentAudit_children = new WeakMap(), _EnrichmentAudit_warnings = new WeakMap(), _EnrichmentAudit_reported = new WeakMap(), _EnrichmentAudit_instances = new WeakSet(), _EnrichmentAudit_isConsumed = function _EnrichmentAudit_isConsumed(segments) {
+    return __classPrivateFieldGet(this, _EnrichmentAudit_consumed, "f").has(toPathKey(segments));
+}, _EnrichmentAudit_divergenceSuggestion = function _EnrichmentAudit_divergenceSuggestion(path) {
+    for (let depth = 0; depth < path.length; depth++) {
+        if (__classPrivateFieldGet(this, _EnrichmentAudit_instances, "m", _EnrichmentAudit_isConsumed).call(this, path.slice(0, depth + 1)))
+            continue;
+        const siblings = __classPrivateFieldGet(this, _EnrichmentAudit_children, "f").get(toPathKey(path.slice(0, depth)));
+        return siblings ? (0, nearestKey_js_1.nearestKey)(path[depth], siblings) : undefined;
+    }
+    return undefined;
+}, _EnrichmentAudit_checkBlock = function _EnrichmentAudit_checkBlock(path) {
+    if (__classPrivateFieldGet(this, _EnrichmentAudit_instances, "m", _EnrichmentAudit_isConsumed).call(this, path))
+        return;
+    const suggestion = __classPrivateFieldGet(this, _EnrichmentAudit_instances, "m", _EnrichmentAudit_divergenceSuggestion).call(this, path);
+    this.report({
+        level: 'warning',
+        type: 'UNCONSUMED_ENRICHMENT',
+        path,
+        message: `enrichment entry '${(0, EnrichmentWarning_js_1.formatEnrichmentPath)(path)}' was never consumed — ` +
+            `no matching generator or subject in this run` +
+            (suggestion !== undefined ? ` (did you mean '${suggestion}'?)` : ''),
+        ...(suggestion !== undefined ? { suggestion } : {})
+    });
+};
+/**
+ * Whether an enrichment block declares the given variant — the presence
+ * probe behind `SKIPPED_SUBJECT_ENRICHMENT` info lines. Exported for the
+ * dispatch loops; a non-record block (absent or malformed) has no
+ * variants.
+ */
+const hasVariantEnrichment = (block, variant) => isRecord(block) && variant in block;
+exports.hasVariantEnrichment = hasVariantEnrichment;

package/script/enrichments/EnrichmentWarning.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview The enrichment-warning surface — the manifest's record of
+ * enrichment config that did not do what the consumer intended.
+ *
+ * Three validation layers precede this one: structural validation at CLI
+ * load (`generatorEnrichments`), the per-leaf Valibot parse at generate
+ * time (a wrongly-typed value in a reached leaf throws), and the
+ * missing-`'main'` variant throw (`toVariantList`). All three are loud.
+ * What they cannot see is *addressing*: a typo'd generator id, path,
+ * method, or model name makes `get()` miss silently — defaults apply and
+ * the config entry is dead. Unknown leaf keys are equally silent:
+ * `v.object` strips them before the generator sees them.
+ *
+ * `EnrichmentWarning` is the shared shape for both detectors:
+ *
+ *  - the **consumption audit** (`EnrichmentAudit`) — records every
+ *    enrichment lookup the engine performs during the generate walk and,
+ *    post-walk, flags configured entries no lookup ever touched;
+ *  - **unknown-key detection** (`findUnknownKeys`, run inside
+ *    `parseEnrichmentUmbrella`) — flags leaf keys the generator's schema
+ *    does not declare.
+ *
+ * Both are warn-level and fail-open: generation output is never affected.
+ * The warnings ride the manifest (`manifest.enrichmentWarnings`) so
+ * post-run diagnostics can re-read them without re-running.
+ *
+ * @module EnrichmentWarning
+ */
+import * as v from 'valibot';
+/**
+ * Discriminates what went wrong with an enrichment entry:
+ *
+ *  - `UNCONSUMED_ENRICHMENT` — a configured routing path no engine lookup
+ *    consumed (typo'd path / method / model name, or an entry orphaned by
+ *    spec evolution). Warning.
+ *  - `UNKNOWN_GENERATOR_ID` — a top-level enrichment key that matches no
+ *    generator in the run (and no insert-only peer consumed it). Warning.
+ *  - `UNKNOWN_ENRICHMENT_KEY` — a leaf key the generator's enrichment
+ *    schema does not declare; Valibot strips it silently. Warning.
+ *  - `SKIPPED_SUBJECT_ENRICHMENT` — the entry is addressed correctly but
+ *    its subject was excluded by `skip`/`include`. Info: temporary skips
+ *    are legitimate, so this is not treated as dead config.
+ *  - `SKIPPED_GENERATOR_ENRICHMENT` — the whole generator is skipped
+ *    (string entry in `settings.skip`) while enrichments for it exist.
+ *    Info, for the same reason.
+ */
+export type EnrichmentWarningType = 'UNCONSUMED_ENRICHMENT' | 'UNKNOWN_GENERATOR_ID' | 'UNKNOWN_ENRICHMENT_KEY' | 'SKIPPED_SUBJECT_ENRICHMENT' | 'SKIPPED_GENERATOR_ENRICHMENT';
+export declare const enrichmentWarningType: v.GenericSchema<EnrichmentWarningType>;
+/**
+ * One enrichment-config warning. `path` is the routing key sequence under
+ * `client.json#settings.enrichments` locating the offending entry —
+ * `[generatorId, ...subjectSegments]` for addressing warnings, extended
+ * down to the leaf key for `UNKNOWN_ENRICHMENT_KEY`. `suggestion` carries
+ * the nearest known key when a close match exists (`submitLabl` →
+ * `submitLabel`); the human-readable `message` already folds it in.
+ */
+export type EnrichmentWarning = {
+    level: 'warning' | 'info';
+    type: EnrichmentWarningType;
+    path: readonly string[];
+    message: string;
+    suggestion?: string;
+};
+export declare const enrichmentWarning: v.GenericSchema<EnrichmentWarning>;
+/**
+ * Render a routing path for warning messages:
+ * `['@skmtc/gen-shadcn-form', '/pets', 'post']` →
+ * `'@skmtc/gen-shadcn-form → /pets → post'`. The arrow separator keeps
+ * segments visually distinct even when they contain dots or slashes.
+ */
+export declare const formatEnrichmentPath: (path: readonly string[]) => string;
+//# sourceMappingURL=EnrichmentWarning.d.ts.map

package/script/enrichments/EnrichmentWarning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnrichmentWarning.d.ts","sourceRoot":"","sources":["../../src/enrichments/EnrichmentWarning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,qBAAqB,GAC7B,uBAAuB,GACvB,sBAAsB,GACtB,wBAAwB,GACxB,4BAA4B,GAC5B,8BAA8B,CAAA;AAElC,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,aAAa,CAAC,qBAAqB,CAMvE,CAAA;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,SAAS,GAAG,MAAM,CAAA;IACzB,IAAI,EAAE,qBAAqB,CAAA;IAC3B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,aAAa,CAAC,iBAAiB,CAM/D,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAA0B,CAAA"}

package/script/enrichments/EnrichmentWarning.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * @fileoverview The enrichment-warning surface — the manifest's record of
+ * enrichment config that did not do what the consumer intended.
+ *
+ * Three validation layers precede this one: structural validation at CLI
+ * load (`generatorEnrichments`), the per-leaf Valibot parse at generate
+ * time (a wrongly-typed value in a reached leaf throws), and the
+ * missing-`'main'` variant throw (`toVariantList`). All three are loud.
+ * What they cannot see is *addressing*: a typo'd generator id, path,
+ * method, or model name makes `get()` miss silently — defaults apply and
+ * the config entry is dead. Unknown leaf keys are equally silent:
+ * `v.object` strips them before the generator sees them.
+ *
+ * `EnrichmentWarning` is the shared shape for both detectors:
+ *
+ *  - the **consumption audit** (`EnrichmentAudit`) — records every
+ *    enrichment lookup the engine performs during the generate walk and,
+ *    post-walk, flags configured entries no lookup ever touched;
+ *  - **unknown-key detection** (`findUnknownKeys`, run inside
+ *    `parseEnrichmentUmbrella`) — flags leaf keys the generator's schema
+ *    does not declare.
+ *
+ * Both are warn-level and fail-open: generation output is never affected.
+ * The warnings ride the manifest (`manifest.enrichmentWarnings`) so
+ * post-run diagnostics can re-read them without re-running.
+ *
+ * @module EnrichmentWarning
+ */
+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.formatEnrichmentPath = exports.enrichmentWarning = exports.enrichmentWarningType = void 0;
+const v = __importStar(require("valibot"));
+exports.enrichmentWarningType = v.picklist([
+    'UNCONSUMED_ENRICHMENT',
+    'UNKNOWN_GENERATOR_ID',
+    'UNKNOWN_ENRICHMENT_KEY',
+    'SKIPPED_SUBJECT_ENRICHMENT',
+    'SKIPPED_GENERATOR_ENRICHMENT'
+]);
+exports.enrichmentWarning = v.object({
+    level: v.picklist(['warning', 'info']),
+    type: exports.enrichmentWarningType,
+    path: v.array(v.string()),
+    message: v.string(),
+    suggestion: v.optional(v.string())
+});
+/**
+ * Render a routing path for warning messages:
+ * `['@skmtc/gen-shadcn-form', '/pets', 'post']` →
+ * `'@skmtc/gen-shadcn-form → /pets → post'`. The arrow separator keeps
+ * segments visually distinct even when they contain dots or slashes.
+ */
+const formatEnrichmentPath = (path) => path.join(' → ');
+exports.formatEnrichmentPath = formatEnrichmentPath;

package/script/enrichments/findUnknownKeys.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Unknown-key detection for enrichment leaves.
+ *
+ * Valibot's `v.object` strips keys the schema does not declare — a
+ * misspelled optional key (`submitLabl` for `submitLabel`) parses cleanly
+ * and the generator silently sees the default. `findUnknownKeys` walks a
+ * value against its schema and reports every key the schema would drop,
+ * so `parseEnrichmentUmbrella` can surface them as
+ * `UNKNOWN_ENRICHMENT_KEY` warnings.
+ *
+ * Comparing against the *schema* (not the parsed output) keeps the check
+ * immune to `v.pipe` transforms that legitimately reshape output, and
+ * gives correct "did you mean …?" suggestions — the intended key is in
+ * the schema's entries even when it is optional and absent from the
+ * parsed value. This is deliberately a warning layer, not
+ * `v.strictObject`: a shared client.json paired with an older generator
+ * version stays survivable under version skew instead of hard-failing.
+ *
+ * The walk is fail-open: unions, intersections, loose objects, and any
+ * shape it cannot attribute keys to are left alone.
+ *
+ * @module findUnknownKeys
+ */
+/**
+ * One key the schema would silently drop. `path` runs from the walked
+ * root down to the unknown key (array indices as strings); `suggestion`
+ * is the nearest declared key at the same level, when a plausible typo
+ * target exists.
+ */
+export type UnknownKey = {
+    path: string[];
+    suggestion?: string;
+};
+/**
+ * Every key in `value` that `schema` does not declare and `v.parse` would
+ * therefore drop. Wrong-typed values are not this function's concern —
+ * the subsequent `v.parse` throws on those as before.
+ */
+export declare const findUnknownKeys: (schema: unknown, value: unknown) => UnknownKey[];
+//# sourceMappingURL=findUnknownKeys.d.ts.map

package/script/enrichments/findUnknownKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findUnknownKeys.d.ts","sourceRoot":"","sources":["../../src/enrichments/findUnknownKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA;AAgDD;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,OAAO,EAAE,OAAO,OAAO,KAAG,UAAU,EAI3E,CAAA"}

package/script/enrichments/findUnknownKeys.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * @fileoverview Unknown-key detection for enrichment leaves.
+ *
+ * Valibot's `v.object` strips keys the schema does not declare — a
+ * misspelled optional key (`submitLabl` for `submitLabel`) parses cleanly
+ * and the generator silently sees the default. `findUnknownKeys` walks a
+ * value against its schema and reports every key the schema would drop,
+ * so `parseEnrichmentUmbrella` can surface them as
+ * `UNKNOWN_ENRICHMENT_KEY` warnings.
+ *
+ * Comparing against the *schema* (not the parsed output) keeps the check
+ * immune to `v.pipe` transforms that legitimately reshape output, and
+ * gives correct "did you mean …?" suggestions — the intended key is in
+ * the schema's entries even when it is optional and absent from the
+ * parsed value. This is deliberately a warning layer, not
+ * `v.strictObject`: a shared client.json paired with an older generator
+ * version stays survivable under version skew instead of hard-failing.
+ *
+ * The walk is fail-open: unions, intersections, loose objects, and any
+ * shape it cannot attribute keys to are left alone.
+ *
+ * @module findUnknownKeys
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findUnknownKeys = void 0;
+const valibotShape_js_1 = require("./valibotShape.js");
+const nearestKey_js_1 = require("../helpers/nearestKey.js");
+const isRecord = (input) => typeof input === 'object' && input !== null && !Array.isArray(input);
+const walk = (rawSchema, value, path, out) => {
+    if (value === undefined || value === null)
+        return;
+    if (!(0, valibotShape_js_1.isValibotSchema)(rawSchema))
+        return;
+    // A piped schema spreads its base, so `type` / `entries` / `item` are
+    // still visible here — no explicit pipe handling needed.
+    const { inner } = (0, valibotShape_js_1.unwrap)(rawSchema);
+    switch (inner.type) {
+        case 'object': {
+            if (!isRecord(value) || !(0, valibotShape_js_1.isEntriesRecord)(inner.entries))
+                return;
+            const entries = inner.entries;
+            const declared = Object.keys(entries);
+            for (const [key, member] of Object.entries(value)) {
+                if (key in entries) {
+                    walk(entries[key], member, [...path, key], out);
+                    continue;
+                }
+                const suggestion = (0, nearestKey_js_1.nearestKey)(key, declared);
+                out.push({ path: [...path, key], ...(suggestion !== undefined ? { suggestion } : {}) });
+            }
+            return;
+        }
+        case 'record': {
+            if (!isRecord(value))
+                return;
+            for (const [key, member] of Object.entries(value)) {
+                walk(inner.value, member, [...path, key], out);
+            }
+            return;
+        }
+        case 'array': {
+            if (!Array.isArray(value))
+                return;
+            value.forEach((member, index) => walk(inner.item, member, [...path, String(index)], out));
+            return;
+        }
+        default:
+            // Leaves, unions, intersections, loose/strict objects: nothing to
+            // attribute, or Valibot itself errors loudly (strict). Fail open.
+            return;
+    }
+};
+/**
+ * Every key in `value` that `schema` does not declare and `v.parse` would
+ * therefore drop. Wrong-typed values are not this function's concern —
+ * the subsequent `v.parse` throws on those as before.
+ */
+const findUnknownKeys = (schema, value) => {
+    const out = [];
+    walk(schema, value, [], out);
+    return out;
+};
+exports.findUnknownKeys = findUnknownKeys;

package/script/enrichments/parseEnrichmentUmbrella.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview The shared umbrella-parse seam for the projection-base
+ * factories.
+ *
+ * Every `static toEnrichments` — OAS operation, webhook, GQL operation,
+ * model — assembles the same `{ subject, generator, stack }` umbrella
+ * from three storage spots and parses it through the generator's
+ * composite schema. This helper centralizes that assembly so both
+ * enrichment-validation mechanisms ride one seam:
+ *
+ *  - the reads go through `context.readEnrichment` — the recording
+ *    accessor feeding the consumption audit (`EnrichmentAudit`);
+ *  - the raw values are diffed against the schema (`findUnknownKeys`)
+ *    and dropped keys surface as `UNKNOWN_ENRICHMENT_KEY` warnings.
+ *
+ * The `stack` scope is exempt from unknown-key detection: it is a single
+ * bag shared by every generator in the composition, and each consumer
+ * declares only the fields it reads — keys other generators own are
+ * expected, not typos.
+ *
+ * A wrong-typed value still throws exactly as before — the `v.parse` at
+ * the end is unchanged, and unknown-key detection runs first so a
+ * throwing leaf doesn't hide a dropped key.
+ *
+ * @module parseEnrichmentUmbrella
+ */
+import * as v from 'valibot';
+import { type EnrichmentWarning } from './EnrichmentWarning.js';
+/**
+ * Minimal structural view of the context the parse needs. Any
+ * `GenerateContext` satisfies it; kept structural so the helper stays
+ * decoupled from the full context type and is trivially testable.
+ */
+type UmbrellaParseContext = {
+    readEnrichment: (segments: readonly string[]) => unknown;
+    reportEnrichmentWarning: (warning: EnrichmentWarning) => void;
+};
+type ParseEnrichmentUmbrellaArgs<EnrichmentType> = {
+    context: UmbrellaParseContext;
+    generatorId: string;
+    /**
+     * Subject routing segments under `[generatorId]`, including the
+     * variant — `[path, method, variant]` for OAS operations,
+     * `[name, method, variant]` for webhooks,
+     * `[rootKind, fieldName, variant]` for GQL operations,
+     * `[refName, variant]` for models.
+     */
+    subjectSegments: readonly string[];
+    /** The generator's composite `{ subject, generator, stack }` schema. */
+    schema: v.GenericSchema<EnrichmentType>;
+};
+/**
+ * Assemble and parse one `{ subject, generator, stack }` enrichment
+ * umbrella, recording the reads for the consumption audit and reporting
+ * schema-dropped keys.
+ *
+ * @throws on a wrong-typed value, exactly like the raw `v.parse` this
+ *   wraps — the generator's item is then recorded as `error` and the run
+ *   continues (fail-open).
+ */
+export declare const parseEnrichmentUmbrella: <EnrichmentType>({ context, generatorId, subjectSegments, schema }: ParseEnrichmentUmbrellaArgs<EnrichmentType>) => EnrichmentType;
+export {};
+//# sourceMappingURL=parseEnrichmentUmbrella.d.ts.map

package/script/enrichments/parseEnrichmentUmbrella.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseEnrichmentUmbrella.d.ts","sourceRoot":"","sources":["../../src/enrichments/parseEnrichmentUmbrella.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAG5B,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAErF;;;;GAIG;AACH,KAAK,oBAAoB,GAAG;IAC1B,cAAc,EAAE,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAA;IACxD,uBAAuB,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;CAC9D,CAAA;AAED,KAAK,2BAA2B,CAAC,cAAc,IAAI;IACjD,OAAO,EAAE,oBAAoB,CAAA;IAC7B,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;;OAMG;IACH,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,wEAAwE;IACxE,MAAM,EAAE,CAAC,CAAC,aAAa,CAAC,cAAc,CAAC,CAAA;CACxC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,GAAI,cAAc,EAAE,mDAKrD,2BAA2B,CAAC,cAAc,CAAC,KAAG,cAgChD,CAAA"}