@milehimikey/em 1.8.0 → 1.9.0

package/dist/cli/status.d.ts

@@ -0,0 +1,261 @@
+import { NormalizedModel } from "../model/model.js";
+import { RefsResult } from "../model/refs.js";
+import { DocReason } from "../catalog/docJoin.js";
+import { DriftSignalKind } from "../catalog/driftSignal.js";
+import { Diagnostic } from "../model/validate.js";
+import { CoverageReport } from "./coverage.js";
+import { GitRunner } from "./diff-inputs.js";
+import { SliceDocFacts } from "./conformScope.js";
+/** The 4 canonical slice-doc lifecycle statuses (docs/slice-doc-schema.md) — the same enum
+ *  `em catalog`'s header coloring and `em render`'s status legend already recognize. */
+export declare const CANONICAL_STATUSES: readonly ["draft", "reviewed", "ready-to-implement", "implemented"];
+export type CanonicalStatus = (typeof CANONICAL_STATUSES)[number];
+/** Bucket a slice's lifecycle status falls into for the rollup: one of the 4 canonical values,
+ *  `"no-doc"` (no doc bound at all, or the binding names a missing file — `resolveSliceDocJoin`'s
+ *  `found: false`), `"frontmatter-invalid"` (a doc WAS found — a note binds it — but its
+ *  frontmatter is missing or malformed, so nothing reliable can be read from it; kept distinct
+ *  from `"no-doc"` because "nothing was ever referenced" and "something's referenced but broken"
+ *  are different states worth telling apart in a rollup), or `"unknown"` (a doc was found and its
+ *  frontmatter usable, but `status` isn't one of the 4 canonical strings — a freeform doc,
+ *  matching `em slice index`'s own "unknown" convention). */
+export type StatusBucket = CanonicalStatus | "no-doc" | "frontmatter-invalid" | "unknown";
+export declare function classifyStatusBucket(found: boolean, reason: DocReason, status: string | null): StatusBucket;
+/** One slice's status-rollup facts, joined from the same doc read every doc-aware command
+ *  shares — never a second parse of the model or the doc. */
+export interface SliceStatusFact {
+    file: string;
+    key: string;
+    docFound: boolean;
+    docReason: DocReason;
+    /** Resolved absolute path to the bound doc file, or null when none was found. Two slices can
+     *  legitimately resolve to the SAME doc (MIL-121 `covers:` cross-binding, one doc ratifying
+     *  coverage for several slices) — this is how `buildStatusReport` dedupes doc-body-derived
+     *  counts (Open Questions) so a shared doc's single unresolved question isn't counted once per
+     *  covered slice. */
+    docPath: string | null;
+    rawStatus: string | null;
+    /** The doc's own `implementedIn:` value verbatim (or null) — carried through from the same
+     *  `resolveSliceDocJoin` call this fact set already makes, so `resolveSlicePRsBehindHead`
+     *  (MIL-164) can build its `SliceDocFacts[]` input from these facts directly rather than
+     *  joining every slice's doc a second time. */
+    implementedIn: string | null;
+    /** MIL-171: the doc's own `owner:` value verbatim (or null) — carried through from the same
+     *  `resolveSliceDocJoin` call this fact set already makes, so a per-slice owner rollup
+     *  (`StatusReport.owners`) never needs a second doc join. */
+    owner: string | null;
+    bucket: StatusBucket;
+    driftSignal: DriftSignalKind | null;
+    openQuestionsTotal: number;
+    openQuestionsUnchecked: number;
+}
+export interface SliceStatusFactsResult {
+    facts: SliceStatusFact[];
+    /** Doc-join diagnostics (`binding-missing-file`/`frontmatter-invalid` warnings) raised while
+     *  resolving each slice's doc — the same diagnostics `em export`'s doc join raises. Carried
+     *  back rather than dropped: a state-of-the-system report shouldn't silently swallow "this
+     *  slice's doc reference is broken." */
+    diagnostics: Diagnostic[];
+}
+/**
+ * Resolve every slice's status-rollup facts for one already-compiled model. `baseDir` is the
+ * `.em` file's directory, same doc-resolution convention every other doc-aware command uses.
+ * Open Questions counts are read from the slice's OWN bound doc (re-deriving the key from
+ * `doc.path`, not assuming it's this slice's own — MIL-121 cross-binding can resolve to a
+ * different slice's doc, same re-derivation `em coverage`/`--slice-ready` use) rather than a
+ * second independent parse.
+ */
+export declare function resolveSliceStatusFacts(file: string, model: NormalizedModel, refs: RefsResult, baseDir: string): SliceStatusFactsResult;
+/** Open `issue "text"` markers in a model — the same predicate `em validate --list-issues`
+ *  counts, here reduced to a bare count for the rollup. */
+export declare function countOpenIssues(model: NormalizedModel): number;
+export interface ConformanceEntry {
+    file: string;
+    modelDir: string;
+    hasStateFile: boolean;
+    lastConformance: {
+        date: string;
+        revision: string;
+    } | null;
+    /** The repo `commitsBehindHead` was computed in — `--repo` when given, else the model's own
+     *  directory (works out of the box for a single-repo project; conform-scope's `--repo`
+     *  convention still applies for a model whose implementation lives in a different repo). */
+    repo: string;
+    commitsBehindHead: number | null;
+    /** Slices whose bound doc's `implementedIn:` maps to a path changed since `lastConformance`'s
+     *  revision (MIL-164) — the same `candidateSlices` computation `em conform-scope` makes for
+     *  one model at a time (`conformScope.ts`'s `changedPathsSince` + `buildConformScope`), rolled
+     *  up here to a single count: "how many slices likely shipped code since the last conform
+     *  sweep." Each candidate slice typically corresponds to one merged slice PR, hence the name.
+     *  Null under the same conditions `commitsBehindHead` is null — it needs the same revision to
+     *  diff against, and by construction is only ever null when `error` is also set (see
+     *  `resolveConformanceEntry` below): a bare "opted out of computing this" state doesn't occur
+     *  on the real CLI/MCP call paths, which always supply `sliceDocFacts`. */
+    slicePRsBehindHead: number | null;
+    /** Set when the state file exists and parses, but git couldn't answer commits-behind-HEAD or
+     *  slice-PRs-behind-HEAD (not a git repo, unknown revision, ...) — reported per-model rather
+     *  than aborting the whole rollup, since `em status` is a soft report, not a gate. Also carries
+     *  a state-file parse failure (unparseable `Last conformance:` bullet), same non-fatal
+     *  treatment. */
+    error: string | null;
+}
+/**
+ * `git rev-list --count <revision>..HEAD` in `repo` (any directory inside it, not necessarily
+ * its root — same "anchor dir, resolve toplevel" convention `conformScope.ts`'s
+ * `changedPathsSince` uses). The git runner is injectable so every failure branch is
+ * unit-testable without a real repository.
+ */
+export declare function commitsBehindHead(repo: string, revision: string, runGit?: GitRunner): {
+    ok: true;
+    count: number;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * `M` in "N commits and M slice-PRs behind HEAD" (MIL-164) — how many slices whose doc's
+ * `implementedIn:` names a path this model's target repo changed since `revision`. Reuses the
+ * exact `em conform-scope` machinery for one model at a time: `changedPathsSince` (the same
+ * `git diff --name-only <revision>..HEAD` walk, same injectable `GitRunner`) to get the changed
+ * paths, then `buildConformScope`'s own `implementedIn`-prefix matching (never fuzzy, never a
+ * second guess) to turn them into a candidate-slice count. `full` is always `false` here — this
+ * is only ever called once `lastConformance` is known non-null (see `resolveConformanceEntry`
+ * below), so there is always a revision to diff against.
+ */
+export declare function resolveSlicePRsBehindHead(repo: string, revision: string, slices: SliceDocFacts[], runGit?: GitRunner): {
+    ok: true;
+    count: number;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Resolve one model's conformance entry: read its sibling state file (if any — not every model
+ * has reached the `conform` phase, so a missing state file is routine, not an error), then
+ * compute commits-behind-HEAD and slice-PRs-behind-HEAD (MIL-164) when `Last conformance:` is
+ * set. `repoOverride` is `--repo`; omitted, each model's own directory is used as the repo to
+ * walk (the common single-repo project case — see `repo` field doc above). `sliceDocFacts` is
+ * THIS model's own slice facts (`key`/`status`/`implementedIn`) — the caller's responsibility to
+ * scope correctly per file, since `resolveSlicePRsBehindHead` matches against exactly this
+ * model's slices, not some other input model's.
+ *
+ * A state file is shared by every `.em` file in its directory (`.event-modeling.md` has no
+ * per-model namespacing), but its `Model file:` bullet names exactly ONE of them — so a sibling
+ * file it does NOT describe (the common case: a `conform-scope --seed-asis` scratch copy like
+ * `checkout-asis.em` sitting next to `checkout.em`) must not inherit `checkout.em`'s conformance
+ * record just because it lives in the same directory. When `Model file:` is set and doesn't match
+ * `basename(file)`, the record is reported as unattributed (via `error`, the same non-fatal
+ * channel a git failure uses) rather than silently misattributed.
+ */
+export declare function resolveConformanceEntry(file: string, repoOverride: string | undefined, sliceDocFacts: SliceDocFacts[], runGit?: GitRunner): ConformanceEntry;
+export interface StatusSliceCounts {
+    total: number;
+    byStatus: {
+        draft: number;
+        reviewed: number;
+        readyToImplement: number;
+        implemented: number;
+        noDoc: number;
+        /** A doc IS bound (a `note` names it) but its frontmatter is missing/malformed — see
+         *  `StatusBucket`'s `"frontmatter-invalid"` doc comment. Kept apart from `noDoc` (nothing
+         *  bound at all) and `unknown` (bound, usable, just a freeform `status` value), and always
+         *  equal to `driftSignal.frontmatterInvalid` below — same slices, two dimensions. */
+        frontmatterInvalid: number;
+        unknown: number;
+    };
+}
+export interface StatusDriftCounts {
+    inSync: number;
+    neverImplemented: number;
+    unpropagatedDelta: number;
+    implementedWithoutLink: number;
+    /** Slices with no doc bound at all (or a binding naming a missing file) — driftSignal is null
+     *  because there's nothing to classify. Distinct from `frontmatterInvalid` below: THIS bucket
+     *  is `resolveSliceDocJoin`'s `found: false`, in either dimension. */
+    notApplicable: number;
+    /** A doc IS bound and found (`found: true`) but its frontmatter is missing/malformed, so
+     *  `driftSignal` couldn't be classified — always equal to `slices.byStatus.frontmatterInvalid`
+     *  (same slices). Kept apart from `notApplicable` so "nothing was ever referenced" and
+     *  "something's referenced but broken" don't collapse into one ambiguous bucket (a doc that
+     *  IS found shouldn't tally the same as one that plain doesn't exist). */
+    frontmatterInvalid: number;
+}
+export interface StatusInvariantTotals {
+    testsDir: string;
+    total: number;
+    cited: number;
+    uncovered: number;
+}
+export interface StatusIssueTotals {
+    openIssues: number;
+    openQuestionsTotal: number;
+    openQuestionsUnchecked: number;
+}
+/** One doc-join diagnostic, tagged with the input file it came from — `em status` can aggregate
+ *  several models in one run, so (unlike `em export`'s single-model diagnostics) each entry
+ *  needs to say which file it concerns. */
+export type StatusDiagnostic = {
+    file: string;
+} & Diagnostic;
+/** MIL-171: one slice's owner fact — the per-slice detail this ticket asked `em status` to
+ *  surface, kept deliberately minimal (no other fact duplicated here that `slices`/`diagnostics`
+ *  already carry elsewhere in the report). `file`+`key` identify the slice the same way
+ *  `StatusDiagnostic`'s `file` tags a diagnostic to its model; `owner` is the doc's own `owner:`
+ *  verbatim, null when absent OR when no doc was found at all — same "null when absent"
+ *  convention `em export`'s doc join uses. Listed once per slice, never deduped: two slices
+ *  legitimately sharing one doc (MIL-121 `covers:`) also legitimately share the same owner. */
+export interface StatusOwnerEntry {
+    file: string;
+    key: string;
+    owner: string | null;
+}
+export interface StatusReport {
+    files: string[];
+    slices: StatusSliceCounts;
+    driftSignal: StatusDriftCounts;
+    /** Null when `--tests <dir>` wasn't given — invariant coverage is opt-in (it needs a test
+     *  tree to scan), unlike every other rollup dimension, which is always computable from the
+     *  model(s) alone. */
+    invariants: StatusInvariantTotals | null;
+    issues: StatusIssueTotals;
+    conformance: ConformanceEntry[];
+    /** Doc-join diagnostics (`binding-missing-file`/`frontmatter-invalid` warnings) collected
+     *  while resolving every slice's doc, across every input file — carried here rather than
+     *  discarded, so a state-of-the-system report doesn't hide a broken doc reference just
+     *  because it also folded that slice into `frontmatterInvalid`/`noDoc` above. */
+    diagnostics: StatusDiagnostic[];
+    /** MIL-171: per-slice owner facts, one entry per slice across every input file — see
+     *  `StatusOwnerEntry`. */
+    owners: StatusOwnerEntry[];
+}
+/** Aggregate everything `em status` reports into one `StatusReport` — pure, no I/O. Callers
+ *  (the CLI action, the MCP tool) resolve every input first (compile each model, join every
+ *  slice's doc, scan the test tree once, resolve conformance) and hand the results here. */
+export declare function buildStatusReport(files: string[], sliceFacts: SliceStatusFact[], openIssuesCount: number, invariants: StatusInvariantTotals | null, conformance: ConformanceEntry[], diagnostics: StatusDiagnostic[]): StatusReport;
+/** Sum per-model `CoverageReport`s (see `./coverage.ts`) into one `StatusInvariantTotals` —
+ *  `em status` doesn't need the per-slice/per-ID detail `em coverage --json` carries, just the
+ *  totals, across however many models `--tests <dir>` was scanned against. */
+export declare function aggregateInvariantTotals(testsDir: string, reports: CoverageReport[]): StatusInvariantTotals;
+/** Exported for `em freshness` (freshness.ts, MIL-164) — the standalone surface for exactly
+ *  this one clause, without pulling in the rest of `em status`'s rollup. */
+export declare function formatConformancePart(entry: ConformanceEntry): string;
+/** The one-line rollup: `"8/8 implemented · 20/20 invariants covered · 0 open issues · last
+ *  conformed <rev>, N commits behind HEAD"` (MIL-163's acceptance line). For multiple input
+ *  models, the conformance clause reports the FIRST file's entry — a single-file invocation is
+ *  the common case this line is written for; the full per-model breakdown is always in
+ *  `formatStatusDetail`/the JSON document regardless of file count. */
+export declare function formatStatusSummary(report: StatusReport): string;
+/** The detail block below the summary line: one line per rollup dimension, plus one line per
+ *  model's conformance entry. */
+export declare function formatStatusDetail(report: StatusReport): string;
+/** Full text report: the summary line, a blank line, then the detail block — same
+ *  "rollup line, then detail" shape `em diff`'s text report uses. */
+export declare function formatStatusText(report: StatusReport): string;
+/** A markdown block suited for pasting into a README (MIL-163's `--md`) — a small table,
+ *  same spirit as `em slice index`'s GENERATED Slices table, but not marker-managed: `--md`
+ *  just prints the block, leaving where/whether to embed it to the caller. */
+export declare function formatStatusMarkdown(report: StatusReport): string;
+/** Render one flat-style SVG badge — two colored rects (label, message) plus centered text,
+ *  no external fonts/images/scripts, so it renders identically anywhere an SVG does. */
+export declare function renderBadgeSvg(label: string, message: string, color: string): string;
+/** Build the `em status --badge` SVG document. */
+export declare function buildStatusBadge(report: StatusReport): string;