@geastack/compiler 1.0.15

package/dist/semantics/normalize/logical-result-type.d.ts

@@ -0,0 +1,16 @@
+import ts from 'typescript';
+export type LogicalOperator = '&&' | '||' | '??';
+/**
+ * The value `left` contributes to `left <op> right` on the branch that does
+ * NOT evaluate `right`, or `null` when there is no such branch -- an
+ * always-truthy `left` under `&&`, an always-falsy one under `||` -- in which
+ * case the expression's value is the right operand's, unqualified.
+ *
+ * The distinction is the whole point for `&&`: `obj && obj.x` keeps nothing
+ * from `obj`, so the expression IS `obj.x`. Widening it to "either operand"
+ * would union an object carrier with a number and produce a tagged union
+ * where an exact answer exists.
+ */
+export declare const keptLeftPartTypeOf: (checker: ts.TypeChecker, operator: LogicalOperator, left: ts.Type) => ts.Type | null;
+/** Combine settled operand types by the operator's value-selection rule, without a second checker query at the expression. */
+export declare const logicalResultTypeOf: (checker: ts.TypeChecker, operator: LogicalOperator, left: ts.Type, right: ts.Type) => ts.Type | null;

package/dist/semantics/normalize/logical-result-type.js

@@ -0,0 +1,102 @@
+import ts from 'typescript';
+/** The values a short-circuit operator can keep from its left operand. */
+const partitionsOf = (checker, type) => {
+    const truthy = [];
+    const falsy = [];
+    const nullish = [];
+    const visit = (part) => {
+        if (part.isUnion()) {
+            for (const member of part.types)
+                visit(member);
+            return;
+        }
+        const flags = part.flags;
+        if (flags & ts.TypeFlags.Never)
+            return;
+        if (flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.Void)) {
+            falsy.push(part);
+            nullish.push(part);
+            return;
+        }
+        if (flags & (ts.TypeFlags.Object | ts.TypeFlags.NonPrimitive | ts.TypeFlags.ESSymbolLike)) {
+            truthy.push(part);
+            return;
+        }
+        if (flags & ts.TypeFlags.BooleanLiteral) {
+            ;
+            (checker.isTypeAssignableTo(part, checker.getFalseType()) ? falsy : truthy).push(part);
+            return;
+        }
+        if (part.isStringLiteral() || part.isNumberLiteral()) {
+            ;
+            (part.value === '' || part.value === 0 ? falsy : truthy).push(part);
+            return;
+        }
+        if (part.isLiteral() && flags & ts.TypeFlags.BigIntLiteral) {
+            ;
+            (typeof part.value === 'object' && part.value.base10Value === '0' ? falsy : truthy).push(part);
+            return;
+        }
+        truthy.push(part);
+        if (flags & ts.TypeFlags.String)
+            falsy.push(checker.getStringLiteralType(''));
+        else if (flags & ts.TypeFlags.Boolean)
+            falsy.push(checker.getFalseType());
+        else if (flags & ts.TypeFlags.BigInt)
+            falsy.push(checker.getBigIntLiteralType({ negative: false, base10Value: '0' }));
+        else {
+            // Number's falsy values include NaN, which has no literal type. Keep the
+            // Number domain instead of inventing a zero-only fact. Unresolved type
+            // parameters and dynamic operands likewise retain their uncertainty.
+            falsy.push(part);
+            if (!(flags & ts.TypeFlags.NumberLike))
+                nullish.push(part);
+        }
+    };
+    visit(type);
+    return { truthy, falsy, nullish };
+};
+/**
+ * The arms of `left` the operator KEEPS as the whole expression's value --
+ * the ones under which the right operand never evaluates -- plus whether the
+ * right operand is reachable at all.
+ *
+ * Split out so the two questions asked of a short-circuit operator have one
+ * answer between them: `logicalResultTypeOf` below needs the merge, while a
+ * caller holding an operand carrier the checker does not agree with needs the
+ * left half ALONE, to union against its own right-hand answer rather than
+ * against the checker's.
+ */
+const keptPartsOf = (checker, operator, left) => {
+    const { truthy, falsy, nullish } = partitionsOf(checker, left);
+    const kept = operator === '&&' ? falsy : operator === '||' ? truthy : [...truthy, ...falsy].filter((part) => !nullish.includes(part));
+    const evaluatesRight = (operator === '&&' ? truthy : operator === '||' ? falsy : nullish).length > 0;
+    // Unknown/any may hold both present and nullish values. Filtering the same
+    // uncertain arm out entirely would turn `unknown ?? typed` into a proof.
+    if (operator === '??')
+        for (const part of nullish)
+            if (!(part.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.Void)))
+                kept.push(part);
+    return { kept, evaluatesRight };
+};
+const unionOf = (checker, members) => checker.getUnionType?.(members) ?? null;
+/**
+ * The value `left` contributes to `left <op> right` on the branch that does
+ * NOT evaluate `right`, or `null` when there is no such branch -- an
+ * always-truthy `left` under `&&`, an always-falsy one under `||` -- in which
+ * case the expression's value is the right operand's, unqualified.
+ *
+ * The distinction is the whole point for `&&`: `obj && obj.x` keeps nothing
+ * from `obj`, so the expression IS `obj.x`. Widening it to "either operand"
+ * would union an object carrier with a number and produce a tagged union
+ * where an exact answer exists.
+ */
+export const keptLeftPartTypeOf = (checker, operator, left) => {
+    const { kept } = keptPartsOf(checker, operator, left);
+    return kept.length === 0 ? null : unionOf(checker, kept);
+};
+/** Combine settled operand types by the operator's value-selection rule, without a second checker query at the expression. */
+export const logicalResultTypeOf = (checker, operator, left, right) => {
+    const { kept, evaluatesRight } = keptPartsOf(checker, operator, left);
+    return unionOf(checker, evaluatesRight ? [...kept, right] : kept);
+};

package/dist/semantics/normalize/namespace-paths.d.ts

@@ -0,0 +1,57 @@
+import ts from 'typescript';
+/**
+ * Which expressions name a source `namespace` -- a PATH -- rather than a value.
+ *
+ * `namespace Debug { export function assert(...) {...}; export let level = 0 }`
+ * followed by `Debug.assert(x)` / `Debug.level = 2` is, in TypeScript's own
+ * semantics, a QUALIFIED NAME: the checker resolves `Debug.assert` straight to
+ * the member's declaration, exactly as it resolves a bare `assert` written
+ * inside the namespace body. At run time the JS emit does allocate an object
+ * and install the exports on it, but that object is an artifact of the emit
+ * target, not a fact of the program: nothing the program can write depends on
+ * its identity, and a native C++ namespace has no object at all.
+ *
+ * Reading `Debug` as a VALUE is what broke TypeScript's own compiler. The
+ * checker types the namespace as a record whose fields are its exports, and a
+ * generic export (`checkDefined<T>(value: T | undefined): T`) puts an OPEN
+ * type parameter into that record. Every `Debug.*` site then selected a
+ * carrier with a hole in it -- 2,811 "type parameter reached representation
+ * without monomorphization" rows from one namespace, at sites that never
+ * instantiate anything -- and even a namespace with no generics at all failed
+ * at emission, because no producer ever introduces a cell for `Debug`
+ * (`binding-external`).
+ *
+ * So a namespace is modelled the way host namespaces already are
+ * (`host-protocols.ts`'s `hostNamespaceRoots`: "a name in here is a path,
+ * never a value"): `Debug` in `Debug.x` is no reference at all, `Debug.x` is
+ * the member's own binding reference -- the same `reference`/`binding` pair
+ * `references.ts` publishes for an identifier, cited by the same
+ * `citeExpressionResult` rule -- and `Debug.log.trace` walks the path one
+ * segment further. A namespace import (`import * as ts`) may ROOT such a path
+ * (`ts.Debug.loggingHost = ...` in tsc.ts), but a plain member of the import
+ * (`ts.foo`) keeps its existing `resolvedBinding` property get: only paths that
+ * pass through a source namespace are this census's business.
+ *
+ * Asked once here, with the checker, so the syntactic layers downstream --
+ * `census.ts`'s family rule and `citeExpressionResult`'s prediction of it --
+ * read ONE answer. Those two disagreeing is not an error anywhere, only a
+ * withheld citation that silently takes its consumers with it.
+ *
+ * Deliberately NOT a path: a namespace merged with a function, class, enum or
+ * variable (`function f() {}; namespace f { export const x = 1 }`) -- there the
+ * exports really are properties on a runtime object -- and anything ambient,
+ * which `host-protocols.ts` owns.
+ */
+export interface NamespacePathCensus {
+    /** Whether this expression names a source namespace, i.e. is a path and never a value. */
+    readonly isPath: (node: ts.Node) => boolean;
+    /**
+     * The member symbol a `Ns.member` property access names as a qualified
+     * binding, or `null` when the access is not one (an ordinary property, a
+     * path segment naming a nested namespace, a name that resolves to no value).
+     */
+    readonly memberSymbolOf: (node: ts.Node) => ts.Symbol | null;
+}
+/** A census that finds nothing, for callers that state no program. */
+export declare const emptyNamespacePathCensus: NamespacePathCensus;
+export declare const censusNamespacePaths: (checker: ts.TypeChecker) => NamespacePathCensus;

package/dist/semantics/normalize/namespace-paths.js

@@ -0,0 +1,108 @@
+import ts from 'typescript';
+/** A census that finds nothing, for callers that state no program. */
+export const emptyNamespacePathCensus = {
+    isPath: () => false,
+    memberSymbolOf: () => null
+};
+const resolveAlias = (checker, symbol) => symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+const isAmbient = (declaration) => {
+    for (let current = declaration; current; current = current.parent) {
+        if (ts.isModuleDeclaration(current) && (ts.getCombinedModifierFlags(current) & ts.ModifierFlags.Ambient) !== 0)
+            return true;
+    }
+    return false;
+};
+/**
+ * A symbol that is a source namespace and nothing else: instantiated
+ * (`ValueModule` -- a namespace holding only types is never in value position),
+ * every value-bearing declaration a non-ambient `namespace X` block in a
+ * source file, and merged with no function/class/enum/variable.
+ *
+ * A type alias or interface merged with the namespace (`type State = <T>(...)
+ * => number; namespace State { export function enter ... }`, the
+ * callable-type-plus-statics idiom, `test/runtime/generic-state-function-array.ts`)
+ * is erased: it contributes no runtime value, so the namespace is still
+ * nothing but a path. Requiring EVERY declaration to be a module block made
+ * `State` a value here, and a value nothing ever produces is the `Debug`
+ * failure above -- every `State.enter` read refused as `binding-external`.
+ */
+const isSourceNamespace = (checker, symbol) => {
+    const resolved = resolveAlias(checker, symbol);
+    if ((resolved.flags & ts.SymbolFlags.ValueModule) === 0)
+        return false;
+    if ((resolved.flags & (ts.SymbolFlags.Class | ts.SymbolFlags.Function | ts.SymbolFlags.Enum | ts.SymbolFlags.Variable)) !== 0)
+        return false;
+    const declarations = resolved.getDeclarations();
+    if (!declarations || declarations.length === 0)
+        return false;
+    return (declarations.some(ts.isModuleDeclaration) &&
+        declarations.every((declaration) => ts.isTypeAliasDeclaration(declaration) ||
+            ts.isInterfaceDeclaration(declaration) ||
+            (ts.isModuleDeclaration(declaration) &&
+                ts.isIdentifier(declaration.name) &&
+                !declaration.getSourceFile().isDeclarationFile &&
+                !isAmbient(declaration))));
+};
+const isNamespaceImportName = (checker, node) => {
+    const symbol = checker.getSymbolAtLocation(node);
+    return symbol?.declarations?.some((declaration) => ts.isNamespaceImport(declaration)) ?? false;
+};
+export const censusNamespacePaths = (checker) => {
+    const paths = new WeakMap();
+    const members = new WeakMap();
+    const isPath = (node) => {
+        const known = paths.get(node);
+        if (known !== undefined)
+            return known;
+        const answer = computePath(node);
+        paths.set(node, answer);
+        return answer;
+    };
+    /** A path, or the namespace import that may root one. */
+    const isPathRoot = (node) => isPath(node) || (ts.isIdentifier(node) && isNamespaceImportName(checker, node));
+    const computePath = (node) => {
+        if (ts.isIdentifier(node)) {
+            const symbol = checker.getSymbolAtLocation(node);
+            return symbol !== undefined && isSourceNamespace(checker, symbol);
+        }
+        if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.name)) {
+            if (!isPathRoot(node.expression))
+                return false;
+            const symbol = checker.getSymbolAtLocation(node.name);
+            return symbol !== undefined && isSourceNamespace(checker, symbol);
+        }
+        return false;
+    };
+    const memberSymbolOf = (node) => {
+        const known = members.get(node);
+        if (known !== undefined)
+            return known;
+        const answer = computeMember(node);
+        members.set(node, answer);
+        return answer;
+    };
+    const computeMember = (node) => {
+        if (!ts.isPropertyAccessExpression(node) || !ts.isIdentifier(node.name))
+            return null;
+        // Through a SOURCE namespace, not merely a namespace import: `ts.foo` is
+        // `properties.ts`'s own `resolvedBinding` shape and stays that way.
+        if (!isPath(node.expression))
+            return null;
+        const symbol = checker.getSymbolAtLocation(node.name);
+        if (!symbol)
+            return null;
+        const resolved = resolveAlias(checker, symbol);
+        // A nested namespace is one more path segment, not a member with a cell.
+        if (isSourceNamespace(checker, resolved))
+            return null;
+        if ((resolved.flags & ts.SymbolFlags.Value) === 0)
+            return null;
+        const declarations = resolved.getDeclarations();
+        if (!declarations || declarations.length === 0)
+            return null;
+        if (declarations.some((declaration) => declaration.getSourceFile().isDeclarationFile || isAmbient(declaration)))
+            return null;
+        return symbol;
+    };
+    return { isPath, memberSymbolOf };
+};

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

@@ -0,0 +1,57 @@
+import type { OperationFamily, OperationId } from '../../identity/ids.js';
+import type { SemanticEdge } from '../model/edges.js';
+import type { SemanticGraph } from '../model/graph.js';
+import type { SemanticOperation } from '../model/operations.js';
+import type { StructuralTypeTable } from '../model/structural-type-table.js';
+import type { ProgramCensus } from './census.js';
+import type { FamilyProducer } from './contribution.js';
+import type { CensusCandidate } from './census.js';
+/**
+ * The normalization driver.
+ *
+ * Producers are passed in rather than imported so that this driver cannot
+ * acquire a hidden dependency on one family's implementation, and so a family
+ * can be exercised in isolation. Every censused family either has a producer or
+ * is reported `not-installed` with its complete candidate list -- there is no
+ * third state where a family quietly contributes nothing.
+ */
+export interface NormalizationInput {
+    readonly census: ProgramCensus;
+    readonly types: StructuralTypeTable;
+    /**
+     * The producers for one monomorphized copy, given a candidate belonging to
+     * it. A program with no generics asks this once and gets one set; a program
+     * that instantiates a generic twice gets two, each resolving that generic's
+     * type parameters as its own copy binds them.
+     */
+    readonly producers: (candidate: CensusCandidate) => readonly FamilyProducer[];
+    /**
+     * What distinguishes one monomorphized copy from another, for the purpose of
+     * reusing a producer set.
+     *
+     * Supplied rather than derived, because deriving it needs the owner half of a
+     * specialization path and this driver cannot see an AST. It must NOT be
+     * `specializationKey`: that is an identity *suffix*, where the owner is
+     * deliberately 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`, and a cache
+     * keyed on that alone hands the second one the first one's view of which
+     * nodes are inside a copy. Every identity that view then mints for a node it
+     * does not recognize comes out unspecialized, so a body and the allocation
+     * that gives it a calling convention end up disagreeing about which copy they
+     * belong to.
+     */
+    readonly copyKey: (candidate: CensusCandidate) => string;
+    /**
+     * The conditional edges no single producer can state, computed once every
+     * operation exists. Kept as a callback so this driver still cannot see an
+     * AST: it hands over the published operations and receives edges back.
+     */
+    readonly gates: (operations: ReadonlyMap<OperationId, SemanticOperation>) => readonly SemanticEdge[];
+}
+export interface NormalizationResult {
+    readonly graph: SemanticGraph;
+    /** Families with no producer, reported rather than omitted. */
+    readonly uninstalledFamilies: readonly OperationFamily[];
+}
+export declare const normalizeProgram: (input: NormalizationInput) => NormalizationResult;

package/dist/semantics/normalize/normalize.js

@@ -0,0 +1,68 @@
+import { operationFamilies } from '../../identity/ids.js';
+import { edgeSource } from '../model/edges.js';
+import { validateGraph } from '../model/graph.js';
+import { publishProgram } from './contribution.js';
+export const normalizeProgram = (input) => {
+    // One producer set per copy, built on first use and reused: the set is a
+    // dozen closures and rebuilding it per candidate would rebuild it thousands
+    // of times for one answer.
+    const byCopy = new Map();
+    const producersFor = (candidate) => {
+        const key = input.copyKey(candidate);
+        const cached = byCopy.get(key);
+        if (cached)
+            return cached;
+        const built = new Map(input.producers(candidate).map((producer) => [producer.family, producer]));
+        byCopy.set(key, built);
+        return built;
+    };
+    const published = publishProgram(operationFamilies, producersFor, input.census.byFamily);
+    const operations = new Map();
+    const results = new Map();
+    for (const operation of published.operations) {
+        if (operations.has(operation.id)) {
+            throw new Error(`operation ${operation.id} was published twice; one source operation must mint one identity`);
+        }
+        operations.set(operation.id, operation);
+        for (const result of operation.results) {
+            if (results.has(result.id))
+                throw new Error(`result ${result.id} was published twice`);
+            results.set(result.id, operation.id);
+        }
+    }
+    const regions = new Map();
+    for (const region of input.census.regions.values())
+        regions.set(region.id, region);
+    // An edge whose endpoints were withheld would dangle. Dropping it here keeps
+    // the sealed graph internally consistent instead of leaving validation to
+    // discover a half-published component -- the withholding itself is already
+    // reported as a blocker, so nothing is hidden by this.
+    const reaches = (edge) => {
+        if (!operations.has(edge.to))
+            return false;
+        if (edge.kind === 'value')
+            return results.has(edge.result);
+        if (edge.kind === 'conditional')
+            return results.has(edge.guard);
+        if (edge.kind === 'loop')
+            return operations.has(edge.loop);
+        return operations.has(edgeSource(edge, (result) => results.get(result) ?? ''));
+    };
+    const graph = {
+        regions,
+        structuralTypes: input.types.seal(),
+        operations,
+        edges: [...published.edges, ...input.gates(operations)].filter(reaches),
+        coverage: published.reports,
+        results
+    };
+    validateGraph(graph);
+    return {
+        graph,
+        uninstalledFamilies: operationFamilies.filter((family) => {
+            const candidates = input.census.byFamily.get(family) ?? [];
+            const first = candidates[0];
+            return first !== undefined && !producersFor(first).has(family);
+        })
+    };
+};