Skip to content

fix(document-api): stop requiring alpha wording in overview check #3454

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
caio-pizzol merged 1 commit into from
May 22, 2026
Merged

fix(document-api): stop requiring alpha wording in overview check #3454

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/document-api/scripts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Do not hand-edit generated output files. Regenerate instead.
| `generate-agent-artifacts.ts` | generate | Regenerate agent artifacts (remediation/workflow/compatibility) | Contract snapshot | `packages/document-api/generated/agent/*` | Focused agent-artifact regeneration |
| `check-generated-reference-docs.ts` | check | Validate generated reference docs and overview generated block drift | Contract snapshot + `apps/docs/document-api/reference` + overview | None | Focused docs generation check |
| `generate-reference-docs.ts` | generate | Regenerate generated reference docs and overview generated block | Contract snapshot + overview markers | `apps/docs/document-api/reference/*`, generated block in `apps/docs/document-api/overview.mdx` | Focused docs regeneration |
| `check-overview-alignment.ts` | check | Enforce overview quality rules (required copy/markers, forbidden placeholders, known API paths only) | `apps/docs/document-api/overview.mdx` + `DOCUMENT_API_MEMBER_PATHS` | None | Docs consistency gate |
| `check-overview-alignment.ts` | check | Enforce structural correctness of the overview page: reference link, generated section markers, no stale placeholders, only known `editor.doc.*` paths | `apps/docs/document-api/available-operations.mdx` + `DOCUMENT_API_MEMBER_PATHS` | None | Docs consistency gate |
| `check-doc-coverage.ts` | check | Ensure every operation has a `### \`<operationId>\`` section in `src/README.md` | `packages/document-api/src/README.md` + `OPERATION_IDS` | None | Contract/docs coverage gate |
| `check-examples.ts` | check | Ensure required workflow example headings exist in `src/README.md` | `packages/document-api/src/README.md` | None | Docs workflow example gate |
| `check-contract-parity.ts` | check | Enforce parity between operation IDs, command catalog, maps, and runtime API member paths | `packages/document-api/src/index.js` exports + runtime API shape | None | Contract surface integrity gate |
Expand Down
20 changes: 9 additions & 11 deletions packages/document-api/scripts/check-overview-alignment.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,15 @@
/**
* Purpose: Enforce required/forbidden overview content and API-surface path validity.
* Caller: Documentation consistency gate for `apps/docs/document-api/overview.mdx`.
* Purpose: Enforce structural correctness of the Document API overview page.
* Caller: Documentation consistency gate for `apps/docs/document-api/available-operations.mdx`.
* Reads: Overview doc content + `DOCUMENT_API_MEMBER_PATHS`.
* Writes: None (exit code + console output only).
* Fails when: Disclaimers/markers are missing, forbidden placeholders exist, or unknown API paths appear.
* Fails when: The reference link or generated section markers are missing,
* forbidden stale placeholders appear, or `editor.doc.*` paths reference
* unknown API members.
*
* NOT enforced: product-status framing (e.g. "alpha", "subject to change").
* Those launch-phase disclaimers were removed when the Document API went
* live; this gate now focuses on durable structural correctness.
*/
import { readFile } from 'node:fs/promises';
import { resolve } from 'node:path';
Expand All @@ -18,14 +24,6 @@ import {
const OVERVIEW_PATH = resolve(process.cwd(), getOverviewDocsPath());

const REQUIRED_PATTERNS = [
{
label: 'alpha disclaimer',
pattern: /\balpha\b/i,
},
{
label: 'subject-to-change disclaimer',
pattern: /subject to (?:breaking )?changes?/i,
},
{
label: 'generated reference link',
pattern: /\/document-api\/reference\/index/i,
Expand Down
Loading