Skip to content

ci(spec): check:skill-examples 拒绝 os:check 块内的裸 any (#5943) - #6049

Merged
os-zhuang merged 2 commits into
mainfrom
claude/issue-5943-skill-examples-any-gate
Aug 7, 2026
Merged

ci(spec): check:skill-examples 拒绝 os:check 块内的裸 any (#5943)#6049
os-zhuang merged 2 commits into
mainfrom
claude/issue-5943-skill-examples-any-gate

Conversation

@os-zhuang

@os-zhuang os-zhuang commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Fixes #5943

前提复核(先于实现)

origin/main(739f496)实测,issue 前提成立:

  • packages/spec/scripts/check-skill-examples.ts 已有两道反空转断言 —— orphan marker、零块 fail() —— 但没有任何 any 相关检查;
  • 全库被标记块实测 208 块,其中裸 any 入参 3 条,全在同一块内。

这道门补的是什么

os:check 标记是作者的声明:「这段应当能编译」。块内一旦出现裸 any,声明即空转 —— 该值上的每一次属性访问都不再被检查,tsc 全绿却什么也没证明。#5720 是实测标本:两段被标记的 hook 示例写着 beforeUpdate(ctx: any),读的 ctx.services 在 hook 上下文里根本不存在(引擎逐键构造九键、沙箱十键均不产),照抄的 hook 会因可选链短路无条件抛 PERMISSION_DENIED;同一个 any 此前还掩盖了 #5605ctx.session?.positions

实现落在 issue 建议的位置:extractFromFile 之后、写 build dir 之前,对每个被标记块做 AST 扫描(ts.createSourceFile),报到 页面:行:列 并给出两条处方。

三个「待承接方实测后定」的细节,按实测定下

1. 范围 —— 入参 + 断言 + 局部变量,但只管「本身就是 any」的位置。

判定条件是 parent.type === node:参数、变量、属性、返回类型、类型别名,以及 as any / satisfies any / 尖括号断言。嵌套 any(Record< string, any >any[]Promise< any >)刻意不报 —— 与 check-exported-any.ts 划的是同一条零误报线(该脚本原文:「a type with any somewhere inside it is NOT flagged … drawing the line here keeps the gate at zero false positives so red keeps meaning broken」)。

把断言与局部变量一并纳入,不是为了对称,而是因为只管入参的规则会被「参数标红时作者顺手做的那一步编辑」绕过:把 any 下移一行(const c: any = ctx)或塞进访问((ctx as any).services),缺陷分毫未动而门重新变绿。实测代价为零:全库 208 块里 as any 0 条、const/let: any 0 条。

2. 既有基线 —— 3 条,一次改净,不建棘轮。

3 条全在 content/docs/protocol/kernel/lifecycle.mdx:515/516/524,同一个生成式迁移示例。该块逐字复现 os generate migration 的 Knex 输出(packages/cli/src/commands/generate.ts 确实产出 up(db: any)(table: any)),且不 import 任何 @objectstack/spec —— 给它标注类型会让文档对 CLI 的实际产物说谎,typecheck 它也证明不了任何 spec 契约。故按门自己给的处方二处理:去掉该块的 os:check 标记(标记是渲染为空的注释,页面正文一字未改)。余下 207 块全部编译通过,无棘轮文件、无豁免名单 —— 基线是零并保持为零。

3. --self-test —— 红/绿双向,外加误报边。

跑真实的 extractFromFile,三个 fixture:

  • 红(docs .mdx):[docs] runtime-services 的 hook 示例在教 ctx.services —— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 的原形 beforeUpdate(ctx: any),断言恰好 1 条命中、where === 'parameter \ctx`'`、页面行号字面量 9;
  • 红(skills .md):四个非入参位置(as any / const loose: any / type Loose = any / 返回 any)各一条,行号逐条钉死;
  • 绿:同一个函数改标真实 HookContext 后 0 条,并同块塞入 Record< string, any >any[]'any' 字面量联合、注释里的英文 "any" —— 四种形状真实存在于语料,报任何一个都会逼出一次无缺陷的全库改写;同文件另有一个未标记块写着 ctx: any,断言只提取到 1 块(门只审作者标记过的东西)。

页面行号换算(bodyStartLine + line - 1)被钉成字面量而非重算 —— 那是会静默漂移的一环,指错行的诊断比没有诊断更糟。

用 AST 而非正则,是因为语料是散文:'any' 出现在字符串字面量联合里、JSDoc 里、以及注释中的普通英文。实测正则按行扫会报出 3 条这类行,无一是类型标注

包脚本改为 --self-test && audit,与 check:exported-any / check:dual-source-exports 一致(CI 该段的注释原文就是「Self-tests first, like exported-any」)。

反向验证(方向先判、后跑)

预判:。在改文档之前、门刚写完时对真实语料跑,应当报出探针量到的那 3 行。实跑逐字命中:

✗ os:check block(s) annotate values `any` — the marker claims
"this compiles" while every property access on that value goes unchecked:

  content/docs/protocol/kernel/lifecycle.mdx:515:30  parameter `db`
  content/docs/protocol/kernel/lifecycle.mdx:516:57  parameter `t`
  content/docs/protocol/kernel/lifecycle.mdx:524:32  parameter `db`

去掉标记后转绿:✅ 207 prose examples type-check against @objectstack/spec

验收对照

issue 验收项 结果
os:check 块把入参标 any ⇒ 门红,报页面 + 行号 + 处方 ✅ 上方实跑输出(含列号)
现存块全绿 ✅ 207 块(208 减去撤标记的那块)
--self-test 覆盖红/绿两个方向 ✅ 红 5 条命中 + 绿 0 误报 + 行号字面量

Changeset:走 skip-changeset 标签,不是空 changeset

派单给的先例是 .changeset/per-package-typecheck-coverage.md 式的空 frontmatter changeset。实测后没有照搬,因为该先例早于 #5292 对这条处方的修正:pr-automation.ymlchangeset-check 现在把三条路排了优先级,并把空 frontmatter changeset 明确降为 LAST RESORT,理由是它与标签不等价 ——

本 PR 确实不发布任何东西:packages/specfiles 字段(dist / json-schema / liveness / prompts / src/**/*.zod.ts / …)不含 scripts/,改动只有一个开发脚本、package.jsonscripts 字段接线,以及一行渲染为空的文档注释。故按工作流自己的处方走路线 2:已在 PR 建好后立即打上 skip-changeset(与既有 size/m 做并集写入,不覆盖 bot 刚打的标签),并撤下先写的那份空 changeset。

本地验证

  • check:skill-examples(自测 + 审计):✅ 207 prose examples type-check against @objectstack/spec
  • pnpm --filter @objectstack/spec typecheck:通过(tsc --noEmit + check:test-typecheck)
  • 脚本本体单独 strict 编译:scripts/** 不在两个 tsconfig project 内,故另跑 tsc --ignoreConfig --strict 单文件校验,0 error
  • pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2:325 files / 8308 tests 全通过
  • pnpm exec eslint packages/spec/scripts/check-skill-examples.ts:0
  • pnpm check:doc-authoring:362 files clean
  • node scripts/check-nul-bytes.mjs:OK(5779 tracked text files,无裸控制字节)

不在本单范围

#5837(spec artifact 分片)正在改读三个生成产物的 packages/spec/scripts/**;本文件不读 authorable-surface.json / json-schema.manifest.json / api-surface.json 中的任何一个,build-schemas.ts / build-docs.ts / .gitattributes 一律未碰,确认无交叠。

🤖 Generated with Claude Code

https://claude.ai/code/session_014wsZeReNTqiceBfLb5Pyf5

os:check 标记是作者的声明「这段应当能编译」。块内一旦出现裸 any,该声明即为空转:
该值上的每一次属性访问都不再被检查,tsc 全绿却什么也没证明。#5720 是实测标本 ——
两段被标记的 hook 示例写着 beforeUpdate(ctx: any),读的 ctx.services 在 hook 上下文
里根本不存在(引擎逐键构造九键、沙箱十键均不产),照抄的 hook 会无条件抛
PERMISSION_DENIED;同一个 any 此前还掩盖了 #5605 的 ctx.session?.positions。

现在提取阶段(extractFromFile 之后、写 build dir 之前)对每个被标记块做 AST 扫描,
对「本身就是 any」的标注失败:参数、变量、属性、返回类型、类型别名,以及
as any / satisfies any / 尖括号断言,报到 页面:行:列 并给出两条处方。断言与局部变量
一并纳入,不是为了对称:只管入参的规则会被「参数标红时作者顺手做的那一步编辑」
绕过 —— 把 any 下移一行(const c: any = ctx)或塞进访问((ctx as any).services)。
嵌套 any(Record<string, any> / any[] / Promise<any>)刻意不报,与
check-exported-any.ts 划的是同一条零误报线。

基线为一处三条:content/docs/protocol/kernel/lifecycle.mdx 的生成式迁移示例逐字复现
os generate migration 的 Knex 输出(packages/cli/src/commands/generate.ts 产出
up(db: any) / (table: any)),且不 import 任何 @objectstack/spec —— 给它标注类型会让
文档对 CLI 的实际产物说谎,故按处方二去掉其 os:check 标记;余下 207 块全部编译通过。

--self-test 红/绿双向覆盖,并把 页面行号换算(bodyStartLine + line - 1)钉成字面量;
包脚本改为「先自测再审计」,与 check:exported-any / check:dual-source-exports 一致。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014wsZeReNTqiceBfLb5Pyf5
@vercel

vercel Bot commented Aug 6, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
objectstack Ignored Ignored Aug 6, 2026 3:43pm

Request Review

@github-actions github-actions Bot added the size/m label Aug 6, 2026
@os-zhuang os-zhuang added the skip-changeset PR has no user-facing published change; bypasses the changeset gate label Aug 6, 2026 — with Claude
本 PR 不发布任何东西:`packages/spec` 的 `files` 不含 `scripts/`,改动只有一个开发
脚本、`package.json` 的 `scripts` 字段接线,以及一行渲染为空的文档注释。

pr-automation.yml 的 changeset-check 在 #5292 之后把三条路排了优先级,并把空
frontmatter changeset 明确降为 LAST RESORT:它与标签不等价 —— 标签是门级豁免、不
向 changesets/action 提供任何输入;空 changeset 是真实输入,当待处理集合全为空时
action 走 "hasChangesets && !hasNonEmptyChangesets" 分支,打印 "All changesets are
empty; not creating PR" 后 0 秒返回,Release 仍然全绿(#4898 即以此静默卡住
17.0.0-rc.2)。且空 changeset 不指名任何包,正文到不了任何 CHANGELOG。

故按该工作流自己的处方走路线 2。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014wsZeReNTqiceBfLb5Pyf5
@github-actions github-actions Bot added documentation Improvements or additions to documentation dependencies Pull requests that update a dependency file tooling labels Aug 6, 2026

Copy link
Copy Markdown
Contributor Author

CI 红签名判读(PM 座位,会话 session_014wsZeReNTqiceBfLb5Pyf5,15:5xZ):

15:42–15:47Z 窗口内 4 个 check 红(No other open PR may claim the same issue / Flag docs affected / Validate Package Dependencies / Check Changeset),抽验 3 个 job 日志签名逐字一致:runner 引导阶段 Failed to resolve action download info — Service Unavailable / Bad Gateway,重试 3 次后放弃,未执行到任何仓库代码 ⇒ GitHub Actions 平台瞬态,与本 PR 内容无关。

处置:4 个 run 的失败 job 已原样重投(201 已入队)。若重投再次同签名失败 = 平台故障未过,继续等窗口再投,⛔ 不改代码;出现任何其它签名才是真问题,按新问题诊断。@dev:无需对这批红做任何改动。


Generated by Claude Code

@github-actions

github-actions Bot commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec.

112 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

  • content/docs/ai/agents.mdx (via @objectstack/spec)
  • content/docs/ai/skills-reference.mdx (via @objectstack/spec)
  • content/docs/ai/skills.mdx (via @objectstack/spec)
  • content/docs/api/client-sdk.mdx (via @objectstack/spec)
  • content/docs/api/environment-routing.mdx (via @objectstack/spec)
  • content/docs/api/error-catalog.mdx (via @objectstack/spec)
  • content/docs/api/error-handling-client.mdx (via @objectstack/spec)
  • content/docs/api/error-handling-server.mdx (via @objectstack/spec)
  • content/docs/api/index.mdx (via @objectstack/spec)
  • content/docs/automation/approvals.mdx (via @objectstack/spec)
  • content/docs/automation/connectors.mdx (via @objectstack/spec)
  • content/docs/automation/flows.mdx (via @objectstack/spec)
  • content/docs/automation/hook-bodies.mdx (via packages/spec)
  • content/docs/automation/hooks.mdx (via @objectstack/spec)
  • content/docs/automation/index.mdx (via @objectstack/spec)
  • content/docs/automation/webhooks.mdx (via @objectstack/spec)
  • content/docs/automation/workflows.mdx (via @objectstack/spec)
  • content/docs/concepts/architecture.mdx (via @objectstack/spec)
  • content/docs/concepts/design-principles.mdx (via packages/spec)
  • content/docs/concepts/index.mdx (via @objectstack/spec)
  • content/docs/concepts/metadata-driven.mdx (via @objectstack/spec)
  • content/docs/concepts/metadata-lifecycle.mdx (via packages/spec)
  • content/docs/concepts/north-star.mdx (via @objectstack/spec)
  • content/docs/data-modeling/analytics.mdx (via @objectstack/spec)
  • content/docs/data-modeling/drivers.mdx (via @objectstack/spec)
  • content/docs/data-modeling/external-datasources.mdx (via @objectstack/spec)
  • content/docs/data-modeling/field-types.mdx (via @objectstack/spec)
  • content/docs/data-modeling/fields.mdx (via @objectstack/spec)
  • content/docs/data-modeling/formulas.mdx (via @objectstack/spec)
  • content/docs/data-modeling/index.mdx (via @objectstack/spec)
  • content/docs/data-modeling/objects.mdx (via @objectstack/spec)
  • content/docs/data-modeling/queries.mdx (via @objectstack/spec)
  • content/docs/data-modeling/schema-design.mdx (via @objectstack/spec)
  • content/docs/data-modeling/seed-data.mdx (via @objectstack/spec)
  • content/docs/data-modeling/validation-rules.mdx (via @objectstack/spec)
  • content/docs/data-modeling/validation.mdx (via @objectstack/spec)
  • content/docs/deployment/cli.mdx (via @objectstack/spec)
  • content/docs/deployment/tenancy-modes.mdx (via @objectstack/spec)
  • content/docs/deployment/troubleshooting.mdx (via @objectstack/spec)
  • content/docs/deployment/validating-metadata.mdx (via @objectstack/spec)
  • content/docs/getting-started/build-with-claude-code.mdx (via @objectstack/spec)
  • content/docs/getting-started/common-patterns.mdx (via @objectstack/spec)
  • content/docs/getting-started/examples.mdx (via @objectstack/spec)
  • content/docs/getting-started/quick-reference.mdx (via @objectstack/spec)
  • content/docs/getting-started/quick-start.mdx (via @objectstack/spec)
  • content/docs/getting-started/your-first-project.mdx (via @objectstack/spec)
  • content/docs/kernel/cluster.mdx (via @objectstack/spec)
  • content/docs/kernel/contracts/auth-service.mdx (via packages/spec)
  • content/docs/kernel/contracts/cache-service.mdx (via packages/spec)
  • content/docs/kernel/contracts/data-engine.mdx (via @objectstack/spec)
  • content/docs/kernel/contracts/index.mdx (via @objectstack/spec)
  • content/docs/kernel/contracts/metadata-service.mdx (via packages/spec)
  • content/docs/kernel/contracts/storage-service.mdx (via @objectstack/spec)
  • content/docs/kernel/index.mdx (via packages/spec)
  • content/docs/kernel/runtime-services/data-service.mdx (via @objectstack/spec)
  • content/docs/kernel/runtime-services/email-service.mdx (via packages/spec)
  • content/docs/kernel/runtime-services/examples.mdx (via @objectstack/spec)
  • content/docs/kernel/runtime-services/index.mdx (via packages/spec)
  • content/docs/kernel/runtime-services/queue-service.mdx (via packages/spec)
  • content/docs/kernel/runtime-services/sharing-service.mdx (via @objectstack/spec)
  • content/docs/kernel/runtime-services/sms-service.mdx (via packages/spec)
  • content/docs/kernel/runtime-services/storage-service.mdx (via @objectstack/spec)
  • content/docs/kernel/services-checklist.mdx (via @objectstack/spec)
  • content/docs/kernel/services.mdx (via @objectstack/spec)
  • content/docs/permissions/authorization.mdx (via @objectstack/spec)
  • content/docs/permissions/permission-sets.mdx (via @objectstack/spec)
  • content/docs/permissions/permissions-matrix.mdx (via @objectstack/spec)
  • content/docs/permissions/positions.mdx (via @objectstack/spec)
  • content/docs/permissions/rls.mdx (via @objectstack/spec)
  • content/docs/permissions/sharing-rules.mdx (via @objectstack/spec)
  • content/docs/plugins/adding-a-metadata-type.mdx (via @objectstack/spec)
  • content/docs/plugins/development.mdx (via @objectstack/spec)
  • content/docs/plugins/index.mdx (via @objectstack/spec)
  • content/docs/plugins/packages.mdx (via @objectstack/spec)
  • content/docs/protocol/backward-compatibility.mdx (via @objectstack/spec)
  • content/docs/protocol/diagram.mdx (via packages/spec)
  • content/docs/protocol/kernel/config-resolution.mdx (via @objectstack/spec)
  • content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/spec)
  • content/docs/protocol/kernel/i18n-standard.mdx (via @objectstack/spec)
  • content/docs/protocol/kernel/index.mdx (via @objectstack/spec)
  • content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/spec)
  • content/docs/protocol/kernel/plugin-spec.mdx (via @objectstack/spec)
  • content/docs/protocol/knowledge.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/index.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/query-syntax.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/schema.mdx (via @objectstack/spec)
  • content/docs/protocol/objectql/security.mdx (via packages/spec)
  • content/docs/protocol/objectql/state-machine.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/actions.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/concept.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/index.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/layout-dsl.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/record-alert.mdx (via @objectstack/spec)
  • content/docs/protocol/objectui/widget-contract.mdx (via @objectstack/spec)
  • content/docs/releases/implementation-status.mdx (via @objectstack/spec)
  • content/docs/releases/index.mdx (via @objectstack/spec)
  • content/docs/releases/v12.mdx (via @objectstack/spec)
  • content/docs/releases/v13.mdx (via @objectstack/spec)
  • content/docs/releases/v16.mdx (via @objectstack/spec)
  • content/docs/releases/v17.mdx (via @objectstack/spec)
  • content/docs/releases/v9.mdx (via @objectstack/spec)
  • content/docs/ui/actions.mdx (via @objectstack/spec)
  • content/docs/ui/apps.mdx (via @objectstack/spec)
  • content/docs/ui/create-vs-edit-form.mdx (via @objectstack/spec)
  • content/docs/ui/dashboards.mdx (via @objectstack/spec)
  • content/docs/ui/field-grouping-and-order.mdx (via @objectstack/spec)
  • content/docs/ui/forms.mdx (via @objectstack/spec)
  • content/docs/ui/index.mdx (via @objectstack/spec)
  • content/docs/ui/public-data-collection.mdx (via @objectstack/spec)
  • content/docs/ui/setup-app.mdx (via @objectstack/spec)
  • content/docs/ui/translations.mdx (via @objectstack/spec)
  • content/docs/ui/views.mdx (via @objectstack/spec)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

Copy link
Copy Markdown
Contributor Author

队列踢出判读与重投(PM 座位,会话 session_014wsZeReNTqiceBfLb5Pyf5,22:3xZ):

本 PR ~22:0xZ 入队后被移出(未合并;同窗口队头 pr-6034、pr-6012 亦被踢且 main 未动)——归因今日 GitHub Actions 平台事故对 merge_group 构建的持续 churn,非本 PR 签名(PR 级检查此刻 mergeable_state=clean 全绿)。踢出连带解除了 auto-merge,已原样重投(重新 enable,22:3xZ)。管家座位无在案处置评论,按双向让行由本座位先动并留此审计。若再次被踢且签名仍为平台引导族,继续原样重投;出现真实测试签名则按 notes 2 重新诊断。


Generated by Claude Code

@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Aug 7, 2026
@github-actions

github-actions Bot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 31132803246 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/3) — 失败步骤: Run this shard's tests

    �[41m�[1m FAIL �[22m�[49m src/__tests__/datasource-pool-support.test.ts�[2m > �[22m#5714 — the driver factory rejects a pool it cannot honour�[2m > �[22msqlite WITHOUT a pool still builds exactly as b
    

历史信号:

  • 本 PR 过去 24h 无队列失败记录(首次)。
  • 过去 24h 队列共有 70 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 在其他 PR 的同类评论里搜同名测试;出现过 ⇒ flaky 实锤,开 issue 修/隔离那条测试。修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

@os-zhuang
os-zhuang added this pull request to the merge queue Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

队列踢出分诊(PM 座位,会话 session_014wsZeReNTqiceBfLb5Pyf5,23:5xZ):走分诊清单支路 2——失败测试 datasource-pool-support.test.ts(service-datasource 包)与本 PR 改动面(spec 门禁脚本)零交集,且为在案 flaky #6044(同签名今日已踢 #5999#5973,本 PR 为第 3 例)。按台账纪律原样重投(auto-merge 已重挂),⛔ 不改代码;flaky 本体的修复归 #6044


Generated by Claude Code

Merged via the queue into main with commit e77c027 Aug 7, 2026
47 of 84 checks passed
@os-zhuang
os-zhuang deleted the claude/issue-5943-skill-examples-any-gate branch August 7, 2026 00:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Pull requests that update a dependency file documentation Improvements or additions to documentation size/m skip-changeset PR has no user-facing published change; bypasses the changeset gate tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[spec] check:skill-examples 应拒绝 os:check 块内把入参标 any —— 标记了却零覆盖的空门

2 participants