@geastack/compiler 1.0.15

package/dist/targets/cpp/recursive-containers.d.ts

@@ -0,0 +1,43 @@
+import { type Representation } from '../../representation/model.js';
+import type { SealedRepresentationPlan } from '../../representation/plan.js';
+/**
+ * One C++ declaration and definition per recursive structural identity.
+ *
+ * The inner reference already spells `Ref<wrapper>` through `cppTypeOf`, so
+ * the base below is finite even for `type Tree = Map<string, Tree>`. The
+ * wrapper preserves the runtime container's methods and storage; it only gives
+ * C++ the declaration name the recursive equation needs. Every wrapper is
+ * forward-declared before any wrapper is defined, because two independently
+ * selected equations can refer to each other and either sorted definition may
+ * therefore need the other's incomplete type.
+ *
+ * This deliberately renders ONLY the wrapper struct, never the
+ * `gea::detail::TraceEdges` specialisation that goes with it -- see
+ * `cppRecursiveContainerTraceEdges` for why that has to land somewhere else.
+ */
+export declare const cppRecursiveContainerDeclarations: (plan: SealedRepresentationPlan, representations?: readonly Representation[]) => readonly string[];
+/**
+ * The `gea::detail::TraceEdges` specialisation for every recursive wrapper
+ * `cppRecursiveContainerDeclarations` declares, kept as a SEPARATE renderer
+ * rather than appended to that struct text.
+ *
+ * A single-layout translation unit renders every program-owned declaration
+ * inside one unnamed `namespace { ... }` for isolation. Re-opening
+ * `namespace gea::detail { ... }` from INSIDE that block does not reach the
+ * real `::gea::detail` -- it declares a new `(anonymous)::gea`, which then
+ * shadows `::gea` for every unqualified `gea::` written after it in the same
+ * translation unit. The caller (`translation-unit.ts`, exactly like it
+ * already does for `structs.runtimeClassBases`) has to close the isolating
+ * namespace, emit these blocks at global scope, and reopen it -- so this
+ * function hands the caller the specialisation text alone, with no namespace
+ * decision baked in about where the wrapper struct itself lives.
+ *
+ * `qualifier` names how to reach the wrapper struct from the point these
+ * blocks render at (after the isolating namespace has been closed), mirroring
+ * `structs.runtimeClassBases`' own `qualifier`: empty when the struct lives in
+ * an unnamed namespace (its members are visible unqualified at the enclosing
+ * scope through C++'s implicit using-directive) or at true global scope (the
+ * unit tests below), and `"<namespaceName>::"` when the struct lives in the
+ * per-file layout's NAMED program namespace, which has no such directive.
+ */
+export declare const cppRecursiveContainerTraceEdges: (plan: SealedRepresentationPlan, qualifier: string, representations?: readonly Representation[]) => readonly string[];

package/dist/targets/cpp/recursive-containers.js

@@ -0,0 +1,144 @@
+import { recursiveCarrierOf, walkRepresentation } from '../../representation/model.js';
+import { cppAbiType, cppRecursiveContainerName, cppTypeOf } from './types.js';
+/**
+ * The runtime base type of one named recursive-container wrapper.
+ *
+ * Every name is spelled from the GLOBAL scope (`::gea::...`), because these
+ * declarations land inside the translation unit's anonymous namespace and a
+ * `gea::detail::TraceEdges` specialisation used to be rendered right there
+ * too. Re-opening `namespace gea::detail` from inside an anonymous namespace
+ * does not reach the real `::gea::detail` -- it declares a NEW
+ * `(anonymous)::gea`, which then shadows `::gea` for every unqualified
+ * `gea::` written after it in the same namespace. With one recursive
+ * container nothing showed: the shadow was introduced after the only base
+ * had already resolved. With two, the second one's base resolved into the
+ * shadow and clang refused it with "no template named 'CallableObject' in
+ * namespace '(anonymous namespace)::gea'".
+ *
+ * A leading `::` makes the base immune to that regardless. The specialisation
+ * itself no longer lands here at all -- see `cppRecursiveContainerTraceEdges`,
+ * which the caller (`translation-unit.ts`) closes the isolating namespace for,
+ * exactly like it already does for `structs.runtimeClassBases`.
+ */
+const baseTypeOf = (representation) => {
+    switch (representation.kind) {
+        case 'array-object':
+            return `::gea::ArrayObject<${cppTypeOf(representation.element)}>`;
+        case 'keyed-collection': {
+            const template = representation.family === 'map'
+                ? '::gea::Map'
+                : representation.family === 'set'
+                    ? '::gea::Set'
+                    : representation.family === 'weak-map'
+                        ? '::gea::WeakMap'
+                        : '::gea::WeakSet';
+            const key = cppTypeOf(representation.key);
+            return `${template}<${representation.value === null ? key : `${key}, ${cppTypeOf(representation.value)}`}>`;
+        }
+        case 'dictionary': {
+            const template = representation.key === 'number'
+                ? '::gea::NumericDictionary'
+                : representation.key === 'symbol'
+                    ? '::gea::SymbolDictionary'
+                    : '::gea::Dictionary';
+            return `${template}<${cppTypeOf(representation.value)}>`;
+        }
+        case 'function-value-dispatch':
+            return `::gea::CallableObject<${cppAbiType(representation.abi)}>`;
+    }
+};
+/**
+ * The recursive structural identities a plan closes, in the one stable order
+ * both `cppRecursiveContainerDeclarations` and `cppRecursiveContainerTraceEdges`
+ * render from -- computed once so the two renderers can never disagree about
+ * which identities exist or what order they come in.
+ */
+const orderedRecursiveDefinitions = (representations) => {
+    const definitions = new Map();
+    const visited = new Set();
+    for (const representation of representations) {
+        for (const nested of walkRepresentation(representation, visited)) {
+            const recursive = recursiveCarrierOf(nested);
+            if (!recursive || recursive.role !== 'definition')
+                continue;
+            if (nested.kind !== 'array-object' &&
+                nested.kind !== 'keyed-collection' &&
+                nested.kind !== 'dictionary' &&
+                nested.kind !== 'function-value-dispatch') {
+                throw new Error(`recursive native definition ${recursive.type} is not a container or a callable`);
+            }
+            const existing = definitions.get(recursive.type);
+            if (existing && existing !== nested) {
+                throw new Error(`recursive native definition ${recursive.type} was published more than once`);
+            }
+            definitions.set(recursive.type, nested);
+        }
+    }
+    return [...definitions.entries()].sort(([left], [right]) => left.localeCompare(right));
+};
+/**
+ * One C++ declaration and definition per recursive structural identity.
+ *
+ * The inner reference already spells `Ref<wrapper>` through `cppTypeOf`, so
+ * the base below is finite even for `type Tree = Map<string, Tree>`. The
+ * wrapper preserves the runtime container's methods and storage; it only gives
+ * C++ the declaration name the recursive equation needs. Every wrapper is
+ * forward-declared before any wrapper is defined, because two independently
+ * selected equations can refer to each other and either sorted definition may
+ * therefore need the other's incomplete type.
+ *
+ * This deliberately renders ONLY the wrapper struct, never the
+ * `gea::detail::TraceEdges` specialisation that goes with it -- see
+ * `cppRecursiveContainerTraceEdges` for why that has to land somewhere else.
+ */
+export const cppRecursiveContainerDeclarations = (plan, representations = [...plan.selected.values()]) => {
+    const ordered = orderedRecursiveDefinitions(representations);
+    return [
+        ...ordered.map(([type]) => `struct ${cppRecursiveContainerName(type)};`),
+        ...ordered.map(([type, representation]) => {
+            const name = cppRecursiveContainerName(type);
+            const base = baseTypeOf(representation);
+            return [`struct ${name} final : ${base} {`, `  using Base = ${base};`, '  using Base::Base;', '};'].join('\n');
+        })
+    ];
+};
+/**
+ * The `gea::detail::TraceEdges` specialisation for every recursive wrapper
+ * `cppRecursiveContainerDeclarations` declares, kept as a SEPARATE renderer
+ * rather than appended to that struct text.
+ *
+ * A single-layout translation unit renders every program-owned declaration
+ * inside one unnamed `namespace { ... }` for isolation. Re-opening
+ * `namespace gea::detail { ... }` from INSIDE that block does not reach the
+ * real `::gea::detail` -- it declares a new `(anonymous)::gea`, which then
+ * shadows `::gea` for every unqualified `gea::` written after it in the same
+ * translation unit. The caller (`translation-unit.ts`, exactly like it
+ * already does for `structs.runtimeClassBases`) has to close the isolating
+ * namespace, emit these blocks at global scope, and reopen it -- so this
+ * function hands the caller the specialisation text alone, with no namespace
+ * decision baked in about where the wrapper struct itself lives.
+ *
+ * `qualifier` names how to reach the wrapper struct from the point these
+ * blocks render at (after the isolating namespace has been closed), mirroring
+ * `structs.runtimeClassBases`' own `qualifier`: empty when the struct lives in
+ * an unnamed namespace (its members are visible unqualified at the enclosing
+ * scope through C++'s implicit using-directive) or at true global scope (the
+ * unit tests below), and `"<namespaceName>::"` when the struct lives in the
+ * per-file layout's NAMED program namespace, which has no such directive.
+ */
+export const cppRecursiveContainerTraceEdges = (plan, qualifier, representations = [...plan.selected.values()]) => {
+    const ordered = orderedRecursiveDefinitions(representations);
+    return ordered.map(([type]) => {
+        const name = `${qualifier}${cppRecursiveContainerName(type)}`;
+        return [
+            'namespace gea::detail {',
+            `template <> struct TraceEdges<${name}> {`,
+            '  static constexpr bool supported = true;',
+            `  static void visit(const ${name}& value, RefVisitor& visitor) {`,
+            `    traceRefs(static_cast<const ${name}::Base&>(value), visitor);`,
+            '  }',
+            '};',
+            '}'
+        ].join('\n');
+    });
+};

package/dist/targets/cpp/regexp-types.d.ts

@@ -0,0 +1,56 @@
+import type { RegExpDeclarationKind } from '../../representation/policies.js';
+/**
+ * This backend's spelling for each of the three standard regular-expression
+ * shapes, and the only place those three C++ names appear outside the runtime
+ * header itself.
+ *
+ * The carrier is selected in `representation/derive.ts` from a policy, and that
+ * policy carries the spelling rather than the deriver naming one, because
+ * nothing under `src/representation/` may name a C++ type -- it selects
+ * carriers for any backend. `compiler.ts` composes the two: the frontend says
+ * WHICH declaration is `RegExp`, this table says what this target calls it.
+ *
+ * All three are ported from v1 geatsc's `targets/cpp/runtime/regex.h`:
+ *
+ * - `Pattern` is v1's `gea::runtime::regex::Pattern`, name for name.
+ * - `ExecResult` is v1's `ExecResult` (regex.h line 32) -- the TYPED result,
+ *   deliberately not v1's `gea_cpp_value exec(...)`, which is the boxed one.
+ * - `MatchResult` has no v1 counterpart and is stated as new work in the
+ *   report: v1's `match` answers `std::vector<std::string>` with no null case
+ *   and no `index`/`input`, so there was nothing typed to port. It implements
+ *   ES2024 22.1.3.14 `String.prototype.match`, whose two answers
+ *   (`RegExpExec` for a non-global pattern, the list of matched substrings for
+ *   a global one) are exactly why `lib.es5.d.ts` declares `RegExpMatchArray`'s
+ *   `index` and `input` OPTIONAL where `RegExpExecArray`'s are required.
+ */
+export declare const cppRegExpNativeTypes: Readonly<Record<RegExpDeclarationKind, string>>;
+/**
+ * This backend's entry point for `RegExpAlloc` + `RegExpInitialize` (ECMA-262
+ * 22.2.3.1 and 22.2.3.2), which is where 22.2.4.1's three pattern branches all
+ * converge. It is `constructPatternOrThrow` rather than a bare
+ * `gea::makeRef<Pattern>` so 22.2.3.2's flag and source validation runs and an
+ * unknown or repeated flag throws where the language says it throws.
+ *
+ * A constant for the same reason the three type names above are: two emitters
+ * spell this call -- `emit-callable.ts` for the string and Pattern forms and
+ * `emit-prototype-regexp.ts` for the object form -- and a name typed twice is
+ * a name that can be renamed once.
+ */
+export declare const cppConstructPatternEntry = "gea::runtime::regex::constructPatternOrThrow";
+/**
+ * This backend's spelling for the ECMAScript String WRAPPER OBJECT (ECMA-262
+ * 22.1.5, `new String(x)`), kept in this file rather than a file of its own:
+ * it is the identical kind of fact `cppRegExpNativeTypes` above states --
+ * "what this target calls a compiler-owned native layout for a
+ * core-ECMAScript type, selected by a declaration policy that may not name a
+ * C++ type itself" -- for a second such type, not a different concept. Same
+ * composition point too: `compiler.ts` joins `frontend.stringObjectDeclaration`
+ * (WHICH declaration is `String`) with this constant (what this target calls
+ * it), exactly as it joins `frontend.regexpDeclarations` with the table above.
+ *
+ * `gea::runtime::StringObject` is defined in `runtime/gea_runtime.h`,
+ * immediately after `Date` -- same reasoning, same shape: a compiler-owned
+ * native layout for a core-ECMAScript type, not a struct `targets/cpp/records.ts`
+ * lays out.
+ */
+export declare const cppStringObjectNativeType = "gea::runtime::StringObject";

package/dist/targets/cpp/regexp-types.js

@@ -0,0 +1,59 @@
+/**
+ * This backend's spelling for each of the three standard regular-expression
+ * shapes, and the only place those three C++ names appear outside the runtime
+ * header itself.
+ *
+ * The carrier is selected in `representation/derive.ts` from a policy, and that
+ * policy carries the spelling rather than the deriver naming one, because
+ * nothing under `src/representation/` may name a C++ type -- it selects
+ * carriers for any backend. `compiler.ts` composes the two: the frontend says
+ * WHICH declaration is `RegExp`, this table says what this target calls it.
+ *
+ * All three are ported from v1 geatsc's `targets/cpp/runtime/regex.h`:
+ *
+ * - `Pattern` is v1's `gea::runtime::regex::Pattern`, name for name.
+ * - `ExecResult` is v1's `ExecResult` (regex.h line 32) -- the TYPED result,
+ *   deliberately not v1's `gea_cpp_value exec(...)`, which is the boxed one.
+ * - `MatchResult` has no v1 counterpart and is stated as new work in the
+ *   report: v1's `match` answers `std::vector<std::string>` with no null case
+ *   and no `index`/`input`, so there was nothing typed to port. It implements
+ *   ES2024 22.1.3.14 `String.prototype.match`, whose two answers
+ *   (`RegExpExec` for a non-global pattern, the list of matched substrings for
+ *   a global one) are exactly why `lib.es5.d.ts` declares `RegExpMatchArray`'s
+ *   `index` and `input` OPTIONAL where `RegExpExecArray`'s are required.
+ */
+export const cppRegExpNativeTypes = {
+    pattern: 'gea::runtime::regex::Pattern',
+    'exec-result': 'gea::runtime::regex::ExecResult',
+    'match-result': 'gea::runtime::regex::MatchResult'
+};
+/**
+ * This backend's entry point for `RegExpAlloc` + `RegExpInitialize` (ECMA-262
+ * 22.2.3.1 and 22.2.3.2), which is where 22.2.4.1's three pattern branches all
+ * converge. It is `constructPatternOrThrow` rather than a bare
+ * `gea::makeRef<Pattern>` so 22.2.3.2's flag and source validation runs and an
+ * unknown or repeated flag throws where the language says it throws.
+ *
+ * A constant for the same reason the three type names above are: two emitters
+ * spell this call -- `emit-callable.ts` for the string and Pattern forms and
+ * `emit-prototype-regexp.ts` for the object form -- and a name typed twice is
+ * a name that can be renamed once.
+ */
+export const cppConstructPatternEntry = 'gea::runtime::regex::constructPatternOrThrow';
+/**
+ * This backend's spelling for the ECMAScript String WRAPPER OBJECT (ECMA-262
+ * 22.1.5, `new String(x)`), kept in this file rather than a file of its own:
+ * it is the identical kind of fact `cppRegExpNativeTypes` above states --
+ * "what this target calls a compiler-owned native layout for a
+ * core-ECMAScript type, selected by a declaration policy that may not name a
+ * C++ type itself" -- for a second such type, not a different concept. Same
+ * composition point too: `compiler.ts` joins `frontend.stringObjectDeclaration`
+ * (WHICH declaration is `String`) with this constant (what this target calls
+ * it), exactly as it joins `frontend.regexpDeclarations` with the table above.
+ *
+ * `gea::runtime::StringObject` is defined in `runtime/gea_runtime.h`,
+ * immediately after `Date` -- same reasoning, same shape: a compiler-owned
+ * native layout for a core-ECMAScript type, not a struct `targets/cpp/records.ts`
+ * lays out.
+ */
+export const cppStringObjectNativeType = 'gea::runtime::StringObject';

package/dist/targets/cpp/substrate.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The non-negotiable runtime object substrate (architecture.md, "Non-negotiable
+ * runtime object substrate"). These types are the written contract every
+ * native carrier the emitter targets must satisfy: prototype/extensibility/
+ * descriptor behavior, array hole and length semantics, callable and
+ * constructor ABIs, and proxy trap forwarding. This module declares that
+ * contract; it emits no C++ and holds no executable logic. `targets/cpp/*`
+ * designs its type mapping and ownership leases against these shapes instead
+ * of re-deriving the substrate ad hoc at each call site, and the C++ runtime
+ * (`src/targets/cpp/runtime/`, compiled once) is what actually implements it.
+ */
+/** A normalized ECMAScript property key: string or symbol identity, never a raw source token. */
+export type PropertyKeySubstrate = {
+    readonly kind: 'string';
+    readonly value: string;
+} | {
+    readonly kind: 'symbol';
+    readonly id: string;
+};
+/**
+ * [[GetOwnProperty]]/[[DefineOwnProperty]] descriptor shape (ECMA-262 6.2.6).
+ * A data and an accessor descriptor are different variants, not one shape
+ * with optional fields, because a carrier must never synthesize a `get`/`set`
+ * pair for a data property or a `value` for an accessor.
+ */
+export type PropertyDescriptorSubstrate = {
+    readonly kind: 'data';
+    readonly value: unknown;
+    readonly writable: boolean;
+    readonly enumerable: boolean;
+    readonly configurable: boolean;
+} | {
+    readonly kind: 'accessor';
+    readonly get: unknown;
+    readonly set: unknown;
+    readonly enumerable: boolean;
+    readonly configurable: boolean;
+};
+/**
+ * The ordinary internal methods (ECMA-262 10.1). Every native carrier that is
+ * not a fully bespoke exotic object composes this contract instead of
+ * reimplementing get/set/delete/enumeration on its own -- the shared contract
+ * is what lets `[[OwnPropertyKeys]]`/`[[HasProperty]]`/etc. mean one thing
+ * across every carrier a Proxy might wrap.
+ */
+export interface OrdinaryObjectSubstrate {
+    readonly getPrototypeOf: () => OrdinaryObjectSubstrate | null;
+    readonly setPrototypeOf: (prototype: OrdinaryObjectSubstrate | null) => boolean;
+    readonly isExtensible: () => boolean;
+    readonly preventExtensions: () => boolean;
+    readonly getOwnProperty: (key: PropertyKeySubstrate) => PropertyDescriptorSubstrate | null;
+    readonly defineOwnProperty: (key: PropertyKeySubstrate, descriptor: PropertyDescriptorSubstrate) => boolean;
+    readonly hasProperty: (key: PropertyKeySubstrate) => boolean;
+    readonly get: (key: PropertyKeySubstrate, receiver: unknown) => unknown;
+    readonly set: (key: PropertyKeySubstrate, value: unknown, receiver: unknown) => boolean;
+    readonly deleteProperty: (key: PropertyKeySubstrate) => boolean;
+    readonly ownPropertyKeys: () => readonly PropertyKeySubstrate[];
+}
+/**
+ * A slot's presence is a fact separate from its value: a hole and a stored
+ * `undefined` are different observations (`0 in arr`, `Object.keys`, and
+ * iteration all differ), and collapsing this to `ElementCarrier | undefined`
+ * is exactly the shortcut that erases hole semantics.
+ */
+export type ArrayElementSlotSubstrate<ElementCarrier> = {
+    readonly present: true;
+    readonly value: ElementCarrier;
+} | {
+    readonly present: false;
+};
+/**
+ * `ArrayObject<ElementCarrier>`: an exotic object with element presence
+ * separate from element value, an array-index key domain disjoint from
+ * arbitrary string keys, and the `length` define/delete/truncation rules
+ * ECMA-262 10.4.2 assigns only to Array exotic objects. A dense
+ * `std::vector` is one storage choice made *after* these semantics exist,
+ * never a substitute for them.
+ */
+export interface ArrayObjectSubstrate<ElementCarrier> extends OrdinaryObjectSubstrate {
+    readonly length: () => number;
+    /** Defining `length` to a smaller value deletes every own index at or above it, in descending order. */
+    readonly defineLength: (newLength: number) => boolean;
+    readonly getElement: (index: number) => ArrayElementSlotSubstrate<ElementCarrier>;
+    readonly defineElement: (index: number, slot: ArrayElementSlotSubstrate<ElementCarrier>) => boolean;
+    readonly deleteElement: (index: number) => boolean;
+    /** The array-index key domain is exactly the canonical numeric strings 0 .. 2^32-2; nothing outside it may alias an element slot. */
+    readonly isArrayIndexKey: (key: PropertyKeySubstrate) => boolean;
+}
+/** `CallableObject<Abi>`: adds `[[Call]]` while retaining the native argument/result carriers named by `Abi`. */
+export interface CallableObjectSubstrate<Abi> extends OrdinaryObjectSubstrate {
+    readonly call: (thisArgument: unknown, argumentList: Abi) => unknown;
+}
+/** `ConstructorObject<Abi>`: a callable that additionally supports `[[Construct]]` with an explicit `newTarget`. */
+export interface ConstructorObjectSubstrate<Abi> extends CallableObjectSubstrate<Abi> {
+    readonly construct: (argumentList: Abi, newTarget: ConstructorObjectSubstrate<Abi>) => unknown;
+}
+/**
+ * `ProxyObject<TargetCarrier, HandlerCarrier>`: owns exactly the proxy
+ * target, handler, and revoked state -- no more, no less. Every internal
+ * method performs standard trap lookup on `handler`, invokes a found trap
+ * through generic `Call`, enforces the trap's invariants against `target`,
+ * and otherwise forwards to `target`'s own corresponding internal method with
+ * the *original* receiver -- never the proxy, never the handler. Once
+ * `revoked` is true every internal method must throw before any lookup runs.
+ */
+export interface ProxyObjectSubstrate<TargetCarrier extends OrdinaryObjectSubstrate, HandlerCarrier extends OrdinaryObjectSubstrate> extends OrdinaryObjectSubstrate {
+    readonly target: TargetCarrier;
+    readonly handler: HandlerCarrier;
+    readonly revoked: boolean;
+}
+/**
+ * A proxy over a callable target is itself callable: its `[[Call]]` traps
+ * through `handler.apply` and otherwise forwards to `target.call` with the
+ * original `thisArgument` -- never the proxy or the handler as receiver.
+ */
+export interface CallableProxyObjectSubstrate<Abi> extends ProxyObjectSubstrate<CallableObjectSubstrate<Abi>, OrdinaryObjectSubstrate>, CallableObjectSubstrate<Abi> {
+}
+/**
+ * A proxy over a constructor is itself a constructor: its `[[Construct]]`
+ * traps through `handler.construct` and otherwise forwards to
+ * `target.construct` with the original `newTarget` -- never the proxy
+ * substituted in its place.
+ */
+export interface ConstructableProxyObjectSubstrate<Abi> extends ProxyObjectSubstrate<ConstructorObjectSubstrate<Abi>, OrdinaryObjectSubstrate>, ConstructorObjectSubstrate<Abi> {
+}

package/dist/targets/cpp/substrate.js

@@ -0,0 +1,12 @@
+/**
+ * The non-negotiable runtime object substrate (architecture.md, "Non-negotiable
+ * runtime object substrate"). These types are the written contract every
+ * native carrier the emitter targets must satisfy: prototype/extensibility/
+ * descriptor behavior, array hole and length semantics, callable and
+ * constructor ABIs, and proxy trap forwarding. This module declares that
+ * contract; it emits no C++ and holds no executable logic. `targets/cpp/*`
+ * designs its type mapping and ownership leases against these shapes instead
+ * of re-deriving the substrate ad hoc at each call site, and the C++ runtime
+ * (`src/targets/cpp/runtime/`, compiled once) is what actually implements it.
+ */
+export {};