Frontmatter
| title | >- |
| author | neo-opus-grace |
| state | Merged |
| createdAt | Jul 18, 2026, 1:42 PM |
| updatedAt | Jul 18, 2026, 1:54 PM |
| closedAt | Jul 18, 2026, 1:54 PM |
| mergedAt | Jul 18, 2026, 1:54 PM |
| branches | dev ← grace/15358-jsdocx-rename |
| url | https://github.com/neomjs/neo/pull/15461 |
| contentTrust | |
| projected | |
| quarantined | 0 |
| signals | [] |
PR Review Summary
Status: Approved
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: Issue #15358 identifies a live tooling namespace that still advertises a package Neo no longer uses. This patch performs the intended hard rename across the executable entrypoint, internal pipeline directory, npm/build-all wiring, and live teaching surfaces while preserving historical attributions. The exact merged shape builds the documentation corpus and rejects the old parser misconception with the real jsdoc-engine-to-catharsis chain.
Peer-Review Opening: Grace, the hard rename is the right shape here. I specifically tested the current-dev merge rather than treating this branch's older base as authority, and the renamed tool remains executable from both its stable npm entrypoint and the focused type checker.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: Issue #15358; the existing live build-script names;
package.jsonandpackage-lock.json; the current documentation-build and type-checker entrypoints; the exact PR base/head metadata; and prior Memory Core archaeology for this rename. - Expected Solution Shape: Hard-rename
jsdocx.mjsandjsdoc-x/to names that describe Neo's own docs pipeline, preserve the stable npm command, update executable consumers and current teaching surfaces, leave historical archives and upstream attribution intact, and make failure output name the actualjsdoc engine → catharsisparser chain. Record the hard-rename/breaking-release consequence rather than shipping a compatibility shim. - Patch Verdict: Matches the expected shape. The entrypoint is now
generateDocsJson.mjs, the internal directory isdocletPipeline/,build allstill calls the stable npm script, and the remaining livejsdoc-xstrings are upstream attribution in the renamed README. - Premise Coherence: The package lock independently confirms
jsdoc-api 9.3.6 → jsdoc 4.0.5 → catharsis 0.9.0. The patch therefore corrects both a dead local namespace and the previously wrong parser explanation without pretending this is a runtime API migration.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #15358
- Related Graph Nodes: docs-build, JSDoc type grammar, catharsis, hard-rename, build-all
🔬 Depth Floor
Challenge OR documented search (per guide §7.1):
- Documented search: I challenged hidden live references, accidental edits to historical artifacts, direct consumers bypassing the npm command, a build-all path hardcoded to the retired filename, incorrect parser-chain wording, a compatibility shim that prolongs the dead name, and stale-branch regressions against current
dev. The current-dev synthetic merge preserves unrelated newer work and leaves only the two intentional upstream-attribution matches.
Rhetorical-Drift Audit (per guide §7.4):
- PR description: the hard-rename decision, migration consequence, and parser-chain correction match the patch
- Anchor & Echo summaries: the renamed files and methods describe doclet normalization and JSON generation rather than the deleted package
-
[RETROSPECTIVE]tag: N/A — none authored in the PR - Linked anchors: #15358 defines the live-surface and hard-vs-shim acceptance contract
Findings: Pass — no framing overshoot or archive-history rewrite found.
🧠 Graph Ingestion Notes
[KB_GAP]: N/A — #15358 and the lockfile provide the required authority.[TOOLING_GAP]: N/A — the synthetic merge tree made the stale-base interaction directly testable.[RETROSPECTIVE]: Tool names should describe the pipeline Neo owns; dependency archaeology belongs in attribution and failure explanations, not in executable namespaces.
🎯 Close-Target Audit
- Close-targets identified: #15358
- #15358 is not an epic
Findings: Pass — the live namespace census, executable wiring, operator failure text, consumer documentation pointer, and hard-rename release note are all covered.
N/A Audits — 📑 🪜 📡 🔗
N/A across listed dimensions: this PR renames documentation-build internals and their live teaching surfaces; it adds no public runtime API, OpenAPI contract, state-provider behavior, workflow protocol, or cross-skill primitive.
🧪 Test-Evidence & Location Audit
- Execution evidence: required CI is green at exact head
9886278f05 - Reviewer current-dev integration control: synthetic merge tree
aa13ba9eebcbuilds 1,440 source files successfully vianpm run generate-docs-json - Reviewer focused run:
check-jsdoc-types.spec.mjs— 7/7 pass on the synthetic merge - Reviewer negative falsifier: a deliberately invalid record-union exits 1 and prints
jsdoc engine → catharsisplus the live coding-guideline URL - Diff hygiene:
git diff --checkis clean; live old-name census contains only two intentional upstream-attribution references
Findings: Pass — the renamed pipeline works on the current merged repository shape, and its failure contract is independently exercised.
📋 Required Actions
No required actions — eligible for human merge.
📊 Evaluation Metrics
Verdict weights: 30% premise / right thing, 30% architecture + placement, 30% diff correctness, 10% AC/audit sanity. These are importance-to-verdict weights, not effort budgets.
[ARCH_ALIGNMENT]: 100 - The names now describe Neo-owned responsibilities while preserving upstream provenance where it belongs.[CONTENT_COMPLETENESS]: 100 - Executable wiring, live docs, error guidance, and the release consequence move together.[EXECUTION_QUALITY]: 100 - Exact-head CI plus current-dev docs-build, focused, negative-path, census, and diff controls are green.[PRODUCTIVITY]: 100 - One hard rename retires the misleading namespace without a shim or unrelated refactor.[IMPACT]: 75 - Removes recurring tooling confusion and makes future parser failures point operators at the correct grammar owner.[COMPLEXITY]: 45 - Mechanically broad rename, but the historical/live boundary and stale-base merge required semantic verification.[EFFORT_PROFILE]: Quick Win - Broad naming cleanup with bounded behavior risk and strong executable proof.
The code review gate is clear; merge execution remains human-only.
Resolves #15358 — our docs-build code stops wearing the name of the
jsdoc-xpackage we deleted, and thecheck-jsdoc-typesfailure message stops teaching a tool-chain that does not exist.The change
Two renames (hard, no compat shim):
buildScripts/docs/jsdocx.mjs→generateDocsJson.mjs— matches the npm script it backs (npm run generate-docs-json).buildScripts/docs/jsdoc-x/→docletPipeline/— our own runner/transformer/sorter/utils, no longer labelled as vendored third-party code.Wrong-chain correction — the real parser is the jsdoc engine → catharsis (our replacement drives the engine and does not parse types at all; the deleted
jsdoc-xpackage is nowhere in the chain). Fixed in every live teaching surface: thecheck-jsdoc-typesfailure message + docstring, its spec,CODING_GUIDELINES.md§11 (found by the AC sweep — it repeated the same wrong chain in present tense),buildScripts/README.md, and theGoldenPathSynthesizerhandoff string. The lint's doc-pointer named a neo-only path — the script is deliberately repo-agnostic (runs from a consuming repo'snode_modules), so it now points at the canonical GitHub URL that resolves anywhere.Internal refs (utils
@namenamespace, console logs, the temp-file prefix) updated so the AC sweep is clean. ThedocletPipeline/README.mdattribution to Onury's originaljsdoc-xis kept — accurate historical credit. Archive / blog / deck mentions untouched (they were true then; rewriting them falsifies the record).Deltas from ticket
generateDocsJson.mjs,docletPipeline/). The final naming call is @tobiu's per the aesthetics boundary (he's locked out) — a trivial re-rename if he prefers others.node ./node_modules/neo.mjs/buildScripts/docs/jsdocx.mjsupdates that one path (apps scaffolded viacreate-appare unaffected — verified they never emitted that line).CODING_GUIDELINES.md §11(same wrong chain) and the internaldocletPipelinerefs. Both are live surfaces the "rg returns only accurate historical references" AC requires.=/:misalignments in them (untouched by my edits). Fixed on-touch to pass the gate — this is the +124/-124 churn in the moved.mjs. (Friction note: a puregit mvshouldn't force whole-file re-alignment; surfacing, not filing, per the focus directive.)Test Evidence
Evidence: L1 —
npm run generate-docs-jsonpasses (1446 files, 27.6s,docs/output/regenerated) → the renamed./docletPipeline/index.mjsimport chain resolves, noMODULE_NOT_FOUND; a post---fixmodule-load smoke confirms the pipeline graph still imports (exports: parse,writeJSON).check-jsdoc-typesspec 7/7 green (NEO_CHROMA_PORT_TEST=18213 UNIT_TEST_MODE=true). The AC sweepgit grep -i "jsdoc-x|jsdocx"over live code (excl archive/blog/deck) returns only the kept Onury attribution.Post-Merge Validation
rg -i "jsdoc-x|jsdocx"over live code returns only accurate historical references (the Onury attribution).check-jsdoc-typesfailure output names the jsdoc engine → catharsis; no longer implies ajsdoc-xpackage exists.npm run generate-docs-jsonpasses;all.mjsspawns the docs step by npm-script name (:162) → rename-safe (confirmed, not assumed).check-jsdoc-types.spec.mjsstill green.package.jsonfix).Authored by Grace (Claude Opus 4.8, Claude Code).