carrick 0.3.53

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

@@ -0,0 +1,61 @@
+/**
+ * Structural type expansion — renders a ts-morph `Type` as fully-inlined
+ * structural text, with every named object/interface member expanded to its
+ * member structure recursively.
+ *
+ * `Type.getText()` does NOT inline named members: the compiler prints a
+ * referenced type by its symbol name when that symbol is in scope
+ * (`total: Money`, not `total: { amountCents: number; currency: string }`).
+ * That is fine inside a single project, but a cross-repo bundle carries only
+ * the alias lines — no source declarations — so a named reference is a
+ * dangling identifier that resolves to `any` downstream. Expanding the shape
+ * structurally puts the real members in the bundle so the type checker can
+ * compare them.
+ *
+ * Object/interface types are expanded to their members; primitives, literals,
+ * library types (`Date`, `Promise`, tuples, …) and functions stay by name.
+ * Bounded recursion + a per-branch cycle set guard against blow-ups; any type
+ * that can't be safely expanded falls back to the non-expanded text rather
+ * than throwing.
+ *
+ * Union and intersection members are printed in a canonical order that does not
+ * depend on when the checker created each member type — see `orderMembers`
+ * (carrick#735), which the depth backstop applies too, and which `namedText`
+ * applies as text to everything the walk hands back to the compiler's own
+ * print (carrick#775).
+ *
+ * Shared by `definition-resolver.ts` (bundle alias resolution) and
+ * `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';
+/**
+ * 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;
+/**
+ * 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.
+ */
+export declare function expandTypeStructural(type: Type, seen?: Set<number>, depth?: number): string;
+/**
+ * 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
+ * generic instantiations do), falling back to the bare `getText()` and
+ * finally to `unknown` so a single bad type never aborts the whole resolve.
+ *
+ * This is the ONE place the walk hands a subtree back to the compiler's own
+ * print — for a library type, a type with no properties to walk, a tuple, a
+ * function, a cycle, or the depth backstop. Everything inside that print is in
+ * type-id order, which is creation order, so the unions it contains are put in
+ * the same canonical order the walk gives the ones it renders itself
+ * (carrick#775). Doing it here rather than at each caller means no bail-out
+ * path can print a union one way while the walk prints it another.
+ */
+export declare function namedText(type: Type): string;

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

@@ -0,0 +1,283 @@
+/**
+ * Structural type expansion — renders a ts-morph `Type` as fully-inlined
+ * structural text, with every named object/interface member expanded to its
+ * member structure recursively.
+ *
+ * `Type.getText()` does NOT inline named members: the compiler prints a
+ * referenced type by its symbol name when that symbol is in scope
+ * (`total: Money`, not `total: { amountCents: number; currency: string }`).
+ * That is fine inside a single project, but a cross-repo bundle carries only
+ * the alias lines — no source declarations — so a named reference is a
+ * dangling identifier that resolves to `any` downstream. Expanding the shape
+ * structurally puts the real members in the bundle so the type checker can
+ * compare them.
+ *
+ * Object/interface types are expanded to their members; primitives, literals,
+ * library types (`Date`, `Promise`, tuples, …) and functions stay by name.
+ * Bounded recursion + a per-branch cycle set guard against blow-ups; any type
+ * that can't be safely expanded falls back to the non-expanded text rather
+ * than throwing.
+ *
+ * Union and intersection members are printed in a canonical order that does not
+ * depend on when the checker created each member type — see `orderMembers`
+ * (carrick#735), which the depth backstop applies too, and which `namedText`
+ * applies as text to everything the walk hands back to the compiler's own
+ * print (carrick#775).
+ *
+ * Shared by `definition-resolver.ts` (bundle alias resolution) and
+ * `type-inferrer.ts` (consumer-side inference), so both paths emit the same
+ * structural form rather than a dangling name.
+ */
+import { ts } from 'ts-morph';
+import { canonicalizeUnionsInText } 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;
+/**
+ * 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.
+ */
+export function expandTypeStructural(type, seen = new Set(), depth = 0) {
+    if (depth > MAX_EXPANSION_DEPTH)
+        return backstopText(type);
+    // Primitives & literals: nothing to inline.
+    if (type.isString() ||
+        type.isNumber() ||
+        type.isBoolean() ||
+        type.isBooleanLiteral() ||
+        type.isUndefined() ||
+        type.isNull() ||
+        type.isVoid() ||
+        type.isAny() ||
+        type.isUnknown() ||
+        type.isNever() ||
+        type.isStringLiteral() ||
+        type.isNumberLiteral() ||
+        type.isEnumLiteral()) {
+        return namedText(type);
+    }
+    // Unions / intersections: expand each member, in canonical order.
+    if (type.isUnion()) {
+        return canonicalMembers(type.getUnionTypes(), seen, depth).join(' | ');
+    }
+    if (type.isIntersection()) {
+        return canonicalMembers(type.getIntersectionTypes(), seen, depth).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.
+    if (isTuple(type)) {
+        return namedText(type);
+    }
+    if (type.isArray()) {
+        const element = type.getArrayElementType();
+        if (!element)
+            return namedText(type);
+        const inner = expandTypeStructural(element, seen, depth + 1);
+        // 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,
+        // and a union led by an object literal (`{ a: string } | null`) MUST be.
+        const needsParens = element.isUnion() || element.isIntersection();
+        return needsParens ? `(${inner})[]` : `${inner}[]`;
+    }
+    // Library / built-in types (Date, Promise, RegExp, …): keep by name.
+    if (isLibraryType(type)) {
+        return namedText(type);
+    }
+    // Callable/constructable object types (functions): keep by name; their
+    // structural form is the signature, which `getText` already renders.
+    if (type.getCallSignatures().length > 0 ||
+        type.getConstructSignatures().length > 0) {
+        return namedText(type);
+    }
+    if (type.isObject() || type.isInterface()) {
+        const id = type.compilerType.id;
+        if (id != null && seen.has(id))
+            return namedText(type);
+        const nextSeen = id != null ? new Set(seen).add(id) : seen;
+        const props = type.getProperties();
+        if (props.length === 0)
+            return namedText(type);
+        const parts = props.map((prop) => expandProperty(prop, nextSeen, depth));
+        return `{ ${parts.join('; ')}; }`;
+    }
+    return namedText(type);
+}
+/**
+ * The print for a type the recursion bound stopped at (carrick#775).
+ *
+ * `namedText` is the compiler's own print, and for a union that print is in
+ * type-id order — the creation-order artefact `canonicalMembers` exists to
+ * remove. Stopping the recursion must not also stop the normalisation: a union
+ * at depth 13 is as much a set as one at depth 2, and a diff reader comparing
+ * two `expanded_definition` strings cannot tell which depth a member came from.
+ *
+ * So the members are rendered by NAME — no recursion, which is the whole point
+ * of the bound — and put in the same canonical order as the expanded path.
+ * Everything else falls through to the compiler's print unchanged.
+ */
+function backstopText(type) {
+    if (type.isUnion()) {
+        return orderMembers(type.getUnionTypes(), namedText).join(' | ');
+    }
+    if (type.isIntersection()) {
+        return orderMembers(type.getIntersectionTypes(), namedText).join(' & ');
+    }
+    return namedText(type);
+}
+/**
+ * Render every member of a union/intersection and put them in a canonical
+ * order (carrick#735).
+ *
+ * The compiler stores a union's constituents sorted by type id, and ids are
+ * handed out in the order the checker CREATES types. A literal type is created
+ * the first time some declaration is checked, and it is then interned — so on
+ * a tree where `"PENDING" | "TIMED_OUT"` and `"TIMED_OUT" | "PENDING"` are both
+ * declared, whichever declaration is reached first decides the printed order of
+ * BOTH. Two runs over an unchanged tree can therefore print one type two ways.
+ *
+ * The order carries no meaning: a union is a set, and the check phase compares
+ * these strings by typechecking them, which is order-insensitive. So we impose
+ * one — every member sorts by its own rendered text, compared by UTF-16 code
+ * unit. That is a pure function of the members, with no dependence on when the
+ * checker happened to create any of them.
+ *
+ * #735 carved out an exception for the intrinsics (`string`, `null`, `number`,
+ * …), keeping them ahead of the rest in compiler-id order on the grounds that
+ * their ids are fixed before any source file is read, so `string | null` would
+ * still print the way the compiler prints it. The second half of that is not
+ * true: the compiler's printer does not use id order. On a union of
+ * `null | number` the checker's ids give `null` first and `typeToString` prints
+ * `number | null`, so keeping id order reproduced neither the compiler's print
+ * nor — once carrick#775 put the compiler's own prints under the same rule —
+ * the other path's. One rule for every member is the only way a union prints
+ * one way wherever it is rendered, and it costs nothing the exception was
+ * actually buying. `type-text-canonicalizer.ts` applies the same rule to text.
+ *
+ * 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));
+}
+/**
+ * The canonical order itself, over whatever text `render` gives each member.
+ * Shared by the expanded path (`canonicalMembers`, which renders structurally)
+ * and the depth backstop (`backstopText`, which renders by name), so one union
+ * cannot be ordered two ways depending on how deep it sits.
+ */
+function orderMembers(members, render) {
+    const rendered = members.map((member, index) => ({
+        index,
+        text: render(member),
+    }));
+    rendered.sort((a, b) => {
+        if (a.text !== b.text)
+            return a.text < b.text ? -1 : 1;
+        return a.index - b.index;
+    });
+    return rendered.map((entry) => entry.text);
+}
+/** Render a single property as `name[?]: <expanded>`. */
+function expandProperty(prop, seen, depth) {
+    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();
+    // An optional property's type includes `undefined`; the structural label
+    // drops it (`note?: string`, not `note?: string | undefined`).
+    if (optional && propType.isUnion()) {
+        const nonUndefined = propType
+            .getUnionTypes()
+            .filter((member) => !member.isUndefined());
+        if (nonUndefined.length === 1) {
+            propType = nonUndefined[0];
+        }
+        else if (nonUndefined.length > 1) {
+            const inner = canonicalMembers(nonUndefined, seen, depth).join(' | ');
+            return `${name}?: ${inner}`;
+        }
+    }
+    const inner = expandTypeStructural(propType, seen, depth + 1);
+    return `${name}${optional ? '?' : ''}: ${inner}`;
+}
+/**
+ * The property key as valid TS text. Uses the declaration's name node so a
+ * quoted (`'x-y'`) or computed (`[Symbol.iterator]`) key keeps its syntax;
+ * `Symbol.getName()` would drop the quoting and emit invalid output. Falls
+ * back to the bare symbol name when there's no usable name node.
+ */
+function renderPropertyName(prop, decl) {
+    const node = decl;
+    const text = node?.getNameNode?.()?.getText();
+    return text && text.length > 0 ? text : prop.getName();
+}
+/** True for tuple types (`[a, b]`), which must not be walked as objects. */
+function isTuple(type) {
+    const compiler = type.compilerType;
+    const target = compiler.target ?? compiler;
+    return ((target.objectFlags ?? 0) & ts.ObjectFlags.Tuple) !== 0;
+}
+/**
+ * True for types declared in `node_modules` or a TS `lib.*.d.ts` (Date,
+ * Promise, RegExp, …). These stay by name rather than being inlined.
+ */
+function isLibraryType(type) {
+    const symbol = type.getSymbol() ?? type.getAliasSymbol();
+    if (!symbol)
+        return false;
+    const decls = symbol.getDeclarations();
+    if (decls.length === 0)
+        return false;
+    return decls.some((decl) => {
+        const sf = decl.getSourceFile();
+        if (sf.isInNodeModules())
+            return true;
+        return (sf.isDeclarationFile() &&
+            // Normalize separators so a Windows `\\` path still matches lib.*.d.ts.
+            /(^|\/)lib\.[^/]*\.d\.ts$/.test(sf.getFilePath().replace(/\\/g, '/')));
+    });
+}
+/**
+ * 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
+ * generic instantiations do), falling back to the bare `getText()` and
+ * finally to `unknown` so a single bad type never aborts the whole resolve.
+ *
+ * This is the ONE place the walk hands a subtree back to the compiler's own
+ * print — for a library type, a type with no properties to walk, a tuple, a
+ * function, a cycle, or the depth backstop. Everything inside that print is in
+ * type-id order, which is creation order, so the unions it contains are put in
+ * the same canonical order the walk gives the ones it renders itself
+ * (carrick#775). Doing it here rather than at each caller means no bail-out
+ * path can print a union one way while the walk prints it another.
+ */
+export function namedText(type) {
+    return canonicalizeUnionsInText(compilerText(type));
+}
+/** The compiler's print, with the two fallbacks. */
+function compilerText(type) {
+    try {
+        return type.getText(undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.InTypeAlias);
+    }
+    catch {
+        try {
+            return type.getText();
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Canonical union order inside text the COMPILER printed (carrick#775, #760).
+ *
+ * `expandTypeStructural` walks a type and orders every union it walks
+ * (`orderMembers`), so the structural path is stable. But the walk stops at
+ * several points and hands the rest of the subtree to `namedText` — the
+ * compiler's own print:
+ *
+ *  - library types, which are kept by name (`isLibraryType`), and whose print
+ *    carries their whole generic instantiation with it;
+ *  - object types with no named properties (an index signature alone), which
+ *    have nothing to walk;
+ *  - tuples, functions, cycles the `seen` set breaks, and the depth backstop.
+ *
+ * Everything inside one of those prints is in the compiler's own union order,
+ * which is type-id order, which is CREATION order — the same instability
+ * `orderMembers` exists to remove, one level down where the type API can no
+ * longer reach it: at that point the members exist only as text.
+ *
+ * So they are ordered as text, by the same rule the walk uses: every member
+ * sorts by its own rendering, compared by UTF-16 code unit. A union is a set,
+ * the check phase compares these strings by typechecking them, and a reader
+ * diffing two `expanded_definition` strings cannot tell which side of a
+ * `namedText` boundary a member came from — so both sides must order them the
+ * same way, which is why `orderMembers` no longer keeps intrinsics in compiler
+ * id order (the compiler's printer does not use that order either).
+ *
+ * The rewrite is deliberately timid. Anything whose meaning could depend on
+ * order or on a parse this file does not do — a function type (`=>`), a
+ * conditional (`?`) — is returned untouched, and untouched is always a legal
+ * answer here because the compiler's print is already valid TypeScript.
+ */
+/**
+ * Put every union in `text` into canonical order, at every nesting level.
+ *
+ * Returns `text` unchanged whenever the shape is one this file does not parse
+ * (see the module comment). Never throws: a type print is arbitrary text, and
+ * a definition resolve must not fail because one member confused a scanner.
+ */
+export declare function canonicalizeUnionsInText(text: string): string;

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

@@ -0,0 +1,297 @@
+/**
+ * Canonical union order inside text the COMPILER printed (carrick#775, #760).
+ *
+ * `expandTypeStructural` walks a type and orders every union it walks
+ * (`orderMembers`), so the structural path is stable. But the walk stops at
+ * several points and hands the rest of the subtree to `namedText` — the
+ * compiler's own print:
+ *
+ *  - library types, which are kept by name (`isLibraryType`), and whose print
+ *    carries their whole generic instantiation with it;
+ *  - object types with no named properties (an index signature alone), which
+ *    have nothing to walk;
+ *  - tuples, functions, cycles the `seen` set breaks, and the depth backstop.
+ *
+ * Everything inside one of those prints is in the compiler's own union order,
+ * which is type-id order, which is CREATION order — the same instability
+ * `orderMembers` exists to remove, one level down where the type API can no
+ * longer reach it: at that point the members exist only as text.
+ *
+ * So they are ordered as text, by the same rule the walk uses: every member
+ * sorts by its own rendering, compared by UTF-16 code unit. A union is a set,
+ * the check phase compares these strings by typechecking them, and a reader
+ * diffing two `expanded_definition` strings cannot tell which side of a
+ * `namedText` boundary a member came from — so both sides must order them the
+ * same way, which is why `orderMembers` no longer keeps intrinsics in compiler
+ * id order (the compiler's printer does not use that order either).
+ *
+ * The rewrite is deliberately timid. Anything whose meaning could depend on
+ * order or on a parse this file does not do — a function type (`=>`), a
+ * conditional (`?`) — is returned untouched, and untouched is always a legal
+ * answer here because the compiler's print is already valid TypeScript.
+ */
+/** Bracket pairs whose interiors are descended into. */
+const CLOSERS = { '{': '}', '<': '>', '(': ')', '[': ']' };
+/**
+ * Put every union in `text` into canonical order, at every nesting level.
+ *
+ * Returns `text` unchanged whenever the shape is one this file does not parse
+ * (see the module comment). Never throws: a type print is arbitrary text, and
+ * a definition resolve must not fail because one member confused a scanner.
+ */
+export function canonicalizeUnionsInText(text) {
+    try {
+        return canonicalizeType(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** Canonicalise one TYPE fragment — not a `key: value` member. */
+function canonicalizeType(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return text;
+    // A function type or a conditional type is left exactly as printed: both
+    // carry a top-level `|` that is not a union separator at this level
+    // (`() => a | b` is one function returning a union, `T extends U ? a : b`
+    // has unions inside its branches), and neither is worth the parse.
+    if (hasTopLevel(trimmed, ['=>', '?']))
+        return text;
+    const members = splitTopLevel(trimmed, '|');
+    if (members.length > 1) {
+        return orderTextMembers(members.map((m) => canonicalizeType(m))).join(' | ');
+    }
+    return descendIntoBrackets(trimmed);
+}
+/**
+ * Rewrite the interiors of the bracket groups in a fragment that is not itself
+ * a union: an object body's member types, a generic argument list, a tuple's
+ * elements, a parenthesised type.
+ */
+function descendIntoBrackets(text) {
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        const quoted = readQuoted(text, i);
+        if (quoted !== null) {
+            out += text.slice(i, quoted);
+            i = quoted;
+            continue;
+        }
+        const closer = CLOSERS[ch];
+        if (closer === undefined) {
+            out += ch;
+            i++;
+            continue;
+        }
+        const end = matchBracket(text, i);
+        if (end === -1) {
+            // Unbalanced (a truncated print): copy the rest verbatim.
+            out += text.slice(i);
+            return out;
+        }
+        const inner = text.slice(i + 1, end);
+        out += ch + canonicalizeBody(inner, ch) + closer;
+        i = end + 1;
+    }
+    return out;
+}
+/**
+ * Canonicalise the inside of one bracket group.
+ *
+ * `{ ... }` is a list of `key: type` members separated by `;` (or `,`), and
+ * only the type half may be rewritten — a key is not a type, and `a: X | Y`
+ * split on `|` would produce the nonsense member `a: X`. Every other bracket
+ * holds a comma-separated list of types.
+ *
+ * Each piece is spliced back at its own offsets, so a body with nothing to
+ * reorder comes out byte-identical to the compiler's print — whitespace,
+ * separators and all.
+ */
+function canonicalizeBody(inner, opener) {
+    const separator = opener === '{' ? ';' : ',';
+    const spans = splitTopLevelSpans(inner, separator);
+    let out = '';
+    let cursor = 0;
+    for (const span of spans) {
+        const piece = inner.slice(span.start, span.end);
+        const trimmed = piece.trim();
+        if (trimmed.length > 0) {
+            const rewritten = canonicalizeMember(trimmed);
+            if (rewritten !== trimmed) {
+                const at = span.start + piece.indexOf(trimmed);
+                out += inner.slice(cursor, at) + rewritten;
+                cursor = at + trimmed.length;
+            }
+        }
+    }
+    return out + inner.slice(cursor);
+}
+/**
+ * One list element: `key: type`, `name?: type`, `[x: string]: type`, or a bare
+ * type. Splits at the element's own `:` — the one at depth zero, which an
+ * index signature's `[x: string]` and a nested object both sit below — and
+ * rewrites only what follows it.
+ */
+function canonicalizeMember(member) {
+    const colon = indexOfTopLevel(member, ':');
+    if (colon === -1)
+        return canonicalizeType(member);
+    const key = member.slice(0, colon + 1);
+    const value = member.slice(colon + 1);
+    const leading = value.length - value.trimStart().length;
+    const trailing = value.length - value.trimEnd().length;
+    return (key +
+        value.slice(0, leading) +
+        canonicalizeType(value.trim()) +
+        value.slice(value.length - trailing));
+}
+/**
+ * The canonical order, as text: every member by its own rendering, compared by
+ * UTF-16 code unit. This is `orderMembers` in `type-structural-expander.ts`,
+ * over the renderings that are all this side has — the two must agree member
+ * for member, or one union prints two ways depending on whether the walk or
+ * the compiler rendered it.
+ */
+function orderTextMembers(members) {
+    return members
+        .map((text, index) => ({ text: text.trim(), index }))
+        .sort((a, b) => {
+        if (a.text !== b.text)
+            return a.text < b.text ? -1 : 1;
+        return a.index - b.index;
+    })
+        .map((entry) => entry.text);
+}
+/**
+ * The spans between depth-zero occurrences of `separator`. Depth counts the
+ * four bracket pairs; quoted runs are skipped whole, so a separator inside a
+ * string literal never splits.
+ */
+function splitTopLevelSpans(text, separator) {
+    const spans = [];
+    let start = 0;
+    let depth = 0;
+    let i = 0;
+    while (i < text.length) {
+        const quoted = readQuoted(text, i);
+        if (quoted !== null) {
+            i = quoted;
+            continue;
+        }
+        const ch = text[i];
+        if (CLOSERS[ch] !== undefined) {
+            depth++;
+        }
+        else if (ch === '}' || ch === ')' || ch === ']' || isTypeArgClose(text, i)) {
+            depth = Math.max(0, depth - 1);
+        }
+        else if (ch === separator && depth === 0) {
+            spans.push({ start, end: i });
+            start = i + 1;
+        }
+        i++;
+    }
+    spans.push({ start, end: text.length });
+    return spans;
+}
+/** Split at every depth-zero occurrence of `separator`. */
+function splitTopLevel(text, separator) {
+    return splitTopLevelSpans(text, separator).map((span) => text.slice(span.start, span.end));
+}
+/** Index of the first depth-zero `char`, or -1. */
+function indexOfTopLevel(text, char) {
+    const parts = splitTopLevel(text, char);
+    return parts.length > 1 ? parts[0].length : -1;
+}
+/** True when any of `tokens` occurs at depth zero. */
+function hasTopLevel(text, tokens) {
+    for (const token of tokens) {
+        if (token === '=>') {
+            // Split on '>' would fight the generic-close rule; look for the arrow
+            // directly, at depth zero, by walking with the same scanner.
+            if (indexOfTopLevelArrow(text) !== -1)
+                return true;
+            continue;
+        }
+        if (indexOfTopLevel(text, token) !== -1)
+            return true;
+    }
+    return false;
+}
+/** Index of a depth-zero `=>`, or -1. */
+function indexOfTopLevelArrow(text) {
+    let depth = 0;
+    let i = 0;
+    while (i < text.length) {
+        const quoted = readQuoted(text, i);
+        if (quoted !== null) {
+            i = quoted;
+            continue;
+        }
+        const ch = text[i];
+        if (ch === '=' && text[i + 1] === '>') {
+            if (depth === 0)
+                return i;
+            i += 2;
+            continue;
+        }
+        if (CLOSERS[ch] !== undefined)
+            depth++;
+        else if (ch === '}' || ch === ')' || ch === ']' || isTypeArgClose(text, i))
+            depth = Math.max(0, depth - 1);
+        i++;
+    }
+    return -1;
+}
+/** A `>` that closes a type-argument list, rather than the tail of an arrow. */
+function isTypeArgClose(text, i) {
+    return text[i] === '>' && text[i - 1] !== '=';
+}
+/**
+ * If a quoted run (string literal or template literal) starts at `i`, the
+ * index just past its closing quote; otherwise null. Escapes are honoured so a
+ * `"a\"|b"` literal is never split.
+ */
+function readQuoted(text, i) {
+    const quote = text[i];
+    if (quote !== '"' && quote !== "'" && quote !== '`')
+        return null;
+    let j = i + 1;
+    while (j < text.length) {
+        if (text[j] === '\\') {
+            j += 2;
+            continue;
+        }
+        if (text[j] === quote)
+            return j + 1;
+        j++;
+    }
+    return text.length;
+}
+/** Index of the bracket closing the one at `open`, or -1 when unbalanced. */
+function matchBracket(text, open) {
+    const closer = CLOSERS[text[open]];
+    let depth = 0;
+    let i = open;
+    while (i < text.length) {
+        const quoted = readQuoted(text, i);
+        if (quoted !== null) {
+            i = quoted;
+            continue;
+        }
+        const ch = text[i];
+        if (ch === text[open]) {
+            depth++;
+        }
+        else if (ch === closer && !(closer === '>' && text[i - 1] === '=')) {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+        i++;
+    }
+    return -1;
+}