fix(api-docs/ts): derive package names from the manifest, restore the 7 dropped packages

[WomB0ComB0]

What

Audit of the four sibling API-docs templates for the same class of bug that
broke the .NET one — a value the template reads or hardcodes that the source
repo no longer matches. One of the four is broken. Three are fine and are
not touched.

Every verdict below was reached by extracting the template's own Python
extraction logic and running it against a fresh clone of the corresponding
repo, the same method that proved the .NET read_version() bug. No verdict
here rests on reading alone.

Scoped to the templates only; the .NET fix is a separate PR.

Per-template verdict

Template	Repo	Reads	Repo actually carries	Verdict
api-docs.rust.yml	crates	[package] version, falling back to [workspace.package] version	hybrid: 4 literal, 4 version.workspace = true	OK
api-docs.python.yml	pypi	first version = "…" in pyproject.toml	literal in [project] version, written by PSR	OK
api-docs.cpp.yml	vcpkg	version / version-semver / version-string / version-date in vcpkg.json	literal "version": "0.1.0"	OK
api-docs.typescript.yml	npm	.version from package.json — but rebuilds the package name from a hardcoded scope, and generates from a stale package list	literal versions; scope renamed; 16 packages	BROKEN — fixed here

rust — OK, no change

The suspicion was that the template would mis-read the hybrid workspace.
It does not. field_in() is ^\s*<name>\s*=\s*"([^"]+)", which requires a
double-quoted value, so version.workspace = true cannot match it — the
. breaks the \s*= and true is unquoted. The function returns "" and
field_in(pkg, "version") or ws_version falls through to the inherited
workspace version, which is the intended path (the neighbouring license
line documents exactly that inheritance).

Ran the real step against crates @ 0ce9c87, README-stub path. All 8
crates match their release-plz tags:

resq-ai      tag=0.1.2    banner=0.1.2
resq-bin     tag=0.1.24   banner=0.1.24   <- version.workspace = true
resq-clean   tag=0.1.24   banner=0.1.24   <- version.workspace = true
resq-cli     tag=0.4.5    banner=0.4.5
resq-dsa     tag=0.1.3    banner=0.1.3
resq-flame   tag=0.1.24   banner=0.1.24   <- version.workspace = true
resq-perf    tag=0.1.24   banner=0.1.24   <- version.workspace = true
resq-tui     tag=0.1.16   banner=0.1.16

The README.mdx step, which re-reads the banner it just wrote, reproduces
the same 8 lines. 8/8, no unknown.

python — OK, no change

pypi configures python-semantic-release with
version_toml = ["pyproject.toml:project.version"] in both released
packages. That directs PSR to write a literal into [project] version
on each release, so there is no dynamic source for the template to miss —
this is the opposite of the MinVer situation. Ran the index step against
pypi @ acb1fbf:

- `resq-dsa` — `v1.3.4`
- `resq-mcp` — `v1.3.3`

Matches the manifests and the v1.3.4 repo tag.

cpp — OK, no change

vcpkg has one package. packages/resq-common/vcpkg.json carries a literal
"version": "0.1.0", agreeing with project(resq-common VERSION 0.1.0 …)
and the resq-common@v0.1.0 tag. Ran the index step against vcpkg @
446b1cd:

- `resq-common` — `v0.1.0`

typescript — BROKEN, fixed in this PR

The version read itself is fine, as expected: package.json always carries
a literal, and all 16 resolved. Two other stale literals in the same step
are not fine.

1. Hardcoded, dead npm scope. The index line was
print(f"- \@resq-sw/{pkg_dir.name}` — `v{version}`"). That scope was renamed to @resq-systems/inresq-software/npm#167("Rebrand to ResQ Systems: rename npm scope@resq-sw/→@resq-systems/*"). @resq-swappears **0 times** across the monorepo'spackage.jsonfiles today;@resq-systems` appears 55 times. The template therefore renders install
names that no longer resolve.

Fixed by reading .name from the manifest the function already opens for
.version — same lesson as MinVer: derive from the source of truth instead
of restating it. The directory name stays as the fallback so a missing or
unparseable manifest still produces a readable entry.

2. PUBLIC_PACKAGES had drifted to 9 of 16. Missing: constants,
email-templates, map, math, nav, telemetry, types.

This is the damaging half. Sync generated MDX clears the target directory
before copying, so a tag-triggered run from the stale list would have
removed 6 already-published package doc trees from sdks/typescript/api/
(all 6 are live in this repo today) and never added nav. The generation
step's own comment warns about precisely this — "a partial sync would delete
these packages' published docs" — but its guard only catches listed and
absent, not present and unlisted.

The list now equals every packages/*/ that has a src/, which is exactly
the set the generation loop accepts. Verified equal by set-diff.

Proof for the fix

Patched index step, run against a clone of resq-software/npm @ 39ea053:

- `@resq-systems/analytics` — `v2.0.2`
- `@resq-systems/constants` — `v0.7.0`
- `@resq-systems/decorators` — `v0.4.0`
- `@resq-systems/dsa` — `v2.2.0`
- `@resq-systems/email-templates` — `v1.2.0`
- `@resq-systems/helpers` — `v0.6.0`
- `@resq-systems/http` — `v2.0.2`
- `@resq-systems/logger` — `v0.3.0`
- `@resq-systems/map` — `v4.0.0`
- `@resq-systems/math` — `v0.2.1`
- `@resq-systems/nav` — `v0.2.0`
- `@resq-systems/rate-limiting` — `v0.4.3`
- `@resq-systems/security` — `v2.1.0`
- `@resq-systems/telemetry` — `v0.4.0`
- `@resq-systems/types` — `v0.2.0`
- `@resq-systems/ui` — `v0.42.0`

Before the fix the same run produced 16 lines under the dead @resq-sw/
scope, and PUBLIC_PACKAGES would have limited generation to 9 of them.

actionlint is clean on all five templates.

Worth a follow-up, deliberately not in this PR

The npm copy of this workflow has diverged from the template by 81 lines,
and carries downstream-only fixes from July–September 2026 that were never
brought back here — including both items above, plus a setup-bun
cache-poisoning mitigation. Conversely the template holds a newer
hardening the copy lacks (abort-on-any-package-failure, #113). Reconciling
that full divergence is a larger change and is left separate.

crates and vcpkg differ only by Dependabot action bumps. pypi also
carries a setup-uv cache-poisoning mitigation not present here.

Test plan

• Template extraction logic run against real clones of crates, pypi, vcpkg, npm
• rust output cross-checked against 204 release tags — 8/8 exact
• python and cpp outputs cross-checked against manifests and tags
• Patched typescript step emits 16/16 correct name+version pairs
• PUBLIC_PACKAGES set-diffed against packages/*/src/ — exact match
• actionlint clean on all five templates
• Sync to resq-software/npm and confirm the next release-tag run publishes all 16 (post-merge; note the divergence above before syncing)

Summary by CodeRabbit

• Documentation
  • Updated generated API documentation to use the current package scope.
  • Expanded the set of packages included in public API documentation.
  • Improved package listings in the documentation index by using each package’s published name.
  • Added fallback handling for packages with missing or unreadable metadata.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: ffe2bd77-6e92-424e-95f7-d3154eb9747e

📥 Commits

Reviewing files that changed from the base of the PR and between 5f24756 and f6f3b7a.

📒 Files selected for processing (1)

• automation/source-repo-templates/api-docs.typescript.yml

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The TypeDoc workflow template now includes more public packages and reads package names and versions from each package manifest. It also updates package scope references in comments, generated index output, and pull request text.

Changes

API documentation package metadata

Layer / File(s)	Summary
Manifest-driven documentation index automation/source-repo-templates/api-docs.typescript.yml	The workflow adds seven packages to PUBLIC_PACKAGES. read_manifest reads package names and versions with fallbacks. The generated README.mdx uses manifest names. Package scope references use @resq-systems/*.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to f6f3b

The workflow updates generated TypeScript API documentation to include the restored packages and manifest-defined names and versions, with fallbacks for incomplete manifests. No concrete merge-blocking production risk is identified.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the two main changes: deriving package names from manifests and restoring the seven missing packages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}