@intentius/chant 0.107.1 → 0.108.1

package/src/cli/handlers/generate.ts

@@ -0,0 +1,90 @@
+import { relative, resolve, sep } from "node:path";
+import { findProjectConfigPastFragments, loadChantConfig } from "../../config";
+import { checkProjectCodegen, generateProjectCode } from "../../project-codegen";
+import { formatError, formatSuccess, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+
+/**
+ * `chant generate [path] [--check] [--lexicon <name>]` — project-local code
+ * generation (../../project-codegen.ts). Each configured lexicon that
+ * implements the `projectCodegen` hook renders typed code from the sources
+ * the project declares (`k8s.crds`, `helm.charts`) into
+ * `<codegen.outDir>/<lexicon>/`.
+ *
+ * `--check` writes nothing and exits 1 when any lexicon's committed output no
+ * longer matches its declared sources: the same check `chant build` makes,
+ * for a CI step that wants to say so before building.
+ *
+ * Not `chant dev generate`, which regenerates a lexicon package's own types
+ * from upstream specs and is for lexicon authors.
+ */
+export async function runGenerate(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const projectRoot = findProjectConfigPastFragments(resolve(args.path)).dir;
+  let config: Record<string, unknown>;
+  try {
+    config = (await loadChantConfig(projectRoot)).config as unknown as Record<string, unknown>;
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+
+  const plugins = ctx.plugins.filter(
+    (p) => typeof p.projectCodegen === "function" && (!args.lexicon || p.name === args.lexicon),
+  );
+  if (args.lexicon && plugins.length === 0) {
+    console.error(formatError({
+      message: `lexicon "${args.lexicon}" is not configured for this project, or generates no project code`,
+    }));
+    return 1;
+  }
+
+  const show = (path: string): string => {
+    const rel = relative(projectRoot, path);
+    return rel === "" ? "." : rel.split(sep).join("/");
+  };
+
+  if (args.check) {
+    let failed = 0;
+    for (const plugin of plugins) {
+      const check = await checkProjectCodegen(plugin, projectRoot, config).catch((err: unknown) => ({
+        status: "error" as const,
+        message: err instanceof Error ? err.message : String(err),
+      }));
+      if (check.status === "current") console.error(formatSuccess(`${plugin.name}: generated code is current`));
+      if ("message" in check) {
+        failed++;
+        console.error(formatError({ message: `${plugin.name}: ${check.message}` }));
+      }
+    }
+    return failed > 0 ? 1 : 0;
+  }
+
+  let written = 0;
+  for (const plugin of plugins) {
+    let result;
+    try {
+      result = await generateProjectCode(plugin, projectRoot, config);
+    } catch (err) {
+      console.error(formatError({ message: `${plugin.name}: ${err instanceof Error ? err.message : String(err)}` }));
+      return 1;
+    }
+    if (!result || result.status === "none") continue;
+    if (result.status === "removed") {
+      console.error(formatWarning({
+        message: `${plugin.name}: no sources declared, removed ${result.files.length} generated file(s) from ${show(result.outDir)}`,
+      }));
+      continue;
+    }
+    written++;
+    for (const line of result.summary) console.log(`  ${plugin.name}: ${line}`);
+    console.error(formatSuccess(`${plugin.name}: wrote ${result.files.length} file(s) to ${show(result.outDir)}`));
+  }
+
+  if (written === 0) {
+    console.error(
+      "Nothing to generate: no configured lexicon declares project sources (for example k8s.crds or helm.charts in chant.config.ts).",
+    );
+  }
+  return 0;
+}

package/src/cli/main.ts

@@ -473,6 +473,30 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace wip --branch <branch>` (#3172)
       result.branch = args[++i];
       if (!result.branch || result.branch.startsWith("-")) throw new Error("--branch needs a branch name: --branch <branch>");
+    } else if (arg === "--workflow") {
+      // `chant ci workflow --workflow <name>`, repeatable (#3573)
+      const name = args[++i];
+      if (!name || name.startsWith("-")) throw new Error("--workflow needs a workflow's name: --workflow <name>");
+      result.ciWorkflows = [...(result.ciWorkflows ?? []), name];
+    } else if (arg === "--chant") {
+      // `chant ci workflow --chant <command>` (#3573): what the tick step runs chant with.
+      result.ciChant = args[++i];
+      if (!result.ciChant || result.ciChant.startsWith("-")) throw new Error("--chant needs the command that runs chant, such as \"npx tsx packages/core/src/cli/main.ts\": --chant <command>");
+    } else if (arg === "--install") {
+      // `chant ci workflow --install <command>` (#3573): a step before the tick that installs what --chant runs.
+      result.ciInstall = args[++i];
+      if (!result.ciInstall || result.ciInstall.startsWith("-")) throw new Error("--install needs the install command, such as \"npm install\": --install <command>");
+    } else if (arg === "--token-secret") {
+      // `chant ci workflow --token-secret <NAME>` (#3573): the secret the tick's tag push authenticates with.
+      result.ciTokenSecret = args[++i];
+      if (!result.ciTokenSecret || result.ciTokenSecret.startsWith("-")) throw new Error("--token-secret needs a repository secret's name, such as CI_GREEN_TOKEN: --token-secret <NAME>");
+    } else if (arg === "--app-id-var") {
+      // `chant ci workflow --app-id-var <VAR> --app-key-secret <NAME>` (#3573): a GitHub App token pushes the tags.
+      result.ciAppIdVar = args[++i];
+      if (!result.ciAppIdVar || result.ciAppIdVar.startsWith("-")) throw new Error("--app-id-var needs the Actions variable holding the App's id: --app-id-var <VAR>");
+    } else if (arg === "--app-key-secret") {
+      result.ciAppKeySecret = args[++i];
+      if (!result.ciAppKeySecret || result.ciAppKeySecret.startsWith("-")) throw new Error("--app-key-secret needs the secret holding the App's private key: --app-key-secret <NAME>");
     } else if (arg === "--verdict") {
       // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
       result.verdict = args[++i];
@@ -796,6 +820,10 @@ Commands:
                         okf emits an OKF v0.2 knowledge bundle — one markdown
                         concept per entity + index.md; -o <dir> writes the
                         bundle tree, otherwise JSON path→content on stdout)
+  generate              Generate typed code from sources chant.config declares
+                        (k8s.crds, helm.charts) into src/generated/<lexicon>/
+                        (codegen.outDir); --check exits 1 when the committed
+                        output no longer matches its sources, as build does
   vendor                Pull pinned, checksummed patterns into your repo
                         (pull [name] | check | migrate; migrate moves
                         vendor.json into .chant/workspace.lock.json)
@@ -846,6 +874,24 @@ Commands:
                         (--json)          its target, stage (planned/emitted/bridged/
                                           applied) and path. Read-only.
 
+CI:
+  ci last-green [--json]  The newest first-parent commit of ci.green's branch
+                        with a ci/green tag and no ci/revoked tag. Reads local
+                        tags only; fetch them first.
+  ci tick [--dry-run] [--forge github]  Tag each commit within ci.green's
+                        window whose required phases all passed ci/green/<sha>,
+                        and revoke a green one that now fails ci/revoked/<sha>.
+                        Reads check runs from the forge, pushes the tags.
+  ci workflow [--workflow <name>]... [--output <file>]  Write
+              [--chant <command>] [--install <command>]
+              [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
+                        .github/workflows/chant-ci-green.yml, which runs the
+                        tick when a required workflow completes and every 15m.
+                        --chant replaces the npx @intentius/chant pin the tick
+                        runs; --install adds a step before it. --token-secret,
+                        or a GitHub App's id and key, pushes the tags with a
+                        token that may tag commits changing workflow files.
+
 Change sets:
   change-set summary <file>  The grouped plan summary of a change-set
                         [--format text|json|markdown]  document: members taking
@@ -1727,6 +1773,10 @@ export const commandRegistry: CommandDef[] = [
   // Status read over a tree of carve manifests (#2038): the contract a
   // renderer replaces its own walk-and-guess discovery with. Read-only.
   { name: "carve status", handler: runCarveStatus },
+  // #3573 — which commits passed CI, kept as ci/green and ci/revoked tags (ws-103). Imported on first use.
+  { name: "ci last-green", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiLastGreen(ctx) },
+  { name: "ci tick", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiTick(ctx) },
+  { name: "ci workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiWorkflow(ctx) },
   // #3188 — the grouped plan summary of a change-set document. Reads one file; imported on first use.
   { name: "change-set summary", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/change-set")).runChangeSetSummary(ctx) },
   { name: "init", handler: runInit, runsNoConfig: true },
@@ -1759,6 +1809,9 @@ export const commandRegistry: CommandDef[] = [
 
   { name: "graph", handler: runGraph },
   { name: "vendor", handler: runVendor },
+  // Project-local codegen: typed code from sources chant.config declares
+  // (k8s.crds, helm.charts). Imported on first use.
+  { name: "generate", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/generate")).runGenerate(ctx) },
 
   // Workspace reads (#2524). Imported on first use, so a level-0 command never
   // loads anything under workspace/ (#2525 rule 5, pinned by #2526's goldens).

package/src/cli/plugins.ts

@@ -9,6 +9,7 @@ import { isLexiconPlugin, type LexiconPlugin } from "../lexicon";
 import { loadChantConfigUpward } from "../config";
 import { findInfraFiles, detectLexicons } from "../index";
 import { checkConflicts, describeConflict } from "./conflict-check";
+import { prepareProjectCodegen } from "../project-codegen";
 
 /**
  * chant#2591 — record the lexicons the chant.config nearest `dir` declares by
@@ -194,11 +195,24 @@ export function collectBuildRootContributors(
   config: Record<string, unknown>,
   projectRoot: string,
 ): Array<import("../lexicon").BuildRootContributor> {
-  return (plugins ?? [])
+  // Project-local codegen (../project-codegen.ts) rides the same seam: every
+  // build path that renders build roots also has to refuse generated code
+  // that drifted from its declared sources, and to let the lexicon load that
+  // code (the k8s kinds its serializer must know) before serialization. Its
+  // contributor adds no entities; a drift is thrown, which the merge reports
+  // as a build error. Runs first, so a build-root hook sees loaded kinds.
+  const codegen = (plugins ?? [])
+    .filter((plugin) => typeof plugin.projectCodegen === "function")
+    .map((plugin): import("../lexicon").BuildRootContributor => async () => {
+      await prepareProjectCodegen(plugin, projectRoot, config);
+      return { entities: new Map() };
+    });
+  const roots = (plugins ?? [])
     .filter((plugin) => typeof plugin.buildRoots === "function")
     // `entities` is not bindable here — discovery has not run — so the merge
     // hands it in when it calls the closure (#1828 / SOPS provenance).
-    .map((plugin) => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities }));
+    .map((plugin): import("../lexicon").BuildRootContributor => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities }));
+  return [...codegen, ...roots];
 }
 
 /**

package/src/cli/registry.ts

@@ -394,6 +394,18 @@ export interface ParsedArgs {
   label?: string;
   /** `chant workspace wip --branch <branch>` (#3172): list one branch's snapshots. */
   branch?: string;
+  /** `chant ci workflow --workflow <name>`, repeatable (#3573): a workflow whose completion triggers a tick, beside those the scan finds. */
+  ciWorkflows?: string[];
+  /** `chant ci workflow --chant <command>` (#3573): the command the tick step runs chant with, in place of the npx pin. */
+  ciChant?: string;
+  /** `chant ci workflow --install <command>` (#3573): a step before the tick that installs what `--chant` runs. */
+  ciInstall?: string;
+  /** `chant ci workflow --token-secret <NAME>` (#3573): the repository secret the tick's tag push authenticates with. */
+  ciTokenSecret?: string;
+  /** `chant ci workflow --app-id-var <VAR>` (#3573): the Actions variable holding the GitHub App id whose token pushes the tags. */
+  ciAppIdVar?: string;
+  /** `chant ci workflow --app-key-secret <NAME>` (#3573): the secret holding that App's private key. */
+  ciAppKeySecret?: string;
   /**
    * `chant workspace records review <id> --by <principal>` (#2670): the
    * reviewer, as the caller names them. Also `chant workspace records new

package/src/codegen/json-schema-to-ts.test.ts

@@ -0,0 +1,256 @@
+import { describe, expect, test } from "vitest";
+import ts from "typescript";
+import { schemaToTypeScript, type SchemaToTsOptions } from "./json-schema-to-ts";
+
+/** The declarations plus `type Root = ...`, as a module. */
+function module(schema: unknown, options: SchemaToTsOptions = {}): string {
+  const { type, declarations } = schemaToTypeScript(schema, { rootName: "Root", ...options });
+  return [...declarations.map((d) => `type ${d.name} = ${d.type};`), `type Root = ${type};`].join("\n");
+}
+
+const libFiles = new Map<string, ts.SourceFile | undefined>();
+
+/** Type-check `code` in memory; returns the diagnostics' messages. */
+function typecheck(code: string): string[] {
+  const fileName = "/virtual/check.ts";
+  const options: ts.CompilerOptions = { strict: true, noEmit: true, target: ts.ScriptTarget.ES2022, lib: ["lib.es2022.d.ts"] };
+  const host = ts.createCompilerHost(options);
+  const getSourceFile = host.getSourceFile;
+  // The standard library parses once per file, not once per check.
+  host.getSourceFile = (name, lang, ...rest) => {
+    if (name === fileName) return ts.createSourceFile(name, code, lang);
+    if (!libFiles.has(name)) libFiles.set(name, getSourceFile.call(host, name, lang, ...rest));
+    return libFiles.get(name);
+  };
+  const program = ts.createProgram([fileName], options, host);
+  return ts
+    .getPreEmitDiagnostics(program)
+    .filter((d) => d.file?.fileName === fileName)
+    .map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"));
+}
+
+/** Whether `value` (TS source) is assignable to the schema's root type. */
+function accepts(schema: unknown, value: string, options?: SchemaToTsOptions): string[] {
+  return typecheck(`${module(schema, options)}\nexport const v: Root = ${value};\n`);
+}
+
+describe("schemaToTypeScript", () => {
+  test("scalars, arrays, type arrays and nullable", () => {
+    const { type } = schemaToTypeScript({
+      type: "object",
+      properties: {
+        s: { type: "string" },
+        i: { type: "integer" },
+        b: { type: "boolean" },
+        list: { type: "array", items: { type: "string" } },
+        maybe: { type: ["string", "null"] },
+        legacy: { type: "string", nullable: true },
+        any: {},
+      },
+    }, { openByDefault: false });
+    expect(type).toBe(
+      [
+        "{",
+        "  s?: string;",
+        "  i?: number;",
+        "  b?: boolean;",
+        "  list?: string[];",
+        "  maybe?: string | null;",
+        "  legacy?: string | null;",
+        "  any?: unknown;",
+        "}",
+      ].join("\n"),
+    );
+  });
+
+  test("required members are required unless allOptional", () => {
+    const schema = { type: "object", required: ["name"], properties: { name: { type: "string" } }, additionalProperties: false };
+    expect(schemaToTypeScript(schema).type).toContain("  name: string;");
+    expect(schemaToTypeScript(schema, { allOptional: true }).type).toContain("  name?: string;");
+    expect(accepts(schema, "{}")).not.toEqual([]);
+    expect(accepts(schema, "{}", { allOptional: true })).toEqual([]);
+  });
+
+  test("$ref into $defs and definitions becomes a named declaration", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        image: { $ref: "#/$defs/image" },
+        probe: { $ref: "#/definitions/io.k8s.api.core.v1.Probe" },
+      },
+      $defs: { image: { type: "object", properties: { tag: { type: "string" } }, additionalProperties: false } },
+      definitions: { "io.k8s.api.core.v1.Probe": { type: "object", properties: { periodSeconds: { type: "integer" } } } },
+    };
+    const { type, declarations } = schemaToTypeScript(schema, { namePrefix: "Values" });
+    expect(type).toContain("image?: ValuesImage;");
+    expect(type).toContain("probe?: ValuesIoK8sApiCoreV1Probe;");
+    expect(declarations.map((d) => d.name)).toEqual(["ValuesImage", "ValuesIoK8sApiCoreV1Probe"]);
+    expect(accepts(schema, `{ image: { tag: "1.0" }, probe: { periodSeconds: 10 } }`)).toEqual([]);
+    expect(accepts(schema, `{ image: { tga: "1.0" } }`).join("\n")).toMatch(/'tga' does not exist/);
+  });
+
+  test("recursive references terminate, including a reference to the root", () => {
+    const schema = {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        children: { type: "array", items: { $ref: "#/$defs/node" } },
+        self: { $ref: "#" },
+      },
+      $defs: {
+        node: { type: "object", additionalProperties: false, properties: { next: { $ref: "#/$defs/node" }, value: { type: "number" } } },
+      },
+    };
+    const { declarations, type } = schemaToTypeScript(schema, { rootName: "Root" });
+    expect(declarations).toHaveLength(1);
+    expect(declarations[0].type).toContain("next?: Node;");
+    expect(type).toContain("self?: Root;");
+    expect(accepts(schema, `{ children: [{ value: 1, next: { value: 2 } }], self: {} }`)).toEqual([]);
+    expect(accepts(schema, `{ children: [{ value: "x" }] }`)).not.toEqual([]);
+  });
+
+  test("keys with slashes, dots, dashes or leading digits are quoted and never renamed", () => {
+    const schema = {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        "app.kubernetes.io/name": { type: "string" },
+        "use-forwarded-headers": { type: "boolean" },
+        "2fa": { type: "boolean" },
+        snake_case: { type: "string" },
+        HTTPPort: { type: "integer" },
+      },
+    };
+    const { type } = schemaToTypeScript(schema);
+    expect(type).toContain(`"app.kubernetes.io/name"?: string;`);
+    expect(type).toContain(`"use-forwarded-headers"?: boolean;`);
+    expect(type).toContain(`"2fa"?: boolean;`);
+    expect(type).toContain(`  snake_case?: string;`);
+    expect(type).toContain(`  HTTPPort?: number;`);
+    expect(accepts(schema, `{ "app.kubernetes.io/name": "x", "use-forwarded-headers": true }`)).toEqual([]);
+  });
+
+  test("objects nested in additionalProperties maps keep their value type", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        ports: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            additionalProperties: false,
+            properties: { port: { type: "integer" }, expose: { type: "object", properties: { default: { type: "boolean" } } } },
+          },
+        },
+      },
+    };
+    const { type } = schemaToTypeScript(schema);
+    expect(type).toContain("ports?: Record<string, {");
+    expect(accepts(schema, `{ ports: { web: { port: 8000, expose: { default: true } } } }`)).toEqual([]);
+    expect(accepts(schema, `{ ports: { web: { prot: 8000 } } }`).join("\n")).toMatch(/'prot' does not exist/);
+    expect(accepts(schema, `{ ports: { web: { port: "8000" } } }`)).not.toEqual([]);
+  });
+
+  test("a map that also lists members widens its signature to cover them", () => {
+    const schema = {
+      type: "object",
+      properties: { fixed: { type: "string" } },
+      additionalProperties: { type: "number" },
+    };
+    expect(schemaToTypeScript(schema).type).toContain("[key: string]: number | string | undefined;");
+    expect(accepts(schema, `{ fixed: "a", other: 1 }`)).toEqual([]);
+  });
+
+  test("additionalProperties false closes an object; the default follows openByDefault", () => {
+    const closed = { type: "object", additionalProperties: false, properties: { a: { type: "string" } } };
+    const unspecified = { type: "object", properties: { a: { type: "string" } } };
+    expect(accepts(closed, `{ a: "x", b: 1 }`)).not.toEqual([]);
+    expect(accepts(unspecified, `{ a: "x", b: 1 }`)).toEqual([]);
+    expect(accepts(unspecified, `{ a: "x", b: 1 }`, { openByDefault: false })).not.toEqual([]);
+    // An object with no properties at all stays open either way.
+    expect(schemaToTypeScript({ type: "object" }, { openByDefault: false }).type).toBe("Record<string, unknown>");
+    expect(schemaToTypeScript({ type: "object", additionalProperties: false }).type).toBe("Record<string, never>");
+  });
+
+  test("enum and const become literal unions", () => {
+    const schema = {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        policy: { type: "string", enum: ["Always", "IfNotPresent", "Never"] },
+        level: { enum: [1, 2, null] },
+        kind: { const: "Widget" },
+      },
+    };
+    const { type } = schemaToTypeScript(schema);
+    expect(type).toContain(`policy?: "Always" | "IfNotPresent" | "Never";`);
+    expect(type).toContain(`level?: 1 | 2 | null;`);
+    expect(type).toContain(`kind?: "Widget";`);
+    expect(accepts(schema, `{ policy: "Sometimes" }`)).not.toEqual([]);
+  });
+
+  test("oneOf and anyOf become unions, allOf an intersection; constraint-only branches are ignored", () => {
+    const schema = {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        port: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        target: { anyOf: [{ $ref: "#/$defs/a" }, { type: "object", properties: { b: { type: "string" } }, additionalProperties: false }] },
+        both: { allOf: [{ type: "object", properties: { x: { type: "string" } } }, { type: "object", properties: { y: { type: "string" } } }] },
+        either: { type: "object", properties: { a: { type: "string" }, b: { type: "string" } }, oneOf: [{ required: ["a"] }, { required: ["b"] }] },
+      },
+      $defs: { a: { type: "object", properties: { a: { type: "string" } }, additionalProperties: false } },
+    };
+    const { type } = schemaToTypeScript(schema);
+    expect(type).toContain("port?: number | string;");
+    expect(type).toMatch(/target\?: A \| \{/);
+    expect(type).toMatch(/both\?: \{[\s\S]*\} & \{/);
+    expect(accepts(schema, `{ port: 80, target: { b: "x" }, both: { x: "1", y: "2" }, either: { a: "1" } }`)).toEqual([]);
+    expect(accepts(schema, `{ port: true }`)).not.toEqual([]);
+  });
+
+  test("an object base with object alternatives is intersected with their union", () => {
+    const schema = {
+      type: "object",
+      additionalProperties: false,
+      properties: { name: { type: "string" } },
+      oneOf: [
+        { type: "object", properties: { file: { type: "string" } } },
+        { type: "object", properties: { url: { type: "string" } } },
+      ],
+    };
+    const { type } = schemaToTypeScript(schema);
+    expect(type).toMatch(/^\{[\s\S]*\} & \(\{[\s\S]*\} \| \{[\s\S]*\}\)$/);
+    expect(typecheck(`${module(schema)}\nexport type T = Root;`)).toEqual([]);
+  });
+
+  test("Kubernetes int-or-string and preserve-unknown-fields", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        port: { "x-kubernetes-int-or-string": true },
+        config: { type: "object", "x-kubernetes-preserve-unknown-fields": true },
+        tuned: { type: "object", "x-kubernetes-preserve-unknown-fields": true, properties: { a: { type: "string" } } },
+      },
+    };
+    const { type } = schemaToTypeScript(schema, { openByDefault: false });
+    expect(type).toContain("port?: number | string;");
+    expect(type).toContain("config?: Record<string, unknown>;");
+    expect(type).toMatch(/tuned\?: \{\n {4}a\?: string;\n {4}\[key: string\]: unknown;/);
+  });
+
+  test("descriptions become JSDoc, with comment terminators escaped", () => {
+    const { type } = schemaToTypeScript({
+      type: "object",
+      properties: { a: { type: "string", description: "Either a | b (see */ docs)" }, b: { type: "string", description: "line one\nline two" } },
+    });
+    expect(type).toContain("/** Either a | b (see *\\/ docs) */");
+    expect(type).toContain("   * line two");
+    expect(typecheck(`type T = ${type};`)).toEqual([]);
+  });
+
+  test("a reference to another document is unknown", () => {
+    expect(schemaToTypeScript({ $ref: "https://example.com/schema.json" }).type).toBe("unknown");
+    expect(schemaToTypeScript({ $ref: "#/$defs/missing" }).type).toBe("unknown");
+  });
+});