code-transform.mdx §ID Generation omits the package-shipped `name@version` ID form
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 2.4k
- Forks
- 365
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 169
Description
Summary
how-it-works/code-transform.mdx §"ID Generation" (v4:309-329, v5:311-329) documents only the local-file ID form {type}//{filepath}//{functionName} and never mentions the package-shipped form {type}//{name}/{subpath}@{version}//{functionName} (produced by packages/builders/src/module-specifier.ts:370-402 for export-reachable package files).
Not wrong, but incomplete in exactly the direction that made the #3152 error plausible: a reader learns IDs come from file paths, so "re-export into my workflows/ dir → my path → my ID" is a natural inference — the same inference #3153 corrects in publishing-libraries.mdx.
Suggested fix
Add the package-shipped form to the ID Generation section, next to the local-file form, with one line on when each applies (workspace/local files vs. export-reachable npm package files). The section's existing callout already states deployment pinning correctly ("changing IDs won't break old workflows from running, but will prevent runs from being upgraded"), so only the ID-form table/list needs the addition.
Related: #3152, #3153. Found during a docs sweep while building the Mastra integration.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Open how-it-works/code-transform.mdx and locate the “ID Generation” section at v4:309-329 or v5:311-329. Compare its local-file form with the package-shipped form produced in packages/builders/src/module-specifier.ts:370-402, then document when each applies to make the section complete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 90/100