feat(front-end): build the API model from a package's source

.changeset/old-cobras-punch.md

@@ -0,0 +1,7 @@
+---
+"@systemfsoftware/api-extractor": minor
+---
+
+Add the `FrontEnd` namespace. It reads a package and emits its declarations two ways behind one emitter port: on the isolated-declarations fast path (oxc-transform), or through the TypeScript 7 compiler when a package's exports are not annotated. One syntactic builder turns those declarations into the versioned API model, and a syntactic resolver reports five api-extractor analysis messages. Both routes produce the same model apart from its producer stamp, which names the emitter that ran.
+
+The package now installs `typescript` 7, `oxc-parser`, `oxc-transform` and `@microsoft/tsdoc` as runtime dependencies, which the front-ends use.

README.md

@@ -13,7 +13,7 @@ The design and its requirements live in
 | Part | State |
 |---|---|
 | Versioned model, canonical serialiser, diff, rule corpus and verdict | in this repository |
-| Front-ends (isolated-declarations fast path, compiler fallback) | next |
+| 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 |
@@ -48,6 +48,114 @@ 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
+
+```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')`)
+- 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 or a dotted name (`[Symbol.iterator]` is kept), 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
+```
+
 ## Development
 
 The `@systemfsoftware/*` packages install from tarballs that this repository's flake