diff --git a/.sfs-deps/effect-cell-types-12.0.0.tgz b/.sfs-deps/effect-cell-types-12.0.0.tgz new file mode 100644 index 000000000..0e1c9dda0 Binary files /dev/null and b/.sfs-deps/effect-cell-types-12.0.0.tgz differ diff --git a/.sfs-deps/effect-gherkin-spec-7.0.1.tgz b/.sfs-deps/effect-gherkin-spec-7.0.1.tgz new file mode 100644 index 000000000..3020c8f45 Binary files /dev/null and b/.sfs-deps/effect-gherkin-spec-7.0.1.tgz differ diff --git a/.sfs-deps/effect-schema-discovery-2.0.0.tgz b/.sfs-deps/effect-schema-discovery-2.0.0.tgz new file mode 100644 index 000000000..7b76271f7 Binary files /dev/null and b/.sfs-deps/effect-schema-discovery-2.0.0.tgz differ diff --git a/.sfs-deps/effect-schema-law-5.0.1.tgz b/.sfs-deps/effect-schema-law-5.0.1.tgz new file mode 100644 index 000000000..9e173c3c2 Binary files /dev/null and b/.sfs-deps/effect-schema-law-5.0.1.tgz differ diff --git a/.sfs-deps/effect-schema-recursion-budget-2.0.0.tgz b/.sfs-deps/effect-schema-recursion-budget-2.0.0.tgz new file mode 100644 index 000000000..9a62a3eff Binary files /dev/null and b/.sfs-deps/effect-schema-recursion-budget-2.0.0.tgz differ diff --git a/.sfs-deps/effect-schema-vite-3.0.1.tgz b/.sfs-deps/effect-schema-vite-3.0.1.tgz new file mode 100644 index 000000000..d3cfb0e43 Binary files /dev/null and b/.sfs-deps/effect-schema-vite-3.0.1.tgz differ diff --git a/.sfs-deps/effect-sim-kernel-1.0.0.tgz b/.sfs-deps/effect-sim-kernel-1.0.0.tgz new file mode 100644 index 000000000..e151c3795 Binary files /dev/null and b/.sfs-deps/effect-sim-kernel-1.0.0.tgz differ diff --git a/.sfs-deps/effect-spec-runtime-1.0.1.tgz b/.sfs-deps/effect-spec-runtime-1.0.1.tgz new file mode 100644 index 000000000..5801d615d Binary files /dev/null and b/.sfs-deps/effect-spec-runtime-1.0.1.tgz differ diff --git a/.sfs-deps/oxlint-config-cell-architecture-4.0.0.tgz b/.sfs-deps/oxlint-config-cell-architecture-4.0.0.tgz new file mode 100644 index 000000000..49e1329e4 Binary files /dev/null and b/.sfs-deps/oxlint-config-cell-architecture-4.0.0.tgz differ diff --git a/.sfs-deps/oxlint-config-dmmf-2.0.0.tgz b/.sfs-deps/oxlint-config-dmmf-2.0.0.tgz new file mode 100644 index 000000000..fc19cd690 Binary files /dev/null and b/.sfs-deps/oxlint-config-dmmf-2.0.0.tgz differ diff --git a/.sfs-deps/oxlint-config-recommended-4.0.0.tgz b/.sfs-deps/oxlint-config-recommended-4.0.0.tgz new file mode 100644 index 000000000..1fd66e1b6 Binary files /dev/null and b/.sfs-deps/oxlint-config-recommended-4.0.0.tgz differ diff --git a/.sfs-deps/oxlint-config-rule-authoring-1.1.0.tgz b/.sfs-deps/oxlint-config-rule-authoring-1.1.0.tgz new file mode 100644 index 000000000..49a9fad7f Binary files /dev/null and b/.sfs-deps/oxlint-config-rule-authoring-1.1.0.tgz differ diff --git a/.sfs-deps/oxlint-plugin-cell-architecture-5.0.0.tgz b/.sfs-deps/oxlint-plugin-cell-architecture-5.0.0.tgz new file mode 100644 index 000000000..f4a08aed2 Binary files /dev/null and b/.sfs-deps/oxlint-plugin-cell-architecture-5.0.0.tgz differ diff --git a/.sfs-deps/oxlint-plugin-dmmf-workflow-7.0.0.tgz b/.sfs-deps/oxlint-plugin-dmmf-workflow-7.0.0.tgz new file mode 100644 index 000000000..91dde059c Binary files /dev/null and b/.sfs-deps/oxlint-plugin-dmmf-workflow-7.0.0.tgz differ diff --git a/.sfs-deps/oxlint-plugin-effect-platform-2.0.0.tgz b/.sfs-deps/oxlint-plugin-effect-platform-2.0.0.tgz new file mode 100644 index 000000000..401b16ee4 Binary files /dev/null and b/.sfs-deps/oxlint-plugin-effect-platform-2.0.0.tgz differ diff --git a/.sfs-deps/oxlint-plugin-effect-schema-6.0.0.tgz b/.sfs-deps/oxlint-plugin-effect-schema-6.0.0.tgz new file mode 100644 index 000000000..7a94722fa Binary files /dev/null and b/.sfs-deps/oxlint-plugin-effect-schema-6.0.0.tgz differ diff --git a/.sfs-deps/oxlint-plugin-test-discipline-5.0.0.tgz b/.sfs-deps/oxlint-plugin-test-discipline-5.0.0.tgz new file mode 100644 index 000000000..45d7192f6 Binary files /dev/null and b/.sfs-deps/oxlint-plugin-test-discipline-5.0.0.tgz differ diff --git a/.sfs-deps/stryker-config-0.1.0.tgz b/.sfs-deps/stryker-config-0.1.0.tgz new file mode 100644 index 000000000..0d3d67368 Binary files /dev/null and b/.sfs-deps/stryker-config-0.1.0.tgz differ diff --git a/.sfs-deps/stryker-framework-interface-0.0.1.tgz b/.sfs-deps/stryker-framework-interface-0.0.1.tgz new file mode 100644 index 000000000..b2e0a52f4 Binary files /dev/null and b/.sfs-deps/stryker-framework-interface-0.0.1.tgz differ diff --git a/.sfs-deps/stryker-ignorer-effect-schema-declarations-0.2.1.tgz b/.sfs-deps/stryker-ignorer-effect-schema-declarations-0.2.1.tgz new file mode 100644 index 000000000..46641527b Binary files /dev/null and b/.sfs-deps/stryker-ignorer-effect-schema-declarations-0.2.1.tgz differ diff --git a/.sfs-deps/stryker-ignorer-in-source-vitest-block-0.1.2.tgz b/.sfs-deps/stryker-ignorer-in-source-vitest-block-0.1.2.tgz new file mode 100644 index 000000000..7837d803c Binary files /dev/null and b/.sfs-deps/stryker-ignorer-in-source-vitest-block-0.1.2.tgz differ diff --git a/.sfs-deps/stryker-ignorer-interface-0.1.2.tgz b/.sfs-deps/stryker-ignorer-interface-0.1.2.tgz new file mode 100644 index 000000000..177cae599 Binary files /dev/null and b/.sfs-deps/stryker-ignorer-interface-0.1.2.tgz differ diff --git a/.sfs-deps/stryker-ignorer-kit-0.1.2.tgz b/.sfs-deps/stryker-ignorer-kit-0.1.2.tgz new file mode 100644 index 000000000..be4ff7d6f Binary files /dev/null and b/.sfs-deps/stryker-ignorer-kit-0.1.2.tgz differ diff --git a/.sfs-deps/stryker-js-18.1.0.tgz b/.sfs-deps/stryker-js-18.1.0.tgz new file mode 100644 index 000000000..5858cd0eb Binary files /dev/null and b/.sfs-deps/stryker-js-18.1.0.tgz differ diff --git a/.sfs-deps/stryker-js-cli-contract-0.4.0.tgz b/.sfs-deps/stryker-js-cli-contract-0.4.0.tgz new file mode 100644 index 000000000..20f0ebdfb Binary files /dev/null and b/.sfs-deps/stryker-js-cli-contract-0.4.0.tgz differ diff --git a/.sfs-deps/stryker-js-instrumenter-12.1.2.tgz b/.sfs-deps/stryker-js-instrumenter-12.1.2.tgz new file mode 100644 index 000000000..51aa8a972 Binary files /dev/null and b/.sfs-deps/stryker-js-instrumenter-12.1.2.tgz differ diff --git a/.sfs-deps/stryker-js-plugin-interface-15.0.0.tgz b/.sfs-deps/stryker-js-plugin-interface-15.0.0.tgz new file mode 100644 index 000000000..728812abf Binary files /dev/null and b/.sfs-deps/stryker-js-plugin-interface-15.0.0.tgz differ diff --git a/.sfs-deps/stryker-js-plugin-runtime-7.0.3.tgz b/.sfs-deps/stryker-js-plugin-runtime-7.0.3.tgz new file mode 100644 index 000000000..98ff8f09e Binary files /dev/null and b/.sfs-deps/stryker-js-plugin-runtime-7.0.3.tgz differ diff --git a/.sfs-deps/stryker-js-typescript-checker-8.3.1.tgz b/.sfs-deps/stryker-js-typescript-checker-8.3.1.tgz new file mode 100644 index 000000000..e556faa1e Binary files /dev/null and b/.sfs-deps/stryker-js-typescript-checker-8.3.1.tgz differ diff --git a/.sfs-deps/stryker-js-vitest-runner-9.0.1.tgz b/.sfs-deps/stryker-js-vitest-runner-9.0.1.tgz new file mode 100644 index 000000000..0aa2f7611 Binary files /dev/null and b/.sfs-deps/stryker-js-vitest-runner-9.0.1.tgz differ diff --git a/.sfs-deps/tsconfig-2.0.1.tgz b/.sfs-deps/tsconfig-2.0.1.tgz new file mode 100644 index 000000000..42bd9c915 Binary files /dev/null and b/.sfs-deps/tsconfig-2.0.1.tgz differ diff --git a/.sfs-deps/tsdown-config-0.1.0.tgz b/.sfs-deps/tsdown-config-0.1.0.tgz new file mode 100644 index 000000000..c82d0f9e4 Binary files /dev/null and b/.sfs-deps/tsdown-config-0.1.0.tgz differ diff --git a/.sfs-deps/vitest-2.0.0.tgz b/.sfs-deps/vitest-2.0.0.tgz new file mode 100644 index 000000000..4a9895be5 Binary files /dev/null and b/.sfs-deps/vitest-2.0.0.tgz differ diff --git a/.sfs-deps/vitest-config-0.1.0.tgz b/.sfs-deps/vitest-config-0.1.0.tgz new file mode 100644 index 000000000..4463d1ec5 Binary files /dev/null and b/.sfs-deps/vitest-config-0.1.0.tgz differ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..17b461fe7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,25 @@ +# Contributing + +## Development setup + +`nix develop` provides the dev shell. nix.systemfsoftware.com is the package registry for `@systemfsoftware` packages: this repository takes them from its flake inputs, pinned to producer commits, and the dev shell copies them into `.deps/`. + +Run the checks through the dev shell: + +```sh +nix develop --command pnpm run bootstrap +nix develop --command pnpm test +nix develop --command pnpm lint +nix develop --command pnpm typecheck +``` + +`bootstrap` installs inside the pnpm-release-management sandbox. + +## Provenance + +This repository is MIT-licensed. The behaviour oracle is `@microsoft/api-extractor` +7.59.1 (`microsoft/rushstack` `apps/api-extractor` at +`bc4cd29cc4984cef267437565bf681582948285e`), whose MIT notice is reproduced in +[`LICENSE`](LICENSE). A file derived from upstream, or from systemfsoftware PR #552, +names its origin (repository, path and commit) in a header comment. No file in the +current tree is derived from either. diff --git a/README.md b/README.md index 702d91867..ef848bb13 100644 --- a/README.md +++ b/README.md @@ -10,16 +10,46 @@ The design and its requirements live in ## Status -| Part | State | -|---|---| -| Versioned model, canonical serialiser, diff, rule corpus and verdict | in this repository | -| Front-ends (isolated-declarations fast path, TypeScript 7 compiler fallback, model builder, analysis messages) | in this repository | -| `.api.md` report with a differential test against `@microsoft/api-extractor` 7.59.1 | planned | -| Benchmark, CLI, changeset-bump check | planned | -| systemfsoftware and stryker-js-effect packages from nix.systemfsoftware.com, copied into `.deps/` by the dev shell | in this repository | -| Lint, typecheck, build and test on systemfsoftware's reusable checks; tsdown, vitest and lint presets | in this repository | -| Releases: changesets and GitHub Releases through pnpm-release-management | in this repository | -| Mutation testing on `main` | waits on systemfsoftware's reusable mutation workflow (#710) | +Shipped in this repository: the versioned model and its canonical serialiser, the diff, the rule corpus and the verdict, and both front-ends (the isolated-declarations fast path and the TypeScript 7 compiler fallback). Planned: an `.api.md` report with a differential test against `@microsoft/api-extractor`, a benchmark, a CLI, and a changeset bump check. + +## Install + +`@systemfsoftware/api-extractor` is not on npm. This repository ships it as a flake output (`release.yml` publishes a git tag and a GitHub Release, and no npm package). A consumer takes the flake as an input and the tarballs through the route in [pnpm-release-management](https://github.com/systemfsoftware/pnpm-release-management#distribution-through-nix); Nix fetches a tarball a producer has pushed to `nix.systemfsoftware.com` and builds the rest from source. + +```nix +{ + nixConfig = { + extra-substituters = "https://nix.systemfsoftware.com"; + extra-trusted-public-keys = "nix-cache-1:wXA8I4DayNW9q6enUyQA/P/nT38pGSTLt374t3gsn7M="; + fallback = true; + }; + inputs = { + nixpkgs.follows = "producer/nixpkgs"; + producer.url = "github:systemfsoftware/api-extractor-effect/"; + pnpm-release-management.url = "github:systemfsoftware/pnpm-release-management"; + }; +} +``` + +```nix +packages = forEachSystem (pkgs: rec { + producer-tarballs = pnpm-release-management.lib.mkProducerTarballs { + inherit pkgs; + producers = { inherit producer; }; + }; + pnpm-store = pnpm-release-management.lib.mkPnpmConsumerStore { + inherit pkgs; + src = self; + files.".deps" = producer-tarballs; + }; +}); +``` + +The package's peer, `effect` 4.x, installs from npm as usual: + +```bash +pnpm add 'effect@^4' +``` ## The verdict @@ -48,7 +78,7 @@ For example, a function returning `Effect` that now returns is minor `E_WIDENED_IN_INPUT`. Removing a tagged error from a returned error channel is major `E_TAG_REMOVED`, because a caller's `catchTag` for that tag stops compiling. -## Front-ends +## Reading a package's API ```ts import { NodeServices } from '@effect/platform-node' @@ -65,116 +95,18 @@ const analysis = await Effect.runPromise( process.stdout.write(ApiModel.serialise(analysis.model)) ``` -`readPackage` takes each export whose `@systemfsoftware/source` condition names a -`.ts`, `.tsx`, `.mts` or `.cts` file, or a hand-written `.d.ts`, `.d.mts` or `.d.cts` -file, as an entry point; `readPackage({ packageRoot, -sourceCondition })` reads another condition instead, for example `types` for a package -whose sources are not under the family's condition. A subpath pattern (`"./*"`, one -star) expands to one entry per matching source under Node's `exports` rules: an explicit -subpath wins over a pattern, and an export path belongs to the pattern key Node picks for -it, so it names no entry when that key's target has no source or is `null`. A key or a -target with two stars names no entry. The condition is read where the family writes it, -directly -under an export path, and its value is the source's path; a target that nests it under -another condition, lists targets in an array, or gives the condition anything but a path -names no entry. A package with no such export is refused with `NoSourceEntry`. -A package whose `package.json` does not decode — invalid JSON, or a manifest the schema -refuses — is refused with `ManifestRejected`, naming the package root. So is a pattern -export whose walk lists more than 1024 directories, which symlinked aliases of a -directory can reach by fanning out. The walk enters only directories the pattern's -prefix can lead to, never a symlink back to an ancestor, and never a `node_modules` -directory no export name could pass through. -A `package.json` -that is missing or cannot be read fails with the file system's `PlatformError`, as every -operation here does on an I/O fault. -`analyse` first emits declarations with `oxc-transform`'s isolated-declarations emitter, -which never type-checks. If any source an entry point reaches needs the checker (an -unannotated export, TS9xxx), or an entry cannot be proven from its own file (its source is -missing, lies outside the package, or shares a declaration path with another entry, or an -import names no file), the package takes the fallback. This package's own TypeScript 7 -`tsc` runs as a process on a config that extends the package's tsconfig with a fixed emit -policy (`FrontEnd.compilerEmitPolicy`), and `route` is `Fallback` with the diagnostics that -sent it there. A `tsc` that fails refuses the package with `CompilerRejected`, whose -diagnostics come from the TypeScript 7 API. Only when the API reports no error (a write -failure, say) does the refusal carry one diagnostic with `tsc`'s exit code and printed -output, which a package's own file names and import specifiers can spell, so a consumer -treats that message as untrusted text. A `Reported` diagnostic is one the compiler -reported, carrying its `TSxxxx` code; a `Note` is a refusal reason no compiler reported, so -it carries no code. Either names a `file` only when that file is inside the package. A -refusal of an entry point names the entry's recorded source, which may lie outside the -package. The fallback runs TypeScript 7's native compiler, which the `typescript` package -installs for the host platform as an optional dependency. Installed without optional -dependencies, or on a platform TypeScript 7 does not ship for, every package that needs -the fallback is refused with `CompilerRejected`, whose one diagnostic carries `tsc`'s -message naming the missing platform package. `oxc-parser` and `oxc-transform` install -their native bindings the same way, but load them when this package is imported, so -without them the import itself fails with `Cannot find native binding`. -Both routes meet at declaration text: one syntactic builder makes the model and one -resolver reports `ae-forgotten-export`, `ae-missing-release-tag`, -`ae-internal-missing-underscore`, `ae-incompatible-release-tags` and -`ae-internal-mixed-release-tag`, so both routes give the same model and messages, apart -from the producer stamp (`producer.declarations`), which names the emitter that ran -(`FrontEnd.OXC_TRANSFORM_PRODUCER` or `FrontEnd.TYPESCRIPT_PRODUCER`). - -The builder refuses a package with `UnsupportedDeclaration`, naming the file and the -construct, when its declarations contain one of these constructs, which model schema -version 2 cannot hold. The compiler fallback refuses the same way when a declaration it -emitted imports a relative path that names no declaration file inside the package. This -is the whole list: - -- a destructuring declaration or parameter, a variable without a type or with an - initialiser that is not a literal, `import x = require(...)`, `export as namespace` - and `export default` of an expression -- an entry point that re-exports a name from another package (`export { it } from 'vitest'`). - The whole package is refused, not just that export. -- an export list naming a name that no declaration holds (`export { present, Missing }` with - no `Missing`), which happens only with declaration text written by hand -- `declare global`, module augmentation (`declare module 'vitest'`) and a dotted - namespace (`declare namespace A.B`) -- `export =` -- an import type that names a module without a member (`typeof import('./x.js')`), and a `typeof` naming a module namespace import -- an enum member whose declared value is computed rather than a literal, for example a - hand-written `.d.ts` with `Write = 1 << 1`, and an enum member declared twice across - merged declarations of one enum. Both emitters write constant members as literals and - `tsc` refuses a repeated member, so these happen only with declaration text written by hand. -- an index signature without a parameter, a computed member or method name other than a - literal, a dotted name or an identifier (`[Symbol.iterator]` and `[sym]` are kept as - written), an enum member named by neither - an identifier nor a string, a heritage clause that is not a name (`extends - mixin(Base)`), a type node the printer has no form for, and text that does not parse as - a declaration file - -One construct is not refused: `export * from 'effect'`, or `export *` from any other -package, adds no items to the model. The names it re-exports are missing from the model, -and a verdict does not see them change. - -The fast-path emitter was chosen from a per-phase profile on systemfsoftware's public -packages, [`docs/profiles/2026-10-12-front-end-phases.md`](docs/profiles/2026-10-12-front-end-phases.md). -To reproduce it, check out systemfsoftware at the commit the profile names, install it -with `pnpm install --frozen-lockfile --ignore-scripts`, and run: - -```sh -nix develop --command pnpm --filter api-extractor-profile profile ../../docs/profiles/-front-end-phases -``` +`readPackage` finds the entry points through the `@systemfsoftware/source` export condition, and `analyse` builds the model. The full entry-point rules, the two front-end routes and every refusal are in [docs/front-ends.md](docs/front-ends.md). -## Development +## Documentation -nix.systemfsoftware.com is the package registry for `@systemfsoftware` packages. This repository -takes them from its flake inputs, pinned to producer commits: the dev shell copies them -into `.deps/`, and `bootstrap` installs inside the pnpm-release-management sandbox: +- [docs/front-ends.md](docs/front-ends.md): reading a package, the fast path and the compiler fallback, and the refusals +- [docs/plans/2026-10-10-1146-feat-effect-api-extractor-plan.md](docs/plans/2026-10-10-1146-feat-effect-api-extractor-plan.md): the design and its requirements +- [CONTRIBUTING.md](CONTRIBUTING.md): development setup, checks and provenance -```sh -nix develop --command pnpm run bootstrap -nix develop --command pnpm test -nix develop --command pnpm lint -nix develop --command pnpm typecheck -``` +## Contributing + +Development setup and checks are in [CONTRIBUTING.md](CONTRIBUTING.md). -## Provenance +## License -This repository is MIT-licensed. The behaviour oracle is `@microsoft/api-extractor` -7.59.1 (`microsoft/rushstack` `apps/api-extractor` at -`bc4cd29cc4984cef267437565bf681582948285e`), whose MIT notice is reproduced in -[`LICENSE`](LICENSE). A file derived from upstream, or from systemfsoftware PR #552, -names its origin (repository, path and commit) in a header comment. No file in the -current tree is derived from either. +MIT. See [LICENSE](LICENSE). The behaviour is checked against `@microsoft/api-extractor` 7.59.1, whose notice is reproduced in the same file. diff --git a/docs/front-ends.md b/docs/front-ends.md new file mode 100644 index 000000000..7c624666e --- /dev/null +++ b/docs/front-ends.md @@ -0,0 +1,111 @@ +# Front-ends + +How a package's declarations become the API model: the entry points, the isolated-declarations fast path, the TypeScript 7 compiler fallback, and the refusals each one can return. + +```ts +import { NodeServices } from '@effect/platform-node' +import { Effect, Layer } from 'effect' +import { ApiModel, FrontEnd } from '@systemfsoftware/api-extractor' + +const emitters = Layer.mergeAll(FrontEnd.isolatedEmitterLayer, FrontEnd.compilerEmitterLayer).pipe( + Layer.provideMerge(NodeServices.layer), +) + +const analysis = await Effect.runPromise( + FrontEnd.readPackage({ packageRoot: 'packages/my-lib' }).pipe(Effect.flatMap(FrontEnd.analyse), Effect.provide(emitters)), +) +process.stdout.write(ApiModel.serialise(analysis.model)) +``` + +`readPackage` takes each export whose `@systemfsoftware/source` condition names a +`.ts`, `.tsx`, `.mts` or `.cts` file, or a hand-written `.d.ts`, `.d.mts` or `.d.cts` +file, as an entry point; `readPackage({ packageRoot, +sourceCondition })` reads another condition instead, for example `types` for a package +whose sources are not under the family's condition. A subpath pattern (`"./*"`, one +star) expands to one entry per matching source under Node's `exports` rules: an explicit +subpath wins over a pattern, and an export path belongs to the pattern key Node picks for +it, so it names no entry when that key's target has no source or is `null`. A key or a +target with two stars names no entry. The condition is read where the family writes it, +directly +under an export path, and its value is the source's path; a target that nests it under +another condition, lists targets in an array, or gives the condition anything but a path +names no entry. A package with no such export is refused with `NoSourceEntry`. +A package whose `package.json` does not decode — invalid JSON, or a manifest the schema +refuses — is refused with `ManifestRejected`, naming the package root. So is a pattern +export whose walk lists more than 1024 directories, which symlinked aliases of a +directory can reach by fanning out. The walk enters only directories the pattern's +prefix can lead to, never a symlink back to an ancestor, and never a `node_modules` +directory no export name could pass through. +A `package.json` +that is missing or cannot be read fails with the file system's `PlatformError`, as every +operation here does on an I/O fault. +`analyse` first emits declarations with `oxc-transform`'s isolated-declarations emitter, +which never type-checks. If any source an entry point reaches needs the checker (an +unannotated export, TS9xxx), or an entry cannot be proven from its own file (its source is +missing, lies outside the package, or shares a declaration path with another entry, or an +import names no file), the package takes the fallback. This package's own TypeScript 7 +`tsc` runs as a process on a config that extends the package's tsconfig with a fixed emit +policy (`FrontEnd.compilerEmitPolicy`), and `route` is `Fallback` with the diagnostics that +sent it there. A `tsc` that fails refuses the package with `CompilerRejected`, whose +diagnostics come from the TypeScript 7 API. Only when the API reports no error (a write +failure, say) does the refusal carry one diagnostic with `tsc`'s exit code and printed +output, which a package's own file names and import specifiers can spell, so a consumer +treats that message as untrusted text. A `Reported` diagnostic is one the compiler +reported, carrying its `TSxxxx` code; a `Note` is a refusal reason no compiler reported, so +it carries no code. Either names a `file` only when that file is inside the package. A +refusal of an entry point names the entry's recorded source, which may lie outside the +package. The fallback runs TypeScript 7's native compiler, which the `typescript` package +installs for the host platform as an optional dependency. Installed without optional +dependencies, or on a platform TypeScript 7 does not ship for, every package that needs +the fallback is refused with `CompilerRejected`, whose one diagnostic carries `tsc`'s +message naming the missing platform package. `oxc-parser` and `oxc-transform` install +their native bindings the same way, but load them when this package is imported, so +without them the import itself fails with `Cannot find native binding`. +Both routes meet at declaration text: one syntactic builder makes the model and one +resolver reports `ae-forgotten-export`, `ae-missing-release-tag`, +`ae-internal-missing-underscore`, `ae-incompatible-release-tags` and +`ae-internal-mixed-release-tag`, so both routes give the same model and messages, apart +from the producer stamp (`producer.declarations`), which names the emitter that ran +(`FrontEnd.OXC_TRANSFORM_PRODUCER` or `FrontEnd.TYPESCRIPT_PRODUCER`). + +The builder refuses a package with `UnsupportedDeclaration`, naming the file and the +construct, when its declarations contain one of these constructs, which model schema +version 2 cannot hold. The compiler fallback refuses the same way when a declaration it +emitted imports a relative path that names no declaration file inside the package. This +is the whole list: + +- a destructuring declaration or parameter, a variable without a type or with an + initialiser that is not a literal, `import x = require(...)`, `export as namespace` + and `export default` of an expression +- an entry point that re-exports a name from another package (`export { it } from 'vitest'`). + The whole package is refused, not just that export. +- an export list naming a name that no declaration holds (`export { present, Missing }` with + no `Missing`), which happens only with declaration text written by hand +- `declare global`, module augmentation (`declare module 'vitest'`) and a dotted + namespace (`declare namespace A.B`) +- `export =` +- an import type that names a module without a member (`typeof import('./x.js')`), and a `typeof` naming a module namespace import +- an enum member whose declared value is computed rather than a literal, for example a + hand-written `.d.ts` with `Write = 1 << 1`, and an enum member declared twice across + merged declarations of one enum. Both emitters write constant members as literals and + `tsc` refuses a repeated member, so these happen only with declaration text written by hand. +- an index signature without a parameter, a computed member or method name other than a + literal, a dotted name or an identifier (`[Symbol.iterator]` and `[sym]` are kept as + written), an enum member named by neither + an identifier nor a string, a heritage clause that is not a name (`extends + mixin(Base)`), a type node the printer has no form for, and text that does not parse as + a declaration file + +One construct is not refused: `export * from 'effect'`, or `export *` from any other +package, adds no items to the model. The names it re-exports are missing from the model, +and a verdict does not see them change. + +The fast-path emitter was chosen from a per-phase profile on systemfsoftware's public +packages, [`docs/profiles/2026-10-12-front-end-phases.md`](profiles/2026-10-12-front-end-phases.md). +To reproduce it, check out systemfsoftware at the commit the profile names, install it +with `pnpm install --frozen-lockfile --ignore-scripts`, and run: + +```sh +nix develop --command pnpm --filter api-extractor-profile profile ../../docs/profiles/-front-end-phases +``` +