@jevitate/cli 0.9.0 → 0.11.0

package/dist/locator-health-api.d.ts

@@ -0,0 +1,101 @@
+import { type Journey } from "@jevitate/journey";
+import type { LocatorHealthSummary } from "./check-types.js";
+import { type CompactLocatorHealth, type LocatorHealthDetail, type LocatorHealthTrend, type LocatorLevels, type LocatorSuggestion, type ResolvedStepInput } from "./locator-health.js";
+import { DEFAULT_TEST_ID_ATTRIBUTES } from "./project-config.js";
+/**
+ * #470 — locator health: how stable each recorded step's target is against the team's test-id
+ * convention (the selector-ladder rung it resolves by; `data-tflow-id` never counts, #468), why a
+ * brittle one is brittle, and the fix for the app. Advisory everywhere (result.json, report,
+ * check.json warnings, the review sheet); `check` gates only past the team's opt-in threshold
+ * `--max-brittle-steps <n>`. The analysis itself is pure (`locator-health.ts`); this module loads.
+ *
+ * - `jevitate locator-health [--journey <id> | --run <result.json>] [--baseline <file>]` / MCP
+ *   `locator_health` (read-only): every promoted Journey by default, one Journey, or the steps of one
+ *   run result (the rung each step actually resolved by, when the run recorded it).
+ * - The test-id attribute list is project config (`testIdAttributes` in `<repo>/.jevitate/project.json`;
+ *   default `data-testid`, `data-test`; teams add e.g. `data-cy`, `data-qa`) — never a flag.
+ */
+export { DEFAULT_TEST_ID_ATTRIBUTES };
+export interface LocatorHealthRequest {
+    /** The journeys dir (`--dir`, else the repo's `.jevitate/journeys`). */
+    readonly journeysDir: string;
+    /** The project data dir whose config holds `testIdAttributes`; null outside a project (defaults apply). */
+    readonly projectDir: string | null;
+    /** `--journey <id>`: just this Journey (exclusive with `runResult`). */
+    readonly journeyId?: string;
+    /** `--run <result.json>`: the steps of this run result (exclusive with `journeyId`). */
+    readonly runResult?: string;
+    /**
+     * `--baseline <file>`: a previous `locator-health --json` output (or a run's result.json) to report
+     * the trend against — steps improved / regressed per Journey.
+     */
+    readonly baseline?: string;
+}
+export interface LocatorHealthJourney {
+    readonly id: string;
+    readonly health: LocatorHealthDetail;
+    /** Against `--baseline`, when the baseline has this Journey. */
+    readonly trend?: LocatorHealthTrend;
+}
+export interface LocatorHealthReport {
+    readonly source: {
+        readonly kind: "journeys";
+    } | {
+        readonly kind: "journey";
+        readonly id: string;
+    } | {
+        readonly kind: "run";
+        readonly path: string;
+    };
+    /** The convention applied (from project config, else DEFAULT_TEST_ID_ATTRIBUTES). */
+    readonly testIdAttributes: readonly string[];
+    readonly journeys: readonly LocatorHealthJourney[];
+    readonly summary: LocatorHealthSummary & {
+        readonly levels: LocatorLevels;
+        readonly line: string;
+    };
+    /** The work list for the app: one fix per element, de-duplicated across steps and Journeys. */
+    readonly suggestions: readonly LocatorSuggestion[];
+    /** Totals against `--baseline`. */
+    readonly trend?: LocatorHealthTrend & {
+        readonly baseline: string;
+        readonly line: string;
+    };
+}
+export declare class LocatorHealthInputError extends Error {
+    readonly code = "E_LOCATOR_HEALTH_INPUT";
+    constructor(message: string);
+}
+/** The project's test-id convention (throws `ProjectConfigError` on a malformed config). */
+export declare function testIdAttributesOf(projectDir: string | null): readonly string[];
+/**
+ * The convention for a writer that must not fail on it (a run's result.json): the project's, else the
+ * default when the config is malformed — `jevitate locator-health` is where a bad config is reported.
+ */
+export declare function testIdAttributesOrDefault(projectDir?: string | null): readonly string[];
+/** A Journey's (static) or a run's (with `resolved`) locator health. */
+export declare function journeyLocatorHealth(journey: Journey, testIdAttributes: readonly string[], resolved?: readonly ResolvedStepInput[]): LocatorHealthDetail;
+/**
+ * What a Journey run's result.json carries (`result.locatorHealth`): the compact health of the run —
+ * the rung each step resolved by when the run recorded it. Undefined when no step acts on a target.
+ */
+export declare function runLocatorHealth(journey: Journey, resolved: readonly ResolvedStepInput[] | undefined, testIdAttributes?: readonly string[]): CompactLocatorHealth | undefined;
+/** Read-only: never changes a Journey and never gates (the exit code is 0 on any report). */
+export declare function locatorHealth(req: LocatorHealthRequest): Promise<LocatorHealthReport>;
+/** The human rendering (no `--json`): per Journey and its brittle steps, the totals, the trend and the work list. */
+export declare function renderLocatorHealth(r: LocatorHealthReport, opts?: {
+    readonly top?: number;
+}): string;
+/**
+ * `check --max-brittle-steps <n>`: the opt-in gate — a Journey item with more than `n` brittle steps
+ * is a gating finding. Called by check-cli before the suite runs; `exceedsBrittleSteps(health, n)`
+ * (locator-health.ts) is the per-item verdict.
+ *
+ * Contract for check integration: add `maxBrittleSteps?: number` to `RunCheckOptions` (check-types.ts)
+ * and have check-cli pass `gate.maxBrittleSteps` through to `runCheck`; check.json reports it in
+ * `LocatorHealthSummary.maxBrittleSteps` / `exceeded`.
+ */
+export interface BrittleStepGate {
+    readonly maxBrittleSteps: number;
+}
+export declare function brittleStepGate(maxBrittleSteps: number): BrittleStepGate;

package/dist/locator-health-api.js

@@ -0,0 +1,203 @@
+import { readFile } from "node:fs/promises";
+import { FsJourneyStore } from "@jevitate/journey";
+import { analyzeRecording, combineHealth, compactHealth, compareLocatorHealth, trendLine, } from "./locator-health.js";
+import { DEFAULT_TEST_ID_ATTRIBUTES, loadProjectConfig } from "./project-config.js";
+import { findProjectDir } from "./project-dir.js";
+/**
+ * #470 — locator health: how stable each recorded step's target is against the team's test-id
+ * convention (the selector-ladder rung it resolves by; `data-tflow-id` never counts, #468), why a
+ * brittle one is brittle, and the fix for the app. Advisory everywhere (result.json, report,
+ * check.json warnings, the review sheet); `check` gates only past the team's opt-in threshold
+ * `--max-brittle-steps <n>`. The analysis itself is pure (`locator-health.ts`); this module loads.
+ *
+ * - `jevitate locator-health [--journey <id> | --run <result.json>] [--baseline <file>]` / MCP
+ *   `locator_health` (read-only): every promoted Journey by default, one Journey, or the steps of one
+ *   run result (the rung each step actually resolved by, when the run recorded it).
+ * - The test-id attribute list is project config (`testIdAttributes` in `<repo>/.jevitate/project.json`;
+ *   default `data-testid`, `data-test`; teams add e.g. `data-cy`, `data-qa`) — never a flag.
+ */
+export { DEFAULT_TEST_ID_ATTRIBUTES };
+export class LocatorHealthInputError extends Error {
+    code = "E_LOCATOR_HEALTH_INPUT";
+    constructor(message) {
+        super(message);
+        this.name = "LocatorHealthInputError";
+    }
+}
+/** The project's test-id convention (throws `ProjectConfigError` on a malformed config). */
+export function testIdAttributesOf(projectDir) {
+    return loadProjectConfig(projectDir).testIdAttributes;
+}
+/**
+ * The convention for a writer that must not fail on it (a run's result.json): the project's, else the
+ * default when the config is malformed — `jevitate locator-health` is where a bad config is reported.
+ */
+export function testIdAttributesOrDefault(projectDir = findProjectDir()) {
+    try {
+        return testIdAttributesOf(projectDir);
+    }
+    catch {
+        return DEFAULT_TEST_ID_ATTRIBUTES;
+    }
+}
+/** A Journey's (static) or a run's (with `resolved`) locator health. */
+export function journeyLocatorHealth(journey, testIdAttributes, resolved) {
+    return analyzeRecording(journey.recording, { testIdAttributes, journeyId: journey.metadata.id, ...(resolved === undefined ? {} : { resolved }) });
+}
+/**
+ * What a Journey run's result.json carries (`result.locatorHealth`): the compact health of the run —
+ * the rung each step resolved by when the run recorded it. Undefined when no step acts on a target.
+ */
+export function runLocatorHealth(journey, resolved, testIdAttributes = testIdAttributesOrDefault()) {
+    const health = journeyLocatorHealth(journey, testIdAttributes, resolved);
+    return health.steps.length === 0 ? undefined : compactHealth(health);
+}
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+async function readJson(path, what) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (err) {
+        throw new LocatorHealthInputError(`${what}: cannot read ${path} (${err instanceof Error ? err.message : String(err)})`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new LocatorHealthInputError(`${what}: ${path} is not JSON`);
+    }
+}
+/** A run result's journey id and resolutions (`{result: {mode: "journey", journeyId, resolved}}`). */
+function runOf(json, path, what) {
+    const result = isRecord(json) && isRecord(json.result) ? json.result : isRecord(json) ? json : undefined;
+    const journeyId = result !== undefined && typeof result.journeyId === "string" ? result.journeyId : undefined;
+    if (result === undefined || journeyId === undefined)
+        throw new LocatorHealthInputError(`${what}: ${path} is not a Journey run result (no result.journeyId)`);
+    const resolved = Array.isArray(result.resolved)
+        ? result.resolved.filter((r) => isRecord(r) && typeof r.index === "number" && typeof r.rung === "string")
+        : undefined;
+    return { journeyId, ...(resolved === undefined ? {} : { resolved }), ...(result.locatorHealth === undefined ? {} : { health: result.locatorHealth }) };
+}
+function asTrendInput(h) {
+    if (!isRecord(h) || typeof h.brittle !== "number" || !Array.isArray(h.steps))
+        return undefined;
+    return h;
+}
+/** Per-Journey baseline healths: a `locator-health --json` output (envelope or report) or a run result. */
+function baselineOf(json, path) {
+    const out = new Map();
+    const report = isRecord(json) && isRecord(json.data) ? json.data : json;
+    if (isRecord(report) && Array.isArray(report.journeys)) {
+        for (const j of report.journeys) {
+            if (!isRecord(j) || typeof j.id !== "string")
+                continue;
+            const h = asTrendInput(j.health);
+            if (h !== undefined)
+                out.set(j.id, h);
+        }
+        return out;
+    }
+    const run = runOf(json, path, "--baseline");
+    const h = asTrendInput(run.health);
+    if (h === undefined)
+        throw new LocatorHealthInputError(`--baseline: ${path} carries no locator health (a locator-health --json output, or a run result that recorded it)`);
+    out.set(run.journeyId, h);
+    return out;
+}
+async function loadJourney(store, id, dir) {
+    const j = await store.get(id);
+    if (j === null)
+        throw new LocatorHealthInputError(`no Journey '${id}' in ${dir}`);
+    return j;
+}
+function sumTrends(trends) {
+    const sum = (k) => trends.reduce((n, t) => n + t[k], 0);
+    return {
+        improved: sum("improved"),
+        regressed: sum("regressed"),
+        unchanged: sum("unchanged"),
+        added: sum("added"),
+        removed: sum("removed"),
+        brittleDelta: sum("brittleDelta"),
+        changes: trends.flatMap((t) => t.changes),
+    };
+}
+/** Read-only: never changes a Journey and never gates (the exit code is 0 on any report). */
+export async function locatorHealth(req) {
+    const testIdAttributes = testIdAttributesOf(req.projectDir);
+    const store = new FsJourneyStore(req.journeysDir);
+    let journeys = [];
+    let source;
+    if (req.runResult !== undefined) {
+        const run = runOf(await readJson(req.runResult, "--run"), req.runResult, "--run");
+        const journey = await loadJourney(store, run.journeyId, req.journeysDir);
+        journeys.push({ id: journey.metadata.id, health: journeyLocatorHealth(journey, testIdAttributes, run.resolved) });
+        source = { kind: "run", path: req.runResult };
+    }
+    else if (req.journeyId !== undefined) {
+        const journey = await loadJourney(store, req.journeyId, req.journeysDir);
+        journeys.push({ id: journey.metadata.id, health: journeyLocatorHealth(journey, testIdAttributes) });
+        source = { kind: "journey", id: req.journeyId };
+    }
+    else {
+        const listed = (await store.list()).filter((m) => m.promoted).sort((a, b) => a.id.localeCompare(b.id));
+        for (const m of listed) {
+            const journey = await store.get(m.id);
+            if (journey !== null)
+                journeys.push({ id: journey.metadata.id, health: journeyLocatorHealth(journey, testIdAttributes) });
+        }
+        source = { kind: "journeys" };
+    }
+    let trend;
+    if (req.baseline !== undefined) {
+        const base = baselineOf(await readJson(req.baseline, "--baseline"), req.baseline);
+        journeys = journeys.map((j) => {
+            const b = base.get(j.id);
+            return b === undefined ? j : { ...j, trend: compareLocatorHealth(j.health, b) };
+        });
+        const total = sumTrends(journeys.flatMap((j) => (j.trend === undefined ? [] : [j.trend])));
+        trend = { ...total, baseline: req.baseline, line: trendLine(total) };
+    }
+    const all = combineHealth(journeys.map((j) => j.health));
+    return {
+        source,
+        testIdAttributes,
+        journeys,
+        summary: { journeys: journeys.length, stable: all.stable, brittle: all.brittle, testIdAttributes, levels: all.levels, line: all.line },
+        suggestions: all.suggestions,
+        ...(trend === undefined ? {} : { trend }),
+    };
+}
+/** The human rendering (no `--json`): per Journey and its brittle steps, the totals, the trend and the work list. */
+export function renderLocatorHealth(r, opts = {}) {
+    const lines = [];
+    for (const j of r.journeys) {
+        lines.push(`${String(j.health.brittle).padStart(4)} brittle / ${j.health.stable} stable  ${j.id}  (${j.health.line})${j.trend === undefined ? "" : `  [${trendLine(j.trend)}]`}`);
+        for (const s of j.health.steps) {
+            if (s.stability === "stable")
+                continue;
+            lines.push(`       step ${s.index + 1}${s.stepId === undefined ? "" : ` (${s.stepId})`} ${s.kind} ${s.locator} — ${s.rung}, ${s.level}: ${s.reasons.join("; ")}`);
+        }
+    }
+    lines.push(`${r.summary.line} across ${r.summary.journeys} Journey(s) (test ids: ${r.testIdAttributes.join(", ")})`);
+    if (r.trend !== undefined)
+        lines.push(r.trend.line);
+    const top = opts.top ?? 10;
+    if (r.suggestions.length > 0) {
+        lines.push(`fixes for the app (${r.suggestions.length} element(s)):`);
+        for (const s of r.suggestions.slice(0, top))
+            lines.push(`  - ${s.fix}  [${s.occurrences.length} step(s): ${s.reasons.join("; ")}]`);
+        if (r.suggestions.length > top)
+            lines.push(`  … ${r.suggestions.length - top} more (--json for all)`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function brittleStepGate(maxBrittleSteps) {
+    if (!Number.isInteger(maxBrittleSteps) || maxBrittleSteps < 0)
+        throw new RangeError(`--max-brittle-steps must be a whole number ≥ 0, got ${maxBrittleSteps}`);
+    return { maxBrittleSteps };
+}
+//# sourceMappingURL=locator-health-api.js.map

package/dist/locator-health-api.js.map

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

package/dist/locator-health.d.ts

@@ -0,0 +1,195 @@
+import type { Recording, Step, TargetDescriptor } from "@jevitate/recording";
+import type { LocatorHealth, LocatorHealthStep, LocatorRung } from "./check-types.js";
+/**
+ * #470 — locator health, the pure core: for every step that acts on a target, the selector rung it
+ * resolves by, how robust that rung is, WHY it is brittle, and the fix for the app under test. A step
+ * is `stable` only when it resolves by a test id from the team's convention (`testIdAttributes`;
+ * `data-tflow-id` never counts, #468) that does not look generated; anything else is `brittle` and
+ * gets a suggestion — a work list for the codebase, de-duplicated by element.
+ *
+ * Static (a Journey's recorded descriptors) or dynamic (a run's `resolved` — the rung that actually
+ * matched at replay, `@jevitate/interpreter` `StepResolution`). No I/O: `locator-health-api.ts` loads
+ * Journeys, results and config; check/report/the review sheet call these helpers.
+ */
+/** The ladder's own grade for a rung (the recorder's `Stability`): how likely it is to survive change. */
+export type LocatorLevel = "high" | "medium" | "low";
+/** Why a step's locator is brittle — the stable vocabulary (machine-readable `code`, human `text`). */
+export type BrittleReasonCode = "no-test-id" | "test-id-not-in-convention" | "tflow-id-not-a-test-id" | "generated-value" | "no-accessible-name" | "duplicate-name" | "positional-css" | "text-copy";
+/** A run's resolution of one step (structurally `@jevitate/interpreter` `StepResolution`). */
+export interface ResolvedStepInput {
+    readonly index: number;
+    readonly stepId?: string;
+    readonly rung: string;
+    readonly testIdAttr?: string;
+    readonly ordinal?: number;
+    readonly candidates?: number;
+}
+/** One step's verdict, in detail (a `LocatorHealthStep`, plus what the reports and the review sheet show). */
+export interface LocatorHealthStepDetail extends LocatorHealthStep {
+    readonly kind: Step["kind"];
+    /** The ladder grade of the rung used. */
+    readonly level: LocatorLevel;
+    /** `recorded`: from the Journey's descriptor; `resolved`: the rung that matched at replay. */
+    readonly source: "recorded" | "resolved";
+    /** The route (path) of the page the step acts on, when known. */
+    readonly route?: string;
+    /** How the step finds its target, e.g. `role=button name="Save"`, `css=main > div:nth-of-type(2)`. */
+    readonly locator: string;
+    readonly reasonCodes: readonly BrittleReasonCode[];
+    /** The key of this step's suggestion (`LocatorSuggestion.key`); absent when stable. */
+    readonly suggestion?: string;
+}
+/** Where a brittle element is used. */
+export interface LocatorOccurrence {
+    readonly journeyId?: string;
+    readonly index: number;
+    readonly stepId?: string;
+}
+/** One actionable fix for the app, per element (route + role + name), however many steps use it. */
+export interface LocatorSuggestion {
+    /** The de-duplication key: `route|role|name` (or `route|css|selector` for an unnamed element). */
+    readonly key: string;
+    readonly route?: string;
+    readonly role?: string;
+    readonly name?: string;
+    /** The element in words, e.g. `the "Save" button`. */
+    readonly element: string;
+    /** A short outerHTML excerpt, when the caller had one (a live page); never a field's value. */
+    readonly html?: string;
+    /** The attribute the fix adds (the convention's first). */
+    readonly attribute: string;
+    /** The suggested test id (kebab-case, from the name and route). */
+    readonly testId: string;
+    /** The fix, e.g. `add data-testid="save-contact" to the "Save" button on /contacts/new`. */
+    readonly fix: string;
+    readonly reasons: readonly string[];
+    readonly occurrences: readonly LocatorOccurrence[];
+}
+export interface LocatorLevels {
+    readonly high: number;
+    readonly medium: number;
+    readonly low: number;
+}
+/** A Journey's (or a run's) locator health in detail — a `LocatorHealth` with the levels, line and fixes. */
+export interface LocatorHealthDetail extends LocatorHealth {
+    readonly steps: readonly LocatorHealthStepDetail[];
+    readonly levels: LocatorLevels;
+    /** e.g. `7/9 steps on stable locators; 2 brittle (high 7 · medium 1 · low 1)`. */
+    readonly line: string;
+    readonly suggestions: readonly LocatorSuggestion[];
+}
+export interface AnalyzeOptions {
+    /** The team's test-id convention (project config `testIdAttributes`). */
+    readonly testIdAttributes: readonly string[];
+    /** Tags each suggestion's occurrences (a multi-Journey report). */
+    readonly journeyId?: string;
+    /** A run's resolutions: the rung that actually matched, per step (overrides the recorded rung). */
+    readonly resolved?: readonly ResolvedStepInput[];
+    /** Short outerHTML excerpts by flat step index, when the caller had a live page. */
+    readonly html?: ReadonlyMap<number, string>;
+}
+/** The target a step acts on, or null (navigate, press, assert, a forEach's items are its own). */
+export declare function stepTarget(step: Step): TargetDescriptor | null;
+interface Verdict {
+    readonly rung: LocatorRung;
+    readonly level: LocatorLevel;
+    readonly codes: BrittleReasonCode[];
+}
+/**
+ * One target's verdict against the convention. `via` (a run's resolution) replaces the recorded rung
+ * when present; everything else is read from the descriptor.
+ */
+export declare function classifyTarget(d: TargetDescriptor, testIdAttributes: readonly string[], via?: ResolvedStepInput): Verdict;
+/** `"Save contact"` → `save-contact` (ASCII letters and digits, at most 40 chars). */
+export declare function kebabCase(s: string): string;
+/** The path of a page URL (`https://x/contacts/new?a=1` → `/contacts/new`); a path is kept as is. */
+export declare function routeOf(url: string | undefined): string | undefined;
+/**
+ * The suggested test id: the element's name in kebab-case, with the route's noun when the name is a
+ * single word (`Save` on /contacts/new → `save-contact`); an unnamed element is named by its route
+ * and tag (`contacts-div`).
+ */
+export declare function suggestTestId(name: string | undefined, route: string | undefined, fallbackTag: string): string;
+/** The element's identity across steps and runs: route + role + name (else its css). */
+export declare function suggestionKey(d: TargetDescriptor, route: string | undefined): string;
+/** Merges suggestions for the same element (route + role + name): occurrences and reasons combined. */
+export declare function dedupeSuggestions(lists: ReadonlyArray<readonly LocatorSuggestion[]>): LocatorSuggestion[];
+export declare function emptyLevels(): LocatorLevels;
+/** `7/9 steps on stable locators; 2 brittle (high 7 · medium 1 · low 1)`. */
+export declare function healthLine(h: {
+    readonly stable: number;
+    readonly brittle: number;
+    readonly levels: LocatorLevels;
+}): string;
+/**
+ * A recording's locator health: every step with a target (flat index, as the interpreter numbers
+ * them), against the convention; with `resolved`, the rung each step actually matched at replay.
+ */
+export declare function analyzeRecording(rec: Recording, opts: AnalyzeOptions): LocatorHealthDetail;
+/** Totals over several healths (a report, a check): counts, levels and the de-duplicated work list. */
+export declare function combineHealth(healths: readonly LocatorHealthDetail[]): {
+    stable: number;
+    brittle: number;
+    levels: LocatorLevels;
+    line: string;
+    suggestions: LocatorSuggestion[];
+};
+/** `check --max-brittle-steps <n>`: true when a Journey item's brittle steps exceed the opt-in threshold. */
+export declare function exceedsBrittleSteps(health: Pick<LocatorHealth, "brittle">, maxBrittleSteps: number | undefined): boolean;
+export interface LocatorTrendStep {
+    /** `stepId`, else `#<index>`. */
+    readonly key: string;
+    readonly from: {
+        readonly rung: LocatorRung;
+        readonly level: LocatorLevel;
+        readonly stability: "stable" | "brittle";
+    };
+    readonly to: {
+        readonly rung: LocatorRung;
+        readonly level: LocatorLevel;
+        readonly stability: "stable" | "brittle";
+    };
+}
+/** Against a baseline: steps whose locator improved / regressed (stability first, then level). */
+export interface LocatorHealthTrend {
+    readonly improved: number;
+    readonly regressed: number;
+    readonly unchanged: number;
+    /** Steps only in the current (added) or only in the baseline (removed). */
+    readonly added: number;
+    readonly removed: number;
+    readonly brittleDelta: number;
+    readonly changes: readonly (LocatorTrendStep & {
+        readonly direction: "improved" | "regressed";
+    })[];
+}
+type TrendInputStep = Pick<LocatorHealthStep, "stepId" | "index" | "rung" | "stability"> & {
+    readonly level?: LocatorLevel;
+};
+/**
+ * The trend of `current` against `baseline` (a previous report or run of the same Journey), keyed by
+ * step id (else index): a Journey re-recorded or healed after the app added test ids shows its
+ * improvement; a step that fell back to a brittle rung shows as a regression.
+ */
+export declare function compareLocatorHealth(current: {
+    readonly brittle: number;
+    readonly steps: readonly TrendInputStep[];
+}, baseline: {
+    readonly brittle: number;
+    readonly steps: readonly TrendInputStep[];
+}): LocatorHealthTrend;
+/** `trend vs baseline: 2 improved, 1 regressed (brittle -1)`. */
+export declare function trendLine(t: LocatorHealthTrend): string;
+/** What a run's result.json / a check item carries: counts, the line, levels, per-step verdicts, top fixes. */
+export interface CompactLocatorHealth extends LocatorHealth {
+    readonly levels: LocatorLevels;
+    readonly line: string;
+    readonly steps: readonly LocatorHealthStep[];
+    readonly suggestions: ReadonlyArray<Pick<LocatorSuggestion, "key" | "element" | "fix" | "reasons"> & {
+        readonly route?: string;
+        readonly steps: number;
+    }>;
+}
+/** The compact form of a detail: per-step rung/stability/reasons, and the top `top` fixes. */
+export declare function compactHealth(h: Pick<LocatorHealthDetail, "stable" | "brittle" | "steps" | "levels" | "line" | "suggestions">, top?: number): CompactLocatorHealth;
+export {};