carrick 0.3.72 → 0.3.73

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

@@ -62,6 +62,17 @@ export interface MemberOverrides {
     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.
  *
@@ -70,9 +81,19 @@ export interface MemberOverrides {
  * functions stay by name. The `seen` set (object type ids on the current
  * branch) breaks reference cycles; `depth` is a hard backstop. `overrides`
  * substitutes a type at named member positions (`MemberOverrides`); without
- * it the print is unchanged.
+ * 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, overrides?: MemberOverrides): 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,7 +29,7 @@
  * 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
@@ -65,12 +65,43 @@ function childCursor(cursor, segment) {
  * functions stay by name. The `seen` set (object type ids on the current
  * branch) breaks reference cycles; `depth` is a hard backstop. `overrides`
  * substitutes a type at named member positions (`MemberOverrides`); without
- * it the print is unchanged.
+ * it the print is unchanged. `wire` picks the representation (`WireFormat`).
  */
-export function expandTypeStructural(type, seen = new Set(), depth = 0, overrides) {
-    return expandAt(type, seen, depth, overrides ? { overrides, position: '' } : undefined);
+export function expandTypeStructural(type, seen = new Set(), depth = 0, overrides, wire = 'declared') {
+    return expandAt(type, seen, depth, overrides ? { overrides, position: '' } : undefined, wire);
 }
-function expandAt(type, seen, depth, at) {
+/**
+ * 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 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;
@@ -78,7 +109,7 @@ function expandAt(type, seen, depth, at) {
         const replacement = cursor.overrides.types.get(cursor.position);
         if (replacement) {
             cursor.overrides.applied.add(cursor.position);
-            return expandAt(replacement, seen, depth, undefined);
+            return expandAt(replacement, seen, depth, undefined, wire);
         }
         // Nothing to substitute below here: print exactly as without overrides.
         if (!hasOverrideBelow(cursor))
@@ -102,10 +133,10 @@ function expandAt(type, seen, depth, at) {
     }
     // Unions / intersections: expand each member, in canonical order.
     if (type.isUnion()) {
-        return canonicalMembers(type.getUnionTypes(), seen, depth, cursor).join(' | ');
+        return canonicalMembers(type.getUnionTypes(), seen, depth, cursor, wire).join(' | ');
     }
     if (type.isIntersection()) {
-        return canonicalMembers(type.getIntersectionTypes(), seen, depth, cursor).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.
@@ -116,7 +147,7 @@ function expandAt(type, seen, depth, at) {
         const element = type.getArrayElementType();
         if (!element)
             return namedText(type);
-        const inner = expandAt(element, seen, depth + 1, childCursor(cursor, '<0>'));
+        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,
@@ -124,6 +155,13 @@ function expandAt(type, seen, depth, at) {
         const needsParens = element.isUnion() || element.isIntersection();
         return needsParens ? `(${inner})[]` : `${inner}[]`;
     }
+    // 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.
@@ -144,7 +182,7 @@ function expandAt(type, seen, depth, at) {
         const props = type.getProperties();
         if (props.length === 0)
             return namedText(type);
-        const parts = props.map((prop) => expandProperty(prop, nextSeen, depth, cursor));
+        const parts = props.map((prop) => expandProperty(prop, nextSeen, depth, cursor, wire));
         return `{ ${parts.join('; ')}; }`;
     }
     return namedText(type);
@@ -203,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, cursor) {
-    return orderMembers(members, (member) => expandAt(member, seen, depth + 1, cursor));
+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.
@@ -213,9 +251,9 @@ function canonicalMembers(members, seen, depth, cursor) {
  * 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)
@@ -225,7 +263,7 @@ function orderMembers(members, render) {
     return rendered.map((entry) => entry.text);
 }
 /** Render a single property as `name[?]: <expanded>`. */
-function expandProperty(prop, seen, depth, at) {
+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
@@ -257,11 +295,11 @@ function expandProperty(prop, seen, depth, at) {
             propType = nonUndefined[0];
         }
         else if (nonUndefined.length > 1) {
-            const inner = canonicalMembers(nonUndefined, seen, depth, cursor).join(' | ');
+            const inner = canonicalMembers(nonUndefined, seen, depth, cursor, wire).join(' | ');
             return `${name}?: ${inner}`;
         }
     }
-    const inner = expandAt(propType, seen, depth + 1, cursor);
+    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({