Add ratcheting coverage-floor gate to CI

.github/workflows/ci.yml

@@ -19,6 +19,10 @@ jobs:
     steps:
       - name: Check out repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # Needed so `git show <base-sha>:coverage-floor.json` below can
+          # resolve the base branch's blob (mirrors lint.yml's guard step).
+          fetch-depth: 0
 
       - name: Setup Node
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@@ -37,12 +41,29 @@ jobs:
       - name: Install test-app dependencies
         run: npm ci --prefix test-app
 
+      # Guards against coverage-floor.json being lowered directly on this PR
+      # branch (paired with a coverage regression) rather than earned via
+      # `npm run coverage:bump`. Mirrors the ESLint baseline guard in
+      # .github/workflows/lint.yml.
+      - name: Guard against a lowered coverage floor
+        if: github.event_name == 'pull_request'
+        run: |
+          git show "${{ github.event.pull_request.base.sha }}:coverage-floor.json" > /tmp/base-coverage-floor.json 2>/dev/null || echo '{}' > /tmp/base-coverage-floor.json
+          node scripts/check-coverage-floor-not-decreased.mjs /tmp/base-coverage-floor.json coverage-floor.json
+
       # Runs the full spec harness with coverage via Vitest (Analog's Angular
       # Vite plugin + istanbul coverage). `vitest run` exits non-zero on any
       # spec failure, gating the build.
       - name: Run test-app harness with coverage
         run: npm --prefix test-app test
 
+      # Ratcheting coverage-floor gate (#627): fails the build if measured
+      # coverage drops below any floor recorded in coverage-floor.json.
+      # Floors only ever move up, via `npm run coverage:bump`, landed as its
+      # own deliberate commit — feature/spec PRs must not edit that file.
+      - name: Enforce coverage-floor gate
+        run: npm run coverage:check
+
       # Coverage is reported here (Vitest's istanbul text-summary in the log
       # above, plus the lcov artifact below). Enforcement of the 80% new-code
       # floor (target 90%) is tracked by #576 and applied once the green

AGENTS.md

@@ -0,0 +1,49 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Repo shape
+
+This is a **raw-source, dual-workspace** Angular library, not a normal Angular CLI app:
+
+- **Root** (`src/ui-kit/`, `src/formly/`) — the `@gsa-sam/sam-ui-elements` library itself. It is published as raw `.ts`/`.scss` source (no build step, no `dist/`) — consumers compile it themselves. `index.ts` re-exports `src/ui-kit`; `src/formly/index.ts` is a second, separately-imported entry point.
+- **`test-app/`** — a _separate_ npm workspace (own `package.json`/`package-lock.json`/`node_modules`) that exists solely to host the Angular build tooling and Vitest test runner needed to exercise the root library's specs. Always `npm ci` (root) **and** `npm ci --prefix test-app` before running anything.
+- Specs live next to the source they test under root `src/**/*.spec.ts` (not copied into `test-app`). `test-app/vitest.config.mts` globs both `test-app/src/**/*.spec.ts` and `../src/**/*.spec.ts`, with `allowExternal: true` so istanbul still instruments files outside `test-app`'s own root.
+
+## Publish contract — do not break silently
+
+`scripts/validate-publish-package.mjs` (`npm run validate:publish`) enforces that `npm pack` still includes every file listed in `scripts/consumer-deep-imports.json` — a frozen list of deep `@gsa-sam/sam-ui-elements/src/...` import paths used by real downstream consumers (`iae-sam-front-end` and others). **Renaming or moving a `src/ui-kit` file that appears in that list is a breaking change for consumers even though nothing inside this repo imports it.** Check that file before restructuring `src/ui-kit`.
+
+## Testing
+
+- Run specs: `npm ci && npm ci --prefix test-app && npm --prefix test-app test` (Vitest, `--coverage`, istanbul provider, jsdom environment). Config lives in `test-app/vitest.config.mts` — **coverage options must stay in this root config**; a shared/extended base config would have them silently ignored (falls back to Vitest defaults: html/clover/json instead of lcov).
+- Run one spec or pattern: `cd test-app && npx vitest run --config vitest.config.mts -t "<name filter>"`, or pass a spec path directly.
+- `it.skip`/`describe.skip`-only files (e.g. `label-wrapper`, `fieldset-wrapper`, the fully-commented-out `alert.spec.ts`) are intentional and contain zero runnable tests — `passWithNoTests: true` is set so these don't fail the run; this preserves prior Karma behavior.
+- Coverage is enforced by a ratcheting floor gate: `coverage-floor.json` at the repo root records minimum statements/branches/functions/lines percentages (fractional, e.g. `53.56`). `node scripts/check-coverage.mjs` (wired into CI as `npm run coverage:check`) fails with a clear per-metric message if measured coverage (from `test-app/coverage/coverage-summary.json`) drops below any floor.
+- **`coverage-floor.json` is a ratchet — it only ever moves up, and only via a dedicated bump.** Feature and spec PRs must **not** edit `coverage-floor.json` directly; raising it is a separate, deliberate commit made with `npm run coverage:bump` (rewrites the floor file to the currently measured coverage — preserving istanbul's fractional `pct`, not floored to a whole percent — and never lowering an existing entry). `.github/workflows/ci.yml` also runs `scripts/check-coverage-floor-not-decreased.mjs` on PRs, comparing `coverage-floor.json` against the base branch and failing if any metric's floor decreased, so a floor can't be hand-lowered in the same PR that regresses coverage. This mirrors the ESLint baseline guard below.
+- The gate scripts are covered by `node --test scripts/check-coverage.test.mjs` and `node --test scripts/check-coverage-floor-not-decreased.test.mjs` (Node's built-in test runner, no extra deps). These are **not currently wired into any CI workflow** — run them manually after touching either script.
+- Playwright E2E smoke test (`test-app/e2e/`) runs via `npm --prefix test-app run test:e2e`, gated separately in `.github/workflows/e2e.yml`.
+
+## Lint
+
+- `npm run lint` (root) / `npm --prefix test-app run lint` run `ng lint` (ESLint) per workspace.
+- A ratcheting warning-baseline gate works the same way as coverage: `eslint-baseline.json` (keys `root`, `test-app`) + `scripts/check-lint-baseline.mjs` fail the build if warnings exceed the recorded baseline, or if there are _any_ errors (errors always fail regardless of the baseline). `--bump` only ever lowers the baseline.
+- `.github/workflows/lint.yml` additionally runs `scripts/check-baseline-not-increased.mjs`, comparing `eslint-baseline.json` on the PR branch against the base branch — this closes the hole where a contributor could raise the ceiling by hand-editing the JSON in the same PR that adds new warnings. The `--bump` scripts are the only sanctioned way to change either baseline file; same rule as `coverage-floor.json` above.
+- Both `scripts/check-lint-baseline.test.mjs` and `scripts/check-baseline-not-increased.test.mjs` exist and pass but, like the coverage gate tests, are **not run in CI** — run `node --test scripts/*.test.mjs` manually when touching any gate script.
+
+## Formatting
+
+- `npm run format:check` / `npm run format` (Prettier). Applies to the whole repo — remember to run it on new root-level `scripts/*.mjs` files too, not just `src/`.
+
+## CI workflows
+
+- `.github/workflows/ci.yml` — installs both workspaces, runs `npm --prefix test-app test`, then `npm run coverage:check`.
+- `.github/workflows/lint.yml` — format check, baseline-not-increased guard, `ng lint` + baseline gate for both workspaces.
+- `.github/workflows/e2e.yml` — Playwright smoke test.
+- `.github/workflows/publish.yml` — npm Trusted Publisher (OIDC) flow, gated on `validate:publish`; only trigger is a GitHub Release (or a dry-run `workflow_dispatch`).
+
+## Angular / TypeScript quirks
+
+- Root `tsconfig.json` targets `es2015`/`commonjs` with `strictNullChecks: false` — this is a legacy config for the raw-source library, distinct from `test-app`'s stricter `tsconfig.spec.json` (`es2022`, TestBed/Vitest types). Don't assume one workspace's TS settings apply to the other.
+- `test-app/src/test-setup.ts` shims several `jsdom` gaps Karma never needed to care about: `Element.scrollIntoView`, `Element.innerText` (falls back to `textContent`), and `Element.animate` (Web Animations API used by `@angular/animations`). If a spec hangs or throws on one of these, check this file before adding a per-spec workaround.
+- `@gsa-sam/icons` is a `test-app`-only dependency (not a root peerDependency) but is imported by root library source (e.g. `header-next`); it's aliased explicitly in `vitest.config.mts` since specs run directly against root `src/` and Node's module resolution wouldn't otherwise reach `test-app/node_modules`.

coverage-floor.json

@@ -0,0 +1,6 @@
+{
+  "statements": 53.56,
+  "branches": 39.77,
+  "functions": 50.31,
+  "lines": 52.84
+}

package.json

@@ -30,6 +30,8 @@
     "lint:report": "ng lint --format json --output-file eslint-report.json",
     "lint:baseline": "npm run lint:report && node scripts/check-lint-baseline.mjs root eslint-report.json",
     "lint:baseline:bump": "npm run lint:report && node scripts/check-lint-baseline.mjs --bump root eslint-report.json",
+    "coverage:check": "node scripts/check-coverage.mjs test-app/coverage/coverage-summary.json",
+    "coverage:bump": "node scripts/check-coverage.mjs --bump test-app/coverage/coverage-summary.json",
     "validate:publish": "node scripts/validate-publish-package.mjs"
   },
   "peerDependencies": {

scripts/check-coverage-floor-not-decreased.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Guards against a coverage-floor being lowered directly in
+ * coverage-floor.json rather than earned via `coverage:bump`.
+ *
+ * The per-metric gate (check-coverage.mjs) only evaluates the floors
+ * committed on the branch being checked, so a contributor could lower a
+ * floor (e.g. `statements` from 53 to 30) in the same PR that regresses
+ * coverage, and the gate would still pass. This script closes that hole by
+ * comparing coverage-floor.json on the PR branch against the base branch's
+ * version and failing if any metric's floor decreased — the same shape as
+ * check-baseline-not-increased.mjs for eslint-baseline.json.
+ *
+ * New metric keys that don't exist on the base branch are allowed (they
+ * can't be "decreased" if there's nothing to compare against). Any increase
+ * or unchanged value is allowed, matching the ratchet-only semantics of
+ * `coverage:bump`.
+ *
+ * Usage:
+ *   node scripts/check-coverage-floor-not-decreased.mjs <base-floor.json> <head-floor.json>
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const [baseArg, headArg] = process.argv.slice(2);
+
+if (!baseArg || !headArg) {
+  console.error(
+    "Usage: node scripts/check-coverage-floor-not-decreased.mjs <base-floor.json> <head-floor.json>"
+  );
+  process.exit(1);
+}
+
+function loadFloors(label, path) {
+  try {
+    return JSON.parse(readFileSync(resolve(path), "utf8"));
+  } catch (error) {
+    console.error(`✖ Could not read ${label} coverage floors at ${path}`);
+    console.error(`  ${error.message}`);
+    process.exit(1);
+  }
+}
+
+const base = loadFloors("base-branch", baseArg);
+const head = loadFloors("pull-request", headArg);
+
+let hasDecrease = false;
+
+for (const metric of Object.keys(head)) {
+  if (!(metric in base)) {
+    // New metric entry — nothing to compare against, so it can't be a
+    // decrease from a previously-trusted value.
+    continue;
+  }
+
+  const baseValue = base[metric];
+  const headValue = head[metric];
+
+  if (!Number.isFinite(baseValue) || !Number.isFinite(headValue)) {
+    console.error(
+      `✖ ${metric}: invalid coverage-floor value (base: ${baseValue}, head: ${headValue})`
+    );
+    hasDecrease = true;
+    continue;
+  }
+
+  if (headValue < baseValue) {
+    console.error(
+      `✖ ${metric}: coverage floor decreased ${baseValue}% → ${headValue}%. ` +
+        "The committed floor can only go up (via `npm run coverage:bump`), never down. " +
+        "Revert this change to coverage-floor.json."
+    );
+    hasDecrease = true;
+  }
+}
+
+if (hasDecrease) {
+  process.exit(1);
+}
+
+console.log(
+  "✓ coverage-floor.json: no metric's floor decreased vs. the base branch."
+);

scripts/check-coverage-floor-not-decreased.test.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * Tests for scripts/check-coverage-floor-not-decreased.mjs — the CI-only
+ * guard that compares coverage-floor.json on a PR branch against the base
+ * branch's version and fails if any metric's floor decreased.
+ *
+ * Run: node --test scripts/check-coverage-floor-not-decreased.test.mjs
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const script = join(scriptDir, "check-coverage-floor-not-decreased.mjs");
+
+function run(args) {
+  try {
+    const stdout = execFileSync("node", [script, ...args], {
+      encoding: "utf8",
+    });
+    return { status: 0, stdout, stderr: "" };
+  } catch (error) {
+    return {
+      status: error.status ?? 1,
+      stdout: error.stdout?.toString() ?? "",
+      stderr: error.stderr?.toString() ?? "",
+    };
+  }
+}
+
+function withTempDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), "floor-guard-"));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function writeFloors(dir, name, data) {
+  const path = join(dir, name);
+  writeFileSync(path, JSON.stringify(data));
+  return path;
+}
+
+test("passes when the floor is unchanged", () => {
+  withTempDir((dir) => {
+    const base = writeFloors(dir, "base.json", {
+      statements: 53,
+      branches: 39,
+      functions: 50,
+      lines: 52,
+    });
+    const head = writeFloors(dir, "head.json", {
+      statements: 53,
+      branches: 39,
+      functions: 50,
+      lines: 52,
+    });
+    const { status } = run([base, head]);
+    assert.equal(status, 0);
+  });
+});
+
+test("passes when a floor is raised", () => {
+  withTempDir((dir) => {
+    const base = writeFloors(dir, "base.json", {
+      statements: 53,
+      branches: 39,
+      functions: 50,
+      lines: 52,
+    });
+    const head = writeFloors(dir, "head.json", {
+      statements: 60,
+      branches: 39,
+      functions: 50,
+      lines: 52,
+    });
+    const { status } = run([base, head]);
+    assert.equal(status, 0);
+  });
+});
+
+test("fails when a floor is lowered", () => {
+  withTempDir((dir) => {
+    const base = writeFloors(dir, "base.json", {
+      statements: 53,
+      branches: 39,
+      functions: 50,
+      lines: 52,
+    });
+    const head = writeFloors(dir, "head.json", {
+      statements: 30,
+      branches: 39,
+      functions: 50,
+      lines: 52,
+    });
+    const { status, stderr } = run([base, head]);
+    assert.equal(status, 1);
+    assert.match(stderr, /statements: coverage floor decreased 53% → 30%/);
+  });
+});
+
+test("fails when any of multiple metrics is lowered", () => {
+  withTempDir((dir) => {
+    const base = writeFloors(dir, "base.json", {
+      statements: 53,
+      branches: 39,
+      functions: 50,
+      lines: 52,
+    });
+    const head = writeFloors(dir, "head.json", {
+      statements: 53,
+      branches: 39,
+      functions: 50,
+      lines: 10,
+    });
+    const { status, stderr } = run([base, head]);
+    assert.equal(status, 1);
+    assert.match(stderr, /lines: coverage floor decreased 52% → 10%/);
+  });
+});
+
+test("allows a brand-new metric entry not present on the base branch", () => {
+  withTempDir((dir) => {
+    const base = writeFloors(dir, "base.json", { statements: 53 });
+    const head = writeFloors(dir, "head.json", {
+      statements: 53,
+      "new-metric": 1,
+    });
+    const { status } = run([base, head]);
+    assert.equal(status, 0);
+  });
+});
+
+test("treats a missing base-branch floor file as an empty floor set", () => {
+  withTempDir((dir) => {
+    const base = writeFloors(dir, "base.json", {});
+    const head = writeFloors(dir, "head.json", { statements: 53 });
+    const { status } = run([base, head]);
+    assert.equal(status, 0);
+  });
+});
+
+test("fails on a non-numeric floor value", () => {
+  withTempDir((dir) => {
+    const base = writeFloors(dir, "base.json", { statements: 53 });
+    const head = writeFloors(dir, "head.json", { statements: "fifty-three" });
+    const { status, stderr } = run([base, head]);
+    assert.equal(status, 1);
+    assert.match(stderr, /invalid coverage-floor value/);
+  });
+});
+
+test("exits non-zero with usage when arguments are missing", () => {
+  const { status, stderr } = run([]);
+  assert.equal(status, 1);
+  assert.match(stderr, /Usage:/);
+});