# `@dads-framework/path-aliases`

`@dads-framework/path-aliases` resolves the TypeScript `paths` aliases declared
by one explicit tsconfig — its own, or any it inherits through `extends` — to
absolute paths of files that exist. It reads through a file system port with
two providers: `nodeFileSystem`, which is the disk, and `inMemoryFileSystem`,
which is a map. Both are put through the same conformance suite.

## What Dad does for you

Dad wants the resolution boundary written down where you can read it. You hand
him one tsconfig; every alias he honors comes from that file's `paths`, and an
alias shape he cannot honor exactly is a startup failure, not a quiet miss.

## Try it

The npm install below is for the public release.

From an npm project on Node.js 22 or newer, install the resolver.

```sh
npm install @dads-framework/path-aliases
```

Save the following as `resolve-alias.mts`. The in-memory file system includes
both the tsconfig and its target, so the example needs no other files.

<!-- dads:check-example -->

```ts
import { relative, resolve } from "node:path";
import {
  createAliasResolver,
  inMemoryFileSystem,
} from "@dads-framework/path-aliases";

const tsconfig = resolve("tsconfig.json");
const source = resolve("src/ui/button.ts");
const fileSystem = inMemoryFileSystem({
  [tsconfig]: JSON.stringify({
    compilerOptions: { paths: { "@app/*": ["./src/*"] } },
  }),
  [source]: 'export const label = "Save";',
});
const resolveAlias = createAliasResolver({ tsconfig, fileSystem });

const button = resolveAlias("@app/ui/button");
console.log(button && relative(".", button).split("\\").join("/"));
console.log(resolveAlias("react"));
```

```sh
node --experimental-strip-types resolve-alias.mts
```

The first line is `src/ui/button.ts`. The second is `null` because `react`
has no entry in the alias map. For an on-disk project, pass the path of your
tsconfig and `nodeFileSystem` to the same resolver.

For a disk-backed example, the repository's
[domain boundaries fixture](../../../fixtures/domain-boundaries/tsconfig.json)
maps `@app/product-id` to `libraries/product-id/src/index.ts`. Pass the
fixture's `tsconfig.json` and `nodeFileSystem` to resolve that import from
its declared alias.

## Use it

| Export                                                                                         | What it is                                                                |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `createAliasResolver({ tsconfig, fileSystem })`                                                | builds the resolver, and refuses every configuration it cannot honor      |
| `AliasResolver`                                                                                | `(specifier: string) => string \| null`                                   |
| `AliasFileSystem`                                                                              | the port: `isFile`, `readText`, `resolvePackage`                          |
| `nodeFileSystem`                                                                               | the provider over `node:fs` and `node:module`                             |
| `inMemoryFileSystem(files)`                                                                    | the provider over a map of absolute paths to text                         |
| `runAliasResolverConformance({ root, fileSystem })`                                            | the suite every provider is run through; an empty finding list is passing |
| `aliasResolverConformanceLaws()`                                                               | the twenty-five law names the suite reports under, in run order           |
| `AliasFileSystemFactory`, `AliasResolverConformanceSubject`, `AliasResolverConformanceFinding` | the shapes that suite takes and answers                                   |

Aliases may be declared on the given tsconfig or inherited through its
`extends` chain, which may be a string or an array of strings and may name a
relative file or a package. The config that declares `paths` is the nearest one
in the chain; its targets resolve against the `baseUrl` of that config, or of
the nearest config after it that sets one, or against its own directory.

Resolution probes an alias target as a file, then as a package directory whose
entry point is the first of `exports`, `module`, and `main` that names an
existing file, then with each supported extension and as `index.<extension>`
inside it: `.ts`, `.tsx`, `.js`, `.jsx`, `.json`, `.mts`, `.mjs`, `.cts`,
`.cjs`, `.css`, `.scss`, and `.less`. A specifier written with an explicit
extension falls back to the matching source file, so `@app/source.js` finds
`src/source.ts`. A `?suffix` query is stripped before matching.

`exports` contributes `exports["."]` when that is a string, otherwise its
`import` condition and then its `default` condition; any other `exports` shape,
an unreadable `package.json`, and no `package.json` at all leave `module` and
`main` to answer, and then the extension and `index.<extension>` probes.

## What it refuses to do

- **It does not load the TypeScript compiler.** The tsconfig dialect —
  comments, trailing commas, and strings containing either — is read by this
  package, so your compiler version is yours to choose, or to skip.
- **It does not touch a disk of its own.** Every file question goes through the
  port, which is why the in-memory stand-in exists and why both providers run
  one suite.
- **It does not discover a tsconfig.** There is no search up the directory tree
  and no default: the config that owns resolution is the one you named.
- **It does not guess at an alias shape it does not support.** Two targets for
  one alias, more than one `*`, or a wildcard count that differs between
  pattern and target is a configuration-time error rather than a weaker match.
- **It does not claim a specifier it cannot prove.** A bare specifier, an
  absolute path, and an alias whose target names no existing file all answer
  `null` and stay the caller's to resolve.
- **It does not resolve every specifier under `baseUrl`.** An alias is honored
  because `paths` declares it, not because a file happens to sit beside the
  ones that are declared.

## Contract

`createAliasResolver(options: AliasResolverOptions): AliasResolver`, where
`AliasResolverOptions` is `{ readonly tsconfig: string; readonly fileSystem:
AliasFileSystem }`. The resolver answers an absolute file path for a specifier
it owns and `null` for everything else.

Every failure below is thrown while the resolver is being built —
configuration time, not resolve time — so a broken alias map fails the run
instead of silently resolving less:

| Message                                                                                | When                                                      |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `Dads path aliases requires a non-empty tsconfig path.`                                | `tsconfig` is blank                                       |
| `Dads path aliases tsconfig is not a readable file: <path>`                            | The named tsconfig is not a readable file                 |
| `Unable to read Dads path aliases tsconfig <path>: <detail> at line <l>, column <c>`   | A config in the chain is unreadable or is not valid JSONC |
| `Dads path aliases tsconfig <path> does not declare or inherit compilerOptions.paths.` | No aliases were found                                     |
| `Dads path alias <pattern> in <path> must have exactly one target.`                    | An alias maps to zero, several, or one unusable target    |
| `Dads path alias <pattern> in <path> must use zero or one matching wildcard.`          | Wildcards exceed one, or do not match                     |
| `Dads path aliases supports tsconfig extends only as a string or string array.`        | `extends` is some other shape                             |
| `Dads path aliases cannot resolve tsconfig extends <target> from <path>.`              | A relative `extends` names no file                        |
| `Dads path aliases cannot resolve tsconfig package <name> from <path>.`                | A package `extends` cannot be resolved                    |
| `Dads path aliases found a circular tsconfig extends chain at <path>.`                 | The `extends` chain revisits a config                     |

`runAliasResolverConformance` answers a list of findings and throws nothing; an
empty list is conformance. Each finding names the case, the law, and what the
provider did instead. A subject is `{ root, fileSystem }`, where `root` is an
absolute directory the suite builds its fixtures under and `fileSystem` builds
a provider serving exactly the files it is handed.

The package requires Node.js 22 or newer and has no dependencies at all.

## Daddy issues this prevents

Alias resolution is where a build quietly stops matching the type checker: the
compiler follows one map, the test runner follows another, and the
disagreement only shows up as an import that works everywhere except in CI. One
named config, one map, and a loud failure when it cannot be honored.
