Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added .sfs-deps/effect-cell-types-12.0.0.tgz
Binary file not shown.
Binary file added .sfs-deps/effect-gherkin-spec-7.0.1.tgz
Binary file not shown.
Binary file added .sfs-deps/effect-schema-discovery-2.0.0.tgz
Binary file not shown.
Binary file added .sfs-deps/effect-schema-law-5.0.1.tgz
Binary file not shown.
Binary file not shown.
Binary file added .sfs-deps/effect-schema-vite-3.0.1.tgz
Binary file not shown.
Binary file added .sfs-deps/effect-sim-kernel-1.0.0.tgz
Binary file not shown.
Binary file added .sfs-deps/effect-spec-runtime-1.0.1.tgz
Binary file not shown.
Binary file not shown.
Binary file added .sfs-deps/oxlint-config-dmmf-2.0.0.tgz
Binary file not shown.
Binary file added .sfs-deps/oxlint-config-recommended-4.0.0.tgz
Binary file not shown.
Binary file added .sfs-deps/oxlint-config-rule-authoring-1.1.0.tgz
Binary file not shown.
Binary file not shown.
Binary file added .sfs-deps/oxlint-plugin-dmmf-workflow-7.0.0.tgz
Binary file not shown.
Binary file added .sfs-deps/oxlint-plugin-effect-platform-2.0.0.tgz
Binary file not shown.
Binary file not shown.
Binary file added .sfs-deps/oxlint-plugin-test-discipline-5.0.0.tgz
Binary file not shown.
Binary file added .sfs-deps/stryker-config-0.1.0.tgz
Binary file not shown.
Binary file added .sfs-deps/stryker-framework-interface-0.0.1.tgz
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file added .sfs-deps/stryker-ignorer-interface-0.1.2.tgz
Binary file not shown.
Binary file added .sfs-deps/stryker-ignorer-kit-0.1.2.tgz
Binary file not shown.
Binary file added .sfs-deps/stryker-js-18.1.0.tgz
Binary file not shown.
Binary file added .sfs-deps/stryker-js-cli-contract-0.4.0.tgz
Binary file not shown.
Binary file added .sfs-deps/stryker-js-instrumenter-12.1.2.tgz
Binary file not shown.
Binary file added .sfs-deps/stryker-js-plugin-interface-15.0.0.tgz
Binary file not shown.
Binary file added .sfs-deps/stryker-js-plugin-runtime-7.0.3.tgz
Binary file not shown.
Binary file not shown.
Binary file added .sfs-deps/stryker-js-vitest-runner-9.0.1.tgz
Binary file not shown.
Binary file added .sfs-deps/tsconfig-2.0.1.tgz
Binary file not shown.
Binary file added .sfs-deps/tsdown-config-0.1.0.tgz
Binary file not shown.
Binary file added .sfs-deps/vitest-2.0.0.tgz
Binary file not shown.
Binary file added .sfs-deps/vitest-config-0.1.0.tgz
Binary file not shown.
25 changes: 25 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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.
170 changes: 51 additions & 119 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<rev>";
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

Expand Down Expand Up @@ -48,7 +78,7 @@ For example, a function returning `Effect<User, NotFound>` 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'
Expand All @@ -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 <systemfsoftware checkout> ../../docs/profiles/<date>-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.
111 changes: 111 additions & 0 deletions docs/front-ends.md
Original file line number Diff line number Diff line change
@@ -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 <systemfsoftware checkout> ../../docs/profiles/<date>-front-end-phases
```

Loading