@nielspeter/eess-ts 0.2.1 → 0.4.0

package/dist/core/module-edges.d.ts

@@ -0,0 +1,361 @@
+import type { SourceFile } from 'ts-morph';
+/**
+ * One definition of "a module edge", for every condition that needs one.
+ *
+ * [ts-archunit Bug 0022](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0022-forward-import-conditions-are-blind-to-reexports-and-dynamic-imports.md):
+ * `src/conditions/dependency.ts` collected edges from `sf.getImportDeclarations()`
+ * at five sites — static `import` statements and nothing else — while the reverse
+ * graph indexed static imports, re-exports **and** dynamic imports. So
+ * `onlyBeImportedVia('…')` saw a re-export as an import and `notImportFrom('…')`
+ * did not, and `export { x } from './banned.js'` crossed every banned edge
+ * unflagged.
+ *
+ * `SourceFile.getImportStringLiterals()` returns one literal per module
+ * specifier across every edge-carrying form, from the binder's cached
+ * `compilerNode.imports` rather than a descendant walk. Measured over 20 forms;
+ * the table lives in plan 0071 §1 and the fixture that pins it is
+ * `tests/fixtures/module-edge-forms/`.
+ *
+ * **Two classification traps**, both of which would mark a *runtime* dependency
+ * as erased — and both are why `kind` is a five-member union rather than four:
+ *
+ * - `import x = require('s')` has parent `ExternalModuleReference`. A 4-way
+ *   branch ending in `else → 'type-expression'` gives it `typeOnly: true`,
+ *   exempt under `ignoreTypeImports`. Common in hand-written `.d.ts`.
+ * - `require('s')` in `.js` under `allowJs` has parent `CallExpression`, the same
+ *   as `import('s')`. `getExpression().getKind() === ImportKeyword` is the only
+ *   discriminator, as `reverse-dependency.ts` already knew.
+ *
+ * **Nothing here narrows the literal.** `getImportStringLiterals()` is declared
+ * `StringLiteral[]` and ``import(`./x.js`)`` yields a
+ * `NoSubstitutionTemplateLiteral`, for which `Node.isStringLiteral()` is
+ * **false**. ADR-005 bars the `as` that would re-narrow it, so an implementer
+ * narrowing defensively silently drops the edge and `tsc` says nothing.
+ * `getLiteralText()` typechecks and is correct for both.
+ */
+export type ModuleEdgeKind = 'import' | 'reexport' | 'dynamic' | 'type-expression' | 'require';
+/** One module specifier leaving one file. */
+export interface ModuleEdge {
+    readonly kind: ModuleEdgeKind;
+    /** The specifier as written. */
+    readonly specifier: string;
+    /** Resolved absolute path, when the compiler resolved it. */
+    readonly resolvedPath: string | undefined;
+    /**
+     * 1-based line of the **statement** carrying the edge.
+     *
+     * Equals `decl.getStartLineNumber()` for `kind === 'import'`, which
+     * `tests/core/module-edges-corpus.test.ts` asserts across the whole repo: 88
+     * of this repo's 1751 import declarations (5.0%) put the specifier on a
+     * different line from the keyword, so keying off the literal would move 5% of
+     * reported lines. Not a baseline concern — `hashViolation` never sees the line
+     * — but it drives the code frame and the GitHub annotation position.
+     *
+     * The same gap exists for every other kind, which is why the fixture carries a
+     * multi-line form of each: a multi-line `export { … } from` and a multi-line
+     * `import(…)` both move too, and a line taken from the literal passes every
+     * single-line test.
+     */
+    readonly line: number;
+    /**
+     * The **bindings** crossing this edge are type-level. Per-kind; see below.
+     *
+     * This is the *coupling* question — "does this file reference that file's types" —
+     * and it is what `dependOn`, `notImportFrom`, `onlyImportFrom` and the module
+     * predicates ask. It is deliberately NOT the same question as
+     * {@link erasesModuleRequest}, and conflating them was
+     * [ts-archunit plan 0087](https://github.com/nielspeter/ts-archunit/blob/main/plans/completed/0087-an-inline-type-import-still-requests-the-module.md).
+     */
+    readonly typeOnly: boolean;
+    /**
+     * The whole statement disappears, so **no module request is emitted** and the
+     * target module is never evaluated.
+     *
+     * This is the *module-initialization* question — "will importing this file cause
+     * that file to run" — and it is what cycle detection must ask. A cycle is a
+     * deadlock in initialization order; a coupling is not.
+     *
+     * The two differ for exactly two spellings, and only under
+     * `verbatimModuleSyntax: true`. Measured through ts-morph's own emit, same source,
+     * both settings:
+     *
+     * | form                          | `vms: false` | `vms: true`                 |
+     * | ----------------------------- | ------------ | --------------------------- |
+     * | `import type { X } from 's'`  | erased       | erased                      |
+     * | `import { type X } from 's'`  | erased       | **`import {} from 's'`**    |
+     * | `import { type X, y } from`   | requests     | requests                    |
+     * | `export type { X } from 's'`  | erased       | erased                      |
+     * | `export { type X } from 's'`  | erased       | **`export {} from 's'`**    |
+     * | `export { type X, y } from`   | requests     | requests                    |
+     * | `export * from 's'`           | requests     | requests                    |
+     * | `export type * as N from 's'` | erased       | erased                      |
+     *
+     * The specifiers vanish; the module request does not. So under that flag those two
+     * forms are eager edges that can close a cycle, and treating them as erased is a
+     * false negative — which is what `beFreeOfCycles` did until v0.49.0.
+     *
+     * `erasesModuleRequest` implies `typeOnly`: a statement cannot vanish while still
+     * binding a runtime value. `tests/conditions/verbatim-module-syntax.test.ts` asserts that
+     * invariant over every form rather than leaving it as a claim.
+     */
+    readonly erasesModuleRequest: boolean;
+    /**
+     * Named bindings crossing the edge.
+     *
+     * **The name, not the local binding** — and which one differs per kind:
+     *
+     * - `reexport`: the **outward** name, `getAliasNode() ?? getName()`. For
+     *   `export { INNER as OUTER } from 's'` this is `OUTER`, because that is the
+     *   key the re-exporting module's runtime namespace carries, and the runtime
+     *   independence guard compares against a runtime namespace. Under the
+     *   local-name reading that guard fails on a *correct* implementation.
+     * - `import`: the **inward** name, `getName()`. For `import { c as d }` this is
+     *   `c` — the name crossing the edge, not the local binding `d`.
+     *
+     * **Empty for `export *`**, and not because the names are unknowable:
+     * `sf.getExportSymbols()` flattens `export *` in a single call, and on a
+     * circular pair the compiler and the Node runtime independently agree.
+     * Nothing is recursive. It is empty for two other reasons:
+     *
+     * 1. it cannot separate an erased re-export from a runtime one — `export type
+     *    { X } from` and `export { X } from` both come back with
+     *    `SymbolFlags.Alias` and a single `ExportSpecifier`, indistinguishable
+     *    without `getAliasedSymbol()` per name; and
+     * 2. it includes names with no runtime existence — a `declare module
+     *    './star-src.js' { export const INJECTED: number }` augmentation anywhere
+     *    in the project injects `INJECTED` into the star target's exports.
+     *
+     * (`symbol.getExports()` does **not** flatten; it hands back a synthetic
+     * `__export` member. The obvious call gives the unflattened view.)
+     *
+     * **`export * as NS from 's'` is not a star for this purpose**: it contributes
+     * exactly one name, `NS`, statically, with no recursion. `isNamespaceExport()`
+     * returns **true for both** star forms — measured — so `getNamespaceExport()`
+     * is the only discriminator.
+     *
+     * Also empty for `dynamic`, `require`, `type-expression`, and for a default or
+     * namespace `import` binding (`import D from 's'`, `import * as NS from 's'`),
+     * which cross an edge under a name the specifier list does not carry.
+     */
+    readonly names: readonly string[];
+    /**
+     * How many edges of the same `kind` and `specifier` precede this one in the file,
+     * in source order. `0` for the first.
+     *
+     * It exists because {@link names} is **empty** wherever no name crosses the edge,
+     * and a finding's identity is built from `kind::specifier::names`. That is `dynamic`,
+     * `require` and `type-expression` — and also four ordinary `import`/`reexport`
+     * spellings: `import D from`, `import * as NS from`, a bare `import './x.js'`, and
+     * `export * from`. So two lazy imports of the same module from one file produced two
+     * findings and **one** baseline hash — measured 2/1, against a control of 2/2 for two
+     * named imports — which means one accepted entry silently pre-accepts the next one
+     * someone adds. Measured on `main`, the same 2/1 held for two default imports and for
+     * two bare side-effect imports, in **both** families. Bug 0028's shape, wherever a
+     * kind or a spelling had no discriminator
+     * ([ts-archunit bug 0059](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0059-slice-conditions-and-module-conditions-disagree-about-a-dependency.md)).
+     *
+     * **Source-order ordinal rather than the line**, deliberately: a line moves when
+     * anything above it is edited, and `identity` exists precisely to survive that.
+     * The ordinal only moves when an edge of the same kind to the same module is
+     * added or removed before it — which is a real change to what the file does.
+     *
+     * The residual caveat, and it is inherent to any positional tiebreaker. **A baseline entry
+     * accepts "an edge of this kind to this module at position n", not _this_ edge.** Measured
+     * end-to-end, v0.55.3 baselines replayed through this version:
+     *
+     * | edit to an accepted colliding pair      | new reds reported |
+     * | --------------------------------------- | ----------------- |
+     * | add a third sibling                     | 1 — correct       |
+     * | insert a sibling **above** the first     | 1 — correct       |
+     * | **delete the first, add a different one**| **0 — silent**    |
+     *
+     * So the insertion case is safe and the equal-count swap is a fail-open: a dependency edge
+     * that did not exist when the baseline was written arrives accepted. This is strictly better
+     * than the pre-ordinal behaviour, where *any* number of added siblings was pre-accepted
+     * rather than only an equal-count swap — but it is a limitation, not a guarantee, and it is
+     * why {@link edgeDiscriminator} is a tiebreaker of last resort rather than an identity
+     * component. The durable fix is a `binding` field consulted before the ordinal, which would
+     * separate `import A` from `import C` outright; recorded as out-of-scope in
+     * [ts-archunit plan 0094](https://github.com/nielspeter/ts-archunit/blob/main/plans/0094-the-residual-findings-from-the-v0-56-0-review.md).
+     *
+     * Both collectors must agree on it, so both walk the literals in source order;
+     * `edgeStream` sorts for that reason and not for output tidiness.
+     */
+    readonly ordinal: number;
+}
+/**
+ * Every module edge leaving each file, in one call (ADR-007 rule 2).
+ *
+ * **Cached since plan 0076**, per file, invalidated by `onModified`. The
+ * sentence this paragraph used to carry — *"No cache … if a consumer reports a
+ * multiple-slowdown, the fix is a cache of resolution, not of the walk"* — was
+ * half right: a consumer did report one, and the walk is indeed not the cost
+ * (1ms across five passes over 520 files). But resolution is not the cost
+ * either. Building the `ModuleEdge` is: 15ms resolution against ~32ms
+ * construction, of 48ms total. So the cache is of the built edges, and the
+ * forward commitment this docstring made — *"what it forecloses is batching a
+ * resolution cache later"* — is discharged rather than left standing.
+ *
+ */
+export declare function moduleEdges(files: readonly SourceFile[]): ReadonlyMap<string, readonly ModuleEdge[]>;
+/**
+ * Every module edge leaving one file, in source order.
+ *
+ * Exported for the predicate sites, which are per-element by construction and
+ * would otherwise build a one-entry `Map` per file just to read it back out.
+ */
+export declare function edgesOf(sourceFile: SourceFile): readonly ModuleEdge[];
+/**
+ * What tells two edges of the same kind, from the same file, to the same module apart.
+ *
+ * `names` when there are any; the source-order ordinal when there are not — and **`names` is
+ * empty for a SPELLING, not for a kind**, which is the distinction the whole of this comment
+ * turns on. `dynamic`, `require` and `type-expression` never carry names, and neither do four
+ * ordinary `import`/`reexport` spellings (`import D from`, `import * as NS from`, a bare
+ * `import './x.js'`, `export * from`). Any of them, twice to one module from one file,
+ * measured **2 findings, 1 hash** against a control of 2/2 for two named imports — so one
+ * accepted baseline entry silently pre-accepts the next one someone adds. Bug 0028's shape,
+ * in every spelling that reached this function without a discriminator; the lazy kinds are
+ * merely the ones
+ * [ts-archunit bug 0059](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0059-slice-conditions-and-module-conditions-disagree-about-a-dependency.md)
+ * made reportable, which is how the narrower reading got written here in the first place.
+ *
+ * The sort and the `,` are load-bearing and cheap to lose: `getNamedImports()` returns source
+ * order, so without the sort a cosmetic reorder of a named import list moves every multi-name
+ * entry in an adopter's baseline — an import-sorting lint autofix would do it. Without the
+ * separator, `['a','b']` and `['ab']` collide. Both are pinned by the multi-name row in
+ * `tests/conditions/identity-does-not-move.test.ts`, and by nothing else in the suite.
+ *
+ * **No existing baseline entry moves**, and that is what the `ordinal === 0` branch buys.
+ * The naive form — `#${ordinal}` whenever `names` is empty — moves far more than the three
+ * kinds it was written for, because `names` is empty for four ordinary `import`/`reexport`
+ * spellings too: `import D from`, `import * as NS from`, a bare `import './x.js'`, and
+ * `export * from` (the barrel). `export * as NS from` is **not** among them — it carries one
+ * statically-known name. That form shipped briefly in v0.56.0's development and was caught by
+ * review, measured against `main` through the public conditions: 4 of 7 spellings moved, in
+ * both families, while the CHANGELOG and ts-archunit's `docs/upgrading.md` promised none did.
+ *
+ * Emitting `''` for the first edge of each group reproduces exactly what the pre-ordinal
+ * formula produced (`[...names].sort().join(',')` over an empty list), so every
+ * single-occurrence finding keeps a byte-identical identity — measured across all seven
+ * spellings plus `dynamic` and `type-expression`, zero diff. The `#n` suffix appears only on
+ * the **second and later** edge of one kind to one module from one file, which is precisely
+ * the group that had two findings and one hash before, i.e. a baseline entry that was already
+ * wrong. So the fail-open closes and the migration is empty — the surviving entry still
+ * matches, and only the genuinely-new sibling is reported.
+ *
+ * Uniqueness still holds: within a group the sequence `''`, `#1`, `#2`, … is injective, and
+ * `''` is unreachable from the named branch because no import specifier is an empty
+ * identifier.
+ *
+ * The cost, stated so it is a decision rather than a discovery: the discriminator is no longer
+ * uniform, so `…::` no longer distinguishes "names-less, first" from "not computed". That is
+ * a readability loss traded for a migration nobody has to perform.
+ */
+export declare function edgeDiscriminator(edge: ModuleEdge): string;
+/**
+ * How a finding refers to this kind of edge.
+ *
+ * **An exhaustive `switch`, not a `Record` lookup or a 4-way branch** (plan 0071
+ * §4). Measured on a build with `require` unfiltered and no `require` verb: a
+ * `Record` lookup emitted the literal string `undefined` into a message —
+ * `cjs-consumer.js undefined "…/target.ts" which matches forbidden […]` — and
+ * that text is hashed into a baseline. A missing verb must be a compile error;
+ * with an explicit `string` return and no fallthrough, adding a sixth
+ * `ModuleEdgeKind` breaks the build here.
+ *
+ * `require` gets a real verb even though no condition reports it (§3). The
+ * alternative — throwing, or returning a placeholder — makes a forgotten kind
+ * filter produce nonsense instead of a correct sentence, and a correct sentence
+ * costs one line.
+ *
+ * **`import` must stay byte-identical.** Every existing baselined dependency
+ * finding hashes its message, so changing this string for `import` silently
+ * invalidates them all; the new kinds get distinct verbs precisely so their
+ * findings are NOT absorbed by an existing `import` entry for the same module.
+ */
+export declare function edgeVerb(kind: ModuleEdgeKind): string;
+/**
+ * How a finding describes a **runtime** edge of this kind, for
+ * `onlyHaveTypeImportsFrom`.
+ *
+ * Separate from {@link edgeVerb} because that condition's sentence needs a noun
+ * phrase ("has a value import from") rather than a verb, and because its remedy
+ * differs per kind in a way the verb does not capture — see
+ * {@link edgeTypeOnlyRemedy}.
+ */
+export declare function edgeValuePhrase(kind: ModuleEdgeKind): string;
+/**
+ * The remedy for a runtime edge that should be type-only — **per kind, because
+ * the remedy differs and one of them has a consequence** (ADR-009 rule 2).
+ *
+ * `onlyHaveTypeImportsFrom`'s shipped preset says *"Use `import type { X }` so
+ * the dependency is erased"*. For an `import` that is complete and local. For a
+ * re-export it is not: `export type { X } from` erases the edge **and removes a
+ * runtime export consumers may be importing as a value**. The finding still
+ * stands — the runtime dependency is real — but a remedy that silently changes
+ * what the module publishes is a remedy the reader must be told about.
+ *
+ * `dynamic` is excluded from that condition entirely for the stronger version of
+ * the same reason: there is no remedy at all. You cannot erase an
+ * `await import(…)`.
+ */
+export declare function edgeTypeOnlyRemedy(edge: Pick<ModuleEdge, 'kind' | 'names'>): string;
+/**
+ * The noun for this kind of edge, for `onlyHaveTypeImportsFrom`'s sentence tail.
+ *
+ * `edgeValuePhrase` was made per-kind and the tail was not, so a re-export read
+ * "has a runtime re-export of … which should be a type-only **import**". The two
+ * halves have to agree or the sentence contradicts itself.
+ */
+/**
+ * The kinds a **forward** dependency site reports on.
+ *
+ * One constant, because there were two: `DEPENDENCY_KINDS` in
+ * `conditions/dependency.ts` and `PREDICATE_KINDS` in `predicates/module.ts`, whose
+ * docstring said "the same set as the conditions … and it has to be" with prose as
+ * the only enforcement. `notImportFrom` is one identifier with two definitions
+ * chosen by chain position, so a predicate that disagreed with its own condition
+ * about what an import is would be this release's Problem statement in miniature.
+ *
+ * **Exhaustive, not an allowlist filter.** A sixth `ModuleEdgeKind` is a compile
+ * error here rather than a kind silently excluded everywhere — that fail-open is the
+ * same false green this release closes.
+ *
+ * `require` is `false`: the kind exists so a 4-way branch cannot mark a CJS runtime
+ * dependency as erased, not to enforce CJS. The **reverse** graph counts it, which
+ * is the opposite disposition and deliberately so — see `indexEdges`'s reasoning.
+ * `onlyHaveTypeImportsFrom` diverges further still (`TYPE_IMPORT_KINDS`), and that
+ * one divergence is intentional and documented at its own site.
+ */
+export declare const FORWARD_EDGE_KINDS: Record<ModuleEdgeKind, boolean>;
+/**
+ * Every module edge leaving one file, **lazily and unsorted**.
+ *
+ * For a caller that only asks "is there any edge matching X". `edgesOf` builds and
+ * resolves the whole array before returning, so `edgesOf(sf).some(...)` pays a
+ * `getSymbol()` for every literal in the file even when the first one answers the
+ * question — on a 100-import file whose first import matches, 100 checker calls
+ * where the pre-0.28.0 code made 1.
+ *
+ * **Order is unspecified, and since plan 0076 it differs between a cold and a
+ * warm call.** Cold, edges arrive in walk order — the declaration forms first,
+ * because that is how ts-morph enumerates them. Warm, they arrive in the source
+ * order {@link edgesOf} sorted them into. Measured, on a file whose dynamic
+ * import precedes its declaration import:
+ *
+ *     cold  ./a.js, ./b.js
+ *     warm  ./b.js, ./a.js
+ *
+ * No verdict depends on it today: the only consumer is `dependOn`
+ * (`conditions/dependency.ts`), which is a `.some()` and stops at the first
+ * match. But "sometimes sorted" is a worse contract than "never sorted", so it
+ * is stated rather than left to be discovered. **Anything that reports a
+ * finding must use {@link edgesOf}**, whose source ordering is part of its
+ * contract — a reporting site fed from here would name a different edge
+ * depending on whether an unrelated rule warmed the file first, which is one
+ * finding with two identities.
+ */
+export declare function edgeStream(sourceFile: SourceFile): Generator<ModuleEdge>;
+export declare function edgeTypeOnlyNoun(kind: ModuleEdgeKind): string;
+//# sourceMappingURL=module-edges.d.ts.map

package/dist/core/module-edges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-edges.d.ts","sourceRoot":"","sources":["../../src/core/module-edges.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,UAAU,CAAA;AAKzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAAA;AAE9F,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAA;IACrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,UAAU,EAAE,GAC3B,WAAW,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC,CAM5C;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE,CAYrE;AAqFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAY1D;AA0ND;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAarD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAa5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,MAAM,CA4BnF;AAED;;;;;;GAMG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,cAAc,EAAE,OAAO,CAM9D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAiB,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CA8BzE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAW7D"}