@nielspeter/eess 0.2.2 → 0.5.0

package/dist/violation.js

@@ -1,2 +1,263 @@
-export {};
+import { registerCacheReset } from './cache-registry.js';
+/**
+ * Extract a human-readable name from a ts-morph Node.
+ *
+ * If the node itself is a named declaration (class, function, method, etc.),
+ * returns its name directly. Otherwise, walks up the AST ancestors to find
+ * the nearest named declaration and builds a qualified name like
+ * "ClassName.methodName". This ensures that inner nodes (e.g., AsExpression,
+ * CallExpression) produce meaningful element names for `.excluding()` matching.
+ *
+ * Falls back to the node's kind name only if no named ancestor is found
+ * (e.g., top-level expressions in a module).
+ */
+/**
+ * Force a configuration meta-finding to `error`, whatever the rule asked for.
+ *
+ * A `bypassFilters` finding reports that the rule enforces **nothing**. That is
+ * not a violation the author gets to grade: `.asSeverity('warn')` says "these
+ * violations are advisory", and a rule that cannot fire has no violations to
+ * be advisory about. Under ADR-009 rule 1 an actionable finding must fail, and
+ * the other suppression paths already refuse to silence these — `.excluding()`
+ * refuses explicitly, baseline and diff honour the flag. The full roster is
+ * `UNSUPPRESSABLE_MECHANISMS` in `unsuppressable.ts`, which is also what the
+ * user-facing sentence is built from; it has grown twice, so it is named here
+ * rather than counted. (This paragraph said "three of the four" while the list
+ * stood at six.)
+ *
+ * Applied at all three severity-stamping sites. `stampSeverity` alone is not
+ * enough: `.violations()` inlines its own map in both root builders, and the
+ * `executeWarn` path resolves an unset severity to `warn`, which is where most
+ * producers landed.
+ */
+export function severityFor(violation, fallback) {
+    return violation.bypassFilters === true ? 'error' : fallback;
+}
+/**
+ * True when a violation's remedy **is** its message, so a renderer that has
+ * already shown the message must not append a `Fix:` line repeating it.
+ *
+ * The assertion gate's finding reports that a rule cannot fire; there, the fault
+ * and its remedy are one sentence, and both fields carry that sentence on
+ * purpose — the JSON payload reads `suggestion`, a human reads the body, and a
+ * configuration finding is the one kind that cannot fall back to the author's
+ * `suggestion` (`execute-rule.ts` refuses it, bug 0021). Measured before the
+ * fix: every surface printed the same paragraph twice.
+ *
+ * One definition, because the three renderers must not disagree about it.
+ * Whether a given renderer *did* render the message stays renderer-local: the
+ * rich terminal format shows it only for a location-less finding, while the
+ * plain and GitHub formats always do.
+ */
+export function remedyRepeatsMessage(violation) {
+    return violation.suggestion !== undefined && violation.suggestion === violation.message;
+}
+/**
+ * Unicode codepoint order — the only comparator admissible anywhere a baseline identity, an
+ * `element`, or a reported location is derived from a sort.
+ *
+ * `String.prototype.localeCompare` without an explicit locale reads the **host** locale from
+ * `LANG`/`LC_ALL`, so a value sorted with it differs between a developer's machine and CI.
+ * 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`. One
+ * finding, two baseline hashes, diverging only in the place hardest to debug.
+ *
+ * The codebase already knew: `module-edges.ts` wrote *"`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"* — 60
+ * lines above a `localeCompare` in the identity discriminator, while `conditions/slice.ts`
+ * eliminated its own machine-dependence *using `localeCompare`*. Four sites in all.
+ *
+ * `tests/tools/scan-locale-ordering.test.ts` is what keeps that from recurring: a runtime row
+ * cannot catch it, because on an `en-US` machine both comparators agree — a guard written for
+ * this defect passed 16/16 with the defect reinstated.
+ */
+export function byCodepoint(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * The subject `hashViolation` keys a baseline entry on: `identity`, or `element::message`.
+ *
+ * **Exported and consumed by `hashViolation`/`hashSubject`** rather than duplicated. An earlier
+ * draft kept a private copy here on the reasoning that `core/` must not depend on `helpers/` —
+ * true, but backwards: `helpers/baseline.ts` already imports from `core/`, which is the
+ * permitted direction, and `core/identity-root.ts` records the same move for the same reason.
+ * A copy plus a test asserting the copies agree is strictly worse than one definition: the
+ * test can only compare the formulas over fixtures it happens to build, and the first draft's
+ * fixture shared every field, so it agreed under any formula.
+ */
+export function subjectOf(violation) {
+    return violation.identity ?? `${violation.element}::${violation.message}`;
+}
+/**
+ * The full key `hashViolation` hashes — `rule::subject` — and therefore the unit
+ * {@link disambiguateIdentities} must group on.
+ *
+ * **Grouping on the subject alone was a defect**, measured: `hashViolation` includes `rule`, so
+ * two findings carrying the same `element::message` under *different* rule descriptions already
+ * hash apart and were never ambiguous. Suffixing the second moved a baseline entry that had no
+ * collision — the precise failure this mechanism exists to avoid, committed by the mechanism.
+ *
+ * Not live at the time it was found (instrumenting the whole suite showed one batch carrying
+ * more than one rule string and zero over-suffixed findings), but reachable by construction:
+ * several builders mix `metadata?.id ?? description` with a bare `description` inside one batch
+ * — `slice-rule-builder.ts`, `correspondence-builder.ts`, `tsconfig-builder.ts`,
+ * `inconsistent-siblings.ts`, `schema-rule-builder.ts` all do. Any of them emitting a colliding
+ * subject across their two rule strings would have moved a published entry.
+ */
+function groupKeyOf(violation) {
+    return `${violation.rule}::${subjectOf(violation)}`;
+}
+/**
+ * Give every finding in a rule a distinct identity, by suffixing only the ones that collide.
+ *
+ * {@link ArchViolation.identity} states the invariant this enforces: *"it must be unique per
+ * finding within a rule: two distinct violations sharing one identity are one violation to the
+ * baseline, and accepting either accepts both."* That was prose with nothing behind it, and
+ * three families broke it independently —
+ * [ts-archunit bug 0063](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0063-a-dependency-identity-collides-across-files-sharing-a-basename.md)
+ * (dependency), [ts-archunit plan 0088](https://github.com/nielspeter/ts-archunit/blob/main/plans/0088-a-slice-finding-identifies-itself.md) (slice), and
+ * then [0064](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0064-a-dependency-identity-collides-across-two-spellings-of-one-module.md)
+ * and [0065](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0065-reverse-dependency-findings-carry-no-identity.md). Each was fixed
+ * per-family, in the family that happened to be reviewed; this is the mechanism, so the next
+ * producer cannot reintroduce it.
+ *
+ * **A finding whose subject is unique is returned untouched — that is a theorem, not a
+ * measurement.** Only a subject that appears more than once is altered, and only from its
+ * second occurrence onward, so:
+ *
+ * - no existing baseline entry moves, because a *unique* entry is what a correct baseline holds;
+ * - the entry a colliding pair *did* record still matches, because the first occurrence keeps
+ *   its subject verbatim — so the fail-open closes by making the hidden sibling report as new,
+ *   which is the finding an adopter never got to see.
+ *
+ * Groups that collide were, by definition, one baseline entry standing for two findings: an
+ * entry that was already wrong. Those are the only ones that move.
+ *
+ * **Ordering — a limitation, not a guarantee.** The suffix follows the order the rule produced
+ * its findings, so a baseline entry accepts *a position in a group*, not *a finding*. An earlier
+ * draft of this paragraph said the residual "is not a fail-open, because the group still yields
+ * as many distinct identities as it has findings", and cited `ModuleEdge.ordinal` as its source.
+ * The premise is true and the conclusion does not follow — and that source, which measured the
+ * identical residual one layer down, concludes the opposite. Its table, reproduced because it
+ * applies verbatim here:
+ *
+ * | edit to an accepted colliding group       | new reds reported |
+ * | ----------------------------------------- | ----------------- |
+ * | add a sibling                             | 1 — correct       |
+ * | insert a sibling **above** the first        | 1 — correct count |
+ * | **delete one, add a different one**       | **0 — silent**    |
+ *
+ * So the equal-count swap is a **fail-open**: a violation that did not exist when the baseline
+ * was written arrives pre-accepted. Strictly better than before this mechanism — where *any*
+ * number of added siblings was pre-accepted, not only an equal-count swap — and still a hole.
+ *
+ * The middle row is right about the number and wrong about the name: the finding reported may
+ * be a **sibling nobody touched**, while the newly-added one takes the bare subject and matches
+ * the existing entry. For ADR-008's stated primary consumer — an agent that acts on the message
+ * — pointing at the wrong file is worse than a miss.
+ *
+ * Sharper still where an entry carries state: a `measured` metric entry holds an accepted
+ * ceiling, so a swap can hand the survivor a ceiling belonging to a different element and
+ * silently accept a regression. That is bug 0028's shape recreated inside bug 0012's fix.
+ *
+ * The durable answer is a real per-finding identity — a `binding` field for the edge family,
+ * qualified names for the metric family — tracked 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). This is the
+ * floor: a collision can no longer be silent *at scale*. It is not the ceiling.
+ *
+ * **Why here and not per condition.** `applyFilters` is the one path every terminal shares, and
+ * its own contract is that identity is complete before any filter reads it. Running before the
+ * filters also makes identity a property of *what the rule found* rather than of what a
+ * `--changed` or `.excluding()` run happened to keep — the same identity in CI and locally.
+ */
+/**
+ * Subjects the mechanism had to disambiguate, by rule — the producer-quality signal.
+ *
+ * **Why this exists.** `disambiguateIdentities` guarantees that a rule's findings have distinct
+ * identities, which silently turned every `new Set(hashes).size === findings.length` assertion
+ * in the suite into a tautology. Measured: collapsing `duplicate-bodies.ts`'s identity to a
+ * literal constant — the worst producer defect available — left **all 234 files and 3178 tests
+ * green**, including `baseline-portability.test.ts`, whose own comment says *"collision is the
+ * failure mode this primitive introduces, so it gets its own guard."*
+ *
+ * The mechanism is a safety net, not a licence for producers to stop identifying their
+ * findings: a positional suffix makes an entry a *slot*, while a producer identity makes it a
+ * *reference*, and only the latter survives a sibling being deleted (see the ordering table
+ * above). So the guards must keep measuring the producer, and after this mechanism the only
+ * way to do that is to ask what the mechanism had to repair.
+ *
+ * Same shape as `recordEdgeCoverage`/`untestedRules` next door, for the same reason: a
+ * disclosure channel that a test can assert on without the production path knowing it exists.
+ */
+const collisions = [];
+/** Every subject a rule produced more than once, since the last reset. */
+export function identityCollisions() {
+    return collisions;
+}
+/** Clear the record — call in a `beforeEach` when asserting on a specific rule. */
+export function resetIdentityCollisions() {
+    collisions.length = 0;
+}
+registerCacheReset(resetIdentityCollisions);
+export function disambiguateIdentities(violations) {
+    const counts = new Map();
+    for (const violation of violations) {
+        const key = groupKeyOf(violation);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    // Nothing collides: return the input untouched rather than rebuilding it, so the
+    // overwhelmingly common case costs one pass and no allocation.
+    let anyDuplicate = false;
+    for (const count of counts.values()) {
+        if (count > 1) {
+            anyDuplicate = true;
+            break;
+        }
+    }
+    if (!anyDuplicate)
+        return violations;
+    // Disclose what had to be repaired, so a guard can still measure the PRODUCER — see
+    // `identityCollisions`. Recorded before the repair, because afterwards there is nothing left
+    // to see, which is precisely how this mechanism disarmed the existing collision guards.
+    for (const [key, count] of counts) {
+        if (count > 1) {
+            const split = key.indexOf('::');
+            collisions.push({
+                rule: key.slice(0, split),
+                subject: key.slice(split + 2),
+                findings: count,
+            });
+        }
+    }
+    // Every key present before suffixing, so a generated `#n` can never land on one a producer
+    // already emits. Without it, a rule holding `X` twice plus a literal `X#1` closes one
+    // collision by opening another — and `taken.add` below is what keeps that true for the
+    // THIRD member: without it, `[X, X, X, X#1]` yields `X, X#2, X#2, X#1`, reintroducing the
+    // collision this function exists to remove. Measured; it takes a group of three to reach,
+    // which is why the guard for it carries three.
+    const taken = new Set(counts.keys());
+    const seen = new Map();
+    return violations.map((violation) => {
+        const key = groupKeyOf(violation);
+        if ((counts.get(key) ?? 0) < 2)
+            return violation;
+        const occurrence = (seen.get(key) ?? 0) + 1;
+        seen.set(key, occurrence);
+        // The first keeps its subject verbatim — this is what makes the migration empty.
+        if (occurrence === 1)
+            return violation;
+        // The suffix goes on the SUBJECT, because that is what `identity` is; the reservation is
+        // checked on the group key, because that is what collides.
+        const subject = subjectOf(violation);
+        let suffix = occurrence - 1;
+        let candidate = `${subject}#${String(suffix)}`;
+        while (taken.has(`${violation.rule}::${candidate}`)) {
+            suffix += 1;
+            candidate = `${subject}#${String(suffix)}`;
+        }
+        taken.add(`${violation.rule}::${candidate}`);
+        return { ...violation, identity: candidate };
+    });
+}
 //# sourceMappingURL=violation.js.map

package/dist/violation.js.map

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

package/dist/watch.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Watch-mode scheduling and the watch loop, shared by every dialect CLI.
+ *
+ * **Why this is in the kernel.** It was copied, and the copies drifted. Measured
+ * on 2026-08-31: `watchAndRerun` scored 98% between `eess-ts` and `eess-mermaid`,
+ * `RunScheduler.schedule` 100%, `RunScheduler.executeRun` 98% — and the drift was
+ * not cosmetic. Two fixes had landed on the ts copy alone:
+ *
+ * - `isArchRuleError` instead of `err instanceof ArchRuleError`. The structural
+ *   check exists because a rule file does not load through the same module
+ *   registry as the CLI loading it, so `instanceof` is FALSE for an error that is
+ *   an `ArchRuleError` in every way that matters. With the `instanceof` form,
+ *   `eess-mermaid --watch` printed an ordinary rule failure as an unexpected
+ *   crash.
+ * - `isNullaryCallable(w.return)` instead of a `typeof` test plus
+ *   `w.return.call(w)`, which the copy's own comment noted yields `any`.
+ *
+ * Nothing here needs a project or a tokenizer, so this unification is not
+ * waiting on either decision plan 0188 turns on — see that plan's inventory.
+ *
+ * Kernel-safe: node builtins and this package only.
+ */
+export interface WatchOptions {
+    /** Directories to watch, recursively. */
+    watchDirs: string[];
+    /** Additional individual files to watch (e.g. rule files). */
+    watchFiles: string[];
+    /** Which filenames inside `watchDirs` count as a change. */
+    watchedFileRe: RegExp;
+    /** Runs on a debounced change. */
+    onChangeDetected: () => Promise<void>;
+    /** Debounce window in ms. Default: 250. */
+    debounceMs?: number;
+}
+/**
+ * Scheduling logic for watch mode — separate from the loop so it is testable
+ * without a filesystem.
+ *
+ * Debounces rapid triggers. A trigger arriving mid-run is remembered and
+ * replayed once the run finishes, so a save during a run is never dropped and
+ * never starts a second concurrent run.
+ */
+export declare class RunScheduler {
+    #private;
+    private debounceTimer;
+    private running;
+    private _pendingRerun;
+    private readonly debounceMs;
+    private readonly onRun;
+    constructor(onRun: (trigger: string) => Promise<void>, debounceMs?: number);
+    /**
+     * Completed runs.
+     *
+     * Hard-private with a getter: the counter is this class's own bookkeeping, and
+     * a caller that could reassign it would make the number mean nothing.
+     */
+    get runCount(): number;
+    get pendingRerun(): boolean;
+    get isRunning(): boolean;
+    /** Debounce a change on `trigger`, coalescing bursts into a single re-run. */
+    schedule(trigger: string): void;
+    private executeRun;
+}
+/**
+ * Watch for file changes and re-run the callback.
+ *
+ * Uses `fs.watch` with `recursive: true` (Node 24+). Debounces rapid events; a
+ * change during a run is queued and executed after it completes.
+ */
+export declare function watchAndRerun(options: WatchOptions): void;
+//# sourceMappingURL=watch.d.ts.map

package/dist/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAA;IACrB,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAOD;;;;;;;GAOG;AACH,qBAAa,YAAY;;IACvB,OAAO,CAAC,aAAa,CAA2C;IAChE,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;gBAG9C,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,SAAsB;IAKvF;;;;;OAKG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAW/B,OAAO,CAAC,UAAU;CAuBnB;AAmBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAsCzD"}

package/dist/watch.js

@@ -0,0 +1,129 @@
+import { watch } from 'node:fs/promises';
+import path from 'node:path';
+import { isArchRuleError } from './errors.js';
+import { isNullaryCallable } from './type-guards.js';
+const DEFAULT_DEBOUNCE_MS = 250;
+/** `fs.watch` reports this when a watcher is closed; it is not a fault. */
+const ABORTED = 'The operation was aborted';
+/**
+ * Scheduling logic for watch mode — separate from the loop so it is testable
+ * without a filesystem.
+ *
+ * Debounces rapid triggers. A trigger arriving mid-run is remembered and
+ * replayed once the run finishes, so a save during a run is never dropped and
+ * never starts a second concurrent run.
+ */
+export class RunScheduler {
+    debounceTimer;
+    running = false;
+    _pendingRerun = false;
+    debounceMs;
+    onRun;
+    #runCount = 0;
+    constructor(onRun, debounceMs = DEFAULT_DEBOUNCE_MS) {
+        this.onRun = onRun;
+        this.debounceMs = debounceMs;
+    }
+    /**
+     * Completed runs.
+     *
+     * Hard-private with a getter: the counter is this class's own bookkeeping, and
+     * a caller that could reassign it would make the number mean nothing.
+     */
+    get runCount() {
+        return this.#runCount;
+    }
+    get pendingRerun() {
+        return this._pendingRerun;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    /** Debounce a change on `trigger`, coalescing bursts into a single re-run. */
+    schedule(trigger) {
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+            if (this.running) {
+                this._pendingRerun = true;
+                return;
+            }
+            this.executeRun(trigger);
+        }, this.debounceMs);
+    }
+    executeRun(trigger) {
+        this.running = true;
+        this._pendingRerun = false;
+        this.#runCount++;
+        process.stdout.write('\x1B[2J\x1B[H'); // clear screen, preserve scrollback
+        process.stdout.write(`Change detected: ${trigger}\n\n`);
+        this.onRun(trigger)
+            .catch((err) => {
+            // A rule failure is the expected outcome of a watch run — swallow it and
+            // let the reporter's own output stand. Anything else is a real fault.
+            if (!isArchRuleError(err) && err instanceof Error) {
+                console.error(err.message);
+            }
+        })
+            .finally(() => {
+            this.running = false;
+            if (this._pendingRerun) {
+                this.executeRun('(queued change)');
+            }
+            else {
+                process.stdout.write('\nWatching for changes...\n');
+            }
+        });
+    }
+}
+/** Consume one watcher, scheduling on each qualifying event. */
+function consume(watcher, label, onEvent) {
+    void (async () => {
+        try {
+            for await (const event of watcher)
+                onEvent(event);
+        }
+        catch (err) {
+            if (err instanceof Error && err.message !== ABORTED) {
+                console.error(`Watcher error on ${label}: ${err.message}`);
+            }
+        }
+    })();
+}
+/**
+ * Watch for file changes and re-run the callback.
+ *
+ * Uses `fs.watch` with `recursive: true` (Node 24+). Debounces rapid events; a
+ * change during a run is queued and executed after it completes.
+ */
+export function watchAndRerun(options) {
+    const { watchDirs, watchFiles, watchedFileRe, onChangeDetected, debounceMs = DEFAULT_DEBOUNCE_MS, } = options;
+    const scheduler = new RunScheduler(onChangeDetected, debounceMs);
+    const watchers = [];
+    for (const dir of watchDirs) {
+        const watcher = watch(path.resolve(dir), { recursive: true });
+        watchers.push(watcher);
+        consume(watcher, dir, (event) => {
+            if (event.filename && watchedFileRe.test(event.filename)) {
+                scheduler.schedule(event.filename);
+            }
+        });
+    }
+    for (const file of watchFiles) {
+        const watcher = watch(path.resolve(file));
+        watchers.push(watcher);
+        consume(watcher, file, () => {
+            scheduler.schedule(path.basename(file));
+        });
+    }
+    // Graceful shutdown — close all watchers on SIGINT.
+    process.on('SIGINT', () => {
+        for (const w of watchers) {
+            if ('return' in w && isNullaryCallable(w.return)) {
+                void w.return();
+            }
+        }
+        process.exit(0);
+    });
+}
+//# sourceMappingURL=watch.js.map

package/dist/watch.js.map

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

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@nielspeter/eess",
-  "version": "0.2.2",
+  "version": "0.5.0",
   "description": "eess kernel — the dialect-independent rule engine (RuleBuilder, Predicate, Condition, baseline, formatters). Specifications you can run.",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
     }
   },
   "files": [
@@ -26,6 +30,7 @@
   "license": "MIT",
   "scripts": {
     "prepublishOnly": "npm run build",
+    "prebuild": "rm -rf dist",
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",