@geastack/compiler 1.0.15

package/dist/semantics/inherited-accessor.d.ts

@@ -0,0 +1,7 @@
+import ts from 'typescript';
+/**
+ * JS assignment inference can publish a subclass Property symbol even when
+ * `this.x = value` invokes an inherited accessor. That symbol describes a
+ * write, not a new own field. Explicit class fields still define own storage.
+ */
+export declare const inheritedAccessorOfAssignment: (checker: ts.TypeChecker, symbol: ts.Symbol) => ts.Symbol | null;

package/dist/semantics/inherited-accessor.js

@@ -0,0 +1,48 @@
+import ts from 'typescript';
+import { heritageClassOrInterfaceOf } from './normalize/flow/model.js';
+/**
+ * JS assignment inference can publish a subclass Property symbol even when
+ * `this.x = value` invokes an inherited accessor. That symbol describes a
+ * write, not a new own field. Explicit class fields still define own storage.
+ */
+export const inheritedAccessorOfAssignment = (checker, symbol) => {
+    const declarations = symbol.declarations;
+    if (!declarations?.length ||
+        !declarations.every((node) => ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken))
+        return null;
+    let owner = declarations[0]?.parent;
+    while (owner && !ts.isClassLike(owner))
+        owner = owner.parent;
+    if (!owner || !ts.isClassLike(owner))
+        return null;
+    const type = checker.getTypeAtLocation(owner);
+    if (!type.isClassOrInterface())
+        return null;
+    const seen = new Set();
+    const find = (base) => {
+        if (seen.has(base))
+            return null;
+        seen.add(base);
+        const property = checker.getPropertyOfType(base, symbol.name);
+        if (property) {
+            if ((property.flags & ts.SymbolFlags.Accessor) !== 0)
+                return property;
+            // An actual intervening data declaration shadows the older accessor.
+            if (!property.declarations?.every((node) => ts.isBinaryExpression(node)))
+                return null;
+        }
+        const declared = heritageClassOrInterfaceOf(base);
+        for (const ancestor of declared === null ? [] : checker.getBaseTypes(declared)) {
+            const found = find(ancestor);
+            if (found)
+                return found;
+        }
+        return null;
+    };
+    for (const base of checker.getBaseTypes(type)) {
+        const found = find(base);
+        if (found)
+            return found;
+    }
+    return null;
+};

package/dist/semantics/interface-families.d.ts

@@ -0,0 +1,70 @@
+import ts from 'typescript';
+import type { DeclarationId } from '../identity/ids.js';
+import type { IdentityTable } from './normalize/identities.js';
+/**
+ * One interface family: the source interfaces an `extends` graph connects.
+ *
+ * `members` is in source order, so the layout `structural.ts` builds from it
+ * lists fields the way the program's own text first declares them; `key` is
+ * the family's stable identity, the id of its first member.
+ */
+export interface InterfaceFamily {
+    readonly key: DeclarationId;
+    readonly members: readonly ts.InterfaceDeclaration[];
+}
+export interface InterfaceFamilyCensus {
+    /** The family an interface declaration (by its canonical declaration id) belongs to, or `null` for a lone one. */
+    readonly familyOf: (declaration: DeclarationId) => InterfaceFamily | null;
+    readonly families: readonly InterfaceFamily[];
+}
+export declare const emptyInterfaceFamilyCensus: InterfaceFamilyCensus;
+/**
+ * The interfaces this program's `extends` edges connect, so that every view
+ * of one object is ONE layout.
+ *
+ * JavaScript has no interfaces, and a program full of them still allocates
+ * one kind of thing: tsc's `Node` is 300 interfaces -- `Statement`,
+ * `Expression`, `Identifier`, `SourceFile`, ... -- every one of them a VIEW
+ * of the same object `function Node(kind, pos, end)` allocated, written
+ * through `as Mutable<Identifier>` casts and read back through `Statement`
+ * parameters. Laying each interface out as its own struct gives one object
+ * 300 incompatible C++ types, and the program's every `Identifier -> Node`
+ * assignment becomes a conversion nothing can install: a copy would break
+ * identity (`a === b`, a later write through the other view) and a
+ * reinterpretation is not a conversion at all. On the tsc self-compile that
+ * was the single largest family in the census after monomorphization landed:
+ * 1,757 `native-record-ref -> native-record-ref` binding reads plus their
+ * return, optional and union forms.
+ *
+ * So the layout follows the OBJECT, not the view: every interface a family
+ * connects derives to one struct holding the union of the family's fields,
+ * with a field required only where every member declares it required and
+ * carried behind a presence bit otherwise -- exactly what an object of that
+ * family may or may not own at runtime. The layout itself is built by
+ * `structural.ts` (`familyBodyOf`), where the member types can be interned;
+ * this census only answers WHICH declarations are one family.
+ *
+ * What is NOT a member, and why each exclusion is the rule rather than a
+ * gap:
+ *
+ * - An interface in a declaration file. Its layout is a host protocol's, and
+ *   the host owns it.
+ * - An interface extending anything that is not itself a member candidate --
+ *   `Array<T>` (`arrayHeritageShapeOf` lays that out as an array), a class,
+ *   a type alias, an ambient interface. Its layout includes the base's
+ *   members, which the family cannot own, and so do its descendants': the
+ *   taint follows `extends` downward.
+ * - An interface with a call or construct signature (a callable, laid out as
+ *   one), an index signature (a dictionary) or an accessor member (a body,
+ *   not storage).
+ * - A generic interface whose type parameter has no constraint that names a
+ *   type: the family's field for `value: T` would have to be `unknown`, and
+ *   a boxed slot in every object of the family is the defect this compiler
+ *   exists to avoid. A constrained one (`Token<TKind extends SyntaxKind>`)
+ *   is fine: its field is the constraint, which is what the union over every
+ *   instantiation is anyway (`structural.ts`'s type-parameter fallback).
+ *
+ * A family of ONE is no family: its single member keeps the body its own
+ * declaration states, exactly as before this census existed.
+ */
+export declare const interfaceFamiliesOf: (checker: ts.TypeChecker, identities: IdentityTable, files: readonly ts.SourceFile[]) => InterfaceFamilyCensus;

package/dist/semantics/interface-families.js

@@ -0,0 +1,180 @@
+import ts from 'typescript';
+export const emptyInterfaceFamilyCensus = { familyOf: () => null, families: [] };
+/**
+ * The interfaces this program's `extends` edges connect, so that every view
+ * of one object is ONE layout.
+ *
+ * JavaScript has no interfaces, and a program full of them still allocates
+ * one kind of thing: tsc's `Node` is 300 interfaces -- `Statement`,
+ * `Expression`, `Identifier`, `SourceFile`, ... -- every one of them a VIEW
+ * of the same object `function Node(kind, pos, end)` allocated, written
+ * through `as Mutable<Identifier>` casts and read back through `Statement`
+ * parameters. Laying each interface out as its own struct gives one object
+ * 300 incompatible C++ types, and the program's every `Identifier -> Node`
+ * assignment becomes a conversion nothing can install: a copy would break
+ * identity (`a === b`, a later write through the other view) and a
+ * reinterpretation is not a conversion at all. On the tsc self-compile that
+ * was the single largest family in the census after monomorphization landed:
+ * 1,757 `native-record-ref -> native-record-ref` binding reads plus their
+ * return, optional and union forms.
+ *
+ * So the layout follows the OBJECT, not the view: every interface a family
+ * connects derives to one struct holding the union of the family's fields,
+ * with a field required only where every member declares it required and
+ * carried behind a presence bit otherwise -- exactly what an object of that
+ * family may or may not own at runtime. The layout itself is built by
+ * `structural.ts` (`familyBodyOf`), where the member types can be interned;
+ * this census only answers WHICH declarations are one family.
+ *
+ * What is NOT a member, and why each exclusion is the rule rather than a
+ * gap:
+ *
+ * - An interface in a declaration file. Its layout is a host protocol's, and
+ *   the host owns it.
+ * - An interface extending anything that is not itself a member candidate --
+ *   `Array<T>` (`arrayHeritageShapeOf` lays that out as an array), a class,
+ *   a type alias, an ambient interface. Its layout includes the base's
+ *   members, which the family cannot own, and so do its descendants': the
+ *   taint follows `extends` downward.
+ * - An interface with a call or construct signature (a callable, laid out as
+ *   one), an index signature (a dictionary) or an accessor member (a body,
+ *   not storage).
+ * - A generic interface whose type parameter has no constraint that names a
+ *   type: the family's field for `value: T` would have to be `unknown`, and
+ *   a boxed slot in every object of the family is the defect this compiler
+ *   exists to avoid. A constrained one (`Token<TKind extends SyntaxKind>`)
+ *   is fine: its field is the constraint, which is what the union over every
+ *   instantiation is anyway (`structural.ts`'s type-parameter fallback).
+ *
+ * A family of ONE is no family: its single member keeps the body its own
+ * declaration states, exactly as before this census existed.
+ */
+export const interfaceFamiliesOf = (checker, identities, files) => {
+    const candidates = new Map();
+    /** The canonical declaration an interface symbol is known by -- merged declarations share it. */
+    const canonicalOf = (symbol) => {
+        const target = (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+        const declaration = identities.declarationOfSymbol(target);
+        if (!declaration || !ts.isInterfaceDeclaration(declaration))
+            return null;
+        // A source interface merged with an ambient one (`interface Node` beside
+        // lib.dom's) is the ambient one's: the host owns that layout.
+        if ((target.declarations ?? []).some((one) => one.getSourceFile().isDeclarationFile))
+            return null;
+        return { id: identities.declarationIdOf(declaration), declaration };
+    };
+    const unconstrainedParameter = (declaration) => (declaration.typeParameters ?? []).some((parameter) => {
+        const symbol = checker.getSymbolAtLocation(parameter.name);
+        const type = symbol ? checker.getDeclaredTypeOfSymbol(symbol) : null;
+        const constraint = type ? checker.getBaseConstraintOfType(type) : undefined;
+        return constraint === undefined || (constraint.flags & (ts.TypeFlags.Unknown | ts.TypeFlags.Any)) !== 0;
+    });
+    const declaresAnAccessor = (symbol) => (symbol.declarations ?? []).some((declaration) => ts.isInterfaceDeclaration(declaration) &&
+        declaration.members.some((member) => ts.isGetAccessorDeclaration(member) || ts.isSetAccessorDeclaration(member)));
+    for (const file of files) {
+        if (file.isDeclarationFile)
+            continue;
+        const visit = (node) => {
+            if (ts.isInterfaceDeclaration(node)) {
+                const symbol = checker.getSymbolAtLocation(node.name);
+                const canonical = symbol ? canonicalOf(symbol) : null;
+                if (symbol && canonical && !candidates.has(canonical.id)) {
+                    const type = checker.getDeclaredTypeOfSymbol(symbol);
+                    const plain = type.getCallSignatures().length === 0 &&
+                        type.getConstructSignatures().length === 0 &&
+                        checker.getIndexInfosOfType(type).length === 0 &&
+                        !declaresAnAccessor(symbol) &&
+                        !unconstrainedParameter(canonical.declaration);
+                    if (plain)
+                        candidates.set(canonical.id, { id: canonical.id, declaration: canonical.declaration, type });
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(file);
+    }
+    // The `extends` edges, as the checker resolves them: `getBaseTypes` covers
+    // every merged declaration and every instantiated base
+    // (`EndOfFileToken extends Token<SyntaxKind.EndOfFileToken>` reaches
+    // `Token`), and a base that is not a candidate taints the whole subtree.
+    const bases = new Map();
+    const tainted = new Set();
+    for (const candidate of candidates.values()) {
+        const resolved = [];
+        for (const base of candidate.type.isClassOrInterface() ? checker.getBaseTypes(candidate.type) : []) {
+            const symbol = base.getSymbol();
+            const canonical = symbol ? canonicalOf(symbol) : null;
+            if (canonical && candidates.has(canonical.id))
+                resolved.push(canonical.id);
+            else
+                tainted.add(candidate.id);
+        }
+        bases.set(candidate.id, resolved);
+    }
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const [id, own] of bases) {
+            if (tainted.has(id) || !own.some((base) => tainted.has(base)))
+                continue;
+            tainted.add(id);
+            grew = true;
+        }
+    }
+    // Union-find over the untainted edges.
+    const parent = new Map();
+    const find = (id) => {
+        const up = parent.get(id) ?? id;
+        if (up === id)
+            return id;
+        const root = find(up);
+        parent.set(id, root);
+        return root;
+    };
+    const unite = (left, right) => {
+        const a = find(left);
+        const b = find(right);
+        if (a !== b)
+            parent.set(a, b);
+    };
+    for (const [id, own] of bases) {
+        if (tainted.has(id))
+            continue;
+        for (const base of own)
+            unite(id, base);
+    }
+    const groups = new Map();
+    for (const candidate of candidates.values()) {
+        if (tainted.has(candidate.id))
+            continue;
+        const root = find(candidate.id);
+        const group = groups.get(root);
+        if (group)
+            group.push(candidate.declaration);
+        else
+            groups.set(root, [candidate.declaration]);
+    }
+    const byPosition = (left, right) => {
+        const leftFile = left.getSourceFile().fileName;
+        const rightFile = right.getSourceFile().fileName;
+        if (leftFile !== rightFile)
+            return leftFile < rightFile ? -1 : 1;
+        return left.pos - right.pos;
+    };
+    const families = [];
+    const familyOfDeclaration = new Map();
+    for (const group of groups.values()) {
+        if (group.length < 2)
+            continue;
+        const members = [...group].sort(byPosition);
+        const first = members[0];
+        if (!first)
+            continue;
+        const family = { key: identities.declarationIdOf(first), members };
+        families.push(family);
+        for (const member of members)
+            familyOfDeclaration.set(identities.declarationIdOf(member), family);
+    }
+    families.sort((left, right) => (left.key < right.key ? -1 : left.key > right.key ? 1 : 0));
+    return { familyOf: (declaration) => familyOfDeclaration.get(declaration) ?? null, families };
+};

package/dist/semantics/interface-implementors.d.ts

@@ -0,0 +1,53 @@
+import ts from 'typescript';
+import type { DeclarationId } from '../identity/ids.js';
+import type { IdentityTable } from './normalize/identities.js';
+/**
+ * Every class that `implements` an interface, for an interface at least one
+ * class in the program implements.
+ *
+ * JavaScript has no interfaces. An `interface` states what may be READ out of
+ * a slot; nothing ever constructs one, so nothing is ever *of* that type -- a
+ * slot typed by an interface holds whatever object the program put there. When
+ * the program declares which classes are that interface's implementations,
+ * those classes are the only objects any such slot can hold, and the slot's
+ * storage is therefore ONE of them: the class itself when there is one, the
+ * tagged sum of them when there are several.
+ *
+ * Carrying the interface instead is not merely wide, it is WRONG in a way no
+ * amount of boxing fixes: a class's methods are free functions taking the
+ * instance, not storage, while an interface's method members are storage. So
+ * the interface's struct has `gea::CallableObject` members nothing can fill,
+ * the class instance does not assign into it, and -- worst -- a call written
+ * `slot.method(...)` never reaches the class's method at all, so the census
+ * never walks it and NO BODY IS EMITTED. hono is the measured case:
+ * `HonoBase.router` is a `Router<[H, RouterRoute]>` and `PatternRouter` is the
+ * only implementation `hono/tiny` contains; carried as the interface, the
+ * emitted program had no `add` and no `match` anywhere in it. The full `hono`
+ * entry holds a `SmartRouter` over a `RegExpRouter` and a `TrieRouter` -- three
+ * implementations of the one interface -- and the same slot is then a real
+ * sum with real dispatch. A union of class carriers already dispatches a
+ * member call per arm (`test/runtime/class-union-slot-method-dispatch.ts`),
+ * so the sum is the honest carrier rather than a refusal.
+ *
+ * ## What it refuses, and why each refusal is the whole point
+ *
+ * - An interface implemented by no class. There is nothing to answer with.
+ * - An interface with no METHOD member. A pure data interface is a shape an
+ *   object literal satisfies as readily as a class does, and this rule's
+ *   premise -- that only the classes can inhabit it -- does not hold there.
+ *   `Router` declares `add` and `match`, which is what makes it a behaviour
+ *   rather than a record.
+ * - A class whose `implements` clause this cannot resolve to exactly one
+ *   interface declaration.
+ *
+ * The `implements` clause is read SYNTACTICALLY, unlike `classHeritageOf`'s
+ * checker-answered `extends` walk, and deliberately: this states what the
+ * AUTHOR declared to be the implementations of a named contract. Structural
+ * satisfaction is a different question with a different answer (every object
+ * literal of the right shape satisfies `Router`), and answering it here would
+ * make the rule fire on data interfaces it must not touch.
+ *
+ * Classes are listed in source order, first file first, so the sum's arm
+ * order -- and with it the emitted output -- is a function of the program.
+ */
+export declare const interfaceImplementorsOf: (checker: ts.TypeChecker, identities: IdentityTable, files: readonly ts.SourceFile[]) => ReadonlyMap<DeclarationId, readonly DeclarationId[]>;

package/dist/semantics/interface-implementors.js

@@ -0,0 +1,87 @@
+import ts from 'typescript';
+/**
+ * Every class that `implements` an interface, for an interface at least one
+ * class in the program implements.
+ *
+ * JavaScript has no interfaces. An `interface` states what may be READ out of
+ * a slot; nothing ever constructs one, so nothing is ever *of* that type -- a
+ * slot typed by an interface holds whatever object the program put there. When
+ * the program declares which classes are that interface's implementations,
+ * those classes are the only objects any such slot can hold, and the slot's
+ * storage is therefore ONE of them: the class itself when there is one, the
+ * tagged sum of them when there are several.
+ *
+ * Carrying the interface instead is not merely wide, it is WRONG in a way no
+ * amount of boxing fixes: a class's methods are free functions taking the
+ * instance, not storage, while an interface's method members are storage. So
+ * the interface's struct has `gea::CallableObject` members nothing can fill,
+ * the class instance does not assign into it, and -- worst -- a call written
+ * `slot.method(...)` never reaches the class's method at all, so the census
+ * never walks it and NO BODY IS EMITTED. hono is the measured case:
+ * `HonoBase.router` is a `Router<[H, RouterRoute]>` and `PatternRouter` is the
+ * only implementation `hono/tiny` contains; carried as the interface, the
+ * emitted program had no `add` and no `match` anywhere in it. The full `hono`
+ * entry holds a `SmartRouter` over a `RegExpRouter` and a `TrieRouter` -- three
+ * implementations of the one interface -- and the same slot is then a real
+ * sum with real dispatch. A union of class carriers already dispatches a
+ * member call per arm (`test/runtime/class-union-slot-method-dispatch.ts`),
+ * so the sum is the honest carrier rather than a refusal.
+ *
+ * ## What it refuses, and why each refusal is the whole point
+ *
+ * - An interface implemented by no class. There is nothing to answer with.
+ * - An interface with no METHOD member. A pure data interface is a shape an
+ *   object literal satisfies as readily as a class does, and this rule's
+ *   premise -- that only the classes can inhabit it -- does not hold there.
+ *   `Router` declares `add` and `match`, which is what makes it a behaviour
+ *   rather than a record.
+ * - A class whose `implements` clause this cannot resolve to exactly one
+ *   interface declaration.
+ *
+ * The `implements` clause is read SYNTACTICALLY, unlike `classHeritageOf`'s
+ * checker-answered `extends` walk, and deliberately: this states what the
+ * AUTHOR declared to be the implementations of a named contract. Structural
+ * satisfaction is a different question with a different answer (every object
+ * literal of the right shape satisfies `Router`), and answering it here would
+ * make the rule fire on data interfaces it must not touch.
+ *
+ * Classes are listed in source order, first file first, so the sum's arm
+ * order -- and with it the emitted output -- is a function of the program.
+ */
+export const interfaceImplementorsOf = (checker, identities, files) => {
+    const claims = new Map();
+    const interfaceOf = (node) => {
+        const symbol = checker.getSymbolAtLocation(ts.isIdentifier(node.expression) ? node.expression : node);
+        const target = symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
+        const declarations = target?.declarations;
+        const sole = declarations && declarations.length === 1 ? declarations[0] : undefined;
+        if (!sole || !ts.isInterfaceDeclaration(sole))
+            return null;
+        return { id: identities.declarationIdOf(sole), declaration: sole };
+    };
+    const declaresAMethod = (declaration) => declaration.members.some((member) => ts.isMethodSignature(member));
+    for (const file of files) {
+        const visit = (node) => {
+            if (ts.isClassLike(node)) {
+                for (const clause of node.heritageClauses ?? []) {
+                    if (clause.token !== ts.SyntaxKind.ImplementsKeyword)
+                        continue;
+                    for (const typeNode of clause.types) {
+                        const resolved = interfaceOf(typeNode);
+                        if (!resolved || !declaresAMethod(resolved.declaration))
+                            continue;
+                        const claimed = identities.declarationIdOf(node);
+                        const existing = claims.get(resolved.id);
+                        if (existing === undefined)
+                            claims.set(resolved.id, [claimed]);
+                        else if (!existing.includes(claimed))
+                            existing.push(claimed);
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(file);
+    }
+    return claims;
+};

package/dist/semantics/jsdoc-namepath-transform.d.ts

@@ -0,0 +1,4 @@
+export declare const jsdocNamepathTransform: (input: {
+    readonly fileName: string;
+    readonly text: string;
+}) => string | null;

package/dist/semantics/jsdoc-namepath-transform.js

@@ -0,0 +1,85 @@
+import ts from 'typescript';
+import { documentationRangesIn } from './documentation-ranges.js';
+/**
+ * JSDoc namepaths (`WebGLRenderer~Options`), respelled as legal identifiers.
+ *
+ * JSDoc's own grammar scopes a name to its owner with `~` for an inner
+ * declaration, `#` for an instance member and `.` for a static one. three
+ * writes its configuration objects that way:
+ *
+ * ```js
+ * /** @typedef {Object} WebGLRenderer~Options
+ *  *  @property {DOMElement} [canvas]
+ *  *  @property {boolean} [antialias] ... *\/
+ *
+ * /** @param {WebGLRenderer~Options} [parameters] *\/
+ * constructor( parameters = {} ) { ... }
+ * ```
+ *
+ * TypeScript has no `~` in a type name. It reads the `@typedef` name as far as
+ * `WebGLRenderer` and stops, and the `@param` reference resolves to nothing --
+ * which is `any`. So a type the library *did* state is lost twice over, and
+ * `WebGLRenderer`'s entire configuration -- `canvas`, `context`, and every
+ * flag -- arrives untyped.
+ *
+ * `~` is not meaning, it is punctuation: the namepath denotes exactly one
+ * declaration and nothing about the program depends on how it is spelled.
+ * Rewriting it to `_` before the checker parses the file gives that
+ * declaration a name TypeScript can bind, and the existing `@typedef`/`@param`
+ * machinery does the rest unmodified. This is the same shape of fix as
+ * `definePropertySourceTransform`: state, in a spelling the checker already
+ * understands, a fact the source had stated in one it does not.
+ *
+ * ## Why the rewrite is confined to JSDoc comments
+ *
+ * `~` is bitwise NOT. `a~b` is not valid expression syntax, but `x = ~y` is
+ * everywhere, and a rewrite that ran over source text would corrupt it. Only
+ * ranges the parser itself reports as `/**` comments are touched, so code --
+ * and ordinary `//` and `/* *\/` comments -- are left exactly as written.
+ *
+ * ## What is deliberately left alone
+ *
+ * Only `~` is respelled. JSDoc's `#` and `.` separators are not: `.` is
+ * already legal in a TypeScript qualified name and means something there, and
+ * a `#` name would collide with private-field syntax. Neither appears in a
+ * namepath this compiler has needed, and respelling a separator that already
+ * has a meaning would be a change of meaning rather than of spelling.
+ *
+ * A collision is possible in principle -- a file could declare both
+ * `A~B` and `A_B` -- and is not guarded, because the respelled name would then
+ * be a duplicate declaration the checker reports, not a silently wrong answer.
+ */
+const NAMEPATH = /\b([A-Za-z_$][A-Za-z0-9_$]*)~([A-Za-z_$][A-Za-z0-9_$]*)\b/g;
+const scriptKindOf = (fileName) => fileName.endsWith('.tsx')
+    ? ts.ScriptKind.TSX
+    : fileName.endsWith('.jsx')
+        ? ts.ScriptKind.JSX
+        : fileName.endsWith('.js') || fileName.endsWith('.mjs') || fileName.endsWith('.cjs')
+            ? ts.ScriptKind.JS
+            : ts.ScriptKind.TS;
+export const jsdocNamepathTransform = (input) => {
+    // A declaration file states its types directly; there is no namepath to
+    // rescue, and rewriting one would change a name the program may refer to.
+    if (input.fileName.endsWith('.d.ts'))
+        return null;
+    // One character test is what a file with no namepath in it costs.
+    if (!input.text.includes('~'))
+        return null;
+    const file = ts.createSourceFile(input.fileName, input.text, ts.ScriptTarget.Latest, true, scriptKindOf(input.fileName));
+    const ranges = documentationRangesIn(file, input.text);
+    if (ranges.length === 0)
+        return null;
+    let rewritten = input.text;
+    let changed = false;
+    // Spliced from the end so every earlier range is still the range it was
+    // measured at, exactly as `definePropertySourceTransform` does.
+    for (const range of [...ranges].reverse()) {
+        const comment = input.text.slice(range.pos, range.end);
+        const respelled = comment.replace(NAMEPATH, '$1_$2');
+        if (respelled === comment)
+            continue;
+        changed = true;
+        rewritten = rewritten.slice(0, range.pos) + respelled + rewritten.slice(range.end);
+    }
+    return changed ? rewritten : null;
+};

package/dist/semantics/model/coverage.d.ts

@@ -0,0 +1,68 @@
+import type { NodeId, OperationFamily, OperationId } from '../../identity/ids.js';
+/**
+ * Per-family coverage.
+ *
+ * An empty complete family and a family that was never installed are different
+ * states, and conflating them is how a missing producer reads as "nothing to
+ * do". A consumer may read a family only when its coverage is `complete`; a
+ * `partial` family has published authoritative components but has not finished
+ * its census, and `not-installed` has published nothing at all.
+ */
+export type FamilyCoverage = 'complete' | 'partial' | 'not-installed';
+/**
+ * A censused candidate that did not become a graph operation.
+ *
+ * The census is what makes "not installed" measurable. Every source site that
+ * belongs to a family is either an operation or a blocker with a stated reason;
+ * a site that is neither has been silently dropped.
+ */
+export interface CensusBlocker {
+    readonly source: NodeId;
+    readonly family: OperationFamily;
+    /** Why this candidate could not be normalized. Stated as a missing capability. */
+    readonly reason: string;
+    /** The primitive family whose absence blocks it, when one is identified. */
+    readonly missingPrimitive: PrimitiveFamily | null;
+}
+/**
+ * The reusable primitive families. Every supported behavior reduces to one of
+ * these; a proposed behavior that fits none of them is not yet designed.
+ */
+export declare const primitiveFamilies: readonly ["P0", "P1", "P2", "P3", "P4", "P5", "P6", "H0"];
+export type PrimitiveFamily = (typeof primitiveFamilies)[number];
+/**
+ * The dependency order between primitive families.
+ *
+ * A family may only be built on families it depends on. P6 does not depend on
+ * P5: ordinary construction must work before Proxy reuses it, and inverting
+ * that is how proxies end up with a private construction path.
+ */
+export declare const primitiveDependencies: Readonly<Record<PrimitiveFamily, readonly PrimitiveFamily[]>>;
+/** What one family published, and what it could not. */
+export interface FamilyReport {
+    readonly family: OperationFamily;
+    readonly coverage: FamilyCoverage;
+    readonly operations: readonly OperationId[];
+    readonly blockers: readonly CensusBlocker[];
+    /** Candidates that contributed at least one operation. */
+    readonly publishedCandidates: number;
+    /** Every candidate the census found, whether or not it became an operation. */
+    readonly censusedCandidates: number;
+}
+/**
+ * Fail closed when a consumer reads a family that has not finished.
+ *
+ * The throw is the point: a consumer that treats `partial` as `complete` will
+ * quietly compile a program whose missing operations were never lowered.
+ */
+export declare const requireCompleteFamily: (report: FamilyReport, consumer: string) => void;
+/**
+ * A family is internally consistent when every candidate it censused either
+ * published or is a stated blocker.
+ *
+ * The count is of CANDIDATES, not operations. One candidate can mint several
+ * operations -- a compound assignment is a get, a computation and a set -- so
+ * balancing operations against candidates would be a check that passes by
+ * construction and proves nothing.
+ */
+export declare const validateFamilyReport: (report: FamilyReport) => void;