Skip to content

chore(devx): migrate the 7 freed scripts/** line citations to file-level anchors (#15809, residual 2 of 3) - #16338

Merged
baozhoutao merged 1 commit into
mainfrom
claude/issue-15809-scripts-line-citations-residual
Sep 6, 2026
Merged

baozhoutao merged 1 commit into
mainfrom
claude/issue-15809-scripts-line-citations-residual

Conversation

@claude

@claude claude Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Part of #15809.

Second dispatch of the scripts/** unresolvable-citation follow-up (PR #16301 residual). Migrates the 7 of the 15-citation residual whose holding files freed since: check-docs-section-name.mjs and docs-audit/affected-docs.mjs (PR #16300, merged 13:49Z), check-type-check-coverage.mjs (PR #16295, merged 13:49Z). ⛔ Does not touch the 8 still held by open PRs #16215 and #16202.

Enumeration (node scripts/check-scripts-symbol-anchors.mjs --list-unresolvable)

before after
unresolvableLineCitation 15 8

Per-file migration (PR #15806 / #16301 method — file-level anchor, number kept beside it as data, no digit repaired or repointed)

file citations resolution
scripts/check-docs-section-name.mjs 3 concept.mdx:426 → content/docs/protocol/objectui/concept.mdx (only tracked file of that basename); doc-pages.mdx:257 → content/docs/ui/doc-pages.mdx (only tracked file of that basename); forms.mdx:183 → content/docs/ui/forms.mdx (basename is ambiguous — two tracked files share it — but only this one has a line 183 carrying the cited "sections": [/* … */] shape; the other, content/docs/capabilities/forms.mdx, is 30 lines long)
scripts/docs-audit/affected-docs.mjs 3 all three rest-server.ts citations → packages/rest/src/rest-server.ts (the only tracked file of that name)
scripts/check-type-check-coverage.mjs 1 engine.test.ts:2547/2577 → packages/services/service-automation/src/engine.test.ts (named directly by the surrounding prose, "service-automation's note")

Zero citations were ambiguous; every resolution above was reachable either because the basename is unique in the tree or because the surrounding prose already named the owning package/file.

scripts/check-scripts-symbol-anchors.mjs's header prose was also updated to record this round's dated reading (residual 15 → 8, both by exclusion) beside the first round's, following the precedent PR #16301 set for a header stating its residual as a dated reading rather than a stale live claim.

Residual (8, unchanged scope — not touched here)

None is an ambiguity. judgeUntrackedLineAnchors stays false per the #15809 fence (flips only when the residual reads 0 and a self-test pins the flip).

Corpus counts after (node scripts/check-scripts-symbol-anchors.mjs)

2898 anchors across 223 scripts resolve — 27 symbol (27 declaration, 0 literal), 2871 file-level,
0 cross-repo, 1 exempt, 2 continuation. 0 line anchors on tracked targets survive
(8 citations name no tracked file and are not judged; 0 dated allowance finding(s)).

(Before, same tree: 2886 anchors, 2859 file-level, 15 unresolvable.)

Gates, pinned to a5fb43463

turbo ls --affected against the branch's base (3e270d4e2) returns 0 packages — every edit is prose inside scripts/** audit/gate scripts themselves, no package's src/.

Byte-identical --self-test output before/after for every gate whose comment prose was edited (compared against a second worktree pinned to the same base 3e270d4e2):

  • scripts/check-docs-section-name.mjs --self-test — identical (85 cases)
  • scripts/docs-audit/affected-docs.mjs --self-test — identical (585 cases)
  • scripts/check-type-check-coverage.mjs --self-test — identical
  • scripts/check-scripts-symbol-anchors.mjs --self-test / plain run — residual count moved 15 → 8 as intended, every other line (2898 vs 2886 anchors etc.) reflects the new file-level anchors added, not a behavioural change

node scripts/pm/dispatch-gates.mjs --changed --commands --repo objectstack-ai/objectstack derived 38 commands for this diff; 37 are EXIT 0. The one exception, check:type-check-debt, is a legitimate PREREQUISITE NOT MET (exit 3, not a finding) -- its --re-measure mode needs the full workspace build closure on disk (pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*'), which this scripts/**-only diff (0 affected packages per turbo ls --affected) does not warrant; the gate's own text says explicitly that measuring without the closure "would not fail, it would silently measure a DIFFERENT WORLD" and must not be entered anywhere. The plain check:type-check-coverage (same script, ledger-comparison mode) passed EXIT 0 in the same run.

skip-changeset applied — no .changeset/*.md needed (no package publishes; every changed line is comment prose inside scripts/**), no content/docs/releases/ touched.


Generated by Claude Code

…vel anchors

Second round of the scripts/** unresolvable-citation migration PR #16301
started. Two of the six held files freed since that PR landed --
check-docs-section-name.mjs and docs-audit/affected-docs.mjs (PR #16300),
check-type-check-coverage.mjs (PR #16295) -- so their 7 citations migrate
now by the same method: the file named as a file-level anchor, the number
kept beside it as data, no digit repaired or repointed.

- check-docs-section-name.mjs: concept.mdx:426, doc-pages.mdx:257 and
  forms.mdx:183 each resolve to exactly one tracked file under
  content/docs/** (forms.mdx is ambiguous by basename alone -- two files
  share it -- but only content/docs/ui/forms.mdx has a line 183 carrying
  the cited "sections": [/* ... */] shape).
- check-type-check-coverage.mjs: engine.test.ts:2547/2577 resolves to
  packages/services/service-automation/src/engine.test.ts, named by the
  surrounding prose ("service-automation's note").
- docs-audit/affected-docs.mjs: three rest-server.ts citations resolve to
  packages/rest/src/rest-server.ts, the only tracked file of that name.

The corpus residual (scripts/check-scripts-symbol-anchors.mjs
--list-unresolvable) drops from 15 to 8, all 8 still held by open PRs
(#16215, #16202) -- none an ambiguity. judgeUntrackedLineAnchors stays
false per the #15809 fence (flips only at residual zero). Header prose
updated to record both dated readings.

Part of #15809.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vbw3RPgdtqesx4azk9SbW8
@claude claude Bot added the skip-changeset PR has no user-facing published change; bypasses the changeset gate label Sep 6, 2026
@github-actions github-actions Bot added the size/s label Sep 6, 2026
@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see
  • a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 3e270d4e296368f6600d71fcec9902f3a14c1698 → packageMentionDocs.

@baozhoutao
baozhoutao marked this pull request as ready for review September 6, 2026 15:01
@baozhoutao
baozhoutao enabled auto-merge September 6, 2026 15:01
@baozhoutao
baozhoutao added this pull request to the merge queue Sep 6, 2026
Merged via the queue into main with commit 4108347 Sep 6, 2026
43 checks passed
@baozhoutao
baozhoutao deleted the claude/issue-15809-scripts-line-citations-residual branch September 6, 2026 15:29
akarma-synetal pushed a commit to akarma-synetal/framework that referenced this pull request Sep 28, 2026
…ors (objectstack-ai#19200)

Third round of the `scripts/**` unresolvable-citation migration (PRs
objectstack-ai#15806 and objectstack-ai#16338 were rounds one and two), **devx-lane slice only**.

`scripts/check-scripts-symbol-anchors.mjs` registers `scripts/**` `.mjs`
comment prose as a symbol-anchor corpus with `judgeUntrackedLineAnchors:
false`, so a citation naming no tracked file is seen, counted and
enumerated — and judged by nothing. This PR migrates **six** of those,
by the gate's own repair form (its header, under `[line-anchor]`):

> ANCHOR FORM: name the file as a file-level anchor and put the number
beside it as data

Not one digit is repaired or repointed. Every number that was part of an
anchor is still on its page, as data.

## The six, and why each target is unambiguous

| site | citation | resolves to |
|---|---|---|
| `scripts/check-changeset-no-major.mjs` | `date-range-presets.ts:101` |
`packages/spec/src/data/date-range-presets.ts` |
| `scripts/cross-package-test-inputs.mjs` | `:102`, `:92`, `:484-485`
(continuations) |
`packages/spec/src/shared/retired-key-migrate-sentence.test.ts` |
| `scripts/ts-parse.mjs` | `tenant-audit-census.mjs:459`, `:723` |
`scripts/tenant-audit-census.mjs` |

- **`date-range-presets.ts`** — one tracked file of that basename
(`date-range-presets.test.ts` is a different basename), and line 101 is
inside the TSDoc block the surrounding prose describes.
- **`retired-key-migrate-sentence.test.ts`** — one tracked file, and all
three numbers still land on what the prose says they do:
`PUBLISHED_SKILLS_ROOT` on line 102, the "plus every `.md` file under
`skills/`" sentence on line 92, and the `skills:`-prefixed `files.push`
on lines 484-485.
- **`tenant-audit-census.mjs`** — one tracked file of that basename
(`check-tenant-audit-census.mjs` is a different basename). It carries
both cited constructs, the `.replace(/\s+/g, ' ')` collapse and the
synthetic `type CensusReceiver = ...` alias; both have drifted off the
cited lines, which is precisely why those lines are kept as dated data
rather than repointed.

## The gate's own dated record is corrected in the same edit

Both prior rounds did this, and it had gone stale in a way that matters:
the header claimed a residual of **8** and named holders (PRs objectstack-ai#16215,
objectstack-ai#16202) that have since merged, while the live command printed **18**.

That regrowth — 8 back up to 18 between rounds, because gate-header
prose written in the interval added citations faster than round two
removed them — is the most load-bearing reading here, and the header now
says so. **This is not a burn-down; it is a quantity that grows.**

## Acceptance, measured on this branch

```
node scripts/check-scripts-symbol-anchors.mjs --list-unresolvable   EXIT 0   18 -> 12
node scripts/check-scripts-symbol-anchors.mjs --self-test           EXIT 0
node scripts/check-scripts-symbol-anchors.mjs                       EXIT 0
```

Row-by-row `diff` of the before and after listings: the **only** lines
removed are the six above, plus the summary line changing from `18 ...
10 bare-filename, 5 continuation, 3 directory-qualified` to `12 ... 8
bare-filename, 1 continuation, 3 directory-qualified`. The other twelve
rows are byte-identical and still listed.

## What is deliberately NOT here

- **`judgeUntrackedLineAnchors` stays `false`.** Whether it should flip
is the open question this card exists to put in front of triage, and it
is now a sharper question than a counting one — see below.
- **The remaining twelve rows are untouched**, every one of them on
another seat's surface: `scripts/pm/check-governed-merges.mjs`,
`scripts/pm/check-skill-line-ratchet.mjs`,
`scripts/pm/check-prior-rulings.mjs`,
`scripts/pm/check-half-states.mjs`,
`scripts/pm/check-widening-tells.mjs` (governed-surface and `pm` patrol
instruments) and `scripts/check-spec-docblock-symbol-anchors.mjs`
(SUBJECT is `packages/spec` docblocks). No card is filed for them here.

## Open question for triage

A flag that flips at residual zero flips into a gate that reds on the
**next** author's first bare citation — and the 8 -> 18 regrowth
measured above says there will be a next author, soon. So what the flip
needs is a **remedy for an unbindable abbreviation** (a bare `engine.ts`
a resolver cannot bind to one of several files of that name), not a
smaller number. Reaching zero and flipping the same day would hand the
repo the permanently-red gate its own header says it retired.

Part of objectstack-ai#15809

---
_Generated by [Claude
Code](https://claude.ai/code/session_017ef78bLdybu3AffehKkhfk)_

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/s skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants