@geastack/compiler 1.0.15

package/dist/ir/verify.js

@@ -0,0 +1,355 @@
+import { dynamicReasons, representationKey, walkRepresentation } from '../representation/model.js';
+import { atBlockExit, buildControlFlowGraph, buildDominatorTree, collectDefinitionSites, isVisible } from './dominance.js';
+import { allOperationsOf, terminatorKinds } from './model.js';
+import { operandsOfIrOperation, resultOfIrOperation } from './queries.js';
+import { nativeEqualityOf } from './native-equality.js';
+const violation = (guard, value, block, message) => ({
+    guard,
+    value,
+    block,
+    message
+});
+/**
+ * `IrBlock.terminator` is a required field, so "missing" and "not last" are
+ * unrepresentable through the ordinary builder path. Both checks stay here
+ * anyway: nothing stops an unsafe cast from handing `verify` a body that was
+ * never built through `createIrBodyBuilder`.
+ */
+const terminatorGuard = (body) => {
+    const violations = [];
+    const known = new Set(terminatorKinds);
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        if (!block.terminator || !known.has(block.terminator.kind)) {
+            violations.push(violation('block-missing-terminator', null, blockId, `block ${blockId} has no valid terminator`));
+        }
+        block.operations.forEach((operation, index) => {
+            // `operations` is typed to exclude terminator kinds, so this can only fire against a body that
+            // reached here through an unsafe cast rather than `createIrBodyBuilder` -- exactly the case this
+            // defensive check exists for.
+            if (known.has(operation.kind)) {
+                violations.push(violation('terminator-not-last', null, blockId, `block ${blockId} holds a ${operation.kind} operation at position ${index}, ahead of the block's actual terminator`));
+            }
+        });
+    }
+    return violations;
+};
+/** Every block a terminator or a phi names must actually exist in this body. */
+const jumpTargetGuard = (body) => {
+    const violations = [];
+    const requireKnown = (target, from, describe) => {
+        if (!body.blocks.has(target))
+            violations.push(violation('jump-to-unknown-block', null, from, `${describe} names unknown block ${target}`));
+    };
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        const terminator = block.terminator;
+        switch (terminator.kind) {
+            case 'branch':
+                requireKnown(terminator.whenTrue, blockId, `branch in block ${blockId} (when-true)`);
+                requireKnown(terminator.whenFalse, blockId, `branch in block ${blockId} (when-false)`);
+                break;
+            case 'jump':
+                requireKnown(terminator.target, blockId, `jump in block ${blockId}`);
+                break;
+            case 'switch':
+                terminator.cases.forEach((switchCase, index) => requireKnown(switchCase.target, blockId, `switch in block ${blockId} (case ${index})`));
+                requireKnown(terminator.defaultTarget, blockId, `switch in block ${blockId} (default)`);
+                break;
+            case 'return':
+            case 'throw':
+                break;
+        }
+        for (const operation of block.operations) {
+            if (operation.kind !== 'phi')
+                continue;
+            for (const edge of operation.incoming)
+                requireKnown(edge.block, blockId, `phi ${operation.result.id} in block ${blockId}`);
+        }
+    }
+    return violations;
+};
+/** No SSA value may be defined at more than one site in one body. */
+const definitionUniquenessGuard = (body) => {
+    const violations = [];
+    for (const [id, occurrences] of collectDefinitionSites(body)) {
+        if (occurrences.length <= 1)
+            continue;
+        violations.push(violation('value-defined-twice', id, null, `value ${id} is defined ${occurrences.length} times, at ${occurrences.map((o) => `${o.block}#${o.position}`).join(', ')}`));
+    }
+    return violations;
+};
+/**
+ * Every value-producing operation must cite the semantic result it lowers; an
+ * empty lineage there is a producer defect, not an unresolved fact. A
+ * terminator may carry none, and only because a body that ends implicitly has
+ * no semantic operation for its end to point at.
+ */
+const lineageGuard = (body) => {
+    const violations = [];
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        block.operations.forEach((operation, index) => {
+            if (operation.lineage)
+                return;
+            violations.push(violation('operation-missing-lineage', resultOfIrOperation(operation)?.id ?? null, blockId, `operation ${operation.kind} at ${blockId}#${index} carries no semantic-result lineage`));
+        });
+    }
+    return violations;
+};
+/**
+ * `values` is a derived index over the authoritative per-operation results,
+ * kept for O(1) lookup exactly like `SemanticGraph.results` is kept over
+ * `operations`. This is the same cross-check `graph.ts` runs: the index must
+ * agree with its source and must not contain an entry the source never
+ * produced.
+ */
+const valuesIndexGuard = (body) => {
+    const violations = [];
+    const declared = new Set();
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        for (const operation of allOperationsOf(block)) {
+            const result = resultOfIrOperation(operation);
+            if (!result)
+                continue;
+            declared.add(result.id);
+            const indexed = body.values.get(result.id);
+            if (indexed === undefined) {
+                violations.push(violation('value-missing-from-index', result.id, blockId, `value ${result.id} is defined but absent from the body's value index`));
+            }
+            else if (representationKey(indexed) !== representationKey(result.representation)) {
+                violations.push(violation('value-index-disagrees-with-definition', result.id, blockId, `value ${result.id} is indexed as ${representationKey(indexed)} but its defining operation selected ${representationKey(result.representation)}`));
+            }
+        }
+    }
+    for (const id of body.values.keys()) {
+        if (!declared.has(id))
+            violations.push(violation('value-index-orphan', id, null, `value ${id} appears in the body's value index but no operation defines it`));
+    }
+    return violations;
+};
+/**
+ * An operand's declared carrier must equal its definition's. A phi's incoming
+ * values must additionally equal the phi's own result: a phi is one value
+ * merged from several paths, so an incoming arm with a different carrier
+ * would make the merge itself observationally meaningless.
+ */
+const representationConsistencyGuard = (body) => {
+    const violations = [];
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        for (const operation of allOperationsOf(block)) {
+            for (const operand of operandsOfIrOperation(operation)) {
+                const defined = body.values.get(operand.value);
+                if (defined === undefined)
+                    continue; // reported by the definition-visibility guard instead
+                if (representationKey(defined) === representationKey(operand.representation))
+                    continue;
+                violations.push(violation('operand-representation-disagrees-with-definition', operand.value, blockId, `operand referencing ${operand.value} in a ${operation.kind} operation expects ${representationKey(operand.representation)} but its definition selected ${representationKey(defined)}`));
+            }
+            if (operation.kind !== 'phi')
+                continue;
+            for (const edge of operation.incoming) {
+                if (representationKey(edge.value.representation) === representationKey(operation.result.representation))
+                    continue;
+                violations.push(violation('phi-incoming-representation-disagrees-with-result', operation.result.id, blockId, `phi ${operation.result.id} selected ${representationKey(operation.result.representation)} but its incoming value from ${edge.block} carries ${representationKey(edge.value.representation)}`));
+            }
+        }
+    }
+    return violations;
+};
+/** A phi's incoming edges must name exactly the block's predecessors -- no fewer, no more, no duplicates. */
+const phiPredecessorGuard = (body, graph) => {
+    const violations = [];
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        const predecessors = new Set(graph.predecessors.get(blockId) ?? []);
+        for (const operation of block.operations) {
+            if (operation.kind !== 'phi')
+                continue;
+            const incomingBlocks = operation.incoming.map((edge) => edge.block);
+            const incomingSet = new Set(incomingBlocks);
+            if (incomingSet.size !== incomingBlocks.length) {
+                violations.push(violation('phi-duplicate-predecessor', operation.result.id, blockId, `phi ${operation.result.id} in block ${blockId} names the same predecessor more than once`));
+            }
+            const missing = [...predecessors].filter((p) => !incomingSet.has(p));
+            const extra = [...incomingSet].filter((p) => !predecessors.has(p));
+            if (missing.length === 0 && extra.length === 0)
+                continue;
+            violations.push(violation('phi-incoming-mismatches-predecessors', operation.result.id, blockId, `phi ${operation.result.id} in block ${blockId} has predecessors {${[...predecessors].join(', ')}} but incoming edges {${[...incomingSet].join(', ')}}` +
+                `${missing.length ? `; missing ${missing.join(', ')}` : ''}${extra.length ? `; unexpected ${extra.join(', ')}` : ''}`));
+        }
+    }
+    return violations;
+};
+/**
+ * A use is legal only when its definition dominates it: earlier in the same
+ * block, or in a block that dominates the using block. A phi's incoming value
+ * is checked against its predecessor's exit rather than the phi's own block,
+ * because that is the point in the program where the value must exist.
+ */
+const usedBeforeDefinedGuard = (body, graph) => {
+    const violations = [];
+    const sites = collectDefinitionSites(body);
+    const firstSiteOf = (id) => sites.get(id)?.[0] ?? null;
+    let dominance;
+    try {
+        dominance = buildDominatorTree(body, graph);
+    }
+    catch (error) {
+        return [
+            violation('dominance-computation-failed', null, null, `dominance computation over body ${body.owner} failed: ${error.message}`)
+        ];
+    }
+    const checkOperand = (id, useBlock, usePosition, describe) => {
+        const site = firstSiteOf(id);
+        if (!site) {
+            violations.push(violation('value-used-before-defined', id, useBlock, `${describe} reads ${id}, which is never defined in this body`));
+            return;
+        }
+        if (!isVisible(site, useBlock, usePosition, dominance)) {
+            violations.push(violation('value-used-before-defined', id, useBlock, `${describe} reads ${id}, but its definition at ${site.block}#${site.position} does not dominate this use`));
+        }
+    };
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        if (!dominance.reachable.has(blockId))
+            continue; // dead code makes no ordering claim on the entry path to verify
+        block.operations.forEach((operation, index) => {
+            if (operation.kind === 'phi') {
+                for (const edge of operation.incoming)
+                    checkOperand(edge.value.value, edge.block, atBlockExit, `phi ${operation.result.id} in block ${blockId} from predecessor ${edge.block}`);
+                return;
+            }
+            for (const operand of operandsOfIrOperation(operation))
+                checkOperand(operand.value, blockId, index, `operation ${operation.kind} at ${blockId}#${index}`);
+        });
+        const terminatorPosition = block.operations.length;
+        for (const operand of operandsOfIrOperation(block.terminator))
+            checkOperand(operand.value, blockId, terminatorPosition, `terminator ${block.terminator.kind} of block ${blockId}`);
+    }
+    return violations;
+};
+/** `unresolved` is lattice bottom and `dynamic` is legitimate only for the four declared reasons -- both must never reach a materialized IR value. */
+const representationValidityGuard = (body) => {
+    const violations = [];
+    const permitted = new Set(dynamicReasons);
+    for (const [id, representation] of body.values) {
+        for (const found of walkRepresentation(representation)) {
+            if (found.kind === 'unresolved') {
+                violations.push(violation('unresolved-reaches-materialization', id, null, `value ${id} selected a carrier containing unresolved(${found.reason})`));
+            }
+            if (found.kind === 'dynamic' && !permitted.has(found.reason)) {
+                violations.push(violation('boxed-without-declared-reason', id, null, `value ${id} selected dynamic carrier with undeclared reason "${found.reason}"`));
+            }
+        }
+    }
+    return violations;
+};
+/** A boxed Function may enter native bind only with the exact declaration identity semantics proved for it. */
+const bindCallableIdentityGuard = (body) => {
+    const violations = [];
+    for (const blockId of body.blockOrder) {
+        const block = body.blocks.get(blockId);
+        if (!block)
+            continue;
+        for (const operation of block.operations) {
+            if (operation.kind !== 'bind-callable' || operation.source.representation.kind !== 'dynamic')
+                continue;
+            if (operation.source.representation.reason !== 'opt-in-fallback') {
+                violations.push(violation('dynamic-bind-source-reason', operation.source.value, blockId, 'a dynamic bind source is not an authenticated opt-in Function object'));
+            }
+            if (operation.sourceFunctionId === null) {
+                violations.push(violation('dynamic-bind-source-identity', operation.source.value, blockId, 'a dynamic bind source carries no checker-authenticated FunctionId'));
+            }
+        }
+    }
+    return violations;
+};
+/** Iterator-close regions are executable IR boundaries, so their carrier and blocks are checked like ordinary operands and jumps. */
+const iteratorCloseRegionGuard = (body) => {
+    const violations = [];
+    const entries = new Set();
+    for (const region of body.iteratorCloseRegions ?? []) {
+        if (region.iterator.representation.kind !== 'dynamic' &&
+            region.iterator.representation.kind !== 'record' &&
+            region.iterator.representation.kind !== 'native-record-ref' &&
+            region.iterator.representation.kind !== 'iterator') {
+            violations.push(violation('iterator-close-region-carrier', region.iterator.value, region.entry, 'IteratorClose region does not carry a dynamic, concrete record, or generator iterator'));
+        }
+        if (!body.blocks.has(region.entry) || !region.blocks.includes(region.entry)) {
+            violations.push(violation('iterator-close-region-entry', region.iterator.value, region.entry, 'IteratorClose region entry is not one of its known blocks'));
+        }
+        for (const target of region.dismissTargets)
+            if (!body.blocks.has(target)) {
+                violations.push(violation('iterator-close-region-continuation', region.iterator.value, target, 'IteratorClose region names an unknown normal-completion target'));
+            }
+        for (const block of region.blocks)
+            if (!body.blocks.has(block)) {
+                violations.push(violation('iterator-close-region-block', region.iterator.value, block, 'IteratorClose region names an unknown body block'));
+            }
+        if (entries.has(region.entry))
+            violations.push(violation('iterator-close-region-entry', region.iterator.value, region.entry, 'two IteratorClose regions share one entry'));
+        entries.add(region.entry);
+        const defined = body.values.get(region.iterator.value);
+        if (!defined || representationKey(defined) !== representationKey(region.iterator.representation)) {
+            violations.push(violation('iterator-close-region-operand', region.iterator.value, region.entry, 'IteratorClose region iterator is not a defined matching SSA value'));
+        }
+    }
+    return violations;
+};
+const nativeEqualityGuard = (body) => {
+    const violations = [];
+    for (const operation of [...body.blocks.values()].flatMap((block) => allOperationsOf(block))) {
+        if (operation.kind !== 'compute' || !operation.nativeEquality)
+            continue;
+        const recipe = operation.nativeEquality;
+        const expected = nativeEqualityOf(operation.operator, operation.operands);
+        if (expected === null ||
+            (operation.form !== 'equality' && operation.form !== 'binary') ||
+            expected.dynamicOperand !== recipe.dynamicOperand ||
+            expected.primitive !== recipe.primitive ||
+            expected.negate !== recipe.negate ||
+            operation.result.representation.kind !== 'scalar' ||
+            operation.result.representation.domain !== 'boolean')
+            violations.push(violation('native-equality-recipe', operation.result.id, null, 'strict equality recipe disagrees with its operands or result'));
+    }
+    return violations;
+};
+/** Run every guard and return the complete violation set, never just the first. */
+export const verifyIrBody = (body) => {
+    const graph = buildControlFlowGraph(body);
+    return [
+        ...terminatorGuard(body),
+        ...jumpTargetGuard(body),
+        ...definitionUniquenessGuard(body),
+        ...lineageGuard(body),
+        ...valuesIndexGuard(body),
+        ...representationConsistencyGuard(body),
+        ...phiPredecessorGuard(body, graph),
+        ...usedBeforeDefinedGuard(body, graph),
+        ...representationValidityGuard(body),
+        ...bindCallableIdentityGuard(body),
+        ...iteratorCloseRegionGuard(body),
+        ...nativeEqualityGuard(body)
+    ].sort((left, right) => {
+        if (left.guard !== right.guard)
+            return left.guard.localeCompare(right.guard);
+        return String(left.value ?? left.block ?? '').localeCompare(String(right.value ?? right.block ?? ''));
+    });
+};

package/dist/plugins/apple/constructors.d.ts

@@ -0,0 +1,112 @@
+import type { HostBaseTable, HostConstructorTable, HostFunctionFileTable, HostFunctionTable, HostIncludeTable } from '../../targets/cpp/host/host-members.js';
+/**
+ * How Apple's frameworks construct their own objects.
+ *
+ * `new NSStackView()` is not a member of anything -- it is the one expression
+ * that brings the view into existence -- so it cannot be a `hostMembers` row,
+ * and a compiler with no table for it refuses every program that builds a host
+ * object while preflight happily certifies the same program.
+ *
+ * The spelling is the package's, verbatim: an ObjC `alloc`/`init` message
+ * wrapped in the retain that hands the object to the C++ wrapper. Nothing here
+ * assembles one -- a constructor whose selector takes arguments
+ * (`NSClickGestureRecognizer(target, action)`) states its own `{argN}` slots,
+ * and the arity is read back off the template for the same reason
+ * `templateArity` exists: the text that renders is the only authority on how
+ * many arguments it consumes.
+ *
+ * Keyed by carrier rather than by class name, so a host's constructor rows and
+ * its member rows are filed under one name.
+ */
+export declare const appleHostConstructors: () => HostConstructorTable;
+/**
+ * Apple's own class hierarchy, carrier to immediate base carrier.
+ *
+ * `NSStackView` IS an `NSView`, and the generated bridge says so in C++ by
+ * giving the wrapper structs the same inheritance the ObjC classes have
+ * (`struct NSStackView : gea::apple::AppKit::NSView`, written by
+ * `appleNativeBridgeHeader`). So passing one where the other is declared costs
+ * nothing at all at the target -- but nothing in TypeScript's structural view
+ * relates two opaque handles, so without this table the backend refuses an
+ * upcast the target performs implicitly.
+ *
+ * The base is spelled `Framework.Class` in the metadata, which is also a key of
+ * `nativeTypes` -- the shim builder files every class under both its bare and
+ * its qualified name -- so the carrier is looked up rather than re-derived. A
+ * base the type table does not carry is dropped: an unresolvable base is a
+ * chain this compiler cannot follow, and half a chain would answer "unrelated"
+ * for a pair that is related, which is the same refusal with a worse reason.
+ */
+export declare const appleNativeBases: () => HostBaseTable;
+/**
+ * The one header every Apple carrier is declared by.
+ *
+ * Named as a constant rather than written twice because a second reader of the
+ * same spelling exists outside the carrier table: `generatedSupportIncludes`
+ * (plugin.ts) states it in `generated_support.hpp`, and
+ * `apple/targets/macos/build-macos.sh` -- through
+ * `finalize-apple-native-output.mjs` and
+ * `apple_native_cached_output_is_current` -- greps that file for exactly the
+ * `#include` line built from it to decide whether an app is apple-native. Two
+ * places that must agree on one string is what the constant is for; `cli-emit.ts`
+ * used to hold its own copy and search the rendered C++ for it.
+ *
+ * `native_bridge.h` is written by the plugin package itself
+ * (`writeAppleNativeBridgeRuntime`) next to the emitted unit, and it declares
+ * every wrapper struct, the `objc::object`/`objc::retain` handle functions the
+ * templates call, and the framework imports behind an `__OBJC__` guard. One
+ * header for all of them because one generator writes all of them; the table is
+ * still keyed by carrier so a program that uses no Apple type includes nothing.
+ */
+export declare const appleNativeBridgeHeader = "gea/apple/native_bridge.h";
+export declare const appleNativeIncludes: () => HostIncludeTable;
+/**
+ * Apple's ambient constants, to the C++ text each one is.
+ *
+ * `NSBoxCustom`, `NSLayoutAttributeLeading` and the hundred others are
+ * Objective-C enumerators. Nothing declares a C++ global of those names, so a
+ * program that reads one and gets an `extern double` does not link -- and in
+ * Objective-C++ it does not even compile, because the enumerator is already a
+ * name at that scope and the declaration is a redefinition as a different kind
+ * of symbol. The host states the value instead, and the read renders it.
+ */
+export declare const appleNativeConstants: () => ReadonlyMap<string, string>;
+/**
+ * Apple's ambient free functions, to the C++ function each one is.
+ *
+ * `installRootViewController(vc)`, `CGRectMake(x, y, w, h)`,
+ * `dispatchAsyncMain(f)` -- names a program writes bare, that resolve to
+ * functions the target's own runtime defines (`macos_main.mm` defines the
+ * first; CoreGraphics defines the second). None of them is a member of
+ * anything, so `hostMembers` cannot state one, and none of them constructs a
+ * host object, so `hostConstructors` cannot either.
+ *
+ * Without this table the backend has one shape left for a value that is
+ * called -- a callable carrier -- and so it declares
+ * `extern gea::CallableObject<void(NSViewController)> installRootViewController;`
+ * and invokes `.call(...)` on it. That is not a near miss: the host exports a
+ * FUNCTION, this declares a global VARIABLE of the same name, and the program
+ * compiles and then fails to link against the very runtime that implements it.
+ *
+ * The spelling is the package's own `embeddedHostFunctions`, verbatim -- the
+ * same table v1's build has consumed all along, and the same one the bridge
+ * metadata records as each function's `thunk`.
+ */
+export declare const appleHostFunctions: () => HostFunctionTable;
+/**
+ * The free functions whose spelling depends on which declaration the program
+ * read, keyed by the file that declaration lives in.
+ *
+ * `installRootView` is the whole of the case: UIKit declares one and AppKit
+ * declares another, they are different functions with different parameter types
+ * and different thunks, and they share a bare name. A table keyed by name alone
+ * cannot hold both, so the flat one holds whichever the package wrote last --
+ * and an iOS program calling UIKit's got AppKit's spelling, which is not a
+ * near miss but a call into a framework the program never imported.
+ *
+ * The name a program wrote is not the coordinate; the declaration it resolved to
+ * is. `appleModuleMarkers` says which marker each declaration file belongs to
+ * and the package says which spelling each marker names, so this is those two
+ * facts joined -- nothing about frameworks is decided here.
+ */
+export declare const appleHostFunctionsByDeclaration: () => HostFunctionFileTable;