@nielspeter/eess-ts 0.2.0 → 0.4.0

package/dist/helpers/baseline-diagnostics.js

@@ -0,0 +1,168 @@
+import { hashSubject, HASH_VERSION } from './baseline.js';
+/**
+ * A meta-finding for baseline entries that stopped matching because the
+ * **rule's description changed**, not because the violation was fixed.
+ *
+ * The distinction is the whole difficulty (bug 0027). An entry that stops
+ * matching is normally success — that is what a ratchet is for — so "some
+ * entries did not match" is not evidence of anything, which is why
+ * \{@link unmatchedBaselineFinding\} is gated on `matched === 0` and stays
+ * silent here. But that leaves the common case unexplained: an accepted
+ * violation reported as new, reading like fresh rot in application code.
+ *
+ * `hashSubject` is the differently-derived value that separates them. A
+ * violation in this run whose subject matches a baseline entry, under a
+ * different full hash, is the same finding about the same code under a rule
+ * whose description moved. A subject present in the baseline and absent from
+ * the run was fixed, and says nothing.
+ *
+ * Silent for a baseline written before 0.24.0: those entries have no subject,
+ * so the question cannot be asked and no cause is guessed.
+ */
+/**
+ * The rule description the baseline recorded for this violation's subject, when
+ * the violation looks like the SAME finding under a renamed rule.
+ *
+ * Extracted from `descriptionChangeFinding` so the four disqualifying cases
+ * read as one question with one answer instead of four `continue`s inside the
+ * accumulating loop (they were most of that method's branching).
+ */
+function renamedRuleFor(ctx, violation) {
+    if (violation.bypassFilters === true)
+        return undefined;
+    if (ctx.isKnown(violation))
+        return undefined;
+    // A regressed metric is not a renamed rule (bug 0012). Its hash is in the
+    // baseline — the description is demonstrably unchanged — and only the
+    // measurement moved, so `isKnown` is false while `hasEntry` is true. Without
+    // this the ratchet's own working case reported "1 rule whose description
+    // changed", which is a false cause under ADR-009 rule 2.
+    if (ctx.hasEntry(violation))
+        return undefined;
+    return ctx.knownSubjects.get(hashSubject(violation, ctx.root));
+}
+export function descriptionChangeFinding(ctx, violations) {
+    if (ctx.knownSubjects.size === 0)
+        return undefined;
+    // Rule descriptions the baseline recorded for subjects this run re-reported
+    // under a different identity. A Map keyed by the OLD description, so the
+    // same edited rule is named once however many violations it has.
+    const changed = new Map();
+    for (const violation of violations) {
+        const recordedRule = renamedRuleFor(ctx, violation);
+        if (recordedRule !== undefined)
+            changed.set(recordedRule, violation.rule);
+    }
+    if (changed.size === 0)
+        return undefined;
+    const where = ctx.sourcePath ?? 'the baseline file';
+    // Identities, never a total (ADR-009 rule 4): name the rules, both spellings,
+    // so the reader can see WHAT changed rather than being told how many did.
+    const pairs = [...changed.entries()]
+        .map(([was, now]) => `\n  was: ${was}\n  now: ${now}`)
+        .join('');
+    const plural = changed.size === 1 ? 'rule' : 'rules';
+    return {
+        rule: 'eess-ts: baseline',
+        element: 'baseline',
+        file: '',
+        line: 0,
+        message: `Baseline at ${where} no longer matches ${String(changed.size)} ${plural} whose ` +
+            `description changed, so already-accepted violations of ${changed.size === 1 ? 'it' : 'them'} ` +
+            `are being reported as new. This is not new rot in your code — the rule was edited, ` +
+            `or its conditions accumulated (v0.23.0):${pairs}`,
+        because: "A violation's identity includes the rule description, so editing a rule re-reports every violation it had already accepted — indistinguishable from a regression unless it is named.",
+        suggestion: `Regenerate the baseline: \`npx eess-ts baseline <your-rule-files> --output ${where}\`. Review the diff: the entries that vanish are the ones listed above, and their replacements should be the same violations under the new description.`,
+        bypassFilters: true,
+    };
+}
+/**
+ * A meta-finding for a baseline that is present, non-empty, and matched
+ * **nothing** in a run that produced findings it could have matched.
+ *
+ * Gated on the measurement, not on the version field. An earlier cut fired
+ * whenever `hashVersion` was older, which was wrong for most users: v2
+ * hashing is byte-identical to v1 for any violation whose fields contain no
+ * path, so the majority of existing baselines still match perfectly. Failing
+ * those with "its entries match nothing" was both a false red and a false
+ * statement — a derived value reported as a fact with nothing disagreeing
+ * with it, which is the ADR-009 rule 5 mistake this bug was about.
+ *
+ * `matched === 0` is the independently-derived signal, and it covers every
+ * cause at once: a v1 file, a root that resolved differently here than where
+ * the file was written, or a baseline for a different project entirely.
+ *
+ * Silent when the run produced nothing to match (`matchable === 0`) — an
+ * empty run is not evidence about the baseline. Carries `bypassFilters`
+ * because the filters are what it is reporting on (ADR-008; plan 0067).
+ */
+export function unmatchedBaselineFinding(ctx, matched, matchable) {
+    if (ctx.knownHashes.size === 0 || matchable === 0 || matched > 0)
+        return undefined;
+    const where = ctx.sourcePath ?? 'the baseline file';
+    const entries = ctx.knownHashes.size;
+    const plural = entries === 1 ? 'entry' : 'entries';
+    const cause = unmatchedCause(ctx);
+    return {
+        rule: 'eess-ts: baseline',
+        element: 'baseline',
+        file: '',
+        line: 0,
+        message: `Baseline at ${where} matched 0 of its ${String(entries)} ${plural} against ` +
+            `${String(matchable)} finding(s) in this run, so every one of them is being reported as new. ${cause}`,
+        because: 'A baseline that matches nothing is indistinguishable from a mass regression, and silently reporting the whole set as new hides which of the two happened (bug 0010).',
+        suggestion: ctx.hashVersion > HASH_VERSION
+            ? 'Upgrade eess-ts to a version that reads this format.'
+            : // `<your-rule-files>` stands in for the caller's own paths on
+                // purpose: the command needs rule files unless a config supplies
+                // them, and printed without them it fails with "No rule files
+                // specified" — a remedy that
+                // cannot remediate (ADR-009 rule 2). Measured. The path is left as
+                // recorded rather than absolutized, so the line is copyable on a
+                // machine other than the one that wrote the baseline.
+                `Regenerate it: \`npx eess-ts baseline <your-rule-files> --output ${where}\` (rule files are implied if an eess-ts config lists them). Review the diff first — entries that vanish were never matching here.`,
+        bypassFilters: true,
+    };
+}
+/**
+ * Why a baseline matched nothing — or, where nothing can be told apart, the
+ * candidates in order.
+ *
+ * Extracted from {@link unmatchedBaselineFinding} so that method stays inside
+ * `eess/max-method-lines`, which bug 0170 re-derived from span lines to code
+ * lines. Most of what was there was this decision.
+ */
+function unmatchedCause(ctx) {
+    if (ctx.hashVersion < HASH_VERSION) {
+        return `It was written in identity format v${String(ctx.hashVersion)} and this version reads v${String(HASH_VERSION)}, which is the likely cause.`;
+    }
+    if (ctx.hashVersion > HASH_VERSION) {
+        return `It was written in identity format v${String(ctx.hashVersion)}, which is newer than this version reads (v${String(HASH_VERSION)}) — upgrade eess-ts rather than regenerating.`;
+    }
+    // **Do not assert a cause that has not been distinguished from its alternatives.**
+    //
+    // This branch used to say "Same identity format, so the likely cause is that it
+    // was generated against a different repository root". That is one cause among
+    // several and the code has checked none of them —
+    // [ts-archunit bug 0060](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0060-a-pattern-change-silently-invalidates-every-baselined-finding.md),
+    // where a shipped default pattern changed and a reader spent an hour on `root`
+    // before regenerating, which is the outcome ts-archunit's `docs/upgrading.md` exists to prevent.
+    //
+    // The rename detector above cannot cover it either: when a pattern changes, the
+    // rule description AND the subject move together, so `hashSubject` misses and
+    // that diagnostic stays silent. Nothing here can tell these apart, so the honest
+    // output is the candidate list, ordered, with the version-specific one first
+    // because upgrading is when this happens.
+    return ('The identity format is unchanged, so one of its INPUTS moved.\n' +
+        '  This code cannot tell which. In order of likelihood:\n' +
+        '    1. you upgraded, and a shipped rule description or default pattern changed —\n' +
+        '       check the CHANGELOG entry for the version you moved to, which says so when\n' +
+        '       it happens. If this is it, regenerating is correct and expected.\n' +
+        '    2. you upgraded, and a metric changed WHAT IT COUNTS (bug 0171). Those entries\n' +
+        '       normally still match and report themselves — but a rule edited in the same\n' +
+        '       release moves the identity too, and then they land here instead.\n' +
+        '    3. the baseline was generated against a different repository root — see the\n' +
+        '       `root` option on withBaseline()/generateBaseline().\n' +
+        '    4. the rules themselves were edited.');
+}
+//# sourceMappingURL=baseline-diagnostics.js.map

package/dist/helpers/baseline-diagnostics.js.map

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

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

@@ -0,0 +1,19 @@
+import type { ArchViolation } from '@nielspeter/eess';
+/**
+ * Collect violations from rules WITHOUT throwing.
+ *
+ * Used to generate a baseline: run all rules via their non-throwing
+ * `.violations()` terminal (severity-stamped), and write them to a baseline
+ * file.
+ *
+ * @example
+ * const violations = collectViolations(
+ *   classes(p).that().extend('Base').should().notContain(call('parseInt')),
+ *   classes(p).that().extend('Base').should().notContain(newExpr('Error')),
+ * )
+ * generateBaseline(violations, 'arch-baseline.json')
+ */
+export declare function collectViolations(...builders: Array<{
+    violations: () => ArchViolation[];
+}>): ArchViolation[];
+//# sourceMappingURL=baseline-generator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-generator.d.ts","sourceRoot":"","sources":["../../src/helpers/baseline-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,QAAQ,EAAE,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,aAAa,EAAE,CAAA;CAAE,CAAC,GACxD,aAAa,EAAE,CAEjB"}

package/dist/helpers/baseline-generator.js

@@ -0,0 +1,18 @@
+/**
+ * Collect violations from rules WITHOUT throwing.
+ *
+ * Used to generate a baseline: run all rules via their non-throwing
+ * `.violations()` terminal (severity-stamped), and write them to a baseline
+ * file.
+ *
+ * @example
+ * const violations = collectViolations(
+ *   classes(p).that().extend('Base').should().notContain(call('parseInt')),
+ *   classes(p).that().extend('Base').should().notContain(newExpr('Error')),
+ * )
+ * generateBaseline(violations, 'arch-baseline.json')
+ */
+export function collectViolations(...builders) {
+    return builders.flatMap((builder) => builder.violations());
+}
+//# sourceMappingURL=baseline-generator.js.map

package/dist/helpers/baseline-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-generator.js","sourceRoot":"","sources":["../../src/helpers/baseline-generator.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAG,QAAsD;IAEzD,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;AAC5D,CAAC"}

package/dist/helpers/baseline.d.ts

@@ -0,0 +1,336 @@
+import type { ArchViolation } from '@nielspeter/eess';
+/**
+ * Identity-hash format version.
+ *
+ * 1 — sha256(rule::element::message) verbatim; absolute paths leak in.
+ * 2 — the repository root is replaced with a token first, so identity is
+ *     portable across checkouts (bug 0010).
+ *
+ * Note that v2 is byte-identical to v1 for any violation whose fields contain
+ * no path, so most v1 baselines keep matching. The version alone is therefore
+ * NOT grounds to fail — see `unmatchedBaselineFinding`, which fires on the
+ * measurement instead.
+ * 4 — bug 0012. Metric findings gained a producer-set `identity`
+ *     (`file::element::metric`) and an accepted `measured` value, so every entry
+ *     for the ten size and complexity conditions hashes differently. The v3
+ *     precedent applies exactly: `hashViolation`'s FORMULA is untouched and one
+ *     of its inputs moved, which is the case the 0.23.0 withdrawal established
+ *     is worth a bump only when the identity of existing entries actually
+ *     changes. It does here, for that family and no other — a baseline with no
+ *     metric entries is byte-identical and keeps matching.
+ *
+ */
+export declare const HASH_VERSION = 5;
+/**
+ * A single entry in the baseline file.
+ *
+ * Violations are identified by rule + file + content hash.
+ * Line numbers are stored for human readability but NOT used for matching —
+ * they drift as code moves. The content hash (of the violation message +
+ * element name) provides stable identity.
+ */
+export interface BaselineEntry {
+    /** Rule description (from the fluent chain) */
+    rule: string;
+    /** File path relative to the identity root (see `root` below), forward-slashed */
+    file: string;
+    /** Line number at time of baseline (informational, not used for matching) */
+    line: number;
+    /** Stable identity hash: sha256(rule + element + message) */
+    hash: string;
+    /**
+     * The measurement this entry accepted, for a metric finding (bug 0012).
+     *
+     * Present only on metric findings. `filterNew` suppresses such a finding
+     * while the current measurement is **no greater** than this, so improving a
+     * metric stays green and regressing past the accepted value fails. Without
+     * it the message's embedded count made every change — in either direction —
+     * a new finding, and paying down debt turned the build red.
+     */
+    measured?: number;
+    /**
+     * What {@link measured} counts — `code-lines`, `methods`, `complexity`.
+     *
+     * Written since bug 0171 and optional. Absent means the entry predates unit
+     * stamping, which {@link Baseline.isKnown} treats as "unknown unit": still
+     * comparable for the metrics whose meaning has never changed, and NOT
+     * comparable for `code-lines`, because such an entry necessarily recorded a
+     * span. That distinction is the whole point — see {@link MEANING_NEVER_CHANGED}.
+     */
+    measuredUnit?: string;
+    /**
+     * Subject hash: sha256(element + message), i.e. identity WITHOUT the rule
+     * description. Written since 0.24.0 and optional, so a baseline from an
+     * earlier version still loads — it simply cannot be diagnosed when an entry
+     * stops matching, which is honest degradation rather than a guessed cause.
+     * See \{@link hashSubject\} for what it is for.
+     */
+    subject?: string;
+}
+/** A measurement an entry accepted, and what that number counts (bugs 0012, 0171). */
+interface AcceptedMeasurement {
+    value: number;
+    /** `undefined` on any entry written before unit stamping — see {@link measurementComparable}. */
+    unit?: string;
+}
+/**
+ * The baseline file structure.
+ */
+export interface BaselineFile {
+    /** ISO timestamp when the baseline was generated */
+    generatedAt: string;
+    /**
+     * Identity-hash format version. Absent means 1 — a baseline written before
+     * paths were stripped from identity, whose hashes cannot be matched.
+     */
+    hashVersion?: number;
+    /**
+     * Where the identity root sits **relative to this file**, e.g. `'../..'`.
+     *
+     * Recorded rather than re-derived because generation and loading otherwise
+     * discover the root independently, and a disagreement between them is
+     * silent: every hash differs, the baseline matches nothing, and the format
+     * version is identical on both sides so nothing notices. A relative position
+     * is a property of the repository layout, so it is the same on every machine
+     * — which is exactly what the absolute root is not.
+     */
+    root?: string;
+    /** Number of violations recorded */
+    count: number;
+    /** The violations */
+    violations: BaselineEntry[];
+}
+/**
+ * Compute a stable hash for a violation.
+ *
+ * Uses rule + element + message as identity. This survives:
+ * - Line number changes (code moved)
+ * - Unrelated code changes in the same file
+ * - **The checkout's absolute location** — see `root` below
+ *
+ * Does NOT survive:
+ * - Rule DESCRIPTION changes — the assembled `that … should …` text, i.e. editing
+ *   the rule's predicates or conditions. **Not** `.because()`: that sets
+ *   `because`, which is not hashed. The old wording said "(rewording
+ *   .because())" and it was false — measured, two violations differing only in
+ *   `because` hash identically, and so do two differing only in `suggestion`.
+ *   The distinction is load-bearing: it is what makes correcting a preset's
+ *   remedy text a patch rather than a change that invalidates every consumer's
+ *   baseline (bug 0017, whose own defect was a remedy claiming something it
+ *   could not do — sitting in the docstring a compat auditor would check).
+ * - Element renames (class renamed)
+ * - Message text changes (condition wording updated)
+ *
+ * This is intentional — if the rule or element changes,
+ * the violation should be re-evaluated.
+ *
+ * @param root - Repository/workspace root. Every occurrence of it inside the
+ *   rule, element and message is replaced with a stable token before hashing.
+ *   Producers interpolate absolute paths into those fields, so without a root
+ *   the identity encodes the checkout directory and a baseline written on one
+ *   machine matches nothing on another (bug 0010). Omitting it preserves the
+ *   pre-0.19 hash and is only correct when no field contains a path.
+ */
+export declare function hashViolation(violation: ArchViolation, root?: string): string;
+/**
+ * The violation's **subject**: what was found, independent of which rule found it.
+ *
+ * `hashViolation` above is `rule::element::message`, so editing a rule's
+ * predicates or conditions — or accumulating them, which v0.23.0 made happen for
+ * a rule derived off a held rule — changes the identity of violations that did
+ * not change at all. Those entries stop matching and their already-accepted
+ * violations report as **new**, with nothing saying why (bug 0027).
+ *
+ * This is the differently-derived value that tells the two cases apart:
+ *
+ * | baseline entry did not match because… | subject present in the run? |
+ * | ------------------------------------- | --------------------------- |
+ * | the violation was fixed               | no — stay silent, this is success |
+ * | the rule's description changed        | yes — say so, and regenerate |
+ *
+ * Bug 0027's own suggested signal was "an entry whose `rule` string appears under
+ * a different hash", and it cannot work: the rule string is precisely what
+ * changed. Measured before this was built.
+ */
+export declare function hashSubject(violation: ArchViolation, root?: string): string;
+/**
+ * Options shared by baseline loading and generation.
+ */
+export interface BaselineOptions {
+    /**
+     * Repository/workspace root used to make violation identity portable.
+     *
+     * Defaults to the **nearest** enclosing repository or workspace root above
+     * the baseline file — `.git`, then a monorepo marker (`pnpm-workspace.yaml`,
+     * `nx.json`, …) or a `package.json` declaring `workspaces`, then the nearest
+     * `package.json`. Nearest, not outermost: an ancestor that is also a repo (a
+     * home directory under dotfiles version control) would otherwise anchor above
+     * the checkout and leave machine-specific segments in the "relative" path.
+     *
+     * You should rarely need this. `generateBaseline` records where the root sat
+     * relative to the file, and `withBaseline` reuses that, so the two ends
+     * cannot silently disagree. Pass it only to override both — and then the
+     * value must be the same on every machine, so derive it from the repository
+     * layout, never from `process.cwd()`.
+     */
+    readonly root?: string;
+}
+/**
+ * Load a baseline from a JSON file.
+ *
+ * @param baselinePath - Path to the baseline JSON file
+ * @param options - See \{@link BaselineOptions\}
+ * @returns A Baseline object for use with check(\{ baseline \})
+ */
+export declare function withBaseline(baselinePath: string, options?: BaselineOptions): Baseline;
+/**
+ * Generate a baseline file from a list of violations.
+ *
+ * Call this to create/update the baseline:
+ * ```typescript
+ * const violations = collectAllViolations(rules)
+ * generateBaseline(violations, 'arch-baseline.json')
+ * ```
+ */
+export declare function generateBaseline(violations: ArchViolation[], outputPath: string, options?: BaselineOptions): BaselineDelta;
+/**
+ * The delta a `generateBaseline` call applied, for the caller to report.
+ *
+ * Plan 0071's second instrument. The 0.28.0 upgrade recipe is "refresh the
+ * baseline, commit, then upgrade", and its whole safety rests on the adopter
+ * seeing what that refresh accepted. Before this, `baseline` printed only the
+ * new total — so a refresh that accepted 37 findings and one that accepted none
+ * printed the same shape of line, and the number that mattered was the one
+ * nobody could see.
+ */
+export interface BaselineDelta {
+    /** Entries in the file that was overwritten; `undefined` if there was none. */
+    readonly before: number | undefined;
+    /** Entries written now. */
+    readonly after: number;
+    /** Entries written now whose identity was not in the prior file. */
+    readonly added: number;
+    /** Prior entries whose identity is not in what was just written. */
+    readonly removed: number;
+    /** The prior file's hash version, when it had a readable one. */
+    readonly priorHashVersion?: number;
+    /** A prior file existed but could not be read as a baseline. */
+    readonly priorUnreadable: boolean;
+}
+/**
+ * The one-line delta, e.g. `41 → 78 entries (+37, −0)`.
+ *
+ * Kept beside {@link BaselineDelta} rather than in the CLI so the `baseline`
+ * command and any programmatic caller print the same sentence.
+ */
+export declare function formatBaselineDelta(delta: BaselineDelta): string;
+/**
+ * A loaded baseline. Passed to check(\{ baseline \}) to filter known violations.
+ */
+export declare class Baseline {
+    private readonly knownHashes;
+    private readonly root;
+    private readonly hashVersion;
+    private readonly sourcePath?;
+    /**
+     * Subject hash -> the rule description recorded against it. Empty for a
+     * baseline written before 0.24.0, which disables the description-change
+     * diagnosis rather than guessing at it (bug 0027).
+     */
+    private readonly knownSubjects;
+    /**
+     * Hash -> the measurement accepted for it, for metric findings (bug 0012).
+     * Absent for every non-metric entry and for baselines written before this
+     * shipped, where equality of identity remains the right test.
+     */
+    private readonly acceptedMeasurements;
+    constructor(knownHashes: Set<string>, root: string, hashVersion?: number, sourcePath?: string | undefined, 
+    /**
+     * Subject hash -> the rule description recorded against it. Empty for a
+     * baseline written before 0.24.0, which disables the description-change
+     * diagnosis rather than guessing at it (bug 0027).
+     */
+    knownSubjects?: ReadonlyMap<string, string>, 
+    /**
+     * Hash -> the measurement accepted for it, for metric findings (bug 0012).
+     * Absent for every non-metric entry and for baselines written before this
+     * shipped, where equality of identity remains the right test.
+     */
+    acceptedMeasurements?: ReadonlyMap<string, AcceptedMeasurement>);
+    /**
+     * Check if a violation is known (exists in the baseline).
+     * Known violations are filtered out — they don't cause failures.
+     */
+    /**
+     * Whether the baseline holds an entry with this violation's identity.
+     *
+     * Distinct from {@link isKnown}, which also asks whether a metric finding is
+     * still within the measurement that entry accepted. A regressed metric has an
+     * entry and is not known.
+     */
+    hasEntry(violation: ArchViolation): boolean;
+    /**
+     * Whether this violation is already accepted by the baseline.
+     *
+     * Identity answers "is this the same finding?"; for a metric finding that is
+     * not enough, so a known hash is additionally required to be **no worse** than
+     * the accepted measurement — improving a metric stays green, regressing past
+     * the accepted value fails (bug 0012).
+     */
+    isKnown(violation: ArchViolation): boolean;
+    /**
+     * What the diagnoses in `baseline-diagnostics.ts` need, stated explicitly.
+     *
+     * An object rather than `this`, because the fields are `private readonly` and
+     * a diagnosis should depend on the facts it reads, not on the class that
+     * happens to hold them.
+     */
+    private facts;
+    /**
+     * Filter out known violations, returning only new ones.
+     *
+     * Config-level meta-findings (empty selector/discovery) are never baselined
+     * away — a regenerated baseline must not silence them (ADR-008; plan 0067).
+     *
+     * A baseline that matches **nothing** looks identical to "every accepted
+     * violation regressed at once", so that case is reported as what it is —
+     * see \{@link unmatchedBaselineFinding\}.
+     */
+    filterNew(violations: ArchViolation[]): ArchViolation[];
+    /**
+     * The stale-unit measurements in this run, grouped by the unit pair that
+     * changed — so one upgrade is described once however many elements it
+     * touched, with the identities carried inside.
+     *
+     * Extracted from {@link staleMeasurementFinding} because the four
+     * disqualifying cases are most of that method's branching, the same reason
+     * {@link renamedRuleFor} sits beside {@link descriptionChangeFinding}.
+     */
+    private staleMeasurementsByUnit;
+    /**
+     * The accepted measurement this violation matches but CANNOT be compared
+     * against, or `undefined` when there is no such conflict — which covers the
+     * ordinary cases too: not a metric finding, no matching entry, or a unit that
+     * still means what it meant.
+     */
+    private incomparableAcceptedFor;
+    /**
+     * A meta-finding for baselined metric entries whose accepted measurement is
+     * denominated in a unit this version no longer produces — bug 0171.
+     *
+     * Without it, the upgrade that changed a metric reports the affected classes
+     * as ordinary new violations. The author sees findings against code they did
+     * not touch, on a rule they had already baselined, with nothing connecting
+     * that to the release note — the "eess started reporting something new"
+     * failure ADR-009 rule 2 exists to prevent.
+     *
+     * This fires where `unmatchedBaselineFinding` structurally cannot: those
+     * entries MATCH. Identity is intact and only the unit moved, so `matched` is
+     * non-zero and that check stays silent by design.
+     */
+    private staleMeasurementFinding;
+    /** Number of known violations in the baseline */
+    get size(): number;
+}
+export {};
+//# sourceMappingURL=baseline.d.ts.map

package/dist/helpers/baseline.d.ts.map

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