Repository navigation
Commit b8929f4
docs(spec): the major-18 conversions docblock places the import, not the definition (#30643)
<!-- claude-projects-attribution: {"github_login":"os-sales"} -->
_Requested by **Sales** · [project
thread](https://claude.ai/code/project/chan_01D5bWFY3rFzgJcytD5gD4Uu?thread=cmsg_01D5bWFY3rFzgJcytD5gD4UuV5cRafodM2YQHxeDkdiWJM)_
domain:spec#2 · os-sales · session_01L6bhgVugtCCwBs98FeR27P
Fixes #29994
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:只改 `packages/spec/src/conversions/registry.ts` 中
`MAJOR_18_CONVERSIONS` 头注的一条「新增转换」规则,不动任何代码行。
- 为什么改:转换拆成每条一个模块后,头注仍教作者把定义写进 `registry.ts`;现改为写独立模块、在 `registry.ts` 只加
import 与列表项,与合并测试一致。
- 风险与回滚:纯注释,`dist/` 不含这段文字,不发布、零运行时影响;回滚即 revert 本提交。
- 先看:`packages/spec/src/conversions/registry.ts` 第 181–189 行(唯一改动的
hunk)。
- 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2
scripts/conversions-major18-merge.test.ts`,预期 `Tests 12 passed (12)`。
- 需要你做的:无,席位落地。
## What changes
One bullet of the `MAJOR_18_CONVERSIONS` docblock's "To add a
conversion" list, the only one the per-entry split (PR #29993) made
false. The other two bullets (insert the entry where its identifier
sorts; how to pick `order`), the conflict explanation above them, and
the closing pointer to the merge test are still true and unchanged. No
code line moves.
Old:
> DEFINE it directly above the definition of the entry that follows it
in this list, so the conversion defined next after it is that entry. One
that sorts last is defined after every other conversion, directly above
`OrderedConversion`. The end of the definitions is one gap too: defining
every new conversion there conflicts exactly as appending here did.
New (two bullets):
> DEFINE it in a module of its own, `./entries/18/ID.ts`, the file named
for the conversion's `id` and exporting it by name (`export { IDENTIFIER
};`). A new file never conflicts.
>
> IMPORT it directly above the import of the entry that follows it in
this list, so the conversion imported next after it is that entry. One
that sorts last is imported after every other `./entries/18/` import.
The imports stand where the definitions stood before the split, and
their end is one gap too: importing every new conversion there conflicts
exactly as appending here did.
(`ID` and `IDENTIFIER` stand for the placeholders the source writes in
angle brackets.)
Each sentence is taken from what
`packages/spec/scripts/conversions-major18-merge.test.ts` asserts, not
from the card's paraphrase:
- module path and name: `MODULE_PATH` (`entries/18/ID.ts`) and
`definitionInModule` (`const IDENTIFIER: MetadataConversion = {` with
`id: 'ID'`, `toMajor: 18`, ending `export { IDENTIFIER };`);
- import above the successor's import: `placementFindings` (the import
that comes next is the next list entry's);
- one that sorts last: `definitionsTail`, after the last `./entries/18/`
import (today that is also the last import in the file, directly above
`OrderedConversion`'s doc comment, but the test anchors on the import,
so the rule does too);
- the tail is a gap: the lit control "the same two conversions imported
after every other conversion conflict".
It matches what `.claude/skills/spec-property-retirement/SKILL.md`
teaches on main after PR #30109 (`entries/TOMAJOR/ID.ts`, named for the
`id`, exported by name; the import directly above the successor entry's
import).
## Verification
Head `6943445b89`, base `778aedf666`.
- `packages/spec/scripts/conversions-major18-merge.test.ts` (the
authority, unchanged): `Test Files 1 passed (1)`, `Tests 12 passed
(12)`.
- `pnpm --filter @objectstack/spec build && pnpm --filter
@objectstack/spec check:generated`: lock `VERDICT command-exit 0`; "All
14 generated artifacts are up to date".
- `eslint --no-inline-config packages/spec/src/conversions/registry.ts`:
exit 0.
- `pnpm check:doc-authoring`: exit 0.
- Changeset: none, `skip-changeset`. A comment on a non-exported
`const`; measured after the build: the new and old docblock sentences
hit 0 files under `dist/` and every other `files[]` path, while the
positive controls `MAJOR_18_CONVERSIONS` and
`flowDecisionModeInclusiveExplicit` hit `dist/` chunks; `registry.ts` is
not a `src/**/*.zod.ts` path.
- No pin is owed: the change is a comment, and the rule it states is
already pinned by the merge test above.
<details><summary>Derived gate families (dispatch-gates --commands at
6943445): 67 run, exit codes captured before any pipe</summary>
`node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
--ran` → "67 derived, 67 run, 0 NOT-MEASURED, 0 UNRUN" (a DERIVED zero:
every line carries an exit code, none is 3).
| # | Command | Exit |
|---|---|---|
| 1 | `node scripts/check-adr-0087-registration.mjs --base origin/main`
| 0 |
| 2 | `node scripts/check-adr-0087-registration.mjs --self-test` | 0 |
| 3 | `node scripts/check-closing-keyword-parity.mjs` | 0 |
| 4 | `node scripts/check-closing-keyword-parity.mjs --self-test` | 0 |
| 5 | `node scripts/check-comment-mask-adoption.mjs` | 0 |
| 6 | `node scripts/check-comment-mask-adoption.mjs --self-test` | 0 |
| 7 | `node scripts/check-comment-mask-corpus.mjs` | 0 |
| 8 | `node scripts/check-dev-prereqs.mjs --self-test` | 0 |
| 9 | `node scripts/check-dts-emitted.mjs --self-test` | 0 |
| 10 | `node scripts/check-issue-citations.mjs` | 0 |
| 11 | `node scripts/check-plugin-teardown-shape.mjs` | 0 |
| 12 | `node scripts/check-plugin-teardown-shape.mjs --self-test` | 0 |
| 13 | `node scripts/ci/assert-turbo-remote-cache.mjs --self-test` | 0 |
| 14 | `node scripts/ci/plan-test-core-shards.mjs --self-test` | 0 |
| 15 | `node scripts/ci/prune-turbo-cache.mjs --self-test` | 0 |
| 16 | `node scripts/docs-audit/check-affected-docs.mjs` | 0 |
| 17 | `node scripts/docs-audit/check-drift-comment.mjs` | 0 |
| 18 | `pnpm --filter @objectstack/lint run
check:doc-formula-expressions` | 0 (first run exit 3, PREREQUISITE NOT
MET: other packages unbuilt; re-run 0 after the full `turbo run build`,
118/118 tasks) |
| 19 | `pnpm --filter @objectstack/spec run check:api-surface` | 0 |
| 20 | `pnpm --filter @objectstack/spec run
check:browser-reachable-entries` | 0 |
| 21 | `pnpm --filter @objectstack/spec run check:docs` | 0 |
| 22 | `pnpm --filter @objectstack/spec run check:dual-source-exports` |
0 |
| 23 | `pnpm --filter @objectstack/spec run check:duration-unit-keys` |
0 |
| 24 | `pnpm --filter @objectstack/spec run check:empty-state` | 0 |
| 25 | `pnpm --filter @objectstack/spec run check:entry-nameability` | 0
|
| 26 | `pnpm --filter @objectstack/spec run check:export-origins` | 0 |
| 27 | `pnpm --filter @objectstack/spec run check:exported-any` | 0 |
| 28 | `pnpm --filter @objectstack/spec run check:liveness` | 0 |
| 29 | `pnpm --filter @objectstack/spec run check:llms-txt` | 0 |
| 30 | `pnpm --filter @objectstack/spec run check:skill-refs` | 0 |
| 31 | `pnpm --filter @objectstack/spec run check:strictness-ledger` | 0
|
| 32 | `pnpm --filter @objectstack/spec run check:upgrade-guide` | 0 |
| 33 | `pnpm --filter @objectstack/spec run check:variant-docs` | 0 |
| 34 | `pnpm check:changeset-gate-self-tests` | 0 |
| 35 | `pnpm check:ci-filter-parity` | 0 |
| 36 | `pnpm check:closed-ceremony-text` | 0 |
| 37 | `pnpm check:cross-package-test-inputs` | 0 |
| 38 | `pnpm check:dispatcher-error-vocabulary` | 0 |
| 39 | `pnpm check:doc-authoring` | 0 |
| 40 | `pnpm check:driver-memory-census` | 0 |
| 41 | `pnpm check:dts-closure` | 0 |
| 42 | `pnpm check:dual-build-cjs-loads` | 0 (first run exit 3,
PREREQUISITE NOT MET: other packages unbuilt; re-run 0 after the full
`turbo run build`, 118/118 tasks) |
| 43 | `pnpm check:gitlink-declared` | 0 |
| 44 | `pnpm check:issue-citations` | 0 |
| 45 | `pnpm check:keyed-text-bounds` | 0 |
| 46 | `pnpm check:lean-entry-closure` | 0 (first run exit 3,
PREREQUISITE NOT MET: other packages unbuilt; re-run 0 after the full
`turbo run build`, 118/118 tasks) |
| 47 | `pnpm check:logger-receiver-detach` | 0 |
| 48 | `pnpm check:merge-driver` | 0 |
| 49 | `pnpm check:nul-bytes` | 0 |
| 50 | `pnpm check:org-identifier` | 0 |
| 51 | `pnpm check:page-declaration-shape` | 0 |
| 52 | `pnpm check:platform-object-tenancy-census` | 0 |
| 53 | `pnpm check:pm-prior-rulings` | 0 |
| 54 | `pnpm check:published-files` | 0 |
| 55 | `pnpm check:refd-timer-probe` | 0 |
| 56 | `pnpm check:registry-log-declared` | 0 |
| 57 | `pnpm check:rest-log-spy-declared` | 0 |
| 58 | `pnpm check:role-word` | 0 |
| 59 | `pnpm check:slot-lookup` | 0 |
| 60 | `pnpm check:sourcemap-no-sources-content` | 0 |
| 61 | `pnpm check:spec-docblock-symbol-anchors` | 0 |
| 62 | `pnpm check:spec-parsed-alias` | 0 |
| 63 | `pnpm check:system-context-census` | 0 |
| 64 | `pnpm check:test-source-alias` | 0 |
| 65 | `pnpm check:tier-file-adoption` | 0 |
| 66 | `pnpm check:undeclared-dep-imports` | 0 |
| 67 | `pnpm check:watch-hint-literal` | 0 |
Local-only families: `pnpm check:dev-prereqs` exit 0; `pnpm
check:skill-frame-freshness` exit 0.
Outside the derivation, left to CI: the 51 artifact-roster families, the
11 wide-population families, the 4 workflow-valued families, the 5
path-scheduled CI jobs and the 5 type-check lanes the tool names.
</details>
## Acceptance notes
- The skill half of #29994 landed in PR #30109; this PR is the remaining
docblock, so `Fixes #29994` closes the card.
- The `[#29987 codemod]` comment above the imports (L20–23) is accurate
as it stands and is left alone.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01L6bhgVugtCCwBs98FeR27P
Co-authored-by: Claude <noreply@anthropic.com>1 parent a839020 commit b8929f4
1 file changed
Lines changed: 9 additions & 5 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
178 | 178 | | |
179 | 179 | | |
180 | 180 | | |
181 | | - | |
182 | | - | |
183 | | - | |
184 | | - | |
185 | | - | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
186 | 190 | | |
187 | 191 | | |
188 | 192 | | |
| |||
0 commit comments