@north-light/api 0.3.524 → 0.3.526

package/dist/api/command-manifest/result.d.ts

@@ -3,6 +3,8 @@ export interface DeclaredOutputShape {
     constraint: string;
     /** Named members of an `object` value. Declaring them closes the object. */
     children?: DeclaredOutputField[];
+    /** Shape of every member `children` does not declare. Absent means the object is closed. */
+    extra?: DeclaredOutputShape;
     /** Shape of each contained value of an `array` or `map` value. */
     items?: DeclaredOutputShape;
     /** Alternatives of a `union` value. */
@@ -31,7 +33,7 @@ export declare function validateDeclaredResult(output: DeclaredOutputField[], re
 } | null;
 /** Checks one JSON value against one shape, recursively: object members, array
  *  items, map values, union variants, enum values and nullability. An object that
- *  declares `children` is closed — an undeclared member is a mismatch at any
- *  depth. Returns null, or the first mismatch with its full path from `path`.
+ *  declares `children` is closed unless it carries `extra`: an undeclared
+ *  member is a mismatch at any depth, or must fit `extra`. Returns null, or the first mismatch with its full path from `path`.
  *  A declared type that is not recognized is accepted. */
 export declare function validateValue(shape: DeclaredOutputShape, value: unknown, path: string): ValueMismatch | null;

package/dist/api/command-manifest/result.js

@@ -19,8 +19,8 @@ export function validateDeclaredResult(output, result) {
 }
 /** Checks one JSON value against one shape, recursively: object members, array
  *  items, map values, union variants, enum values and nullability. An object that
- *  declares `children` is closed — an undeclared member is a mismatch at any
- *  depth. Returns null, or the first mismatch with its full path from `path`.
+ *  declares `children` is closed unless it carries `extra`: an undeclared
+ *  member is a mismatch at any depth, or must fit `extra`. Returns null, or the first mismatch with its full path from `path`.
  *  A declared type that is not recognized is accepted. */
 export function validateValue(shape, value, path) {
     const atoms = shape.type.split('|').map((part) => part.trim()).filter(Boolean);
@@ -135,8 +135,15 @@ function atomMismatch(type, shape, v, path) {
         }
         const declared = new Set(shape.children.map((member) => member.name));
         for (const key of Object.keys(v)) {
-            if (!declared.has(key))
+            if (declared.has(key))
+                continue;
+            if (shape.extra === undefined)
                 return mismatch(`${path}.${key}`, 'no such member (the object is closed)', v[key]);
+            if (v[key] === undefined)
+                continue;
+            const inner = validateValue(shape.extra, v[key], `${path}.${key}`);
+            if (inner !== null)
+                return inner;
         }
         return null;
     }

package/dist/api/command-manifest/schema.js

@@ -44,9 +44,9 @@ const PARAM_KEYS_BY_KIND = {
     stdin: new Set(['kind', 'name', 'required', 'constraint']),
     'context-file': new Set(['kind', 'name', 'required', 'constraint', 'shape']),
 };
-const OUTPUT_KEYS = new Set(['name', 'type', 'required', 'constraint', 'children', 'items', 'variants', 'values']);
+const OUTPUT_KEYS = new Set(['name', 'type', 'required', 'constraint', 'children', 'extra', 'items', 'variants', 'values']);
 /** An `items` element shape: an output field without a name or required. */
-const OUTPUT_SHAPE_KEYS = new Set(['type', 'constraint', 'children', 'items', 'variants', 'values']);
+const OUTPUT_SHAPE_KEYS = new Set(['type', 'constraint', 'children', 'extra', 'items', 'variants', 'values']);
 /** UPPER_SNAKE_CASE environment variable name — the only form an ambient default
  *  may name, so a typo'd lowercase key fails at authoring time rather than
  *  silently never resolving. */
@@ -378,6 +378,25 @@ function validateOutputShape(f, fp, topLevel, issue) {
             return null;
         children = c;
     }
+    let extra;
+    if (f['extra'] !== undefined) {
+        const raw = f['extra'];
+        const ep = `${fp}.extra`;
+        if (base !== 'object' || f['children'] === undefined) {
+            issue('command_node_invalid', `extra is only valid on an object field that declares children`, `type ${type}${f['children'] === undefined ? ' without children' : ''}`, 'type "object" with children (optionally "| null")', 'Remove extra, or declare children; an object without children already accepts any members, and a map takes items.', ep);
+            return null;
+        }
+        if (!isRecord(raw)) {
+            issue('command_node_invalid', `output extra must be an object`, typeName(raw), 'a { type, constraint, ... } shape', 'Fix the extra shape.', ep);
+            return null;
+        }
+        if (!checkKeys(raw, OUTPUT_SHAPE_KEYS, ep, issue))
+            return null;
+        const shape = validateOutputShape(raw, ep, false, issue);
+        if (shape === null)
+            return null;
+        extra = shape;
+    }
     let items;
     if (f['items'] !== undefined) {
         const raw = f['items'];
@@ -433,6 +452,7 @@ function validateOutputShape(f, fp, topLevel, issue) {
         type,
         constraint: f['constraint'],
         ...(children !== undefined ? { children } : {}),
+        ...(extra !== undefined ? { extra } : {}),
         ...(items !== undefined ? { items } : {}),
         ...(variants !== undefined ? { variants } : {}),
         ...(values !== undefined ? { values } : {}),

package/dist/api/plugin-manifest-schema.d.ts

@@ -16,6 +16,9 @@ export interface ManifestFieldShape {
     constraint: string;
     /** Named members; only when the base type is `object`. */
     children?: ManifestField[];
+    /** The shape every member not named in `children` must have; only when the base type is `object` and `children` is present.
+     *  An object with `children` and no `extra` is closed. */
+    extra?: ManifestFieldShape;
     /** Value shape; only when the base type is `array` or `map`. */
     items?: ManifestFieldShape;
     /** Alternatives; required when the base type is `union`. */

package/dist/core/help.js

@@ -327,11 +327,20 @@ function renderOutputFields(fields, indent, lines) {
         renderOutputShapeBody(f, `${indent}  `, lines);
     }
 }
+/** An open object's last row: the shape of the members it does not declare, then that shape's own body one indent deeper. */
+function renderExtraRow(shape, indent, lines) {
+    const extra = shape.extra;
+    if (extra === undefined)
+        return;
+    lines.push(`${indent}other members: ${outputTypePhrase(extra)}.${outputValuesNote(extra)}${extra.constraint.length > 0 ? ` ${extra.constraint}` : ''}`);
+    renderOutputShapeBody(extra, `${indent}  `, lines);
+}
 /** The nested part of a shape: object children, or an array element's shape. */
 function renderOutputShapeBody(shape, indent, lines) {
     if (shape.children !== undefined && shape.children.length > 0) {
         renderOutputFields(shape.children, indent, lines);
     }
+    renderExtraRow(shape, indent, lines);
     for (const variant of shape.variants ?? []) {
         const note = outputValuesNote(variant);
         lines.push(`${indent}variant: ${outputTypePhrase(variant)}.${note}${variant.constraint.length > 0 ? ` ${variant.constraint}` : ''}`);
@@ -350,6 +359,11 @@ function renderOutputShapeBody(shape, indent, lines) {
         }
         if (item.children !== undefined && item.children.length > 0) {
             renderOutputFields(item.children, indent, lines);
+            renderExtraRow(item, indent, lines);
+            return;
+        }
+        if (item.extra !== undefined) {
+            renderExtraRow(item, indent, lines);
             return;
         }
         eachWord = outputBaseType(item.type) === 'map' ? 'each value' : 'each element';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.524",
+  "version": "0.3.526",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",