@geastack/compiler 1.0.15

package/dist/targets/cpp/translation-unit.d.ts

@@ -0,0 +1,219 @@
+import type { CapabilityCertificate } from '../../ir/certificate.js';
+import type { CapabilityKey } from '../../ir/certify.js';
+import type { SealedRepresentationPlan } from '../../representation/plan.js';
+import { type DeclarationId, type FunctionId, type RegionId, type StructuralTypeId } from '../../identity/ids.js';
+import type { BindingPlacement } from '../../projection/bindings.js';
+import { type ClassLayout, type PhysicalClassLayout } from '../../projection/classes.js';
+import type { StructuralType } from '../../semantics/model/structural-types.js';
+import type { Representation } from '../../representation/model.js';
+import { type IrBody } from '../../ir/model.js';
+import type { RuntimeDefinition } from '../../plugins/model.js';
+import type { HostSpellings } from './host/host-members.js';
+import { type RenderedCppSource } from './document.js';
+import type { ReflectionExposure } from '../../ir/reflection-demand.js';
+import { type PrinterDrift } from './emit-narrowing.js';
+import type { ConversionCensus } from '../../conversion/nodes.js';
+import type { RepresentationDeriver } from '../../representation/derive.js';
+/**
+ * How badly this unit needs internal linkage.
+ *
+ * `'required'` is a resident build's answer: several geatsc units link into one
+ * binary, their per-compilation identities collide, and a unit that cannot be
+ * isolated must be refused rather than silently letting one definition win.
+ *
+ * `'preferred'` is every other program's. A unit that IS the whole program has
+ * nothing to collide with, so isolation is not a correctness question there --
+ * but it is still the right answer, because internal linkage is what lets the
+ * C++ compiler see that a function is never called from anywhere else. Measured
+ * on the comparison suite (2026-09-02, clang 18, 16 core fixtures): geomean vs
+ * native 0.699 without it and 0.729 with, from `binary_trees` 0.207 -> 0.247,
+ * `fibonacci` 0.660 -> 0.789 and `method_calls` 1.232 -> 1.579 -- the thunk and
+ * the `CallableObject` global take a function's address, and an externally
+ * visible address is what stops the inliner cloning it.
+ *
+ * A `'preferred'` unit that cannot be isolated simply is not, which is what
+ * every unit did before this existed.
+ */
+export type CppSymbolIsolation = 'required' | 'preferred' | 'off';
+export interface CppTranslationUnitInput {
+    readonly plan: SealedRepresentationPlan;
+    /** Reachable carrier closure published before certification; absent facts retain the full plan. */
+    readonly emissionRepresentations?: readonly Representation[];
+    readonly reflection?: ReflectionExposure;
+    readonly structuralTypes: ReadonlyMap<StructuralTypeId, StructuralType>;
+    readonly bodies: readonly IrBody[];
+    /** Where each binding cell lives, so a region-owned one becomes a file-scope variable. */
+    readonly placements: ReadonlyMap<DeclarationId, BindingPlacement>;
+    /**
+     * Region cells no surviving operation names, so no variable is defined for
+     * them (`ir/shake.ts`).
+     *
+     * Passed alongside the placements rather than removed from them, because a
+     * placement is where a cell LIVES and every consumer that resolves a
+     * reference asks that map. Filtering it here would turn a cell this unit
+     * simply has no use for into a cell whose reference refuses -- two different
+     * facts, and only one of them is true.
+     */
+    readonly omitGlobals: ReadonlySet<DeclarationId>;
+    /** What each class is made of, so its construction can be rendered as one function. */
+    readonly classes: ReadonlyMap<DeclarationId, ClassLayout>;
+    /** Physical inheritance also covers classes retained only through native field types. */
+    readonly physicalClasses?: ReadonlyMap<DeclarationId, PhysicalClassLayout>;
+    /**
+     * Every host member spelling installed for this compilation -- the backend's
+     * own (`coreHostMembers`) unioned with every plugin's, by `compiler.ts`.
+     *
+     * The union happens once, next to the one that builds `nativeProtocols`, so a
+     * protocol's claim and its spelling are admitted by the same step. Splitting
+     * them would let a program certify against a claim whose template never
+     * arrived, and that failure lands in clang rather than in a refusal.
+     */
+    readonly hosts: HostSpellings;
+    /**
+     * The deriver that produced `plan`, so emission asks the same authority the
+     * plan did rather than re-deriving under default policies.
+     */
+    readonly deriver: RepresentationDeriver;
+    /** The conversion census the lowering named its `convert` nodes from; see `EmitContext.conversions`. */
+    readonly conversions: ConversionCensus;
+    /**
+     * This program's module bodies, in the order ECMA-262 evaluates them
+     * (`FrontendResult.moduleOrder`).
+     *
+     * A module body is called by nothing in the program -- it runs when the
+     * module graph is evaluated -- so without this a rendered unit is a set of
+     * functions no target can start. What it produces is one entry function that
+     * calls them in order; see `entryDefinitionOf`.
+     */
+    /**
+     * C++ the installed hosts require this unit to carry, verbatim
+     * (`PluginCapabilities.runtimeDefinitions`, unioned by `compiler.ts`).
+     *
+     * Each carries its own condition rather than arriving as bare text, so a
+     * definition that belongs only in some units says so itself -- see
+     * `RuntimeDefinition.requires`.
+     */
+    readonly runtimeDefinitions: readonly RuntimeDefinition[];
+    readonly moduleOrder: readonly RegionId[];
+    /**
+     * The C++ name the target starts this program at, or `null` to emit none.
+     *
+     * A name rather than a fixed symbol because it is the TARGET's convention,
+     * not the language's: the gea runtimes call `__gea_top_level` (declared by
+     * `core/gea_app_entry.cpp` and invoked from `Application::init`), and a
+     * resident-app build gives each app its own prefixed entry so several can
+     * link together. A caller that states no name gets no entry, which is right
+     * for a unit that is being inspected rather than linked.
+     */
+    readonly entrySymbol: string | null;
+    /**
+     * Whether this unit is one of several a single binary links, so everything
+     * it defines except the names the caller states must be private to it.
+     *
+     * A resident build compiles one unit per app and links them together
+     * (`simulator/targets/web/build-web.sh`). Every name this file mints is
+     * derived from a declaration identity -- `gea_body_fn_decl_f67_3083`,
+     * `gea_record_type_646`, `gea_global_decl_f65_17_0` -- and those identities
+     * are per-COMPILATION, not per-program: two apps that both import the
+     * framework number its files the same way, so four units collide on hundreds
+     * of names, and the ones that happen to hold different code collide
+     * SILENTLY (one definition wins, and the app that lost calls it).
+     *
+     * The fix is the language's own: an unnamed namespace gives every name in it
+     * internal linkage, so nothing has to be renamed and nothing can be confused
+     * across units. What stays outside is exactly what another unit declares --
+     * the entry symbol, and the definitions the installed hosts require
+     * (`runtimeDefinitions`: the per-resident `drainMicrotasks`, the weak
+     * `gea_cpp_clear_microtasks`, and the prelude function the build named).
+     * `core/packages/core/test/test_gea_resident_app_switch_main.cpp` states that
+     * boundary from the other side, down to which symbol must NOT be anonymous.
+     */
+    readonly isolateSymbols: CppSymbolIsolation;
+    /**
+     * How the program is laid out on disk -- see `CppTranslationUnitLayout`.
+     *
+     * `single` is what every unit was until this existed. `per-file` groups
+     * bodies by the source file that declared them, one C++ unit each, with the
+     * declarations they share in one header and the program's storage, dispatch
+     * members, host-required definitions and entry in one program unit.
+     */
+    readonly layout: CppTranslationUnitLayout;
+    /**
+     * The stem every file of a `per-file` layout is named from: `<stem>.hpp` is
+     * the shared header each unit includes, `<stem>.cpp` the program unit, and
+     * `<stem>.<module>.cpp` one module's bodies. Unused by `single`, whose one
+     * unit the caller names itself.
+     */
+    readonly unitBaseName: string;
+    /** Which file each identity segment names (`FrontendResult.sourceFileNames`), so a module unit can be named after its file. */
+    readonly sourceFileNames: ReadonlyMap<string, string>;
+    /** Declaration identities of the standard well-known symbols used by computed property keys. */
+    readonly wellKnownSymbols: ReadonlyMap<DeclarationId, string>;
+    /** Proof that every obligation the program raised was satisfied. */
+    readonly certificate: CapabilityCertificate;
+}
+/** One thing the emitter refused, naming what it was rendering and the capability it lacked. */
+export interface CppEmissionRefusal {
+    /**
+     * The body, the class whose construction, or the struct whose layout could
+     * not be rendered.
+     *
+     * A struct name is not an identity the rest of the compiler mints, and it is
+     * admitted here anyway because the alternative is worse: a struct is required
+     * by every carrier that names it and authored by none of them, so there is no
+     * single semantic owner to attribute its gap to, and refusing to name one
+     * would leave the only report as an exception escaping the whole compilation.
+     */
+    readonly owner: FunctionId | RegionId | DeclarationId | string;
+    readonly reason: string;
+    /**
+     * The capability the printer lacked, as `createCppEmitBlockedError` named
+     * it -- one of `ir/certify.ts`'s keys since Phase 2.3, so a print-stage
+     * refusal of a certified program is attributable to the demand the
+     * certifier failed to raise. `print:refused` is the residue: a refusal this
+     * module states itself (an unconstructible class, a module body with no
+     * lowering) rather than one a renderer threw.
+     */
+    readonly key: CapabilityKey | 'print:refused';
+}
+/**
+ * How many C++ files one program becomes.
+ *
+ * `single` renders the whole program as one translation unit, which is what
+ * every build consumed until the other layout existed, and stays the default.
+ *
+ * `per-file` renders one unit per SOURCE FILE -- the file that declared a
+ * body, read back off its identity (`fileIdentityOf`, identity/ids.ts) rather
+ * than off any path -- plus a header holding everything those units share and
+ * a program unit holding everything that must exist exactly once. The point
+ * is the build, not the program: a C++ compiler works on one unit at a time,
+ * so a program in one unit compiles on one core and recompiles whole after any
+ * edit, while a program in many compiles in parallel and recompiles the units
+ * that changed. What it costs is linkage: a function another unit may call or
+ * take the address of cannot be `static`, so the inliner no longer sees that
+ * nothing else reaches it. `docs/TRANSLATION-UNITS.md` records both measured.
+ */
+export type CppTranslationUnitLayout = 'single' | 'per-file' | 'balanced';
+/** One file of a rendered program, named and ready to write. */
+export interface CppRenderedUnit {
+    /** `unit` is the `single` layout's one file; the other three are the `per-file` layout's. */
+    readonly role: 'unit' | 'runtime-header' | 'header' | 'program' | 'module';
+    readonly fileName: string;
+    /** For a `module` unit, the source file whose bodies it holds -- display evidence for a reader, decided by nothing. */
+    readonly sourceFile: string | null;
+    readonly sourceFiles?: readonly string[];
+    readonly source: RenderedCppSource;
+}
+export interface CppTranslationUnitResult {
+    /**
+     * The program as one unit -- `single` only. `null` under `per-file`, where
+     * there is no one text that is the program, and whenever any body was
+     * refused: a file missing one body is silently wrong, not partially right.
+     */
+    readonly source: RenderedCppSource | null;
+    /** Every file the layout produced, in the order to write them; empty whenever any body was refused. */
+    readonly units: readonly CppRenderedUnit[];
+    readonly refused: readonly CppEmissionRefusal[];
+    readonly printerDrift: readonly PrinterDrift[];
+}
+export declare const renderTranslationUnit: (input: CppTranslationUnitInput) => CppTranslationUnitResult;