@geastack/compiler 1.0.15

package/dist/semantics/normalize/cells/policies/local.js

@@ -0,0 +1,37 @@
+import ts from 'typescript';
+import { cellCandidatesOf } from '../candidates.js';
+import { cellType } from '../model.js';
+import { rulesFor } from '../policy.js';
+import { combineTypesByJoin } from './shared.js';
+const isUnannotatedUninitializedLocal = (node) => ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.type === undefined && node.initializer === undefined;
+/**
+ * The LOCAL domain: `local-bindings.ts`'s question ("an unannotated
+ * `let`/`var` cell with no initializer, filled in by exactly the writes the
+ * program makes to it"), restated over the shared flow index's
+ * `identifier-assignment` and `logical-assignment` edges.
+ *
+ * `compound-assignment` (`x += 1`) is deliberately given no rule: per
+ * `flow/model.ts`'s own doc, that edge states existence and a DERIVED value,
+ * never a fresh one, so admitting it here would join the cell's own prior
+ * (unknown) contents into its write-join. `rulesFor` skipping an edge is the
+ * correct, sound default -- soundness cuts one way here:
+ * missing evidence is a box, joining the wrong evidence is a silent
+ * miscompile, and this domain refuses the second, never the first.
+ */
+export const createLocalCellPolicy = (checker, reachable) => {
+    const valueRule = (write) => write.value ? cellType(checker.getTypeAtLocation(write.value)) : null;
+    return {
+        domain: 'local',
+        candidatesOf: (files) => cellCandidatesOf(reachable, files, isUnannotatedUninitializedLocal),
+        // Candidates have no annotation by construction; kept as a real read
+        // rather than a constant `null` so a looser candidate set still gets a
+        // correct answer instead of a silently stale one.
+        statedAt: () => null,
+        checkerAt: (declaration) => cellType(checker.getTypeAtLocation(declaration)),
+        rules: rulesFor([
+            ['identifier-assignment', valueRule],
+            ['logical-assignment', valueRule]
+        ]),
+        combine: combineTypesByJoin(checker)
+    };
+};

package/dist/semantics/normalize/cells/policies/parameter.d.ts

@@ -0,0 +1,28 @@
+import ts from 'typescript';
+import type { ProgramReachability } from '../../reachability.js';
+import type { CellEvidencePolicy } from '../policy.js';
+/**
+ * The PARAMETER domain: `parameter-bindings.ts`'s question ("the type a
+ * parameter the program never annotated is actually called with"), restated
+ * as one evidence rule over the shared flow index's `call-argument` edge.
+ *
+ * `flow/model.ts` already resolves an argument to the callee's parameter slot
+ * wherever the walk could name the callee (the value-flow survey's callee row), so
+ * this policy does no call-site resolution of its own -- it reads
+ * `flow.writesToDeclaration(parameter)` and asks only "does this edge state a
+ * value", which is the one thing a `CellEvidenceRule` may ask.
+ *
+ * `parameter-bindings.ts` additionally refuses a parameter that escapes as a
+ * value to an unresolved caller, is itself reassigned, or whose call sites'
+ * types merely differ rather than provably agreeing (`widestOf`'s guard) --
+ * none of that policy is re-implemented here. `joinOfWrites` (via
+ * `combineTypesByJoin`) already returns `null` on genuine disagreement, so
+ * soundness against a wrong join is unaffected; what is not yet ported is the
+ * ESCAPE refusal, so this policy's write-join can be more OPTIMISTIC than the
+ * existing census's about a parameter whose name leaks somewhere this domain
+ * does not itself track. That is safe for phase 4.1 -- nothing downstream
+ * reads this table -- and is exactly the "not yet a policy" gap this
+ * refactor's report calls out for phase 4.2 to close before anything is
+ * wired to replace `parameter-bindings.ts`.
+ */
+export declare const createParameterCellPolicy: (checker: ts.TypeChecker, reachable: ProgramReachability) => CellEvidencePolicy;

package/dist/semantics/normalize/cells/policies/parameter.js

@@ -0,0 +1,39 @@
+import ts from 'typescript';
+import { cellCandidatesOf } from '../candidates.js';
+import { cellType } from '../model.js';
+import { rulesFor } from '../policy.js';
+import { checkerTypeAt, combineTypesByJoin, statedTypeOf } from './shared.js';
+/**
+ * The PARAMETER domain: `parameter-bindings.ts`'s question ("the type a
+ * parameter the program never annotated is actually called with"), restated
+ * as one evidence rule over the shared flow index's `call-argument` edge.
+ *
+ * `flow/model.ts` already resolves an argument to the callee's parameter slot
+ * wherever the walk could name the callee (the value-flow survey's callee row), so
+ * this policy does no call-site resolution of its own -- it reads
+ * `flow.writesToDeclaration(parameter)` and asks only "does this edge state a
+ * value", which is the one thing a `CellEvidenceRule` may ask.
+ *
+ * `parameter-bindings.ts` additionally refuses a parameter that escapes as a
+ * value to an unresolved caller, is itself reassigned, or whose call sites'
+ * types merely differ rather than provably agreeing (`widestOf`'s guard) --
+ * none of that policy is re-implemented here. `joinOfWrites` (via
+ * `combineTypesByJoin`) already returns `null` on genuine disagreement, so
+ * soundness against a wrong join is unaffected; what is not yet ported is the
+ * ESCAPE refusal, so this policy's write-join can be more OPTIMISTIC than the
+ * existing census's about a parameter whose name leaks somewhere this domain
+ * does not itself track. That is safe for phase 4.1 -- nothing downstream
+ * reads this table -- and is exactly the "not yet a policy" gap this
+ * refactor's report calls out for phase 4.2 to close before anything is
+ * wired to replace `parameter-bindings.ts`.
+ */
+export const createParameterCellPolicy = (checker, reachable) => ({
+    domain: 'parameter',
+    candidatesOf: (files) => cellCandidatesOf(reachable, files, (node) => ts.isParameter(node) && node.type === undefined && ts.isIdentifier(node.name) && node.dotDotDotToken === undefined),
+    statedAt: (declaration) => statedTypeOf(checker, declaration.type),
+    checkerAt: checkerTypeAt(checker),
+    rules: rulesFor([
+        ['call-argument', (write) => (write.value ? cellType(checker.getTypeAtLocation(write.value)) : null)]
+    ]),
+    combine: combineTypesByJoin(checker)
+});

package/dist/semantics/normalize/cells/policies/return.d.ts

@@ -0,0 +1,26 @@
+import ts from 'typescript';
+import type { ProgramReachability } from '../../reachability.js';
+import type { CellEvidencePolicy } from '../policy.js';
+/**
+ * The RETURN domain: `return-bindings.ts`'s question, restated as one
+ * evidence rule over the shared flow index's `return` edge, exactly the way
+ * `parameter-bindings.ts` restates as `call-argument`.
+ *
+ * `flow/model.ts` already resolves a `return expr` to its ENCLOSING
+ * function's return cell (the value-flow survey's `RET: Y` column), so
+ * `flow.writesToDeclaration(declaration)` needs no recursion tracking of its
+ * own here -- unlike `return-bindings.ts`'s `resolvedReturnTypeOf`, which
+ * exists mainly to CALL a not-yet-settled callee's return from a parameter
+ * census, a question this policy does not answer at all (that is
+ * `parameter-bindings.ts`'s own internal fixpoint, item 8 of the edge
+ * matrix, and not a write-join over one cell's own writes).
+ *
+ * `checkerAt` reads the SIGNATURE's return type, not
+ * `checker.getTypeAtLocation(declaration)` -- the latter is the function's
+ * own callable type (`() => number`), and this domain's cell is what the
+ * body produces, not the function object itself. This is the one place the
+ * "checker" primitive is not a plain `getTypeAtLocation` call, because the
+ * declaration node names two different cells depending on who reads it: the
+ * ALLOCATION producer wants the callable, this domain wants the result.
+ */
+export declare const createReturnCellPolicy: (checker: ts.TypeChecker, reachable: ProgramReachability) => CellEvidencePolicy;

package/dist/semantics/normalize/cells/policies/return.js

@@ -0,0 +1,45 @@
+import ts from 'typescript';
+import { cellCandidatesOf } from '../candidates.js';
+import { cellType } from '../model.js';
+import { rulesFor } from '../policy.js';
+import { combineTypesByJoin, statedTypeOf } from './shared.js';
+const isReturnLikeCandidate = (node) => (ts.isFunctionDeclaration(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isArrowFunction(node) ||
+    ts.isMethodDeclaration(node) ||
+    ts.isGetAccessorDeclaration(node)) &&
+    node.body !== undefined &&
+    node.type === undefined;
+/**
+ * The RETURN domain: `return-bindings.ts`'s question, restated as one
+ * evidence rule over the shared flow index's `return` edge, exactly the way
+ * `parameter-bindings.ts` restates as `call-argument`.
+ *
+ * `flow/model.ts` already resolves a `return expr` to its ENCLOSING
+ * function's return cell (the value-flow survey's `RET: Y` column), so
+ * `flow.writesToDeclaration(declaration)` needs no recursion tracking of its
+ * own here -- unlike `return-bindings.ts`'s `resolvedReturnTypeOf`, which
+ * exists mainly to CALL a not-yet-settled callee's return from a parameter
+ * census, a question this policy does not answer at all (that is
+ * `parameter-bindings.ts`'s own internal fixpoint, item 8 of the edge
+ * matrix, and not a write-join over one cell's own writes).
+ *
+ * `checkerAt` reads the SIGNATURE's return type, not
+ * `checker.getTypeAtLocation(declaration)` -- the latter is the function's
+ * own callable type (`() => number`), and this domain's cell is what the
+ * body produces, not the function object itself. This is the one place the
+ * "checker" primitive is not a plain `getTypeAtLocation` call, because the
+ * declaration node names two different cells depending on who reads it: the
+ * ALLOCATION producer wants the callable, this domain wants the result.
+ */
+export const createReturnCellPolicy = (checker, reachable) => ({
+    domain: 'return',
+    candidatesOf: (files) => cellCandidatesOf(reachable, files, isReturnLikeCandidate),
+    statedAt: (declaration) => statedTypeOf(checker, declaration.type),
+    checkerAt: (declaration) => {
+        const signature = checker.getSignatureFromDeclaration(declaration);
+        return cellType(signature ? signature.getReturnType() : checker.getTypeAtLocation(declaration));
+    },
+    rules: rulesFor([['return', (write) => (write.value ? cellType(checker.getTypeAtLocation(write.value)) : null)]]),
+    combine: combineTypesByJoin(checker)
+});

package/dist/semantics/normalize/cells/policies/shared.d.ts

@@ -0,0 +1,33 @@
+import type ts from 'typescript';
+import { type CellValue } from '../model.js';
+import type { CellEvidenceContribution } from '../policy.js';
+/**
+ * The join itself, over plain `CellValue`s -- factored out of
+ * `combineTypesByJoin` so `collection.ts`'s per-slot combine can apply the
+ * SAME join twice (once for the key group, once for the value group)
+ * instead of restating `joinOfWrites`'s unwrap-or-refuse rule a second time.
+ */
+export declare const joinCellTypeValues: (checker: ts.TypeChecker, values: readonly CellValue[]) => ts.Type | null;
+/**
+ * The combinator every `ts.Type`-space domain (parameter, return, local,
+ * field) shares: the exact join `parameter-bindings.ts` and its siblings
+ * already use over an argument/return/write set, reused rather than
+ * re-derived -- `joinOfWrites` is a pure function these censuses already
+ * export, and the rule to add exports only if a
+ * policy needs to call an existing pure helper" is exactly this case.
+ *
+ * These four domains join their WHOLE cell into one answer, so the
+ * `CellEvidenceContribution.write` half of each contribution (which slot,
+ * which member) is simply not asked -- `collection`/`bag` are the two
+ * domains where it is.
+ */
+export declare const combineTypesByJoin: (checker: ts.TypeChecker) => (contributions: readonly CellEvidenceContribution[]) => CellValue | null;
+/** The checker's own answer at a declaration, wrapped -- always present, the fallback of last resort. */
+export declare const checkerTypeAt: (checker: ts.TypeChecker) => (declaration: ts.Node) => CellValue | null;
+/**
+ * The program's own annotation, when a declaration shape carries one and
+ * states something usable -- `null` covers both "no annotation" and "the
+ * annotation is `any`/`void`/`never`, i.e. states nothing more than the
+ * checker's own vacuous answer would".
+ */
+export declare const statedTypeOf: (checker: ts.TypeChecker, typeNode: ts.TypeNode | undefined) => CellValue | null;

package/dist/semantics/normalize/cells/policies/shared.js

@@ -0,0 +1,45 @@
+import { isUnusableEvidence, joinOfWrites } from '../../derived-expression-type.js';
+import { cellType } from '../model.js';
+/**
+ * The join itself, over plain `CellValue`s -- factored out of
+ * `combineTypesByJoin` so `collection.ts`'s per-slot combine can apply the
+ * SAME join twice (once for the key group, once for the value group)
+ * instead of restating `joinOfWrites`'s unwrap-or-refuse rule a second time.
+ */
+export const joinCellTypeValues = (checker, values) => {
+    const types = values.flatMap((value) => (value.kind === 'type' ? [value.type] : []));
+    if (types.length !== values.length)
+        return null;
+    return joinOfWrites(checker, types);
+};
+/**
+ * The combinator every `ts.Type`-space domain (parameter, return, local,
+ * field) shares: the exact join `parameter-bindings.ts` and its siblings
+ * already use over an argument/return/write set, reused rather than
+ * re-derived -- `joinOfWrites` is a pure function these censuses already
+ * export, and the rule to add exports only if a
+ * policy needs to call an existing pure helper" is exactly this case.
+ *
+ * These four domains join their WHOLE cell into one answer, so the
+ * `CellEvidenceContribution.write` half of each contribution (which slot,
+ * which member) is simply not asked -- `collection`/`bag` are the two
+ * domains where it is.
+ */
+export const combineTypesByJoin = (checker) => (contributions) => {
+    const joined = joinCellTypeValues(checker, contributions.map((contribution) => contribution.value));
+    return joined ? cellType(joined) : null;
+};
+/** The checker's own answer at a declaration, wrapped -- always present, the fallback of last resort. */
+export const checkerTypeAt = (checker) => (declaration) => cellType(checker.getTypeAtLocation(declaration));
+/**
+ * The program's own annotation, when a declaration shape carries one and
+ * states something usable -- `null` covers both "no annotation" and "the
+ * annotation is `any`/`void`/`never`, i.e. states nothing more than the
+ * checker's own vacuous answer would".
+ */
+export const statedTypeOf = (checker, typeNode) => {
+    if (!typeNode)
+        return null;
+    const stated = checker.getTypeFromTypeNode(typeNode);
+    return isUnusableEvidence(stated) ? null : cellType(stated);
+};

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

@@ -0,0 +1,72 @@
+import type ts from 'typescript';
+import type { FlowEdgeKind, ValueFlowIndex, ValueWrite } from '../flow/model.js';
+import type { CellDomain, CellValue } from './model.js';
+/**
+ * One domain's reading of one write: the value it contributes to the cell's
+ * write-join, or `null` to sit out. `null` is the ordinary answer for an edge
+ * that exists but states no fresh value for THIS domain -- a `compound-
+ * assignment` (existence only, per `flow/model.ts`'s own doc on the kind) or
+ * a write whose value this domain cannot resolve to anything usable.
+ */
+export type CellEvidenceRule = (write: ValueWrite, declaration: ts.Node) => CellValue | null;
+/**
+ * One admitted write, paired with the value its rule produced -- what
+ * `combine` actually receives. Plain `CellValue`s were enough while every
+ * ported domain (parameter, return, local, field) joined its whole cell into
+ * ONE answer; `collection`/`bag` join per SLOT (`collection-key` vs
+ * `collection-value`) or per MEMBER NAME (`ValueWrite.member`), a question
+ * `combine` cannot ask once the write that produced a value is discarded.
+ * Keeping the pair is the whole extension `policies/index.ts`'s header calls
+ * for -- `combine` was already free to look at `write.slot`/`write.member`
+ * (both were already on `ValueWrite`, see `flow/model.ts`), it simply never
+ * received the write to look at.
+ */
+export interface CellEvidenceContribution {
+    readonly write: ValueWrite;
+    readonly value: CellValue;
+}
+/**
+ * A census, restated as data: `(domain, FlowEdgeKind) -> evidence rule`,
+ * the "cell census" row: a capability is keyed rows, never an ordered chain. Nothing here
+ * is ordered -- a policy is asked about every edge kind it registered a rule
+ * for, independent of every other policy and of any position in a chain.
+ */
+export interface CellEvidencePolicy {
+    readonly domain: CellDomain;
+    /** Every declaration this domain is willing to answer for, in this program. */
+    readonly candidatesOf: (files: readonly ts.SourceFile[]) => Iterable<ts.Declaration>;
+    /** The program's own annotation for this declaration, or `null` when it stated none. */
+    readonly statedAt: (declaration: ts.Node) => CellValue | null;
+    /** The checker's own answer -- always present, the fallback of last resort. */
+    readonly checkerAt: (declaration: ts.Node) => CellValue | null;
+    /**
+     * The writes this domain admits as evidence for one candidate. Defaults to
+     * `flow.writesToDeclaration(declaration)` (every ported `ts.Type`-space
+     * domain relies on that default and states no `writesOf` of its own) --
+     * `collection`'s own reason to override it is the OTHER stated obstacle:
+     * `collection-bindings.ts` follows a value's identity through an ALIAS
+     * CLOSURE (`const helper = []; fill(helper)`, `this.cache.set(...)`) that a
+     * single declaration's own writes cannot state, because the evidence lands
+     * on a DIFFERENT declaration (a parameter the value was passed to, a
+     * property that re-exports it) than the candidate this policy is answering
+     * for. A policy that needs that closure computes it itself, over the same
+     * `flow.flowsFromDeclaration` reverse edge `collection-bindings.ts` already
+     * walks -- this hook is what lets it do so without forcing every OTHER
+     * domain to pay for a closure it never needed.
+     */
+    readonly writesOf?: (declaration: ts.Node, flow: ValueFlowIndex) => readonly ValueWrite[];
+    /** One evidence rule per `FlowEdgeKind` this domain admits as a write; an edge with no entry contributes nothing. */
+    readonly rules: Partial<Readonly<Record<FlowEdgeKind, CellEvidenceRule>>>;
+    /** The join over every admitted write, or `null` when they disagree -- never merged into a wider guess. */
+    readonly combine: (contributions: readonly CellEvidenceContribution[]) => CellValue | null;
+}
+/**
+ * Builds a policy's `rules` table from `(edge, rule)` pairs and throws on a
+ * second rule for one edge -- the mechanical form of table 2.8's collision
+ * rule for a cell census: "a second rule for one key throws at census
+ * construction." A plain object literal cannot enforce this on its own (a
+ * repeated key just silently overwrites the first), so every policy in this
+ * directory builds its `rules` through this function rather than writing the
+ * object literal by hand.
+ */
+export declare const rulesFor: (entries: readonly (readonly [FlowEdgeKind, CellEvidenceRule])[]) => Partial<Readonly<Record<FlowEdgeKind, CellEvidenceRule>>>;

package/dist/semantics/normalize/cells/policy.js

@@ -0,0 +1,18 @@
+/**
+ * Builds a policy's `rules` table from `(edge, rule)` pairs and throws on a
+ * second rule for one edge -- the mechanical form of table 2.8's collision
+ * rule for a cell census: "a second rule for one key throws at census
+ * construction." A plain object literal cannot enforce this on its own (a
+ * repeated key just silently overwrites the first), so every policy in this
+ * directory builds its `rules` through this function rather than writing the
+ * object literal by hand.
+ */
+export const rulesFor = (entries) => {
+    const rules = {};
+    for (const [edge, rule] of entries) {
+        if (rules[edge] !== undefined)
+            throw new Error(`cell evidence policy: two rules registered for edge kind '${edge}'`);
+        rules[edge] = rule;
+    }
+    return rules;
+};

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

@@ -0,0 +1,14 @@
+import type { CellEvidencePolicy } from './policy.js';
+/** Every domain's evidence policy, registered once. */
+export interface CellPolicyRegistry {
+    readonly policies: readonly CellEvidencePolicy[];
+}
+/**
+ * Registers one evidence policy per domain -- table 2.8's collision rule for
+ * a cell census, on the other axis `policy.ts`'s `rulesFor` does not cover:
+ * two policies both claiming one domain, rather than two rules inside one
+ * policy. Thrown at construction, not discovered later as two domains quietly
+ * shadowing each other the way `structural.ts`'s `typeAt` chain lets a
+ * position decide today.
+ */
+export declare const createCellPolicyRegistry: (policies: readonly CellEvidencePolicy[]) => CellPolicyRegistry;

package/dist/semantics/normalize/cells/registry.js

@@ -0,0 +1,17 @@
+/**
+ * Registers one evidence policy per domain -- table 2.8's collision rule for
+ * a cell census, on the other axis `policy.ts`'s `rulesFor` does not cover:
+ * two policies both claiming one domain, rather than two rules inside one
+ * policy. Thrown at construction, not discovered later as two domains quietly
+ * shadowing each other the way `structural.ts`'s `typeAt` chain lets a
+ * position decide today.
+ */
+export const createCellPolicyRegistry = (policies) => {
+    const seen = new Set();
+    for (const policy of policies) {
+        if (seen.has(policy.domain))
+            throw new Error(`cell evidence policy: domain '${policy.domain}' registered twice`);
+        seen.add(policy.domain);
+    }
+    return { policies };
+};

package/dist/semantics/normalize/census-refusal.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Which write-discovery census refused.
+ *
+ * The same six domains `cells/` registers as evidence policies, plus
+ * `jsdoc-type-name`, the one smaller census that publishes a refusal
+ * vocabulary of its own. A domain is spelled once, here, because it is half of
+ * a refusal's key and a domain spelled twice is two vocabularies.
+ */
+export type CensusDomain = 'parameter' | 'return' | 'local' | 'field' | 'collection' | 'bag' | 'jsdoc-type-name';
+/**
+ * `census:<domain>:<root>` -- the ROOT, never the prose.
+ *
+ * A refusal's key is what groups it with the others that share a cause, so it
+ * must name the cause and nothing else: no node text, no type spelling, no
+ * count, nothing that varies between two instances of one defect. The prose
+ * belongs in `reason`, where it can name the specific node. This is the same
+ * split `cells/model.ts`'s `CellRefusalKey` already makes, and the same reason
+ * `parameter-bindings.ts` keyed its count map by reason rather than by site.
+ */
+export type CensusRefusalKey = `census:${CensusDomain}:${string}`;
+/**
+ * A census refusal in the compiler's one refusal vocabulary
+ * (`ir/refusal.ts`'s `Refusal`).
+ *
+ * These used to be eight private `ReadonlyMap<string, number>`s of hand-written
+ * prose -- a count per reason, with no owner, reaching `CompileResult` only as
+ * `censusAccounting` and never joining `CompileResult.refusals` the way every
+ * other stage's refusals do. A count says a cell went untyped; it cannot say
+ * WHICH cell, so nothing downstream could act on one and nothing did. Carrying
+ * the owner is what makes a census refusal the same kind of object as an ABI
+ * blocker or a print refusal, and lets one list answer "what did this
+ * compilation refuse, and where" (the frontend is replaced, not instrumented).
+ *
+ * Declared here rather than as an `ir/refusal.ts` `Refusal` for the reason
+ * `cells/model.ts` already gives for `CellRefusal`: the frontend settles long
+ * before there is a plan to certify against, and semantics must not import the
+ * IR to name its own refusals. `compiler.ts` sees both layers and is where the
+ * two lists join.
+ */
+export interface CensusRefusal {
+    readonly stage: 'census';
+    readonly key: CensusRefusalKey;
+    readonly reason: string;
+    readonly owner: string;
+}
+/**
+ * State a refusal.
+ *
+ * `owner` is the declaration, node or symbol the refusal is attributed to,
+ * already rendered -- the census knows how to name its own subject and the
+ * refusal list must not depend on an identity table to read one.
+ */
+export declare const censusRefusal: (domain: CensusDomain, root: string, reason: string, owner: string) => CensusRefusal;
+/**
+ * The count-per-reason map the censuses used to publish, derived.
+ *
+ * Kept because instruments already read that shape, and DERIVED rather than
+ * maintained beside the list so the two cannot disagree -- a count that drifts
+ * from the refusals it counts is the two-authorities defect this refactor
+ * exists to remove, in miniature.
+ */
+export declare const censusRefusalCounts: (refusals: readonly CensusRefusal[]) => ReadonlyMap<string, number>;

package/dist/semantics/normalize/census-refusal.js

@@ -0,0 +1,27 @@
+/**
+ * State a refusal.
+ *
+ * `owner` is the declaration, node or symbol the refusal is attributed to,
+ * already rendered -- the census knows how to name its own subject and the
+ * refusal list must not depend on an identity table to read one.
+ */
+export const censusRefusal = (domain, root, reason, owner) => ({
+    stage: 'census',
+    key: `census:${domain}:${root}`,
+    reason,
+    owner
+});
+/**
+ * The count-per-reason map the censuses used to publish, derived.
+ *
+ * Kept because instruments already read that shape, and DERIVED rather than
+ * maintained beside the list so the two cannot disagree -- a count that drifts
+ * from the refusals it counts is the two-authorities defect this refactor
+ * exists to remove, in miniature.
+ */
+export const censusRefusalCounts = (refusals) => {
+    const counts = new Map();
+    for (const refusal of refusals)
+        counts.set(refusal.key, (counts.get(refusal.key) ?? 0) + 1);
+    return counts;
+};

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

@@ -0,0 +1,109 @@
+import ts from 'typescript';
+import type { NamespacePathCensus } from './namespace-paths.js';
+import type { NodeId, OperationFamily } from '../../identity/ids.js';
+import type { SemanticCaller } from '../model/operands.js';
+import type { SemanticRegion } from '../model/graph.js';
+import { type IdentityTable, type SpecializationPath } from './identities.js';
+import type { SpecializationCensus } from './specialization.js';
+import type { ProgramReachability } from './reachability.js';
+/**
+ * The census.
+ *
+ * Before anything is normalized, every syntactic site in the program is
+ * enumerated and assigned to a family. This is what makes "not installed"
+ * measurable: a family that publishes nothing still has to account for every
+ * candidate it saw. Without the census, a producer that silently skips a
+ * construct is indistinguishable from a program that does not contain it.
+ *
+ * The census assigns families from ECMAScript syntax kinds only. It does not
+ * look at names, and it does not look at what a call resolves to -- that is
+ * proof, and proof comes later.
+ */
+export interface CensusCandidate {
+    readonly node: ts.Node;
+    readonly id: NodeId;
+    readonly family: OperationFamily;
+    readonly caller: SemanticCaller;
+    /** Reachability requires this class's shape but no runtime definition. */
+    readonly classLayoutOnly?: boolean;
+    /**
+     * Which monomorphized copy of its enclosing generic this candidate belongs
+     * to; empty when it is not inside one.
+     *
+     * A candidate carries this rather than being looked up from its node, because
+     * one node produces one candidate per copy and the node cannot say which of
+     * them is being asked about. Every consumer that needs a type for this
+     * candidate needs the path with it: `T` is `number` in one copy and `string`
+     * in the next, and the node is identical in both.
+     */
+    readonly specialization: SpecializationPath;
+    /**
+     * This candidate's position in its caller's evaluation, counted in the order
+     * the walk reaches it.
+     *
+     * Only the walk knows this. A per-producer counter cannot: producers run
+     * family by family, so its numbers record which family published when, not
+     * which operation runs first. The ordinal orders *siblings*, whose document
+     * order really is their evaluation order; an operation and the operands it
+     * consumes are ordered by the dependency between them, which is stronger
+     * than any ordinal and needs no help from one.
+     *
+     * Operations minted from one candidate share its ordinal, and their relative
+     * order travels on the evaluation edges their producer publishes -- the only
+     * authority that knows an object literal's properties install left to right.
+     */
+    readonly evaluationOrdinal: number;
+}
+export interface ProgramCensus {
+    readonly candidates: readonly CensusCandidate[];
+    readonly regions: ReadonlyMap<string, SemanticRegion>;
+    readonly byFamily: ReadonlyMap<OperationFamily, readonly CensusCandidate[]>;
+}
+/**
+ * Whether an identifier resolves a value out of a scope.
+ *
+ * Exported because it is an authority, not a helper: the census uses it to
+ * decide which identifiers become reference candidates, and `frontend.ts`'s
+ * ambient-host walk uses the same answer to decide which identifiers name a
+ * cell a host owns. Two walks with two rules would disagree exactly on the
+ * awkward cases -- a JSX tag, an import specifier, a property key -- and each
+ * disagreement is a binding one layer thinks exists and the other does not.
+ */
+export declare const isValueReference: (node: ts.Identifier | ts.PrivateIdentifier, paths: NamespacePathCensus) => boolean;
+export declare const familyOf: (node: ts.Node, paths: NamespacePathCensus) => OperationFamily | null;
+/**
+ * Whether this node is a class field's initializer expression.
+ *
+ * `ClassFieldDefinitionRecord`'s initializer is a function whose whole body is
+ * `Return ? Evaluation of the initializer` -- the same implicit return a
+ * concise arrow body performs, for the same reason: the value has to leave the
+ * call, and no `ReturnStatement` exists to census.
+ */
+export declare const isFieldInitializerBody: (node: ts.Node) => boolean;
+/**
+ * Whether this node is a parameter property: `constructor(readonly name: T)`.
+ *
+ * TypeScript's own predicate, not a re-derivation of it -- the modifier set
+ * that makes a parameter also declare a member is the language's rule, and
+ * spelling it a second time here would be a second authority over it.
+ */
+export declare const isParameterProperty: (node: ts.Node) => node is ts.ParameterPropertyDeclaration;
+/**
+ * Every family a node carries, in evaluation order.
+ *
+ * Almost every node carries one. A concise arrow body and a field initializer
+ * carry two -- the expression and the implicit return -- and they stay
+ * distinguishable because identity is keyed by `(node, family, ordinal)`, so
+ * neither can be mistaken for the other by a consumer citing one of them.
+ * Dropping the second is what made an arrow function evaluate its body and
+ * then return nothing.
+ *
+ * A parameter property carries two for a third reason: it IS two declarations
+ * written as one. `constructor(readonly name: string)` declares a formal
+ * parameter -- the `binding` every parameter is -- and an instance member the
+ * constructor assigns that parameter into. The second half is class evaluation,
+ * so it is `class-lifecycle`, and its caller is the constructor the parameter
+ * sits in, which is exactly where the assignment belongs.
+ */
+export declare const familiesOf: (node: ts.Node, paths: NamespacePathCensus) => readonly OperationFamily[];
+export declare const censusProgram: (files: readonly ts.SourceFile[], identities: IdentityTable, reachable: ProgramReachability, specializations: SpecializationCensus, namespacePaths: NamespacePathCensus) => ProgramCensus;