@sincpro/client-framework 0.0.0-stage → 0.1.0

package/dist/codegen/domain.js

@@ -0,0 +1,195 @@
+import { claimed, contextOf, deprecationOf, docOf, headerOf, identifierOf, keyOf, localOf, sorted, } from "./names.js";
+/**
+ * The DTOs of a bounded context as TypeScript, out of the contract sincpro_framework exports:
+ * a type per model, per shared definition a model or an operation reaches, and per operation's
+ * input and answer. Only types — nothing in the file runs.
+ *
+ * Context: the file is a snapshot for whoever writes code — a person, or an agent reading the
+ * repository —, never the truth at runtime: the transport keeps reading the live definition and
+ * revalidates it by `model_version`. So it is written the same way for the same contract (every
+ * key sorted, byte for byte, which is what `make verify-client` compares) and never edited; an
+ * application extends a type by composition (`Wire & {…}`).
+ *
+ * criteria's grammar comes with every metamodel (`$defs.Criteria`); `@sincpro/criteria` already
+ * types it, so it is imported, never written a second time.
+ *
+ *     domainFileOf(JSON.parse(readFileSync("project.contract.json", "utf8")))
+ */
+const MODELS = "#/models/";
+const DEFINITIONS = "#/$defs/";
+/** A shared definition a package of the stack already types: imported, never written again. */
+const IMPORTED = {
+    Criteria: { name: "Criteria", from: "@sincpro/criteria" },
+};
+/** The field types whose value is the record itself, not a key that names it. */
+const RELATIONAL = new Set(["many2one", "one2many", "many2many", "embedded"]);
+/** A related record: in an answer only when the read expands it. */
+const EXPANDED = new Set(["many2one", "one2many", "many2many"]);
+const SIMPLE_TYPE = /^[A-Za-z0-9_$.]+$/;
+function union(members) {
+    const distinct = [...new Set(members)];
+    if (distinct.includes("unknown"))
+        return "unknown";
+    return distinct.join(" | ");
+}
+function arrayOf(item) {
+    return SIMPLE_TYPE.test(item) ? `${item}[]` : `Array<${item}>`;
+}
+/** Whose record a key names — `EntityID[Customer]` on the server —, said where it is written. */
+function keyNote(schema) {
+    const said = schema["x-sincpro"];
+    if (said?.relation == null || RELATIONAL.has(said.type ?? ""))
+        return undefined;
+    return `The key of a \`${said.relation}\`.`;
+}
+function scopeOf(metamodel) {
+    const definitions = metamodel.$defs ?? {};
+    const scope = {
+        reached: new Set(),
+        imports: new Set(),
+        refer: (ref) => {
+            const model = ref.startsWith(MODELS);
+            if (!model && !ref.startsWith(DEFINITIONS))
+                throw new Error(`"${ref}" points outside the metamodel of ${contextOf(metamodel)}`);
+            const name = ref.slice(model ? MODELS.length : DEFINITIONS.length);
+            // A model's own contract names a related model as a definition (`#/$defs/Run`).
+            if (model || name in metamodel.models) {
+                if (!(name in metamodel.models))
+                    throw new Error(`"${ref}" names no model of ${contextOf(metamodel)}`);
+                return identifierOf(name);
+            }
+            const imported = IMPORTED[name];
+            if (imported !== undefined) {
+                scope.imports.add(name);
+                return imported.name;
+            }
+            if (!(name in definitions))
+                throw new Error(`"${ref}" names no definition of ${contextOf(metamodel)}`);
+            scope.reached.add(name);
+            return identifierOf(name);
+        },
+    };
+    return scope;
+}
+/**
+ * Whether a property may be absent. In a record a model describes, every field comes but a
+ * related record, which comes only when the read expands it: the server writes the whole record,
+ * and its contract lists as required only what has no default (most fields have one). Anywhere
+ * else — an operation's input or answer, a shared definition — `required` says it.
+ */
+function optional(name, property, schema, record) {
+    if (record)
+        return EXPANDED.has(property["x-sincpro"]?.type ?? "");
+    return !(schema.required ?? []).includes(name);
+}
+function objectOf(schema, scope, depth, record) {
+    const properties = sorted(schema.properties ?? {});
+    if (properties.length === 0) {
+        const extra = schema.additionalProperties;
+        if (extra === false)
+            return "Record<string, never>";
+        const value = extra === undefined || extra === true ? "unknown" : typeOf(extra, scope, depth, record);
+        return `Record<string, ${value}>`;
+    }
+    const pad = "  ".repeat(depth + 1);
+    const lines = properties.map(([name, property]) => {
+        const doc = docOf([property.description, keyNote(property)], pad);
+        const mark = optional(name, property, schema, record) ? "?" : "";
+        return `${doc}${pad}${keyOf(name)}${mark}: ${typeOf(property, scope, depth + 1, record)};`;
+    });
+    return `{\n${lines.join("\n")}\n${"  ".repeat(depth)}}`;
+}
+/** The TypeScript of `schema`; `record` when it is (inside) a record a model describes. */
+function typeOf(schema, scope, depth, record) {
+    if (schema.$ref !== undefined)
+        return scope.refer(schema.$ref);
+    const options = schema.anyOf ?? schema.oneOf;
+    if (options !== undefined)
+        return union(options.map((one) => typeOf(one, scope, depth, record)));
+    if ("const" in schema)
+        return JSON.stringify(schema.const);
+    if (schema.enum !== undefined)
+        return union(schema.enum.map((one) => JSON.stringify(one)));
+    const types = typeof schema.type === "string" ? [schema.type] : (schema.type ?? []);
+    if (types.length > 1)
+        return union(types.map((one) => typeOf({ ...schema, type: one }, scope, depth, record)));
+    switch (types[0]) {
+        case "string":
+            return "string";
+        case "integer":
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        case "array":
+            return arrayOf(schema.items === undefined ? "unknown" : typeOf(schema.items, scope, depth, record));
+        case "object":
+            return objectOf(schema, scope, depth, record);
+        default:
+            return schema.properties === undefined
+                ? "unknown"
+                : objectOf(schema, scope, depth, record);
+    }
+}
+/** What the server says of an operation: its words, then what it is, for whom, on which field. */
+function operationDoc(metamodel, local, operation) {
+    const runsOn = sorted(operation.targets).map(([entity, field]) => `\`${entity}\` in \`${field}\``);
+    const whose = operation.entities.map((one) => `\`${one}\``).join(", ");
+    const facts = [
+        `\`${operation.role}\`${whose === "" ? "" : ` of ${whose}`}`,
+        operation.query ? "reads only" : undefined,
+        operation.dry_run ? "may run dry" : undefined,
+        runsOn.length === 0 ? undefined : `its record: ${runsOn.join(", ")}`,
+    ].filter((one) => one !== undefined);
+    return (docOf([operation.description, `${facts.join(" · ")}.`, deprecationOf(metamodel, operation)], "") || `/** ${local} */\n`);
+}
+/**
+ * The TypeScript of every DTO of `metamodel`, as the text of one file.
+ *
+ * 1. The models, by name: an entity's contract, a related model by its own name.
+ * 2. Each operation, by its local name (its identity without `<context>.`): its input as
+ *    `<Name>` and its answer as `<Name>Answer`.
+ * 3. The shared definitions those reach — and the ones those reach, until none is new —, but
+ *    never one a package of the stack already types (`Criteria`).
+ * Final: a header that says where it came from and not to edit it, the imports, then models,
+ *    definitions and operations, each sorted by name; two of them with one TypeScript name are
+ *    refused, naming both.
+ */
+export function domainFileOf(metamodel) {
+    const scope = scopeOf(metamodel);
+    const definitions = metamodel.$defs ?? {};
+    const claim = claimed();
+    const models = sorted(metamodel.models).map(([name, schema]) => {
+        claim(identifierOf(name), `model ${name}`);
+        return `${docOf([schema.description], "")}export type ${identifierOf(name)} = ${typeOf(schema, scope, 0, true)};`;
+    });
+    const operations = sorted(metamodel.operations).flatMap(([identity, operation]) => {
+        const local = localOf(metamodel, identity);
+        claim(local, `operation ${identity}`);
+        claim(`${local}Answer`, `the answer of ${identity}`);
+        const answer = operation.output === null ? "unknown" : typeOf(operation.output, scope, 0, false);
+        return [
+            `${operationDoc(metamodel, local, operation)}export type ${local} = ${typeOf(operation.input, scope, 0, false)};`,
+            `/** What \`${local}\` answers. */\nexport type ${local}Answer = ${answer};`,
+        ];
+    });
+    const written = new Map();
+    for (let pending = [...scope.reached]; pending.length > 0;) {
+        for (const name of pending) {
+            const schema = definitions[name];
+            written.set(name, `${docOf([schema.description], "")}export type ${identifierOf(name)} = ${typeOf(schema, scope, 0, false)};`);
+        }
+        pending = [...scope.reached].filter((name) => !written.has(name));
+    }
+    const shared = [...written.keys()].sort().map((name) => {
+        claim(identifierOf(name), `definition ${name}`);
+        return written.get(name);
+    });
+    const imports = [...scope.imports].sort().map((name) => {
+        const imported = IMPORTED[name];
+        return `import type { ${imported.name} } from "${imported.from}";`;
+    });
+    return `${[headerOf("The DTOs", metamodel), ...(imports.length === 0 ? [] : [imports.join("\n")]), ...models, ...shared, ...operations].join("\n\n")}\n`;
+}

package/dist/codegen/entities.d.ts

@@ -0,0 +1,14 @@
+import type { Metamodel } from "./metamodel.js";
+import { type GenerateOptions } from "./rest.js";
+/**
+ * The TypeScript of the entities of `metamodel`, as the text of one file next to its `domain.ts`.
+ *
+ * 1. Per model, by name: the one `search` a transport reads for it (`own` when there are
+ *    several) — none, and the model gets no entity, said in the file's own doc.
+ * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`.
+ * 3. Every write of role `command` that concerns it: with `target` when its body names the
+ *    record, as it is when it creates one; its body typed without that field.
+ * Final: an `entity<T, C>()` per model listed, keyed `<domain>:<kind>`, and `entities`, all of
+ *    them, for `FrameworkProvider entities`.
+ */
+export declare function entitiesFileOf(metamodel: Metamodel, options?: GenerateOptions): string;

package/dist/codegen/entities.js

@@ -0,0 +1,158 @@
+import { entityKeyOf } from "../client/contract.js";
+import { aliasOf, claimed, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, isEntity, localOf, methodOf, pluralOf, sorted, } from "./names.js";
+import { ownerOf, restOf, WRITES, } from "./rest.js";
+/** The one operation of `role` for `entity` a transport can call, by `own` when there are many. */
+function oneOf(candidates, role) {
+    if (candidates.length === 0)
+        return undefined;
+    if (candidates.length === 1)
+        return { found: candidates[0] };
+    const own = candidates.filter((one) => one.operation.own === true);
+    if (own.length === 1)
+        return { found: own[0] };
+    const names = candidates.map((one) => `\`${one.local}\``).join(", ");
+    return { missing: `${candidates.length} of role \`${role}\` (${names}) and none \`own\`` };
+}
+/** A route for `entity()`: the record's field in the path written `{id}`, as `entity()` fills it. */
+function recordPath(rest, field) {
+    return field === undefined || field === "id"
+        ? rest.path
+        : rest.path.replace(`{${field}}`, "{id}");
+}
+/**
+ * The field of a Command's body that names the one record of `model` it runs on. A list of keys
+ * (`list[EntityID[Issue]]`, `issue_ids`) names many: `run(id, body)` has one id to give, so the
+ * screen sends that list in the body itself.
+ */
+function singleTarget(operation, model) {
+    const field = operation.targets[model];
+    if (field === undefined)
+        return undefined;
+    const schema = operation.input.properties?.[field];
+    const held = schema?.anyOf?.find((one) => one.type !== "null") ?? schema;
+    return held?.type === "array" ? undefined : field;
+}
+function entitySourceOf(metamodel, model, domain, options, claim) {
+    const reached = sorted(metamodel.operations).flatMap(([identity, operation]) => {
+        const rest = restOf(metamodel, identity, options);
+        return rest === undefined
+            ? []
+            : [{ local: localOf(metamodel, identity), operation, rest }];
+    });
+    const reads = (role, method) => reached.filter((one) => one.operation.role === role &&
+        method(one.rest.method) &&
+        ownerOf(metamodel, one.operation) === model);
+    const isGet = (verb) => verb === "GET";
+    const isWrite = (verb) => WRITES.has(verb);
+    const list = oneOf(reads("search", isGet), "search");
+    if (list === undefined)
+        return { missing: "no `search` a transport reads" };
+    if ("missing" in list)
+        return { missing: list.missing };
+    // A list under a record (`/tenants/{tenant_id}/members`) keeps its keys: the screen gives
+    // them as the list's parameters (`useListing(entity, { params })`), and `listRoute` fills them.
+    const missing = [];
+    const routes = [`  list: ${JSON.stringify(list.found.rest.path)},`];
+    const one = oneOf(reads("get", isGet), "get");
+    if (one !== undefined && "found" in one) {
+        const field = one.found.operation.targets[model];
+        if (field !== undefined && one.found.rest.fields.length === 1)
+            routes.push(`  one: ${JSON.stringify(recordPath(one.found.rest, field))},`);
+        else
+            missing.push(`one: \`${one.found.local}\` is at ${one.found.rest.path}`);
+    }
+    else if (one !== undefined)
+        missing.push(`one: ${one.missing}`);
+    for (const role of ["edit", "preview"]) {
+        const write = oneOf(reads(role, isWrite), role);
+        if (write === undefined)
+            continue;
+        if ("missing" in write) {
+            missing.push(`${role}: ${write.missing}`);
+            continue;
+        }
+        const field = write.found.operation.targets[model];
+        const route = `${write.found.rest.method} ${recordPath(write.found.rest, field)}`;
+        routes.push(`  ${role}: ${JSON.stringify(route)},`);
+    }
+    const commands = reached.filter((one) => one.operation.role === "command" &&
+        isWrite(one.rest.method) &&
+        one.operation.entities.includes(model));
+    const bodies = [];
+    const answers = [];
+    const named = [];
+    for (const command of commands) {
+        const method = methodOf(command.local);
+        const target = singleTarget(command.operation, model);
+        const route = `${command.rest.method} ${command.rest.path}`;
+        bodies.push(target === undefined
+            ? `    ${method}: dto.${command.local};`
+            : `    ${method}: Omit<dto.${command.local}, ${JSON.stringify(target)}>;`);
+        answers.push(`    ${method}: dto.${command.local}Answer;`);
+        named.push(target === undefined
+            ? `    ${method}: ${JSON.stringify(route)},`
+            : `    ${method}: { route: ${JSON.stringify(route)}, target: ${JSON.stringify(target)} },`);
+    }
+    if (named.length > 0)
+        routes.push(`  commands: {\n${named.join("\n")}\n  },`);
+    const name = pluralOf(identifierOf(model));
+    claim(name, `the entity of ${model}`);
+    const types = bodies.length === 0
+        ? `dto.${identifierOf(model)}`
+        : `\n  dto.${identifierOf(model)},\n  {\n${bodies.join("\n")}\n  },\n  {\n${answers.join("\n")}\n  }\n`;
+    const doc = [
+        "/**",
+        ` * \`${model}\`: its list, its record and the Commands that run on it or create it.`,
+        ...(missing.length === 0
+            ? []
+            : [" *", " * Not declared:", ...missing.map((one) => ` * - ${one}.`)]),
+        " */",
+    ].join("\n");
+    const key = JSON.stringify(entityKeyOf(domain, model));
+    return {
+        name,
+        missing,
+        source: `${doc}\nexport const ${name} = entity<${types}>(${key}, {\n${routes.join("\n")}\n});`,
+    };
+}
+/**
+ * The TypeScript of the entities of `metamodel`, as the text of one file next to its `domain.ts`.
+ *
+ * 1. Per model, by name: the one `search` a transport reads for it (`own` when there are
+ *    several) — none, and the model gets no entity, said in the file's own doc.
+ * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`.
+ * 3. Every write of role `command` that concerns it: with `target` when its body names the
+ *    record, as it is when it creates one; its body typed without that field.
+ * Final: an `entity<T, C>()` per model listed, keyed `<domain>:<kind>`, and `entities`, all of
+ *    them, for `FrameworkProvider entities`.
+ */
+export function entitiesFileOf(metamodel, options = {}) {
+    const domain = options.domain ?? aliasOf(metamodel);
+    const claim = claimed();
+    claim("entities", "the list of every entity");
+    const declared = [];
+    const left = [];
+    // A value a record holds (no identity) is no entity: it is never listed nor opened alone.
+    for (const [model] of sorted(metamodel.models).filter(([name]) => isEntity(metamodel, name))) {
+        const one = entitySourceOf(metamodel, model, domain, options, claim);
+        if ("source" in one)
+            declared.push(one);
+        else
+            left.push(`\`${model}\`: ${one.missing}`);
+    }
+    const imports = [
+        `import { entity } from "${FRAMEWORK}";`,
+        "",
+        `import type * as dto from "${DOMAIN_MODULE}";`,
+    ].join("\n");
+    const all = [
+        "/**",
+        ` * Every entity of «${aliasOf(metamodel)}», for \`FrameworkProvider entities\`.`,
+        ...(left.length === 0
+            ? []
+            : [" *", " * Without an entity here:", ...left.map((one) => ` * - ${one}.`)]),
+        " */",
+        `export const entities = [${declared.map((one) => one.name).join(", ")}] as const;`,
+    ].join("\n");
+    return `${[headerOf("The entities", metamodel), imports, ...declared.map((one) => one.source), all].join("\n\n")}\n`;
+}

package/dist/codegen/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The generator: a bounded context's DTOs, client and entities out of the client contract
+ * sincpro_framework exports (PRD_01 phase B). A build step that runs in Node — nothing in
+ * the runtime imports it (`make doctor`), and the package's root entry does not re-export it. `sincpro-client generate` (`cli.ts`) is the same, from a terminal.
+ */
+export { clientFileOf } from "./client.js";
+export { domainFileOf } from "./domain.js";
+export { entitiesFileOf } from "./entities.js";
+export type { Bindings, Metamodel, Operation, RestBinding, Schema, } from "./metamodel.js";
+export type { GenerateOptions } from "./rest.js";

package/dist/codegen/index.js

@@ -0,0 +1,8 @@
+/**
+ * The generator: a bounded context's DTOs, client and entities out of the client contract
+ * sincpro_framework exports (PRD_01 phase B). A build step that runs in Node — nothing in
+ * the runtime imports it (`make doctor`), and the package's root entry does not re-export it. `sincpro-client generate` (`cli.ts`) is the same, from a terminal.
+ */
+export { clientFileOf } from "./client.js";
+export { domainFileOf } from "./domain.js";
+export { entitiesFileOf } from "./entities.js";

package/dist/codegen/metamodel.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The client contract of a bounded context, as sincpro_framework exports it
+ * (`export_client_contract`, PRD_33): its metamodel — models, the definitions they share, every
+ * operation a client may call — and how each wire reaches each operation (`bindings`). A bare
+ * metamodel (`export_metamodel`) is the same without `format` and `bindings`.
+ *
+ * Context: only what the generator reads is typed here. The file is the server's, written with
+ * its keys sorted, so the same code writes the same bytes; a key this does not name is kept in
+ * the snapshot and ignored by the generator.
+ */
+export type Schema = {
+    type?: string | readonly string[];
+    format?: string;
+    enum?: readonly unknown[];
+    const?: unknown;
+    items?: Schema;
+    $ref?: string;
+    anyOf?: readonly Schema[];
+    oneOf?: readonly Schema[];
+    properties?: Readonly<Record<string, Schema>>;
+    required?: readonly string[];
+    additionalProperties?: boolean | Schema;
+    title?: string;
+    description?: string;
+    "x-sincpro"?: {
+        type?: string;
+        relation?: string | null;
+        identity?: string;
+    };
+};
+export type Operation = {
+    /** What it is for its entity: `search`, `get`, `edit`, `command`… */
+    role: string;
+    /** It writes nothing: retrying or caching it is safe. */
+    query: boolean;
+    entities: readonly string[];
+    /** The field of `input` that names the record of each entity it runs on. */
+    targets: Readonly<Record<string, string>>;
+    dry_run: boolean;
+    description?: string | null;
+    input: Schema;
+    /** What it answers; `null` when the server declares nothing. */
+    output: Schema | null;
+    /** The entity's own operation of its role, when it has several (`@entity_tags(own=True)`). */
+    own?: boolean;
+    deprecated?: boolean;
+    /** The day it stops being served, `YYYY-MM-DD`. */
+    sunset?: string | null;
+    /** The operation that replaces it, by identity. */
+    replacement?: string | null;
+};
+/** How REST reaches an operation: its method and its whole path, `{field}` where a field goes. */
+export type RestBinding = {
+    method: string;
+    path: string;
+    /** The fields of the input the path carries. */
+    path_fields: readonly string[];
+};
+export type Bindings = {
+    rest?: Readonly<Record<string, RestBinding>>;
+    rpc?: Readonly<Record<string, {
+        method: string;
+    }>>;
+    grpc?: Readonly<Record<string, {
+        method: string;
+    }>>;
+    mcp?: Readonly<Record<string, {
+        tool: string;
+    }>>;
+};
+export type Metamodel = {
+    /** `sincpro.client-contract/1` for an exported client contract. */
+    format?: string;
+    /** The bounded context's own name: what every operation's identity starts with. */
+    bounded_context?: string;
+    /** The name the gateways publish it under (`FastApiGateway({"project": …})`): what a client
+     *  names the context by. */
+    alias?: string;
+    /** The bounded context's name, as sincpro_framework 3.32 wrote it before `bounded_context`. */
+    context?: string;
+    version: string;
+    /** Every shape the contract names: an entity (it has an `identity`) or a value it holds. */
+    models: Readonly<Record<string, Schema>>;
+    /** By the Command's identity, `"<bounded_context>.<Class>"`. */
+    operations: Readonly<Record<string, Operation>>;
+    $defs?: Readonly<Record<string, Schema>>;
+    /** By wire, then by the Command's identity. */
+    bindings?: Bindings;
+};

package/dist/codegen/metamodel.js

@@ -0,0 +1 @@
+export {};

package/dist/codegen/names.d.ts

@@ -0,0 +1,39 @@
+import type { Metamodel } from "./metamodel.js";
+/**
+ * What a generated file imports, built in parts. The build rewrites this package's own
+ * specifiers to relative paths (`tsc-alias`), and it reads `from "…"` inside a string too: written
+ * whole, the generated files came out importing `"../index.js"` and `"./domain.js"`.
+ */
+export declare const FRAMEWORK: string;
+export declare const DOMAIN_MODULE: string;
+/** A name of the server's as a TypeScript identifier: `shop__orders__Line` stays, `-` is `_`. */
+export declare function identifierOf(name: string): string;
+/** A property key as TypeScript writes it: bare when it can be, quoted otherwise. */
+export declare function keyOf(name: string): string;
+export declare function sorted<V>(record: Readonly<Record<string, V>>): [string, V][];
+/** `{ Issue: "issue_id" }`: a record of texts as TypeScript writes it, keys sorted. */
+export declare function recordLiteral(record: Readonly<Record<string, string>>): string;
+/** The bounded context's own name: `bounded_context`, or `context` in a 3.32 contract. */
+export declare function contextOf(metamodel: Metamodel): string;
+/** What a client names the context by: its `alias`, else its own name. */
+export declare function aliasOf(metamodel: Metamodel): string;
+/** A model the contract names is an entity when it has an identity; else a value it holds. */
+export declare function isEntity(metamodel: Metamodel, model: string): boolean;
+/** An operation's name in its context: its identity without `<bounded_context>.`. */
+export declare function localOf(metamodel: Metamodel, identity: string): string;
+/** The method an operation is called by: `CommandSendIssue` → `sendIssue`. */
+export declare function methodOf(local: string): string;
+/** `Issue` → `issues`, `ProjectEvent` → `projectEvents`, `Policy` → `policies`. */
+export declare function pluralOf(name: string): string;
+/** A JSDoc block, or nothing: the paragraphs given, each one kept. */
+export declare function docOf(lines: readonly (string | null | undefined)[], pad: string): string;
+/** The first lines of every generated file: what it is, where it came from, not to edit it. */
+export declare function headerOf(what: string, metamodel: Metamodel): string;
+/** What a deprecated operation says: since when it goes and what replaces it. */
+export declare function deprecationOf(metamodel: Metamodel, operation: {
+    deprecated?: boolean;
+    sunset?: string | null;
+    replacement?: string | null;
+}): string | undefined;
+/** Refuses a second thing under a name already given, naming both. */
+export declare function claimed(): (name: string, by: string) => void;

package/dist/codegen/names.js

@@ -0,0 +1,113 @@
+/**
+ * How the generator names what the server names: a TypeScript identifier for a class, a method
+ * for an operation, a value for an entity, the key the workspace refers to an entity by.
+ *
+ * Context: every name here is derived, the same way every time, from what the contract already
+ * says — never chosen — so regenerating never renames by itself. Two things that come out with
+ * one name are refused by whoever writes them, naming both (`claimed`): a silent rename would
+ * break whoever imported the first.
+ */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/**
+ * What a generated file imports, built in parts. The build rewrites this package's own
+ * specifiers to relative paths (`tsc-alias`), and it reads `from "…"` inside a string too: written
+ * whole, the generated files came out importing `"../index.js"` and `"./domain.js"`.
+ */
+export const FRAMEWORK = ["@sincpro", "client-framework"].join("/");
+export const DOMAIN_MODULE = [".", "domain"].join("/");
+/** A name of the server's as a TypeScript identifier: `shop__orders__Line` stays, `-` is `_`. */
+export function identifierOf(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9_$]/g, "_");
+    return /^[0-9]/.test(cleaned) ? `_${cleaned}` : cleaned;
+}
+/** A property key as TypeScript writes it: bare when it can be, quoted otherwise. */
+export function keyOf(name) {
+    return IDENTIFIER.test(name) ? name : JSON.stringify(name);
+}
+export function sorted(record) {
+    return Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/** `{ Issue: "issue_id" }`: a record of texts as TypeScript writes it, keys sorted. */
+export function recordLiteral(record) {
+    const entries = sorted(record).map(([key, value]) => `${keyOf(key)}: ${JSON.stringify(value)}`);
+    return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
+}
+/** The bounded context's own name: `bounded_context`, or `context` in a 3.32 contract. */
+export function contextOf(metamodel) {
+    const name = metamodel.bounded_context ?? metamodel.context;
+    if (name === undefined)
+        throw new Error("the contract names no bounded context");
+    return name;
+}
+/** What a client names the context by: its `alias`, else its own name. */
+export function aliasOf(metamodel) {
+    return metamodel.alias ?? contextOf(metamodel);
+}
+/** A model the contract names is an entity when it has an identity; else a value it holds. */
+export function isEntity(metamodel, model) {
+    return metamodel.models[model]?.["x-sincpro"]?.identity !== undefined;
+}
+/** An operation's name in its context: its identity without `<bounded_context>.`. */
+export function localOf(metamodel, identity) {
+    const prefix = `${contextOf(metamodel)}.`;
+    return identifierOf(identity.startsWith(prefix) ? identity.slice(prefix.length) : identity);
+}
+/** The method an operation is called by: `CommandSendIssue` → `sendIssue`. */
+export function methodOf(local) {
+    const bare = local.replace(/^(Command|Query)(?=[A-Z])/, "");
+    return `${bare.charAt(0).toLowerCase()}${bare.slice(1)}`;
+}
+/** `Issue` → `issues`, `ProjectEvent` → `projectEvents`, `Policy` → `policies`. */
+export function pluralOf(name) {
+    const value = `${name.charAt(0).toLowerCase()}${name.slice(1)}`;
+    if (/[^aeiou]y$/.test(value))
+        return `${value.slice(0, -1)}ies`;
+    if (/(s|x|z|ch|sh)$/.test(value))
+        return `${value}es`;
+    return `${value}s`;
+}
+/** A JSDoc block, or nothing: the paragraphs given, each one kept. */
+export function docOf(lines, pad) {
+    const text = lines
+        .filter((one) => typeof one === "string" && one.trim() !== "")
+        .join("\n\n")
+        .replace(/\*\//g, "*\\/")
+        .trim();
+    if (text === "")
+        return "";
+    const parts = text.split("\n");
+    if (parts.length === 1)
+        return `${pad}/** ${parts[0]} */\n`;
+    const body = parts.map((one) => `${pad} *${one === "" ? "" : ` ${one}`}`).join("\n");
+    return `${pad}/**\n${body}\n${pad} */\n`;
+}
+/** The first lines of every generated file: what it is, where it came from, not to edit it. */
+export function headerOf(what, metamodel) {
+    const alias = aliasOf(metamodel);
+    const own = contextOf(metamodel);
+    return [
+        `// ${what} of «${alias}»${alias === own ? "" : ` (${own})`}, generated by @sincpro/client-framework.`,
+        `// Version ${metamodel.version}.`,
+        `// Do not edit: regenerate it (\`sincpro-client generate\`).`,
+    ].join("\n");
+}
+/** What a deprecated operation says: since when it goes and what replaces it. */
+export function deprecationOf(metamodel, operation) {
+    if (operation.deprecated !== true)
+        return undefined;
+    const sunset = operation.sunset ? ` It stops being served on ${operation.sunset}.` : "";
+    const replacement = operation.replacement
+        ? ` Use \`${localOf(metamodel, operation.replacement)}\`.`
+        : "";
+    return `@deprecated${sunset}${replacement}`;
+}
+/** Refuses a second thing under a name already given, naming both. */
+export function claimed() {
+    const named = new Map();
+    return (name, by) => {
+        const before = named.get(name);
+        if (before !== undefined)
+            throw new Error(`${by} and ${before} are both "${name}" in TypeScript: rename one`);
+        named.set(name, by);
+    };
+}

package/dist/codegen/rest.d.ts

@@ -0,0 +1,31 @@
+import type { Metamodel, Operation } from "./metamodel.js";
+/**
+ * How REST reaches each operation of a contract, as the generated client and entities write it.
+ *
+ * Context: the export names each path whole (`/v1/issues/{issue_id}`), version included, while
+ * an application's transport already prepends it (`restTransport({ base: "/v1" })`). `base`
+ * takes it off every path, and a path outside it is refused — a client written with half its
+ * routes under the wrong base would fail one call at a time.
+ */
+export type GenerateOptions = {
+    /** The first part of every entity's key: `project` makes `project:issue`. The contract's
+     *  `alias` by default. */
+    domain?: string;
+    /** What every REST path starts with and the transport prepends: `/v1`. */
+    base?: string;
+};
+export type Reached = {
+    method: string;
+    /** The path under `base`, `{field}` where a field of the input goes. */
+    path: string;
+    /** The fields of the input the path carries. */
+    fields: readonly string[];
+};
+/** What a transport can send: GET is read by `list` (a page) or `one` (a record) only. */
+export declare const WRITES: Set<string>;
+export declare function restOf(metamodel: Metamodel, identity: string, options: GenerateOptions): Reached | undefined;
+/**
+ * The one entity a read belongs to: its only entity, or — when it concerns several — the one
+ * whose model its answer carries. `undefined` when that still leaves more than one.
+ */
+export declare function ownerOf(metamodel: Metamodel, operation: Operation): string | undefined;