From 6ec64a0235d6fd241105495cc92d1983da797ed0 Mon Sep 17 00:00:00 2001 From: systemfsoftware-maker <248545757+systemfsoftware-maker@users.noreply.github.com> Date: Wed, 11 Nov 2026 15:01:21 +0000 Subject: [PATCH 1/2] docs: rewrite the README for a reader deciding whether to use the package The README now leads with a real verdict (two package versions in, canonical JSON out), then install through the flake, the verdict, the status and a user FAQ. The front-end detail moves to docs/front-ends.md, and the development setup, profile reproduction and provenance move to CONTRIBUTING.md. Claims were checked against the source, the manifests and a run of the example. --- CONTRIBUTING.md | 33 +++++ README.md | 320 ++++++++++++++++++++++++--------------------- docs/front-ends.md | 110 ++++++++++++++++ 3 files changed, 311 insertions(+), 152 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/front-ends.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..370e8220e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,33 @@ +# 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. + +## Reproducing the front-end profile + +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 +``` + +## 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..3ad748a8b 100644 --- a/README.md +++ b/README.md @@ -1,180 +1,196 @@ # api-extractor-effect -`@systemfsoftware/api-extractor` is a public-API tool for Effect-heavy TypeScript -libraries. It reduces a package to one versioned JSON API model, diffs two models, -and gives a semver verdict that understands Effect's `A`/`E`/`R` channels and dual -APIs. Every output is byte-identical across locales, time zones and hosts. +[![CI](https://img.shields.io/github/actions/workflow/status/systemfsoftware/api-extractor-effect/ci.yml?branch=main&label=CI)](https://github.com/systemfsoftware/api-extractor-effect/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE) -The design and its requirements live in -[`docs/plans/2026-10-10-1146-feat-effect-api-extractor-plan.md`](docs/plans/2026-10-10-1146-feat-effect-api-extractor-plan.md). +`@systemfsoftware/api-extractor` reads a TypeScript package's public API, compares two versions of it, and tells you the semver bump the change needs. It understands Effect: adding a tagged error to the `E` channel of a function that returns an `Effect` is a major bump, because callers must now handle the new error. Every output is byte-identical across locales, time zones and hosts. -## Status +## Example -| 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) | +### The change -## The verdict +A package adds a failure to one function: -```ts -import { Effect } from 'effect' -import { Verdict } from '@systemfsoftware/api-extractor' - -// `before` and `after` are encoded API models (the JSON this tool writes). -const document = await Effect.runPromise(Verdict.cell.run({ before, after })) -process.stdout.write(document) // canonical JSON: { _tag, schemaVersion, engine, corpusVersion, declarations, bump, findings } +```diff ++export class Timeout { readonly _tag = 'Timeout' } +-export declare const loadUser: (id: string) => Effect.Effect ++export declare const loadUser: (id: string) => Effect.Effect ``` -`bump` is `none`, `patch`, `minor` or `major`; each finding is -`{ rule_id, reason_code, bump, next_action, locations }`. A model that does not decode -fails the cell with `SurfaceRejected`; a rule corpus in which two rules match the same -change fails it with `RuleCorpusRejected`. The decision itself, `Verdict.judge`, is a -pure `effect-cell-types` workflow over decoded values. - -Rules are data: [`src/rules/corpus.v1.json`](packages/api-extractor/src/rules/corpus.v1.json) -maps each kind of change, its position (`in`, `out`, `both`), its Effect channel and -its direction (`widened`, `narrowed`, `changed`) to a bump. The most specific matching -rule wins. A change no rule covers is reported as major `UNCLASSIFIED_CHANGE`. - -For example, a function returning `Effect` that now returns -`Effect` is major `E_WIDENED`; the same change to a parameter -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. +### Judge both versions -## Front-ends +Read both versions of the package and judge them: ```ts import { NodeServices } from '@effect/platform-node' +import { FrontEnd, Verdict } from '@systemfsoftware/api-extractor' 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)) +const modelOf = (packageRoot: string) => + FrontEnd.readPackage({ packageRoot }).pipe(Effect.flatMap(FrontEnd.analyse), Effect.map((analysis) => analysis.model)) + +const program = Effect.gen(function*() { + const before = yield* modelOf('before/my-lib') + const after = yield* modelOf('after/my-lib') + process.stdout.write(yield* Verdict.cell.run({ before, after })) +}).pipe(Effect.provide(emitters)) + +await Effect.runPromise(program) +``` + +### The verdict document + +The output is canonical JSON, here from a package whose `package.json` exports `./src/mod.ts` under the `@systemfsoftware/source` condition: + +```json +{ + "_tag": "Verdict", + "bump": "major", + "corpusVersion": "1.1.0", + "declarations": { + "after": "oxc-transform@0.150.0", + "before": "oxc-transform@0.150.0" + }, + "engine": "@systemfsoftware/api-extractor@0.1.0", + "findings": [ + { + "bump": "major", + "locations": [ + ".:loadUser/returns/E" + ], + "next_action": "Declare a major bump: callers must now handle the new error, or remove it from the error channel.", + "reason_code": "E_WIDENED", + "rule_id": "e-widened-out" + }, + { + "bump": "minor", + "locations": [ + ".:Timeout" + ], + "next_action": "Declare at least a minor bump.", + "reason_code": "EXPORT_ADDED", + "rule_id": "export-added" + } + ], + "schemaVersion": 1 +} ``` -`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 +## Install + +`@systemfsoftware/api-extractor` is not on npm. This repository ships it as a flake output, and a release is a git tag and a GitHub Release (the latest is [v0.1.0](https://github.com/systemfsoftware/api-extractor-effect/releases/tag/%40systemfsoftware%2Fapi-extractor%40v0.1.0)). 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.systemfsoftware.com` is the registry for `@systemfsoftware` packages: Nix fetches what a producer has pushed there and builds the rest from source. This repository does not push its own tarball yet, so Nix builds `api-extractor` here. + +### Add the flake as an input + +```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"; + }; +} ``` -## Development +### Build the tarballs and the pnpm store + +```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; + }; +}); +``` + +### Requirements -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: +The package needs Node 24 or later and has `effect` `^4.1.2` as a peer, which installs from npm as usual: -```sh -nix develop --command pnpm run bootstrap -nix develop --command pnpm test -nix develop --command pnpm lint -nix develop --command pnpm typecheck +```bash +pnpm add 'effect@^4.1.2' ``` -## Provenance +## The verdict + +`bump` is `none`, `patch`, `minor` or `major`. Each finding names the rule that fired, a reason code, the bump it needs, what to do next, and the places in the model it applies to. A model that does not decode fails the cell with `SurfaceRejected`, and a rule corpus in which two rules match the same change fails it with `RuleCorpusRejected`. The decision itself, `Verdict.judge`, is a pure `effect-cell-types` workflow over decoded values. + +Rules are data. [`corpus.v1.json`](packages/api-extractor/src/rules/corpus.v1.json) holds 61 rules over 33 kinds of change; each maps a kind, its position (`in`, `out`, `both`), its Effect channel and its direction (`widened`, `narrowed`, `changed`) to a bump. The most specific matching rule wins, and a change no rule covers is reported as major `UNCLASSIFIED_CHANGE`. + +| Change to a function | Reason code | Bump | +| --- | --- | --- | +| A tagged error joins the returned `E` channel | `E_WIDENED` | major | +| A tagged error leaves the returned `E` channel | `E_TAG_REMOVED` | major | +| The `E` channel of a parameter widens | `E_WIDENED_IN_INPUT` | minor | +| The `E` channel of a parameter narrows | `E_NARROWED_IN_INPUT` | major | + +A removed tag is major because a caller's `catchTag` for that tag stops compiling. + +## Reading a package's API + +`FrontEnd.readPackage` finds a package's entry points through the `@systemfsoftware/source` export condition, and `FrontEnd.analyse` builds the API model from the declarations. It emits them on a fast path with `oxc-transform`'s isolated declarations, and falls back to the TypeScript 7 compiler when a package's exports are not annotated. Both routes give the same model apart from the producer stamp. The entry-point rules, the two routes and every refusal are in [docs/front-ends.md](docs/front-ends.md). + +## Status + +| Part | State | +| --- | --- | +| Versioned model, canonical serialiser, diff, rule corpus and verdict | released | +| Front-ends: isolated-declarations fast path, TypeScript 7 compiler fallback, model builder, analysis messages | released in 0.1.0 | +| `.api.md` report with a differential test against `@microsoft/api-extractor` 7.59.1 | planned | +| Benchmark, CLI, changeset-bump check | planned | + +The design and its requirements are in [`docs/plans/2026-10-10-1146-feat-effect-api-extractor-plan.md`](docs/plans/2026-10-10-1146-feat-effect-api-extractor-plan.md). + +## Repository + +| Path | What it is | +| --- | --- | +| [`packages/api-extractor`](packages/api-extractor) | `@systemfsoftware/api-extractor`, the library | +| [`apps/api-extractor-e2e`](apps/api-extractor-e2e) | Private. Checks that the library's outputs are byte-identical across locales and hosts | +| [`apps/api-extractor-profile`](apps/api-extractor-profile) | Private. Reproduces the per-phase profile behind the fast-path choice, kept in [`docs/profiles`](docs/profiles) | + +## FAQ + +**`Cannot find native binding` when importing the package.** +`oxc-parser` and `oxc-transform` load their native bindings when the package is imported. Install with optional dependencies, on a platform they ship for. + +**`CompilerRejected` for a package that needs the fallback.** +The fallback runs TypeScript 7's native compiler, which the `typescript` package installs for the host platform as an optional dependency. Without it, every package that needs the fallback is refused, and the diagnostic names the missing platform package. + +**`NoSourceEntry`.** +No export of the package has an `@systemfsoftware/source` condition that names a source file. Pass another condition, for example `FrontEnd.readPackage({ packageRoot, sourceCondition: 'types' })`. + +**`UnsupportedDeclaration`.** +The package's declarations contain a construct the model cannot hold. The error names the file and the construct; the full list is in [docs/front-ends.md](docs/front-ends.md). + +**`SurfaceRejected` from `Verdict.cell.run`.** +One of the two models does not decode as an API model. Produce models with `FrontEnd.analyse`, or check them against `ApiModel.decode`. + +## Documentation + +- [docs/front-ends.md](docs/front-ends.md): reading a package, the two routes and the refusals +- [docs/plans](docs/plans): the design and its requirements +- [docs/profiles](docs/profiles): the per-phase profile behind the fast path +- [CONTRIBUTING.md](CONTRIBUTING.md): development setup, checks and provenance + +## Contributing + +Development setup and checks: [CONTRIBUTING.md](CONTRIBUTING.md). + +## 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..53c12632e --- /dev/null +++ b/docs/front-ends.md @@ -0,0 +1,110 @@ +# 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 +``` From 96d788c1c1907f041cdb358e7fdff7223e8fe1ec Mon Sep 17 00:00:00 2001 From: Ryan Lee Date: Wed, 11 Nov 2026 10:03:47 -0500 Subject: [PATCH 2/2] Delete docs/front-ends.md --- docs/front-ends.md | 110 --------------------------------------------- 1 file changed, 110 deletions(-) delete mode 100644 docs/front-ends.md diff --git a/docs/front-ends.md b/docs/front-ends.md deleted file mode 100644 index 53c12632e..000000000 --- a/docs/front-ends.md +++ /dev/null @@ -1,110 +0,0 @@ -# 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 -```