@jarenjs/emit 0.56.0 → 0.67.0

package/README.md

@@ -216,6 +216,10 @@ jaren-emit --schema <file|dir> --out <dir> [options]
 generated types did not, which is the failure mode that makes generated code
 untrustworthy in the first place.
 
+Outside bundle mode, schema names must produce distinct output filenames.
+Names such as `user-account.json` and `user_account.json` both become
+`UserAccount.d.ts`; the CLI refuses that collision with exit 2 before writing.
+
 `--bundle` compiles every schema into **one name space**: a `$defs.Id` that
 two schemas both declare comes out as `Id` and `Id2`, deterministically in
 sorted-file order, instead of two colliding declarations. The programmatic
@@ -228,9 +232,9 @@ equivalent is the `reserved` option of `compileEmitModel`.
 | `type: 'string' \| 'number' \| 'integer' \| 'boolean' \| 'null'` | the primitive (`integer` → `number`) |
 | `const` / `enum` | a literal / a union of literals |
 | `properties` + `required` | interface members, optional when not required |
-| `additionalProperties` / `patternProperties` | an index signature, widened to cover the declared members |
+| `additionalProperties` / `patternProperties` | an index signature combining their value types, widened to cover the declared members |
 | *omitted* `additionalProperties` | `[key: string]: unknown` — the object is **open**, see below |
-| `additionalProperties: false` | a closed interface, with no index signature; with no members at all, `Record<string, never>` (an empty interface would let a primitive through) |
+| `additionalProperties: false` | a closed interface unless `patternProperties` supplies an index signature; with no members or patterns, `Record<string, never>` (an empty interface would let a primitive through) |
 | `items` | `Array<T>` |
 | `prefixItems`, array-form `items` | a tuple: the first `minItems` positions required, the rest optional, and an **open** rest (`...Array<unknown>`) unless `items: false`/`additionalItems: false` closes it — JSON Schema accepts shorter and longer arrays, so the type does too |
 | `$ref` (same document, including cycles) | a reference to the named declaration — `#/pointer` and plain `#anchor` forms, resolving exactly as `compileNormalizer` resolves them; a root `$ref` aliases its target, and 2019-09+ siblings intersect with it |
@@ -245,7 +249,10 @@ equivalent is the `reserved` option of `compileEmitModel`.
 A JSON Schema object accepts members it never declared. That is the default,
 and it is easy to forget when reading a schema that lists four properties and
 looks like a struct. So an interface generated from one carries an index
-signature, and only `additionalProperties: false` removes it.
+signature. `additionalProperties: false` removes it unless `patternProperties`
+still permits matching names. When patterns and typed additional properties
+coexist, the index includes both value types; TypeScript cannot restrict each
+type to the names that JSON Schema assigns it.
 
 This costs something real: with an index signature TypeScript stops flagging a
 misspelled property, because the misspelling is a legal member. The trade is
@@ -292,6 +299,55 @@ theirs. If your schemas are documents — published, shared with other
 languages, or fed to an LLM's structured-output mode — this is the one that
 fits.
 
+## Exports
+
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.emit-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/emit` | JavaScript | declared |
+| `@jarenjs/emit/model` | JavaScript | declared |
+| `@jarenjs/emit/typescript` | JavaScript | declared |
+| `@jarenjs/emit/markdown` | JavaScript | declared |
+| `@jarenjs/emit/schemas/jaren-emit-model.schema.json` | schema | — |
+| `@jarenjs/emit/package.json` | metadata | — |
+<!--/fact-->
+
+What each family is for, and what it costs:
+
+- **The root** re-exports the three routes below, so `import { emitTypeScript }
+  from '@jarenjs/emit'` is the whole package. Reach for a subpath when a
+  bundle should carry one target only.
+- **`./model`** is the published intermediate stage
+  ([EMIT-FORMAT](docs/EMIT-FORMAT.md)): `compileEmitModel(schema, options)`
+  turns a JSON Schema into a `jaren-emit` model document — every type
+  resolved, every union normalized, every constraint the target cannot
+  express listed — and `EMIT_MODEL_VERSION` names the document version it
+  writes. It is the route a *new* target starts from: a stylesheet over
+  the model is a generator, and the model is what the TypeScript and
+  Markdown routes both read. It imports the validator's schema
+  normalizer, so it is the heaviest of the three by itself.
+- **`./typescript`**: `emitTypeScript(schema, options)` is schema → model →
+  declaration text in one call; `renderTypeScript(model, options)` renders a
+  model you already compiled (the CLI compiles once and renders per target
+  this way); `TYPESCRIPT_STYLESHEET` is the JTLT document doing the
+  rendering, exported so a host can extend it rather than fork it.
+- **`./markdown`**: `emitMarkdown`, `renderMarkdown` and
+  `MARKDOWN_STYLESHEET` — the same three shapes, emitting a reference
+  document instead of a declaration file.
+- **`./schemas/*`** is the JSON Schema of the model document itself
+  (`jaren-emit-model.schema.json`): validate a model you stored or wrote
+  by hand against it before rendering, or hand it to an editor for
+  completion. It is JSON, not code — no declaration rides with it.
+- **`./package.json`** is metadata: the version a tool may read, nothing
+  a program imports.
+
+The `jaren-emit` CLI (`bin`) is not an export — it is the command the
+package installs, and it uses `./typescript` and `./markdown` exactly as a
+program would.
+
 ## Development
 
 Tests live in `test/emit/` at the repository root (`npm run test:emit`).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/emit",
   "private": false,
-  "version": "0.56.0",
+  "version": "0.67.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -68,8 +68,8 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.56.0",
-    "@jarenjs/json": "^0.56.0",
-    "@jarenjs/validate": "^0.56.0"
+    "@jarenjs/core": "^0.67.0",
+    "@jarenjs/json": "^0.67.0",
+    "@jarenjs/validate": "^0.67.0"
   }
 }

package/src/cli.js

@@ -143,6 +143,23 @@ function main() {
     return;
   }
 
+  // Validate the whole output plan before writing: different schema names
+  // can collapse onto the same PascalCase filename.
+  if (options.bundle === null) {
+    const destinations = new Map();
+    for (const file of files) {
+      const out = path.join(options.out, nameFromFile(file) + target.extension);
+      const destination = process.platform === 'win32' ? out.toLowerCase() : out;
+      const previous = destinations.get(destination);
+      if (previous !== undefined) {
+        console.error(`output collision: '${previous}' and '${file}' both write '${out}'`);
+        process.exit(2);
+        return;
+      }
+      destinations.set(destination, file);
+    }
+  }
+
   // Only pass normalize options when at least one is on: a null here is what
   // tells the model to emit a single declaration per type rather than a pair.
   const normalizeOptions = options.defaults || options.coerce

package/src/model.js

@@ -851,11 +851,15 @@ function objectShape(node, ctx, hint) {
     // unsound type for a consumer who prefers excess-property checking.
     index = T.unknown();
   }
-  else if (isJsonObject(node.patternProperties)) {
+  // Matching names are governed by their pattern schemas, not by
+  // additionalProperties. A typed additional index must therefore include
+  // those values too; an unknown index already covers every pattern.
+  if (index?.kind !== 'unknown' && isJsonObject(node.patternProperties)) {
     const patterns = Object.getOwnPropertyNames(node.patternProperties);
     if (patterns.length > 0) {
-      index = unionOf(patterns.map((p, i) =>
-        typeOf(node.patternProperties[p], ctx, `${hint}Pattern${i + 1}`)));
+      const patternTypes = patterns.map((p, i) =>
+        typeOf(node.patternProperties[p], ctx, `${hint}Pattern${i + 1}`));
+      index = unionOf(index === null ? patternTypes : [index, ...patternTypes]);
     }
   }