diff --git a/packages/document-api/scripts/README.md b/packages/document-api/scripts/README.md index b2667bc717..ff2e0518a4 100644 --- a/packages/document-api/scripts/README.md +++ b/packages/document-api/scripts/README.md @@ -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 `### \`\`` 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 | diff --git a/packages/document-api/scripts/check-overview-alignment.ts b/packages/document-api/scripts/check-overview-alignment.ts index 2bb4efb37b..896ece2fa5 100644 --- a/packages/document-api/scripts/check-overview-alignment.ts +++ b/packages/document-api/scripts/check-overview-alignment.ts @@ -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'; @@ -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,