carrick 0.3.70 → 0.3.72

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

@@ -36,17 +36,54 @@ import { canonicalizeUnionsInText } from './type-text-canonicalizer.js';
  * 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.
  */
-export function expandTypeStructural(type, seen = new Set(), depth = 0) {
+export function expandTypeStructural(type, seen = new Set(), depth = 0, overrides) {
+    return expandAt(type, seen, depth, overrides ? { overrides, position: '' } : undefined);
+}
+function expandAt(type, seen, depth, at) {
     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);
+        }
+        // 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 +102,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).join(' | ');
     }
     if (type.isIntersection()) {
-        return canonicalMembers(type.getIntersectionTypes(), seen, depth).join(' & ');
+        return canonicalMembers(type.getIntersectionTypes(), seen, depth, cursor).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 +116,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>'));
         // 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 +124,10 @@ 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)) {
+    // 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 +144,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));
         return `{ ${parts.join('; ')}; }`;
     }
     return namedText(type);
@@ -164,8 +203,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) {
+    return orderMembers(members, (member) => expandAt(member, seen, depth + 1, cursor));
 }
 /**
  * The canonical order itself, over whatever text `render` gives each member.
@@ -186,16 +225,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) {
     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 +257,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).join(' | ');
             return `${name}?: ${inner}`;
         }
     }
-    const inner = expandTypeStructural(propType, seen, depth + 1);
+    const inner = expandAt(propType, seen, depth + 1, cursor);
     return `${name}${optional ? '?' : ''}: ${inner}`;
 }
 /**