@leemour/cli-core 0.7.0 → 0.9.0

package/README.md

@@ -7,8 +7,9 @@ keyring behind a testable seam, and injectable clocks.
 Extracted from [`brazecli`](https://github.com/leemour/brazecli), where each piece earned its
 shape, and shared with [`max-cli`](https://github.com/leemour/max-cli).
 
-**Status: 0.5.0.** Published on npm, used by `max-cli`. Both extraction steps have landed: the
-files that move unchanged, and the ones that needed a parameter threaded through. 75 tests.
+Published on npm and used by `max-cli`, `cli-messaging`, `tg-cli` and `brazecli`. What changed in
+each version is in [`CHANGELOG.md`](CHANGELOG.md); how the package is put together and released is in
+[`docs/dev/`](docs/dev/ARCHITECTURE.md).
 
 ## The rule this package exists to keep
 
@@ -46,6 +47,8 @@ streams.stderr // []
 | `/commands` | the command registry: `describeProgram`, `annotate`, `flatten` — see below |
 | `/completion` | shell completion over the registry: `suggest`, `formatSuggestions` — see below |
 | `/update` | keeping an install current: `installerOf`, `updateCommand`, `latestVersion`, `mayNotify`, `updateNotice`, `runUpdate` — see below |
+| `/codegen` | build time: an official API description → types, Valibot schemas, an operation manifest and a coverage page — see below |
+| `/release` | release time: `releaseCheck` and the checks it runs — changelog shape, links, package contents, version in step — see below |
 
 **Nothing in the root export is HTTP.** Status classification, `Retry-After` parsing and the fetch
 seam live in `@leemour/cli-core/http`, so a CLI that speaks a socket never depends on a stack it
@@ -95,9 +98,40 @@ a throwaway config directory silently overwrites the real secret unless you pass
 And a secret should never be handed to a logger in the first place — redaction by field name is the
 second line of defence, not the first.
 
-**Everything the environment knows is passed in.** No `process.env` reads, no config file paths,
-no ambient clock. That is what makes a timeout test finish instantly and a keyring test incapable
-of reaching a real keychain.
+**Everything the environment knows can be passed in**: the clock, the sleep, the keyring, `env`,
+`fetch` and the streams. The real ones are only defaults — `Credentials` without a `keyring` uses the
+system keychain, `resolvePaths` without `env` reads `process.env`. Passing them is what makes a
+timeout test finish instantly and a keyring test incapable of reaching a real keychain.
+
+**Generating an API catalog is `@leemour/cli-core/codegen`**, a build-time tool. It reads a
+format-neutral `ApiModel` — operations with a transport binding (`http` method and path, or `rpc`
+name), an `effect` (`read`, `write`, `destructive`) and how far the source can be trusted
+(`contract`, `example`, `inferred`, `override`) — and writes committed files. It parses no file
+format: the adapter from OpenAPI, Postman or anything else lives in the CLI that has that source,
+so this adds no dependency. Generation stops, naming the problem, when two operations collide, an
+operation is not classified as a read or a write, an override matches nothing, a reference points
+nowhere or a construct cannot be expressed; it never drops an operation or falls back to `any`.
+
+```ts
+import { generate, manifestGenerator, typesGenerator, valibotGenerator, writeArtifacts } from "@leemour/cli-core/codegen"
+
+const artifacts = generate(model, [typesGenerator({ path }), valibotGenerator({ path, typesImport }), manifestGenerator({ path })], {
+  overrides: { answerOnCallback: { effect: "write", reason: "a POST that edits a message" } },
+  banner: ["Source: spec/bot/schema.yaml", "Run: pnpm bot:generate"],
+})
+const stale = writeArtifacts(artifacts, { root, check: process.argv.includes("--check") })
+```
+
+The generated schemas import `@leemour/cli-core/codegen/runtime` at run time — a few number
+helpers, not the generator. Numbers are expected from a lossless JSON parser (`lossless-json`): a
+64-bit integer comes out as its exact decimal string, and any other integer that does not fit a JS
+number fails instead of rounding. Objects are loose, so a field the API added later passes through.
+Enums and discriminated unions are **strict**: a value or subtype the snapshot does not know fails,
+so decode a live stream (updates, webhooks) only where that is what you want.
+
+**The schemas decode; they do not encode.** Their output carries an `int64` as a string, so sending
+it back would put a string where the API expects a number. Validate a request with the schema, then
+send the original lossless value.
 
 **Keeping an install current is `@leemour/cli-core/update`.** `installerOf(realpath(script))` says
 which package manager put the CLI there — pnpm, npm or bun, measured on real installs — and
@@ -110,6 +144,30 @@ sentence or `undefined` — it never throws. `runUpdate` starts the package mana
 stderr (`spawnPlan` is the Windows `.cmd` rule). Nothing here updates or prints by itself — a CLI
 holding somebody's credentials must not change itself unasked.
 
+**The release checks are `@leemour/cli-core/release`** — everything about a release that a program
+can decide. A check is `{ name, run }`, and `run` returns the problems it found, one line each; an
+empty list is a pass. `releaseCheck(checks, { version, log })` runs them all, even after a failure,
+prints `ok` or `FAIL` per check and returns how many failed — the caller exits. The checks every CLI
+shares: `command(root, "pnpm", "lint")` for anything that passes by exiting 0, `notOnNpm`,
+`packContents` against a list of what may ship, `changelogProblems` for the fixed headings and the
+dated top section, `docsProblems` for dead links and anchors and the rules of the pages a user reads,
+and `versionScript` — the whole of a `version:check` / `version:sync` script. Each CLI passes its
+own headings, id prefixes and pages; the checks that belong to one messenger stay in that CLI.
+
+```ts
+import { command, notOnNpm, packageVersion, releaseCheck } from "@leemour/cli-core/release"
+
+const version = packageVersion(root)
+const failed = releaseCheck(
+  [
+    { name: "version not on npm", run: notOnNpm(root, "@leemour/tg-cli", version) },
+    { name: "lint", run: command(root, "pnpm", "lint") },
+  ],
+  { version, log: console.log },
+)
+process.exit(failed === 0 ? 0 : 1)
+```
+
 ## Where secrets actually go, per platform
 
 The keyring is real on every desktop and absent on most servers, so the fallback is not an edge
@@ -149,19 +207,23 @@ pnpm typecheck
 pnpm build
 ```
 
+The rest of the checks, and what each is for, are in [`docs/dev/TESTING.md`](docs/dev/TESTING.md).
+
 ## Releasing
 
-Raise `version` in `package.json` through a pull request, merge it, then on `main`:
+Raise `version` in `package.json` and date the `## Unreleased` section of
+[`CHANGELOG.md`](CHANGELOG.md) as that version, through a pull request; merge it, then on `main`:
 
 ```sh
 bin/release
 ```
 
-It refuses a dirty tree, a branch other than `main`, a `main` that is not pushed and a version npm
-already has, then starts [`release.yml`](.github/workflows/release.yml) and follows it. The workflow
-runs every check, publishes through npm's
-[trusted publishing](https://docs.npmjs.com/trusted-publishers/) — no npm token in GitHub, and npm
-attaches provenance — and tags `v<version>` only once npm shows the new version.
+It refuses a dirty tree, a branch other than `main` and a `main` that is not pushed. When npm already
+has the version, or a higher one, it commits the next free version to `main` — the next minor for
+`x.y.0`, the next patch otherwise — renames the changelog heading to match, and publishes that. Then it starts
+[`release.yml`](.github/workflows/release.yml) and follows it. The workflow runs every check,
+publishes through npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers/) — no npm
+token in GitHub, and npm attaches provenance — and tags `v<version>` only once npm shows the new version.
 
 npm trusts the workflow **by file name**: the package's Trusted Publisher settings on npmjs.com name
 `leemour` / `cli-core` / `release.yml`. Rename the file and publishing stops until they are updated.

package/dist/codegen/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Turns an official API description into committed code: types, Valibot schemas, an operation
+ * manifest and a coverage page. Build-time only, and format-neutral: it parses no file format and
+ * adds no dependency. The adapter from OpenAPI, Postman or anything else lives in the consumer.
+ */
+export { type CoverageOptions, coverageGenerator, type ManifestOperation, manifestGenerator } from "./manifest.js";
+export type { ApiBody, ApiModel, ApiOperation, ApiParameter, ApiSchema, Binding, CodeGenerator, Confidence, Discriminator, Effect, GeneratedArtifact, HttpBinding, HttpMethod, Override, RpcBinding, SchemaNode, SourceInfo, SourceReference, } from "./model.js";
+export { identifier, kebab } from "./names.js";
+export { applyOverrides, CodegenError, type GenerateOptions, generate, validateModel, type WriteOptions, writeArtifacts, } from "./pipeline.js";
+export { typesGenerator } from "./typescript.js";
+export { type ValibotOptions, valibotGenerator } from "./valibot.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codegen/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,eAAe,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAClH,YAAY,EACV,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,OAAO,EACP,aAAa,EACb,UAAU,EACV,aAAa,EACb,MAAM,EACN,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,UAAU,EACV,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EACL,cAAc,EACd,YAAY,EACZ,KAAK,eAAe,EACpB,QAAQ,EACR,aAAa,EACb,KAAK,YAAY,EACjB,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAE,KAAK,cAAc,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA"}

package/dist/codegen/index.js

@@ -0,0 +1,11 @@
+/**
+ * Turns an official API description into committed code: types, Valibot schemas, an operation
+ * manifest and a coverage page. Build-time only, and format-neutral: it parses no file format and
+ * adds no dependency. The adapter from OpenAPI, Postman or anything else lives in the consumer.
+ */
+export { coverageGenerator, manifestGenerator } from "./manifest.js";
+export { identifier, kebab } from "./names.js";
+export { applyOverrides, CodegenError, generate, validateModel, writeArtifacts, } from "./pipeline.js";
+export { typesGenerator } from "./typescript.js";
+export { valibotGenerator } from "./valibot.js";
+//# sourceMappingURL=index.js.map

package/dist/codegen/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/codegen/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAwB,iBAAiB,EAA0B,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAqBlH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EACL,cAAc,EACd,YAAY,EAEZ,QAAQ,EACR,aAAa,EAEb,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAuB,gBAAgB,EAAE,MAAM,cAAc,CAAA"}

package/dist/codegen/manifest.d.ts

@@ -0,0 +1,41 @@
+import type { Binding, CodeGenerator, Confidence, Effect, SchemaNode } from "./model.js";
+/** One operation as a CLI reads it at run time: enough to build a command, validate input and guard a write. */
+export interface ManifestOperation {
+    id: string;
+    command: string;
+    binding: Binding;
+    effect: Effect;
+    summary?: string;
+    description?: string;
+    tags: readonly string[];
+    deprecated?: boolean;
+    parameters: readonly {
+        name: string;
+        in: "path" | "query" | "header";
+        required: boolean;
+        description?: string;
+        schema: SchemaNode;
+    }[];
+    request?: {
+        required: boolean;
+        confidence: Confidence;
+        schema?: string;
+    };
+    response?: {
+        confidence: Confidence;
+        schema?: string;
+    };
+}
+export declare const manifestGenerator: (options: {
+    path: string;
+    coreImport?: string;
+}) => CodeGenerator;
+export interface CoverageOptions {
+    path: string;
+    title: string;
+    /** How a user reaches the operation, e.g. `max bot api get-my-info`. */
+    command: (operation: ManifestOperation) => string;
+}
+/** Every operation the source has, and how it is reached — the page a reviewer diffs after a sync. */
+export declare const coverageGenerator: (options: CoverageOptions) => CodeGenerator;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/codegen/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/codegen/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA0B,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAIhH,gHAAgH;AAChH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,UAAU,EAAE,SAAS;QACnB,IAAI,EAAE,MAAM,CAAA;QACZ,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;QAC/B,QAAQ,EAAE,OAAO,CAAA;QACjB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,MAAM,EAAE,UAAU,CAAA;KACnB,EAAE,CAAA;IACH,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACxE,QAAQ,CAAC,EAAE;QAAE,UAAU,EAAE,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACvD;AA4BD,eAAO,MAAM,iBAAiB,YAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,aAWjD,CAAA;AAIH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,OAAO,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,MAAM,CAAA;CAClD;AAED,sGAAsG;AACtG,eAAO,MAAM,iBAAiB,YAClB,eAAe,KAAG,aAwB3B,CAAA"}

package/dist/codegen/manifest.js

@@ -0,0 +1,59 @@
+import { kebab } from "./names.js";
+import { SchemaTree } from "./tree.js";
+const withoutUndefined = (value) => Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
+const toManifest = (operation, tree) => withoutUndefined({
+    id: operation.id,
+    command: kebab(operation.id),
+    binding: operation.binding,
+    effect: operation.effect,
+    summary: operation.summary,
+    description: operation.description,
+    tags: operation.tags,
+    deprecated: operation.deprecated,
+    parameters: operation.parameters.map((parameter) => withoutUndefined({ ...parameter })),
+    request: operation.requestBody
+        ? withoutUndefined({
+            required: operation.requestBody.required,
+            confidence: operation.requestBody.confidence,
+            schema: tree.requestName(operation.id),
+        })
+        : undefined,
+    response: operation.response
+        ? withoutUndefined({ confidence: operation.response.confidence, schema: tree.responseName(operation.id) })
+        : undefined,
+});
+export const manifestGenerator = (options) => (model) => {
+    const tree = new SchemaTree(model);
+    const operations = model.operations.map((operation) => toManifest(operation, tree));
+    const content = [
+        `import type { ManifestOperation } from "${options.coreImport ?? "@leemour/cli-core/codegen"}"`,
+        "",
+        `export const operations: readonly ManifestOperation[] = ${JSON.stringify(operations, null, 2)}`,
+        "",
+    ].join("\n");
+    return [{ path: options.path, content }];
+};
+const cell = (text) => (text ?? "").replace(/\s+/g, " ").replace(/\|/g, "\\|").trim();
+/** Every operation the source has, and how it is reached — the page a reviewer diffs after a sync. */
+export const coverageGenerator = (options) => (model) => {
+    const tree = new SchemaTree(model);
+    const rows = model.operations.map((operation) => {
+        const entry = toManifest(operation, tree);
+        const binding = entry.binding.kind === "http" ? `${entry.binding.method} ${entry.binding.path}` : entry.binding.name;
+        const status = entry.deprecated ? "deprecated" : "generated";
+        return `| \`${entry.id}\` | \`${binding}\` | \`${options.command(entry)}\` | ${entry.effect} | ${entry.request?.confidence ?? "—"} | ${status} | ${cell(entry.summary)} |`;
+    });
+    const version = model.source.version ? ` ${model.source.version}` : "";
+    const content = [
+        `# ${options.title}`,
+        "",
+        `${model.operations.length} operations from ${model.source.kind}${version}.`,
+        "",
+        "| Operation | Call | Command | Effect | Request source | Status | Summary |",
+        "|---|---|---|---|---|---|---|",
+        ...rows,
+        "",
+    ].join("\n");
+    return [{ path: options.path, content }];
+};
+//# sourceMappingURL=manifest.js.map

package/dist/codegen/manifest.js.map

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

package/dist/codegen/model.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The model every generator reads, whatever the source was: an OpenAPI file, a Postman collection,
+ * a scraped reference page. A source adapter lives in the consumer and produces this; nothing here
+ * parses a file format.
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
+/** How much the source promises. A Postman example is not a contract and must never become one. */
+export type Confidence = "contract" | "example" | "inferred" | "override";
+/**
+ * `undefined` in an adapter's output means "the source did not say". Generation refuses to run
+ * until an override classifies it — a write mistaken for a read is the expensive mistake.
+ */
+export type Effect = "read" | "write" | "destructive";
+export interface HttpBinding {
+    kind: "http";
+    method: HttpMethod;
+    path: string;
+}
+/** Every call is the same HTTP shape and only the name differs, as in the Telegram Bot API. */
+export interface RpcBinding {
+    kind: "rpc";
+    name: string;
+}
+export type Binding = HttpBinding | RpcBinding;
+interface SchemaCommon {
+    description?: string;
+    nullable?: boolean;
+    deprecated?: boolean;
+    default?: unknown;
+}
+export type SchemaNode = SchemaCommon & ({
+    type: "ref";
+    ref: string;
+} | {
+    type: "string";
+    enum?: readonly string[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+} | {
+    type: "integer";
+    format?: "int32" | "int64";
+    minimum?: number;
+    maximum?: number;
+    enum?: readonly number[];
+} | {
+    type: "number";
+    minimum?: number;
+    maximum?: number;
+} | {
+    type: "boolean";
+} | {
+    type: "array";
+    items: SchemaNode;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+} | {
+    type: "object";
+    properties: Readonly<Record<string, SchemaNode>>;
+    required: readonly string[];
+    additionalProperties?: SchemaNode;
+}
+/** Inheritance: every member must resolve to an object, and the fields are merged. */
+ | {
+    type: "allOf";
+    of: readonly SchemaNode[];
+}
+/** Only where the source itself says "anything". An adapter never falls back to this. */
+ | {
+    type: "unknown";
+});
+/**
+ * A base type with subtypes chosen by one property, OpenAPI's `discriminator`. Referenced from
+ * inside an `allOf` it means the base's own fields; referenced anywhere else, one of the subtypes.
+ */
+export interface Discriminator {
+    property: string;
+    mapping: Readonly<Record<string, string>>;
+}
+export interface ApiSchema {
+    id: string;
+    schema: SchemaNode;
+    discriminator?: Discriminator;
+}
+export interface ApiParameter {
+    name: string;
+    in: "path" | "query" | "header";
+    required: boolean;
+    description?: string;
+    schema: SchemaNode;
+}
+export interface ApiBody {
+    confidence: Confidence;
+    required: boolean;
+    schema?: SchemaNode;
+    example?: unknown;
+}
+export interface SourceReference {
+    /** Where in the source this came from, for a reviewer: a JSON pointer, a folder path. */
+    location: string;
+}
+export interface ApiOperation {
+    /** The source's own id where it has one. Never re-derived when it does. */
+    id: string;
+    binding: Binding;
+    summary?: string;
+    description?: string;
+    tags: readonly string[];
+    parameters: readonly ApiParameter[];
+    requestBody?: ApiBody;
+    response?: ApiBody;
+    effect?: Effect;
+    deprecated?: boolean;
+    source: SourceReference;
+}
+export interface SourceInfo {
+    kind: "openapi" | "postman" | "other";
+    version?: string;
+    sourceUrl?: string;
+    sourceRevision?: string;
+}
+export interface ApiModel {
+    source: SourceInfo;
+    operations: readonly ApiOperation[];
+    schemas: readonly ApiSchema[];
+}
+export interface Override {
+    effect?: Effect;
+    /** Required: an override nobody can explain is one nobody dares remove. */
+    reason: string;
+}
+export interface GeneratedArtifact {
+    path: string;
+    content: string;
+}
+export type CodeGenerator = (model: ApiModel) => GeneratedArtifact[];
+export {};
+//# sourceMappingURL=model.d.ts.map

package/dist/codegen/model.d.ts.map

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

package/dist/codegen/model.js

@@ -0,0 +1,7 @@
+/**
+ * The model every generator reads, whatever the source was: an OpenAPI file, a Postman collection,
+ * a scraped reference page. A source adapter lives in the consumer and produces this; nothing here
+ * parses a file format.
+ */
+export {};
+//# sourceMappingURL=model.js.map

package/dist/codegen/model.js.map

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

package/dist/codegen/names.d.ts

@@ -0,0 +1,4 @@
+export declare const identifier: (id: string) => string;
+/** `getMyInfo` → `get-my-info`. */
+export declare const kebab: (id: string) => string;
+//# sourceMappingURL=names.d.ts.map

package/dist/codegen/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/codegen/names.ts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,UAAU,OAAQ,MAAM,KAAG,MAIvC,CAAA;AAED,mCAAmC;AACnC,eAAO,MAAM,KAAK,OAAQ,MAAM,KAAG,MAKjB,CAAA"}

package/dist/codegen/names.js

@@ -0,0 +1,46 @@
+const pascal = (text) => text
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((word) => word[0]?.toUpperCase() + word.slice(1))
+    .join("");
+// A generated `export const Error` compiles, and then every `new Error()` in that module builds a schema.
+const GLOBALS = new Set([
+    "Array",
+    "BigInt",
+    "Boolean",
+    "Date",
+    "Error",
+    "Function",
+    "Intl",
+    "JSON",
+    "Map",
+    "Math",
+    "Number",
+    "Object",
+    "Partial",
+    "Promise",
+    "Proxy",
+    "Record",
+    "Reflect",
+    "RegExp",
+    "Required",
+    "Set",
+    "String",
+    "Symbol",
+    "URL",
+    "WeakMap",
+    "WeakSet",
+]);
+export const identifier = (id) => {
+    const name = pascal(id);
+    if (!/^[A-Za-z]/.test(name))
+        return `Schema${name}`;
+    return GLOBALS.has(name) ? `Api${name}` : name;
+};
+/** `getMyInfo` → `get-my-info`. */
+export const kebab = (id) => id
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+//# sourceMappingURL=names.js.map

package/dist/codegen/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../../src/codegen/names.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG,CAAC,IAAY,EAAU,EAAE,CACtC,IAAI;KACD,KAAK,CAAC,eAAe,CAAC;KACtB,MAAM,CAAC,OAAO,CAAC;KACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACrD,IAAI,CAAC,EAAE,CAAC,CAAA;AAEb,0GAA0G;AAC1G,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC;IACtB,OAAO;IACP,QAAQ;IACR,SAAS;IACT,MAAM;IACN,OAAO;IACP,UAAU;IACV,MAAM;IACN,MAAM;IACN,KAAK;IACL,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,SAAS;IACT,OAAO;IACP,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,UAAU;IACV,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,KAAK;IACL,SAAS;IACT,SAAS;CACV,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,EAAU,EAAU,EAAE;IAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,CAAA;IACvB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,IAAI,EAAE,CAAA;IACnD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AAChD,CAAC,CAAA;AAED,mCAAmC;AACnC,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,EAAU,EAAU,EAAE,CAC1C,EAAE;KACC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;KACtC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC;KAC9B,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;KACrB,WAAW,EAAE,CAAA"}

package/dist/codegen/pipeline.d.ts

@@ -0,0 +1,24 @@
+import type { ApiModel, CodeGenerator, GeneratedArtifact, Override } from "./model.js";
+export declare class CodegenError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+export declare const applyOverrides: (model: ApiModel, overrides: Readonly<Record<string, Override>>) => ApiModel;
+/** Everything that would otherwise make an operation vanish or turn into a guess. */
+export declare const validateModel: (model: ApiModel) => void;
+export interface GenerateOptions {
+    overrides?: Readonly<Record<string, Override>>;
+    /** Lines under "GENERATED. DO NOT EDIT." — the source and the command. Nothing that changes by itself. */
+    banner: readonly string[];
+}
+export declare const generate: (model: ApiModel, generators: readonly CodeGenerator[], options: GenerateOptions) => GeneratedArtifact[];
+export interface WriteOptions {
+    root: string;
+    /** Compare only: report what is out of date and write nothing. */
+    check?: boolean;
+    /** The consumer's formatter, so a check compares what would actually be committed. */
+    format?: (path: string, content: string) => string;
+}
+/** Paths whose committed content differs from what was generated — written, or with `check`, only reported. */
+export declare const writeArtifacts: (artifacts: readonly GeneratedArtifact[], options: WriteOptions) => string[];
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/codegen/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/codegen/pipeline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAgB,aAAa,EAAE,iBAAiB,EAAE,QAAQ,EAAc,MAAM,YAAY,CAAA;AAGhH,qBAAa,YAAa,SAAQ,KAAK;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE;IAAhD,YAAqB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAG/C;CACF;AAED,eAAO,MAAM,cAAc,UAAW,QAAQ,aAAa,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,KAAG,QAc/F,CAAA;AA6BD,qFAAqF;AACrF,eAAO,MAAM,aAAa,UAAW,QAAQ,KAAG,IAyC/C,CAAA;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;IAC9C,0GAA0G;IAC1G,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B;AAOD,eAAO,MAAM,QAAQ,UACZ,QAAQ,cACH,SAAS,aAAa,EAAE,WAC3B,eAAe,KACvB,iBAAiB,EAQnB,CAAA;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,sFAAsF;IACtF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;CACnD;AAED,+GAA+G;AAC/G,eAAO,MAAM,cAAc,cAAe,SAAS,iBAAiB,EAAE,WAAW,YAAY,KAAG,MAAM,EAarG,CAAA"}