waterplane 0.1.6 → 0.1.11

package/node_modules/@waterplane/shared/dist/healthindex.d.ts

@@ -72,414 +72,18 @@
  *   the file.
  */
 /** The five baskets the score reads, in the order the body names them. */
-export declare const HEALTH_ENTRIES: readonly ["size", "retouch", "hatches", "context", "untested"];
-export type HealthEntry = (typeof HEALTH_ENTRIES)[number];
-/**
- * The GOOD value of each reading — at or under it, the entry scores 100.
- * Opinion, and PROVISIONAL: picked by the owner from the repos on this
- * desktop on 2026-10-17, not a published standard. `retouch` most of all (a
- * fortnight's rework rate has no long record behind it yet). A repo that
- * disagrees overrides the value it is compared with (`central`), never these.
- * `context` has none here: its good line IS the repo's own warn line
- * (`contextweight.ts`): the setup sheet calls a repo lean under it, so the index
- * must not call the same repo unhealthy.
- */
-export declare const HEALTH_GOOD: {
-    /** Line-weighted mean file length, lines. */
-    readonly lineMean: 500;
-    /** Longest source file, lines. */
-    readonly max: 1000;
-    /** Share of source-file edits that rework the previous edit. Provisional. */
-    readonly retouch: 0.15;
-    /** UNEXPLAINED escape hatches per 1,000 source lines. */
-    readonly hatches: 2;
-    /** Share of source files no test reaches. */
-    readonly untested: 0.2;
-};
-/** Context's good line, as a share of the repo's warn line: all of it — the setup sheet calibrated
- *  that line so a well-organised repo is NOT flagged; half of it made the two disagree on one number. */
-export declare const HEALTH_CONTEXT_GOOD_SHARE = 1;
-/** The headline never sits more than this many points above its worst entry. */
-export declare const HEALTH_SCORE_CAP_GAP = 30;
-/** An entry scoring under this is a `warn` alert… */
-export declare const HEALTH_ALERT_WARN = 50;
-/** …and under this a `severe` one. */
-export declare const HEALTH_ALERT_SEVERE = 25;
-/** Links of history needed before a move is called at all. */
-export declare const HEALTH_INDEX_MIN_WEEKS = 8;
-/** Prior rolling four-week windows needed before a MONTH move is called. */
-export declare const HEALTH_INDEX_MIN_MONTH_WINDOWS = 4;
-/** Width of the month horizon, in weekly points. */
-export declare const HEALTH_INDEX_MONTH_WEEKS = 4;
-/** A move must sit below this percentile of its own past to be a drop… */
-export declare const HEALTH_INDEX_LOW_PCT = 10;
-/** …or above this one to be a rise. */
-export declare const HEALTH_INDEX_HIGH_PCT = 90;
-/** …AND move the score by at least this many points. */
-export declare const HEALTH_INDEX_MIN_POINTS = 2;
-/**
- * The context-weight warn line when the repo has none of its own: the setup
- * checklist's `DEFAULT_CONTEXT_LIMITS.maxChars` (`contextweight.ts`), restated
- * as a literal so this module carries no import cycle through the index.
- * Pinned equal to it by the test.
- */
-export declare const HEALTH_INDEX_DEFAULT_WARN_CHARS = 16000;
-/** The engine's `context.reason` for a tree with no CLAUDE.md (`metrics/context.mjs`; a tools test pins the two equal). */
-export declare const HEALTH_NO_CLAUDE_MD = "no CLAUDE.md at this commit";
-/**
- * The fields of one series row this module reads. Everything is optional
- * because a row is parsed JSON: a family can be absent (`{value: null,
- * reason}`) or missing outright, and either way that entry is absent.
- */
-export interface HealthSeriesRow {
-    sha?: string;
-    day: string;
-    ts: number;
-    batch?: boolean;
-    prereg?: string;
-    size?: {
-        value?: {
-            p95?: unknown;
-            max?: unknown;
-            maxPath?: unknown;
-            lineMean?: unknown;
-        } | null;
-    } | null;
-    retouch?: {
-        value?: {
-            rate?: unknown;
-        } | null;
-    } | null;
-    hatches?: {
-        value?: Record<string, unknown> | null;
-    } | null;
-    context?: {
-        value?: {
-            claudeMdChars?: unknown;
-            descChars?: unknown;
-        } | null;
-        reason?: unknown;
-    } | null;
-    untested?: {
-        value?: unknown[] | null;
-    } | null;
-    classics?: {
-        value?: {
-            loc?: unknown;
-            files?: unknown;
-        } | null;
-    } | null;
-    /** The repo's disables and overrides in force on this row; absent = none. */
-    central?: HealthRowCentral | null;
-}
-/** `row.central` — written by the engine's `central.mjs`. */
-export interface HealthRowCentral {
-    /** Fingerprint of what was APPLIED on this row; "" (or absent) = nothing. */
-    fp?: unknown;
-    disabled?: Record<string, {
-        why?: unknown;
-    } | null> | null;
-    override?: Record<string, {
-        value?: unknown;
-        why?: unknown;
-    } | null> | null;
-}
-/** Size's two sub-readings, each with its value and score. */
-export interface HealthSizeParts {
-    lineMean: {
-        value: number;
-        score: number;
-    };
-    max: {
-        value: number;
-        score: number;
-        path: string | null;
-    };
-}
-/** Which reading an alert is about: an entry, or one of size's two sub-readings. */
-export type HealthAlertSubject = Exclude<HealthEntry, "size"> | "lineMean" | "max";
-export interface HealthAlert {
-    level: "warn" | "severe";
-    /** The entry the alert counts against (`size` for both sub-readings). */
-    entry: HealthEntry;
-    subject: HealthAlertSubject;
-    /** The value read (after any override) and its good line. */
-    value: number;
-    good: number;
-    score: number;
-    /** The longest file's path, on a `max` alert where the engine named it. */
-    path?: string;
-    /** One sentence: `severe: lib/a.dart is 8,397 lines (good: under 1,000)`. */
-    text: string;
-}
-export interface HealthIndexPoint {
-    /** The ISO week's Monday, `YYYY-MM-DD` (UTC). */
-    week: string;
-    /** The headline SCORE, 0–100: `min(mean, worst + HEALTH_SCORE_CAP_GAP)`. */
-    index: number;
-    /** Geometric mean of the enabled entries' scores, before the cap. */
-    mean: number;
-    /** Each enabled entry's score, 0–100. */
-    scores: Partial<Record<HealthEntry, number>>;
-    /** Size's two sub-readings; null where size is disabled. */
-    sizeParts: HealthSizeParts | null;
-    /** The worst entry when the cap set the headline (`index < mean`), else null. */
-    cappedBy: HealthEntry | null;
-    /** Every entry or size sub-reading under `HEALTH_ALERT_WARN`, worst first. */
-    alerts: HealthAlert[];
-    /** A prereg or `central` change since the previous scored week: the score
-     *  stands as measured, but the link is not used to call a move. */
-    gap: boolean;
-    /** `ln(index / previous index)`; `null` on the first scored week and on a gap. */
-    lnLink: number | null;
-    /** How many entries the contributions split the mean's move over (0 on the first week and a gap). */
-    comparable: number;
-    /**
-     * Each entry's share of the MEAN's move, in LOG POINTS:
-     * `prevMean · (ln s_cur − ln s_prev) / n`. Log points are what is additive —
-     * the terms of a geometric mean add in log space — so these sum EXACTLY to
-     * `prevMean · ln(mean / prevMean)`. Negative = that entry's score fell
-     * (its metric rose). The cap is explained apart, by `cappedBy`.
-     */
-    contributions: Partial<Record<HealthEntry, number>>;
-    /** The values read this week (after any override); size's is `lineMean`. */
-    values: Partial<Record<HealthEntry, number>>;
-    prereg: string | null;
-    /**
-     * Days since the previous SCORED week (Monday to Monday, so a multiple of
-     * 7); null on the first. A week with no commit has no row, and a week with a
-     * partial basket has no score, so a link over 7 days spans weeks with no
-     * score — a reader should be told before reading it as one week's move.
-     */
-    spanDays: number | null;
-    /** Why a gap was marked: the engine's definition moved, or the repo's own
-     *  `central` config moved. (`nothing` is no longer produced: every scored
-     *  week has every enabled entry.) */
-    gapReason?: "prereg" | "central" | "nothing";
-    /** The repo's `central` fingerprint this week; "" = none applied. */
-    central: string;
-    /** Entries the repo disabled this week — out of the mean, not absent readings. */
-    disabled: HealthEntry[];
-    /** Entries whose value this week is the repo's override, not the engine's. */
-    overridden: HealthEntry[];
-    /** Source files and lines this week (`classics`), so growth can be stated;
-     *  null where that reading was absent. */
-    tree: {
-        files: number;
-        loc: number;
-    } | null;
-}
-export interface HealthIndexSeries {
-    /** The first SCORED week — no longer a "100", just where the line starts. */
-    baselineWeek: string;
-    /** One point per scored week, oldest first. */
-    points: HealthIndexPoint[];
-}
-/** `100 · min(1, good / value)`; a value at or under 0 is 100. */
-export declare function healthScore(value: number, good: number): number;
-/** The Monday (UTC) of the ISO week holding `day` (`YYYY-MM-DD`), or null for a malformed day. */
-export declare function isoWeekOf(day: string): string | null;
-/** The last row (greatest `ts`) of each ISO week, oldest week first. */
-export declare function healthWeeks(rows: readonly HealthSeriesRow[]): {
-    week: string;
-    row: HealthSeriesRow;
-}[];
-/** The good line of the context entry for a repo's warn line (null = the default). */
-export declare function healthContextGood(contextWarnChars: number | null): number;
-/** One week's readings: the five values (size's is `lineMean`), plus size's longest file. */
-export interface HealthEntryReadings {
-    values: Partial<Record<HealthEntry, number>>;
-    /** The longest file, read beside `lineMean`; absent where size is. */
-    max?: {
-        value: number;
-        path: string | null;
-    };
-}
-/**
- * One week's values, raw (no epsilon, no floor — `min(1, good/value)` is
- * finite for any value ≥ 0); an entry is absent where its reading is.
- *
- * - `size` is `lineMean` and needs `max` beside it; either missing ⇒ absent.
- * - `untested` is a SHARE: `untested.count / classics.files` — the source-file
- *   count of the same tree, which counts test files too, so the share is a
- *   floor. A share and not the count, so a repo that grows does not read as
- *   slipping just for having more modules.
- * - `hatches` is UNEXPLAINED escapes per kLOC where the row classified them
- *   (engine 2026-10-16a on); every occurrence on an older row.
- * - `context` is `claudeMdChars + descChars`; `descChars` null (no counted
- *   skills) counts as 0 descriptions.
- */
-export declare function healthEntryReadings(row: HealthSeriesRow): HealthEntryReadings;
-/** The five values alone — `healthEntryReadings(row).values`. The warn line is not read here any more (scores read it). */
-export declare function healthEntryValues(row: HealthSeriesRow, _contextWarnChars?: number | null): Partial<Record<HealthEntry, number>>;
-/**
- * What the repo applied on this row: its fingerprint and which entries it
- * disabled or overrode. An entry both disabled and overridden reads disabled
- * (the engine never writes both; a hand-edited row must not count twice).
- */
-export declare function centralOf(row: HealthSeriesRow): {
-    fp: string;
-    disabled: HealthEntry[];
-    overridden: HealthEntry[];
-};
-/** Plain names for an entry, as the cap sentence names it. */
-export declare const HEALTH_ENTRY_LABEL: Record<HealthEntry, string>;
-/**
- * The cap, said once: `null` when the cap did not set the number. The worst
- * entry's score is derived (`value − HEALTH_SCORE_CAP_GAP`), so the wire
- * summary can be worded from its three fields alone.
- */
-export declare function healthCapWords(s: {
-    value: number;
-    mean: number;
-    cappedBy: HealthEntry | null;
-}): string | null;
-/**
- * The scored series. `null` when no week has every enabled entry — no score
- * is no series, never a number nobody measured.
- */
-export declare function healthIndex(rows: readonly HealthSeriesRow[], contextWarnChars: number | null): HealthIndexSeries | null;
-/** One row by the SAME formula a week uses (`scoreWeek`); null when an enabled entry is absent. */
-export declare function healthRowScore(row: HealthSeriesRow, contextWarnChars: number | null): {
-    index: number;
-    mean: number;
-    scores: Partial<Record<HealthEntry, number>>;
-    cappedBy: HealthEntry | null;
-} | null;
-/** One scored commit (a series row) for the phone's commits axis. No lnLink, contributions or move. */
-export interface HealthCommitPoint {
-    sha7: string;
-    day: string;
-    ts: number;
-    week: string;
-    index: number;
-    mean: number;
-    cappedBy: HealthEntry | null;
-    /** Prereg or central fingerprint differs from the previous scored row: do not join the line. */
-    gap: boolean;
-}
-export interface HealthCommitSeries {
-    points: HealthCommitPoint[];
-    /** Scored rows before thinning. */
-    total: number;
-    thinned: boolean;
-}
-/** Thin to ~`max`: each ISO week's LAST point stays; `ceil(n/max)`-long runs keep their min and max index. At most 2*max + weeks. */
-export declare function thinCommitPoints(points: readonly HealthCommitPoint[], max: number): HealthCommitPoint[];
-/** Every scorable row as a commit point, thinned to about `max`; `null` when no row scores. */
-export declare function healthIndexCommits(rows: readonly HealthSeriesRow[], contextWarnChars: number | null, max?: number): HealthCommitSeries | null;
-/** `absent` = an older host (no key), `none` = the host looked and nothing scores, else `present`. */
-export declare function healthCommitsAvailability(view: {
-    commits?: HealthCommitSeries | null;
-} | null | undefined): "absent" | "none" | "present";
-/** How far back "vs 12 weeks ago" looks, in weeks. */
-export declare const HEALTH_INDEX_VS_WEEKS = 12;
-export interface HealthIndexVs {
-    /** `now.index / then.index` — 1.05 is five percent healthier. */
-    ratio: number;
-    /** Score points between the two (`now − then`). */
-    delta: number;
-    then: HealthIndexPoint;
-    now: HealthIndexPoint;
-    /** Weeks actually between the two points — `weeks` asked or more, since a
-     *  week nobody measured has no point. The UI names `then.week`. */
-    weeks: number;
-}
-/**
- * "Vs 12 weeks ago": the score at `points[at]` (default the latest) against
- * the LATEST measured point at least `weeks` earlier — however much further
- * back that is, because a week with no commit has no row and the honest
- * comparison names the week it actually used (`then.week`, `weeks`). Null
- * only when no point sits that far back (a series younger than the horizon).
- *
- * Both ends are absolute scores, so the ratio is simply the two numbers —
- * including any prereg or `central` change between them (the point's `gap`
- * says one happened; the caller decides whether to say so).
- */
-export declare function healthIndexVs(points: readonly HealthIndexPoint[], weeks?: number, at?: number): HealthIndexVs | null;
-export interface HealthMove {
-    kind: "drop" | "rise" | null;
-    horizon: "week" | "month" | null;
-    /** Index points the horizon moved (latest − then); null when there is no comparable move to state. */
-    delta: number | null;
-    reason: string;
-}
-export interface HealthMoveOpts {
-    minWeeks?: number;
-    minMonthWindows?: number;
-    lowPct?: number;
-    highPct?: number;
-    minPoints?: number;
-}
-/**
- * Whether the latest move is unusual for THIS repo: the week's link against
- * the distribution of every earlier link, then (only if the week says nothing)
- * the last four weeks against every earlier rolling four-week change. Both
- * need the percentile AND a minimum number of points, so a dead-flat series
- * cannot call a 0.1-point wobble a drop. Under `HEALTH_INDEX_MIN_WEEKS` links
- * of history there is no distribution to stand on: `kind: null`, with why.
- */
-export declare function assessHealthMove(points: readonly HealthIndexPoint[], opts?: HealthMoveOpts): HealthMove;
-/** A signed whole number with a real minus sign: `−4`, `+3`, `±0`. */
-export declare function signedPoints(n: number): string;
-export interface HealthWords {
-    /** Short label for the repo row: `Health 94 −4`. */
-    chip: string;
-    /** `Health score 94 (−4 this week)`. */
-    title: string;
-    /** Names the (at most two) metrics that carried the move, or "" when none can be named. */
-    body: string;
-}
-/**
- * When the latest measured week happened, worded against the week it is now:
- * `this week` only when they are the same ISO week — a week with no commit has
- * no point, so the newest one can be months old — else `in the week of <Monday>`.
- * `currentWeek` absent = the caller did not say, and the claim falls back to
- * naming the week (never a `this week` nobody checked).
- */
-export declare function healthWeekWhen(week: string, currentWeek?: string | null): string;
-/**
- * The notification and chip wording for a called move. `null` when there is
- * nothing to say (no move called, or no points) — a sentence is never written
- * around a null. `currentWeek` (the ISO week's Monday, `isoWeekOf(today)`)
- * decides whether the latest point may be called "this week".
- */
-export declare function healthMoveWords(points: readonly HealthIndexPoint[], move: HealthMove, currentWeek?: string | null): HealthWords | null;
-/** What `RepoTarget.healthIndex` carries. */
-export interface RepoHealthIndex {
-    /** The latest headline score, 0–100. */
-    value: number;
-    /** The latest week's move in score points; null on a gap week or the first scored week. */
-    deltaWeek: number | null;
-    /** The latest week's Monday. */
-    week: string;
-    move: "drop" | "rise" | null;
-    /** The mean before the cap, so `healthCapWords` can be said from this summary alone. */
-    mean?: number;
-    /** The entry holding the score down when the cap set it, else null. */
-    cappedBy?: HealthEntry | null;
-    /** The worst alert level on the latest week; null when nothing is under the warn line. */
-    alert?: "warn" | "severe" | null;
-    /** That worst alert's sentence; null with it. */
-    alertText?: string | null;
-}
-/** The wire summary for one repo, or null where there is no index (the field stays ABSENT, never 0). */
-export declare function repoHealthIndexOf(series: HealthIndexSeries | null, move?: HealthMove | null): RepoHealthIndex | null;
-/**
- * `GET /api/repos/:id/healthindex` — the whole scored series for the phone's
- * chart (the latest point carries the alerts and `cappedBy`), the called move
- * and its words. `series: null` + `reason` when there is no series file or no
- * scored week yet; never a made-up number.
- */
-export interface HealthIndexResponse {
-    series: HealthIndexSeries | null;
-    move: HealthMove | null;
-    words: HealthWords | null;
-    /** ISO time of the last weekly refresh this host ran for the repo, if any. */
-    lastRefresh: string | null;
-    reason?: string;
-    /** Context per request by ISO week (`healthspend.ts`); absent with no ledger (older host; VS Code before its first log scan). */
-    spend?: import("./healthspend.js").HealthSpendWeek[];
-    /** Scored commits, thinned. ABSENT only on an older host; null = no row scores (or no series). */
-    commits?: HealthCommitSeries | null;
-}
+export { HEALTH_ENTRIES, HEALTH_GOOD, HEALTH_CONTEXT_GOOD_SHARE, HEALTH_SCORE_CAP_GAP, HEALTH_ALERT_WARN, HEALTH_ALERT_SEVERE, HEALTH_INDEX_MIN_WEEKS, HEALTH_INDEX_MIN_MONTH_WINDOWS, HEALTH_INDEX_MONTH_WEEKS, HEALTH_INDEX_LOW_PCT, HEALTH_INDEX_HIGH_PCT, HEALTH_INDEX_MIN_POINTS, HEALTH_INDEX_DEFAULT_WARN_CHARS, HEALTH_NO_CLAUDE_MD, } from "./healthindex/types.js";
+export type { HealthEntry, HealthSeriesRow, HealthRowCentral, HealthSizeParts, HealthAlertSubject, HealthAlert, HealthIndexPoint, HealthIndexSeries, } from "./healthindex/types.js";
+export { healthScore, isoWeekOf, healthWeeks, healthContextGood, healthEntryReadings, healthEntryValues, centralOf, } from "./healthindex/readings.js";
+export type { HealthEntryReadings, } from "./healthindex/readings.js";
+export { HEALTH_ENTRY_LABEL, healthCapWords, healthIndex, healthRowScore, } from "./healthindex/score.js";
+export { thinCommitPoints, healthIndexCommits, healthCommitsAvailability, } from "./healthindex/commits.js";
+export type { HealthCommitPoint, HealthCommitSeries, } from "./healthindex/commits.js";
+export { HEALTH_INDEX_VS_WEEKS, healthIndexVs, } from "./healthindex/vs.js";
+export type { HealthIndexVs, } from "./healthindex/vs.js";
+export { assessHealthMove, } from "./healthindex/move.js";
+export type { HealthMove, HealthMoveOpts, } from "./healthindex/move.js";
+export { signedPoints, healthWeekWhen, healthMoveWords, } from "./healthindex/words.js";
+export type { HealthWords, } from "./healthindex/words.js";
+export { repoHealthIndexOf, } from "./healthindex/repoindex.js";
+export type { RepoHealthIndex, HealthIndexResponse, } from "./healthindex/repoindex.js";