@jarenjs/emit 0.72.0 → 0.72.2

package/README.md

@@ -19,7 +19,7 @@ emitTypeScript({
     role: { enum: ['admin', 'user'] },
   },
   required: ['id'],
-}, { name: 'User' });
+}, { name: 'User', banner: false });
 ```
 
 ```typescript
@@ -32,6 +32,7 @@ export interface User {
    */
   id: string;
   role?: "admin" | "user";
+  [key: string]: unknown;
 }
 ```
 
@@ -80,10 +81,10 @@ or a type so wide it certifies anything.
 
 Because Jaren owns **both sides**, that can be tested rather than trusted.
 The suite in `test/emit/agreement.test.js` takes a corpus of schemas plus
-instances, generates the declarations, writes a probe file that assigns every
-instance to its generated type, and runs `tsc` over it. Then it runs the
-compiled validator over the same instances and requires three relationships to
-hold:
+instances, checks the generated declaration fixture, and runs the compiled
+validator over those same instances. The companion `npm run test:types` gate
+runs `tsc` over assignments to that fixture. Together the gates require three
+relationships to hold:
 
 | Instance | Validator | Generated type | What a failure would mean |
 | --- | --- | --- | --- |
@@ -106,7 +107,10 @@ dropped constraint into the generated file:
 The type says `string`. The comment says the schema also demands a minimum
 length that the type does not enforce. A reader learns both. **Widening
 silently would be a lie of omission**, and it is the single most common way a
-generated type misleads the person reading it.
+generated type misleads the person reading it. Anonymous constrained nodes gain
+stable named declarations so their constraints have a documentation location;
+objects with documented members are named as well. Markdown emits those member
+notes after the declaration's table.
 
 The rig is checked against itself, too: deliberately breaking the generator so
 it emits `unknown` everywhere makes the "not wider than the schema" assertion
@@ -146,7 +150,7 @@ handler signature takes `ConfigInput`, the rest of the program handles
 `Config`, and the normalizer is the transition between them.
 
 **A twin appears only where the type actually differs.** The generator works
-that out bottom-up, so a schema with one defaulted field does not double every
+that out across the reference graph, including cycles, so a schema with one defaulted field does not double every
 declaration; everything unaffected keeps a single shared name on both sides.
 
 **Only two normalizations produce a difference.** `useDefaults` moves a member
@@ -212,6 +216,10 @@ jaren-emit --schema <file|dir> --out <dir> [options]
   --check           write nothing; exit 1 if any output is out of date
 ```
 
+Options requiring a value reject a missing value before writing. Input and
+filesystem errors are concise diagnostics with exit status 2; output drift under
+`--check` uses status 1.
+
 `--check` is the CI guard: it fails the build when a schema changed and the
 generated types did not, which is the failure mode that makes generated code
 untrustworthy in the first place.

package/dist/types/model.d.ts

@@ -68,6 +68,10 @@ export type EmitMember = {
     default?: any;
     constraints: EmitConstraint[];
     doc: string[];
+    /**
+     * - Selected extension annotations carried from the property schema
+     */
+    extensions?: Record<string, unknown>;
 };
 export type EmitDeclaration = {
     kind: 'declaration';

package/docs/EMIT-FORMAT.md

@@ -74,7 +74,9 @@ generated artifact that churns between runs cannot be reviewed in a diff.
 `name` is the property name **verbatim** — it is data, not an identifier, and
 an emitter quotes it if its target language requires that. `default` is
 present only when the source schema declares one. Members appear in the order
-the schema declared them.
+the schema declared them. Names present only in `required` are appended in that
+array's order with type `unknown`; the `properties` map is not required to
+establish member presence.
 
 ### 4.1 The extension seam
 
@@ -194,7 +196,7 @@ boundary can name them separately.
   its counterpart in `variantOf`.
 
 **A twin is emitted only when the type actually differs.** A producer computes
-that bottom-up — a type differs if anything it contains differs — so a schema
+that across reference cycles — a type differs if anything it contains differs — so a schema
 with one defaulted field does not double every declaration in the document.
 Everything unaffected is referenced by its single shared name from both sides.
 
@@ -229,6 +231,17 @@ Three consequences worth stating because each was once wrong:
 - coercion widens only nodes with a **single string-valued `type`**, because
   that is the only place `coerceToType` runs.
 
+Anonymous nodes carrying unrepresentable constraints are promoted to stable,
+named declarations so their documentation survives rendering. An anonymous
+object with documented members is named for the same reason. This can add
+helper declarations without changing the structural type. The Markdown emitter
+prints member documentation after each member table.
+
+`nullable: true` extends an explicitly declared type with `null`, matching the
+validator's extension. Literal `const`/`enum` values still satisfy the declared
+type and compose with sibling applicators; an incompatible literal cannot erase
+a type constraint.
+
 ## 8. Determinism
 
 Two compilations of the same input MUST produce byte-identical models.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/emit",
   "private": false,
-  "version": "0.72.0",
+  "version": "0.72.2",
   "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.72.0",
-    "@jarenjs/json": "^0.72.0",
-    "@jarenjs/validate": "^0.72.0"
+    "@jarenjs/core": "^0.72.2",
+    "@jarenjs/json": "^0.72.2",
+    "@jarenjs/validate": "^0.72.2"
   }
 }

package/schemas/jaren-emit-model.schema.json

@@ -64,6 +64,7 @@
         "type": { "$ref": "#/$defs/type" },
         "required": { "type": "boolean" },
         "default": { "description": "The schema default, when it declares one." },
+        "extensions": { "type": "object", "description": "Selected property extension annotations, carried verbatim." },
         "constraints": { "$ref": "#/$defs/constraints" },
         "doc": { "$ref": "#/$defs/doc" }
       }

package/src/cli.js

@@ -51,16 +51,24 @@ function parseArgs(argv) {
     defaults: false, coerce: false, suffix: 'Input',
   };
   for (let i = 2; i < argv.length; i++) {
+    const value = () => {
+      const option = argv[i];
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('-'))
+        throw new Error(`${option} requires a value`);
+      i++;
+      return next;
+    };
     switch (argv[i]) {
-      case '--schema': options.schema = argv[++i]; break;
-      case '--out': options.out = argv[++i]; break;
-      case '--target': options.target = argv[++i]; break;
-      case '--name': options.name = argv[++i]; break;
-      case '--bundle': options.bundle = argv[++i]; break;
+      case '--schema': options.schema = value(); break;
+      case '--out': options.out = value(); break;
+      case '--target': options.target = value(); break;
+      case '--name': options.name = value(); break;
+      case '--bundle': options.bundle = value(); break;
       case '--check': options.check = true; break;
       case '--defaults': options.defaults = true; break;
       case '--coerce': options.coerce = true; break;
-      case '--suffix': options.suffix = argv[++i]; break;
+      case '--suffix': options.suffix = value(); break;
       case '--help': case '-h': options.help = true; break;
       default:
         throw new Error(`unknown option: ${argv[i]}`);
@@ -203,6 +211,12 @@ function main() {
   }
 }
 
-main();
+try {
+  main();
+}
+catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 2;
+}
 
 //#endregion

package/src/markdown.js

@@ -43,6 +43,7 @@ export const MARKDOWN_STYLESHEET = {
         '| Member | Type | Required |\n| --- | --- | --- |\n',
         [{ $apply: ['$.members[*]', 'row'] }],
         '\n',
+        [{ $apply: ['$.members[?@.doc[0]]', 'memberdoc'] }],
       ],
     },
     {
@@ -55,6 +56,13 @@ export const MARKDOWN_STYLESHEET = {
         [{ $apply: ['$.required', 'yesno'] }], ' |\n'],
     },
     { mode: 'yesno', body: [{ $if: ['$', 'yes', 'no'] }] },
+    {
+      mode: 'memberdoc',
+      body: [
+        '**`', { $raw: '$.name' }, '`**\n\n',
+        [{ $apply: ['$.doc[*]', 'docline'] }],
+      ],
+    },
 
     // --- the same type vocabulary, printed as prose ---------------------
     { match: isKind('primitive'), mode: 'type', body: [{ $raw: '$.primitive' }] },

package/src/model.js

@@ -28,7 +28,7 @@
 // a private intermediate: a third-party stylesheet targets it, and `emit`'s
 // own TypeScript and Markdown emitters have no privileged access.
 
-import { isJsonObject } from '@jarenjs/core/object';
+import { isJsonObject, setObjectMember } from '@jarenjs/core/object';
 import {
   NUMERIC_CONSTRAINTS, STRING_CONSTRAINTS,
   ARRAY_CONSTRAINTS, OBJECT_CONSTRAINTS,
@@ -79,6 +79,7 @@ export const EMIT_MODEL_VERSION = '0.1';
  * @property {any} [default] - The schema default, when it declares one
  * @property {EmitConstraint[]} constraints
  * @property {string[]} doc
+ * @property {Record<string, unknown>} [extensions] - Selected extension annotations carried from the property schema
  */
 
 /**
@@ -337,7 +338,7 @@ function unionOf(types) {
  * analysis answering differently from the runtime is precisely the defect the
  * variants exist to rule out.
  *
- * Computed bottom-up and memoized, because a type differs if anything it
+ * Follows reference reachability, because a type differs if anything it
  * contains differs. A node reached while it is still being analyzed is a
  * cycle, and a cycle alone introduces no difference, so it answers `false`.
  * @param {any} node - The schema node
@@ -411,7 +412,10 @@ function normalizationChangesType(node, ctx) {
   }
 
   ctx.analyzing.delete(node);
-  memo.set(node, differs);
+  // A false answer reached through a backedge may still depend on a node
+  // whose coercible member has not been visited. Only a completed outer
+  // traversal proves false; a discovered difference is final immediately.
+  if (differs || ctx.analyzing.size === 0) memo.set(node, differs);
   return differs;
 }
 
@@ -509,9 +513,10 @@ function reserveName(ctx, preferred) {
  * @param {any} node - The schema node
  * @param {object} ctx - The compile context
  * @param {string} hint - A name to use if this node has to be hoisted
+ * @param {boolean} [documented=false] - The owning member already carries this node's own documentation
  * @returns {object} A type ref
  */
-function typeOf(node, ctx, hint) {
+function typeOf(node, ctx, hint, documented = false) {
   if (node === true || node === undefined) return T.unknown();
   if (node === false) return T.never();
   if (!isJsonObject(node)) return T.unknown();
@@ -529,6 +534,15 @@ function typeOf(node, ctx, hint) {
     return T.ref(name);
   }
 
+  // Anonymous constraints need a declaration's documentation slot. Object
+  // member documentation also needs the declaration printer: an inline
+  // object type has no member comment surface in either bundled emitter.
+  const documentedMembers = isJsonObject(node.properties)
+    && Object.values(node.properties).some((member) => isJsonObject(member)
+      && (droppedConstraints(member).length > 0
+        || (typeof member.description === 'string' && member.description.length > 0)));
+  if ((!documented && droppedConstraints(node).length > 0) || documentedMembers)
+    return declare(node, ctx, hint);
   return shapeOf(node, ctx, hint);
 }
 
@@ -671,6 +685,24 @@ function coercionCanProduce(source, type, value) {
   }
 }
 
+/** Whether a literal satisfies the explicitly declared JSON type. */
+function literalMatchesType(value, node) {
+  if (node.type === undefined) return true;
+  if (value === null && node.nullable === true) return true;
+  const types = Array.isArray(node.type) ? node.type : [node.type];
+  return types.some((type) => {
+    switch (type) {
+      case 'null': return value === null;
+      case 'object': return isJsonObject(value);
+      case 'array': return Array.isArray(value);
+      case 'integer': return typeof value === 'number' && Number.isInteger(value);
+      case 'number': return typeof value === 'number' && Number.isFinite(value);
+      case 'string': case 'boolean': return typeof value === type;
+      default: return true;
+    }
+  });
+}
+
 /** The structural shape of a schema node. */
 function shapeOf(node, ctx, hint) {
   const parts = [];
@@ -689,41 +721,38 @@ function shapeOf(node, ctx, hint) {
       parts.push(declare(target.node, ctx, target.name ?? hint));
   }
 
-  // const and enum are the most precise things a schema can say. On the
-  // accepted side the literal set still admits what the normalizer coerces
-  // INTO a member — `"2"` for an integer enum — so it widens by the source
-  // primitives that can actually reach one.
-  if (node.const !== undefined || Array.isArray(node.enum)) {
-    const values = node.const !== undefined ? [node.const] : node.enum;
-    const literals = values.map((v) => T.literal(v));
+  // Literals still satisfy the node's type and every sibling applicator.
+  // Filter the type here instead of emitting redundant `"a" & string` arms.
+  const hasLiterals = node.const !== undefined || Array.isArray(node.enum);
+  let containerLiteral = false;
+  if (hasLiterals) {
+    const values = (node.const !== undefined ? [node.const] : node.enum)
+      .filter((value) => literalMatchesType(value, node));
+    const literals = values.map((value) => T.literal(value));
+    containerLiteral = values.some((value) => isJsonObject(value) || Array.isArray(value));
     for (const source of coercionSources(node, values, ctx))
       literals.push(T.primitive(PRIMITIVES[source]));
     parts.push(unionOf(literals));
   }
-  else {
-    // allOf is intersection.
-    if (Array.isArray(node.allOf) && node.allOf.length > 0) {
-      const branches = node.allOf.map((b, i) => typeOf(b, ctx, `${hint}Part${i + 1}`));
-      const usable = branches.filter((t) => t.kind !== 'unknown');
-      if (usable.length === 1) parts.push(usable[0]);
-      else if (usable.length > 1) parts.push(T.intersection(usable));
-    }
 
-    // anyOf and oneOf are both unions at the type level. oneOf's exclusivity
-    // is a validation property with no type-level equivalent, so it widens to
-    // the same union rather than being faked. When variants are being
-    // derived, branches compile in the PLAIN universe: the runtime
-    // normalizer does not descend them (see createPlainContext).
-    for (const key of ['anyOf', 'oneOf']) {
-      if (Array.isArray(node[key]) && node[key].length > 0) {
-        const branchCtx = ctx.normalize === null
-          ? ctx
-          : (ctx.plain ??= createPlainContext(ctx));
-        parts.push(unionOf(node[key].map((b, i) =>
-          typeOf(b, branchCtx, `${hint}${toIdentifier(key)}${i + 1}`))));
-      }
+  if (Array.isArray(node.allOf) && node.allOf.length > 0) {
+    const branches = node.allOf.map((branch, i) => typeOf(branch, ctx, `${hint}Part${i + 1}`));
+    const usable = branches.filter((type) => type.kind !== 'unknown');
+    if (usable.length === 1) parts.push(usable[0]);
+    else if (usable.length > 1) parts.push(T.intersection(usable));
+  }
+
+  // The normalizer does not descend union branches, so both variants use
+  // the plain schema reading of those branches.
+  for (const key of ['anyOf', 'oneOf']) {
+    if (Array.isArray(node[key]) && node[key].length > 0) {
+      const branchCtx = ctx.normalize === null ? ctx : (ctx.plain ??= createPlainContext(ctx));
+      parts.push(unionOf(node[key].map((branch, i) =>
+        typeOf(branch, branchCtx, `${hint}${toIdentifier(key)}${i + 1}`))));
     }
+  }
 
+  if (!hasLiterals || containerLiteral) {
     const own = ownShape(node, ctx, hint);
     if (own !== null) parts.push(own);
   }
@@ -742,7 +771,8 @@ function ownShape(node, ctx, hint) {
 
   const hasObjectKeywords = node.properties !== undefined
     || node.patternProperties !== undefined
-    || node.additionalProperties !== undefined;
+    || node.additionalProperties !== undefined
+    || Array.isArray(node.required);
   const hasArrayKeywords = node.items !== undefined || node.prefixItems !== undefined;
 
   // No `type`: the applicator keywords describe the container cases, but
@@ -786,6 +816,7 @@ function ownShape(node, ctx, hint) {
     }
     else alternatives.push(T.unknown());
   }
+  if (node.nullable === true) alternatives.push(T.primitive('null'));
   return unionOf(alternatives);
 }
 
@@ -812,7 +843,7 @@ function objectShape(node, ctx, hint) {
       const member = {
         kind: 'member',
         name: key,
-        type: typeOf(sub, ctx, `${hint}${toIdentifier(key)}`),
+        type: typeOf(sub, ctx, `${hint}${toIdentifier(key)}`, true),
         required: defaulted
           ? ctx.variant !== 'accepted'
           : declaredRequired,
@@ -828,7 +859,7 @@ function objectShape(node, ctx, hint) {
         for (const keyword of declaredExtensions) {
           if (subNode[keyword] === undefined) continue;
           if (carried === null) carried = {};
-          carried[keyword] = subNode[keyword];
+          setObjectMember(carried, keyword, subNode[keyword]);
         }
         if (carried !== null) member.extensions = carried;
       }
@@ -836,6 +867,13 @@ function objectShape(node, ctx, hint) {
     }
   }
 
+  // `required` owns presence independently of `properties`. A required
+  // undeclared member has no narrower named schema to infer here.
+  for (const key of required) {
+    if (members.some((member) => member.name === key)) continue;
+    members.push({ kind: 'member', name: key, type: T.unknown(), required: true, constraints: [], doc: [] });
+  }
+
   // An index signature comes from additionalProperties or patternProperties.
   // `additionalProperties: false` is the closed case and adds nothing; `true`
   // or a schema opens the object up.