@nielspeter/eess 0.4.0 → 0.5.1

package/README.md

@@ -12,6 +12,90 @@ This package is the engine every eess dialect runs on. It knows nothing about Ty
 - Baseline mode, diff-aware filtering, exclusions, and the terminal/GitHub/JSON formatters
 - `definePredicate` / `defineCondition` — extension points for advanced users
 
+## Two entry points
+
+`@nielspeter/eess` publishes two:
+
+| Specifier                   | What it is                                                                                                                                          |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@nielspeter/eess`          | The public API. Everything below is documented here, and a change to it is a versioned change.                                                      |
+| `@nielspeter/eess/internal` | Family plumbing the sibling dialects share — cache registries, stderr guards, suppression counters, identity hashing, glob-tree internals. Not API. |
+
+You want the root. `/internal` exists so the dialects can share one engine without
+each name they touch becoming a public commitment; it is published because npm has
+no way to ship a package-private module, not because it is for you. Nothing there is
+documented, and no dialect re-exports it _as its own API_. Two names — `DiskSet`
+and `OnDisk` — are also on `@nielspeter/eess-ts`'s root, where they are eess-ts's
+own types that happen to share a name; that is the whole of the overlap.
+
+Breaking something here is still a versioned change and still needs a changeset
+(ADR-011 clause 4). What you are not owed is migration guidance, because it is not
+API. See
+[ADR-011](https://github.com/nielspeter/eess/blob/main/adr/011-the-kernels-public-api-is-explicit.md).
+
+If a symbol you used disappeared from the root, it moved here — the import path is
+the only change.
+
+## Kernel API reference
+
+The fluent surface (`RuleBuilder`, `Predicate`, `Condition`, the combinators, the
+formatters) is covered in the [docs site](https://nielspeter.github.io/eess/). This
+section covers the supporting types you will meet in signatures.
+
+### Reporting and severity
+
+A preset never emits on its own — the caller owns emission (ADR-008).
+
+- **`ReportMode`** — `'throw' | 'return' | 'warn'`. What a finisher does with findings: raise an `ArchRuleError`, hand them back, or print them as advisory and continue.
+- **`ReportOptions`** — the emission controls: `format` (terminal/json/github) and `reason`, the rationale threaded into the output.
+- **`RuleSeverity`** — `'error' | 'warn' | 'off'`, the value of a per-rule override.
+- **`PresetBaseOptions`** — what every preset accepts: an `overrides` map of rule id → `RuleSeverity`, plus the reporting controls. Extend it when you write a preset so `{ report: 'return' }` works without your own plumbing.
+- **`RuleBuilderLike`** — the one-method shape (`violations()`) a preset needs from anything it dispatches, so a preset is not coupled to a dialect's builder class.
+- **`Dispatchable`** — what `dispatchRule` accepts: a builder that can produce violations _and_ name itself, so the dispatcher can apply a per-rule override to it. Strictly more than `RuleBuilderLike`; that one is the narrower shape used where only the findings matter.
+- **`isArchRuleError(err)`** — use this instead of `instanceof ArchRuleError` when catching. `instanceof` compares class identity, so it returns `false` whenever two copies of the package are on disk — a nested `node_modules`, or a rule file loaded through a separate module registry. The check is structural (the stamped `name` plus the `violations` array), so it survives that. The thrown shape itself — `violations: ArchViolation[]` — is public either way.
+- **`ArchConfigError`** / **`isArchConfigError(err)`** — thrown when a _rule_ is misconfigured (bad arguments to a condition, a malformed rule file), as opposed to `ArchRuleError`, which means the _architecture_ is wrong. Two different faults with two different audiences: one tells a rule author they mistyped something, the other tells a team their code drifted. Carries `subject` — the condition, predicate or file at fault — so a caller can route the failure without parsing the message. `isArchConfigError` is structural for the same two-copies-on-disk reason as `isArchRuleError`.
+- **`ArchFix`** — a machine-applicable edit on a violation: `file`, a `[start, end)` character span, and the `replacement` text. This is what `--fix` applies.
+
+### The JSON report
+
+`--format json` emits an **`ArchJsonReport`**: a `summary` (`total`, `errors`, `warnings`, `reason`), then **`ArchJsonViolation`** entries, plus **`ArchJsonSuppression`** for findings silenced by an `eess-exclude` comment and **`ArchJsonUntestedAllowlist`** for allowlists nothing exercised. Import these to type a tool that consumes eess output rather than re-declaring the shape.
+
+### Filtering a run
+
+- **`BaselineFilter`** — decides whether an already-accepted finding is suppressed by the baseline file.
+- **`DiffFilterLike`** — decides whether a finding falls inside the changed region, for `--changed` runs.
+
+Both are interfaces so a host can supply its own; the kernel ships implementations.
+
+### Correspondence
+
+`correspondence()` binds two `Selection`s and checks they agree in both directions.
+
+- **`CorrespondenceOptions`** — its argument: the `left` and `right` selections, a join strategy, and optional per-side `suggest` callbacks for the two-sided message.
+- **`KeyBy`** — the fast join: a key extracted per element, giving an O(n+m) match. Prefer it. The fallback `matchBy` predicate is O(n×m).
+- **`RelationSpec`** — what `preserveRelations()` takes: how to read edges from each side, so the check covers relationships and not just membership.
+- **`ElementInfo`** — the `name` / `file` / `line` a dialect reports for one element, which is what the message and the violation's location are built from.
+
+### Declaring globs (for custom predicates)
+
+A predicate written with `definePredicate` should declare the globs it matches on.
+Without that it is opaque, so a vacuity diagnosis cannot tell "matched nothing
+because the glob is dead" from "matched nothing because nothing was there" — and
+any `or()` containing it becomes undiagnosable too.
+
+- **`globNode(leaf)`** — wrap a single declared glob into a tree. The common case.
+- **`globAnyOf(globs, kind, base?)`** — declare several alternatives at once.
+- **`DeclaredGlob`** — one glob with its `kind` and `base`. **`GlobKind`** is what the glob matches against (`'file-path' | 'parent-dir' | 'import-target' | 'specifier' | 'literal'`) and **`GlobBase`** is what it is resolved against (`'absolute' | 'tsconfig-relative' | 'normalized'`).
+- **`GlobTree<L>`** — the `and`/`any` tree the declarations form; **`DeclaredGlobs`** is that tree over `DeclaredGlob`, and **`GlobLeaf<L>`** is one position in it.
+- **`OpaqueGlob`** — the explicit "this branch cannot be described" marker. Honest, and it is what keeps an undeclared predicate from silently reading as a dead one.
+- **`GlobSite`** — a declared glob plus where it was written; **`GlobPosition`** is that where (`'selector' | 'discovery' | 'condition' | 'exclusion'`), which is what lets a diagnosis point at the glob you actually got wrong.
+- **`GlobNode`** — the tree over `GlobSite`, i.e. a fully-stamped declaration ready to diagnose.
+
+### Coverage evidence
+
+- **`EdgeCoverage`** — one rule's evidence: how many `subjects` it saw, how many `edges` it actually tested, and a `reason` when that number is zero.
+- **`UntestedReason`** — why zero: `'no-edges'` (nothing to test, usually correct), `'all-filtered'` (edges existed and every one was filtered out), `'none-matched'` (edges existed and none matched the allowlist). The distinction is the point — a rule that tested nothing should say which of the three it was, per ADR-010.
+
 ## Who uses it
 
 You normally don't install this directly — you install a dialect:
@@ -19,7 +103,16 @@ You normally don't install this directly — you install a dialect:
 - [`@nielspeter/eess-ts`](https://www.npmjs.com/package/@nielspeter/eess-ts) — TypeScript
 - [`@nielspeter/eess-mermaid`](https://www.npmjs.com/package/@nielspeter/eess-mermaid) — Mermaid class diagrams
 
-Install `@nielspeter/eess` directly only when authoring a new dialect or a cross-dialect tool on top of the kernel.
+Install `@nielspeter/eess` directly only when authoring a new dialect or a cross-dialect
+tool on top of the kernel.
+
+**If that is you, `/internal` is your surface, not a wall.** The two sentences above look
+like they contradict each other — "not for you", then "install it if you are writing a
+dialect" — so to be explicit: a dialect author is exactly who `/internal` exists for, and
+the five in this repo import from it. What the root alone gives you is the rule-authoring
+vocabulary, not the engine. Nothing there is documented and it changes without migration
+notes, so treat it as a contract you re-check on each kernel bump; if you are building a
+dialect you intend to publish, open an issue and we will work out what belongs on the root.
 
 ## License
 

package/dist/baseline-generator.d.ts

@@ -5,6 +5,15 @@ import type { ArchViolation } from './violation.js';
  * Used to generate a baseline: run all rules, collect violations,
  * write them to a baseline file.
  *
+ * **This bypasses the evidence gate, deliberately and knowingly** — see ADR-014
+ * and proposal 011 ask C. Prefer a dialect's `baseline` command, which gates per
+ * rule file and refuses a builder that certified nothing.
+ *
+ * **Not the same function as `eess-ts`'s `collectViolations`.** This one takes
+ * builders with a throwing `check()` and harvests the `ArchRuleError`; the
+ * dialect's takes builders with a non-throwing `violations()`. Same name, same
+ * `@example`, different contract.
+ *
  * @example
  * const violations = collectViolations(
  *   classes(p).that().extend('Base').should().notContain(call('parseInt')),

package/dist/baseline-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"baseline-generator.d.ts","sourceRoot":"","sources":["../src/baseline-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGnD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC,GAAG,aAAa,EAAE,CAc5F"}
+{"version":3,"file":"baseline-generator.d.ts","sourceRoot":"","sources":["../src/baseline-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC,GAAG,aAAa,EAAE,CAc5F"}

package/dist/baseline-generator.js

@@ -5,6 +5,15 @@ import { ArchRuleError } from './errors.js';
  * Used to generate a baseline: run all rules, collect violations,
  * write them to a baseline file.
  *
+ * **This bypasses the evidence gate, deliberately and knowingly** — see ADR-014
+ * and proposal 011 ask C. Prefer a dialect's `baseline` command, which gates per
+ * rule file and refuses a builder that certified nothing.
+ *
+ * **Not the same function as `eess-ts`'s `collectViolations`.** This one takes
+ * builders with a throwing `check()` and harvests the `ArchRuleError`; the
+ * dialect's takes builders with a non-throwing `violations()`. Same name, same
+ * `@example`, different contract.
+ *
  * @example
  * const violations = collectViolations(
  *   classes(p).that().extend('Base').should().notContain(call('parseInt')),

package/dist/baseline-generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"baseline-generator.js","sourceRoot":"","sources":["../src/baseline-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAG,QAAsC;IACzE,MAAM,aAAa,GAAoB,EAAE,CAAA;IAEzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,OAAO,CAAC,KAAK,EAAE,CAAA;QACjB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,aAAa,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,CAAA;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAA;AACtB,CAAC"}
+{"version":3,"file":"baseline-generator.js","sourceRoot":"","sources":["../src/baseline-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAG,QAAsC;IACzE,MAAM,aAAa,GAAoB,EAAE,CAAA;IAEzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,OAAO,CAAC,KAAK,EAAE,CAAA;QACjB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,aAAa,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,CAAA;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAA;AACtB,CAAC"}

package/dist/baseline.d.ts

@@ -26,7 +26,7 @@ export interface BaselineEntry {
     /**
      * What {@link measured} counts — `code-lines`, `methods`, `complexity`.
      *
-     * Written since [bug 0171](../../../work/bugs/0171-a-metric-unit-change-silently-loosens-every-baselined-ratchet.md).
+     * Written since [bug 0171](../../../work/bugs/fixed/0171-a-metric-unit-change-silently-loosens-every-baselined-ratchet.md).
      * An accepted ceiling is a number IN A UNIT, and comparing across a change of
      * unit does not measure a regression — it moves the bar. Absent on entries
      * written before stamping, which {@link Baseline.isKnown} treats as "unknown

package/dist/cardinality.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cardinality.d.ts","sourceRoot":"","sources":["../src/cardinality.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,CAGzE;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE7D"}
+{"version":3,"file":"cardinality.d.ts","sourceRoot":"","sources":["../src/cardinality.ts"],"names":[],"mappings":"AAyCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,CAGzE;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE7D"}

package/dist/cardinality.js

@@ -16,11 +16,26 @@
  * empty-selection gate on any rule, permanently and invisibly. That is
  * `.allowEmpty()` wearing a different hat.
  *
- * This symbol is **not** re-exported from `src/index.ts`, and `package.json`'s
- * `exports` map has no wildcard subpath, so a consumer cannot import it to
- * name the key. The escape hatch users *do* get is `.expectEmpty()`, which is
- * an assertion that fails when the selection stops being empty — not a
- * silencer.
+ * **What actually stops a consumer doing this: not enough.** Say it plainly,
+ * because two earlier versions of this comment did not.
+ *
+ * The `WeakSet` below defends the KEY — membership cannot be read off an object,
+ * copied, or forged. It does not defend the CALL. Anyone holding
+ * `marksAssertsCardinality` can mark any condition, and it is reachable from
+ * `@nielspeter/eess/internal`. The first rationale here ("the exports map has no
+ * wildcard subpath") stopped being true when ADR-011 added the subpath; the
+ * second ("the `WeakSet` is the real defence") was simply wrong about which half
+ * it guards, and was written in the same branch that added the subpath.
+ *
+ * The honest position: this is narrower than it was — on `main` the marker was
+ * exported from the kernel ROOT and re-exported by eess-ts's root, so it sat on
+ * two published surfaces; it is now on one, named `/internal`, which no dialect
+ * re-exports. It is not closed. Closing it means validating at the registration
+ * site (accept only conditions from a sanctioned constructor), which is a design
+ * change, not a comment.
+ *
+ * The escape hatch users are *meant* to have is `.expectEmpty()` — an assertion
+ * that fails when the selection stops being empty, not a silencer.
  */
 const CARDINALITY_ASSERTERS = new WeakSet();
 /**

package/dist/cardinality.js.map

@@ -1 +1 @@
-{"version":3,"file":"cardinality.js","sourceRoot":"","sources":["../src/cardinality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,qBAAqB,GAAG,IAAI,OAAO,EAAU,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,uBAAuB,CAAmB,SAAY;IACpE,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IACpC,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,OAAO,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;AAC7C,CAAC"}
+{"version":3,"file":"cardinality.js","sourceRoot":"","sources":["../src/cardinality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,qBAAqB,GAAG,IAAI,OAAO,EAAU,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,uBAAuB,CAAmB,SAAY;IACpE,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IACpC,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,OAAO,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;AAC7C,CAAC"}

package/dist/cli-config.d.ts

@@ -0,0 +1,106 @@
+import type { OutputFormat } from './check-options.js';
+/**
+ * The parts of dialect CLI config handling that are the same everywhere.
+ *
+ * **Split along the kernel's existing seam, not behind a new injection point.**
+ * `PathUniverse` sets the pattern: the kernel takes materialized data and the
+ * dialect does the I/O. Here the pure halves are finding the config file and
+ * validating what a loaded module claims — both were byte-identical between
+ * `eess-ts` and `eess-mermaid` (`findConfigFile` scored 100%). The impure half,
+ * actually importing the file, stays in each dialect because it needs `jiti`,
+ * which the kernel cannot depend on.
+ *
+ * That left one genuinely shared subtlety in the impure half —
+ * {@link isModuleFormatRefusal} — so it lived here too: pure, and the part that
+ * is easy to get dangerously wrong.
+ *
+ * **That description is no longer complete, and saying so is the point.** Bug
+ * 0223 added two more members of the same family, and one of them —
+ * {@link enableTypeScriptSpecifierResolution} — is NOT pure: it registers a
+ * resolve hook on the host process, permanently. The substitution it performs is
+ * a fact about the language rule files are WRITTEN in, which is TypeScript for
+ * every dialect, so the kernel is the right owner. But "the impure half stays in
+ * each dialect" is now true of importing and false of resolving, and an
+ * architecture review called the three of them module-loading policy sitting in
+ * a config-discovery file. Splitting them into their own kernel module is the
+ * open half of that finding; the header no longer claims otherwise in the
+ * meantime.
+ */
+/** Config fields every dialect CLI understands. A dialect may add its own. */
+export interface SharedCliConfig {
+    rules?: string[];
+    format?: OutputFormat | 'auto';
+    watchDirs?: string[];
+}
+/** The first of `filenames` that exists in the working directory. */
+export declare function findConfigFile(filenames: readonly string[]): string | undefined;
+/**
+ * The shared config a loaded module claims, validated.
+ *
+ * Everything is checked rather than trusted: a config file is arbitrary user
+ * code and its default export can be any shape at all. An unrecognised `format`
+ * is dropped rather than passed through, so a typo falls back to the default
+ * instead of reaching a formatter that has no case for it.
+ */
+export declare function extractSharedConfig(mod: unknown): SharedCliConfig;
+/**
+ * Did Node refuse this file for its MODULE FORMAT, rather than for anything the
+ * file does?
+ *
+ * Narrow on purpose. A broad `catch` that fell back to a transpiling loader on
+ * any error would re-execute a rule file that had already run — doubling its
+ * output — and would hide a genuine syntax error behind a second,
+ * differently-worded failure.
+ *
+ * The condition it detects is bug 0074: the CONSUMER project is
+ * `"type": "commonjs"` (what `npm init -y` writes) and the config or rule file
+ * uses ESM syntax.
+ */
+export declare function isModuleFormatRefusal(error: unknown): boolean;
+/**
+ * Did Node fail to resolve a specifier that TypeScript requires be written that
+ * way — a `./sibling.js` whose file on disk is `./sibling.ts`?
+ *
+ * Narrow for the same reason {@link isModuleFormatRefusal} is, and narrower
+ * still: it answers yes only when the TypeScript source is ACTUALLY on disk. A
+ * genuinely missing module is still a genuinely missing module, reported the way
+ * it always was, and nothing is retried on its behalf.
+ *
+ * This is bug 0223, reported by a consuming project. `"type": "module"` plus the
+ * `.js` specifier is not an exotic combination — it is the one TypeScript
+ * mandates for ESM, so every project that splits its rules across files reaches
+ * it on the first attempt. The failure is `ERR_MODULE_NOT_FOUND` rather than a
+ * `SyntaxError`, which is why the format-refusal predicate above cannot see it.
+ */
+export declare function isTypeScriptSpecifierMiss(error: unknown): boolean;
+/**
+ * Teach this process's loader the substitution, so `./sibling.js` resolves to
+ * `./sibling.ts` when that is the file that exists.
+ *
+ * **`registerHooks`, deliberately, and not a transpiling loader.** The hook is
+ * synchronous and in-thread, so a rule file still loads into THIS module
+ * registry. That is the invariant plan 0165 and bug 0029 paid for and the reason
+ * the alternative fix was rejected: a second registry makes
+ * `instanceof ArchRuleError` false and sets `callerAggregatesReports` on one
+ * copy while it is read on the other, printing every configuration finding
+ * twice. Resolution is the only thing being changed here; execution is
+ * untouched.
+ *
+ * The hook rewrites nothing unless the emitted path is absent AND the
+ * TypeScript source is present, so a real `.js` file beside a `.ts` of the same
+ * name always wins, and a specifier naming neither is left alone to fail as it
+ * would have.
+ */
+export declare function enableTypeScriptSpecifierResolution(): void;
+/**
+ * Refuse a run that named no rule files, saying where to name them.
+ *
+ * Sets `process.exitCode` rather than throwing: the caller is a CLI entry point
+ * that still wants to return normally. Returns whether the run may proceed.
+ *
+ * `configName` is the dialect's own config filename, because "set them in
+ * config" is not an instruction — the two copies of this differed in exactly
+ * that word, one naming the file and one not.
+ */
+export declare function requireRuleFiles(ruleFiles: readonly string[], configName: string): boolean;
+//# sourceMappingURL=cli-config.d.ts.map

package/dist/cli-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-config.d.ts","sourceRoot":"","sources":["../src/cli-config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAGtD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAAA;IAC9B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACrB;AAID,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAO/E;AAOD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CAiBjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM7D;AAiDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKjE;AAYD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mCAAmC,IAAI,IAAI,CA6C1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAO1F"}

package/dist/cli-config.js

@@ -0,0 +1,231 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { registerHooks } from 'node:module';
+import { isRecord } from './type-guards.js';
+const FORMATS = new Set(['terminal', 'json', 'github', 'auto']);
+/** The first of `filenames` that exists in the working directory. */
+export function findConfigFile(filenames) {
+    const cwd = process.cwd();
+    for (const name of filenames) {
+        const candidate = path.join(cwd, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Strings from an unknown array, dropping anything that is not one. */
+function stringsOf(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : undefined;
+}
+/**
+ * The shared config a loaded module claims, validated.
+ *
+ * Everything is checked rather than trusted: a config file is arbitrary user
+ * code and its default export can be any shape at all. An unrecognised `format`
+ * is dropped rather than passed through, so a typo falls back to the default
+ * instead of reaching a formatter that has no case for it.
+ */
+export function extractSharedConfig(mod) {
+    if (!isRecord(mod) || !('default' in mod))
+        return {};
+    const defaultExport = mod.default;
+    if (!isRecord(defaultExport))
+        return {};
+    const config = {};
+    const format = defaultExport['format'];
+    if (typeof format === 'string' && FORMATS.has(format)) {
+        // Narrowed by the set above; the cast-free form is this re-check.
+        config.format =
+            format === 'terminal' || format === 'json' || format === 'github' ? format : 'auto';
+    }
+    const rules = stringsOf(defaultExport['rules']);
+    if (rules)
+        config.rules = rules;
+    const watchDirs = stringsOf(defaultExport['watchDirs']);
+    if (watchDirs)
+        config.watchDirs = watchDirs;
+    return config;
+}
+/**
+ * Did Node refuse this file for its MODULE FORMAT, rather than for anything the
+ * file does?
+ *
+ * Narrow on purpose. A broad `catch` that fell back to a transpiling loader on
+ * any error would re-execute a rule file that had already run — doubling its
+ * output — and would hide a genuine syntax error behind a second,
+ * differently-worded failure.
+ *
+ * The condition it detects is bug 0074: the CONSUMER project is
+ * `"type": "commonjs"` (what `npm init -y` writes) and the config or rule file
+ * uses ESM syntax.
+ */
+export function isModuleFormatRefusal(error) {
+    if (!(error instanceof SyntaxError))
+        return false;
+    return (error.message.includes('Cannot use import statement outside a module') ||
+        error.message.includes("Unexpected token 'export'"));
+}
+/**
+ * The extension substitutions TypeScript performs and Node does not.
+ *
+ * Under `nodenext`, TypeScript REQUIRES a relative import to name the emitted
+ * `.js` file even when the file on disk is `.ts`. Node performs no such
+ * substitution, so the specifier that `tsc` demands is the one Node cannot
+ * resolve.
+ */
+const TS_SPECIFIER_SUBSTITUTIONS = new Map([
+    ['.js', ['.ts', '.tsx']],
+    ['.jsx', ['.tsx']],
+    ['.mjs', ['.mts']],
+    ['.cjs', ['.cts']],
+]);
+/**
+ * Is this URL a TypeScript source file — the only kind that writes `.js` for `.ts`?
+ *
+ * Reads the PATH, not the href. Watch mode cache-busts by appending `?t=<now>`
+ * to the entry url, so an href check answers no for exactly the rule file being
+ * re-run — measured, and it disabled the substitution in watch mode entirely
+ * while every non-watch test stayed green.
+ */
+function isTypeScriptSource(url) {
+    let pathname;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch (error) {
+        void error;
+        return false;
+    }
+    return ['.ts', '.tsx', '.mts', '.cts'].some((ext) => pathname.endsWith(ext));
+}
+/** The TypeScript file a JS-family URL stands for, if one is on disk. */
+function typeScriptSourceFor(url) {
+    for (const [emitted, sources] of TS_SPECIFIER_SUBSTITUTIONS) {
+        if (!url.endsWith(emitted))
+            continue;
+        const stem = url.slice(0, -emitted.length);
+        for (const source of sources) {
+            const candidate = `${stem}${source}`;
+            if (fs.existsSync(new URL(candidate)))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Did Node fail to resolve a specifier that TypeScript requires be written that
+ * way — a `./sibling.js` whose file on disk is `./sibling.ts`?
+ *
+ * Narrow for the same reason {@link isModuleFormatRefusal} is, and narrower
+ * still: it answers yes only when the TypeScript source is ACTUALLY on disk. A
+ * genuinely missing module is still a genuinely missing module, reported the way
+ * it always was, and nothing is retried on its behalf.
+ *
+ * This is bug 0223, reported by a consuming project. `"type": "module"` plus the
+ * `.js` specifier is not an exotic combination — it is the one TypeScript
+ * mandates for ESM, so every project that splits its rules across files reaches
+ * it on the first attempt. The failure is `ERR_MODULE_NOT_FOUND` rather than a
+ * `SyntaxError`, which is why the format-refusal predicate above cannot see it.
+ */
+export function isTypeScriptSpecifierMiss(error) {
+    if (!isRecord(error))
+        return false;
+    if (error['code'] !== 'ERR_MODULE_NOT_FOUND')
+        return false;
+    const url = error['url'];
+    return typeof url === 'string' && typeScriptSourceFor(url) !== undefined;
+}
+/**
+ * Registered at most once per MODULE REGISTRY, which is usually per process.
+ *
+ * This is module state, so a second registry — the very hazard the loaders that
+ * call this exist to avoid — would hold a second flag and register a second
+ * hook. Harmless, since the hook is idempotent in effect, but the distinction is
+ * worth stating in the one file whose surrounding prose is about registries.
+ */
+let specifierResolutionEnabled = false;
+/**
+ * Teach this process's loader the substitution, so `./sibling.js` resolves to
+ * `./sibling.ts` when that is the file that exists.
+ *
+ * **`registerHooks`, deliberately, and not a transpiling loader.** The hook is
+ * synchronous and in-thread, so a rule file still loads into THIS module
+ * registry. That is the invariant plan 0165 and bug 0029 paid for and the reason
+ * the alternative fix was rejected: a second registry makes
+ * `instanceof ArchRuleError` false and sets `callerAggregatesReports` on one
+ * copy while it is read on the other, printing every configuration finding
+ * twice. Resolution is the only thing being changed here; execution is
+ * untouched.
+ *
+ * The hook rewrites nothing unless the emitted path is absent AND the
+ * TypeScript source is present, so a real `.js` file beside a `.ts` of the same
+ * name always wins, and a specifier naming neither is left alone to fail as it
+ * would have.
+ */
+export function enableTypeScriptSpecifierResolution() {
+    if (specifierResolutionEnabled)
+        return;
+    specifierResolutionEnabled = true;
+    registerHooks({
+        resolve(specifier, context, nextResolve) {
+            if (!specifier.startsWith('./') && !specifier.startsWith('../')) {
+                return nextResolve(specifier, context);
+            }
+            const parentURL = context.parentURL;
+            // Only a TypeScript file writes the specifier TypeScript mandates. Without
+            // this the hook rewrites for every relative specifier in the process,
+            // including from inside `node_modules` — so a dependency shipping source
+            // beside a stale build directory would get its `.ts` loaded through
+            // strip-only mode instead of the resolution error it expects.
+            if (parentURL === undefined || !isTypeScriptSource(parentURL)) {
+                return nextResolve(specifier, context);
+            }
+            // A non-hierarchical parent (`data:`, `node:`) makes this throw
+            // ERR_INVALID_URL, which inside a resolve hook would convert Node's own
+            // diagnostic into a TypeError attributed to us.
+            let emitted;
+            try {
+                emitted = new URL(specifier, parentURL);
+            }
+            catch (error) {
+                void error;
+                return nextResolve(specifier, context);
+            }
+            if (emitted.protocol !== 'file:' || fs.existsSync(emitted)) {
+                return nextResolve(specifier, context);
+            }
+            const source = typeScriptSourceFor(emitted.href);
+            if (source === undefined)
+                return nextResolve(specifier, context);
+            // Carry the parent's query onto the rewrite. Watch mode busts Node's
+            // module cache by appending `?t=<now>` to the ENTRY url only; a statically
+            // imported sibling keys on its own url, which carries no query, so it is
+            // evaluated once and reused for the life of the session. Measured: edit a
+            // shared glob in the sibling and the re-run reports green computed from
+            // the code you just replaced, with no signal. Propagating the query makes
+            // the whole graph fresh, and is a no-op outside watch because there is no
+            // query to carry.
+            const rewritten = new URL(source);
+            rewritten.search = new URL(parentURL).search;
+            return nextResolve(rewritten.href, context);
+        },
+    });
+}
+/**
+ * Refuse a run that named no rule files, saying where to name them.
+ *
+ * Sets `process.exitCode` rather than throwing: the caller is a CLI entry point
+ * that still wants to return normally. Returns whether the run may proceed.
+ *
+ * `configName` is the dialect's own config filename, because "set them in
+ * config" is not an instruction — the two copies of this differed in exactly
+ * that word, one naming the file and one not.
+ */
+export function requireRuleFiles(ruleFiles, configName) {
+    if (ruleFiles.length > 0)
+        return true;
+    console.error(`Error: No rule files specified. Pass rule files as arguments or set them in ${configName}.`);
+    process.exitCode = 1;
+    return false;
+}
+//# sourceMappingURL=cli-config.js.map

package/dist/cli-config.js.map

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