Repository navigation
refactor(objectql): move the last 28 hand-series private docblocks out of engine.ts with the codemod's third pass (slice 2 of 2) - #30415
Conversation
…t of engine.ts with the codemod's third pass (slice 2 of 2) `node scripts/codemod-split-engine.mjs --hand-docs --write` on main 38717d3, unedited: 10 hand modules, 858 docblock lines, 4 import bindings only a moved docblock linked pruned. The query.groupBy liveness row is repointed at engine-delete-and-aggregate.ts#aggregate, since engine.ts no longer names the key. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Utp6CYHBS7P5hkUQrNHkHZ
|
domain:server#3 · os-bill · session_01Utp6CYHBS7P5hkUQrNHkHZ os-dev report: #30053 slice 2 of 2, PR #30415 (draft), head
|
📓 Docs Drift CheckThis PR changes 2 package(s): 15 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:
⛔ 9 release-owned page(s) also name something this change touched. These are read-only:
What this run could not see
Coarse fallback — 172 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): Which tree this was computed onThis run read A worktree cut from an older # while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 6814ed670ff05d8c05a5bd5fbe25bffec25e5ae9 && git checkout 6814ed670ff05d8c05a5bd5fbe25bffec25e5ae9
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 1e6f54235deaa8b59eef5d249ea1c13375a5b2d0 cc44c59f389deb28effeafb181ab1fdb7d681fc6 && git checkout -B drift-repro 1e6f54235deaa8b59eef5d249ea1c13375a5b2d0 && git merge --no-ff cc44c59f389deb28effeafb181ab1fdb7d681fc6
node scripts/docs-audit/affected-docs.mjs --json 1e6f54235deaa8b59eef5d249ea1c13375a5b2d0
|
|
domain:server#3 · os-bill · session_01Utp6CbPxYq1wQmUNWvMZkC 席位核对ACCEPT · head
|
Requested by Bill · project thread
Fixes #30053
Clause-②: no
Metadata-protocol: none
维护者速读
--hand-docs(不带--modules)在main38717d34上生成:其余 10 个手写模块的 28 块私有 docblock(858 行)从engine.ts搬到函数上。engine.ts12,618 → 11,752 行。生成物未手改,脚本本片未改。另把 liveness 台账query.groupBy一行的证据改指engine-delete-and-aggregate.ts#aggregate。engine.ts从 13,550 行降到 11,752 行。.d.ts相等;objectql 测试 base 550 文件 / 10,967 = head;回滚就是 revert。engine.ts顶部被剪掉的 4 个 import 绑定;②query.json的groupBy一行(第一片时searchFields的同类问题见 main red: spec check:liveness — query/searchFields cites engine.ts, which no longer mentions searchFields after #30341 #30367 / fix(spec): repoint the query.searchFields liveness row at engine-find.ts#expandSearchOnAst #30368,这次check:liveness进了门禁清单,推前已过)。node scripts/codemod-split-engine.mjs --hand-docs --verify --base 38717d34,应看到28 moved (858 lines) across 10 module(s), 36 already moved at base、12618 -> 11752 lines,退出码 0;pnpm --filter @objectstack/spec check:liveness退出码 0。What changes
node scripts/codemod-split-engine.mjs --hand-docs --writeonmain38717d34, unedited. With no--modulesit moves every remaining private hand-series docblock; the 36 the first slice moved are skipped as already moved. The script is unchanged since refactor(objectql): move 36 hand-series private docblocks out of engine.ts with the codemod's third pass (slice 1 of 2) #30341.engine.ts, because a moved docblock's{@link}was their only reader (noUnusedLocalscounts a link):RELATION_FILTER_ID_CAP(its wholeimport { type … }goes),resolveFilterTokens, andcollectInternalReadFields/collectCredentialFields(their whole import goes).packages/spec/liveness/query.json, rowquery.groupBy. The third leg citedengine.ts#aggregate; the body has lived inengine-delete-and-aggregate.tssince the codemod split, and the last mention ofgroupByinengine.ts, a private docblock, moved in this slice. The leg now citesengine-delete-and-aggregate.ts#aggregate, and the note gains one dated sentence. Without itcheck:livenessreds exactly as it did after the first slice (main red: spec check:liveness — query/searchFields cites engine.ts, which no longer mentions searchFields after #30341 #30367).patchon@objectstack/objectqland@objectstack/spec(the ledger ships in the spec package).What moved in this slice (10 modules, 28 docblocks, 858 lines)
engine-driver-options.tsengine-hook-dispatch.tsengine-file-reference-hydration.tsengine-referential-integrity.tsengine-execute-transactions.tsengine-query-lowering.tsengine-realtime-publish.tsengine-count-aggregate.tsengine-validation-messages.tsengine-reference-name-visible.tspackages/objectql/src/engine.ts: 12,618 → 11,752 lines.After both slices
All 64 private hand-series stubs that had a docblock now keep it beside their body. On the class stay: the 20 public stubs (their docblock is the contract),
validationMessageContext(its function already carries a richer docblock; merging two is an edit, not a move) andnoteAdmittedValueShapeViolation(no docblock).--hand-docson this head plans 0 moves.Verification
All at head
cc44c59funless stated.--hand-docs --verify --base 38717d34: exit 0.28 moved (858 lines) across 10 module(s), 36 already moved at base; engine.ts 12618 -> 11752 lines; undoing every move rebuilds the base, undone the same way, for engine.ts and its 21 hand module(s) byte-for-byte, once the 4 import binding(s) only a moved docblock linked are pruned.--writeon a stale checkout ofmain(f672e0dc, the sameengine.tsand hand modules) printed the same output tree sha2566c71d47c…7b38as the run on38717d34..d.ts.packages/objectql/distbuilt at base38717d34twice and at head twice. Base 1 = base 2 and head 1 = head 2, byte for byte. Base against head:coreandindex(.d.tsand.d.mts) are byte-identical;util-HASHhas 193/193 statements and 334/334 private members, and its public surface is EQUAL. The raw difference is the 858 lines of moved private docblocks.scripts/ablation-replace.mjs, each restored to the HEAD blob: one character changed in a moved docblock (inAfterAbortUnit's, inengine-hook-dispatch.ts) →--verifyexits 1 naming the line; one character changed in a docblock that stays on the class (checkDriversHealth) → exits 1 naming the line. The battery's own ablations ran on refactor(objectql): move 36 hand-series private docblocks out of engine.ts with the codemod's third pass (slice 1 of 2) #30341 and the script is unchanged;--self-test105 cases pass.test: base38717d34550 files / 10,967 passed, head 550 / 10,967. objectqltypecheck: exit 0.pnpm --filter @objectstack/spec check:liveness: exit 1 before thegroupByrepoint (only that row), exit 0 after. Separately, all 36 ledger rows that citeengine.tswere read: each one's key (camelCase or snake_case) is still named inengine.tson this head.dispatch-gates --commandsderived 62 commands (check:livenessamong them), each run after a fullturbo run build --filter='!@objectstack/docs'(exit 0). All 62 exit 0;--ran: 62 derived, 62 run, 0 NOT-MEASURED.Acceptance notes
{@link}s inside a moved docblock now sit in the hand module and are not rewritten.protocol.tshalf of refactor: move the private docblocks of the hand-series stubs into their hand modules — about 1,900 lines off engine.ts (86 stubs) and about 4,000 off protocol.ts (157 stubs) #30053 (157 stubs, about 4,000 lines) is not in this card's claim. The seat files it separately once its own serial constraints clear.Human Minimum
packages/specholds no runtime logic. (a ledger row only)main, one pull request. (the designated thread branch, recreated frommain; second of two slices)packages/spectouched: its generated artifacts are regenerated and committed. (a liveness row; nothing generated reads it)content/docs/references/,packages/*/CHANGELOG.mdorcontent/docs/releases/.🤖 Generated with Claude Code
https://claude.ai/code/session_01Utp6CYHBS7P5hkUQrNHkHZ