From 81ed96f39174862151ec82e25a73e7a7d713061d Mon Sep 17 00:00:00 2001 From: systemfsoftware-maker <248545757+systemfsoftware-maker@users.noreply.github.com> Date: Wed, 11 Nov 2026 14:16:08 +0000 Subject: [PATCH] docs: rewrite the README as a front page for people deciding to use it The pitch, status and install route come first, then the verdict and reading a package. The front-end detail moves to docs/front-ends.md and the development setup and provenance to CONTRIBUTING.md. Each claim was checked against the source. --- CONTRIBUTING.md | 25 +++++++ README.md | 171 ++++++++++++++------------------------------- docs/front-ends.md | 111 +++++++++++++++++++++++++++++ 3 files changed, 187 insertions(+), 120 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..9c45bfa88 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,25 @@ +# Contributing + +## Development setup + +`nix develop` provides the dev shell and the `@systemfsoftware/*` packages the workspace installs. The flake builds them from pinned systemfsoftware and stryker-js-effect commits, so they arrive as tarballs and never come from a registry. + +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 faf775664..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 the flake (`.sfs-deps`) | 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,117 +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 -The `@systemfsoftware/*` packages install from tarballs that this repository's flake -builds from pinned systemfsoftware and stryker-js-effect commits, never from a registry. -The dev shell copies them into `.sfs-deps/`; `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 +``` +