@nielspeter/eess-ts 0.2.1 → 0.5.0

package/dist/core/module-edges.js

@@ -0,0 +1,593 @@
+import { Node, SyntaxKind } from 'ts-morph';
+import { isTypeOnlyImport, isTypeOnlyReExport } from './import-options.js';
+import { registerCacheReset } from '@nielspeter/eess/internal';
+import { verbatimModuleSyntaxFor } from './per-root-compiler-options.js';
+/**
+ * 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 function moduleEdges(files) {
+    const byFile = new Map();
+    for (const sf of files) {
+        byFile.set(sf.getFilePath(), edgesOf(sf));
+    }
+    return byFile;
+}
+/**
+ * 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 function edgesOf(sourceFile) {
+    const hit = cache.get(sourceFile);
+    if (hit !== undefined)
+        return hit;
+    const edges = buildEdges(sourceFile);
+    if (!watched.has(sourceFile)) {
+        // Once per file, not once per miss: a watch session that re-evaluates
+        // rules would otherwise accumulate one listener per rule execution.
+        watched.add(sourceFile);
+        sourceFile.onModified(() => cache.delete(sourceFile));
+    }
+    cache.set(sourceFile, edges);
+    return edges;
+}
+/**
+ * One built edge list per file, invalidated when the file is modified.
+ *
+ * Plan 0076. Measured on this repository (520 files): five whole-project
+ * `notImportFrom` rules made **10,525 `getSymbol()` calls in 47ms** where 2,105
+ * would do — exactly 5x, because rules that share subjects re-resolve the same
+ * literals. Five *disjoint* folder rules cost 388, so the win tracks subject
+ * overlap rather than rule count.
+ *
+ * **Why not `resolve()` alone**, which this file's own docstring above
+ * recommends: measured across five passes, the walk is 1ms, resolution 15ms and
+ * building the `ModuleEdge` ~32ms. The advice predates anyone splitting the
+ * three, and resolution is the middle third rather than the cost.
+ *
+ * **Why a listener rather than object identity.** A `SourceFile`'s identity
+ * SURVIVES an edit — measured, `addImportDeclaration` and `replaceWithText`
+ * both keep the same object while the edges change — so the argument that makes
+ * `WeakMap<ArchProject, …>` safe in `element-cache.ts` does **not** transfer. A
+ * `SourceFile`-keyed cache without invalidation serves pre-edit edges after an
+ * edit, and a `notImportFrom` rule then passes on the import the edit just
+ * added: ADR-008's false green, manufactured by a cache. `onModified` is a
+ * ts-morph API (no raw compiler access, ADR-002 intact) and fires on every
+ * mutation path — `addImportDeclaration`, `replaceWithText`, `remove` and
+ * `insertText` — and never on a read.
+ */
+let cache = new WeakMap();
+const watched = new WeakSet();
+/**
+ * Drop every cached edge list. Called by `resetProjectCache()`.
+ *
+ * `onModified` covers a change to the file that OWNS the edge. It does not cover
+ * a change to the edge's **target** — `resolvedPath` is a function of the whole
+ * program, so creating the file a specifier could not resolve to, or deleting
+ * the one it did, leaves the importer's cached edge stale. Measured, both
+ * directions. This is the escape hatch for that; `watched` is deliberately not
+ * cleared, since those listeners stay correct.
+ */
+function clearModuleEdgeCache() {
+    cache = new WeakMap();
+}
+registerCacheReset(clearModuleEdgeCache);
+function buildEdges(sourceFile) {
+    // Once per file, not once per literal. Measured: 0.1ms across this repo's 574
+    // files, so hoisting is for clarity rather than cost.
+    const verbatim = usesVerbatimModuleSyntax(sourceFile);
+    const edges = [];
+    for (const literal of sourceFile.getImportStringLiterals()) {
+        const parent = literal.getParent();
+        if (parent === undefined)
+            continue;
+        const kind = kindOf(parent);
+        if (kind === undefined)
+            continue;
+        edges.push({
+            // The literal's absolute position, so the sort below is genuine source
+            // order. It is dropped from the public shape by the `map` at the end.
+            pos: literal.getPos(),
+            ...makeEdge(literal, parent, kind, verbatim),
+            // Sorted by the literal's absolute position so the result is source-ordered
+            // and deterministic. The binder's `imports` array puts declaration forms
+            // first and expression forms after, regardless of where they appear — so
+            // without this, `kind === 'import'` filtered out of an interleaved file
+            // would still be source-ordered but `relpath:line` multisets across kinds
+            // would not be, and item 8's fixture is exactly such a file.
+        });
+    }
+    // Source order, by the literal's absolute position.
+    //
+    // This used to be `(line, specifier.localeCompare(...))`, which was two defects
+    // in one line. The comment claimed "the literal's absolute position" and the
+    // code did not use it — measured, `import { Z } from './z.js'; import { A } from
+    // './a.js'` on ONE line came back `./a.js, ./z.js` against declaration order
+    // `./z.js, ./a.js`, which is one same-line double import away from a false red
+    // in the corpus sequence-equality test. And `localeCompare` is ICU/locale
+    // sensitive — exactly the machine-dependent ordering `conditions/slice.ts` goes
+    // out of its way to eliminate, because a value that differs per machine gives
+    // one finding two identities.
+    const counters = new Map();
+    return (edges.length > 1 ? [...edges].sort((a, b) => a.pos - b.pos) : edges).map(({ pos: _pos, ...edge }) => ({ ...edge, ordinal: nextOrdinal(counters, edge) }));
+}
+/**
+ * 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 function edgeDiscriminator(edge) {
+    // Unicode codepoint order, NOT `localeCompare` — a baseline identity may not depend on the
+    // machine that computed it. `localeCompare` reads the host locale, and this file already said
+    // so 60 lines above (`indexEdges`: "exactly the machine-dependent ordering `conditions/slice.ts`
+    // goes out of its way to eliminate, because a value that differs per machine gives one finding
+    // two identities") — and then used it here anyway. Measured on plain ASCII: `zebra, aardvark`
+    // sorts to `aardvark,zebra` under `en-US` and to `zebra,aardvark` under `da-DK`, because Danish
+    // collates `aa` as `å`, after `z`. Same import, two baseline hashes, diverging only between a
+    // developer's machine and CI. `src/core/project.ts` uses this comparator for the same reason.
+    if (edge.names.length > 0)
+        return [...edge.names].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).join(',');
+    return edge.ordinal === 0 ? '' : `#${String(edge.ordinal)}`;
+}
+/** Which of the five forms this literal belongs to, or `undefined` if none. */
+function kindOf(parent) {
+    if (Node.isImportDeclaration(parent))
+        return 'import';
+    if (Node.isExportDeclaration(parent))
+        return 'reexport';
+    if (Node.isLiteralTypeNode(parent))
+        return 'type-expression';
+    if (Node.isExternalModuleReference(parent))
+        return 'require';
+    if (Node.isCallExpression(parent)) {
+        // The one place `import()` and `require()` are indistinguishable by parent
+        // kind. `reverse-dependency.ts` already discriminates this way.
+        return parent.getExpression().getKind() === SyntaxKind.ImportKeyword ? 'dynamic' : 'require';
+    }
+    return undefined;
+}
+/**
+ * The resolved file, via the **specifier's** symbol.
+ *
+ * One mechanism for all five parent kinds, and it returns the **named** module:
+ * `type A = import('./barrel.js').Deep` resolves to `barrel.ts`, where following
+ * the *type* symbol instead lands on `impl.ts` and would make
+ * `notImportFrom('**\/impl.ts')` fire on a file that never names `impl`.
+ *
+ * **`getDeclarations()[0]` is not the answer.** With a module augmentation
+ * elsewhere in the project, the symbol has two declarations — the `SourceFile`
+ * and a `ModuleDeclaration` in the augmenting file — and `[0]` is whichever the
+ * compiler merged first. ts-morph's own `ModuleUtils.getReferencedSourceFileFromSymbol`
+ * takes `[0]` and bails to `undefined` when it is not a SourceFile, so the other
+ * ordering is live in the reference implementation.
+ *
+ * **How live, measured:** across four shapes — the augmenting file sorting first
+ * alphabetically, two augmentations of one module, a `.d.ts` target, and the
+ * augmentation written inside the importing file itself — the `SourceFile` came
+ * first **every time**. So this is defence against an ordering that is documented
+ * in ts-morph's own code and that no arrangement here reproduces, not a fix for an
+ * observable defect. A review flagged it as a certain field false positive; that
+ * claim did not survive measurement, and saying so is cheaper than a future reader
+ * re-deriving it. `find` costs nothing and cannot be wrong, so it stays — but the
+ * `[0]` variant passes this repo's suite, which is recorded in
+ * `tests/core/module-edges-forms.test.ts` rather than hidden.
+ */
+function resolve(literal) {
+    for (const declaration of literal.getSymbol()?.getDeclarations() ?? []) {
+        if (Node.isSourceFile(declaration))
+            return declaration.getFilePath();
+    }
+    return undefined;
+}
+/**
+ * The line of the statement carrying the edge, not of the literal.
+ *
+ * The nearest **edge-carrying node** — the declaration, call or import-type that
+ * names the module — not the nearest enclosing `Statement`.
+ *
+ * For the declaration forms the two are the same node, so `import` still equals
+ * `decl.getStartLineNumber()` and the corpus equality test holds. They diverge
+ * for an expression form nested inside a larger statement, and there the
+ * statement is the wrong answer: measured, `register({ handlers: { a: () =>
+ * import('./banned.js') } })` spanning lines 3–7 reported **line 3**, pointing the
+ * code frame at `register(` rather than at the import, and a class property
+ * `loader = import('./x.js')` reported the `ClassDeclaration`'s line because a
+ * `PropertyDeclaration` is not a `Statement`. A lazily-loaded route inside an
+ * object literal is the commonest real dynamic import, so that was the common
+ * case rather than a corner.
+ *
+ * Falls back to the literal's own line if no carrier is found, which the 20-form
+ * corpus does not produce — a guard, not a path.
+ */
+function statementLine(literal) {
+    const carrier = literal.getFirstAncestor((a) => Node.isImportDeclaration(a) ||
+        Node.isExportDeclaration(a) ||
+        Node.isImportEqualsDeclaration(a) ||
+        Node.isCallExpression(a) ||
+        Node.isImportTypeNode(a));
+    return (carrier ?? literal).getStartLineNumber();
+}
+/**
+ * Whether the edge is erased at compile time.
+ *
+ * Per kind, and the two constants are the classification traps: `require` is
+ * **runtime** (an `else → type-expression` branch is what made it look erased)
+ * and `dynamic` is always runtime.
+ */
+function isErased(kind, parent) {
+    switch (kind) {
+        case 'import':
+            // Reused unchanged. Its `getDefaultImport()`/`getNamespaceImport()` guards
+            // are load-bearing: `import React, { type FC } from 'react'` is a RUNTIME
+            // edge, and a formula without them classifies it type-only and skips it
+            // under `ignoreTypeImports` — a lost existing finding.
+            return Node.isImportDeclaration(parent) ? isTypeOnlyImport(parent) : false;
+        case 'reexport':
+            return Node.isExportDeclaration(parent) ? isTypeOnlyReExport(parent) : false;
+        case 'type-expression':
+            return true;
+        case 'dynamic':
+        case 'require':
+            return false;
+    }
+}
+/**
+ * Whether the statement vanishes entirely, emitting no module request.
+ *
+ * `typeOnly` is passed in rather than recomputed: the two answers must agree on the
+ * same node, and `isErased` is not free (it walks specifiers).
+ *
+ * Under `verbatimModuleSyntax` TypeScript preserves the statement unless the `type`
+ * modifier is on the **declaration** — `import type { X }` goes, `import { type X }`
+ * stays as `import {} from 's'`. Without the flag, elision is by binding usage and
+ * every type-only form disappears.
+ */
+function erasesRequest(kind, parent, typeOnly, verbatimModuleSyntax) {
+    // A statement that binds a runtime value is always emitted.
+    if (!typeOnly)
+        return false;
+    if (!verbatimModuleSyntax)
+        return true;
+    switch (kind) {
+        case 'import':
+            return Node.isImportDeclaration(parent) ? parent.isTypeOnly() : true;
+        case 'reexport':
+            return Node.isExportDeclaration(parent) ? parent.isTypeOnly() : true;
+        case 'type-expression':
+            // `type X = import('s').Y` is a type position: never emitted under any flag.
+            return true;
+        case 'dynamic':
+        case 'require':
+            // Unreachable — neither is ever `typeOnly` — but stated rather than defaulted,
+            // for the same reason the sibling switches in this file are exhaustive.
+            return false;
+    }
+}
+/**
+ * One edge, built in one place.
+ *
+ * `buildEdges` and `edgeStream` each used to spell out the same field list, which is
+ * a shape that drifts silently: `edgeStream`'s only consumer reads `typeOnly`, so a
+ * field missing there would never surface until something else looked.
+ */
+function makeEdge(literal, parent, kind, verbatimModuleSyntax) {
+    const typeOnly = isErased(kind, parent);
+    return {
+        kind,
+        // `getLiteralText()`, NOT `getText().slice(1, -1)` and NOT a narrowing — see the
+        // module docstring. The declared element type of `getImportStringLiterals()` is
+        // what this parameter takes, so the accessor is available without narrowing a
+        // node that may really be a NoSubstitutionTemplateLiteral.
+        specifier: literal.getLiteralText(),
+        resolvedPath: resolve(literal),
+        line: statementLine(literal),
+        typeOnly,
+        erasesModuleRequest: erasesRequest(kind, parent, typeOnly, verbatimModuleSyntax),
+        names: namesOf(kind, parent),
+        // Filled by the collectors, which are the only callers that can see the file's
+        // other edges. `makeEdge` is per-literal and has no way to count siblings.
+        ordinal: 0,
+    };
+}
+/**
+ * The next ordinal for `kind::specifier`, mutating `counters`.
+ *
+ * Shared by both collectors so they cannot drift: an identity that depended on which
+ * code path built the edge would be worse than the collision it fixes.
+ */
+function nextOrdinal(counters, edge) {
+    const key = `${edge.kind}::${edge.specifier}`;
+    const n = counters.get(key) ?? 0;
+    counters.set(key, n + 1);
+    return n;
+}
+/**
+ * `verbatimModuleSyntax` for the package that owns this file, off when absent.
+ *
+ * Delegated rather than read from the project, because inside a `workspace()` the project
+ * carries the alphabetically-first tsconfig's options and every other package would be
+ * judged by them — wrong in both directions, measured
+ * ([ts-archunit bug 0058](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0058-workspace-applies-one-packages-compiler-flag-to-all.md)).
+ */
+function usesVerbatimModuleSyntax(sourceFile) {
+    return verbatimModuleSyntaxFor(sourceFile);
+}
+/** The names crossing the edge. See {@link ModuleEdge.names} for which name. */
+function namesOf(kind, parent) {
+    if (kind === 'import' && Node.isImportDeclaration(parent)) {
+        // Inward names. A default or namespace binding contributes none — it crosses
+        // under a name the specifier list does not carry.
+        return parent.getNamedImports().map((specifier) => specifier.getName());
+    }
+    if (kind === 'reexport' && Node.isExportDeclaration(parent)) {
+        // `export * as NS` is not a star here: one statically-known name.
+        const namespaceExport = parent.getNamespaceExport();
+        if (namespaceExport !== undefined)
+            return [namespaceExport.getName()];
+        // Outward names, so `export { INNER as OUTER }` reports `OUTER`.
+        return parent
+            .getNamedExports()
+            .map((specifier) => specifier.getAliasNode()?.getText() ?? specifier.getName());
+    }
+    return [];
+}
+/**
+ * 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 function edgeVerb(kind) {
+    return EDGE_WORDS[kind].verb;
+}
+/**
+ * Both words for every edge kind, in one table.
+ *
+ * They were two exhaustive switches over the same union — `no-copy-paste`
+ * reported them at 100% — and keeping them apart is what lets a new kind be
+ * added with a verb and no noun phrase, which compiles: the `Record` makes
+ * that a type error instead, so a kind cannot be half-described.
+ *
+ * `import`'s verb must stay byte-identical. Every existing baselined
+ * dependency finding hashes its message, so changing that one string silently
+ * invalidates them all; the other kinds get distinct verbs precisely so their
+ * findings are NOT absorbed by an existing `import` entry for the same module.
+ */
+const EDGE_WORDS = {
+    import: { verb: 'imports', valuePhrase: 'a value import from' },
+    reexport: { verb: 're-exports', valuePhrase: 'a runtime re-export of' },
+    dynamic: { verb: 'dynamically imports', valuePhrase: 'a dynamic import of' },
+    'type-expression': {
+        verb: 'references the type from',
+        valuePhrase: 'a type reference to',
+    },
+    require: { verb: 'requires', valuePhrase: 'a require call for' },
+};
+/**
+ * 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 function edgeValuePhrase(kind) {
+    return EDGE_WORDS[kind].valuePhrase;
+}
+/**
+ * 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 function edgeTypeOnlyRemedy(edge) {
+    switch (edge.kind) {
+        case 'import':
+            return 'Change it to `import type { … }` so the dependency is erased at compile time.';
+        case 'reexport':
+            // A STAR re-export has no names to put in the braces, and telling the reader
+            // to write `export type { … } from` there asks them to enumerate the target's
+            // entire export list — which an agent will invent rather than look up.
+            // `export type * from` is the one-token fix, and `isTypeOnlyReExport`
+            // already recognises it.
+            if (edge.names.length === 0) {
+                return ('Change it to `export type * from …`, which erases the dependency. Note this removes the ' +
+                    'runtime re-exports too — check no consumer imports any of them as a value.');
+            }
+            return ('Change it to `export type { … } from …`, which erases the dependency but also removes a ' +
+                'runtime export — check no consumer imports it as a value. If one does, re-export it from ' +
+                'a module this rule permits, or stop re-exporting it here.');
+        case 'dynamic':
+            return 'A dynamic import cannot be erased. Move the dependency behind an interface this rule permits.';
+        case 'type-expression':
+            return 'This edge is already erased; no change is needed.';
+        case 'require':
+            return 'Convert the `require` to an `import type { … }`, or move the dependency.';
+    }
+}
+/**
+ * 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 const FORWARD_EDGE_KINDS = {
+    import: true,
+    reexport: true,
+    dynamic: true,
+    'type-expression': true,
+    require: false,
+};
+/**
+ * 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 function* edgeStream(sourceFile) {
+    // Warm: yield the already-built edges. The caller still breaks early, and
+    // iterating a materialized array costs nothing — the resolution it was
+    // avoiding has already happened.
+    const hit = cache.get(sourceFile);
+    if (hit !== undefined) {
+        yield* hit;
+        return;
+    }
+    const verbatim = usesVerbatimModuleSyntax(sourceFile);
+    // Cold: stream, and deliberately do NOT populate the cache. Filling it here
+    // would resolve every literal in the file to answer a question the first one
+    // may settle, which is the cost this generator exists to avoid
+    // (`dependency.ts:327-334`).
+    // Sorted by position, so `ordinal` matches what `buildEdges` assigns. The binder's
+    // array puts declaration forms before expression forms regardless of where they
+    // appear, so without this a file mixing `import` and `import()` of the same module
+    // gets different ordinals depending on which collector ran — and the identity would
+    // depend on whether the cache was warm. Sorting costs a comparison per literal and
+    // resolves nothing, so the early exit this generator exists for is untouched.
+    const literals = [...sourceFile.getImportStringLiterals()].sort((a, b) => a.getPos() - b.getPos());
+    const counters = new Map();
+    for (const literal of literals) {
+        const parent = literal.getParent();
+        if (parent === undefined)
+            continue;
+        const kind = kindOf(parent);
+        if (kind === undefined)
+            continue;
+        const edge = makeEdge(literal, parent, kind, verbatim);
+        yield { ...edge, ordinal: nextOrdinal(counters, edge) };
+    }
+}
+export function edgeTypeOnlyNoun(kind) {
+    switch (kind) {
+        case 'import':
+        case 'dynamic':
+        case 'require':
+            return 'import';
+        case 'reexport':
+            return 're-export';
+        case 'type-expression':
+            return 'reference';
+    }
+}
+//# sourceMappingURL=module-edges.js.map

package/dist/core/module-edges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-edges.js","sourceRoot":"","sources":["../../src/core/module-edges.ts"],"names":[],"mappings":"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"}

package/dist/core/object-literal-functions.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Object-literal function traversal. **In `core/` because it was the wrong way up.**
+ *
+ * It lived in `helpers/` and was imported by `models/arch-function.ts` — a
+ * `models → helpers` edge, which is backwards: helpers may depend on models, not
+ * the reverse. That edge sat harmlessly until
+ * [ts-archunit plan 0082](https://github.com/nielspeter/ts-archunit/blob/main/plans/completed/0082-an-object-literal-callback-keeps-its-name.md)
+ * added `helpers/callback-extractor.ts → models/arch-function.ts` as a **value**
+ * import, closing a runtime cycle.
+ *
+ * Measured: at v0.45.6 no file in `helpers/` had a value import from `models/` —
+ * only `import type`. So the cycle was one day old when
+ * [ts-archunit plan 0084](https://github.com/nielspeter/ts-archunit/blob/main/plans/completed/0084-cycle-detection-that-ignores-type-only-imports.md)
+ * found it, and the rule that exists to catch exactly this was pinned at `.warn()`
+ * with a comment explaining why. A rule that cannot fail let a cycle in overnight.
+ *
+ * This module imports nothing but ts-morph, so `core/` costs it no dependency and
+ * both `models → core` and `helpers → core` are permitted directions.
+ */
+import { Node } from 'ts-morph';
+/**
+ * A function found as a value in an object literal, with the property-key path
+ * that reached it.
+ */
+export interface ObjectLiteralFunction {
+    /** The function node: `ArrowFunction | FunctionExpression | MethodDeclaration`. */
+    readonly node: Node;
+    /** Property-key path from the root object literal, e.g. `['routes', '/x', 'GET']`. */
+    readonly keyPath: readonly string[];
+}
+/**
+ * Walk an object literal and collect every function-valued property — arrow,
+ * function expression, or method shorthand — recursing into nested object
+ * literals up to `maxDepth`. Call-agnostic (F3): the single traversal shared by
+ * `functions()` object-literal collection (proposal 016) and the
+ * callback-extractor (`within()` / call path), so the two cannot drift.
+ *
+ * Only descends into nested object-literal property values, never into function
+ * bodies. Returns `[]` when `node` is not an object literal.
+ */
+export declare function collectObjectLiteralFunctions(node: Node, maxDepth?: number): ObjectLiteralFunction[];
+//# sourceMappingURL=object-literal-functions.d.ts.map

package/dist/core/object-literal-functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-literal-functions.d.ts","sourceRoot":"","sources":["../../src/core/object-literal-functions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAG/B;;;GAGG;AAEH,MAAM,WAAW,qBAAqB;IACpC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAKD;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,IAAI,EACV,QAAQ,GAAE,MAAiC,GAC1C,qBAAqB,EAAE,CAIzB"}