@skmtc/core 0.27.0 → 0.28.0

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"}

package/script/enrichments/parseEnrichmentUmbrella.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * @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
+ */
+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.parseEnrichmentUmbrella = void 0;
+const v = __importStar(require("valibot"));
+const Enrichments_js_1 = require("../types/Enrichments.js");
+const findUnknownKeys_js_1 = require("./findUnknownKeys.js");
+const EnrichmentWarning_js_1 = require("./EnrichmentWarning.js");
+/**
+ * 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).
+ */
+const parseEnrichmentUmbrella = ({ context, generatorId, subjectSegments, schema }) => {
+    const raw = {
+        subject: context.readEnrichment([generatorId, ...subjectSegments]),
+        generator: context.readEnrichment([generatorId, Enrichments_js_1.GENERATOR_ENRICHMENT_KEY]),
+        stack: context.readEnrichment([Enrichments_js_1.STACK_ENRICHMENT_KEY])
+    };
+    // Diff the generator-owned scopes against the schema (stack excluded —
+    // shared bag). Walking the umbrella keeps the scope schemas attributed
+    // without reaching into the composite's entries.
+    const unknownKeys = (0, findUnknownKeys_js_1.findUnknownKeys)(schema, { subject: raw.subject, generator: raw.generator });
+    for (const { path, suggestion } of unknownKeys) {
+        const [scope, ...leafPath] = path;
+        const routingPath = scope === 'subject'
+            ? [generatorId, ...subjectSegments, ...leafPath]
+            : [generatorId, Enrichments_js_1.GENERATOR_ENRICHMENT_KEY, ...leafPath];
+        context.reportEnrichmentWarning({
+            level: 'warning',
+            type: 'UNKNOWN_ENRICHMENT_KEY',
+            path: routingPath,
+            message: `unknown enrichment key '${routingPath[routingPath.length - 1]}' at ` +
+                `'${(0, EnrichmentWarning_js_1.formatEnrichmentPath)(routingPath.slice(0, -1))}' — ignored` +
+                (suggestion !== undefined ? ` (did you mean '${suggestion}'?)` : ''),
+            ...(suggestion !== undefined ? { suggestion } : {})
+        });
+    }
+    return v.parse(schema, raw);
+};
+exports.parseEnrichmentUmbrella = parseEnrichmentUmbrella;

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

@@ -1 +1 @@
-{"version":3,"file":"toEnrichmentDescriptor.d.ts","sourceRoot":"","sources":["../../src/enrichments/toEnrichmentDescriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,CAAC,MAAM,SAAS,CAAA;AAGjC;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAA;IACX,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IACE,IAAI,EAAE,QAAQ,CAAA;IACd,8BAA8B;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB,GACD;IACE,IAAI,EAAE,cAAc,CAAA;IACpB;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAA;CACnB,GACD;IACE,IAAI,EAAE,OAAO,CAAA;IACb,0BAA0B;IAC1B,IAAI,EAAE,eAAe,CAAA;CACtB,GACD;IACE,IAAI,EAAE,QAAQ,CAAA;IACd,kCAAkC;IAClC,MAAM,EAAE,eAAe,EAAE,CAAA;CAC1B,CAAA;AAEL;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,oBAAoB,CAAA;AAExE,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;AAEzD,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAA;AAE3D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,WAAW,CAAA;IACxB;;;;;OAKG;IACH,eAAe,EAAE,OAAO,CAAA;IACxB,MAAM,EAAE,eAAe,EAAE,CAAA;CAC1B,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,OAAO,GAAG,SAAS,CAAA;IACpE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC,CAAC,aAAa,CAAA;IACnD;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAA;CACxC,CAAA;AAqJD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,CAAC,CAAC,aAAa,GAAG,SAAS,KAAG,eAAe,EAKvF,CAAA;AAsBD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,gBAAgB,KAAG,oBAK/D,CAAA"}
+{"version":3,"file":"toEnrichmentDescriptor.d.ts","sourceRoot":"","sources":["../../src/enrichments/toEnrichmentDescriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,CAAC,MAAM,SAAS,CAAA;AAUjC;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAA;IACX,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IACE,IAAI,EAAE,QAAQ,CAAA;IACd,8BAA8B;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB,GACD;IACE,IAAI,EAAE,cAAc,CAAA;IACpB;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAA;CACnB,GACD;IACE,IAAI,EAAE,OAAO,CAAA;IACb,0BAA0B;IAC1B,IAAI,EAAE,eAAe,CAAA;CACtB,GACD;IACE,IAAI,EAAE,QAAQ,CAAA;IACd,kCAAkC;IAClC,MAAM,EAAE,eAAe,EAAE,CAAA;CAC1B,CAAA;AAEL;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,oBAAoB,CAAA;AAExE,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;AAEzD,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAA;AAE3D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,WAAW,CAAA;IACxB;;;;;OAKG;IACH,eAAe,EAAE,OAAO,CAAA;IACxB,MAAM,EAAE,eAAe,EAAE,CAAA;CAC1B,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,OAAO,GAAG,SAAS,CAAA;IACpE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC,CAAC,aAAa,CAAA;IACnD;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAA;CACxC,CAAA;AAwGD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,CAAC,CAAC,aAAa,GAAG,SAAS,KAAG,eAAe,EAKvF,CAAA;AAsBD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,gBAAgB,KAAG,oBAK/D,CAAA"}

package/script/enrichments/toEnrichmentDescriptor.js

@@ -2,27 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toEnrichmentDescriptor = exports.toEnrichmentFields = void 0;
 const ModuleSelect_js_1 = require("../types/ModuleSelect.js");
-const isValibotSchema = (input) => typeof input === 'object' &&
-    input !== null &&
-    'type' in input &&
-    typeof input.type === 'string';
-const isEntriesRecord = (input) => typeof input === 'object' && input !== null;
+const valibotShape_js_1 = require("./valibotShape.js");
 const isOptionsArray = (input) => Array.isArray(input);
-const WRAPPER_TYPES = new Set(['optional', 'nullable', 'nullish']);
-const unwrap = (schema) => {
-    if (WRAPPER_TYPES.has(schema.type) && isValibotSchema(schema.wrapped)) {
-        return { inner: schema.wrapped, optional: true };
-    }
-    return { inner: schema, optional: false };
-};
-/**
- * A `v.pipe(base, …actions)` schema spreads `base` and adds a `pipe` array
- * whose first element IS the original base schema. The `moduleSelect`
- * registry lookup must therefore also check the pipe's base, or piping a
- * moduleSelect through metadata (`v.title(…)`) would silently demote it to
- * a generic object widget.
- */
-const baseOf = (schema) => Array.isArray(schema.pipe) && isValibotSchema(schema.pipe[0]) ? schema.pipe[0] : schema;
 /** The `v.title(…)` metadata riding a piped schema, if any — the field label. */
 const titleOf = (schema) => {
     if (!Array.isArray(schema.pipe))
@@ -49,7 +30,7 @@ const titleOf = (schema) => {
  * rule is structural — it names no scope, so it composes with the generic
  * object walk rather than special-casing `subject` / `generator` / `stack`.
  */
-const isOmittedMember = (rawSchema) => isValibotSchema(rawSchema) && unwrap(rawSchema).inner.type === 'undefined';
+const isOmittedMember = (rawSchema) => (0, valibotShape_js_1.isValibotSchema)(rawSchema) && (0, valibotShape_js_1.unwrap)(rawSchema).inner.type === 'undefined';
 const toLabel = (key) => {
     if (key === '')
         return '';
@@ -57,7 +38,7 @@ const toLabel = (key) => {
     return spaced.charAt(0).toUpperCase() + spaced.slice(1);
 };
 const typeFor = (schema) => {
-    const moduleType = (0, ModuleSelect_js_1.moduleTypeOf)(schema) ?? (0, ModuleSelect_js_1.moduleTypeOf)(baseOf(schema));
+    const moduleType = (0, ModuleSelect_js_1.moduleTypeOf)(schema) ?? (0, ModuleSelect_js_1.moduleTypeOf)((0, valibotShape_js_1.baseOf)(schema));
     if (moduleType !== undefined) {
         return { type: 'moduleSelect', moduleType };
     }
@@ -73,14 +54,14 @@ const typeFor = (schema) => {
             return { type: 'select', options: opts };
         }
         case 'object': {
-            const entries = isEntriesRecord(schema.entries) ? schema.entries : {};
+            const entries = (0, valibotShape_js_1.isEntriesRecord)(schema.entries) ? schema.entries : {};
             return {
                 type: 'object',
                 fields: walkEntries(entries)
             };
         }
         case 'array': {
-            if (isValibotSchema(schema.item)) {
+            if ((0, valibotShape_js_1.isValibotSchema)(schema.item)) {
                 return { type: 'array', item: walkFromShape('', schema.item) };
             }
             // An unrecognisable item schema degrades to a text item — consistent
@@ -92,14 +73,14 @@ const typeFor = (schema) => {
     }
 };
 const walkFromShape = (key, rawSchema) => {
-    const { inner, optional } = unwrap(rawSchema);
+    const { inner, optional } = (0, valibotShape_js_1.unwrap)(rawSchema);
     // A `v.title(…)` label wins over the key-derived one; the title may ride
     // the schema itself or sit inside an optional wrapper.
     const label = titleOf(inner) ?? titleOf(rawSchema) ?? toLabel(key);
     return { key, label, optional, ...typeFor(inner) };
 };
 const walkField = (key, rawSchema) => {
-    if (!isValibotSchema(rawSchema)) {
+    if (!(0, valibotShape_js_1.isValibotSchema)(rawSchema)) {
         return { key, label: toLabel(key), optional: false, type: 'text' };
     }
     return walkFromShape(key, rawSchema);
@@ -134,10 +115,10 @@ const walkEntries = (entries) => Object.keys(entries)
  * when only the field shape is needed.
  */
 const toEnrichmentFields = (schema) => {
-    if (!isValibotSchema(schema))
+    if (!(0, valibotShape_js_1.isValibotSchema)(schema))
         return [];
-    const { inner } = unwrap(schema);
-    if (inner.type !== 'object' || !isEntriesRecord(inner.entries))
+    const { inner } = (0, valibotShape_js_1.unwrap)(schema);
+    if (inner.type !== 'object' || !(0, valibotShape_js_1.isEntriesRecord)(inner.entries))
         return [];
     return walkEntries(inner.entries);
 };

package/script/enrichments/valibotShape.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Structural view of Valibot schemas as observed at runtime.
+ *
+ * Valibot's declared `GenericSchema` is opaque (intentionally a black box
+ * for parse calls) but the runtime objects expose tagged-union shape via
+ * `type` plus the wrapper / container properties below. The walkers that
+ * traverse generator enrichment schemas — `toEnrichmentDescriptor` (form
+ * projection) and `findUnknownKeys` (dropped-key detection) — narrow into
+ * this view once at each entry point and stay inside it.
+ *
+ * @module valibotShape
+ */
+import type * as v from 'valibot';
+/**
+ * The runtime shape of a Valibot schema node. `wrapped` carries the inner
+ * schema of `optional` / `nullable` / `nullish` wrappers; `entries` the
+ * member schemas of an `object`; `item` an `array`'s element schema;
+ * `key` / `value` a `record`'s key and value schemas; `options` a
+ * `picklist` / union's choices; `pipe` a `v.pipe(...)`'s action chain
+ * (whose first element is the base schema).
+ */
+export type ValibotSchemaShape = {
+    readonly type: string;
+    readonly wrapped?: unknown;
+    readonly entries?: unknown;
+    readonly item?: unknown;
+    readonly key?: unknown;
+    readonly value?: unknown;
+    readonly options?: unknown;
+    readonly pipe?: unknown;
+};
+export declare const isValibotSchema: (input: unknown) => input is ValibotSchemaShape;
+export declare const isEntriesRecord: (input: unknown) => input is Record<string, v.GenericSchema>;
+/**
+ * Strip a single `optional` / `nullable` / `nullish` wrapper, reporting
+ * whether one was present. Wrappers don't nest in practice (a schema is
+ * declared optional once), so one level suffices.
+ */
+export declare const unwrap: (schema: ValibotSchemaShape) => {
+    inner: ValibotSchemaShape;
+    optional: boolean;
+};
+/**
+ * A `v.pipe(base, …actions)` schema spreads `base` and adds a `pipe` array
+ * whose first element IS the original base schema. Lookups keyed on schema
+ * *identity* (e.g. the `moduleSelect` registry) must therefore also check
+ * the pipe's base, or piping a schema through metadata (`v.title(…)`)
+ * would silently break the lookup.
+ */
+export declare const baseOf: (schema: ValibotSchemaShape) => ValibotSchemaShape;
+//# sourceMappingURL=valibotShape.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"valibotShape.d.ts","sourceRoot":"","sources":["../../src/enrichments/valibotShape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,KAAK,CAAC,MAAM,SAAS,CAAA;AAEjC;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,kBAIH,CAAA;AAEvD,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,aAAa,CAC3C,CAAA;AAI7C;;;;GAIG;AACH,eAAO,MAAM,MAAM,GACjB,QAAQ,kBAAkB,KACzB;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAKhD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,QAAQ,kBAAkB,KAAG,kBACqC,CAAA"}

package/script/enrichments/valibotShape.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * @fileoverview Structural view of Valibot schemas as observed at runtime.
+ *
+ * Valibot's declared `GenericSchema` is opaque (intentionally a black box
+ * for parse calls) but the runtime objects expose tagged-union shape via
+ * `type` plus the wrapper / container properties below. The walkers that
+ * traverse generator enrichment schemas — `toEnrichmentDescriptor` (form
+ * projection) and `findUnknownKeys` (dropped-key detection) — narrow into
+ * this view once at each entry point and stay inside it.
+ *
+ * @module valibotShape
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.baseOf = exports.unwrap = exports.isEntriesRecord = exports.isValibotSchema = void 0;
+const isValibotSchema = (input) => typeof input === 'object' &&
+    input !== null &&
+    'type' in input &&
+    typeof input.type === 'string';
+exports.isValibotSchema = isValibotSchema;
+const isEntriesRecord = (input) => typeof input === 'object' && input !== null;
+exports.isEntriesRecord = isEntriesRecord;
+const WRAPPER_TYPES = new Set(['optional', 'nullable', 'nullish']);
+/**
+ * Strip a single `optional` / `nullable` / `nullish` wrapper, reporting
+ * whether one was present. Wrappers don't nest in practice (a schema is
+ * declared optional once), so one level suffices.
+ */
+const unwrap = (schema) => {
+    if (WRAPPER_TYPES.has(schema.type) && (0, exports.isValibotSchema)(schema.wrapped)) {
+        return { inner: schema.wrapped, optional: true };
+    }
+    return { inner: schema, optional: false };
+};
+exports.unwrap = unwrap;
+/**
+ * A `v.pipe(base, …actions)` schema spreads `base` and adds a `pipe` array
+ * whose first element IS the original base schema. Lookups keyed on schema
+ * *identity* (e.g. the `moduleSelect` registry) must therefore also check
+ * the pipe's base, or piping a schema through metadata (`v.title(…)`)
+ * would silently break the lookup.
+ */
+const baseOf = (schema) => Array.isArray(schema.pipe) && (0, exports.isValibotSchema)(schema.pipe[0]) ? schema.pipe[0] : schema;
+exports.baseOf = baseOf;

package/script/helpers/nearestKey.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Nearest-key suggestion for "did you mean …?" hints.
+ *
+ * Used by the enrichment validation surfaces (`EnrichmentAudit`,
+ * `findUnknownKeys`) to pair an unrecognized key with its closest known
+ * sibling. Pure string utility — no context, no schema awareness.
+ *
+ * @module nearestKey
+ */
+/**
+ * The candidate closest to `target`, or `undefined` when nothing is close
+ * enough to be a plausible typo. A case-only mismatch (`POST` for `post`)
+ * always wins; otherwise candidates compete within a small edit-distance
+ * budget (1 for short keys, 2 otherwise). An exact match returns
+ * `undefined` — a key that exists needs no suggestion.
+ */
+export declare const nearestKey: (target: string, candidates: Iterable<string>) => string | undefined;
+//# sourceMappingURL=nearestKey.d.ts.map

package/script/helpers/nearestKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nearestKey.d.ts","sourceRoot":"","sources":["../../src/helpers/nearestKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+BH;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,YAAY,QAAQ,CAAC,MAAM,CAAC,KAAG,MAAM,GAAG,SAmBlF,CAAA"}