zuplo 7.13.3 → 7.13.5

package/docs/articles/api-lint-breaking-changes.mdx

@@ -0,0 +1,211 @@
+---
+title: Breaking Change Detection
+sidebar_label: Breaking changes
+description:
+  Use `zuplo lint` to compare your OpenAPI files to a Git branch and catch
+  removed endpoints, new required inputs, and changed types before they reach
+  consumers.
+applies_to:
+  product: gateway
+  hosting: all
+---
+
+Your OpenAPI files are the contract your API consumers build against. Remove an
+endpoint, make a query parameter required, or change a field from a string to an
+integer, and every client that relied on the old shape breaks — usually in
+production, and usually after the change has shipped.
+
+Breaking change detection catches these changes before you merge them.
+`zuplo lint` compares each OpenAPI file in your project with the same file on a
+Git branch, such as `main`, and reports every change that can break an existing
+consumer:
+
+```txt
+  Breaking Changes
+
+  config/routes.oas.json
+    0:0        error     Removed "/todos/{id}" (was "/todos/{id}")  breaking-change
+    15:25      error     Modified "required" from "false" to "true"  breaking-change
+    37:21      error     Modified "type" from "string" to "integer"  breaking-change
+
+  ✖ 3 breaking changes remaining
+```
+
+## Turn on detection
+
+Breaking change detection is off by default. Turn it on in `zuplo.lint.jsonc` in
+the root of your project:
+
+```jsonc title="zuplo.lint.jsonc"
+{
+  "version": 2,
+  "breakingChanges": {
+    "enabled": true,
+    "baseline": "origin/main",
+  },
+}
+```
+
+Then run the linter as usual:
+
+```bash
+git fetch origin main
+npx zuplo lint
+```
+
+Detection runs alongside the rest of the lint checks. It uses no extra flags, so
+the same command works on your machine and in CI.
+
+## Settings
+
+| Field      | Description                                                                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`  | Turns detection on. Defaults to `false`.                                                                                              |
+| `baseline` | The branch, tag, or commit SHA to compare against, such as `main`, `origin/main`, or `v1.2.0`. Defaults to `"main"`.                  |
+| `severity` | `"error"` or `"warn"`. Defaults to `"error"`. Controls whether a breaking change fails the run — see [Block or warn](#block-or-warn). |
+
+## Choose a baseline
+
+The baseline is the version of your API that consumers use today. Compare
+against whatever represents that version:
+
+- **The branch you deploy production from**, usually `main`. Each pull request
+  then reports what it would break once merged. This is the most common setup.
+- **A release tag**, such as `v1.2.0`. Every change since the last release is
+  checked, which is useful when several merges ship together.
+
+Use `origin/main` rather than `main` when you lint in CI. CI systems usually
+check out the pull request's commit without creating a local `main` branch, so
+only the remote-tracking branch `origin/main` exists. `origin/main` also works
+on your machine after `git fetch`, so one configuration serves both.
+
+The `baseline` value must be a branch, tag, or commit SHA. Expressions such as
+`HEAD~1` or `main^` aren't accepted.
+
+## What counts as a breaking change
+
+A change is breaking when a client written against the baseline can fail against
+the new version. The linter reports these kinds of change, among others:
+
+| Change                                                | Example message                              |
+| ----------------------------------------------------- | -------------------------------------------- |
+| Removing a path or an operation                       | `Removed "/todos/{id}" (was "/todos/{id}")`  |
+| Adding a required parameter                           | `Added "parameters"`                         |
+| Making an optional parameter required                 | `Modified "required" from "false" to "true"` |
+| Making a request body property required               | `Added property "required"`                  |
+| Changing the type of a parameter, property, or schema | `Modified "type" from "string" to "integer"` |
+| Removing a value from an enum                         | `Removed property "enum" (was "done")`       |
+| Removing a response status code                       | `Removed "codes" (was "201")`                |
+
+These changes are safe, so the linter doesn't report them:
+
+- Adding a new path, operation, or response
+- Adding an optional parameter or request body property
+- Adding a property to a response
+- Adding a value to an enum
+- Changing descriptions, summaries, and examples
+
+Detection compares the API contract — paths, operations, parameters, request
+bodies, and responses. It doesn't compare the gateway configuration inside
+`x-zuplo-route`, so removing a policy or changing a handler isn't reported as a
+breaking change.
+
+## Read the results
+
+Breaking changes appear in their own **Breaking Changes** section, after the
+other lint results, and are counted separately in the summary. Every result uses
+the ID `breaking-change`.
+
+Each result points at the change in your current file. A removal has nothing
+left to point at, so its location is `0:0`; the message names what was removed.
+
+In `--format json` output, breaking changes are in the `breakingChanges` array
+and counted in `summary.breakingChanges`. In `--format sarif` output, they're
+included with the other results.
+
+New files have nothing to compare against, so a file that doesn't exist on the
+baseline never reports breaking changes. Detection checks the same files as the
+rest of the linter: every `.oas.json` file in `config/`, or the files listed in
+[`include`](./api-lint-configuration.mdx#include).
+[`ignorePaths`](./api-lint-configuration.mdx#ignorepaths) doesn't apply to
+breaking changes.
+
+## Block or warn
+
+`severity` decides whether a breaking change fails the run:
+
+| `severity`          | `failOn: "error"` (default) | `failOn: "warn"` |
+| ------------------- | --------------------------- | ---------------- |
+| `"error"` (default) | Fails                       | Fails            |
+| `"warn"`            | Passes, and reports         | Fails            |
+
+Use `"error"` to block pull requests that break the contract. Use `"warn"` when
+breaking changes are sometimes intentional — for example, while an API is still
+in beta — and you want reviewers to see them without blocking the merge.
+
+When you do mean to ship a breaking change, the usual approach is to version the
+API instead: keep the old operation, add the new one under a new path such as
+`/v2/todos`, and remove the old one later. See
+[Versioning on Zuplo](./versioning-on-zuplo.mdx).
+
+## Run in CI
+
+Detection reads the baseline from your Git history, so the CI checkout has to
+include it. With GitHub Actions, set `fetch-depth: 0` on `actions/checkout`:
+
+```yaml title=".github/workflows/lint.yaml"
+steps:
+  - uses: actions/checkout@v4
+    with:
+      fetch-depth: 0
+
+  - uses: actions/setup-node@v4
+    with:
+      node-version: 24
+
+  - name: Install dependencies
+    run: npm ci
+
+  - name: Lint
+    run: npx zuplo lint
+```
+
+On other CI systems, run `git fetch origin main` (or the branch you compare
+against) before the linter. See [Lint in CI/CD](./api-lint-ci-cd.mdx) for
+complete workflows, including GitHub code scanning.
+
+## Requirements and errors
+
+Detection uses Git, so it needs:
+
+- Git installed where the linter runs.
+- A project inside a Git repository. The project can be the repository root or
+  any subdirectory of it.
+- The baseline ref in the local repository.
+
+If any of these is missing, the linter can't compare, and it says so instead of
+reporting no changes:
+
+```txt
+  Breaking Changes
+
+    0:0        error     Breaking change detection failed: baseline ref "main" not found in this repository; fetch it first (for example, git fetch origin main) or set breakingChanges.baseline to a ref that exists, such as origin/main  breaking-change
+```
+
+This result uses the `severity` you set, so with the default `"error"` it fails
+the run. A comparison you asked for that can't happen fails the same gate a
+breaking change would.
+
+| Message                                         | Fix                                                                                 |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `baseline ref "main" not found`                 | Fetch the branch (`git fetch origin main`), or set `baseline` to `origin/main`.     |
+| `cannot read baseline ... not a git repository` | Run the linter inside a Git repository, or turn off detection for that environment. |
+| `invalid baseline ref`                          | Use a branch, tag, or commit SHA rather than an expression such as `HEAD~1`.        |
+
+## Next steps
+
+- [Lint in CI/CD](./api-lint-ci-cd.mdx) — run detection on every pull request.
+- [Lint configuration](./api-lint-configuration.mdx) — the rest of the
+  `zuplo.lint.jsonc` options.
+- [Versioning on Zuplo](./versioning-on-zuplo.mdx) — ship a breaking change
+  without breaking existing consumers.

package/docs/articles/api-lint-ci-cd.mdx

@@ -0,0 +1,242 @@
+---
+title: Lint in CI/CD
+sidebar_label: Lint in CI/CD
+description:
+  Run `zuplo lint` in CI to block pull requests on lint errors, show results in
+  GitHub code scanning, and report breaking OpenAPI changes against the main
+  branch.
+applies_to:
+  product: gateway
+  hosting: all
+---
+
+`zuplo lint` exits with a non-zero code when it finds problems, so any CI system
+can use it as a gate. This page shows a GitHub Actions workflow for each common
+setup, then the pieces you need to adapt them to another CI system.
+
+The examples assume your Zuplo project is at the root of the repository and
+lists `zuplo` in `package.json`, as projects created with
+[`create-zuplo-api`](../cli/create-zuplo-api.mdx) do. `zuplo lint` doesn't need
+an API key; it reads only the files in your repository.
+
+## Fail pull requests on lint errors
+
+The simplest setup runs the linter and lets its exit code pass or fail the job:
+
+```yaml title=".github/workflows/lint.yaml"
+name: Lint
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npx zuplo lint
+```
+
+The job fails when the linter finds an error. To fail on warnings too, change
+the step to `npx zuplo lint --fail-on warn`, or set
+[`failOn`](./api-lint-configuration.mdx#failon) in `zuplo.lint.jsonc` so local
+runs and CI agree.
+
+To lint before deploying, add the same step before `zuplo deploy` in your
+deployment workflow. See [Custom CI/CD](./custom-ci-cd.mdx) for deployment
+workflows.
+
+## Show results in GitHub code scanning
+
+With `--format sarif`, the linter writes results in the SARIF format that GitHub
+code scanning reads. Code scanning shows each result as an annotation on the
+line it applies to in the pull request diff, and tracks open results in the
+repository's **Security** tab.
+
+```yaml title=".github/workflows/lint.yaml"
+name: Lint
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npx zuplo lint --format sarif > zuplo-lint.sarif
+
+      - name: Upload results
+        if: ${{ !cancelled() }}
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: zuplo-lint.sarif
+          category: zuplo-lint
+```
+
+The `if: ${{ !cancelled() }}` condition uploads the results even when the lint
+step fails, so the annotations appear on the pull requests that need them. The
+lint step still fails the job.
+
+:::note
+
+Code scanning is available on public repositories, and on private repositories
+with GitHub Advanced Security. Without it, use the
+[pass/fail workflow](#fail-pull-requests-on-lint-errors) — the results appear in
+the job log.
+
+:::
+
+## Report breaking changes on pull requests
+
+[Breaking change detection](./api-lint-breaking-changes.mdx) compares your
+OpenAPI files with the version on another branch. In CI, point the baseline at
+the remote branch and make sure Git has fetched it.
+
+```jsonc title="zuplo.lint.jsonc"
+{
+  "version": 2,
+  "breakingChanges": {
+    "enabled": true,
+    "baseline": "origin/main",
+    "severity": "error",
+  },
+}
+```
+
+`actions/checkout` fetches a single commit by default, and the local `main`
+branch doesn't exist in that checkout. Set `fetch-depth: 0` to fetch the full
+history, including `origin/main`:
+
+```yaml title=".github/workflows/lint.yaml"
+steps:
+  - uses: actions/checkout@v4
+    with:
+      fetch-depth: 0
+
+  - uses: actions/setup-node@v4
+    with:
+      node-version: 24
+
+  - name: Install dependencies
+    run: npm ci
+
+  - name: Lint
+    run: npx zuplo lint
+```
+
+If the baseline isn't in the checkout, the run fails with
+`baseline ref "origin/main" not found`. Fetch the branch before linting.
+
+`origin/main` also works on your machine after a `git fetch`, so the same
+configuration file serves local runs and CI.
+
+To report breaking changes without blocking the merge, set `"severity": "warn"`.
+The changes still appear in the output and in code scanning, and the job passes
+unless `failOn` is `"warn"`.
+
+## Use the JSON output in scripts
+
+`--format json` prints a single JSON document with a summary, every result, and
+any breaking changes or fixes. Use it to build your own report, such as a pull
+request comment or a job summary:
+
+```yaml title=".github/workflows/lint.yaml"
+- name: Lint
+  id: lint
+  run: npx zuplo lint --format json > zuplo-lint.json || true
+
+- name: Summarize
+  run: |
+    jq -r '"### Zuplo lint\n\n\(.summary.errors) errors, \(.summary.warnings) warnings, \(.summary.breakingChanges) breaking changes"' \
+      zuplo-lint.json >> "$GITHUB_STEP_SUMMARY"
+    jq -e '.passed' zuplo-lint.json > /dev/null
+```
+
+`--fail-on none` keeps the lint step from failing before the summary is written;
+the final `jq -e '.passed'` fails the job when the run didn't pass. The `passed`
+field already takes `failOn` from your configuration file into account. See
+[Output formats](./api-lint.mdx#output-formats) for the full JSON shape.
+
+## Other CI systems
+
+Any CI system that runs Node.js can run the linter. Each workflow above uses
+three things you need to carry over:
+
+1. **Install the project's dependencies** with `npm ci` (or your package
+   manager's equivalent), so `npx zuplo` uses the version in your lockfile.
+2. **Run `npx zuplo lint`** from the project root, or pass `--dir`. With
+   `--dir`, file paths in the output are relative to that directory, so SARIF
+   results won't line up with files in code scanning unless the project is at
+   the repository root.
+3. **Read the exit code.** `0` passes, `1` means the linter found problems, and
+   `2` means it couldn't run. Treat `2` as a broken pipeline rather than a lint
+   result — check the error message in the log.
+
+For breaking change detection, also fetch the baseline branch before linting,
+for example with `git fetch origin main`.
+
+## Troubleshooting
+
+### The linter binary for your platform isn't installed
+
+The linter ships as a separate, platform-specific package that npm installs
+alongside the Zuplo CLI as an optional dependency. If optional dependencies are
+skipped — for example with `npm install --omit=optional` — `zuplo lint` stops
+with:
+
+```txt
+The zuplo-lint binary for your platform (linux-x64) is not installed.
+```
+
+Install the dependencies again without skipping optional dependencies. The error
+message names the exact package for your platform, such as
+`@zuplo/lint-linux-x64`, if you need to install it directly.
+
+### Invalid directory
+
+```txt
+Invalid directory: The project directory is not the root of a Zuplo project.
+```
+
+The command needs a `config/` directory containing at least one file that ends
+in `.oas.json`. Run it from the project root, or pass `--dir` to point at the
+project. This error exits with `2`.
+
+## Next steps
+
+- [Lint configuration](./api-lint-configuration.mdx) — presets, severities, and
+  breaking change settings.
+- [Testing your API](./testing.mdx) — run tests against a live gateway in the
+  same pipeline.
+- [Custom CI/CD](./custom-ci-cd.mdx) — deploy from your own CI system.