fix(docs-audit): derive package roots from the filesystem, not a special-cased regex - #4206
Merged
Merged
Conversation
…ial-cased regex (#4162) The drift mapper special-cased only `packages/plugins/*`, so the 30 packages nested under the other six container dirs collapsed into their container — whose missing package.json killed the npm-name matching arm. A doc naming `@objectstack/service-automation` but never the repo path was a guaranteed miss (`automation/flows.mdx` on a service-automation- only change). The root is now the deepest ancestor with a package.json, with no hardcoded container list to drift out of sync. Also from the issue thread: `<packageRoot>/scripts/**` is build tooling, not documented behaviour, and no longer counts as an implementation change (#4183); `package.json` and `src/scripts/**` stay counted. Both the derivation and the classifiers are now pinned by `--self-test`. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J2x8Tie9WT1VgWFifqMKrR
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
size/m
documentation
Contributor
📓 Docs Drift CheckNo hand-written docs reference the 0 changed package(s). ✅ |
os-zhuang
marked this pull request as ready for review
July 30, 2026 15:22
os-zhuang
added a commit
that referenced
this pull request
Jul 31, 2026
…never got (#4219) The drift comment on #4161 was computed by the mapper bug #4206 fixed: the service-automation change collapsed to `packages/services`, so these four docs were attributed to the wrong package — and a service-automation-only diff would have reported none of them. Re-derived with the fixed mapper and audited against the implementation. flows.mdx carries the #4161 axis itself: a `runAs:'user'` run that resolved no trigger user has its data operations refused. Also documents `node.type` as an open string checked against the live registry (ADR-0018), the script executor as naming a callable with logger-backed `email`/`slack` markers, the `.strict()` shells, and six previously undocumented node keys. implementation-status.mdx gains the real `/api/v1` route prefixes, the memory driver's actual `InMemoryDriver.supports` matrix, and the ADR-0090 D3 `Role` -> `Position` rename — which ratchets the role-word baseline down by one, so that gate-mandated update ships here too. Gates: docs build, check:doc-authoring, check:role-word, check:nul-bytes, check:release-notes, check:skill-examples (198 prose examples). Claude-Session: https://claude.ai/code/session_01J2x8Tie9WT1VgWFifqMKrR Co-authored-by: Claude <noreply@anthropic.com>
This was referenced Jul 31, 2026
os-zhuang
added a commit
that referenced
this pull request
Jul 31, 2026
#4248) (#4262) 20 of the 49 publishable packages declared no `files` field, so npm fell back to packing the whole package directory. `npm pack --dry-run` on @objectstack/plugin-webhooks listed 21 files -- 15 under src/, three of them unit tests, plus the build-time scripts/i18n-extract.config.ts. dist/ lands on top of that at publish time rather than instead of it. Each now declares ["dist", "README.md"], matching the 29 packages that already did. Nothing a consumer imports moves: every main / types / exports target in all 20 already resolved inside dist/. The other half is the gate. check:published-files (wired into the always-required lint job) holds every non-private workspace package to four invariants: DECLARED, SUFFICIENT (covers every entry point, so tightening a whitelist cannot ship a package that fails to resolve), MINIMAL (admits no test, test-harness config or build script), and REGISTERED (anything beyond dist + README.md carries a reason, reconciled in both directions). MINIMAL also closes an assumption #4206 rested on: that no package publishes scripts/ as runtime code held, but it held by hand-checking three packages. It is now checked on every PR.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #4162.
Problem
affected-docs.mjsderived changed-package roots with a regex that special-cased onlypackages/plugins/*. The 30 packages nested under the other six container directories (services/,connectors/,apps/,qa/,triggers/,adapters/) collapsed into their container, whose missingpackage.jsonleftname = null— so the npm-name matching arm never fired for them. Any doc that names@objectstack/service-automationbut never the repo path was a guaranteed miss (content/docs/automation/flows.mdxis one), the exact direction the tool promises to avoid ("over-inclusion is preferred over misses").Fix
package.json, resolved from the filesystem. No hardcoded container list replaces the special case — a list would silently fail again on container dir number eight (排查「手抄 spec 清单 + "keep in sync" 注释」模式:一天内确认三例,全部曾静默漂移 #3786's pattern). A deleted package falls back to the coarsepackages/<x>token so path matching still works.<packageRoot>/scripts/**is build/verification tooling and no longer counts as an implementation change (feat(spec):check:generated— report every stale artifact in one run #4183 flagged 106 docs for a diff whose only code change was a new check script). Kept deliberately narrow:package.jsonandsrc/scripts/**stay counted. Publication check done — no package'sfilesallowlist shipsscripts/; three plugins ship a lonei18n-extract.config.tsonly for lack of afilesfield (tooling, not runtime).--self-testnow pins the derivation and both classifiers (32 hermetic cases via an injected fake tree), closing the guard-of-the-guard hole — the original self-test pinned onlyisTestFile. Includes the issue's two invariants: a container directory must never come out as a package root;packages/x/package.jsonis implementation whilepackages/x/scripts/y.tsis not.scriptFilesSkippedalongsidetestFilesSkippedin--json.Verified against real history
service-automation+spec)packages/services@objectstack/service-automation;flows.mdxnow hits via the right packageservice-automation-only changepackages/servicespath token),flows.mdxabsentflows.mdxincludedpackage.jsonregistration)package.jsonchange keepspackages/speccounted, by design) + explicit "1 tooling script(s) excluded" notenode scripts/docs-audit/affected-docs.mjs --self-test→ 32 cases pass; the drift workflow already runs it before computing the mapping.🤖 Generated with Claude Code
https://claude.ai/code/session_01J2x8Tie9WT1VgWFifqMKrR
Generated by Claude Code