@geastack/compiler 1.0.15

package/dist/semantics/normalize/host-mutation-keys.d.ts

@@ -0,0 +1,114 @@
+import type { DeclarationId } from '../../identity/ids.js';
+/**
+ * The property keys a whole-program write may have created, replaced or
+ * deleted, and the per-key obligations that ask about them.
+ *
+ * The host-mutation census used to answer one question per object -- "was it
+ * touched at all" -- plus one wildcard, `*`, for any write it could not pin to
+ * an object. A single `o.needsUpdate = true` through a receiver it could not
+ * prove non-global therefore failed every proof about every intrinsic
+ * prototype, including "Object.prototype lacks `glslVersion`". The write's KEY
+ * was always known; only its receiver was not. This module keeps the key.
+ *
+ * Soundness is carried by three rules, and nothing here may weaken them:
+ *
+ * 1. A key is recorded exactly only when it is statically known. A key the
+ *    census cannot name is `every`, which is the old wildcard.
+ * 2. A number-typed key is not an array index: `o[n]` with `n: number` can
+ *    write "-1", "1.5", "NaN" or "Infinity". It is recorded as the NUMERIC
+ *    domain -- every `ToString(Number)` string -- and an obligation on a key
+ *    is touched by it exactly when that key is such a string.
+ * 3. An object's taint never masks the surface taint: a query asks both the
+ *    object's own keys and the keys written on "any surface that might be an
+ *    intrinsic or the global object".
+ *
+ * Symbol-keyed obligations are named `@@name` (`@@iterator`), after the
+ * WELL-KNOWN symbols. No write ever records a symbol key by name, so such an
+ * obligation is touched only by `every`.
+ *
+ * A symbol key the program itself declared is the one case that records NO key
+ * rather than `every`: it can name no string member, and it can name no
+ * `@@well-known` member either, so it touches nothing this module models. That
+ * is not a fourth kind -- it is the empty key set, decided in
+ * `host-mutation-key-reader.ts`'s `isProgramDeclaredSymbolKey`, which is also
+ * where the soundness argument lives.
+ */
+/** @semanticCategory generic-primitive */
+export type MutationKey = {
+    readonly kind: 'name';
+    readonly name: string;
+} | {
+    readonly kind: 'numeric';
+} | {
+    readonly kind: 'every';
+};
+export declare const everyKey: MutationKey;
+export declare const numericKeys: MutationKey;
+export declare const namedKey: (name: string) => MutationKey;
+/** @semanticCategory generic-primitive */
+export interface MutationKeySet {
+    readonly names: ReadonlySet<string>;
+    /** Some `ToString(Number)` key: canonical numeric strings, "NaN" and "Infinity" included. */
+    readonly numeric: boolean;
+    /** A key nobody can name: every key, prototype replacement included. */
+    readonly every: boolean;
+}
+/** Exactly the strings `ToPropertyKey` produces from some Number. "-0" is not one: `String(-0)` is "0". */
+export declare const isCanonicalNumericKey: (key: string) => boolean;
+/** 7.1.21 CanonicalNumericIndexString restricted to array indices: "0" .. "4294967294", no other spelling. */
+export declare const isArrayIndexKey: (key: string) => boolean;
+/** The key a numeric LITERAL writes: `o[1.50]` writes "1.5", `o[0x10]` writes "16". */
+export declare const numericLiteralKey: (text: string) => string | null;
+/**
+ * What a proof depends on. `names` are exact keys (methods it calls, keys it
+ * proves absent); `arrayIndices` asks for every canonical array index at once
+ * (a hole read consults the prototype chain for that index).
+ * @semanticCategory generic-primitive
+ */
+export interface PrototypeKeyQuery {
+    readonly names?: readonly string[];
+    readonly arrayIndices?: boolean;
+    /** Every ToString(Number) key, including fractions, infinities and NaN. */
+    readonly numeric?: boolean;
+}
+/** A stable spelling of a query, for ledgers that deduplicate obligations. */
+export declare const prototypeKeyQuerySignature: (query: PrototypeKeyQuery) => string;
+/** Does a write set reach any key the query depends on? `'all'` is the whole-object query. */
+export declare const keySetTouches: (keys: MutationKeySet | undefined, query: PrototypeKeyQuery | "all") => boolean;
+/**
+ * The sealed census. As a set it is the legacy view, kept so every consumer
+ * that asks about a declaration identity keeps working unchanged:
+ *
+ * - `'*'` is present exactly when some surface may have been written under
+ *   an unknown key (`surfaceKeys.every`);
+ * - a declaration is present when anything at all was recorded against it --
+ *   a host binding replaced, a member overwritten, a key added to an
+ *   intrinsic prototype.
+ *
+ * Keys written through a receiver that might be ANY intrinsic surface are
+ * NOT in the legacy view (they would be `'*'` there), which is why every
+ * consumer that asks about an intrinsic object's contents must ask per key:
+ * `intrinsicObjectKeysIntact`, or `intactIntrinsicPrototypeType` for the
+ * whole-object question.
+ * @semanticCategory generic-primitive
+ */
+export interface GlobalHostMutationTaint extends ReadonlySet<DeclarationId | '*'> {
+    /** Keys written on some receiver that may be the global object or any intrinsic object. */
+    readonly surfaceKeys: MutationKeySet;
+    /** Keys written on this specific object identity; `undefined` when nothing was. */
+    readonly keysOf: (object: DeclarationId) => MutationKeySet | undefined;
+}
+/** May a proof that depends on `query` of this intrinsic object still stand? */
+export declare const intrinsicObjectKeysIntact: (taint: GlobalHostMutationTaint, object: DeclarationId, query: PrototypeKeyQuery | "all") => boolean;
+/** The census's builder and its sealed result. Every record goes through `taintObject`/`taintSurface`. */
+export declare class HostMutationTaint extends Set<DeclarationId | '*'> implements GlobalHostMutationTaint {
+    #private;
+    get surfaceKeys(): MutationKeySet;
+    readonly keysOf: (object: DeclarationId) => MutationKeySet | undefined;
+    /** A legacy add carries no key, so it is the whole object (or, for `'*'`, every surface key). */
+    add(entry: DeclarationId | '*'): this;
+    taintObject(object: DeclarationId, key: MutationKey): void;
+    taintSurface(key: MutationKey): void;
+    /** Copy a sealed census into this (shared, pre-allocated) one without losing a key. */
+    absorb(other: GlobalHostMutationTaint): void;
+}

package/dist/semantics/normalize/host-mutation-keys.js

@@ -0,0 +1,183 @@
+export const everyKey = { kind: 'every' };
+export const numericKeys = { kind: 'numeric' };
+export const namedKey = (name) => ({ kind: 'name', name });
+/** Exactly the strings `ToPropertyKey` produces from some Number. "-0" is not one: `String(-0)` is "0". */
+export const isCanonicalNumericKey = (key) => String(Number(key)) === key;
+/** 7.1.21 CanonicalNumericIndexString restricted to array indices: "0" .. "4294967294", no other spelling. */
+export const isArrayIndexKey = (key) => {
+    if (!isCanonicalNumericKey(key))
+        return false;
+    const value = Number(key);
+    return Number.isInteger(value) && value >= 0 && value < 4294967295;
+};
+/** The key a numeric LITERAL writes: `o[1.50]` writes "1.5", `o[0x10]` writes "16". */
+export const numericLiteralKey = (text) => {
+    const value = Number(text.replace(/_/g, ''));
+    return Number.isNaN(value) ? null : String(value);
+};
+/** A stable spelling of a query, for ledgers that deduplicate obligations. */
+export const prototypeKeyQuerySignature = (query) => `${[...new Set(query.names ?? [])].sort().join(',')}${query.arrayIndices ? '|indices' : ''}${query.numeric ? '|numeric' : ''}`;
+/** Does a write set reach any key the query depends on? `'all'` is the whole-object query. */
+export const keySetTouches = (keys, query) => {
+    if (!keys)
+        return false;
+    if (keys.every)
+        return true;
+    if (query === 'all')
+        return keys.numeric || keys.names.size > 0;
+    for (const name of query.names ?? []) {
+        if (keys.names.has(name) || (keys.numeric && isCanonicalNumericKey(name)))
+            return true;
+    }
+    if (query.arrayIndices && (keys.numeric || [...keys.names].some(isArrayIndexKey)))
+        return true;
+    if (query.numeric && (keys.numeric || [...keys.names].some(isCanonicalNumericKey)))
+        return true;
+    return false;
+};
+/**
+ * TEMPORARY INSTRUMENT -- not for landing. `GEA_KEY_BLOCK_DEBUG=1` names, per
+ * distinct outcome, WHICH of the three disjuncts refused and which key matched.
+ * Suppressing the wildcard alone left the three.js app's 300 census diagnostics at 300,
+ * so the question this answers is whether the NAMED surface keys (three's own
+ * `linecap`, `version`, `isTexture` ... written through opaque receivers) are
+ * doing the blocking on their own.
+ */
+const keyBlockDebug = process.env['GEA_KEY_BLOCK_DEBUG'] === '1';
+const reportedKeyBlocks = new Set();
+const matchedKeys = (keys, query) => !keys
+    ? ''
+    : keys.every
+        ? 'every'
+        : query === 'all'
+            ? [...keys.names].join(',')
+            : [...(query.names ?? [])].filter((name) => keys.names.has(name)).join(',');
+/** May a proof that depends on `query` of this intrinsic object still stand? */
+export const intrinsicObjectKeysIntact = (taint, object, query) => {
+    const star = taint.has('*');
+    const surface = keySetTouches(taint.surfaceKeys, query);
+    const own = keySetTouches(taint.keysOf(object), query);
+    if (keyBlockDebug && (star || surface || own)) {
+        const asked = query === 'all' ? 'all' : prototypeKeyQuerySignature(query);
+        // The OBJECT belongs in the line. Without it every blocked query on every
+        // intrinsic collapsed into one row -- `own=true(every) asked=keys` says
+        // that SOME object is wildcarded, not which, and the whole next question
+        // (which arguments reach the objects a program's own obligations name) is
+        // unreadable from it. It is also what makes the dedupe per object rather
+        // than per outcome.
+        const line = `[KEY-BLOCK] ${object} star=${star} surface=${surface}(${matchedKeys(taint.surfaceKeys, query)}) own=${own}(${matchedKeys(taint.keysOf(object), query)}) asked=${asked}`;
+        if (!reportedKeyBlocks.has(line)) {
+            reportedKeyBlocks.add(line);
+            process.stderr.write(`${line}\n`);
+        }
+    }
+    return !star && !surface && !own;
+};
+const emptyKeys = () => ({ names: new Set(), numeric: false, every: false });
+/**
+ * TEMPORARY EXPERIMENT -- not for landing. `GEA_NO_WILDCARD=1` drops every
+ * `every`-kind key, at the ONE place all of them are recorded, so a single
+ * three.js run answers the question that decides what to work on next: with the
+ * wildcard gone, do the 300 census diagnostics clear, or do the 64 NAMED
+ * surface keys block them anyway? Guarding `markWildcard` alone was not enough
+ * -- `taintIntrinsicMember` and `markIntrinsicPrototypeKeys` reach these two
+ * methods with `everyKey` without passing through it.
+ */
+const dropsWildcardKeys = process.env['GEA_NO_WILDCARD'] === '1';
+const wildcardStackDebug = process.env['GEA_WILDCARD_STACK'] === '1';
+const reportedWildcardStacks = new Set();
+/** The census's builder and its sealed result. Every record goes through `taintObject`/`taintSurface`. */
+export class HostMutationTaint extends Set {
+    #surface = emptyKeys();
+    #objects = new Map();
+    get surfaceKeys() {
+        return this.#surface;
+    }
+    keysOf = (object) => this.#objects.get(object);
+    /** A legacy add carries no key, so it is the whole object (or, for `'*'`, every surface key). */
+    add(entry) {
+        if (entry === '*')
+            this.taintSurface(everyKey);
+        else
+            this.taintObject(entry, everyKey);
+        return this;
+    }
+    taintObject(object, key) {
+        if (key.kind === 'every' && dropsWildcardKeys)
+            return;
+        // TEMPORARY INSTRUMENT -- not for landing. `GEA_WILDCARD_STACK=1` names the
+        // RULE that stamps `every` on an object, by capturing the compiler-side call
+        // path once per distinct path. Reading the census for it does not work: the
+        // `add` override below routes several unrelated rules through this one
+        // method, so the site is only visible from the stack.
+        if (key.kind === 'every' && wildcardStackDebug) {
+            const stack = (new Error().stack ?? '')
+                .split('\n')
+                .slice(2, 9)
+                .map((line) => line
+                .trim()
+                .replace(/^at /, '')
+                .replace(/ \(.*$/, ''))
+                .join(' <- ');
+            // Deduped by OBJECT AND stack, not by stack alone. One rule wildcards
+            // many objects through one code path, so a stack-only memo printed the
+            // first object it reached and swallowed every other -- which reads as
+            // "one intrinsic is wildcarded" when the truth is "this loop wildcards
+            // all of them". That is the shape of the answer, and it was invisible:
+            // located hono-hello's whole remaining census gap at ONE site only after
+            // cross-checking the printed frames against the source by hand.
+            const seen = `${object} :: ${stack}`;
+            if (!reportedWildcardStacks.has(seen)) {
+                reportedWildcardStacks.add(seen);
+                process.stderr.write(`[WILDCARD-STACK] ${object} :: ${stack}\n`);
+            }
+        }
+        let keys = this.#objects.get(object);
+        if (!keys)
+            this.#objects.set(object, (keys = emptyKeys()));
+        record(keys, key);
+        super.add(object);
+    }
+    taintSurface(key) {
+        if (key.kind === 'every' && dropsWildcardKeys)
+            return;
+        record(this.#surface, key);
+        if (this.#surface.every)
+            super.add('*');
+    }
+    /** Copy a sealed census into this (shared, pre-allocated) one without losing a key. */
+    absorb(other) {
+        const surface = other.surfaceKeys;
+        for (const name of surface.names)
+            this.taintSurface(namedKey(name));
+        if (surface.numeric)
+            this.taintSurface(numericKeys);
+        if (surface.every)
+            this.taintSurface(everyKey);
+        for (const entry of other) {
+            if (entry === '*') {
+                this.taintSurface(everyKey);
+                continue;
+            }
+            const keys = other.keysOf(entry);
+            if (!keys) {
+                this.taintObject(entry, everyKey);
+                continue;
+            }
+            for (const name of keys.names)
+                this.taintObject(entry, namedKey(name));
+            if (keys.numeric)
+                this.taintObject(entry, numericKeys);
+            if (keys.every || (keys.names.size === 0 && !keys.numeric))
+                this.taintObject(entry, everyKey);
+        }
+    }
+}
+const record = (keys, key) => {
+    if (key.kind === 'every')
+        keys.every = true;
+    else if (key.kind === 'numeric')
+        keys.numeric = true;
+    else
+        keys.names.add(key.name);
+};

package/dist/semantics/normalize/identities.d.ts

@@ -0,0 +1,172 @@
+import ts from 'typescript';
+import { type DeclarationId, type FunctionId, type NodeId } from '../../identity/ids.js';
+import { type SpecializationCensus } from './specialization.js';
+/**
+ * Minting identities from checker facts.
+ *
+ * Identity here is *structural position*, never a byte offset and never a file
+ * path. A file is identified by its index in the program's sorted root list, and
+ * a node by the ordinal it receives in a deterministic pre-order walk of that
+ * file. Both are stable under reformatting, renaming a local, and moving a file
+ * on disk -- which is exactly the property an offset does not have.
+ *
+ * Relative order is retained because JavaScript semantics depend on it:
+ * declaration order, evaluation order, and hoisting are real behavior. What is
+ * excluded is using a *particular* position as evidence that a particular
+ * program is being compiled.
+ */
+/**
+ * One link in the chain of monomorphized copies a node is being compiled
+ * inside: which generic was instantiated, and which of its instantiations this
+ * is.
+ *
+ * The owner travels with the ordinal because resolving a type parameter needs
+ * both. An ordinal alone says "the first instantiation" without saying of what,
+ * and a node inside two nested generics has two ordinals that mean nothing until
+ * each is paired with the generic it indexes.
+ */
+export interface SpecializationStep {
+    readonly owner: ts.Declaration;
+    readonly ordinal: number;
+}
+/**
+ * Which monomorphized copy an identity belongs to, outermost first.
+ *
+ * The empty path is a body that is not inside any generic, which is every body
+ * in a program that declares none -- and its identities stay byte-identical to
+ * what they were before monomorphization, because an empty path adds no suffix.
+ */
+export type SpecializationPath = readonly SpecializationStep[];
+export declare const rootSpecialization: SpecializationPath;
+/**
+ * The identity suffix for a path: the ordinals alone.
+ *
+ * The owner is deliberately left out. A node's own identity already pins where
+ * it is, so which generics enclose it is not in question -- only which copy is,
+ * and that is what the ordinals say. Putting the owner in as well would make the
+ * suffix longer without making any two copies more distinguishable.
+ */
+export declare const specializationKey: (path: SpecializationPath) => string;
+export interface IdentityTable {
+    /**
+     * The same table, minting identities for one monomorphized copy.
+     *
+     * A view rather than an argument on every method, for the same reason the
+     * structural mapper has one: producers ask these questions from a hundred
+     * places, and threading the copy through all of them would express, a hundred
+     * times, one fact that belongs to the candidate being compiled.
+     *
+     * The view does NOT stamp the path onto every identity it mints. A body
+     * inside a copy routinely names things outside it -- a module-scope constant,
+     * an imported class -- and stamping those would mint a second identity for
+     * one declaration, which is exactly the two-identities-for-one-thing defect
+     * identities exist to prevent. What it stamps is the longest prefix of the
+     * path whose generics actually contain the node, which is empty for anything
+     * declared outside them.
+     */
+    readonly forSpecialization: (path: SpecializationPath) => IdentityTable;
+    /**
+     * What distinguishes one monomorphized copy from another *as a copy*, owner
+     * included.
+     *
+     * Deliberately not `specializationKey`, and the difference is load-bearing.
+     * That one is an identity *suffix*, where the owner is redundant because a
+     * node's own identity already says which generic encloses it. Here the owner
+     * is the entire question: two unrelated generics each instantiated once both
+     * have ordinal path `0`, so anything caching per copy under that key hands
+     * the second generic the first one's answers -- including `prefixFor`'s
+     * answer to "is this node inside a copy", which is `false` for every node of
+     * the generic the cached view was not built for. Every identity minted
+     * through such a view comes out unspecialized, so a body and the allocation
+     * that gives it a calling convention end up naming different copies.
+     */
+    readonly copyKeyOf: (path: SpecializationPath) => string;
+    /**
+     * How much of a copy's path applies to one node: the longest prefix whose
+     * generics lexically contain it, empty for anything declared outside them.
+     *
+     * Exposed because composing a path is not something a caller may invent. A
+     * use site inside one copy that names a generic declared *elsewhere* reaches
+     * a copy of that other generic, and appending its step to this walk's whole
+     * path would mint `decl|X@0.0` -- an id no census walk ever publishes, since
+     * the census walks that generic from the scope it was declared in. The
+     * composed path is this prefix plus the site's own step, and this is the one
+     * function that says what the prefix is.
+     */
+    readonly prefixFor: (node: ts.Node, path: SpecializationPath) => SpecializationPath;
+    /**
+     * The identity segment every declaration in one file is minted under.
+     *
+     * Exposed so the frontend can publish which file each identity's segment
+     * names (`FrontendResult.sourceFileNames`) without any later stage learning
+     * the rule this table uses to spell it.
+     */
+    readonly fileIdentityOf: (file: ts.SourceFile) => string;
+    /**
+     * Every file the program holds, identity segment to file name. This is the
+     * whole program -- library and ambient files included -- because a unit can
+     * be owned by any file an identity was minted under, not only the compiled
+     * sources. Display evidence for naming emitted units; nothing decides on it.
+     */
+    readonly sourceFileNames: ReadonlyMap<string, string>;
+    readonly nodeIdOf: (node: ts.Node, path?: SpecializationPath) => NodeId;
+    readonly declarationIdOf: (declaration: ts.Declaration, path?: SpecializationPath) => DeclarationId;
+    readonly functionIdOf: (declaration: ts.Declaration, path?: SpecializationPath) => FunctionId;
+    /**
+     * The declaration a symbol is *anchored* on: the one the structural walk
+     * interns a shape under, and the one a nominal type is identified by.
+     *
+     * This is not always the declaration that supplies a value -- see
+     * `valueDeclarationOfSymbol`, which answers the other question. Keeping them
+     * apart is load-bearing rather than tidy: a merged ambient global is one
+     * symbol with a type-space declaration and a value-space one, and the two
+     * questions genuinely have different answers for it.
+     */
+    readonly declarationOfSymbol: (symbol: ts.Symbol) => ts.Declaration | null;
+    /**
+     * The declaration that supplies a symbol's *value*, or `null` when it has
+     * none.
+     *
+     * A merged ambient global -- `interface Error {}` for the type plus
+     * `declare var Error: ErrorConstructor` for the value -- is one symbol with
+     * two declarations, and only the second one holds anything. Asking the
+     * anchor question instead returns the interface whenever it sorts first
+     * (true for `Error`, `Math`, `Date`, `JSON` and every other merged global in
+     * lib.es5.d.ts), which mints a binding read against a declaration nothing
+     * ever introduces -- the emitter then refuses the read by name, after
+     * preflight has already certified the program.
+     *
+     * `frontend.ts`'s `bindAmbientValue` resolves the host placement this exact
+     * way, so a read minted here and the placement it must find are keyed by one
+     * rule rather than two.
+     */
+    readonly valueDeclarationOfSymbol: (symbol: ts.Symbol) => ts.Declaration | null;
+    /**
+     * The declaration whose type parameters a node's value writes down -- the
+     * node monomorphized copies are keyed on.
+     *
+     * `specialization.ts` owns the rule; this is where the checker gets bound
+     * into it, because one of its cases -- `const jsxs = jsx`, a generic named as
+     * a value -- needs a name resolved to what it denotes. Every consumer has to
+     * ask through here, or the census forks one node and the reads name another.
+     */
+    readonly genericSubjectOf: (declaration: ts.Declaration) => ts.Declaration;
+    /**
+     * Identity of the symbol a name resolves to, following aliases to their
+     * target.
+     *
+     * `at` is the node doing the naming, and it matters for exactly one reason:
+     * a name that reaches a generic reaches one of its monomorphized copies, and
+     * which one is decided by the instantiation the *use site* makes, not by
+     * anything about the declaration. `identity(1)` and `identity('one')` name
+     * two different functions through one symbol.
+     */
+    readonly symbolDeclarationId: (symbol: ts.Symbol, at?: ts.Node) => DeclarationId | null;
+    /**
+     * Identity of the declaration a name's *value* comes from -- the same
+     * question `symbolDeclarationId` asks, resolved through
+     * `valueDeclarationOfSymbol` instead of the anchor.
+     */
+    readonly symbolValueDeclarationId: (symbol: ts.Symbol, at?: ts.Node) => DeclarationId | null;
+}
+export declare const createIdentityTable: (program: ts.Program, checker: ts.TypeChecker, specializations?: SpecializationCensus) => IdentityTable;