Skip to content

Commit b8929f4

Browse files
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

File tree

‎packages/spec/src/conversions/registry.ts‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -178,11 +178,15 @@ function inApplicationOrder(entries: readonly OrderedConversion[]): readonly Met
178178
* take the same number; they then apply in `id` order. One that must apply
179179
* BEFORE an existing entry takes a number between its neighbours' (`23.5`)
180180
* instead of renumbering them.
181-
* - DEFINE it directly above the definition of the entry that follows it in
182-
* this list, so the conversion defined next after it is that entry. One that
183-
* sorts last is defined after every other conversion, directly above
184-
* `OrderedConversion`. The end of the definitions is one gap too: defining
185-
* every new conversion there conflicts exactly as appending here did.
181+
* - DEFINE it in a module of its own, `./entries/18/<id>.ts`, the file named for
182+
* the conversion's `id` and exporting it by name (`export { <identifier> };`).
183+
* A new file never conflicts.
184+
* - IMPORT it directly above the import of the entry that follows it in this
185+
* list, so the conversion imported next after it is that entry. One that
186+
* sorts last is imported after every other `./entries/18/` import. The
187+
* imports stand where the definitions stood before the split, and their end
188+
* is one gap too: importing every new conversion there conflicts exactly as
189+
* appending here did.
186190
*
187191
* `scripts/conversions-major18-merge.test.ts` holds both rules for every entry
188192
* added after this shape, and proves the merge.

0 commit comments

Comments
 (0)