@nekostack/schema 1.0.0

package/dist/src/generators/zod-mapping.js

@@ -0,0 +1,174 @@
+/**
+ * Shared Zod semantic mapping (Decision #6 of v0.6 plan).
+ *
+ * One module owns:
+ *   - the IR traversal order
+ *   - the fixed Zod modifier-application order (v0.2 contract — see
+ *     `docs/ZOD_MODIFIER_ORDERING.md`):
+ *
+ *       1. base schema
+ *       2. portable refinements (IR insertion order)
+ *       3. describe
+ *       4. nullable / optional / nullish (mutually exclusive)
+ *       5. default (LAST)
+ *
+ *   - the rules for empty / single / all-string / mixed enums
+ *   - the rules for the `unknownKeys` object policy
+ *
+ * Two consumers realize this mapping into different concrete outputs:
+ *
+ *   - `src/generators/zod.ts` (a `ZodEmitter<string>`) produces the
+ *     deterministic TypeScript source text. v0.2 snapshot bytes must
+ *     remain identical after this extraction.
+ *
+ *   - `src/runtime/zod-compile.ts` (a `ZodEmitter<ZodTypeAny>`) produces
+ *     a live Zod schema value for runtime `parse` / `safeParse` /
+ *     `validate`.
+ *
+ * The shared mapping is the contract; neither consumer stringifies the
+ * other's output (no `eval`, no source-to-value parsing, no
+ * value-to-source serialization).
+ */
+import { UnsupportedNodeKindError } from "./errors.js";
+/**
+ * Entry point: walk a `SchemaNode` and produce the consumer's `T`.
+ *
+ * `depth` is threaded for the string consumer's indentation. Callers
+ * outside this module should start at depth 0.
+ */
+export function emit(node, depth, emitter) {
+    let expr = emitBase(node, depth, emitter);
+    expr = applyPortableRefinements(expr, node.refinements ?? [], emitter);
+    expr = applyDescribeStep(expr, node, emitter);
+    expr = applyAbsenceModifiers(expr, node, emitter);
+    expr = applyDefaultStep(expr, node, emitter);
+    return expr;
+}
+function emitBase(node, depth, emitter) {
+    switch (node.kind) {
+        case "string":
+            return emitter.stringBase();
+        case "number":
+            return emitter.numberBase();
+        case "boolean":
+            return emitter.booleanBase();
+        case "literal":
+            return emitter.literalBase(node.value);
+        case "enum":
+            return emitEnum(node, emitter);
+        case "array":
+            return emitter.arrayBase(emit(node.element, depth + 1, emitter));
+        case "object":
+            return emitObject(node, depth, emitter);
+        default:
+            throw new UnsupportedNodeKindError({
+                kind: node.kind,
+                generator: "zod",
+            });
+    }
+}
+function emitEnum(node, emitter) {
+    // Empty enums should be rejected at the builder (`s.enum`); fail
+    // loudly if one ever reaches here so we never emit invalid Zod.
+    if (node.values.length === 0) {
+        throw new Error("Cannot emit Zod for an empty enum");
+    }
+    const allStrings = node.values.every((v) => typeof v === "string");
+    if (allStrings) {
+        return emitter.enumStringsBase(node.values);
+    }
+    // z.union requires >= 2 options; a single-value mixed/numeric enum
+    // collapses to z.literal.
+    if (node.values.length === 1) {
+        return emitter.enumSingleLiteralBase(node.values[0]);
+    }
+    return emitter.enumUnionBase(node.values);
+}
+function emitObject(node, depth, emitter) {
+    const entries = Object.entries(node.fields).map(([key, field]) => [key, emit(field, depth + 1, emitter)]);
+    return emitter.applyUnknownKeys(emitter.objectBase(entries, depth), node.unknownKeys);
+}
+function applyPortableRefinements(expr, refinements, emitter) {
+    let out = expr;
+    for (const r of refinements) {
+        if (r.kind === "runtime") {
+            // Invariant 7: fail loudly. Silently dropping a runtime refinement
+            // would emit a chain that accepts inputs the IR intends to reject.
+            throw new UnsupportedNodeKindError({
+                kind: "runtimeRefinement",
+                generator: "zod",
+            });
+        }
+        if (r.kind !== "portable")
+            continue;
+        out = applyPortableRefinement(out, r, emitter);
+    }
+    return out;
+}
+function applyPortableRefinement(expr, r, emitter) {
+    const params = r.params ?? {};
+    switch (r.name) {
+        case "minLength":
+            return emitter.applyMinLength(expr, numParam(params.value));
+        case "maxLength":
+            return emitter.applyMaxLength(expr, numParam(params.value));
+        case "length":
+            return emitter.applyLength(expr, numParam(params.value));
+        case "regex":
+            return emitter.applyRegex(expr, String(params.source ?? ""), String(params.flags ?? ""));
+        case "email":
+            return emitter.applyEmail(expr);
+        case "uuid":
+            return emitter.applyUuid(expr);
+        case "url":
+            return emitter.applyUrl(expr);
+        case "int":
+            return emitter.applyInt(expr);
+        case "min":
+            return emitter.applyMin(expr, numParam(params.value));
+        case "max":
+            return emitter.applyMax(expr, numParam(params.value));
+        case "gt":
+            return emitter.applyGt(expr, numParam(params.value));
+        case "lt":
+            return emitter.applyLt(expr, numParam(params.value));
+        case "multipleOf":
+            return emitter.applyMultipleOf(expr, numParam(params.value));
+        case "minItems":
+            return emitter.applyMinItems(expr, numParam(params.value));
+        case "maxItems":
+            return emitter.applyMaxItems(expr, numParam(params.value));
+    }
+}
+function applyDescribeStep(expr, node, emitter) {
+    const desc = node.metadata?.description;
+    if (!desc)
+        return expr;
+    return emitter.applyDescribe(expr, desc);
+}
+function applyAbsenceModifiers(expr, node, emitter) {
+    const mods = node.modifiers ?? {};
+    // Mutually exclusive — `.optional().nullable()` would produce a
+    // different Zod type than `.nullish()` despite the surface
+    // similarity.
+    if (mods.optional && mods.nullable)
+        return emitter.applyNullish(expr);
+    if (mods.nullable)
+        return emitter.applyNullable(expr);
+    if (mods.optional)
+        return emitter.applyOptional(expr);
+    return expr;
+}
+function applyDefaultStep(expr, node, emitter) {
+    const def = node.modifiers?.default;
+    if (!def)
+        return expr;
+    return emitter.applyDefault(expr, def.value);
+}
+function numParam(value) {
+    if (typeof value !== "number") {
+        throw new Error(`Expected numeric refinement param, got ${typeof value}`);
+    }
+    return value;
+}
+//# sourceMappingURL=zod-mapping.js.map

package/dist/src/generators/zod-mapping.js.map

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

package/dist/src/generators/zod.d.ts

@@ -0,0 +1,17 @@
+import type { SchemaNode } from "../ir/nodes.js";
+import type { ZodGeneratorOptions } from "./types.js";
+/**
+ * Generate Zod 3.x schema code from a SchemaNode.
+ *
+ * Output is a complete TS module: header + `import { z } from "zod"` +
+ * `export const <name> = <chain>;`.
+ *
+ * The per-node semantic mapping and modifier-application order live in
+ * [`zod-mapping.ts`](./zod-mapping.ts) — see that file's header for the
+ * v0.2 modifier-ordering contract. This file is the **string consumer**:
+ * it realizes each op as TypeScript source text. The runtime compiler
+ * in `src/runtime/zod-compile.ts` is the value consumer. They share
+ * the mapping; neither converts the other's output.
+ */
+export declare function generateZod(node: SchemaNode, options?: ZodGeneratorOptions): string;
+//# sourceMappingURL=zod.d.ts.map

package/dist/src/generators/zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../../../src/generators/zod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,UAAU,EAEX,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGtD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,mBAAwB,GAChC,MAAM,CAkBR"}

package/dist/src/generators/zod.js

@@ -0,0 +1,118 @@
+import { buildHeader } from "./header.js";
+import { emit } from "./zod-mapping.js";
+/**
+ * Generate Zod 3.x schema code from a SchemaNode.
+ *
+ * Output is a complete TS module: header + `import { z } from "zod"` +
+ * `export const <name> = <chain>;`.
+ *
+ * The per-node semantic mapping and modifier-application order live in
+ * [`zod-mapping.ts`](./zod-mapping.ts) — see that file's header for the
+ * v0.2 modifier-ordering contract. This file is the **string consumer**:
+ * it realizes each op as TypeScript source text. The runtime compiler
+ * in `src/runtime/zod-compile.ts` is the value consumer. They share
+ * the mapping; neither converts the other's output.
+ */
+export function generateZod(node, options = {}) {
+    const constName = options.constName ?? "schema";
+    const header = buildHeader(node, {
+        generator: "zod",
+        ...(options.sourceHash !== undefined
+            ? { sourceHash: options.sourceHash }
+            : {}),
+    });
+    const chain = emit(node, /*depth*/ 0, stringEmitter);
+    const doc = emitTopLevelDocComment(node);
+    return [
+        header,
+        "",
+        `import { z } from "zod";`,
+        "",
+        `${doc}export const ${constName} = ${chain};`,
+        "",
+    ].join("\n");
+}
+// ---------- string consumer ----------
+const stringEmitter = {
+    stringBase: () => "z.string()",
+    numberBase: () => "z.number()",
+    booleanBase: () => "z.boolean()",
+    literalBase: (value) => `z.literal(${formatJson(value)})`,
+    enumStringsBase: (values) => {
+        const list = values.map((v) => JSON.stringify(v)).join(", ");
+        return `z.enum([${list}] as const)`;
+    },
+    enumSingleLiteralBase: (value) => `z.literal(${formatJson(value)})`,
+    enumUnionBase: (values) => {
+        const parts = values.map((v) => `z.literal(${formatJson(v)})`);
+        return `z.union([${parts.join(", ")}])`;
+    },
+    arrayBase: (element) => `z.array(${element})`,
+    objectBase: (fields, depth) => {
+        if (fields.length === 0)
+            return "z.object({})";
+        const indent = "  ".repeat(depth + 1);
+        const closeIndent = "  ".repeat(depth);
+        const lines = fields.map(([key, value]) => {
+            const safeKey = isSafeIdentifier(key) ? key : JSON.stringify(key);
+            return `${indent}${safeKey}: ${value},`;
+        });
+        return `z.object({\n${lines.join("\n")}\n${closeIndent}})`;
+    },
+    applyUnknownKeys: (prev, policy) => {
+        // Zod's default is "strip"; emit the explicit modifier so the
+        // generated code is unambiguous about which policy applies.
+        switch (policy) {
+            case "strict":
+                return `${prev}.strict()`;
+            case "stripUnknown":
+                return `${prev}.strip()`;
+            case "passthrough":
+                return `${prev}.passthrough()`;
+            default:
+                return assertUnreachable(policy);
+        }
+    },
+    applyMinLength: (prev, value) => `${prev}.min(${value})`,
+    applyMaxLength: (prev, value) => `${prev}.max(${value})`,
+    applyLength: (prev, value) => `${prev}.length(${value})`,
+    applyRegex: (prev, source, flags) => `${prev}.regex(new RegExp(${JSON.stringify(source)}, ${JSON.stringify(flags)}))`,
+    applyEmail: (prev) => `${prev}.email()`,
+    applyUuid: (prev) => `${prev}.uuid()`,
+    applyUrl: (prev) => `${prev}.url()`,
+    applyInt: (prev) => `${prev}.int()`,
+    applyMin: (prev, value) => `${prev}.min(${value})`,
+    applyMax: (prev, value) => `${prev}.max(${value})`,
+    applyGt: (prev, value) => `${prev}.gt(${value})`,
+    applyLt: (prev, value) => `${prev}.lt(${value})`,
+    applyMultipleOf: (prev, value) => `${prev}.multipleOf(${value})`,
+    applyMinItems: (prev, value) => `${prev}.min(${value})`,
+    applyMaxItems: (prev, value) => `${prev}.max(${value})`,
+    applyDescribe: (prev, text) => `${prev}.describe(${JSON.stringify(text)})`,
+    applyNullable: (prev) => `${prev}.nullable()`,
+    applyOptional: (prev) => `${prev}.optional()`,
+    applyNullish: (prev) => `${prev}.nullish()`,
+    applyDefault: (prev, value) => `${prev}.default(${formatJson(value)})`,
+};
+// ---------- string-only helpers ----------
+function emitTopLevelDocComment(node) {
+    // `metadata.deprecated` is a source-level JSDoc concern; Zod has no
+    // runtime "deprecated" marker, so the runtime value consumer ignores
+    // it entirely.
+    const lines = [];
+    if (node.metadata?.deprecated)
+        lines.push("@deprecated");
+    if (lines.length === 0)
+        return "";
+    return `/**\n${lines.map((l) => ` * ${l}`).join("\n")}\n */\n`;
+}
+function formatJson(value) {
+    return JSON.stringify(value);
+}
+function isSafeIdentifier(s) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(s);
+}
+function assertUnreachable(value) {
+    throw new Error(`Unreachable: unknown unknownKeys policy ${String(value)}`);
+}
+//# sourceMappingURL=zod.js.map

package/dist/src/generators/zod.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,21 @@
+export { s } from "./builders/s.js";
+export { Schema, type AnySchema } from "./builders/schema.js";
+export type { ArraySchema } from "./builders/array.js";
+export type { ObjectSchema } from "./builders/object.js";
+export type { BooleanSchema, EnumSchema, LiteralSchema, NumberSchema, StringSchema, } from "./builders/primitives.js";
+export type { ArrayNode, BooleanNode, EnumNode, JsonValue, LiteralNode, NumberNode, ObjectNode, SchemaNode, StringNode, } from "./ir/nodes.js";
+export { serializeIR } from "./ir/serialize.js";
+export { irHash } from "./ir/hash.js";
+export { generateTypeScript } from "./generators/ts.js";
+export { generateZod } from "./generators/zod.js";
+export { generateJsonSchema } from "./generators/json-schema.js";
+export { generateOpenApiSchemaComponent } from "./generators/openapi.js";
+export type { GeneratorOptions, JsonSchemaGeneratorOptions, OpenApiGeneratorOptions, TypeScriptGeneratorOptions, ZodGeneratorOptions, } from "./generators/types.js";
+export { GENERATOR_VERSION } from "./generators/version.js";
+export { UnsupportedNodeKindError } from "./generators/errors.js";
+export { ISSUE_CODES, type Issue, type IssueCode, type IssuePath, type Result, } from "./errors/issue.js";
+export type { Infer, Input, Output } from "./types.js";
+export type { Mask, OverrideMask, MergeOptions } from "./types.js";
+export { parse, safeParse, validate } from "./runtime/parse.js";
+export { ParseError } from "./runtime/errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAGpC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAK9D,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EACV,aAAa,EACb,UAAU,EACV,aAAa,EACb,YAAY,EACZ,YAAY,GACb,MAAM,0BAA0B,CAAC;AAOlC,YAAY,EACV,SAAS,EACT,WAAW,EACX,QAAQ,EACR,SAAS,EACT,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,GACX,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAatC,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AACzE,YAAY,EACV,gBAAgB,EAChB,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAGlE,OAAO,EACL,WAAW,EACX,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,MAAM,GACZ,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAQvD,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAWnE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,43 @@
+// =============================================================================
+// Public API — @nekostack/schema v0.5
+//
+// Surface is intentionally narrow. Anything not re-exported here is package-
+// internal and may change without a major version bump. See docs/SCOPE.md.
+// =============================================================================
+// ---- DSL entry point ----
+export { s } from "./builders/s.js";
+// ---- Base schema (for generic constraints) ----
+export { Schema } from "./builders/schema.js";
+export { serializeIR } from "./ir/serialize.js";
+export { irHash } from "./ir/hash.js";
+// ---- Generators ----
+// Each generator consumes the canonical SchemaNode IR and returns a complete
+// emit-ready artifact as a string. File-writing is intentionally a downstream
+// concern.
+//   - generateTypeScript / generateZod emit TS-source artifacts (header
+//     comment + body code).
+//   - generateJsonSchema / generateOpenApiSchemaComponent emit JSON artifacts
+//     (provenance is embedded via the `x-nekostack` extension object — JSON
+//     has no comment syntax).
+// See docs/USAGE.md for per-generator details and docs/{HEADER_FORMAT,
+// JSON_SCHEMA_MAPPING, OPENAPI_MAPPING}.md for the per-format contracts.
+export { generateTypeScript } from "./generators/ts.js";
+export { generateZod } from "./generators/zod.js";
+export { generateJsonSchema } from "./generators/json-schema.js";
+export { generateOpenApiSchemaComponent } from "./generators/openapi.js";
+export { GENERATOR_VERSION } from "./generators/version.js";
+export { UnsupportedNodeKindError } from "./generators/errors.js";
+// ---- Errors ----
+export { ISSUE_CODES, } from "./errors/issue.js";
+// ---- Runtime validation (v0.6) ----
+// Three free-function entry points + one error class. See `docs/RUNTIME.md`
+// for the full contract — default semantics, unknown-key policies, issue
+// normalization, the validate-only IR variant, and the engine-swap-safe
+// invariant that keeps Zod internal. The compile cache, the
+// validate-variant cache, the Zod source-vs-runtime semantic mapping, and
+// the `ZodError → Issue[]` normalizer are intentionally NOT re-exported:
+// they are implementation surface that v0.7+ may rework without a major
+// version bump.
+export { parse, safeParse, validate } from "./runtime/parse.js";
+export { ParseError } from "./runtime/errors.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,sCAAsC;AACtC,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,gFAAgF;AAEhF,4BAA4B;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAEpC,kDAAkD;AAClD,OAAO,EAAE,MAAM,EAAkB,MAAM,sBAAsB,CAAC;AAgC9D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,uBAAuB;AACvB,6EAA6E;AAC7E,8EAA8E;AAC9E,WAAW;AACX,wEAAwE;AACxE,4BAA4B;AAC5B,8EAA8E;AAC9E,4EAA4E;AAC5E,8BAA8B;AAC9B,uEAAuE;AACvE,yEAAyE;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AAQzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAElE,mBAAmB;AACnB,OAAO,EACL,WAAW,GAKZ,MAAM,mBAAmB,CAAC;AAa3B,sCAAsC;AACtC,4EAA4E;AAC5E,yEAAyE;AACzE,wEAAwE;AACxE,4DAA4D;AAC5D,0EAA0E;AAC1E,yEAAyE;AACzE,wEAAwE;AACxE,gBAAgB;AAChB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/ir/hash.d.ts

@@ -0,0 +1,19 @@
+import type { SchemaNode } from "./nodes.js";
+/**
+ * Stable, content-addressed hash of a SchemaNode's canonical IR. Two
+ * structurally identical IRs always produce the same hash; any semantic
+ * change to the IR produces a different one.
+ *
+ * Algorithm: `sha256(serializeIR(node))` over UTF-8 bytes, hex-encoded.
+ *
+ * Consumed by:
+ *  - Generated-file headers (v0.2+) — proves a generated artifact was
+ *    produced from a specific IR.
+ *  - The v0.7 CLI freshness check — `neko schema check` re-derives the
+ *    hash from current source and compares against the committed header.
+ *
+ * This helper deliberately does NOT compute `sourceHash`. That requires
+ * knowing the source file (path + bytes), which is a CLI concern.
+ */
+export declare function irHash(node: SchemaNode): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/src/ir/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/ir/hash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAE/C"}

package/dist/src/ir/hash.js

@@ -0,0 +1,22 @@
+import { createHash } from "node:crypto";
+import { serializeIR } from "./serialize.js";
+/**
+ * Stable, content-addressed hash of a SchemaNode's canonical IR. Two
+ * structurally identical IRs always produce the same hash; any semantic
+ * change to the IR produces a different one.
+ *
+ * Algorithm: `sha256(serializeIR(node))` over UTF-8 bytes, hex-encoded.
+ *
+ * Consumed by:
+ *  - Generated-file headers (v0.2+) — proves a generated artifact was
+ *    produced from a specific IR.
+ *  - The v0.7 CLI freshness check — `neko schema check` re-derives the
+ *    hash from current source and compares against the committed header.
+ *
+ * This helper deliberately does NOT compute `sourceHash`. That requires
+ * knowing the source file (path + bytes), which is a CLI concern.
+ */
+export function irHash(node) {
+    return createHash("sha256").update(serializeIR(node), "utf8").digest("hex");
+}
+//# sourceMappingURL=hash.js.map

package/dist/src/ir/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../../src/ir/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,MAAM,CAAC,IAAgB;IACrC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/src/ir/nodes.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Canonical Intermediate Representation for NekoStack schemas.
+ *
+ * Every builder produces a `SchemaNode`. Generators consume only IR — never
+ * builder internals. This is the single contract that prevents drift between
+ * the TS, Zod, JSON Schema, and OpenAPI outputs.
+ *
+ * The IR is JSON-serializable (no functions, no symbols, no class instances).
+ * Runtime-only constructs (transforms, custom refinement predicates) are
+ * stored as opaque metadata; the registry that owns the predicate is the
+ * runtime, not the IR.
+ */
+export type SchemaNode = StringNode | NumberNode | BooleanNode | DateNode | LiteralNode | EnumNode | ArrayNode | ObjectNode | UnionNode | RecursiveRefNode | TransformNode;
+export interface NodeMetadata {
+    id?: string;
+    version?: string;
+    description?: string;
+    deprecated?: boolean;
+}
+export interface NodeModifiers {
+    optional?: boolean;
+    nullable?: boolean;
+    /**
+     * Stored as a serializable literal so the IR remains JSON-roundtrip-safe.
+     * Functions-as-defaults are explicitly disallowed in v0.1.
+     */
+    default?: {
+        value: JsonValue;
+    };
+}
+export type Refinement = PortableRefinement | RuntimeRefinement;
+/**
+ * A refinement representable in every output format (TS comments, Zod chain,
+ * JSON Schema keyword, OpenAPI schema).
+ */
+export interface PortableRefinement {
+    kind: "portable";
+    name: PortableRefinementName;
+    params?: Record<string, JsonValue>;
+}
+export type PortableRefinementName = "minLength" | "maxLength" | "length" | "regex" | "email" | "uuid" | "url" | "int" | "min" | "max" | "gt" | "lt" | "multipleOf" | "minItems" | "maxItems";
+/**
+ * A custom predicate only the runtime can evaluate. Non-runtime outputs
+ * (JSON Schema, OpenAPI) MUST emit semantic-loss metadata when present.
+ */
+export interface RuntimeRefinement {
+    kind: "runtime";
+    /** Stable, machine-readable issue code emitted on failure. */
+    code: string;
+    description?: string;
+}
+interface NodeBase {
+    metadata?: NodeMetadata;
+    modifiers?: NodeModifiers;
+    refinements?: readonly Refinement[];
+}
+export interface StringNode extends NodeBase {
+    kind: "string";
+}
+export interface NumberNode extends NodeBase {
+    kind: "number";
+}
+export interface BooleanNode extends NodeBase {
+    kind: "boolean";
+}
+/**
+ * Date variants are explicit per the absence-of-ambiguity rule (no `s.date()`).
+ *  - isoDateTime: ISO 8601 string (default for APIs / config)
+ *  - isoDate:     YYYY-MM-DD string
+ *  - epochMs:     integer milliseconds since epoch
+ *  - dateObject:  runtime-only Date (never serialized)
+ *
+ * v0.1 declares the IR shape; builders ship in a later phase.
+ */
+export interface DateNode extends NodeBase {
+    kind: "date";
+    variant: "isoDateTime" | "isoDate" | "epochMs" | "dateObject";
+}
+export interface LiteralNode<T extends JsonValue = JsonValue> extends NodeBase {
+    kind: "literal";
+    value: T;
+}
+export interface EnumNode<T extends string | number = string | number> extends NodeBase {
+    kind: "enum";
+    values: readonly T[];
+}
+export interface ArrayNode extends NodeBase {
+    kind: "array";
+    element: SchemaNode;
+}
+export type UnknownKeysPolicy = "strict" | "stripUnknown" | "passthrough";
+export interface ObjectNode extends NodeBase {
+    kind: "object";
+    fields: Readonly<Record<string, SchemaNode>>;
+    unknownKeys: UnknownKeysPolicy;
+}
+export interface UnionNode extends NodeBase {
+    kind: "union";
+    options: readonly SchemaNode[];
+    /** When set, the union is discriminated by this field. */
+    discriminator?: string;
+}
+export interface RecursiveRefNode extends NodeBase {
+    kind: "recursiveRef";
+    /** Reverse-DNS schema id, e.g. "com.nekostack.auth.User". */
+    targetId: string;
+    /** Optional version pin; defaults to the latest registered. */
+    targetVersion?: string;
+}
+export interface TransformNode extends NodeBase {
+    kind: "transform";
+    source: SchemaNode;
+    /** Stable id of the transform; the runtime maps id → function. */
+    transformId: string;
+}
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export {};
+//# sourceMappingURL=nodes.d.ts.map

package/dist/src/ir/nodes.d.ts.map

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

package/dist/src/ir/nodes.js

@@ -0,0 +1,14 @@
+/**
+ * Canonical Intermediate Representation for NekoStack schemas.
+ *
+ * Every builder produces a `SchemaNode`. Generators consume only IR — never
+ * builder internals. This is the single contract that prevents drift between
+ * the TS, Zod, JSON Schema, and OpenAPI outputs.
+ *
+ * The IR is JSON-serializable (no functions, no symbols, no class instances).
+ * Runtime-only constructs (transforms, custom refinement predicates) are
+ * stored as opaque metadata; the registry that owns the predicate is the
+ * runtime, not the IR.
+ */
+export {};
+//# sourceMappingURL=nodes.js.map

package/dist/src/ir/nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.js","sourceRoot":"","sources":["../../../src/ir/nodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/src/ir/serialize.d.ts

@@ -0,0 +1,8 @@
+import type { SchemaNode } from "./nodes.js";
+/**
+ * Canonical JSON serialization of a SchemaNode: keys are sorted alphabetically
+ * at every level so two structurally identical IRs always produce byte-identical
+ * output. This is the input to `irHash` (computed in a later phase).
+ */
+export declare function serializeIR(node: SchemaNode): string;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/src/ir/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/ir/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEpD"}

package/dist/src/ir/serialize.js

@@ -0,0 +1,23 @@
+/**
+ * Canonical JSON serialization of a SchemaNode: keys are sorted alphabetically
+ * at every level so two structurally identical IRs always produce byte-identical
+ * output. This is the input to `irHash` (computed in a later phase).
+ */
+export function serializeIR(node) {
+    return JSON.stringify(canonicalize(node));
+}
+function canonicalize(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        const v = value[key];
+        if (v === undefined)
+            continue;
+        out[key] = canonicalize(v);
+    }
+    return out;
+}
+//# sourceMappingURL=serialize.js.map