@nielspeter/eess-ts 0.2.1 → 0.5.0

package/dist/core/disk-set.d.ts

@@ -0,0 +1,48 @@
+import type { ArchProject } from './project.js';
+/**
+ * What the filesystem says about a glob that the compiler's file set does not.
+ *
+ * Only populated for `no-match` — the other faults are syntactic and the disk
+ * has nothing to add. `not-determined` is the honest answer above the walk's
+ * entry budget, or where the walk refused to look.
+ *
+ * Declared here rather than in `glob-diagnosis.ts` because this is the module
+ * that produces it: the other way round made the two files import each other.
+ * Both edges were `import type` and therefore erased at runtime — but our own
+ * `arch/no-cycles` rule slices by directory, so it could not see a cycle
+ * INSIDE `core/`, and a per-file slicing in a test found it immediately. A
+ * cycle nothing can see is the shape this whole plan is about.
+ */
+export type OnDisk = 'holds-typescript' | 'no-typescript' | 'absent' | 'not-determined';
+/**
+ * What the filesystem knows that the compiler's file set does not.
+ *
+ * The second derivation ADR-009 rule 5 asks for: filesystem contents versus
+ * compiler membership. It is what distinguishes "your glob is misspelled" from
+ * "your glob is fine and your tsconfig scope excludes it" — the cheapest wrong
+ * action an agent can take, and the majority case in a real monorepo.
+ */
+export interface DiskSet {
+    /** Classify a glob by what exists on disk under the paths it matches. */
+    classify(glob: string): OnDisk;
+}
+/**
+ * The project's disk set, walked at most once and only when asked.
+ *
+ * Lazy on purpose. This is only ever reached from `diagnoseGlob`, which is
+ * only ever reached from an already-firing fault, so a project with no faults
+ * never touches the filesystem. An eager version would charge every `check()`
+ * a recursive walk to answer a question no fault asked.
+ */
+export declare function diskSet(project: ArchProject): DiskSet;
+/**
+ * The walk, with the budget injectable.
+ *
+ * Exported for tests only. The degrade path is the difference between "not
+ * determined" and a *partial, wrong* classification — a false "contains no
+ * TypeScript" in the one message whose whole defence is that it states only
+ * facts — and with the budget a module constant it could only ever have been
+ * reached by accident on a repository nobody has.
+ */
+export declare function buildDiskSet(project: ArchProject, budgetLimit?: number): DiskSet;
+//# sourceMappingURL=disk-set.d.ts.map

package/dist/core/disk-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disk-set.d.ts","sourceRoot":"","sources":["../../src/core/disk-set.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAkD/C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,MAAM,GAAG,kBAAkB,GAAG,eAAe,GAAG,QAAQ,GAAG,gBAAgB,CAAA;AAEvF;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAC/B;AAID;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAMrD;AAED;;;;;;;;GAQG;AAEH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,WAAW,SAAe,GAAG,OAAO,CAEtF"}

package/dist/core/disk-set.js

@@ -0,0 +1,218 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { discoverIdentityRoot } from '@nielspeter/eess/internal';
+/**
+ * Directories never worth walking.
+ *
+ * `node_modules` and `.git` dominate the cost. The build-output names are here
+ * because a walk that reports `dist/` as "absent from the project" is noise,
+ * not a finding. The list cannot be complete — a real TypeScript monorepo may
+ * hold a Rust `target/`, a Python `.venv`, a `.gradle` — which is why the
+ * entry budget below exists rather than a longer list.
+ */
+const PRUNE = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    '.next',
+    '.turbo',
+    '.venv',
+    'vendor',
+    'target',
+    '.gradle',
+    '.yarn',
+    '.cache',
+]);
+/**
+ * How many directory entries the walk will read before giving up.
+ *
+ * An implementation constant, not part of the public contract and not
+ * tunable. It exists because the walk is unbounded in principle: a
+ * contributor who has run `cargo build` inside a TypeScript monorepo has tens
+ * of thousands of entries under one directory, and a *failing* run that then
+ * hangs inside a 5s vitest timeout is a worse experience than the false green
+ * this whole mechanism exists to remove. Above the budget the classification
+ * degrades to `not-determined`, which costs message quality and nothing else —
+ * the enrichment is already fail-open.
+ */
+const ENTRY_BUDGET = 50_000;
+// `.d.ts` and its `.d.mts`/`.d.cts` siblings count. They ARE TypeScript for
+// the question this set answers — "does this path contain TypeScript your
+// tsconfig is keeping out" — and excluding them made a `types/` directory of
+// pure declarations report "this path exists but contains no TypeScript",
+// which is false.
+const TS_FILE = /\.(m|c)?tsx?$/;
+const cache = new WeakMap();
+/**
+ * The project's disk set, walked at most once and only when asked.
+ *
+ * Lazy on purpose. This is only ever reached from `diagnoseGlob`, which is
+ * only ever reached from an already-firing fault, so a project with no faults
+ * never touches the filesystem. An eager version would charge every `check()`
+ * a recursive walk to answer a question no fault asked.
+ */
+export function diskSet(project) {
+    const cached = cache.get(project);
+    if (cached)
+        return cached;
+    const built = build(project, ENTRY_BUDGET);
+    cache.set(project, built);
+    return built;
+}
+/**
+ * The walk, with the budget injectable.
+ *
+ * Exported for tests only. The degrade path is the difference between "not
+ * determined" and a *partial, wrong* classification — a false "contains no
+ * TypeScript" in the one message whose whole defence is that it states only
+ * facts — and with the budget a module constant it could only ever have been
+ * reached by accident on a repository nobody has.
+ */
+// eess-exclude eess/no-unused-exports: consumed by the test suite; the build tsconfig this gate reads excludes tests, so `src` is the only usage it can see
+export function buildDiskSet(project, budgetLimit = ENTRY_BUDGET) {
+    return build(project, budgetLimit);
+}
+function build(project, budgetLimit) {
+    // Guard on the INPUT, before deriving anything. `discoverIdentityRoot` calls
+    // `path.resolve`, so every root it returns is absolute and checking the
+    // output can never fail. Both halves matter, and this repo's own suite
+    // supplies both: the relative `'in-memory'` double (whose dirname is '.',
+    // which would walk the real CWD) and absolute paths that do not exist, where
+    // `readdirSync` throws from inside a guard. Counted in prose as "eight
+    // doubles, two relative" until the suite reached 114 of them — so the shapes
+    // are named and the arithmetic is not. And `ArchProject` is a public type, so
+    // this protects user-constructed projects, not only test doubles.
+    if (!path.isAbsolute(project.tsConfigPath))
+        return UNDETERMINED;
+    const root = discoverIdentityRoot(path.dirname(project.tsConfigPath));
+    if (!fs.existsSync(root))
+        return UNDETERMINED;
+    const files = [];
+    /** Every file, TypeScript or not — so `absent` means absent, not "not TypeScript". */
+    const everyFile = [];
+    const dirs = [];
+    /**
+     * Directories the walk refused to enter.
+     *
+     * A glob matching one of these cannot be classified: nothing under it was
+     * seen. Reporting `absent` would say "this path does not exist" about
+     * `**\/dist/**` or `**\/vendor/**` — all realistic rule scopes — and
+     * `absent` carries no advice, so the caller then falls back to a cause list
+     * beginning "a path segment is misspelled".
+     */
+    const pruned = [];
+    let budget = budgetLimit;
+    let exhausted = false;
+    const walk = (dir) => {
+        if (exhausted)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            void err; // unreadable or gone: not a finding, just not walkable
+            return;
+        }
+        budget -= entries.length;
+        if (budget < 0) {
+            exhausted = true;
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name).replaceAll('\\', '/');
+            // Prune by NAME, before asking whether it is a directory.
+            //
+            // [ts-archunit Bug 0045](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0045-two-tests-fail-by-environment-and-corrupt-sabotage-verdicts.md):
+            // `Dirent.isDirectory()` is false for a symlink, so a symlinked
+            // `node_modules` — what pnpm produces, and what `git worktree add`
+            // leaves behind — fell through to the `else` branch and was recorded as
+            // a **file**. It never entered `pruned`, so a glob under it classified
+            // `absent` ("no such path") instead of `not-determined` ("this walk
+            // cannot say"). Those carry different advice, and `absent` is the one
+            // that asserts something false.
+            //
+            // Safe: pruning records the path and does not recurse, so no link is
+            // followed and the loop argument below is untouched.
+            if (PRUNE.has(entry.name)) {
+                pruned.push(full);
+                continue;
+            }
+            // `Dirent.isDirectory()` is false for a symlink under `withFileTypes`,
+            // so symlink loops are impossible by construction. Do not "fix" this
+            // with `statSync`, which follows them.
+            //
+            // The cost, for symlinks we do NOT prune: a symlinked source directory —
+            // pnpm and yarn workspaces create them — is recorded as a file, so a glob
+            // naming it classifies `no-typescript`. Wrong, but wrong in the direction
+            // that only weakens a message; following the link risks a walk that never
+            // terminates.
+            if (entry.isDirectory()) {
+                dirs.push(full);
+                walk(full);
+            }
+            else {
+                everyFile.push(full);
+                if (TS_FILE.test(entry.name))
+                    files.push(full);
+            }
+        }
+    };
+    walk(root.replaceAll('\\', '/'));
+    if (exhausted)
+        return UNDETERMINED;
+    // Containment is TRANSITIVE, and that is load-bearing. Using each file's
+    // immediate parent instead labels `docs/` "contains no TypeScript" while
+    // `docs/.vitepress/config.ts` sits one level below it — a false statement in
+    // the one message whose entire defence is that it states only facts.
+    // Measured on this repo: 36 directories hold TypeScript transitively but not
+    // directly.
+    const holdsTypeScript = new Set();
+    for (const file of files) {
+        let dir = path.dirname(file);
+        while (dir.length >= root.length) {
+            holdsTypeScript.add(dir);
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    // Directories AND every file, not just the TypeScript ones. Deriving
+    // `absent` from the TypeScript-only set asserted "this path does not exist"
+    // about any path holding a `.md`, a `.json`, or anything under a pruned
+    // name — and `absent` carries no advice, so the caller fell back to
+    // `no-match`'s list, whose first cause is "a path segment is misspelled".
+    // Exactly the confidently-wrong cause ADR-009 rule 2 forbids.
+    const everything = [...everyFile, ...dirs];
+    const typeScript = new Set(files);
+    return {
+        classify(glob) {
+            const isMatch = picomatch(glob);
+            // Never `everything.some(isMatch)` — picomatch reads the array index as
+            // its second argument and returns a truthy object from index 1 onwards.
+            const matched = everything.filter((candidate) => isMatch(candidate));
+            if (matched.length === 0) {
+                // Not seen is not the same as not there.
+                return pruned.some((dir) => isMatch(dir) || glob.includes(dir.slice(root.length + 1)))
+                    ? 'not-determined'
+                    : 'absent';
+            }
+            // Per GLOB, not per path: one glob routinely matches paths in both
+            // categories — `**/tests/**` matched 44 directories of mixed kind on the
+            // monorepo this was gated against. Any matched path holding TypeScript
+            // makes the tsconfig the story worth telling.
+            return matched.some((candidate) => holdsTypeScript.has(candidate) || typeScript.has(candidate))
+                ? 'holds-typescript'
+                : 'no-typescript';
+        },
+    };
+}
+const UNDETERMINED = {
+    classify: () => 'not-determined',
+};
+//# sourceMappingURL=disk-set.js.map

package/dist/core/disk-set.js.map

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

package/dist/core/element-cache.d.ts

@@ -0,0 +1,75 @@
+import type { ArchProject } from './project.js';
+/**
+ * Collect a builder's elements once per project instead of once per rule.
+ *
+ * Plan 0075. `filterElements()` calls `getElements()` on every rule execution
+ * and each builder re-collects from scratch, so a suite with five `calls()`
+ * rules walks every file's AST five times. Measured on this repository (518
+ * files): **5 × `calls()` issued 2,600 `getDescendantsOfKind` queries in 692ms;
+ * with this memo, 0 in 3ms warm** — measured against the implementation by
+ * stashing it, not projected from a prototype.
+ *
+ * ## Why a factory rather than one shared map
+ *
+ * A single `WeakMap<ArchProject, Map<string, unknown[]>>` would need a cast to
+ * hand `unknown[]` back as `ArchCall[]`, and ADR-005 bars both `any` and `as`.
+ * Each builder module instead creates its own instance at module scope, closed
+ * over its own element type, so the type survives end to end with no assertion.
+ *
+ * ## Why `WeakMap`, keyed on the project object
+ *
+ * The same shape `src/core/disk-set.ts:83` and `src/core/path-universe.ts:35`
+ * already use. Keying on **object identity** is what makes a stale entry
+ * unreachable: `resetProjectCache()` (`project.ts:178`) clears the `project()`
+ * and `workspace()` maps, so the next call constructs a new object literal and
+ * therefore a new key. Watch mode depends on that, and it is where a stale
+ * cache would be an ADR-008 failure rather than a slow test — a rule
+ * re-evaluated against a pre-edit AST reports a pass the edit did not earn. A
+ * cache keyed on `tsConfigPath` would pass this repository's whole suite and
+ * silently break watch mode.
+ *
+ * ## What it does not cover, measured rather than asserted
+ *
+ * An `ArchProject` a consumer built themselves and holds across a change to the
+ * underlying ts-morph project. An earlier version of this docstring said the memo
+ * "does not worsen" that case. **It does**, and review measured it:
+ *
+ *     classes(p).subjects()            -> One
+ *     m.createSourceFile('/two.ts', …)
+ *     classes(p).subjects()            -> One      (before this cache: One, Two)
+ *
+ * The population is frozen at first collection for the lifetime of the project
+ * object, so a rule about `Two` selects nothing and passes — an ADR-008 false
+ * green manufactured by a cache. Re-collection used to heal it.
+ *
+ * Two things make it survivable, and both are load-bearing rather than
+ * reassuring: the CLI is unaffected, because `resetProjectCache()`
+ * (`project.ts`) builds a new `ArchProject` per run and `--watch` calls it; and
+ * `resetProjectCache()` now **also clears these caches**, so a consumer holding
+ * their own project object has a documented way out. Call it after mutating.
+ *
+ * ## What must NOT be cached through this
+ *
+ * The **unfiltered** `getElements()` result only. `filterElements()`
+ * unconditionally calls `.filter(...)`, which always allocates, so `subjects()`
+ * keeps handing out a fresh array and no caller can alias the cached one.
+ * Memoizing `filterElements()` instead would break that *and* be wrong:
+ * `ScopedFunctionRuleBuilder` overrides `getElements()` to draw from a call
+ * selection rather than the project, so a shared key would serve
+ * `within(sel).functions()` the plain `functions()` population and let
+ * `.should().notExist()` pass vacuously.
+ */
+interface ElementCache<T> {
+    /**
+     * The cached collection for `project` under `key`, collecting it on first
+     * ask. `key` distinguishes populations that differ for the same project —
+     * see `FunctionRuleBuilder`, whose collection options change what it returns.
+     */
+    get(project: ArchProject, key: string, collect: () => T[]): T[];
+}
+/** A cache private to one builder module, typed to that builder's element. */
+export declare function createElementCache<T>(): ElementCache<T>;
+/** The key for builders whose population is a function of the project alone. */
+export declare const SOLE_POPULATION = "default";
+export {};
+//# sourceMappingURL=element-cache.d.ts.map

package/dist/core/element-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-cache.d.ts","sourceRoot":"","sources":["../../src/core/element-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,UAAU,YAAY,CAAC,CAAC;IACtB;;;;OAIG;IACH,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,EAAE,CAAA;CAChE;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,CA0BvD;AAED,gFAAgF;AAChF,eAAO,MAAM,eAAe,YAAY,CAAA"}

package/dist/core/element-cache.js

@@ -0,0 +1,32 @@
+import { registerCacheReset } from '@nielspeter/eess/internal';
+/** A cache private to one builder module, typed to that builder's element. */
+export function createElementCache() {
+    let perProject = new WeakMap();
+    // Registered rather than exported: a `clearElementCaches()` that `project.ts`
+    // imported directly would close the cycle `project -> element-cache -> project`
+    // (the back edge is `import type { ArchProject }`, which counts).
+    registerCacheReset(() => {
+        perProject = new WeakMap();
+    });
+    return {
+        get(project, key, collect) {
+            let byKey = perProject.get(project);
+            if (byKey === undefined) {
+                byKey = new Map();
+                perProject.set(project, byKey);
+            }
+            const hit = byKey.get(key);
+            // `has`, not truthiness: a legitimately empty collection is `[]`, and
+            // `[]` is truthy — but an empty project is exactly the case where
+            // re-collecting on every rule is pure waste, so it must cache too.
+            if (hit !== undefined)
+                return hit;
+            const fresh = collect();
+            byKey.set(key, fresh);
+            return fresh;
+        },
+    };
+}
+/** The key for builders whose population is a function of the project alone. */
+export const SOLE_POPULATION = 'default';
+//# sourceMappingURL=element-cache.js.map

package/dist/core/element-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-cache.js","sourceRoot":"","sources":["../../src/core/element-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAuE9D,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB;IAChC,IAAI,UAAU,GAAG,IAAI,OAAO,EAAiC,CAAA;IAC7D,8EAA8E;IAC9E,gFAAgF;IAChF,kEAAkE;IAClE,kBAAkB,CAAC,GAAG,EAAE;QACtB,UAAU,GAAG,IAAI,OAAO,EAAiC,CAAA;IAC3D,CAAC,CAAC,CAAA;IAEF,OAAO;QACL,GAAG,CAAC,OAAoB,EAAE,GAAW,EAAE,OAAkB;YACvD,IAAI,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,KAAK,GAAG,IAAI,GAAG,EAAe,CAAA;gBAC9B,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;YAChC,CAAC;YACD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC1B,sEAAsE;YACtE,kEAAkE;YAClE,mEAAmE;YACnE,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,GAAG,CAAA;YACjC,MAAM,KAAK,GAAG,OAAO,EAAE,CAAA;YACvB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YACrB,OAAO,KAAK,CAAA;QACd,CAAC;KACF,CAAA;AACH,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAA"}

package/dist/core/empty-project-advice.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The one text for "this project loaded nothing", owned in one place.
+ *
+ * Two surfaces state this fact: `diagnose()` (and through it `doctor`) and
+ * `SliceRuleBuilder`'s discovery message, which is what a **failing `check`
+ * build** prints. They were written separately and had already diverged at
+ * birth — the builder said only "Check that this tsconfig includes your
+ * sources", which bug 0031 itself records as not actionable for a config that
+ * has no `include` at all, while `diagnose` named the solution-style cause. So
+ * the high-stakes surface carried the weaker text.
+ *
+ * This is the `assertionAdvice` precedent applied to a second state: plan 0070
+ * put that one behind a single owner after the two copies were **measured**
+ * diverging, and a later review found a third copy re-added with nothing
+ * failing. Two texts for one state is a trust problem for an agent diffing
+ * them.
+ *
+ * Reported by review of the bug 0031 fix, which created the second copy while
+ * quoting the bug's own instruction not to.
+ */
+import type { ArchProject } from './project.js';
+/**
+ * Why nothing can match, and what to do about it.
+ *
+ * Deliberately **not** ending in a period: both call sites append their own
+ * trailing sentence.
+ *
+ * ## The solution-style clause is conditional, and that is the point
+ *
+ * An earlier revision **asserted** it — "this one is solution-style, so point
+ * the rules at the tsconfig that does" — and review refuted that: the imperative
+ * is impossible on several reachable shapes with no such sibling (an `include`
+ * that matches nothing yet, a repository with no `.ts` files, `allowJs: false`
+ * over a `.js` tree, `"files": []` with no `references` at all). ADR-008
+ * rule 2 — a stated fix that is impossible on the path that produced it is
+ * worse than none.
+ *
+ * The obvious repair was to read the tsconfig and state it only when true. That
+ * was **written, and then removed by this project's own architecture rules**:
+ * it put `JSON.parse` in `src/core/`, which `hygiene/no-json-parse` bans with
+ * the reason "eess-ts analyzes AST, not JSON", and `references` is not in
+ * `getCompilerOptions()` so ts-morph cannot supply it (ADR-002 rules out the
+ * raw TypeScript API). Exempting the rule to accommodate this file would be
+ * the wrong direction — the rule is right.
+ *
+ * So the clause is phrased as a **condition the reader can evaluate in one
+ * glance at their own file**. It is true whether or not their config has that
+ * shape, it names the mechanism that produced the commonest real occurrence,
+ * and it asserts nothing the tool has not checked.
+ */
+/**
+ * Did this project load nothing at all?
+ *
+ * The **decision**, extracted — [ts-archunit bug 0048](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0048-the-dead-glob-gate-blames-the-glob-when-the-project-is-empty.md).
+ *
+ * `emptyProjectAdvice` already owned the *text*, and that was taken to mean the
+ * state had one owner. It did not: the test `if (getSourceFiles().length === 0)`
+ * lived in `diagnose.ts` and in `SliceRuleBuilder`, and **not** in the assertion
+ * gate — so a selector-position glob in an empty project was told its glob could
+ * never match and to correct it. The glob was correct; the tsconfig loaded
+ * nothing.
+ *
+ * Measured on `tests/fixtures/does-not-load`: the selector path said *"This
+ * rule's selector … can never match anything … Correct the glob, or remove the
+ * rule"* while `doctor` and the slice path both said *"The project loaded 0
+ * source files"*.
+ *
+ * Two texts for one state is a trust problem for an agent diffing them — which
+ * is this file's original argument. Two **decisions** about when to use the one
+ * text is the same problem one level up, and it is the level the first fix
+ * missed.
+ */
+export declare function loadedNothing(project: ArchProject): boolean;
+export declare function emptyProjectAdvice(project: ArchProject): string;
+//# sourceMappingURL=empty-project-advice.d.ts.map

package/dist/core/empty-project-advice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-project-advice.d.ts","sourceRoot":"","sources":["../../src/core/empty-project-advice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAO/D"}

package/dist/core/empty-project-advice.js

@@ -0,0 +1,61 @@
+/**
+ * Why nothing can match, and what to do about it.
+ *
+ * Deliberately **not** ending in a period: both call sites append their own
+ * trailing sentence.
+ *
+ * ## The solution-style clause is conditional, and that is the point
+ *
+ * An earlier revision **asserted** it — "this one is solution-style, so point
+ * the rules at the tsconfig that does" — and review refuted that: the imperative
+ * is impossible on several reachable shapes with no such sibling (an `include`
+ * that matches nothing yet, a repository with no `.ts` files, `allowJs: false`
+ * over a `.js` tree, `"files": []` with no `references` at all). ADR-008
+ * rule 2 — a stated fix that is impossible on the path that produced it is
+ * worse than none.
+ *
+ * The obvious repair was to read the tsconfig and state it only when true. That
+ * was **written, and then removed by this project's own architecture rules**:
+ * it put `JSON.parse` in `src/core/`, which `hygiene/no-json-parse` bans with
+ * the reason "eess-ts analyzes AST, not JSON", and `references` is not in
+ * `getCompilerOptions()` so ts-morph cannot supply it (ADR-002 rules out the
+ * raw TypeScript API). Exempting the rule to accommodate this file would be
+ * the wrong direction — the rule is right.
+ *
+ * So the clause is phrased as a **condition the reader can evaluate in one
+ * glance at their own file**. It is true whether or not their config has that
+ * shape, it names the mechanism that produced the commonest real occurrence,
+ * and it asserts nothing the tool has not checked.
+ */
+/**
+ * Did this project load nothing at all?
+ *
+ * The **decision**, extracted — [ts-archunit bug 0048](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0048-the-dead-glob-gate-blames-the-glob-when-the-project-is-empty.md).
+ *
+ * `emptyProjectAdvice` already owned the *text*, and that was taken to mean the
+ * state had one owner. It did not: the test `if (getSourceFiles().length === 0)`
+ * lived in `diagnose.ts` and in `SliceRuleBuilder`, and **not** in the assertion
+ * gate — so a selector-position glob in an empty project was told its glob could
+ * never match and to correct it. The glob was correct; the tsconfig loaded
+ * nothing.
+ *
+ * Measured on `tests/fixtures/does-not-load`: the selector path said *"This
+ * rule's selector … can never match anything … Correct the glob, or remove the
+ * rule"* while `doctor` and the slice path both said *"The project loaded 0
+ * source files"*.
+ *
+ * Two texts for one state is a trust problem for an agent diffing them — which
+ * is this file's original argument. Two **decisions** about when to use the one
+ * text is the same problem one level up, and it is the level the first fix
+ * missed.
+ */
+export function loadedNothing(project) {
+    return project.getSourceFiles().length === 0;
+}
+export function emptyProjectAdvice(project) {
+    return (`the project loaded 0 source files (${project.tsConfigPath}), so no glob can match. ` +
+        `Check that this tsconfig includes your sources — and if it delegates to project ` +
+        `references ("files": [] with "references"), it loads none of them itself, so the rules ` +
+        `need the tsconfig that holds your sources rather than this one`);
+}
+//# sourceMappingURL=empty-project-advice.js.map

package/dist/core/empty-project-advice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-project-advice.js","sourceRoot":"","sources":["../../src/core/empty-project-advice.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,aAAa,CAAC,OAAoB;IAChD,OAAO,OAAO,CAAC,cAAc,EAAE,CAAC,MAAM,KAAK,CAAC,CAAA;AAC9C,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAoB;IACrD,OAAO,CACL,sCAAsC,OAAO,CAAC,YAAY,2BAA2B;QACrF,kFAAkF;QAClF,yFAAyF;QACzF,gEAAgE,CACjE,CAAA;AACH,CAAC"}

package/dist/core/exclusion-comments.d.ts

@@ -0,0 +1,19 @@
+import { isExcludedByComment as isExcludedShared } from '@nielspeter/eess';
+import type { ExclusionComment, ExclusionWarning, ParseResult } from '@nielspeter/eess';
+/**
+ * Exclusion comments for `eess-ts` — the kernel's parser, with this dialect's
+ * lexer.
+ *
+ * **This file used to be a second parser** (426 lines), and it drifted: bug
+ * 0158's fix landed on the kernel copy and never reached here, so a bare
+ * `eess-exclude-start` was silent in `eess-ts` and blamed the `-end` line when it
+ * did speak. That is bug 0227, and it is why ADR-012 exists.
+ *
+ * What was ever this package's own is the masker — knowing which spans of a
+ * `.ts` file are string literals needs a TypeScript parser, and the kernel
+ * cannot have one. That is now the only thing passed across.
+ */
+export type { ExclusionComment, ExclusionWarning, ParseResult };
+export declare function parseExclusionComments(sourceText: string, filePath: string): ParseResult;
+export declare const isExcludedByComment: typeof isExcludedShared;
+//# sourceMappingURL=exclusion-comments.d.ts.map

package/dist/core/exclusion-comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclusion-comments.d.ts","sourceRoot":"","sources":["../../src/core/exclusion-comments.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,mBAAmB,IAAI,gBAAgB,EACxC,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGvF;;;;;;;;;;;;GAYG;AACH,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,CAAA;AAE/D,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAExF;AAED,eAAO,MAAM,mBAAmB,yBAAmB,CAAA"}

package/dist/core/exclusion-comments.js

@@ -0,0 +1,7 @@
+import { parseExclusionComments as parseShared, isExcludedByComment as isExcludedShared, } from '@nielspeter/eess';
+import { maskTsLiterals } from './ts-comment-mask.js';
+export function parseExclusionComments(sourceText, filePath) {
+    return parseShared(sourceText, filePath, { mask: maskTsLiterals });
+}
+export const isExcludedByComment = isExcludedShared;
+//# sourceMappingURL=exclusion-comments.js.map

package/dist/core/exclusion-comments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclusion-comments.js","sourceRoot":"","sources":["../../src/core/exclusion-comments.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,IAAI,WAAW,EACrC,mBAAmB,IAAI,gBAAgB,GACxC,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAiBrD,MAAM,UAAU,sBAAsB,CAAC,UAAkB,EAAE,QAAgB;IACzE,OAAO,WAAW,CAAC,UAAU,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAA;AACpE,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAAA"}