@geastack/compiler 1.0.15

package/dist/semantics/normalize/structural-rules.d.ts

@@ -0,0 +1,112 @@
+import ts from 'typescript';
+import type { StructuralTypeId } from '../../identity/ids.js';
+/**
+ * One step of `structural.ts`'s `typeAt`, keyed by the FORM it serves.
+ *
+ * `typeAt` was an ordered chain of thirty-nine `if (answer) return answer`
+ * steps (a join, not an ordered chain). The order was load-bearing and
+ * almost entirely undocumented as order: where two steps can both answer one
+ * node, whichever was written first wins, and that precedence is the answer --
+ * not a tie-break over two answers that agree. `collection` before `bag` is a
+ * commented choice; `field` versus `collection` for one declaration is never
+ * cross-checked at all. A chain like that cannot be extended by adding a row,
+ * which is the whole complaint 4.3 exists to fix: every new form means finding
+ * the right place in a sequence whose constraints live in nobody's head.
+ *
+ * A rule states which forms it serves. The dispatcher selects by form, so a
+ * rule that cannot possibly answer for a node is never asked, and two rules
+ * claiming one form become VISIBLE -- a disagreement to resolve at its root,
+ * rather than a precedence nobody chose.
+ *
+ * `forms: null` means "any node", which is where the port currently stands for
+ * most rules: it does NOT assert that the rule is form-independent, only that
+ * its own first test is not a node-kind test and so nobody has yet written
+ * down what it answers for. Order still decides among those, exactly as the
+ * chain did. Every `forms: null` is a row this phase still owes a form, and
+ * counting them is the honest measure of the port.
+ */
+export interface StructuralRule {
+    /** What this rule is called when a disagreement names it. Stable; it is an identifier in reports, not prose. */
+    readonly name: string;
+    /** The syntactic forms this rule answers for, or `null` for a rule that is not keyed by form yet. */
+    readonly forms: readonly ts.SyntaxKind[] | null;
+    /**
+     * Must be correct for ANY node, including one outside `forms`.
+     *
+     * `forms` is a claim the dispatcher acts on and the audit checks -- never the
+     * thing that makes a rule right. Deleting a resolver's own kind test because
+     * `forms` "already covers it" produces a rule that is correct only while
+     * nobody asks it, and the first port to try that
+     * (`binding-pattern-is-its-source`) immediately answered for call
+     * expressions and string literals under `GEA_STRUCTURAL_FORM_AUDIT`. That is
+     * also precisely why the audit can be a gate at all: it asks every rule for
+     * every node, so a rule leaning on `forms` for correctness reports itself.
+     */
+    readonly resolve: (node: ts.Node) => StructuralTypeId | null;
+}
+/** Two rules that both answered for one node, and what each said. */
+export interface StructuralDisagreement {
+    readonly kind: ts.SyntaxKind;
+    readonly winner: string;
+    readonly other: string;
+    /** Whether the two agreed on the id. An AGREEING pair is still a finding: two authorities that happen to match today. */
+    readonly agreed: boolean;
+}
+/**
+ * Whether the extra work that finds disagreements runs at all.
+ *
+ * It is opt-in for a reason this codebase has already paid for once: asking a
+ * rule that the chain would have skipped INTERNS structural ids that the
+ * compilation never needed, and interning an id nobody needed renumbers every
+ * later id -- and with it every `gea_record_type_N` in the emitted C++. The
+ * cell-facts agreement instrument renumbered 68 corpus programs exactly that
+ * way (`cells/agreement.ts`). An instrument that changes the artifact it
+ * measures is not an instrument, so this one runs only when asked for.
+ */
+export declare const structuralDisagreementsEnabled: () => boolean;
+/** A rule that answered for a node whose form its `forms` does not claim. */
+export interface StructuralFormViolation {
+    readonly rule: string;
+    readonly kind: ts.SyntaxKind;
+}
+/**
+ * Whether to audit the form keys instead of trusting them.
+ *
+ * This is the gate for the 4.3 port, and it is the only thing that can be one.
+ * A `forms` list is a CLAIM about which nodes a rule can answer for, arrived at
+ * by reading the resolver and everything it delegates to; a wrong claim does
+ * not fail to compile and does not throw -- it silently stops asking a rule for
+ * a whole syntactic form, which is a miscompile that looks like a design.
+ *
+ * Under audit every rule is asked for every node, in declaration order, which
+ * is exactly what the chain did before the port. So the answer is the
+ * pre-port answer by construction, and any rule that answers outside its own
+ * `forms` is reported. Zero violations over a corpus is the proof that keying
+ * changed nothing; one violation names the rule and the form it lied about.
+ *
+ * Opt-in for the same reason as the disagreement instrument, and more sharply:
+ * asking every rule for every node interns ids the compilation never needed.
+ * An audit run's emitted C++ must never be compared with anything.
+ */
+export declare const structuralFormAuditEnabled: () => boolean;
+/** A rule set with its per-form selection already made. */
+export interface StructuralRuleSet {
+    /** The first answer among the rules that serve this node's form, or `null` if none answered. */
+    readonly resolve: (node: ts.Node, record?: (disagreement: StructuralDisagreement) => void) => StructuralTypeId | null;
+    /** Rules caught answering outside their declared forms. Always empty unless `GEA_STRUCTURAL_FORM_AUDIT` is set. */
+    readonly formViolations: readonly StructuralFormViolation[];
+}
+/**
+ * Prepare a rule set for dispatch.
+ *
+ * The selection is cached per syntax kind rather than recomputed per node, and
+ * that is not micro-optimisation: `typeAt` is asked for essentially every node
+ * of every source file, so filtering the whole rule list at each call would put
+ * an allocation and a linear scan on the hottest path in the normalize stage --
+ * the same shape of cost that `geatsc-normalize-stage-quadratic-scans` already
+ * cost this compiler 48 seconds once.
+ *
+ * Order within a form is the order the rules were declared in, which is the
+ * order the chain asked them, so preparing changes no answer.
+ */
+export declare const prepareStructuralRules: (rules: readonly StructuralRule[]) => StructuralRuleSet;

package/dist/semantics/normalize/structural-rules.js

@@ -0,0 +1,93 @@
+/**
+ * Whether the extra work that finds disagreements runs at all.
+ *
+ * It is opt-in for a reason this codebase has already paid for once: asking a
+ * rule that the chain would have skipped INTERNS structural ids that the
+ * compilation never needed, and interning an id nobody needed renumbers every
+ * later id -- and with it every `gea_record_type_N` in the emitted C++. The
+ * cell-facts agreement instrument renumbered 68 corpus programs exactly that
+ * way (`cells/agreement.ts`). An instrument that changes the artifact it
+ * measures is not an instrument, so this one runs only when asked for.
+ */
+export const structuralDisagreementsEnabled = () => Boolean(process.env['GEA_STRUCTURAL_DISAGREEMENT']);
+/**
+ * Whether to audit the form keys instead of trusting them.
+ *
+ * This is the gate for the 4.3 port, and it is the only thing that can be one.
+ * A `forms` list is a CLAIM about which nodes a rule can answer for, arrived at
+ * by reading the resolver and everything it delegates to; a wrong claim does
+ * not fail to compile and does not throw -- it silently stops asking a rule for
+ * a whole syntactic form, which is a miscompile that looks like a design.
+ *
+ * Under audit every rule is asked for every node, in declaration order, which
+ * is exactly what the chain did before the port. So the answer is the
+ * pre-port answer by construction, and any rule that answers outside its own
+ * `forms` is reported. Zero violations over a corpus is the proof that keying
+ * changed nothing; one violation names the rule and the form it lied about.
+ *
+ * Opt-in for the same reason as the disagreement instrument, and more sharply:
+ * asking every rule for every node interns ids the compilation never needed.
+ * An audit run's emitted C++ must never be compared with anything.
+ */
+export const structuralFormAuditEnabled = () => Boolean(process.env['GEA_STRUCTURAL_FORM_AUDIT']);
+/**
+ * Prepare a rule set for dispatch.
+ *
+ * The selection is cached per syntax kind rather than recomputed per node, and
+ * that is not micro-optimisation: `typeAt` is asked for essentially every node
+ * of every source file, so filtering the whole rule list at each call would put
+ * an allocation and a linear scan on the hottest path in the normalize stage --
+ * the same shape of cost that `geatsc-normalize-stage-quadratic-scans` already
+ * cost this compiler 48 seconds once.
+ *
+ * Order within a form is the order the rules were declared in, which is the
+ * order the chain asked them, so preparing changes no answer.
+ */
+export const prepareStructuralRules = (rules) => {
+    // Decided once, when the set is prepared: an audit asks every rule for every
+    // node, so the selection below is bypassed rather than rebuilt.
+    const auditing = structuralFormAuditEnabled();
+    const formViolations = [];
+    const servingByKind = new Map();
+    const servingFor = (kind) => {
+        if (auditing)
+            return rules;
+        const known = servingByKind.get(kind);
+        if (known)
+            return known;
+        const serving = rules.filter((rule) => rule.forms === null || rule.forms.includes(kind));
+        servingByKind.set(kind, serving);
+        return serving;
+    };
+    return {
+        // `record` collects what the rules AFTER the winner would have said, so a
+        // disagreement is visible as a disagreement. It is opt-in because asking a
+        // rule the chain would have skipped mints ids nobody needed -- see
+        // `structuralDisagreementsEnabled`.
+        resolve: (node, record) => {
+            let answer = null;
+            let winner = '';
+            for (const rule of servingFor(node.kind)) {
+                const resolved = rule.resolve(node);
+                if (resolved === null)
+                    continue;
+                // Recorded whether or not this rule WON: a rule that answers outside
+                // its forms is a false claim even when an earlier rule would have
+                // shadowed it today, because the next reordering makes it the answer.
+                if (auditing && rule.forms !== null && !rule.forms.includes(node.kind)) {
+                    formViolations.push({ rule: rule.name, kind: node.kind });
+                }
+                if (answer === null) {
+                    answer = resolved;
+                    winner = rule.name;
+                    if (!record && !auditing)
+                        return answer;
+                    continue;
+                }
+                record?.({ kind: node.kind, winner, other: rule.name, agreed: resolved === answer });
+            }
+            return answer;
+        },
+        formViolations
+    };
+};

package/dist/semantics/normalize/structural-self-reference.d.ts

@@ -0,0 +1,150 @@
+import ts from 'typescript';
+import type { StructuralTypeId } from '../../identity/ids.js';
+import type { StructuralIndexShape, StructuralShape, TupleElement } from '../model/structural-types.js';
+/**
+ * Self-reference without a declared name.
+ *
+ * `structural.ts`'s anchor rule assumes every cycle in the type graph passes
+ * through a declaration -- true for an interface or a class, and false for a
+ * recursive *type alias*: `type IDBValidKey = number | string | Date |
+ * BufferSource | IDBValidKey[]` (lib.dom.d.ts) is a union one of whose arms
+ * mentions it, and a union interns by shape rather than anchoring, so the walk
+ * re-enters it forever. The failure is a stack overflow, which says nothing
+ * about the program and takes every other answer down with it.
+ *
+ * Self-reference is *detected*, not assumed: the first walk raises the signal
+ * below when it re-enters a type it is already inside, and the retry anchors
+ * first, exactly as a declared name does. So only a type proven self-referential
+ * pays for an anchor, and every ordinary union keeps interning by shape --
+ * which is what keeps two structurally identical unions one id.
+ *
+ * That covers a cycle the walk can SEE, because the same `ts.Type` object comes
+ * back. `AliasRecurrence`, at the bottom of this file, covers the cycle it
+ * cannot: a generic alias that re-instantiates to a fresh type at every level,
+ * where re-entry is a fact about layout rather than about object identity. Both
+ * end in the same place -- an anchor reserved for the outer occurrence, which
+ * the inner one resolves to -- and only the test for "have I been here before"
+ * differs.
+ */
+/** Raised when a walk re-enters the type it is already inside. Carries the type so the frame that owns it can tell its own re-entry from an inner one. */
+export declare const selfReferentialSignal: (type: ts.Type) => {
+    readonly selfReferentialType: ts.Type;
+};
+export declare const isSelfReferentialSignal: (error: unknown) => error is {
+    readonly selfReferentialType: ts.Type;
+};
+/**
+ * The identity a self-referential type anchors under.
+ *
+ * Minted per checker type object -- the same identity the walk's `inProgress`
+ * and `completed` maps are already keyed on -- rather than derived from the
+ * alias's declaration: an alias with type arguments would need its arguments'
+ * structural ids in its key, and computing those means walking back into the
+ * very type the key exists to anchor. The cost is that two checker objects for
+ * one alias would anchor twice; the checker hands back one object per alias
+ * instantiation, so in practice they do not.
+ */
+export declare const selfReferentialKeyOf: (keys: Map<ts.Type, string>, type: ts.Type) => string;
+/**
+ * The shape of a self-referential type, built once its anchor exists so the
+ * mention of itself resolves to that anchor instead of recursing.
+ *
+ * The structural kinds that can close a cycle without a declared name: a
+ * union, an intersection, a tuple, an array, a callable, and a bare
+ * index-signature object. A declared name has its own anchor path and never
+ * reaches here.
+ */
+export declare const selfReferentialShapeOf: (checker: ts.TypeChecker, type: ts.Type, typeOf: (type: ts.Type) => StructuralTypeId, tupleElementsOf: (reference: ts.TupleTypeReference) => readonly TupleElement[], indexesOf: (type: ts.Type) => readonly StructuralIndexShape[], callableShapeOf?: (type: ts.Type) => StructuralShape | null) => StructuralShape | null;
+/**
+ * Where a recursive type alias closes back on itself.
+ *
+ * A recursive conditional or mapped type alias instantiates into a FRESH
+ * `ts.Type` at every level, so `structural.ts`'s cycle guards -- all keyed by
+ * `ts.Type` object identity -- can never see one twice, and the walk does not
+ * terminate on its own.
+ *
+ * mongodb's `Filter` is the concrete case, and it is worth reading in full
+ * because it is the shape of the whole problem:
+ *
+ * ```ts
+ * type Filter<T> = { [P in keyof WithId<T>]?: Condition<WithId<T>[P]> } & RootFilterOperators<WithId<T>>
+ * interface RootFilterOperators<T> extends Document { $and?: Filter<T>[]; $nor?: Filter<T>[]; $or?: Filter<T>[] }
+ * ```
+ *
+ * `Filter<T>` does not refer to `Filter<T>`. It refers to `Filter<WithId<T>>`,
+ * whose `$and` refers to `Filter<WithId<WithId<T>>>`, forever. TypeScript mints
+ * a new type for each -- measured on the mongodb driver: type#34381, #34389,
+ * #34397, ... one per level, each argument a fresh `WithId` instantiation.
+ *
+ * Every one of those types has the same layout. The unfolding is infinite as a
+ * TREE and finite as a GRAPH: one node whose `$and` field points back at that
+ * same node. That is an ordinary recursive record, and the compiler already
+ * carries one -- `native-record-ref`, a name plus a forward declaration, which
+ * is what `representation/derive.ts` hands any record that re-enters itself.
+ *
+ * So the question this module answers is NOT "how deep may an alias go". It is
+ * "has this instantiation already appeared", and the answer closes the loop.
+ *
+ * ⛔ This used to be a depth counter that refused at 16 levels. A counter
+ * cannot distinguish the two cases that matter:
+ *
+ *   - REGULAR recursion (`Filter`): every level has the same layout, the graph
+ *     is finite, and the right answer is to fold -- which is what `within`
+ *     does now, typically at level 2.
+ *   - IRREGULAR recursion (`type Nest<T> = { value: T; next: Nest<[T]> }`):
+ *     `value` is `T`, then `[T]`, then `[[T]]`; no two levels share a layout,
+ *     no finite carrier exists, and the right answer is to refuse.
+ *
+ * A counter answers neither. It stops at an arbitrary number in both cases and
+ * reports "I stopped looking" as though it were a verdict -- and the number is
+ * wrong in both directions at once, because the work between levels multiplies:
+ * `Filter`'s three recursive fields made the SELECTED CARRIER for level 1
+ * contain 3^15 copies of level 16, and `representationKey` overflowed V8's
+ * 512 MB string limit (a `RangeError` out of `Array.join`) long before the
+ * refusal at 16 could be reported. Raising the limit explodes; lowering it
+ * refuses programs with a perfectly good finite layout.
+ *
+ * An alias re-entered through a non-equivalent instantiation has no stable
+ * declaration/type identity to anchor. It is refused at that FIRST mismatched
+ * back edge, rather than being unfolded some arbitrary number of times and
+ * then cut. A finite native fixpoint has to close at an equivalent ancestor;
+ * a different instantiation is a different C++ type equation.
+ */
+export interface AliasRecurrence<T> {
+    /**
+     * Walks `type`, folding to an equivalent ancestor instantiation of the same
+     * alias when there is one.
+     *
+     * `fold` is given that ancestor, and is expected to resolve it to whatever
+     * anchor the ancestor's own in-flight walk is building -- the caller owns
+     * that, because reserving an anchor for a walk still on the stack is
+     * `structural.ts`'s self-reference machinery, not this module's.
+     *
+     * `fold` is also the identity of the VIEW doing the walking: one closure per
+     * specialization view, stable for that view's life. The stack is shared
+     * across views (see `createAliasRecurrence`), so an ancestor may have been
+     * pushed by another view, whose `inProgress`/`walking` maps are the only
+     * ones that know its anchor. The fold therefore goes through the ancestor's
+     * OWN entry's resolver, never the caller's -- asking the caller's view about
+     * a type it never walked answered "already unwound" for every cross-view
+     * back edge, which is how tsc's `sameMap`/`find` copies over a recursive
+     * alias published unresolved bindings (31 rows on the self-compile).
+     */
+    readonly within: (type: ts.Type, walk: () => T, fold: (ancestor: ts.Type) => T, refuse: (reason: string) => T) => T;
+}
+export declare const createAliasRecurrence: <T>(checker: ts.TypeChecker) => AliasRecurrence<T>;
+/**
+ * The anchor key of a self-referential type whose shape cannot depend on
+ * the view it is walked in -- it mentions no type parameter a function or
+ * class declaration binds -- so every specialization view closes the cycle
+ * at ONE anchor. `null` for a type a view could shape differently, which
+ * keeps its per-view key. One instance serves every view of a mapper: the
+ * ordinal names the checker's type object compilation-wide, where the
+ * per-view `selfReferentialKeyOf` ordinal would collide across views.
+ *
+ * Why it exists: `type State = <S, R>(m: Machine<S, R>, stack: State[], ...)
+ * => number` entered from `stateStack: State[]` in three generic functions
+ * minted one `State[]` per copy -- five ids for one array -- and a callable
+ * read out of one copy's cell could not enter another's slot.
+ */
+export declare const createViewIndependentRecurrence: (checker: ts.TypeChecker) => ((type: ts.Type) => string | null);