@geastack/compiler 1.0.15

package/dist/semantics/normalize/producers/mint.d.ts

@@ -0,0 +1,39 @@
+import type { NodeId, OperationFamily, OperationId, ResultRole, StructuralTypeId } from '../../../identity/ids.js';
+import type { CensusBlocker } from '../../model/coverage.js';
+import type { OperandEvaluation, OperandSource, SemanticCaller, SemanticOperand, SemanticResult } from '../../model/operands.js';
+import type { PrimitiveFamily } from '../../model/coverage.js';
+/**
+ * Shared minting helpers for family producers.
+ *
+ * One AST node can normalize to several operations, and the ordinal is what
+ * keeps them apart. Producers must allocate ordinals from a single counter per
+ * node so that two producers cannot mint the same identity for different
+ * operations -- which would silently merge two operations into one.
+ */
+export interface OrdinalCounter {
+    readonly next: (source: NodeId, family: OperationFamily) => number;
+}
+export declare const createOrdinalCounter: () => OrdinalCounter;
+/**
+ * Per-caller evaluation sequencing.
+ *
+ * Evaluation order is a property of the executing context, not of the family
+ * that happens to be publishing. One counter per caller shared by every producer
+ * is what keeps two families from handing out the same ordinal inside one
+ * function -- which would give two distinct operations one identity.
+ */
+export interface EvaluationOrdinals {
+    readonly next: (caller: SemanticCaller) => number;
+}
+export declare const createEvaluationOrdinals: () => EvaluationOrdinals;
+export declare const mintOperationId: (counter: OrdinalCounter, source: NodeId, family: OperationFamily) => OperationId;
+export declare const mintResult: (operation: OperationId, role: ResultRole, type: StructuralTypeId) => SemanticResult;
+export declare const operand: (role: string, ordinal: number, source: OperandSource, type: StructuralTypeId, evaluation?: OperandEvaluation) => SemanticOperand;
+/**
+ * A blocker states a missing capability, not a source shape.
+ *
+ * "cannot normalize `foo.bar` in file X" is not a blocker: it names a site. The
+ * blocker must name what the compiler cannot yet do, so that fixing it fixes
+ * every site at once.
+ */
+export declare const blocked: (source: NodeId, family: OperationFamily, reason: string, missingPrimitive: PrimitiveFamily | null) => CensusBlocker;

package/dist/semantics/normalize/producers/mint.js

@@ -0,0 +1,44 @@
+import { operationId, semanticResultId } from '../../../identity/ids.js';
+export const createOrdinalCounter = () => {
+    const used = new Map();
+    return {
+        next: (source, family) => {
+            const key = `${source}|${family}`;
+            const ordinal = used.get(key) ?? 0;
+            used.set(key, ordinal + 1);
+            return ordinal;
+        }
+    };
+};
+const callerKey = (caller) => (caller.kind === 'function' ? `fn|${caller.functionId}` : `region|${caller.regionId}`);
+export const createEvaluationOrdinals = () => {
+    const used = new Map();
+    return {
+        next: (caller) => {
+            const key = callerKey(caller);
+            const ordinal = used.get(key) ?? 0;
+            used.set(key, ordinal + 1);
+            return ordinal;
+        }
+    };
+};
+export const mintOperationId = (counter, source, family) => operationId(source, family, counter.next(source, family));
+export const mintResult = (operation, role, type) => ({
+    id: semanticResultId(operation, role),
+    role,
+    type
+});
+export const operand = (role, ordinal, source, type, evaluation = { kind: 'runtime' }) => ({ role, ordinal, source, type, evaluation });
+/**
+ * A blocker states a missing capability, not a source shape.
+ *
+ * "cannot normalize `foo.bar` in file X" is not a blocker: it names a site. The
+ * blocker must name what the compiler cannot yet do, so that fixing it fixes
+ * every site at once.
+ */
+export const blocked = (source, family, reason, missingPrimitive) => ({
+    source,
+    family,
+    reason,
+    missingPrimitive
+});

package/dist/semantics/normalize/producers/nullish.d.ts

@@ -0,0 +1,16 @@
+import ts from 'typescript';
+/**
+ * Whether a type can never be `null` or `undefined`.
+ *
+ * `any`/`unknown` do not count: neither rules out either value, so a proof
+ * built on them is not a proof. `void` does not count either -- a `void` in a
+ * stored position is `undefined`, and treating it as a non-nullish type is how
+ * an absent value passes for a present one.
+ *
+ * Two questions in this compiler turn on it, and they must agree. A property
+ * access asks it of a receiver to decide whether the `[[Get]]` can throw
+ * (`properties.ts`), and both halves of an optional chain ask it of a declared
+ * type to decide whether the `undefined` the checker put on their result is the
+ * operator's own -- and so removable -- or the declaration's, and not.
+ */
+export declare const excludesNullish: (type: ts.Type) => boolean;

package/dist/semantics/normalize/producers/nullish.js

@@ -0,0 +1,27 @@
+import ts from 'typescript';
+/**
+ * Whether a type can never be `null` or `undefined`.
+ *
+ * `any`/`unknown` do not count: neither rules out either value, so a proof
+ * built on them is not a proof. `void` does not count either -- a `void` in a
+ * stored position is `undefined`, and treating it as a non-nullish type is how
+ * an absent value passes for a present one.
+ *
+ * Two questions in this compiler turn on it, and they must agree. A property
+ * access asks it of a receiver to decide whether the `[[Get]]` can throw
+ * (`properties.ts`), and both halves of an optional chain ask it of a declared
+ * type to decide whether the `undefined` the checker put on their result is the
+ * operator's own -- and so removable -- or the declaration's, and not.
+ */
+export const excludesNullish = (type) => {
+    const constituents = type.isUnion() ? type.types : [type];
+    const nullishOrUnproven = ts.TypeFlags.Null |
+        ts.TypeFlags.Undefined |
+        ts.TypeFlags.Void |
+        ts.TypeFlags.Any |
+        ts.TypeFlags.Unknown |
+        ts.TypeFlags.TypeParameter |
+        ts.TypeFlags.Conditional |
+        ts.TypeFlags.IndexedAccess;
+    return constituents.every((member) => (member.flags & nullishOrUnproven) === 0);
+};

package/dist/semantics/normalize/producers/object-assignment.d.ts

@@ -0,0 +1,8 @@
+import ts from 'typescript';
+import { type ObjectAssignmentElement } from '../assignment-patterns.js';
+import type { CensusCandidate } from '../census.js';
+import type { CandidateContribution } from '../contribution.js';
+import type { ProducerContext } from '../producer-context.js';
+/** Assignment patterns use the same reads and writes as ordinary expressions. */
+export declare const contributeObjectAssignmentSource: (context: ProducerContext, candidate: CensusCandidate, node: ts.ObjectLiteralExpression) => CandidateContribution;
+export declare const contributeObjectAssignmentElement: (context: ProducerContext, candidate: CensusCandidate, node: ObjectAssignmentElement) => CandidateContribution;

package/dist/semantics/normalize/producers/object-assignment.js

@@ -0,0 +1,204 @@
+import ts from 'typescript';
+import { operationId, regionId, semanticResultId } from '../../../identity/ids.js';
+import { normalCompletion, throwingCompletion, pureEffects } from '../../model/operands.js';
+import { objectAssignmentSource } from '../assignment-patterns.js';
+import { memberTypeOf } from '../derived-expression-type.js';
+import { bindingKindOf } from './binding-kind.js';
+import { unwrapErasedExpression } from './erasure.js';
+import { mintOperationId, mintResult, operand } from './mint.js';
+import { citeExpressionResult } from './references.js';
+import { asBlocked, isStrictContext, valueEdgesInto } from './shared.js';
+/**
+ * This object pattern's own source, in whichever of the two shapes it
+ * takes: an ordinary `=` right-hand side (`objectAssignmentSource`), or a
+ * for-of LOOP-HEAD pattern (`for ({ x, y } of points)`), which has no `=` at
+ * all -- ECMA-262 assigns it from the loop's own IteratorStep, cited by the
+ * SAME fixed ordinal `producers/destructuring.ts`'s `arrayAssignmentSourceInfo`
+ * already cites for the array-literal sibling of this identical shape
+ * (`mintIteratorSteps` reserves `next` at ordinal 2 for exactly this). The
+ * loop's own ITERABLE states the per-iteration element -- never the pattern
+ * node's own checker type, which for a literal written as an assignment
+ * target is a contextually-typed shape matching the TARGET, not the source,
+ * the same trap that function's header documents at length.
+ *
+ * A NESTED object pattern (`{ a: { b } } = ...`) is still refused: its
+ * source is another element's own resolved value, which this producer has
+ * no citation for yet, exactly as before this loop-head shape was added.
+ */
+const objectAssignmentSourceOf = (context, pattern) => {
+    const direct = objectAssignmentSource(pattern);
+    if (direct) {
+        const cited = citeExpressionResult(direct, context);
+        if (cited.kind === 'unmodelled')
+            return null;
+        return {
+            source: cited.source,
+            structuralType: context.types.typeAt(direct),
+            rawType: context.checker.getNonNullableType(context.types.rawTypeAt(direct))
+        };
+    }
+    const parent = pattern.parent;
+    if (!ts.isForOfStatement(parent) || parent.initializer !== pattern)
+        return null;
+    const id = operationId(context.identities.nodeIdOf(parent), 'protocol', 2);
+    const iterableRaw = context.checker.getNonNullableType(context.types.rawTypeAt(parent.expression));
+    const elementRaw = context.checker.getIndexTypeOfType(iterableRaw, ts.IndexKind.Number);
+    if (!elementRaw)
+        return null;
+    const nonNullElement = context.checker.getNonNullableType(elementRaw);
+    return {
+        source: { kind: 'result', result: semanticResultId(id, 'value') },
+        structuralType: context.types.typeOf(elementRaw),
+        rawType: nonNullElement
+    };
+};
+/** Assignment patterns use the same reads and writes as ordinary expressions. */
+export const contributeObjectAssignmentSource = (context, candidate, node) => {
+    if (node.properties.some((property) => !ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property))) {
+        return asBlocked(candidate.id, 'destructuring', 'rest properties in object assignment are not yet modelled', null);
+    }
+    const info = objectAssignmentSourceOf(context, node);
+    if (!info)
+        return asBlocked(candidate.id, 'destructuring', 'nested object assignment sources are not yet modelled', null);
+    const id = mintOperationId(context.ordinals, candidate.id, 'destructuring');
+    const op = {
+        id,
+        family: 'destructuring',
+        form: 'object-source',
+        caller: candidate.caller,
+        evaluationOrdinal: candidate.evaluationOrdinal,
+        operands: [operand('base', 0, info.source, info.structuralType)],
+        results: [mintResult(id, 'value', info.structuralType)],
+        completion: throwingCompletion,
+        effects: pureEffects
+    };
+    return { kind: 'operations', operations: [op], edges: valueEdgesInto(id, op.operands) };
+};
+const staticPropertyName = (name) => ts.isIdentifier(name) || ts.isStringLiteralLike(name) || ts.isNumericLiteral(name) ? name.text : null;
+export const contributeObjectAssignmentElement = (context, candidate, node) => {
+    const refuse = (reason) => asBlocked(candidate.id, 'destructuring', reason, null);
+    const pattern = node.parent;
+    if (!ts.isObjectLiteralExpression(pattern))
+        return refuse('object assignment element has no object pattern');
+    const info = objectAssignmentSourceOf(context, pattern);
+    if (!info)
+        return refuse('nested object assignment sources are not yet modelled');
+    if (ts.isShorthandPropertyAssignment(node) && node.objectAssignmentInitializer)
+        return refuse('defaulted object assignment is not yet modelled');
+    const target = unwrapErasedExpression(ts.isPropertyAssignment(node) ? node.initializer : node.name);
+    if (!ts.isIdentifier(target) && !ts.isPropertyAccessExpression(target) && !ts.isElementAccessExpression(target)) {
+        return refuse('object assignment target requires a name or a property reference; defaults and nested patterns are not yet modelled');
+    }
+    const key = staticPropertyName(node.name);
+    if (key === null)
+        return refuse('computed object assignment source keys are not yet modelled');
+    const stringType = context.table.intern({ kind: 'primitive', primitive: 'string' });
+    const sourceType = info.structuralType;
+    const rawSource = info.rawType;
+    const rawMember = memberTypeOf(context.checker, rawSource, key, node) ?? context.checker.getIndexTypeOfType(rawSource, ts.IndexKind.String);
+    // The extracted property's type belongs to the source, not to the target
+    // slot. A real conversion between those two is audited at the store.
+    const extractedType = context.types.typeOf(rawMember ?? ((rawSource.flags & ts.TypeFlags.Any) !== 0 ? rawSource : context.checker.getUndefinedType()));
+    const sourceResult = semanticResultId(operationId(context.identities.nodeIdOf(pattern), 'destructuring', 0), 'value');
+    const getId = mintOperationId(context.ordinals, candidate.id, 'destructuring');
+    const get = {
+        id: getId,
+        family: 'destructuring',
+        form: 'object-pattern',
+        caller: candidate.caller,
+        evaluationOrdinal: candidate.evaluationOrdinal,
+        operands: [
+            operand('base', 0, { kind: 'result', result: sourceResult }, sourceType),
+            operand('key', 0, { kind: 'constant', text: key, literal: 'string' }, stringType)
+        ],
+        results: [mintResult(getId, 'value', extractedType)],
+        completion: throwingCompletion,
+        effects: { readsMutableState: true, writesMutableState: false, allocates: false, callsUserCode: true }
+    };
+    const value = { kind: 'result', result: semanticResultId(getId, 'value') };
+    let write;
+    if (ts.isIdentifier(target)) {
+        // Shorthand keys have their own symbol. The value symbol names the cell.
+        const symbol = ts.isShorthandPropertyAssignment(node)
+            ? context.checker.getShorthandAssignmentValueSymbol(node)
+            : context.checker.getSymbolAtLocation(target);
+        const declaration = symbol ? context.identities.symbolDeclarationId(symbol) : null;
+        const declarationNode = symbol ? context.identities.declarationOfSymbol(symbol) : null;
+        if (!declaration || !declarationNode)
+            return refuse('object assignment target has no declared binding cell');
+        const id = mintOperationId(context.ordinals, candidate.id, 'binding');
+        const targetType = context.types.typeAt(target);
+        write = {
+            id,
+            family: 'binding',
+            action: 'write',
+            declaration,
+            ...bindingKindOf(declarationNode),
+            ...(context.commonJsBindings.has(declaration)
+                ? {
+                    commonJs: {
+                        global: context.commonJsBindings.get(declaration),
+                        owner: regionId(context.identities.nodeIdOf(target.getSourceFile()), 'module-body')
+                    }
+                }
+                : {}),
+            caller: candidate.caller,
+            evaluationOrdinal: candidate.evaluationOrdinal,
+            operands: [operand('value', 0, value, targetType)],
+            results: [mintResult(id, 'value', targetType)],
+            completion: normalCompletion,
+            effects: { ...pureEffects, writesMutableState: true }
+        };
+    }
+    else {
+        const receiver = citeExpressionResult(target.expression, context);
+        if (receiver.kind === 'unmodelled')
+            return refuse(receiver.reason);
+        const targetKey = ts.isPropertyAccessExpression(target)
+            ? target.name.text
+            : ts.isStringLiteralLike(target.argumentExpression) || ts.isNumericLiteral(target.argumentExpression)
+                ? target.argumentExpression.text
+                : null;
+        if (targetKey === null)
+            return refuse('computed object assignment target keys are not yet modelled');
+        const id = mintOperationId(context.ordinals, candidate.id, 'property');
+        const receiverType = context.types.typeAt(target.expression);
+        write = {
+            id,
+            family: 'property',
+            internalMethod: 'set',
+            strict: isStrictContext(target, context.buildIsStrict),
+            keyIsComputed: false,
+            descriptor: null,
+            caller: candidate.caller,
+            evaluationOrdinal: candidate.evaluationOrdinal,
+            operands: [
+                operand('receiver', 0, receiver.source, receiverType, { kind: 'provenance' }),
+                operand('key', 0, { kind: 'constant', text: targetKey, literal: 'string' }, stringType),
+                operand('value', 0, value, extractedType)
+            ],
+            results: [mintResult(id, 'value', receiverType)],
+            completion: throwingCompletion,
+            effects: { readsMutableState: false, writesMutableState: true, allocates: false, callsUserCode: true }
+        };
+    }
+    const edges = [
+        ...valueEdgesInto(getId, get.operands),
+        ...valueEdgesInto(write.id, write.operands),
+        { kind: 'evaluation', from: getId, to: write.id }
+    ];
+    // The write orders BEFORE the enclosing `=` expression's own value -- real
+    // only when this pattern IS the left side of one (`({ a } = src)` reads as
+    // the whole expression producing `src`, so every write must precede that).
+    // A for-of LOOP-HEAD pattern has no such enclosing expression at all: the
+    // pattern is the loop's own initializer, and citing a nonexistent
+    // `computation` operation at the loop statement's node id pointed this
+    // edge at whatever real operation happens to share that identity instead
+    // -- silently, and only visible as an unrelated evaluation-graph cycle at
+    // lowering.
+    const assignmentSource = objectAssignmentSource(pattern);
+    if (assignmentSource) {
+        edges.push({ kind: 'evaluation', from: write.id, to: operationId(context.identities.nodeIdOf(pattern.parent), 'computation', 0) });
+    }
+    return { kind: 'operations', operations: [get, write], edges };
+};

package/dist/semantics/normalize/producers/object-tag.d.ts

@@ -0,0 +1,9 @@
+import ts from 'typescript';
+import type { CensusCandidate } from '../census.js';
+import type { CandidateContribution } from '../contribution.js';
+import type { ProducerContext } from '../producer-context.js';
+/** Authenticate the borrowed algorithm while declarations and mutation facts exist. */
+export declare const isAuthenticatedObjectTag: (context: ProducerContext, node: ts.Node) => node is ts.CallExpression;
+export declare const contributeObjectTag: (context: ProducerContext, candidate: CensusCandidate, node: ts.Node) => CandidateContribution | null;
+/** Proven intrinsic callee reads are consumed by the ObjectTag algorithm itself. */
+export declare const isObjectTagCalleePart: (context: ProducerContext, node: ts.Node) => boolean;

package/dist/semantics/normalize/producers/object-tag.js

@@ -0,0 +1,119 @@
+import { outermostErasureOf } from './erasure.js';
+import ts from 'typescript';
+import { throwingCompletion } from '../../model/operands.js';
+import { isGlobalObjectConstructor } from '../derived-expression-type.js';
+import { mintOperationId, mintResult, operand } from './mint.js';
+import { sourceForValue, unwrapErased, valueEdgesInto } from './shared.js';
+import { intactIntrinsicPrototypeKeysType } from '../intrinsic-prototype.js';
+import { intrinsicObjectKeysIntact } from '../host-mutation-keys.js';
+/** Authenticate the borrowed algorithm while declarations and mutation facts exist. */
+export const isAuthenticatedObjectTag = (context, node) => {
+    if (!ts.isCallExpression(node) || ts.isOptionalChain(node) || node.arguments.some(ts.isSpreadElement))
+        return false;
+    const call = unwrapErased(node.expression);
+    if (!ts.isPropertyAccessExpression(call) || call.name.text !== 'call')
+        return false;
+    const method = unwrapErased(call.expression);
+    if (!ts.isPropertyAccessExpression(method) || method.name.text !== 'toString')
+        return false;
+    const prototype = unwrapErased(method.expression);
+    if (!ts.isPropertyAccessExpression(prototype) || prototype.name.text !== 'prototype')
+        return false;
+    const owner = prototype.expression;
+    if (!isGlobalObjectConstructor(context.checker, owner, context.checker.getTypeAtLocation(owner)))
+        return false;
+    const taint = context.globalHostMutationTaint;
+    if (taint.has('*'))
+        return false;
+    // Function.call and CallableFunction.call have distinct checker declarations
+    // but borrow the same runtime prototype. Ask its shared mutation identity,
+    // for the one key this borrowing reads from it.
+    if (intactIntrinsicPrototypeKeysType(context, 'Function', { names: ['call'] }, owner) === null)
+        return false;
+    // Each link reads one key: `Object.prototype`, then its `toString`, then
+    // that function's `call`. A member link must not have been replaced; an
+    // owner link must not have had the next key written.
+    const keyReadThrough = new Map([
+        [owner, 'prototype'],
+        [prototype.name, 'toString'],
+        [method.name, 'call']
+    ]);
+    for (const location of [owner, prototype.name, method.name, call.name]) {
+        const symbol = context.checker.getSymbolAtLocation(location);
+        const declarations = location === owner ? (symbol?.valueDeclaration ? [symbol.valueDeclaration] : []) : (symbol?.declarations ?? []);
+        if (declarations.length === 0 || !declarations.every((declaration) => context.isStandardLibraryDeclaration?.(declaration) === true))
+            return false;
+        const identity = symbol
+            ? location === owner
+                ? context.identities.symbolValueDeclarationId(symbol, owner)
+                : context.identities.symbolDeclarationId(symbol)
+            : null;
+        if (identity === null)
+            return false;
+        const next = keyReadThrough.get(location);
+        // The owner and `Object.prototype` are objects read through by key; the
+        // member declarations are values that must not have been replaced.
+        const objectIntact = next === undefined || intrinsicObjectKeysIntact(taint, identity, { names: [next] });
+        const replaced = location !== owner && location !== prototype.name && taint.has(identity);
+        if (!objectIntact || replaced)
+            return false;
+    }
+    const primitivePrototypesIntact = (type) => {
+        if (type.isUnion())
+            return type.types.every(primitivePrototypesIntact);
+        const flags = type.flags;
+        const names = (flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0
+            ? ['Number', 'String', 'Boolean', 'BigInt', 'Symbol']
+            : (flags & ts.TypeFlags.NumberLike) !== 0
+                ? ['Number']
+                : (flags & ts.TypeFlags.StringLike) !== 0
+                    ? ['String']
+                    : (flags & ts.TypeFlags.BooleanLike) !== 0
+                        ? ['Boolean']
+                        : (flags & ts.TypeFlags.BigIntLike) !== 0
+                            ? ['BigInt']
+                            : (flags & ts.TypeFlags.ESSymbolLike) !== 0
+                                ? ['Symbol']
+                                : [];
+        // A primitive receiver's tag is read from its wrapper prototype's @@toStringTag.
+        return names.every((name) => intactIntrinsicPrototypeKeysType(context, name, { names: ['@@toStringTag'] }, node) !== null);
+    };
+    const receiver = node.arguments[0];
+    return !receiver || primitivePrototypesIntact(context.checker.getTypeAtLocation(receiver));
+};
+export const contributeObjectTag = (context, candidate, node) => {
+    if (!isAuthenticatedObjectTag(context, node))
+        return null;
+    // Preserve the invocation candidate's published identity: callers already cite it.
+    // Authentication changes the operation's algorithm, not the source expression.
+    const id = mintOperationId(context.ordinals, candidate.id, 'invocation');
+    const args = node.arguments;
+    const receiver = args[0];
+    const receiverIsVoid = receiver !== undefined && (context.checker.getTypeAtLocation(receiver).flags & ts.TypeFlags.Void) !== 0;
+    const operands = [
+        receiver && !receiverIsVoid
+            ? operand('operand', 0, sourceForValue(context, receiver), context.types.typeAt(receiver))
+            : operand('operand', 0, { kind: 'constant', text: 'undefined', literal: 'undefined' }, context.types.typeOf(context.checker.getUndefinedType())),
+        ...(receiverIsVoid ? args : args.slice(1)).map((argument, index) => operand('ignored-argument', index, sourceForValue(context, argument), context.types.typeAt(argument)))
+    ];
+    const operation = {
+        id,
+        family: 'computation',
+        caller: candidate.caller,
+        form: 'unary',
+        operator: 'ObjectTag',
+        operands,
+        results: [mintResult(id, 'value', context.types.typeOf(context.checker.getStringType()))],
+        completion: throwingCompletion,
+        effects: { readsMutableState: true, writesMutableState: false, allocates: false, callsUserCode: true },
+        evaluationOrdinal: candidate.evaluationOrdinal
+    };
+    return { kind: 'operations', operations: [operation], edges: valueEdgesInto(id, operands) };
+};
+/** Proven intrinsic callee reads are consumed by the ObjectTag algorithm itself. */
+export const isObjectTagCalleePart = (context, node) => {
+    let current = outermostErasureOf(node);
+    while (ts.isPropertyAccessExpression(current.parent) && current.parent.expression === current)
+        current = outermostErasureOf(current.parent);
+    return ts.isCallExpression(current.parent) && current.parent.expression === current && isAuthenticatedObjectTag(context, current.parent);
+};

package/dist/semantics/normalize/producers/optional-chain.d.ts

@@ -0,0 +1,44 @@
+import ts from 'typescript';
+/**
+ * Which link of an optional chain answers for the whole chain, and what it
+ * branches on.
+ *
+ * Three producers ask this -- `properties.ts` builds the gated `[[Get]]`,
+ * `invocations.ts` builds the gated `[[Call]]`, and `references.ts` decides
+ * which of a link's two results a citer gets -- and they must agree exactly. A
+ * link that publishes a `short-circuit` result nobody cites leaves a value
+ * unread; a citer that asks for one nobody published names a result no producer
+ * installed, which the publication guard withholds silently. So the rule lives
+ * here once rather than as three spellings of it.
+ */
+/**
+ * The nearest optional link's base, shared by every operation in that chain.
+ * ECMA-262 (2025), OptionalExpression / ChainEvaluation: plain suffixes keep
+ * the original short-circuit condition; only another ?. introduces a new one.
+ * Parentheses end a chain, so the walk follows the checker's OptionalChain
+ * flags instead of erasing expression wrappers before asking the question.
+ */
+export declare const optionalChainGuardOf: (node: ts.Node) => ts.Expression | null;
+export declare const optionalCallGuardOf: (node: ts.CallExpression) => ts.Expression | null;
+/** Every value-producing link publishes the whole expression's undefined arm. */
+export declare const publishesShortCircuit: (node: ts.Node) => boolean;
+/**
+ * What a call's signature returns on the branch where it actually ran.
+ *
+ * The checker augments the signature it resolves for an optional call: ask
+ * `d?.scale(2)` for its resolved return and it answers `number | undefined`,
+ * not `number`. That `undefined` is the *chain's*, not the method's -- the
+ * method returns `number` and never runs at all on the other branch -- so a
+ * consumer that believes it builds a callee carrier the callee does not have,
+ * and the store of the real method into it has no conversion.
+ *
+ * The strip is licensed rather than assumed, exactly as `presentValueTypeOf`
+ * licenses the property half: the signature is asked for its *own* declared
+ * return, uninstantiated by any call site, and the `undefined` is removed only
+ * when that has none of its own. A signature with no declaration, an inferred
+ * return this cannot re-ask, or a genuinely `undefined`-returning one keeps the
+ * union -- wider than the truth, and never narrower than it.
+ */
+export declare const presentReturnTypeOf: (checker: ts.TypeChecker, signature: ts.Signature) => ts.Type;
+/** Whether this call is one whose resolved signature the checker augmented with the chain's `undefined`. */
+export declare const isShortCircuitingCall: (call: ts.CallExpression | ts.NewExpression | ts.TaggedTemplateExpression) => boolean;

package/dist/semantics/normalize/producers/optional-chain.js

@@ -0,0 +1,75 @@
+import ts from 'typescript';
+import { excludesNullish } from './nullish.js';
+/**
+ * Which link of an optional chain answers for the whole chain, and what it
+ * branches on.
+ *
+ * Three producers ask this -- `properties.ts` builds the gated `[[Get]]`,
+ * `invocations.ts` builds the gated `[[Call]]`, and `references.ts` decides
+ * which of a link's two results a citer gets -- and they must agree exactly. A
+ * link that publishes a `short-circuit` result nobody cites leaves a value
+ * unread; a citer that asks for one nobody published names a result no producer
+ * installed, which the publication guard withholds silently. So the rule lives
+ * here once rather than as three spellings of it.
+ */
+/**
+ * The nearest optional link's base, shared by every operation in that chain.
+ * ECMA-262 (2025), OptionalExpression / ChainEvaluation: plain suffixes keep
+ * the original short-circuit condition; only another ?. introduces a new one.
+ * Parentheses end a chain, so the walk follows the checker's OptionalChain
+ * flags instead of erasing expression wrappers before asking the question.
+ */
+export const optionalChainGuardOf = (node) => {
+    if (!ts.isOptionalChain(node))
+        return null;
+    if (ts.isNonNullExpression(node))
+        return optionalChainGuardOf(node.expression);
+    if (node.questionDotToken !== undefined)
+        return node.expression;
+    return optionalChainGuardOf(node.expression);
+};
+export const optionalCallGuardOf = (node) => optionalChainGuardOf(node);
+/** Every value-producing link publishes the whole expression's undefined arm. */
+export const publishesShortCircuit = (node) => optionalChainGuardOf(node) !== null;
+/**
+ * What a call's signature returns on the branch where it actually ran.
+ *
+ * The checker augments the signature it resolves for an optional call: ask
+ * `d?.scale(2)` for its resolved return and it answers `number | undefined`,
+ * not `number`. That `undefined` is the *chain's*, not the method's -- the
+ * method returns `number` and never runs at all on the other branch -- so a
+ * consumer that believes it builds a callee carrier the callee does not have,
+ * and the store of the real method into it has no conversion.
+ *
+ * The strip is licensed rather than assumed, exactly as `presentValueTypeOf`
+ * licenses the property half: the signature is asked for its *own* declared
+ * return, uninstantiated by any call site, and the `undefined` is removed only
+ * when that has none of its own. A signature with no declaration, an inferred
+ * return this cannot re-ask, or a genuinely `undefined`-returning one keeps the
+ * union -- wider than the truth, and never narrower than it.
+ */
+// Deliberately checker-only, not a bypass to route through a census: both
+// callers (`producers/shared.ts`'s `resolvedCalleeSignatureType`,
+// `producers/invocations.ts`'s `buildSelectedSignature`) already reconcile
+// a census answer around this -- `invocations.ts`'s own extensive comment on
+// `censusReturn`/`siteReturn` covers exactly why this stays the checker's raw
+// SIGNATURE answer (this callee's own declared shape, stripped of the
+// chain's synthetic `undefined`) rather than a second place asking the same
+// return-binding question the census already owns downstream.
+export const presentReturnTypeOf = (checker, signature) => {
+    const returned = signature.getReturnType();
+    const declaration = signature.getDeclaration();
+    const declared = declaration ? checker.getSignatureFromDeclaration(declaration) : undefined;
+    // `void | undefined` describes the chain's value, but `() => void` is the
+    // method's ABI. Normalizing that union as a stored value would publish an
+    // undefined-returning callable and make the actual void method unassignable.
+    // An explicitly void signature has no type parameters in its result to
+    // instantiate, so its declaration is also the exact present-branch answer.
+    if (declared && (declared.getReturnType().flags & ts.TypeFlags.Void) !== 0)
+        return declared.getReturnType();
+    if (!declared || !excludesNullish(declared.getReturnType()))
+        return returned;
+    return checker.getNonNullableType(returned);
+};
+/** Whether this call is one whose resolved signature the checker augmented with the chain's `undefined`. */
+export const isShortCircuitingCall = (call) => ts.isCallExpression(call) && optionalCallGuardOf(call) !== null;

package/dist/semantics/normalize/producers/properties.d.ts

@@ -0,0 +1,21 @@
+import ts from 'typescript';
+import { type StructuralTypeId } from '../../../identity/ids.js';
+import type { FamilyProducer } from '../contribution.js';
+import type { ProducerContext } from '../producer-context.js';
+type AccessNode = ts.PropertyAccessExpression | ts.ElementAccessExpression;
+/**
+ * The value type published for this exact property expression.
+ *
+ * Consumers cite the property producer's result by identity, so they must cite
+ * its type from the same rule as well. In particular, an indexed dictionary
+ * read can publish `T | undefined` even when TypeScript's unchecked index
+ * signature reports only `T`; asking the checker again at a conditional merge
+ * erases the missing-key state the property operation deliberately restored.
+ * Optional chains cite their whole-expression result, including the synthetic
+ * `undefined` branch, rather than the present-only internal `[[Get]]` result.
+ */
+export declare const propertyExpressionValueTypeAt: (context: ProducerContext, node: AccessNode) => StructuralTypeId;
+/** Whether an expression is an authenticated host identity that cannot be nullish in this program. */
+export declare const isAlwaysPresentHostExpression: (expression: ts.Expression, context: ProducerContext) => boolean;
+export declare const createPropertyProducer: (context: ProducerContext) => FamilyProducer;
+export {};