From 3d6d775d2f0c24f92a2005f45ff618f4cdea3349 Mon Sep 17 00:00:00 2001
From: JSONbored <49853598+JSONbored@users.noreply.github.com>
Date: Thu, 30 Jul 2026 17:45:23 -0700
Subject: [PATCH 1/2] deps(ui-kit): publish the recharts v3 migration, with
 coverage for what it rewrote
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

@loopover/ui-kit has been stuck on 1.3.0 while carrying an unreleased,
user-visible change: `chore(deps): migrate recharts to v3 across all three
workspaces (#8610)` rewrote src/components/chart.tsx and shipped to nobody.

release-please would never cut that release on its own. It decides whether a
component HAS a release before it decides how much to bump, and that decision
keeps only "user facing" commits -- those whose type is not `hidden: true` in
changelog-sections. `chore` is hidden here, so its own dry run says:

  ✔ Building candidate release pull request for path: packages/loopover-ui-kit
  ✔ No user facing commits found since 0fa52ed838... - skipping

This is deliberately typed `deps` -- the repo's own non-hidden "Dependencies"
section -- because that is what the release publishes: the recharts v3
migration. `Release-As:` was the other candidate and does not work here; the
skip above is on an empty changelog and runs after the version is computed, so
a footer on a hidden-type commit is still skipped.

The diff is the coverage that migration never had. chart.tsx had NO tests at
all, so the load-bearing parts of a major-version rewrite were resting on the
type-checker: that payload/label now arrive through context rather than as
Tooltip props, that config labels (not raw dataKeys) are what a reader sees,
that an inactive or empty payload paints nothing, and that both arms of
ChartConfig's color/theme union reach the stylesheet.

ResponsiveContainer is replaced with a passthrough for these tests and nothing
else is: it measures through a ResizeObserver that never resolves under jsdom,
so it renders nothing and discards its children -- which would have made the
"renders nothing" assertions pass for entirely the wrong reason.

Mutation-tested: forcing the tooltip to always render, inverting ChartStyle's
empty-config guard, and dropping useChart's provider check each fail.
---
 .../src/components/chart.test.tsx             | 135 ++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 packages/loopover-ui-kit/src/components/chart.test.tsx

diff --git a/packages/loopover-ui-kit/src/components/chart.test.tsx b/packages/loopover-ui-kit/src/components/chart.test.tsx
new file mode 100644
index 0000000000..15326edf2e
--- /dev/null
+++ b/packages/loopover-ui-kit/src/components/chart.test.tsx
@@ -0,0 +1,135 @@
+import { render } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+// ResponsiveContainer measures its parent through a ResizeObserver, and under jsdom that measurement never
+// resolves -- it renders NOTHING, discarding its children entirely. Every assertion below would then fail, and
+// the "renders nothing" ones would pass for entirely the wrong reason.
+//
+// Only that one measuring wrapper is replaced, with a plain passthrough; everything else -- including
+// ChartContainer, which is the context provider under test -- stays real. Stubbing the whole module would mean
+// asserting against a mock rather than against `chart.tsx`.
+vi.mock("recharts", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("recharts")>()),
+  ResponsiveContainer: ({ children }: { children?: React.ReactNode }) => <div data-testid="responsive">{children}</div>,
+}));
+
+import {
+  ChartContainer,
+  ChartLegendContent,
+  ChartStyle,
+  ChartTooltipContent,
+  type ChartConfig,
+} from "./chart.js";
+
+// #9937: `chart.tsx` is the one file the recharts v3 migration (#8610) rewrote, and it shipped with no tests
+// at all -- so the migration's load-bearing behaviours were resting on the type-checker alone.
+//
+// What v3 actually changed here: `payload` and `label` moved OFF Tooltip's own props and are supplied through
+// context, and the render-prop shape is published as `TooltipContentProps`. Everything below drives
+// ChartTooltipContent the way recharts now drives it -- as a component receiving that shape -- inside the real
+// ChartContainer, so the context wiring the migration touched is exercised rather than assumed.
+
+const config = {
+  revenue: { label: "Revenue", color: "#0ea5e9" },
+  cost: { label: "Cost", theme: { light: "#111827", dark: "#f9fafb" } },
+} satisfies ChartConfig;
+
+const payload = [
+  { dataKey: "revenue", name: "revenue", value: 120, color: "#0ea5e9", payload: { month: "Jan", revenue: 120 } },
+  { dataKey: "cost", name: "cost", value: 80, color: "#111827", payload: { month: "Jan", cost: 80 } },
+];
+
+/** ChartTooltipContent calls useChart(), so it must render inside a provider. ChartContainer is that
+ *  provider and is exercised deliberately rather than mocked. Queries are scoped to the slot, never the whole
+ *  container: ChartContainer also emits a <style> element, so a container-wide "rendered nothing" assertion
+ *  would be comparing against that stylesheet. */
+function renderInChart(node: React.ReactNode) {
+  const result = render(
+    <ChartContainer config={config}>
+      <div data-testid="slot">{node}</div>
+    </ChartContainer>,
+  );
+  // Scoped through this render's OWN container, not the shared document: a test that renders twice would
+  // otherwise match both slots and fail on "found multiple elements".
+  return { ...result, slot: () => result.container.querySelector('[data-testid="slot"]')! };
+}
+
+describe("ChartTooltipContent (recharts v3, #8610)", () => {
+  it("renders one row per payload entry, labelled from the chart config", () => {
+    // The config's `label` -- not the raw dataKey -- is what a reader sees. Regressing to the dataKey is the
+    // most likely silent breakage, and it still "renders fine".
+    const chart = renderInChart(<ChartTooltipContent active payload={payload} label="Jan" />);
+
+    expect(chart.getByText("Revenue")).toBeTruthy();
+    expect(chart.getByText("Cost")).toBeTruthy();
+    expect(chart.getByText("120")).toBeTruthy();
+    expect(chart.getByText("80")).toBeTruthy();
+  });
+
+  it("INVARIANT: renders nothing when inactive or when the payload is empty", () => {
+    // A tooltip that paints on an empty payload follows the cursor around an empty chart. Both arms, because
+    // `!active || !payload?.length` is two conditions and only testing one leaves the other free to invert.
+    const inactive = renderInChart(<ChartTooltipContent active={false} payload={payload} />);
+    expect(inactive.slot().textContent).toBe("");
+
+    const empty = renderInChart(<ChartTooltipContent active payload={[]} />);
+    expect(empty.slot().textContent).toBe("");
+  });
+
+  it("hides the label when asked, and formats it through labelFormatter otherwise", () => {
+    const formatted = renderInChart(<ChartTooltipContent active payload={payload} label="Jan" labelFormatter={(value) => `Month: ${String(value)}`} />);
+    expect(formatted.getByText("Month: Jan")).toBeTruthy();
+
+    const hidden = renderInChart(<ChartTooltipContent active payload={payload} label="Jan" hideLabel />);
+    expect(hidden.queryByText("Jan")).toBeNull();
+  });
+
+  it("routes the value through a custom formatter when one is supplied", () => {
+    const chart = renderInChart(<ChartTooltipContent active payload={[payload[0]!]} formatter={(value) => `$${String(value)}`} />);
+    expect(chart.getByText("$120")).toBeTruthy();
+  });
+
+  it("resolves a series by nameKey when the payload's own key is not the config key", () => {
+    const chart = renderInChart(<ChartTooltipContent active payload={[{ ...payload[0]!, dataKey: "unmapped", name: "unmapped" }]} nameKey="revenue" />);
+    expect(chart.getByText("Revenue")).toBeTruthy();
+  });
+});
+
+describe("ChartLegendContent (recharts v3, #8610)", () => {
+  it("labels each legend entry from the config", () => {
+    const chart = renderInChart(<ChartLegendContent payload={[{ value: "revenue", dataKey: "revenue", color: "#0ea5e9" }]} />);
+    expect(chart.getByText("Revenue")).toBeTruthy();
+  });
+
+  it("renders nothing without a payload", () => {
+    const legend = renderInChart(<ChartLegendContent payload={[]} />);
+    expect(legend.slot().textContent).toBe("");
+  });
+});
+
+describe("ChartStyle", () => {
+  it("emits per-theme CSS variables only for series that declare a colour", () => {
+    // The `theme` and `color` arms of ChartConfig are a union, and both have to reach the stylesheet -- a
+    // series configured with `theme` produces one variable per theme selector.
+    const { container } = render(<ChartStyle id="chart-test" config={config} />);
+    const css = container.querySelector("style")?.innerHTML ?? "";
+
+    expect(css).toContain("--color-revenue: #0ea5e9");
+    expect(css).toContain("--color-cost: #111827");
+    expect(css).toContain("--color-cost: #f9fafb");
+    expect(css).toContain("[data-chart=chart-test]");
+  });
+
+  it("emits no stylesheet at all when no series declares a colour", () => {
+    const { container } = render(<ChartStyle id="chart-empty" config={{ plain: { label: "Plain" } }} />);
+    expect(container.querySelector("style")).toBeNull();
+  });
+});
+
+describe("useChart", () => {
+  it("REGRESSION: throws a named error outside a ChartContainer rather than reading null", () => {
+    // Without the guard this is a `Cannot read properties of null` deep inside a tooltip render, which is a
+    // materially harder thing to diagnose than the message the component actually throws.
+    expect(() => render(<ChartTooltipContent active payload={payload} />)).toThrow(/useChart must be used within a <ChartContainer \/>/);
+  });
+});

From 6be3f903be760822b15ce401c14cccbe6a3d3ef8 Mon Sep 17 00:00:00 2001
From: JSONbored <49853598+JSONbored@users.noreply.github.com>
Date: Thu, 30 Jul 2026 17:45:36 -0700
Subject: [PATCH 2/2] ci(release): fail on a shipped-source change
 release-please would never release

The recharts v3 migration rewrote packages/loopover-ui-kit/src/components/
chart.tsx under a `chore(deps):` subject. It merged, CI was green, and the
package sat on 1.3.0 with that change unpublished. Nothing was red; the only
symptom was a drift issue whose checklist said "merge the release-please PR"
for a PR that could never exist.

release-please filters commits whose type is `hidden: true` in
changelog-sections BEFORE building a release candidate, so a hidden type on
published source strands the change. Note this is not the same question as how
much to bump: asked directly, DefaultVersioningStrategy turns a `chore` into a
patch (1.3.0 -> 1.3.1). It simply never gets asked. That gap is why this has to
be checked rather than reasoned about.

The config is the source of truth, not a list here. Both the released package
paths and the hidden-type set are read out of release-please-config.json, so
adding a package or unhiding a type moves the check with it.

Test files are excluded even though they sit under src/. Every package excludes
src/**/*.test.* from its build and none list tests in `files`, so a test is not
published -- and `test:` is itself hidden, which makes `test(pkg): add a test`
the most common hidden-type commit there is. Flagging it would fire the guard on
the ordinary case and get the guard switched off. Found by running the guard
against the very commit that added it.

A `Release-As:` footer is exempt: that is release-please's own mechanism for
forcing a version, so a commit using it has already answered the question -- and
a guard that rejects the remedy its own message recommends is a broken guard.
---
 package.json                                  |   3 +-
 scripts/check-releasable-commit-types.ts      | 176 ++++++++++++++++
 .../check-releasable-commit-types.test.ts     | 193 ++++++++++++++++++
 3 files changed, 371 insertions(+), 1 deletion(-)
 create mode 100644 scripts/check-releasable-commit-types.ts
 create mode 100644 test/unit/check-releasable-commit-types.test.ts

diff --git a/package.json b/package.json
index d729176943..26eecf6f6e 100644
--- a/package.json
+++ b/package.json
@@ -93,6 +93,7 @@
     "dead-exports:check": "node --experimental-strip-types scripts/check-dead-exports.ts",
     "publishable-deps:check": "node --experimental-strip-types scripts/check-publishable-deps.ts",
     "release-commit-parsing:check": "tsx scripts/check-release-commit-parsing.ts",
+    "releasable-commit-types:check": "tsx scripts/check-releasable-commit-types.ts",
     "checkers-wired:check": "node --experimental-strip-types scripts/check-checkers-wired.ts",
     "maintainer-associations:check": "node --experimental-strip-types scripts/check-maintainer-association-copies.ts",
     "regate-sort-key:check": "node --experimental-strip-types scripts/check-regate-sort-key.ts",
@@ -146,7 +147,7 @@
     "test:smoke:browser:install": "playwright install chromium",
     "test:smoke:browser": "node --experimental-strip-types scripts/smoke-ui-browser.ts",
     "pretest:ci": "npm run check-node-version",
-    "test:ci": "git diff --check && npm run actionlint && npm run lint:composite-actions && npm run db:migrations:check && npm run db:migrations:immutable:check && npm run turbo-inputs:check && npm run workspace-dep-ranges:check && npm run db:schema-drift:check && npm run selfhost:env-reference:check && npm run miner:env-reference:check && npm run selfhost:validate-observability && npm run cf-typegen:check && npm run build --workspace @loopover/engine && npm run build --workspace @loopover/discovery-index && npm run build:mcp && npm run build:miner && npm run build --workspace @loopover/ui-kit && npm run typecheck && npm run test:coverage && npm run test:engine-parity && npm run test:live-gate-parity && npm run test:driver-parity && npm run validate:mcp && npm run test --workspace @loopover/engine && npm run test:workers && npm run test:mcp-pack && npm run test:contract-pack && npm run test:miner-pack && npm run test:engine-pack && npm run test:ui-kit-pack && npm run test:miner-deployment-docs-audit && npm run rees:test && npm run ui:openapi:check && npm run control-plane:contract:check && npm run control-plane:openapi:check && npm run ui:version-audit && npm run docs:drift-check && npm run coverage-boltons:check && npm run import-specifiers:check && npm run ui-derived-types:check && npm run server-manifest:check && npm run dead-source-files:check && npm run dead-exports:check && npm run publishable-deps:check && npm run fixture-clock-races:check && npm run typecheck-coverage:check && npm run checkers-wired:check && npm run release-commit-parsing:check && npm run regate-sort-key:check && npm run maintainer-associations:check && npm run command-redelivery-guards:check && npm run dispatch-gate-reasons:check && npm run validate:no-hand-written-js && npm run replay-runner-manifest:check && npm run coco-dev-versions:check && npm run branding-drift:check && npm run manifest:drift-check && npm run engine-parity:drift-check && npm run engines-nvmrc:check && npm run release-manifest:sync:check && npm run release-linked-versions:check && npm run command-reference:check && npm run mcp:tool-reference:check && npm run mcp:client-config:check && npm run contract:api-schemas:check && npm run ui:lint && npm run ui:typecheck && npm run ui:test && npm run ui:build",
+    "test:ci": "git diff --check && npm run actionlint && npm run lint:composite-actions && npm run db:migrations:check && npm run db:migrations:immutable:check && npm run turbo-inputs:check && npm run workspace-dep-ranges:check && npm run db:schema-drift:check && npm run selfhost:env-reference:check && npm run miner:env-reference:check && npm run selfhost:validate-observability && npm run cf-typegen:check && npm run build --workspace @loopover/engine && npm run build --workspace @loopover/discovery-index && npm run build:mcp && npm run build:miner && npm run build --workspace @loopover/ui-kit && npm run typecheck && npm run test:coverage && npm run test:engine-parity && npm run test:live-gate-parity && npm run test:driver-parity && npm run validate:mcp && npm run test --workspace @loopover/engine && npm run test:workers && npm run test:mcp-pack && npm run test:contract-pack && npm run test:miner-pack && npm run test:engine-pack && npm run test:ui-kit-pack && npm run test:miner-deployment-docs-audit && npm run rees:test && npm run ui:openapi:check && npm run control-plane:contract:check && npm run control-plane:openapi:check && npm run ui:version-audit && npm run docs:drift-check && npm run coverage-boltons:check && npm run import-specifiers:check && npm run ui-derived-types:check && npm run server-manifest:check && npm run dead-source-files:check && npm run dead-exports:check && npm run publishable-deps:check && npm run fixture-clock-races:check && npm run typecheck-coverage:check && npm run checkers-wired:check && npm run release-commit-parsing:check && npm run releasable-commit-types:check && npm run regate-sort-key:check && npm run maintainer-associations:check && npm run command-redelivery-guards:check && npm run dispatch-gate-reasons:check && npm run validate:no-hand-written-js && npm run replay-runner-manifest:check && npm run coco-dev-versions:check && npm run branding-drift:check && npm run manifest:drift-check && npm run engine-parity:drift-check && npm run engines-nvmrc:check && npm run release-manifest:sync:check && npm run release-linked-versions:check && npm run command-reference:check && npm run mcp:tool-reference:check && npm run mcp:client-config:check && npm run contract:api-schemas:check && npm run ui:lint && npm run ui:typecheck && npm run ui:test && npm run ui:build",
     "test:release": "npm run test:ci && npm run changelog:check",
     "test:release:mcp": "npm run test:ci",
     "test:watch": "vitest",
diff --git a/scripts/check-releasable-commit-types.ts b/scripts/check-releasable-commit-types.ts
new file mode 100644
index 0000000000..199a06e8fc
--- /dev/null
+++ b/scripts/check-releasable-commit-types.ts
@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// A change to a released package's SHIPPED SOURCE, filed under a commit type release-please treats as
+// invisible, never reaches npm (#9937).
+//
+// THE INCIDENT. `chore(deps): migrate recharts to v3 across all three workspaces (#8610)` rewrote
+// `packages/loopover-ui-kit/src/components/chart.tsx` -- a real behavioural change to shipped code. It merged,
+// CI was green, and @loopover/ui-kit stayed on 1.3.0 for weeks with that change sitting unreleased. Nothing
+// was broken, nothing was red, and the only symptom was a drift issue whose checklist said "merge the
+// release-please PR" for a PR that could never exist.
+//
+// WHY IT IS INVISIBLE. release-please decides whether a component has a release to cut BEFORE it decides how
+// much to bump. Its own dry run says so:
+//
+//   ✔ Building candidate release pull request for path: packages/loopover-ui-kit
+//   ✔ No user facing commits found since 0fa52ed838... - skipping
+//
+// "User facing" means the commit's type is not `hidden: true` in `changelog-sections`. `chore` is hidden here,
+// so the commit is filtered out and no candidate release is built. Note that this is NOT the same question as
+// how the versioning strategy would bump: asked directly, `DefaultVersioningStrategy` happily turns a `chore`
+// into a patch (1.3.0 -> 1.3.1). It simply never gets asked. That gap between the two is precisely why this
+// has to be checked rather than reasoned about.
+//
+// THE CONFIG IS THE SOURCE OF TRUTH, not a list here. Both the released package paths and the set of hidden
+// types are read out of `release-please-config.json`, so adding a package, or unhiding a type, moves this
+// check with it. Hardcoding either would make the guard drift from the release process it is guarding -- the
+// same "compute the fact, don't remember it" bar the sibling `check-release-commit-parsing.ts` sets.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+export type ReleasePleaseConfig = {
+  packages?: Record<string, unknown>;
+  // `section` is carried so a fixture (or the real config) can be assigned to this type verbatim; only
+  // `type` and `hidden` are read.
+  "changelog-sections"?: { type?: unknown; hidden?: unknown; section?: unknown }[];
+};
+
+/** A commit reduced to what this check needs. */
+export type CommitUnderReview = { sha: string; subject: string; files: readonly string[] };
+
+export type StrandedCommit = { sha: string; subject: string; type: string; paths: string[] };
+
+/** PURE. The commit types release-please filters out of "user facing commits", read from the config. A type
+ *  absent from `changelog-sections` entirely is NOT hidden -- release-please's own default sections apply. */
+export function hiddenCommitTypes(config: ReleasePleaseConfig): Set<string> {
+  const hidden = new Set<string>();
+  for (const section of config["changelog-sections"] ?? []) {
+    if (section.hidden === true && typeof section.type === "string") hidden.add(section.type);
+  }
+  return hidden;
+}
+
+/** PURE. The source roots whose contents get published, one per configured package.
+ *
+ *  Deliberately `<pkg>/src/` rather than the whole package directory: a change to a package's README or its
+ *  tsconfig does not alter what consumers install, so requiring a releasable type for those would be noise
+ *  that trains people to reach for the override. `package.json` IS included -- a dependency range is part of
+ *  what a consumer resolves. */
+export function publishedSourcePrefixes(config: ReleasePleaseConfig): string[] {
+  return Object.keys(config.packages ?? {}).flatMap((path) => {
+    const base = path.replace(/\/+$/, "");
+    return [`${base}/src/`, `${base}/package.json`];
+  });
+}
+
+/** PURE. Test files live under `src/` in this repo but are excluded from every package's build (`tsconfig`
+ *  `exclude`) and absent from its `files` allowlist, so they are NOT published. Without this, the single most
+ *  common hidden-type commit there is -- `test(pkg): …` adding a co-located test -- would be flagged as a
+ *  stranded release, and a guard that fires on the ordinary case is a guard that gets disabled. */
+export function isPublishedFile(file: string): boolean {
+  return !/\.(test|spec)\.[cm]?[jt]sx?$/.test(file);
+}
+
+/** PURE. The conventional-commit type of a subject line, or null when it has none. Only the type is needed,
+ *  and only from the subject -- the body cannot change which section a commit lands in. */
+export function commitType(subject: string): string | null {
+  const match = /^([a-zA-Z]+)(?:\([^)]*\))?(!)?:/.exec(subject.trim());
+  return match?.[1] ? match[1].toLowerCase() : null;
+}
+
+/** PURE. A breaking change is always user-facing regardless of its type, so `chore!:` is never stranded. */
+export function isBreaking(subject: string): boolean {
+  return /^[a-zA-Z]+(?:\([^)]*\))?!:/.test(subject.trim());
+}
+
+/**
+ * PURE. The commits that change published source under a type release-please will not release.
+ *
+ * A commit carrying a `Release-As:` footer is exempt: that is release-please's own documented mechanism for
+ * forcing a version, so a commit using it has already answered this check's question.
+ */
+export function findStrandedCommits(
+  commits: readonly CommitUnderReview[],
+  config: ReleasePleaseConfig,
+  bodyOf: (sha: string) => string = () => "",
+): StrandedCommit[] {
+  const hidden = hiddenCommitTypes(config);
+  const prefixes = publishedSourcePrefixes(config);
+  const stranded: StrandedCommit[] = [];
+  for (const commit of commits) {
+    const type = commitType(commit.subject);
+    if (type === null || !hidden.has(type) || isBreaking(commit.subject)) continue;
+    const paths = commit.files.filter((file) => isPublishedFile(file) && prefixes.some((prefix) => file.startsWith(prefix)));
+    if (paths.length === 0) continue;
+    if (/^\s*Release-As:/im.test(bodyOf(commit.sha))) continue;
+    stranded.push({ sha: commit.sha, subject: commit.subject, type, paths });
+  }
+  return stranded;
+}
+
+/** PURE. The failure text. Names the offending paths and both ways out, because a guard whose message does not
+ *  say what to do instead gets bypassed rather than satisfied. */
+export function describeStranded(stranded: readonly StrandedCommit[], hidden: ReadonlySet<string>): string {
+  const lines = [
+    "",
+    "These commits change published package source under a commit type release-please treats as invisible,",
+    "so the change would merge green and then never reach npm:",
+    "",
+  ];
+  for (const commit of stranded) {
+    lines.push(`  ${commit.sha.slice(0, 8)} ${commit.subject}`);
+    for (const path of commit.paths) lines.push(`      ${path}`);
+  }
+  lines.push(
+    "",
+    `Hidden types (from release-please-config.json changelog-sections): ${[...hidden].sort().join(", ")}`,
+    "",
+    "Fix by either:",
+    "  • using a user-facing type -- `fix:` for a correction, `feat:` for an addition, `deps:` for a",
+    "    dependency change (this repo already publishes a 'Dependencies' section for `deps`); or",
+    "  • adding a `Release-As: <version>` footer, release-please's own mechanism for forcing a release when",
+    "    the type genuinely is a chore.",
+    "",
+  );
+  return lines.join("\n");
+}
+
+const git = (args: string[]): string => execFileSync("git", args, { encoding: "utf8" });
+
+/** The commits this branch adds over its base, with the files each touched. Scoped to the branch rather than
+ *  to all of history for the reason the sibling checker documents: `main` already carries commits that would
+ *  fail, so an unscoped check would be permanently red and switched off within a day. */
+export function commitsOnThisBranch(base: string): CommitUnderReview[] {
+  const range = `${base}...HEAD`;
+  const shas = git(["log", "--no-merges", "--format=%H", range]).split("\n").filter(Boolean);
+  return shas.map((sha) => ({
+    sha,
+    subject: git(["log", "-1", "--format=%s", sha]).trim(),
+    files: git(["show", "--name-only", "--format=", sha]).split("\n").filter(Boolean),
+  }));
+}
+
+export function readConfig(path = "release-please-config.json"): ReleasePleaseConfig {
+  return JSON.parse(readFileSync(path, "utf8")) as ReleasePleaseConfig;
+}
+
+/* v8 ignore start -- the self-execution guard and its git/process plumbing; every pure branch is tested. */
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const base = process.env["GITHUB_BASE_REF"] ? `origin/${process.env["GITHUB_BASE_REF"]}` : "origin/main";
+  let commits: CommitUnderReview[] = [];
+  try {
+    commits = commitsOnThisBranch(base);
+  } catch {
+    process.stdout.write(`releasable-commit-types: cannot resolve ${base}; skipping.\n`);
+    process.exit(0);
+  }
+  const config = readConfig();
+  const stranded = findStrandedCommits(commits, config, (sha) => git(["log", "-1", "--format=%b", sha]));
+  if (stranded.length === 0) {
+    process.stdout.write(`releasable-commit-types: ${commits.length} commit(s) checked, none would be stranded.\n`);
+    process.exit(0);
+  }
+  process.stderr.write(describeStranded(stranded, hiddenCommitTypes(config)));
+  process.exit(1);
+}
+/* v8 ignore stop */
diff --git a/test/unit/check-releasable-commit-types.test.ts b/test/unit/check-releasable-commit-types.test.ts
new file mode 100644
index 0000000000..f7bcd31a90
--- /dev/null
+++ b/test/unit/check-releasable-commit-types.test.ts
@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  commitType,
+  describeStranded,
+  findStrandedCommits,
+  hiddenCommitTypes,
+  isBreaking,
+  isPublishedFile,
+  publishedSourcePrefixes,
+  readConfig,
+  type CommitUnderReview,
+  type ReleasePleaseConfig,
+} from "../../scripts/check-releasable-commit-types";
+
+// #9937: the guard against a shipped-source change that release-please will never release.
+//
+// The real incident: `chore(deps): migrate recharts to v3` rewrote packages/loopover-ui-kit/src/components/
+// chart.tsx and @loopover/ui-kit stayed on 1.3.0, because `chore` is `hidden: true` in changelog-sections and
+// release-please filters hidden types out before it ever builds a release candidate ("No user facing commits
+// found ... skipping"). Green CI, unreleased change, no signal anywhere.
+
+const CONFIG: ReleasePleaseConfig = {
+  packages: { "packages/loopover-ui-kit": {}, "packages/loopover-engine": {} },
+  "changelog-sections": [
+    { type: "feat", section: "Features" },
+    { type: "fix", section: "Fixes" },
+    { type: "deps", section: "Dependencies" },
+    { type: "chore", section: "Chores", hidden: true },
+    { type: "test", section: "Tests", hidden: true },
+  ],
+};
+
+const commit = (over: Partial<CommitUnderReview> = {}): CommitUnderReview => ({
+  sha: "a".repeat(40),
+  subject: "chore(deps): migrate recharts to v3 across all three workspaces (#8610)",
+  files: ["packages/loopover-ui-kit/src/components/chart.tsx"],
+  ...over,
+});
+
+describe("hiddenCommitTypes", () => {
+  it("reads the hidden set out of the config rather than hardcoding it", () => {
+    expect(hiddenCommitTypes(CONFIG)).toEqual(new Set(["chore", "test"]));
+  });
+
+  it("treats a type absent from changelog-sections as NOT hidden", () => {
+    // Absent means release-please's defaults apply; assuming hidden would fail commits that release fine.
+    expect(hiddenCommitTypes(CONFIG).has("perf")).toBe(false);
+    expect(hiddenCommitTypes({})).toEqual(new Set());
+  });
+});
+
+describe("publishedSourcePrefixes", () => {
+  it("covers each configured package's src/ and package.json", () => {
+    expect(publishedSourcePrefixes(CONFIG)).toEqual([
+      "packages/loopover-ui-kit/src/",
+      "packages/loopover-ui-kit/package.json",
+      "packages/loopover-engine/src/",
+      "packages/loopover-engine/package.json",
+    ]);
+  });
+
+  it("derives them from the config, so a newly configured package is covered automatically", () => {
+    expect(publishedSourcePrefixes({ packages: { "packages/new-thing": {} } })).toContain("packages/new-thing/src/");
+  });
+});
+
+describe("isPublishedFile", () => {
+  it("excludes test and spec files in every extension the repo uses", () => {
+    for (const file of ["a/chart.test.tsx", "a/x.test.ts", "a/y.spec.ts", "a/z.spec.tsx"]) {
+      expect(isPublishedFile(file), file).toBe(false);
+    }
+  });
+
+  it("keeps ordinary source, including files that merely mention test in the name", () => {
+    for (const file of ["a/chart.tsx", "a/test-utils.ts", "a/latest.ts"]) {
+      expect(isPublishedFile(file), file).toBe(true);
+    }
+  });
+});
+
+describe("commitType / isBreaking", () => {
+  it("reads the type, with or without a scope", () => {
+    expect(commitType("chore(deps): x")).toBe("chore");
+    expect(commitType("fix: y")).toBe("fix");
+    expect(commitType("FEAT(ui): z")).toBe("feat");
+  });
+
+  it("returns null for a non-conventional subject", () => {
+    expect(commitType("just some text")).toBeNull();
+    expect(commitType("")).toBeNull();
+  });
+
+  it("detects the breaking marker, which is user-facing whatever the type", () => {
+    expect(isBreaking("chore(deps)!: drop node 20")).toBe(true);
+    expect(isBreaking("chore(deps): bump")).toBe(false);
+  });
+});
+
+describe("findStrandedCommits", () => {
+  it("REGRESSION: flags the real recharts commit -- hidden type, published source", () => {
+    const [stranded] = findStrandedCommits([commit()], CONFIG);
+    expect(stranded).toMatchObject({ type: "chore", paths: ["packages/loopover-ui-kit/src/components/chart.tsx"] });
+  });
+
+  it("allows a user-facing type on the same files", () => {
+    expect(findStrandedCommits([commit({ subject: "deps(ui-kit): migrate recharts to v3" })], CONFIG)).toEqual([]);
+    expect(findStrandedCommits([commit({ subject: "fix(ui-kit): correct tooltip payload" })], CONFIG)).toEqual([]);
+  });
+
+  it("allows a hidden type that touches NO published source", () => {
+    // The overwhelmingly common case, and the one that decides whether this guard is livable: chores against
+    // scripts, workflows, tests and docs must stay silent.
+    const files = ["scripts/thing.ts", ".github/workflows/ci.yml", "test/unit/x.test.ts", "README.md"];
+    expect(findStrandedCommits([commit({ files })], CONFIG)).toEqual([]);
+  });
+
+  it("does not flag a package's own config or docs -- those are not what consumers install", () => {
+    const files = ["packages/loopover-ui-kit/tsconfig.json", "packages/loopover-ui-kit/README.md"];
+    expect(findStrandedCommits([commit({ files })], CONFIG)).toEqual([]);
+  });
+
+  it("REGRESSION: does not flag a co-located TEST file, even though it sits under src/", () => {
+    // Caught by running this guard against the very commit that added it. Every package excludes
+    // `src/**/*.test.*` from its build and none list tests in `files`, so a test is not published -- and
+    // `test:` is a hidden type, making `test(pkg): add a test` the single most common hidden-type commit
+    // there is. Flagging it would fire the guard on the ordinary case and get the guard switched off.
+    const files = ["packages/loopover-ui-kit/src/components/chart.test.tsx"];
+    expect(findStrandedCommits([commit({ subject: "test(ui-kit): cover chart", files })], CONFIG)).toEqual([]);
+  });
+
+  it("still flags the implementation file sitting beside that test", () => {
+    const files = ["packages/loopover-ui-kit/src/components/chart.test.tsx", "packages/loopover-ui-kit/src/components/chart.tsx"];
+    const [stranded] = findStrandedCommits([commit({ files })], CONFIG);
+    // Only the shipped file is named -- listing the test too would send a reader to fix the wrong thing.
+    expect(stranded?.paths).toEqual(["packages/loopover-ui-kit/src/components/chart.tsx"]);
+  });
+
+  it("DOES flag a package.json change, because a dependency range is part of what consumers resolve", () => {
+    const files = ["packages/loopover-ui-kit/package.json"];
+    expect(findStrandedCommits([commit({ files })], CONFIG)).toHaveLength(1);
+  });
+
+  it("allows a breaking hidden-type commit -- breaking is user-facing whatever the type", () => {
+    expect(findStrandedCommits([commit({ subject: "chore(deps)!: drop react 18" })], CONFIG)).toEqual([]);
+  });
+
+  it("allows a commit carrying a Release-As footer, release-please's own override", () => {
+    // Exempt because the commit has already answered this check's question, and this is the documented escape
+    // hatch the failure message points at -- a guard whose stated remedy it then rejects is a broken guard.
+    expect(findStrandedCommits([commit()], CONFIG, () => "Release-As: 1.3.1")).toEqual([]);
+    expect(findStrandedCommits([commit()], CONFIG, () => "body\n\nRelease-As: 1.3.1\n")).toEqual([]);
+  });
+
+  it("does not mistake a mention of Release-As mid-sentence for the footer", () => {
+    expect(findStrandedCommits([commit()], CONFIG, () => "we could use Release-As: here")).toHaveLength(1);
+  });
+
+  it("ignores a non-conventional subject rather than guessing at its type", () => {
+    expect(findStrandedCommits([commit({ subject: "merge branch main" })], CONFIG)).toEqual([]);
+  });
+
+  it("reports every offending commit, not just the first", () => {
+    const second = commit({ sha: "b".repeat(40), subject: "test(engine): x", files: ["packages/loopover-engine/src/a.ts"] });
+    expect(findStrandedCommits([commit(), second], CONFIG)).toHaveLength(2);
+  });
+});
+
+describe("describeStranded", () => {
+  it("names the commit, the paths, and BOTH documented ways out", () => {
+    const message = describeStranded(findStrandedCommits([commit()], CONFIG), hiddenCommitTypes(CONFIG));
+    expect(message).toContain("packages/loopover-ui-kit/src/components/chart.tsx");
+    expect(message).toContain("deps:");
+    expect(message).toContain("Release-As:");
+    expect(message).toContain("chore, test");
+  });
+});
+
+describe("readConfig", () => {
+  it("INVARIANT: the repo's real config still marks chore hidden and lists ui-kit", () => {
+    // Pins the two facts the guard depends on against the ACTUAL config, so unhiding `chore` or renaming a
+    // package path cannot leave this check quietly asserting nothing.
+    const config = readConfig();
+    expect(hiddenCommitTypes(config).has("chore")).toBe(true);
+    expect(publishedSourcePrefixes(config)).toContain("packages/loopover-ui-kit/src/");
+  });
+
+  it("REGRESSION: the historical recharts commit would have been caught by this guard", () => {
+    // The whole point, stated against the real config rather than the fixture.
+    const stranded = findStrandedCommits([commit()], readConfig());
+    expect(stranded).toHaveLength(1);
+  });
+});