carrick 0.3.70 → 0.3.73

package/sidecar/dist/src/type-structural-expander.d.ts

@@ -28,22 +28,72 @@
  * `type-inferrer.ts` (consumer-side inference), so both paths emit the same
  * structural form rather than a dangling name.
  */
-import { type Type } from 'ts-morph';
+import { type Node, type Type } from 'ts-morph';
 /**
  * Bound on the structural-expansion recursion. Deep enough for every realistic
  * request/response shape; a backstop against pathological/recursive types the
  * cycle set somehow misses.
  */
 export declare const MAX_EXPANSION_DEPTH = 12;
+/**
+ * Types to print at named member positions instead of the walked type
+ * (carrick#1105).
+ *
+ * A validation schema's request contract is its INPUT, except at a member
+ * whose input is `unknown` and whose output is concrete (a coercion): that
+ * member prints the OUTPUT type. The substitution is per member, so it has to
+ * happen inside the walk, where the member is printed.
+ *
+ * Positions use the member-path notation of the provenance entries: `''` for
+ * the root, `sub.field` for a property (keyed by symbol name), `items<0>` for
+ * an array element; union and intersection members share their parent's
+ * position. The walk records every position it printed an override at in
+ * `applied`, so a caller can tell a substitution the walk could not reach (a
+ * tuple, a cycle, the depth backstop) from one it made.
+ *
+ * `at` is the node the member types are read at while walking toward an
+ * override. A library's inferred object type is a mapped type whose member
+ * declaration sits inside a generic, where the member reads as `any`; read at
+ * the schema's own node it is the instantiated type, the same read the
+ * caller's position walk makes.
+ */
+export interface MemberOverrides {
+    readonly types: ReadonlyMap<string, Type>;
+    readonly applied: Set<string>;
+    readonly at: Node;
+}
+/**
+ * The representation a type is printed in.
+ *
+ * `'declared'` prints the type the source declares. `'json'` prints what a
+ * JSON serialiser puts on the wire for a value of that type (carrick#1163):
+ * `JSON.stringify` calls a value's `toJSON()` and serialises its RESULT, so a
+ * `Date` travels as the string its `toJSON` returns, and so does any other
+ * type that declares one. The mapping is read from the compiler's own
+ * signature, never from a list of type names.
+ */
+export type WireFormat = 'declared' | 'json';
 /**
  * Recursively render a `Type` as fully-inlined structural text.
  *
  * Named object/interface types are expanded to their member structure;
  * primitives, literals, library types (`Date`, `Promise`, tuples, …) and
  * functions stay by name. The `seen` set (object type ids on the current
- * branch) breaks reference cycles; `depth` is a hard backstop.
+ * branch) breaks reference cycles; `depth` is a hard backstop. `overrides`
+ * substitutes a type at named member positions (`MemberOverrides`); without
+ * it the print is unchanged. `wire` picks the representation (`WireFormat`).
+ */
+export declare function expandTypeStructural(type: Type, seen?: Set<number>, depth?: number, overrides?: MemberOverrides, wire?: WireFormat): string;
+/**
+ * The type `JSON.stringify` serialises in place of a value of `type`: the
+ * return type of the value's own `toJSON()`, or `undefined` when it declares
+ * none (carrick#1163).
+ *
+ * Only a callable `toJSON` member counts, and only a return type that says
+ * something: an `any` return describes nothing, and a `toJSON` that returns
+ * its own type again maps nothing either.
  */
-export declare function expandTypeStructural(type: Type, seen?: Set<number>, depth?: number): string;
+export declare function jsonWireType(type: Type): Type | undefined;
 /**
  * Non-expanded text for a type. Passes `undefined` as the enclosing node so
  * the compiler can't throw on an invalid node context (tuples and some

package/sidecar/dist/src/type-structural-expander.js

@@ -29,24 +29,92 @@
  * structural form rather than a dangling name.
  */
 import { ts } from 'ts-morph';
-import { canonicalizeUnionsInText } from './type-text-canonicalizer.js';
+import { canonicalizeUnionsInText, foldBooleanLiterals, } from './type-text-canonicalizer.js';
 /**
  * Bound on the structural-expansion recursion. Deep enough for every realistic
  * request/response shape; a backstop against pathological/recursive types the
  * cycle set somehow misses.
  */
 export const MAX_EXPANSION_DEPTH = 12;
+/** True when some override sits strictly below `position`. */
+function hasOverrideBelow({ overrides, position }) {
+    for (const key of overrides.types.keys()) {
+        if (position === ''
+            ? key !== ''
+            : key.startsWith(`${position}.`) || key.startsWith(`${position}<`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function childCursor(cursor, segment) {
+    if (!cursor)
+        return undefined;
+    const position = segment.startsWith('<')
+        ? `${cursor.position}${segment}`
+        : cursor.position === ''
+            ? segment
+            : `${cursor.position}.${segment}`;
+    return { overrides: cursor.overrides, position };
+}
 /**
  * Recursively render a `Type` as fully-inlined structural text.
  *
  * Named object/interface types are expanded to their member structure;
  * primitives, literals, library types (`Date`, `Promise`, tuples, …) and
  * functions stay by name. The `seen` set (object type ids on the current
- * branch) breaks reference cycles; `depth` is a hard backstop.
+ * branch) breaks reference cycles; `depth` is a hard backstop. `overrides`
+ * substitutes a type at named member positions (`MemberOverrides`); without
+ * it the print is unchanged. `wire` picks the representation (`WireFormat`).
+ */
+export function expandTypeStructural(type, seen = new Set(), depth = 0, overrides, wire = 'declared') {
+    return expandAt(type, seen, depth, overrides ? { overrides, position: '' } : undefined, wire);
+}
+/**
+ * The type `JSON.stringify` serialises in place of a value of `type`: the
+ * return type of the value's own `toJSON()`, or `undefined` when it declares
+ * none (carrick#1163).
+ *
+ * Only a callable `toJSON` member counts, and only a return type that says
+ * something: an `any` return describes nothing, and a `toJSON` that returns
+ * its own type again maps nothing either.
  */
-export function expandTypeStructural(type, seen = new Set(), depth = 0) {
+export function jsonWireType(type) {
+    if (!type.isObject() || type.isArray() || isTuple(type))
+        return undefined;
+    const member = type.getProperty('toJSON');
+    if (!member)
+        return undefined;
+    const declaration = member.getValueDeclaration() ?? member.getDeclarations()[0];
+    const memberType = declaration
+        ? member.getTypeAtLocation(declaration)
+        : member.getDeclaredType();
+    const signature = memberType.getCallSignatures()[0];
+    if (!signature)
+        return undefined;
+    const serialised = signature.getReturnType();
+    if (serialised.isAny() || serialised.isUnknown())
+        return undefined;
+    const id = type.compilerType.id;
+    const serialisedId = serialised.compilerType.id;
+    if (id != null && id === serialisedId)
+        return undefined;
+    return serialised;
+}
+function expandAt(type, seen, depth, at, wire) {
     if (depth > MAX_EXPANSION_DEPTH)
         return backstopText(type);
+    let cursor = at;
+    if (cursor) {
+        const replacement = cursor.overrides.types.get(cursor.position);
+        if (replacement) {
+            cursor.overrides.applied.add(cursor.position);
+            return expandAt(replacement, seen, depth, undefined, wire);
+        }
+        // Nothing to substitute below here: print exactly as without overrides.
+        if (!hasOverrideBelow(cursor))
+            cursor = undefined;
+    }
     // Primitives & literals: nothing to inline.
     if (type.isString() ||
         type.isNumber() ||
@@ -65,10 +133,10 @@ export function expandTypeStructural(type, seen = new Set(), depth = 0) {
     }
     // Unions / intersections: expand each member, in canonical order.
     if (type.isUnion()) {
-        return canonicalMembers(type.getUnionTypes(), seen, depth).join(' | ');
+        return canonicalMembers(type.getUnionTypes(), seen, depth, cursor, wire).join(' | ');
     }
     if (type.isIntersection()) {
-        return canonicalMembers(type.getIntersectionTypes(), seen, depth).join(' & ');
+        return canonicalMembers(type.getIntersectionTypes(), seen, depth, cursor, wire).join(' & ');
     }
     // Tuples are array-like but must keep their `[a, b]` shape, not be walked
     // as objects (which explodes into `Array.prototype`). Handle before arrays.
@@ -79,7 +147,7 @@ export function expandTypeStructural(type, seen = new Set(), depth = 0) {
         const element = type.getArrayElementType();
         if (!element)
             return namedText(type);
-        const inner = expandTypeStructural(element, seen, depth + 1);
+        const inner = expandAt(element, seen, depth + 1, childCursor(cursor, '<0>'), wire);
         // Parenthesise a union/intersection element so `(A | B)[]` doesn't misparse
         // as `A | B[]`. Decide from the TYPE, not the string: a single object
         // literal like `{ a: A | B }` is NOT a union and must not be parenthesised,
@@ -87,8 +155,17 @@ export function expandTypeStructural(type, seen = new Set(), depth = 0) {
         const needsParens = element.isUnion() || element.isIntersection();
         return needsParens ? `(${inner})[]` : `${inner}[]`;
     }
-    // Library / built-in types (Date, Promise, RegExp, …): keep by name.
-    if (isLibraryType(type)) {
+    // On the JSON wire a value with `toJSON()` is its serialised form, library
+    // type or not, so this runs before the by-name bail-out below.
+    if (wire === 'json') {
+        const serialised = jsonWireType(type);
+        if (serialised)
+            return expandAt(serialised, seen, depth + 1, undefined, wire);
+    }
+    // Library / built-in types (Date, Promise, RegExp, …): keep by name, unless
+    // a member below has to be substituted — a schema library declares its
+    // inferred object types itself, and they are only walkable, not by-name.
+    if (!cursor && isLibraryType(type)) {
         return namedText(type);
     }
     // Callable/constructable object types (functions): keep by name; their
@@ -105,7 +182,7 @@ export function expandTypeStructural(type, seen = new Set(), depth = 0) {
         const props = type.getProperties();
         if (props.length === 0)
             return namedText(type);
-        const parts = props.map((prop) => expandProperty(prop, nextSeen, depth));
+        const parts = props.map((prop) => expandProperty(prop, nextSeen, depth, cursor, wire));
         return `{ ${parts.join('; ')}; }`;
     }
     return namedText(type);
@@ -164,8 +241,8 @@ function backstopText(type) {
  * Ties can only happen between two members that render identically, in which
  * case the joined output is the same whichever way round they go.
  */
-function canonicalMembers(members, seen, depth) {
-    return orderMembers(members, (member) => expandTypeStructural(member, seen, depth + 1));
+function canonicalMembers(members, seen, depth, cursor, wire) {
+    return orderMembers(members, (member) => expandAt(member, seen, depth + 1, cursor, wire));
 }
 /**
  * The canonical order itself, over whatever text `render` gives each member.
@@ -174,9 +251,9 @@ function canonicalMembers(members, seen, depth) {
  * cannot be ordered two ways depending on how deep it sits.
  */
 function orderMembers(members, render) {
-    const rendered = members.map((member, index) => ({
+    const rendered = foldBooleanLiterals(members.map(render)).map((text, index) => ({
         index,
-        text: render(member),
+        text,
     }));
     rendered.sort((a, b) => {
         if (a.text !== b.text)
@@ -186,16 +263,28 @@ function orderMembers(members, render) {
     return rendered.map((entry) => entry.text);
 }
 /** Render a single property as `name[?]: <expanded>`. */
-function expandProperty(prop, seen, depth) {
+function expandProperty(prop, seen, depth, at, wire) {
     const optional = (prop.getFlags() & ts.SymbolFlags.Optional) !== 0;
     const propDecl = prop.getDeclarations()[0];
     // Render the key from the declaration's name node so quoted/computed keys
     // ('x-y', "x y", [Symbol.iterator]) survive as valid TS text rather than
     // being unquoted into invalid output; fall back to the bare symbol name.
     const name = renderPropertyName(prop, propDecl);
-    let propType = propDecl
-        ? prop.getTypeAtLocation(propDecl)
-        : prop.getDeclaredType();
+    let propType = at
+        ? prop.getTypeAtLocation(at.overrides.at)
+        : propDecl
+            ? prop.getTypeAtLocation(propDecl)
+            : prop.getDeclaredType();
+    // A substituted member takes the override's TYPE but keeps this key's
+    // optionality, and is looked up before the `undefined` strip below so an
+    // override that carries `| undefined` strips like any other optional key.
+    let cursor = childCursor(at, prop.getName());
+    const replacement = cursor && cursor.overrides.types.get(cursor.position);
+    if (cursor && replacement) {
+        cursor.overrides.applied.add(cursor.position);
+        propType = replacement;
+        cursor = undefined;
+    }
     // An optional property's type includes `undefined`; the structural label
     // drops it (`note?: string`, not `note?: string | undefined`).
     if (optional && propType.isUnion()) {
@@ -206,11 +295,11 @@ function expandProperty(prop, seen, depth) {
             propType = nonUndefined[0];
         }
         else if (nonUndefined.length > 1) {
-            const inner = canonicalMembers(nonUndefined, seen, depth).join(' | ');
+            const inner = canonicalMembers(nonUndefined, seen, depth, cursor, wire).join(' | ');
             return `${name}?: ${inner}`;
         }
     }
-    const inner = expandTypeStructural(propType, seen, depth + 1);
+    const inner = expandAt(propType, seen, depth + 1, cursor, wire);
     return `${name}${optional ? '?' : ''}: ${inner}`;
 }
 /**

package/sidecar/dist/src/type-text-canonicalizer.d.ts

@@ -38,3 +38,17 @@
  * a definition resolve must not fail because one member confused a scanner.
  */
 export declare function canonicalizeUnionsInText(text: string): string;
+/**
+ * A union's rendered members with the literal pair `false`, `true` folded into
+ * `boolean` (carrick#1165).
+ *
+ * The compiler stores `boolean` as exactly that pair, and its own printer folds
+ * it back. Anything that renders a union member by member — the structural
+ * walk, and this file's reordering of a compiler print — sees the two literals
+ * separately, and sorting them apart produced `false | null | true` for
+ * `boolean | null`. Folding before the sort gives the one print a reader and a
+ * diff expect. A lone literal is a literal type and is kept. Shared by
+ * `orderMembers` in `type-structural-expander.ts`, so both halves of the normal
+ * form fold the same way.
+ */
+export declare function foldBooleanLiterals(members: string[]): string[];

package/sidecar/dist/src/type-text-canonicalizer.js

@@ -156,8 +156,8 @@ function canonicalizeMember(member) {
  * the compiler rendered it.
  */
 function orderTextMembers(members) {
-    return members
-        .map((text, index) => ({ text: text.trim(), index }))
+    return foldBooleanLiterals(members.map((text) => text.trim()))
+        .map((text, index) => ({ text, index }))
         .sort((a, b) => {
         if (a.text !== b.text)
             return a.text < b.text ? -1 : 1;
@@ -165,6 +165,27 @@ function orderTextMembers(members) {
     })
         .map((entry) => entry.text);
 }
+/**
+ * A union's rendered members with the literal pair `false`, `true` folded into
+ * `boolean` (carrick#1165).
+ *
+ * The compiler stores `boolean` as exactly that pair, and its own printer folds
+ * it back. Anything that renders a union member by member — the structural
+ * walk, and this file's reordering of a compiler print — sees the two literals
+ * separately, and sorting them apart produced `false | null | true` for
+ * `boolean | null`. Folding before the sort gives the one print a reader and a
+ * diff expect. A lone literal is a literal type and is kept. Shared by
+ * `orderMembers` in `type-structural-expander.ts`, so both halves of the normal
+ * form fold the same way.
+ */
+export function foldBooleanLiterals(members) {
+    const falseAt = members.indexOf('false');
+    const trueAt = members.indexOf('true');
+    if (falseAt === -1 || trueAt === -1)
+        return members;
+    const rest = members.filter((member) => member !== 'false' && member !== 'true');
+    return rest.includes('boolean') ? rest : [...rest, 'boolean'];
+}
 /**
  * The spans between depth-zero occurrences of `separator`. Depth counts the
  * four bracket pairs; quoted runs are skipped whole, so a separator inside a

package/sidecar/dist/src/validators.d.ts

@@ -415,16 +415,19 @@ export declare const CaptureV2RequestSchema: z.ZodObject<{
         alias: z.ZodString;
         type_text: z.ZodString;
         anchor_origin: z.ZodEnum<["llm-symbol", "deterministic-infer", "anchor-backfill"]>;
+        source_file: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         kind: "literal";
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill";
         type_text: string;
+        source_file?: string | undefined;
     }, {
         kind: "literal";
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill";
         type_text: string;
+        source_file?: string | undefined;
     }>]>, "many">;
     out_dir: z.ZodString;
     tsconfig_path: z.ZodOptional<z.ZodString>;
@@ -461,6 +464,7 @@ export declare const CaptureV2RequestSchema: z.ZodObject<{
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill";
         type_text: string;
+        source_file?: string | undefined;
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;
@@ -497,6 +501,7 @@ export declare const CaptureV2RequestSchema: z.ZodObject<{
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill";
         type_text: string;
+        source_file?: string | undefined;
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;
@@ -1476,16 +1481,19 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         alias: z.ZodString;
         type_text: z.ZodString;
         anchor_origin: z.ZodEnum<["llm-symbol", "deterministic-infer", "anchor-backfill"]>;
+        source_file: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         kind: "literal";
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill";
         type_text: string;
+        source_file?: string | undefined;
     }, {
         kind: "literal";
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill";
         type_text: string;
+        source_file?: string | undefined;
     }>]>, "many">;
     out_dir: z.ZodString;
     tsconfig_path: z.ZodOptional<z.ZodString>;
@@ -1522,6 +1530,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill";
         type_text: string;
+        source_file?: string | undefined;
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;
@@ -1558,6 +1567,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill";
         type_text: string;
+        source_file?: string | undefined;
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;

package/sidecar/dist/src/validators.js

@@ -219,6 +219,7 @@ const CaptureAnchorRequestSchema = z.discriminatedUnion('kind', [
         alias: z.string().min(1),
         type_text: z.string().min(1),
         anchor_origin: AnchorOriginSchema,
+        source_file: z.string().min(1).optional(),
     }),
 ]);
 export const CaptureV2RequestSchema = BaseRequestSchema.extend({