[GH-ISSUE #649] [Docs] README, AGENTS.md, and docs/testing.md still describe the removed TypeDoc API docs pipeline #308

Closed
opened 2026-10-15 18:23:43 +00:00 by bsakaguchi · 0 comments
Owner

Originally created by @coygeek on GitHub (Oct 6, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/649

Summary

The commit "chore(deps): remove incompatible TypeDoc generator" removed the docs:api and docs:api:cached scripts, the docs:api Turbo task, typedoc.json, and the CI step that uploaded the api-docs artifact, and it updated CONTRIBUTING.md and removed the docs:api:cached row from the docs/testing.md command table. The follow-up pull request #644 added a conformance test that asserts the removal. Four statements on main still describe the removed pipeline: two in README.md, one in AGENTS.md, and one in docs/testing.md. A contributor or coding agent who follows AGENTS.md and runs npm run docs:api:cached gets a missing-script error, and readers of README.md are told that PR CI renders TypeDoc and publishes an api-docs artifact, which it no longer does.

Affected area

  • README.md:385: "PR CI verifies this catalog, narrative documentation, generated schemas, and a clean TypeDoc render."
  • README.md:654: "PR CI publishes generated API documentation as the api-docs artifact."
  • AGENTS.md:38: "npm run docs:check: check committed generated documents; npm run docs:api:cached separately renders API HTML when needed."
  • docs/testing.md:232-233: "TypeDoc rendering is a separate command and CI step."
  • Related qualifier, docs/testing.md:185: the npm run docs:check row says "Committed generated-document freshness, without API HTML rendering". At 4.0.1 this contrasted with the next row, npm run docs:api:cached ("Explicit cached API HTML rendering"), which the removal deleted. The qualifier is not false by itself, but it now points at a rendering path that no longer exists.

Runtime or environment

  • Repository: main at 19f8cddfd6, fresh clone.
  • Removal commit: 965d0b35f9.
  • Latest published release: rea-agents 4.0.1 (tag rea-agents-4.0.1, feeb19b8b3), which predates the removal.
  • Local tools: Node.js v22.23.2 and npm 12.0.2 on macOS. These differ from the Node.js 24.18.x and npm 11.16.x that CONTRIBUTING.md asks contributors to use; the result below comes from npm's script lookup in package.json and needs no installed dependencies.

Steps to reproduce

  1. Clone the repository and check out the main baseline above.
  2. Read the locations listed under Affected area.
  3. Without installing dependencies, run npm run docs:api:cached and npm run docs:api in the clone root.
  4. Search the tree: grep -rn -i 'typedoc\|api-docs\|docs:api\|api html' --exclude-dir=node_modules --exclude-dir=.git . | grep -v package-lock.
  5. Optional CI check: list the artifacts of any PR CI run after the removal commit, for example run 37412309539 (pull request #647, head commit e4bf5048): gh api repos/morluto/rea/actions/runs/37412309539/artifacts --jq '.artifacts[].name'. Then list the steps of its "Docs Generation" job.

Expected behavior

After the removal commit, the documentation should describe only the documentation checks that exist. CONTRIBUTING.md on main already does this: "docs:check checks committed generated metadata. docs:generate regenerates those files, and the docs CI lane checks them." The conformance test tests/conformance/releaseConfiguration.test.ts ("keeps generated API HTML out of the tracked tree") asserts that typedoc.json is absent and that package.json has no docs:api script, so the removal is intentional. README.md, AGENTS.md, and docs/testing.md should therefore not claim that PR CI performs a TypeDoc render, that it publishes an api-docs artifact, or that npm run docs:api:cached renders API HTML.

Actual behavior

All four statements and the qualifier are present verbatim on main. Running the script named in AGENTS.md fails. Each command also printed a final line pointing at npm's local debug log; that line is omitted below.

$ npm run docs:api:cached
npm error Missing script: "docs:api:cached"
npm error
npm error To see a list of scripts, run:
npm error   npm run
exit=1

$ npm run docs:api
npm error Missing script: "docs:api"
npm error
npm error To see a list of scripts, run:
npm error   npm run
exit=1

On main, npm run lists docs:generate, docs:generate:unlocked, docs:check, docs:check:built, and docs:error-schema, but no docs:api* script. turbo.json has no docs:api task, and .github/workflows/ci.yml has no docs:api:cached step and no api-docs upload. The PR CI run 37412309539 uploaded eight artifacts: vitest-report-0 through vitest-report-3, rea-dist, reconstruction-readiness, windows-capabilities, and test-results. None of them is api-docs. Its "Docs Generation" job ran only npm ci and npm run docs:check between setup and teardown. The grep in step 4 finds no other matches besides the four stale statements, the docs/testing.md:185 qualifier, the conformance test above, and historical CHANGELOG.md entries.

Evidence

  • Expected source: CONTRIBUTING.md:55-56 and tests/conformance/releaseConfiguration.test.ts:104-112 on main, plus the removal commit's diff of package.json, turbo.json, typedoc.json, and .github/workflows/ci.yml.
  • Failure source: README.md:385, README.md:654, AGENTS.md:38, and docs/testing.md:232-233 (with the related qualifier at docs/testing.md:185) on main, with the npm run docs:api:cached output and the CI run 37412309539 artifact list shown under Actual behavior.
  • Evidence provenance: observed
  • Local verification: reproduced
  • Reproduction completeness: complete

The evidence above comes from a fresh clone, local npm run, and read-only GitHub API queries for the CI run. The removal commit deleted exactly the scripts, Turbo task, config file, and CI upload step that these four statements describe. At the 4.0.1 tag the scripts docs:api (typedoc) and docs:api:cached (turbo run docs:api), the docs:api Turbo task, typedoc.json, and the CI upload of build/api-docs as api-docs all exist, so the same four statements were accurate for the 4.0.1 release. This report concerns main only. README.md is in the package files list, and the open release pull request #635 for 4.0.2 does not change these lines, so the next npm release would carry the stale README.md statements unless they are corrected first.

Restoration check

On main, README.md, AGENTS.md, and docs/testing.md no longer state or imply that PR CI performs a TypeDoc render, publishes an api-docs artifact, or that npm run docs:api:cached (or docs:api) renders API HTML. Any documentation command a reader is told to run exists in package.json. Repeating the grep in step 4 returns no matches in README.md, AGENTS.md, or docs/testing.md that describe TypeDoc, an api-docs artifact, or a docs:api* command; the remaining matches are historical CHANGELOG.md entries, the conformance test that asserts the removal, and at most a reworded docs/testing.md:185 row that no longer implies a separate API HTML rendering command. As a control, the existing conformance test that asserts the absence of typedoc.json and the docs:api script still passes. A wording change that only renames the missing command, or one that reintroduces a TypeDoc step without a working script and CI step, does not restore the contract.

Additional context

Issue #643 ("docs:api broken under TypeScript 7 (typedoc incompatible)") led to the removal and was closed with a comment that "related docs were removed." The removal commit updated CONTRIBUTING.md and the docs/testing.md command table but not the four statements above. The translated READMEs (README_ar.md, README_ja.md, README_ko.md, README_zh.md) contain no TypeDoc, api-docs, or docs:api string.

Triage assessment

  • Impact level: P3
  • Assessment status: supported
  • Impact basis: Following the stale text causes no data loss or broken product behavior. npm run docs:api:cached fails immediately with a clear missing-script error, and the README claims about PR CI only misdescribe contributor tooling. The effect is limited to contributors and coding agents who read AGENTS.md, README.md, or docs/testing.md.
  • Workaround status: available
  • Workaround basis: CONTRIBUTING.md on main correctly describes docs:check and docs:generate as the documentation checks, and npm run lists the scripts that exist. No API HTML rendering exists to preserve.
Originally created by @coygeek on GitHub (Oct 6, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/649 ## Summary The commit "chore(deps): remove incompatible TypeDoc generator" removed the `docs:api` and `docs:api:cached` scripts, the `docs:api` Turbo task, `typedoc.json`, and the CI step that uploaded the `api-docs` artifact, and it updated `CONTRIBUTING.md` and removed the `docs:api:cached` row from the `docs/testing.md` command table. The follow-up pull request #644 added a conformance test that asserts the removal. Four statements on `main` still describe the removed pipeline: two in `README.md`, one in `AGENTS.md`, and one in `docs/testing.md`. A contributor or coding agent who follows `AGENTS.md` and runs `npm run docs:api:cached` gets a missing-script error, and readers of `README.md` are told that PR CI renders TypeDoc and publishes an `api-docs` artifact, which it no longer does. ## Affected area - `README.md:385`: "PR CI verifies this catalog, narrative documentation, generated schemas, and a clean TypeDoc render." - `README.md:654`: "PR CI publishes generated API documentation as the `api-docs` artifact." - `AGENTS.md:38`: "`npm run docs:check`: check committed generated documents; `npm run docs:api:cached` separately renders API HTML when needed." - `docs/testing.md:232-233`: "TypeDoc rendering is a separate command and CI step." - Related qualifier, `docs/testing.md:185`: the `npm run docs:check` row says "Committed generated-document freshness, without API HTML rendering". At 4.0.1 this contrasted with the next row, `npm run docs:api:cached` ("Explicit cached API HTML rendering"), which the removal deleted. The qualifier is not false by itself, but it now points at a rendering path that no longer exists. ## Runtime or environment - Repository: `main` at 19f8cddfd6f283188567b8ff1e49b810d79952ee, fresh clone. - Removal commit: 965d0b35f9907d1a4a3ce16553c01f20368b576c. - Latest published release: `rea-agents` 4.0.1 (tag `rea-agents-4.0.1`, feeb19b8b3172b2827b80fde8f09570ce5aeed88), which predates the removal. - Local tools: Node.js v22.23.2 and npm 12.0.2 on macOS. These differ from the Node.js 24.18.x and npm 11.16.x that `CONTRIBUTING.md` asks contributors to use; the result below comes from npm's script lookup in `package.json` and needs no installed dependencies. ## Steps to reproduce 1. Clone the repository and check out the `main` baseline above. 2. Read the locations listed under Affected area. 3. Without installing dependencies, run `npm run docs:api:cached` and `npm run docs:api` in the clone root. 4. Search the tree: `grep -rn -i 'typedoc\|api-docs\|docs:api\|api html' --exclude-dir=node_modules --exclude-dir=.git . | grep -v package-lock`. 5. Optional CI check: list the artifacts of any PR CI run after the removal commit, for example run 37412309539 (pull request #647, head commit `e4bf5048`): `gh api repos/morluto/rea/actions/runs/37412309539/artifacts --jq '.artifacts[].name'`. Then list the steps of its "Docs Generation" job. ## Expected behavior After the removal commit, the documentation should describe only the documentation checks that exist. `CONTRIBUTING.md` on `main` already does this: "`docs:check` checks committed generated metadata. `docs:generate` regenerates those files, and the docs CI lane checks them." The conformance test `tests/conformance/releaseConfiguration.test.ts` ("keeps generated API HTML out of the tracked tree") asserts that `typedoc.json` is absent and that `package.json` has no `docs:api` script, so the removal is intentional. `README.md`, `AGENTS.md`, and `docs/testing.md` should therefore not claim that PR CI performs a TypeDoc render, that it publishes an `api-docs` artifact, or that `npm run docs:api:cached` renders API HTML. ## Actual behavior All four statements and the qualifier are present verbatim on `main`. Running the script named in `AGENTS.md` fails. Each command also printed a final line pointing at npm's local debug log; that line is omitted below. ```text $ npm run docs:api:cached npm error Missing script: "docs:api:cached" npm error npm error To see a list of scripts, run: npm error npm run exit=1 $ npm run docs:api npm error Missing script: "docs:api" npm error npm error To see a list of scripts, run: npm error npm run exit=1 ``` On `main`, `npm run` lists `docs:generate`, `docs:generate:unlocked`, `docs:check`, `docs:check:built`, and `docs:error-schema`, but no `docs:api*` script. `turbo.json` has no `docs:api` task, and `.github/workflows/ci.yml` has no `docs:api:cached` step and no `api-docs` upload. The PR CI run 37412309539 uploaded eight artifacts: `vitest-report-0` through `vitest-report-3`, `rea-dist`, `reconstruction-readiness`, `windows-capabilities`, and `test-results`. None of them is `api-docs`. Its "Docs Generation" job ran only `npm ci` and `npm run docs:check` between setup and teardown. The grep in step 4 finds no other matches besides the four stale statements, the `docs/testing.md:185` qualifier, the conformance test above, and historical `CHANGELOG.md` entries. ## Evidence - Expected source: `CONTRIBUTING.md:55-56` and `tests/conformance/releaseConfiguration.test.ts:104-112` on `main`, plus the removal commit's diff of `package.json`, `turbo.json`, `typedoc.json`, and `.github/workflows/ci.yml`. - Failure source: `README.md:385`, `README.md:654`, `AGENTS.md:38`, and `docs/testing.md:232-233` (with the related qualifier at `docs/testing.md:185`) on `main`, with the `npm run docs:api:cached` output and the CI run 37412309539 artifact list shown under Actual behavior. - Evidence provenance: observed - Local verification: reproduced - Reproduction completeness: complete The evidence above comes from a fresh clone, local `npm run`, and read-only GitHub API queries for the CI run. The removal commit deleted exactly the scripts, Turbo task, config file, and CI upload step that these four statements describe. At the 4.0.1 tag the scripts `docs:api` (`typedoc`) and `docs:api:cached` (`turbo run docs:api`), the `docs:api` Turbo task, `typedoc.json`, and the CI upload of `build/api-docs` as `api-docs` all exist, so the same four statements were accurate for the 4.0.1 release. This report concerns `main` only. `README.md` is in the package `files` list, and the open release pull request #635 for 4.0.2 does not change these lines, so the next npm release would carry the stale `README.md` statements unless they are corrected first. ## Restoration check On `main`, `README.md`, `AGENTS.md`, and `docs/testing.md` no longer state or imply that PR CI performs a TypeDoc render, publishes an `api-docs` artifact, or that `npm run docs:api:cached` (or `docs:api`) renders API HTML. Any documentation command a reader is told to run exists in `package.json`. Repeating the grep in step 4 returns no matches in `README.md`, `AGENTS.md`, or `docs/testing.md` that describe TypeDoc, an `api-docs` artifact, or a `docs:api*` command; the remaining matches are historical `CHANGELOG.md` entries, the conformance test that asserts the removal, and at most a reworded `docs/testing.md:185` row that no longer implies a separate API HTML rendering command. As a control, the existing conformance test that asserts the absence of `typedoc.json` and the `docs:api` script still passes. A wording change that only renames the missing command, or one that reintroduces a TypeDoc step without a working script and CI step, does not restore the contract. ## Additional context Issue #643 ("docs:api broken under TypeScript 7 (typedoc incompatible)") led to the removal and was closed with a comment that "related docs were removed." The removal commit updated `CONTRIBUTING.md` and the `docs/testing.md` command table but not the four statements above. The translated READMEs (`README_ar.md`, `README_ja.md`, `README_ko.md`, `README_zh.md`) contain no `TypeDoc`, `api-docs`, or `docs:api` string. ## Triage assessment - Impact level: P3 - Assessment status: supported - Impact basis: Following the stale text causes no data loss or broken product behavior. `npm run docs:api:cached` fails immediately with a clear missing-script error, and the README claims about PR CI only misdescribe contributor tooling. The effect is limited to contributors and coding agents who read `AGENTS.md`, `README.md`, or `docs/testing.md`. - Workaround status: available - Workaround basis: `CONTRIBUTING.md` on `main` correctly describes `docs:check` and `docs:generate` as the documentation checks, and `npm run` lists the scripts that exist. No API HTML rendering exists to preserve.
bsakaguchi 2026-10-15 18:23:43 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#308
No description provided.