@geastack/compiler 1.0.15

package/dist/semantics/normalize/producers/tagged-template.js

@@ -0,0 +1,307 @@
+import ts from 'typescript';
+import { semanticResultId } from '../../../identity/ids.js';
+import { normalCompletion, pureEffects, throwingCompletion } from '../../model/operands.js';
+import { blocked, mintOperationId, mintResult, operand } from './mint.js';
+import { calleeAwareTypeAt, resolvedCalleeSignatureType, sourceForValue, unwrapErased, valueEdgesInto } from './shared.js';
+const literalsOf = (template) => ts.isTemplateExpression(template) ? [template.head, ...template.templateSpans.map((span) => span.literal)] : [template];
+const normalizeRawText = (rawText) => {
+    // Template Raw Value canonicalizes CR and CRLF to LF. Written as a scan
+    // rather than a replace so it states the two sequences it collapses.
+    let normalized = '';
+    for (let index = 0; index < rawText.length; index += 1) {
+        const character = rawText[index];
+        if (character !== '\r') {
+            normalized += character;
+            continue;
+        }
+        normalized += '\n';
+        if (rawText[index + 1] === '\n')
+            index += 1;
+    }
+    return normalized;
+};
+const isHexDigit = (character) => character !== undefined &&
+    ((character >= '0' && character <= '9') || (character >= 'a' && character <= 'f') || (character >= 'A' && character <= 'F'));
+const isDecimalDigit = (character) => character !== undefined && character >= '0' && character <= '9';
+/**
+ * The Template Value of one segment's raw text -- ECMA-262 12.9.6.1 -- or
+ * `null` when the segment contains a NotEscapeSequence, whose TV is
+ * `undefined`.
+ *
+ * Computed from the RAW text rather than read off `literal.text`, and that
+ * direction is the point. A tagged template is the one place in the language
+ * where an invalid escape is legal (12.9.6, the carve-out that makes
+ * `` tag`\unicode` `` parse where an untagged template is a syntax error), and
+ * its cooked value is then `undefined` rather than a string. TypeScript records
+ * that fact in a token flag its public API does not expose, and its `text`
+ * cannot stand in for the flag: a segment with a valid escape AND an invalid
+ * one (`` `a\nb\unicode c` ``) cooks the valid half and leaves the invalid one
+ * verbatim, so `text !== rawText` is true for a segment whose TV is undefined.
+ * That measurement is what ruled out the cheaper test.
+ *
+ * `segmentsOf` then checks this against TypeScript's own `text` and refuses on
+ * any disagreement, so the two are a cross-check rather than one authority
+ * silently replacing the other.
+ */
+const cookTemplateSegment = (raw) => {
+    let cooked = '';
+    let index = 0;
+    while (index < raw.length) {
+        const character = raw[index] ?? '';
+        if (character !== '\\') {
+            cooked += character;
+            index += 1;
+            continue;
+        }
+        const escape = raw[index + 1];
+        if (escape === undefined)
+            return null;
+        index += 2;
+        // A LineTerminatorSequence after a backslash is a line continuation and
+        // contributes nothing. CR and CRLF are already LF by the time this runs.
+        if (escape === '\n' || escape === '\u2028' || escape === '\u2029')
+            continue;
+        if (escape === 'b') {
+            cooked += '\b';
+            continue;
+        }
+        if (escape === 't') {
+            cooked += '\t';
+            continue;
+        }
+        if (escape === 'n') {
+            cooked += '\n';
+            continue;
+        }
+        if (escape === 'v') {
+            cooked += '\v';
+            continue;
+        }
+        if (escape === 'f') {
+            cooked += '\f';
+            continue;
+        }
+        if (escape === 'r') {
+            cooked += '\r';
+            continue;
+        }
+        if (escape === '0') {
+            // `\0` is NUL, but `\0` followed by a digit is a legacy octal escape,
+            // which a template may not contain.
+            if (isDecimalDigit(raw[index]))
+                return null;
+            cooked += '\u0000';
+            continue;
+        }
+        if (escape === 'x') {
+            const high = raw[index];
+            const low = raw[index + 1];
+            if (!isHexDigit(high) || !isHexDigit(low))
+                return null;
+            cooked += String.fromCharCode(Number.parseInt(`${high ?? ''}${low ?? ''}`, 16));
+            index += 2;
+            continue;
+        }
+        if (escape === 'u') {
+            if (raw[index] === '{') {
+                const close = raw.indexOf('}', index + 1);
+                if (close < 0)
+                    return null;
+                const digits = raw.slice(index + 1, close);
+                if (digits.length === 0 || [...digits].some((digit) => !isHexDigit(digit)))
+                    return null;
+                const point = Number.parseInt(digits, 16);
+                if (point > 0x10ffff)
+                    return null;
+                cooked += String.fromCodePoint(point);
+                index = close + 1;
+                continue;
+            }
+            const digits = raw.slice(index, index + 4);
+            if (digits.length !== 4 || [...digits].some((digit) => !isHexDigit(digit)))
+                return null;
+            cooked += String.fromCharCode(Number.parseInt(digits, 16));
+            index += 4;
+            continue;
+        }
+        // A decimal digit after a backslash is a legacy octal (or `\8`/`\9`)
+        // escape; every other character is a NonEscapeCharacter and stands for
+        // itself.
+        if (isDecimalDigit(escape))
+            return null;
+        cooked += escape;
+    }
+    return cooked;
+};
+const segmentsOf = (template) => {
+    const cooked = [];
+    const raw = [];
+    for (const literal of literalsOf(template)) {
+        // Parsed program source always carries the exact token body. A synthesized
+        // node does not, and there is no way to cook one without it.
+        if (literal.rawText === undefined)
+            return { blocked: 'a tagged template segment carries no parsed raw text to build its raw array from' };
+        const rawValue = normalizeRawText(literal.rawText);
+        const cookedValue = cookTemplateSegment(rawValue);
+        if (cookedValue === null) {
+            raw.push(rawValue);
+            cooked.push(undefined);
+            continue;
+        }
+        // Two authorities on one value. TypeScript cooked this segment while
+        // parsing it and this file cooked it again from the raw text; a
+        // disagreement means one of them is wrong about the language, and guessing
+        // which would put a string the program never wrote into the tag's hands.
+        if (cookedValue !== literal.text) {
+            return {
+                blocked: `a tagged template segment cooks to ${JSON.stringify(cookedValue)} from its raw text but TypeScript cooked it to ` +
+                    `${JSON.stringify(literal.text)}; the two readings of one segment have to agree`
+            };
+        }
+        raw.push(rawValue);
+        cooked.push(cookedValue);
+    }
+    return { cooked, raw };
+};
+/** The type the tag's own first parameter declares -- the template object's, asked of the signature the checker resolved for this exact site. */
+const templateObjectTypeOf = (context, node, signature) => {
+    const parameter = signature.getParameters()[0];
+    if (!parameter)
+        return null;
+    // STATED, not held: this asks what the resolved tag signature's own first
+    // parameter DECLARES -- the tag function's authored type, not a program
+    // binding a census could improve on. The checker's answer is the real
+    // question here.
+    return context.types.typeOf(context.checker.getTypeOfSymbolAtLocation(parameter, node));
+};
+/**
+ * The allocated value is always a complete `TemplateStringsArray`, regardless
+ * of how broadly the tag elects to receive it.  In particular, a tag declared
+ * as `(strings: readonly string[])` still observes the real object, including
+ * its frozen own `raw` array; its parameter type is the invocation target, not
+ * a license to omit those source-value properties.
+ */
+const templateObjectValueTypeOf = (context) => {
+    const stringType = context.table.intern({ kind: 'primitive', primitive: 'string' });
+    const rawType = context.table.intern({ kind: 'array', element: stringType, readonly: false, extension: [] });
+    return context.table.intern({
+        kind: 'array',
+        element: stringType,
+        readonly: false,
+        extension: [
+            {
+                key: { kind: 'string', value: 'raw' },
+                type: rawType,
+                optional: false,
+                readonly: true,
+                accessor: null
+            }
+        ]
+    });
+};
+export const contributeTaggedTemplate = (context, candidate, node) => {
+    const refuse = (reason) => ({
+        kind: 'blocked',
+        blocker: blocked(candidate.id, 'invocation', reason, 'P2')
+    });
+    const segments = segmentsOf(node.template);
+    if ('blocked' in segments)
+        return refuse(segments.blocked);
+    const signature = context.checker.getResolvedSignature(node);
+    if (!signature)
+        return refuse('a tagged template resolved no signature for its tag, so the template object has no declared parameter type');
+    const templateObjectType = templateObjectTypeOf(context, node, signature);
+    if (templateObjectType === null) {
+        return refuse('a tagged template names a tag that declares no first parameter for the template object to be passed as');
+    }
+    const templateObjectValueType = templateObjectValueTypeOf(context);
+    const stringType = context.table.intern({ kind: 'primitive', primitive: 'string' });
+    const undefinedType = context.table.intern({ kind: 'primitive', primitive: 'undefined' });
+    const allocationId = mintOperationId(context.ordinals, candidate.id, 'allocation');
+    const allocation = {
+        id: allocationId,
+        family: 'allocation',
+        allocated: 'template-object',
+        shape: templateObjectValueType,
+        callable: null,
+        caller: candidate.caller,
+        // The segments travel as constants because that is what they are: no step
+        // of the language computes them, and the emitter builds the object out of
+        // exactly these texts.
+        operands: [
+            ...segments.cooked.map((text, index) => text === undefined
+                ? operand('cooked', index, { kind: 'constant', text: 'undefined', literal: 'undefined' }, undefinedType)
+                : operand('cooked', index, { kind: 'constant', text, literal: 'string' }, stringType)),
+            ...segments.raw.map((text, index) => operand('raw', index, { kind: 'constant', text, literal: 'string' }, stringType))
+        ],
+        results: [mintResult(allocationId, 'value', templateObjectValueType)],
+        completion: normalCompletion,
+        // `allocates: false` is not an oversight. This operation yields the SAME
+        // object on every evaluation (`GetTemplateObject` caches per Parse Node),
+        // so nothing is created when it runs, and a consumer that treats it as a
+        // fresh identity per evaluation would be wrong about the one property that
+        // makes a template object what it is.
+        effects: { ...pureEffects, allocates: false },
+        evaluationOrdinal: candidate.evaluationOrdinal
+    };
+    const invocationId = mintOperationId(context.ordinals, candidate.id, 'invocation');
+    const calleeType = resolvedCalleeSignatureType(context, node.tag) ?? calleeAwareTypeAt(context, node.tag);
+    const operands = [operand('callee', 0, sourceForValue(context, node.tag), calleeType)];
+    const tagUnwrapped = unwrapErased(node.tag);
+    if (ts.isPropertyAccessExpression(tagUnwrapped) || ts.isElementAccessExpression(tagUnwrapped)) {
+        operands.push(operand('receiver', 0, sourceForValue(context, tagUnwrapped.expression), context.types.typeAt(tagUnwrapped.expression), {
+            kind: 'provenance'
+        }));
+    }
+    // Argument 0 is the template object, and the substitutions follow it in
+    // source order -- ECMA-262 13.3.11.1's `ArgumentListEvaluation` for a
+    // `TemplateLiteral`, which is also the shape every tag signature is written
+    // against (`(strings, ...values)`).
+    //
+    // Stated as `templateObjectValueType` -- the same type the allocation's own
+    // result carries -- not `templateObjectType`, the tag's DECLARED parameter
+    // type. A tag may narrow what it asks for (`(strings: readonly string[])`),
+    // but the value ECMA-262 actually hands it is always the complete object
+    // with its frozen `raw` array. Stamping the declared type here fed that
+    // narrower shape into the callee parameter's own binding census, so a tag
+    // stated no more specifically than its parameter list lost `raw` and its
+    // frozen-array identity entirely -- the parameter carrier a call-argument
+    // join produces can never be richer than what the argument itself states.
+    operands.push(operand('argument', 0, { kind: 'result', result: semanticResultId(allocationId, 'value') }, templateObjectValueType));
+    const substitutions = ts.isTemplateExpression(node.template) ? node.template.templateSpans.map((span) => span.expression) : [];
+    substitutions.forEach((expression, index) => {
+        operands.push(operand('argument', index + 1, sourceForValue(context, expression), context.types.typeAt(expression)));
+    });
+    const invocation = {
+        id: invocationId,
+        family: 'invocation',
+        caller: candidate.caller,
+        internalMethod: 'call',
+        optionalChain: false,
+        // No signature is published, and no exact target is proven. Both are the
+        // same honest answer an ordinary call gives when the checker withholds an
+        // overload set: the callee's own carrier is what supplies the calling
+        // convention, and a tag is reached through a value like any other callee.
+        // `invocations.ts`'s own `exactFunctionTarget` could prove one for a tag
+        // that names a source function directly, but it reads `node.expression`,
+        // which a tagged template does not have -- and the difference it makes is a
+        // direct call instead of one through the callable value, never whether
+        // anything boxes. Left `open` rather than widening a shared helper for it.
+        selectedSignature: null,
+        resultDivergence: { kind: 'none' },
+        target: { kind: 'open', evidence: ['tagged-template-callee', 'no-static-target-proof'] },
+        operands,
+        results: [mintResult(invocationId, 'value', context.types.typeAt(node))],
+        completion: throwingCompletion,
+        effects: { readsMutableState: true, writesMutableState: true, allocates: false, callsUserCode: true },
+        evaluationOrdinal: candidate.evaluationOrdinal
+    };
+    const edges = [
+        ...valueEdgesInto(invocationId, operands),
+        // The object exists before the call that receives it. Stated explicitly
+        // because the two operations share one candidate and therefore one
+        // evaluation ordinal, which says nothing about their order.
+        { kind: 'evaluation', from: allocationId, to: invocationId }
+    ];
+    return { kind: 'operations', operations: [allocation, invocation], edges };
+};

package/dist/semantics/normalize/producers/tuple-spread.d.ts

@@ -0,0 +1,189 @@
+import ts from 'typescript';
+import { type StructuralTypeId } from '../../../identity/ids.js';
+import type { SemanticEdge } from '../../model/edges.js';
+import { type OperandSource } from '../../model/operands.js';
+import type { PropertyOperation } from '../../model/operations.js';
+import type { CensusCandidate } from '../census.js';
+import type { ProducerContext } from '../producer-context.js';
+/**
+ * `...t` where `t` is a closed tuple: N positional reads, no iterator.
+ *
+ * A tuple is the one iterable whose iteration is settled before the program
+ * runs. Its length is part of its type and each position carries its own
+ * declared type, so `f(...pair)` is `f(pair[0], pair[1])` and `[...pair, x]`
+ * is `[pair[0], pair[1], x]` -- exactly, not approximately. Driving
+ * GetIterator/next() over it would ask the runtime to rediscover an arity the
+ * checker already stated, and would hand every position the *union* of the
+ * tuple's element types (`protocol.ts`'s `iterationElementType` has no other
+ * answer to give for a per-step value), losing the per-position typing that
+ * makes a tuple a tuple.
+ *
+ * The reads are minted as ordinary `[[Get]]`s with constant keys, which is
+ * what a tuple position IS in this compiler: `lower-allocation.ts`'s
+ * `lowerTupleLiteral` writes position `n` into the record field keyed
+ * `String(n)`, and `lower-destructuring.ts`'s `lowerTuplePatternRead` already
+ * reads one back with this identical shape. Minting a property operation
+ * rather than expanding inside a lowering is what keeps the expansion visible
+ * to every layer that has an opinion about a read: the representation plan
+ * selects a carrier for each position's own result, `preflight/property-access.ts`
+ * records a `property-access:<carrier>:get:false` obligation per read, and
+ * `preflight/invocation-arguments.ts` / `array-literal-elements.ts` record the
+ * conversion obligation for each expanded operand. An IR-level expansion would
+ * be invisible to all four and would certify a program whose reads nothing
+ * proved.
+ *
+ * Cross-family minting under one candidate is the established shape here --
+ * `control.ts` mints `protocol` operations for a loop candidate,
+ * `invocations.ts` mints the `reference`/`binding` pair `super(...)` needs --
+ * and `contribution.ts` attributes each minted operation to its own family's
+ * coverage rather than to the candidate's.
+ */
+/** One expanded position: the result to cite and the type that position carries. */
+export interface TupleSpreadPosition {
+    readonly source: OperandSource;
+    readonly type: StructuralTypeId;
+}
+export interface TupleSpreadReads {
+    readonly operations: readonly PropertyOperation[];
+    readonly edges: readonly SemanticEdge[];
+    /** One entry per tuple position, in position order. */
+    readonly positions: readonly TupleSpreadPosition[];
+}
+/**
+ * The per-position types of a tuple whose arity is closed, or `null` for
+ * anything else.
+ *
+ * `optional`/`rest`/`variadic` elements are each a reason the arity is NOT
+ * settled -- `[number, ...string[]]` has no compile-time length, and
+ * `[number, string?]` has two possible ones -- so a tuple carrying any of them
+ * is not admitted here and falls through to whatever its caller's general path
+ * is. This is the same closed-arity requirement `lowerTupleLiteral`'s own
+ * `layout.length !== operands.length` check enforces one layer down, asked
+ * before the operands are built rather than after.
+ */
+export declare const closedTupleElementTypesOf: (context: ProducerContext, type: StructuralTypeId) => readonly StructuralTypeId[] | null;
+/**
+ * An OPEN-ENDED tuple a spread can still settle positionally: `k` required
+ * positions followed by exactly one `rest` element and nothing after it --
+ * `[DiagnosticMessage, ...DiagnosticArguments]`. The fixed positions expand
+ * to `[[Get]]`s like a closed tuple's (`mintPositionalSpreadReads`), and the
+ * tail is a range copy from `fixed.length` into the callee's rest array,
+ * which is exactly what the language's own iteration would hand it. An
+ * optional position before the rest, or a variadic position, has no such
+ * split and stays `null`.
+ */
+export declare const openTupleSpreadShapeOf: (context: ProducerContext, type: StructuralTypeId) => {
+    readonly fixed: readonly StructuralTypeId[];
+    readonly tail: StructuralTypeId;
+} | null;
+/** Whether `...expression`'s own source is a closed tuple, asked without minting anything. */
+export declare const isClosedTupleSpread: (context: ProducerContext, expression: ts.Expression) => boolean;
+export declare const declaredTupleRestArityOf: (context: ProducerContext, expression: ts.Expression) => number | null;
+/**
+ * The positional reads a declared-tuple rest parameter spread expands to
+ * (`declaredTupleRestArityOf`), each typed as the DECLARED tuple's own
+ * position -- not as the array cell's element. The cell holds the join of
+ * every position (`[string, number, number]` is an array of `string | number`),
+ * and a read typed by that join handed `describe( name, x, y )` a
+ * `string | number` for `x`, which made `x * y` a dynamic multiplication with
+ * no C++ spelling. The declaration is what fixes the value at each position,
+ * and a closed tuple LOCAL's reads are typed the same way off the same
+ * tagged-union carrier.
+ */
+export declare const declaredTupleRestSpreadReads: (context: ProducerContext, candidate: CensusCandidate, expression: ts.Expression) => TupleSpreadReads | null;
+/**
+ * The receiver both expansions below read positions off: `resolveExpressionOperand`'s
+ * own VALUE identity (which family published this expression's result --
+ * correctly resolved past an `as`/`satisfies`/`<T>` wrapper, since none of
+ * those own a runtime operation of their own), paired with the TYPE asked
+ * directly at `expression`, exactly as `isClosedTupleSpread`/
+ * `admitsMaxArityTupleSpread` (`spread-arguments.ts`) already ask it -- not
+ * `resolveExpressionOperand`'s own bundled `.type`, which asks past the same
+ * wrapper for the type too and disagrees with both admission gates the
+ * moment one is present. `args as Parameters<NewResponse>` (hono's
+ * `Context.newResponse`) is the concrete case: the CAST states a real closed
+ * shape the underlying `args` binding does not have on its own (an ordinary,
+ * open-arity array, once the rest-parameter census has done its job) -- an
+ * admission gate that reads the cast agrees to expand it, and an expansion
+ * that then reads past the cast right back to the array finds no tuple
+ * there and refuses, silently, for an admission that already said yes.
+ * `local-bindings.ts`'s `knownOrResolve` draws this identical line for a
+ * cast ("the checker's own answer there is taken as-is and never read
+ * past"); this is that same rule, asked with the SAME node the two
+ * admission gates already use, so the three can only ever agree.
+ */
+export declare const spreadReceiverOf: (context: ProducerContext, expression: ts.Expression) => {
+    readonly source: OperandSource;
+    readonly type: StructuralTypeId;
+} | null;
+/**
+ * The `[[Get]]`s a tuple's positions expand to, shared by every admission
+ * shape below -- each differs only in WHICH element types it is sound to ask
+ * for, never in how a position, once admitted, is read.
+ *
+ * The receiver is cited ONCE and read N times, which is what the language
+ * does: `f(...sideEffect())` evaluates `sideEffect()` a single time and then
+ * indexes the result. Citing the expression per position instead would name
+ * the same published result N times, which is harmless, but building the
+ * operand once makes that single evaluation explicit rather than incidental.
+ */
+export declare const mintPositionalSpreadReads: (context: ProducerContext, candidate: CensusCandidate, receiver: {
+    readonly source: OperandSource;
+    readonly type: StructuralTypeId;
+}, elements: readonly StructuralTypeId[], firstIndex?: number) => TupleSpreadReads;
+/**
+ * The positional reads `...expression` expands to, or `null` when the source
+ * is not a closed tuple or when no operation publishes its value.
+ */
+export declare const tupleSpreadReads: (context: ProducerContext, candidate: CensusCandidate, expression: ts.Expression) => TupleSpreadReads | null;
+/**
+ * The per-position types of a tuple whose only "unsettled" elements are a
+ * trailing OPTIONAL run, or `null` for anything else -- including a `rest`/
+ * `variadic` element, which still has no settled arity at all.
+ *
+ * `closedTupleElementTypesOf` above is right to refuse an optional-tailed
+ * tuple for its own callers: a spread's DESTINATION cares about the source's
+ * true runtime LENGTH (`[...t]` with `t.length === 1` must allocate a
+ * one-element array, not `[t[0], undefined]`), and expanding to the tuple's
+ * full declared arity would silently manufacture a longer collection than the
+ * source ever had. `maxArityTupleSpreadReads` is the one context where a
+ * fixed-at-declared-arity expansion is still exact rather than approximate --
+ * see it for why.
+ *
+ * The type widening happens HERE, at the element, rather than being layered
+ * onto every read: `t[i]` for an absent optional position `i` already reads
+ * `undefined` by ordinary out-of-bounds `[[Get]]`, so the element's own type
+ * has to say so, exactly the way `parameter-slot.ts`'s `parameterSlotTypeOf`
+ * widens an optional PARAMETER's slot with `undefined` for the same reason.
+ * The union is flattened rather than nested -- a member that is already a
+ * union has its own members spliced in -- because only a flat union derives
+ * to this compiler's three-armed optional carrier (`parameter-slot.ts`'s own
+ * comment states why a nested one would not).
+ */
+export declare const maxArityTupleElementTypesOf: (context: ProducerContext, type: StructuralTypeId) => readonly StructuralTypeId[] | null;
+/**
+ * `...expression`'s positional reads, over an OPTIONAL-tailed tuple, for the
+ * one context where that is still sound: a CALL ARGUMENT, where an omitted
+ * argument and an explicitly `undefined` one read identically at the callee.
+ *
+ * Ordinary JS parameter binding makes that true unconditionally: an omitted
+ * argument binds `undefined` (ECMA-262 `FunctionDeclarationInstantiation` /
+ * `IteratorBindingInitialization` over a shorter argument list), and a
+ * defaulted parameter's initializer triggers on `undefined` however it
+ * arrived -- there is no third state a NAMED, non-rest parameter can
+ * observe. So `f(...t)` with `t: [A, B?]` reads IDENTICALLY at the callee
+ * whether `t`'s true runtime length is 1 or 2, PROVIDED:
+ *
+ *  - the callee has no REST formal anywhere the tuple's positions could
+ *    land -- a rest parameter's own `.length` DOES observe the caller's true
+ *    argument count, which this fixed-at-declared-arity expansion cannot
+ *    track;
+ *  - nothing else follows this spread in the argument list -- a written
+ *    argument after it would land at a position that shifts with the
+ *    tuple's TRUE length, which only the real spread ever knows.
+ *
+ * Both conditions are the CALLER's to check (`spread-arguments.ts`'s
+ * `restFrom` and its own last-argument scan) -- this function only expands
+ * the positions, exactly as `tupleSpreadReads` does for a closed tuple.
+ */
+export declare const maxArityTupleSpreadReads: (context: ProducerContext, candidate: CensusCandidate, expression: ts.Expression) => TupleSpreadReads | null;