Uh oh!
There was an error while loading. Please reload this page.
docs(plugin-report): rewrite README export snippets against the real signatures - #5060
Merged
Merged
Conversation
…signatures The `### Export` / `### Live Export` blocks named only real exports but called every one of them with the wrong arity or argument order — a defect class the name-set check used for #5016 cannot see, because each import reads as real. - The six format exporters are `(report, data, config?)` returning `void`. The README called them `(data, filename)`, so a filename string landed in the `data` slot the engine iterates as rows, and no filename parameter exists at all (the name comes from `config.filename`, else `report.title`). The `await` on a synchronous `void` return was inert. `exportReport` takes the format first, which no snippet showed. - `exportWithLiveData(report, options)` requires `dataSource` and `resource`; the README passed only `{ format: 'pdf' }`. - `exportExcelWithFormulas(report, data, options)` takes three parameters, not two, and `ExcelColumnConfig` has the required `name` + `header`, not `field`. Formula templates use the `{ROW}` placeholder. The replacements are the exporters' own correct JSDoc examples. Each block was extracted from the README programmatically and compiled against the package's built `dist/index.d.ts` (rc=0); the old form backfilled into the same probe goes red on all three blocks. Docs only — no API or runtime change. Fixes#5048 Co-authored-by: Claude <noreply@anthropic.com>
Contributor
✅ Console Performance Budget
📦 Bundle Size Report
Size Limits
|
yinlianghui
commented
Aug 17, 2026
CollaboratorAuthor
PM 验收:ACCEPT(session 实物核验:merge-base 验收要点:
转 ready 并挂 auto-merge(squash)。 Generated by Claude Code |
yinlianghui
marked this pull request as ready for review
August 17, 2026 21:51
Uh oh!
There was an error while loading. Please reload this page.
This was referenced Aug 18, 2026
Merged
os-zhuang pushed a commit
that referenced
this pull request
Aug 18, 2026
…t types (#5138) objectui#5138 shape 2, as ruled: promote the snippet-extraction + `tsc --strict`-against-built-`dist` harness into `scripts/`, where it runs once in CI instead of three times by hand. The harness already existed three times, hand-rolled and private — in #5053, #5060 and #5047's PR — and each copy found defects its reviewer had not listed. This keeps the practice each one proved: extraction by script rather than by hand, resolution against the package's built `dist/*.d.ts` with a self-check that says so, and a planted sentinel export that must produce a diagnostic. The false-green mechanism #5047 measured is designed against structurally rather than noted: parse errors suppress semantic checking program-wide, so a run can print a few syntax errors, no semantic diagnostics at all, and read as a meaningful red. The two phases are separate here, unparseable blocks are reported and kept out of the semantic program, every failure line is tagged `[syntax]` or `[semantic]`, and the summary always states how many blocks the semantic phase actually judged. Fragments are declared, never guessed: a block that is not meant to compile carries a marker with a written reason immediately above its fence. A block that fails to parse is a failure, never a skip — the alternative turns every real defect into a silent skip. Coverage is declared too. A document is covered unless it is named in the script's ledger with a reason; the default is covered, so a new page is gated from the day it lands. 13 documents and 67 blocks are covered today; the 44 documents on the ledger are debt with names, and the script's header says plainly that they are unverified. Scope of the gate, stated in its header because an unstated blind spot is how this class stays green: it judges TypeScript resolvability only — not schema-key validity against the spec (#5138 shape 1, unruled), not `type`-literal registration (`check-doc-component-types.mjs`), and not shell examples (#5151).
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 freeto 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#5048
packages/plugin-report/README.md的### Export/### Live Export两节里,导出函数的名字全部真实,但调用的参数个数与顺序全错。这正是 #5016 用的名集合核对看不见的缺陷类:每个 import 读起来都是真的,错的是调用形。本 PR 只重写这三个示例块 + 一个 changeset,不改任何 API、不加导出、不动src/。Base:
ee4f796d26635c39ff1f9a814bf9fc04529a9e7a(含前置 PR #5053 的f331f5a8b)。前提验证:卡面三处签名断言逐条对 src 复核
卡面的行号在本 base 上全部命中,三条断言全部为真 —— 前提成立。
(report, data, config?): voidReportExportEngine.ts:19,43,57,96,151:19CSV /:43JSON /:57HTML /:96PDF /:151Excel,五个签名逐字一致,全部: void、无asyncexportReportformat-first:175exportReport(format: ReportExportFormat, report, data, config?): voidconfig?.filename || report.title || 'report'(:37,:50,:90,:169)LiveExportOptions的dataSource/resource必填LiveReportExporter.ts:34-45:34-45,dataSource: DataSource/resource: string均无?exportWithLiveData真签名:97async (report, options: LiveExportOptions): Promise< LiveExportResult >:88-95:86-94(内容定位;偏移 2 行),形状正确,已直接复用exportExcelWithFormulas三参:161:161(report, data, options = {}): voidExcelColumnConfig列键是name而非field:50-61:50-61,{ name: string; header: string; width?; numberFormat?; formula? }{ROW}占位:139-146:149-156(偏移 10 行);实现在:177col.formula.replace(/\{ROW\}/g, String(rowIndex + 2))卡面未列、复核时补测到的一条:
ExcelColumnConfig.header也是必填(header: string,无?)。所以把field改成name并不足以让示例编译 —— 见下面探针 P6。重写后的列都带header。逐块签名对照
块 1 —
### Export(旧README.md:237-239)await exportAsCSV(reportData, 'sales-report.csv')exportAsCSV(report, rows, config?)reportData(读作数据)report: ReportComponentSchema—— 列与标题的来源data: any[]—— 引擎按行迭代config.filename,否则report.titleawait(视作 async)void同步,await空转exportReportexportReport('csv', report, rows)exportAsJSON/exportAsHTML原先只在 import 列表里出现、从无调用,现在六个全部各给一行。顺带订正两处旧文字的事实错误:exportAsPDF才是开打印窗口的那个(:100window.open,被拦则退回.html),exportAsHTML是下载.html(:90);exportAsExcel落盘的是带 BOM 的 TSV,默认名后缀.tsv而非旧示例写的.xlsx(:169)。块 2 —
exportWithLiveData(旧:249):旧写法{ format: 'pdf' }缺两个必填键。改后直接复用函数自己的 JSDoc 示例(dataSource+resource+format),并补上返回值LiveExportResult的形状与失败语义(返回而非抛出)。块 3 —
exportExcelWithFormulas(旧:250-252):旧写法传 2 参、列键写field、formula 写死SUM(B2:B100)。改后三参齐全,列键name+ 必填header,formula 用'=B{ROW}*C{ROW}'(即:149-156的正例)。编译探针读数
探针把 README 的三个
tsx块用脚本从README.md里提取(不是手抄),对构建产物编译。解析确认打到的是产物而非源码:前置构建:
pnpm --workspace-concurrency=2 --filter '@object-ui/plugin-report...' build→ Done。tsc --noEmit --strict)exportReport('csv', report, rows)故意换成exportReport(report, 'csv', rows)TS2345: Argument of type 'ReportComponentSchema' is not assignable to parameter of type 'ReportExportFormat'.—— 证明探针不是静默any反向验证 —— 预判先写,含两条「抓不到」
预判在跑之前写进探针文件头,方向为旧写法回填必须转红:
data: any[],三次35,33 / 36,33 / 37,35: error TS2345: Argument of type 'string' is not assignable to parameter of type 'any[]'.42,42: error TS2345: ... '{ format: "pdf"; }' is missing the following properties from type 'LiveExportOptions': dataSource, resource48,5: error TS2353: Object literal may only specify known properties, and 'columns' does not exist in type 'any[]'.—— 我预判 TS2345,实为 TS2353。同一缺陷,码不同,如实记录void同步函数await。TS 允许 await 非 thenable,只有 eslintawait-thenable看得见await exportAsCSV(report, rows)+await exportExcelWithFormulas(report, rows, {})→ 零诊断。故「await空转」这一条没有编译期证据,证据改用源码读数:ReportExportEngine.ts:19,43,57,96,151五个签名均为: void、无async、不返回 Promise;exportExcelWithFormulas(:161)同样: void。README 里改为不写await,并在正文点明「同步void,没有可 await 的东西」field键名。它只有在对象落到options位后才被判定,躺在 P3 后面永远轮不到56,17: error TS2353: Object literal may only specify known properties, and 'field' does not exist in type 'ExcelColumnConfig'.field改成name后,缺header是否仍红error TS2741: Property 'header' is missing in type '{ name: string; formula: string; }' but required in type 'ExcelColumnConfig'.一处对 issue「影响」段的订正
Issue 的 Impact 写「块 1 和块 3 能过检(type-check as written against
any[]/loose params),在运行期才炸」。实测不成立:在strict程序里两块都是硬编译错误(P1 / P3),读者会被编译器直接拦住,而不是拿到一份用文件名字符逐字拼出来的表格。签名断言本身全部为真,所以前提成立;错的只是严重性刻画。方向上这让缺陷更硬而非更软 —— 每个照抄的读者都会被拦,而不是只有一部分被误导。唯一真正「静默」的一条是await空转(P4),而它落在 tsc 的盲区里。同文件同性质漂移扫描
README 其余带真实 API 调用的块(
isDatasetReport+DatasetReportRenderer、ReportViewer的schema形、createScheduleTrigger(report, dataSource, resource, onComplete)四参 +trigger()、formatValue(value, field?))逐块抄进同一探针 → rc=0,无未列的同性质签名漂移可修。#5047 的 schema 形(retired query form)是不同性质,按钉子未碰。名集合核对(多行 import 块 + 剥注释,对
dist/index.d.ts与types/dist/index.d.ts的真实导出面):14 块,fake=0 —— 本次改动没有引入任何假名。(过程中修了核对脚本自身一个贪婪正则:它会跨过相邻两条 import 语句把ReportInput } from '@objectstack/spec/ui'; import { ReportRenderer整段当成一个名字误报;改成[^{}]*?后归零。脚本是探针,不入库。)验证
pnpm exec turbo run type-check --concurrency=2(仓根,全量)→Tasks: 81 successful, 81 totalnode scripts/check-doc-links.mjs→Links are valid across 13 scan roots.node scripts/check-control-bytes.mjs→OK (scanned 4507 tracked text file(s); skipped 85 binary);两个改动文件另做grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]'自扫,零命中packages/plugin-report/src/__tests__/无 README 引用;scripts/__tests__/doc-version-claims.test.ts只核该文件的 peer 版本声明,本次未触及).changeset/plugin-report-export-signatures.md:@object-ui/plugin-reportpatch,docs 级说明。Generated by Claude Code