@aurodesignsystem-dev/auro-cli 0.0.0-pr348.2 → 0.0.0-pr350.0

package/README.md

@@ -51,6 +51,7 @@ Run `auro <command> --help` for options on any command. Defaults are shown where
 | `auro rc-workflow` | Cuts the RC branch and opens the RC PR. |
 | `auro pr-release` | Sets the PR preview version in `package.json`. |
 | `auro check-commits` (alias `auro cc`) | Classifies commits and can label the PR. |
+| `auro api-diff` | Checks that a PR's commits declare a big enough version bump for its code changes. |
 
 ## Full reference
 
@@ -183,6 +184,59 @@ Reads the repo's commits, classifies each by conventional-commit type, and repor
 - `-d, --debug`: print detailed commit info.
 - `-r, --release-notes`: generate release notes from the commits.
 
+#### `auro api-diff <baseRef> [headRef]`
+
+Works out the smallest version bump the code changes from `baseRef` to `headRef` (default `HEAD`) require, and checks that the commits declare at least that much. A version number is a promise to consumers, so a `fix:` commit that removes a public attribute shouldn't ship as a patch.
+
+- `--json`: write the result to stdout as JSON.
+- `--enforce`: exit 1 when the commits declare a smaller bump than the code requires (default: off, so the check can run report-only).
+- `--no-rebuild`: compare the committed `custom-elements.json` files instead of rebuilding them. Faster, but only as good as the committed files, and many repos don't commit the manifest.
+- `--manifest <path>`: manifest path from the repo root (default: `customElements` in `package.json`, else `custom-elements.json`).
+- `--install-command <cmd>`: installs dependencies in each rebuilt checkout (default: `npm ci --no-audit --no-fund`).
+- `--build-command <cmd>`: writes the manifest in each rebuilt checkout (default: `npm run build`).
+
+```bash
+auro api-diff origin/dev
+```
+
+Everything is compared from the merge base of the two refs, so only the PR's own changes and commits count.
+
+**Required bump.** The highest bump among these changes:
+
+| Change | Bump |
+|---|---|
+| Element removed or renamed; public attribute, property, method, event, slot, CSS part or CSS custom property removed or made private; type narrowed or replaced; attribute stops reflecting; default value changed, added or removed | Major |
+| `exports` entry, `main`, `types` or `files` entry removed; `exports` added where there was none; peer or runtime dependency moved to a new major; `engines` tightened | Major |
+| Element or public member added; private member made public; type widened; `exports` entry added | Minor |
+| Any file under `src/` or `demo/`, or a `README.md` | Patch |
+| Only `test/`, `.github/`, `docs/` or other unpublished files | None |
+
+Only public API counts. Members are filtered on the manifest's `privacy` field, not on name prefixes. Attributes backed by a private or `@internal` property don't count. Default values are compared after normalizing quotes, so `'md'` and `"md"` are the same.
+
+The manifest is rebuilt at both refs in temporary git worktrees, by default with `npm ci` and `npm run build`. The rebuild is skipped when only `test/`, `.github/` or `docs/` changed. If the head doesn't build, the check errors (fails closed). If the base doesn't build, the check uses the base's committed manifest, or skips the API comparison, and says so in `warnings` (fails open): a PR shouldn't be blocked by a base it didn't break.
+
+**Declared bump.** The highest bump among the non-merge commits, worked out by `@semantic-release/commit-analyzer` with the repo's own release config (usually `@aurodesignsystem/auro-config/releaserc`, including its custom rules: `refactor`, `style` and `docs(README)` release a patch). It's loaded from the repo's `node_modules` when installed, so the check reads commits exactly as the release will. Otherwise auro-cli's own copy and the shared rules are used. The PR title never counts, because merge commits don't affect the version.
+
+**Outcome.**
+
+- `fail`: the commits declare less than the code requires. Reword the commits (`fix:` → `feat:`, or add `!` and a `BREAKING CHANGE:` footer).
+- `warn`: no release is required, but the commits declare one (for example, a `fix:` that only touches tests).
+- `pass`: otherwise. Declaring more than required is allowed, because behavior can break without the API changing.
+
+The JSON starts with `required` and `reasons`, followed by `declared`, `outcome`, a one-line `summary` for PR comments, the refs, each change and commit with its bump, the release config and analyzer used, and any `warnings`:
+
+```json
+{
+  "required": "major",
+  "reasons": ["Removed attribute `ondark` from `<auro-button>`"],
+  "declared": "patch",
+  "outcome": "fail",
+  "summary": "Commits declare `fix` (patch). Code requires major: removed attribute `ondark` from `<auro-button>`."
+}
+```
+
+Exit codes: `0` when the analysis ran, `1` with `--enforce` when the outcome is `fail`, `2` when the analysis couldn't run (an unknown ref, or a head that won't build).
+
 ### AI assistant context
 
 #### `auro context`