DESIGN.md 发布前如何验证 npm 包check-package 四阶段 17 项检查详解【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md如果你正在维护或参与贡献google/design.mdDESIGN.md 格式规范的 CLI 与 linter准备把packages/cli下的包发布到 npm就需要先确认package.json字段、构建产物、tarball 内容以及消费端的导入与运行行为都正确。仓库内置了验证脚本 check-package它按 4 个阶段执行一组检查全部通过时退出码为0有任何失败时退出码为1。本文说明如何运行它以及每项检查在验证什么帮助你在npm publish之前拦截结构问题。运行前提在仓库的packages/cli目录下运行该脚本需要提前满足以下条件Bun 运行时脚本 shebang 为#!/usr/bin/env bun并从bun导入Glob、$monorepo 根 package.json 声明packageManager: bun1.3.9根目录含bun.lock。npmPhase 3 会执行npm pack --dry-run需要 npm 可用脚本内部会把~/.bun/bin加入子进程PATH。Node ≥ 18CLI package.json 的engines字段要求node 18.0.0Phase 4 会用node直接执行构建产物。工作区依赖已安装脚本内部执行bun run build该构建命令依赖bun build、npx tsc等 devDependencies先按仓库的包管理器安装依赖再运行检查。完整仓库检出build 脚本会把../../docs/spec.md即 docs/spec.md和src/linter/spec-config.yaml拷贝进dist/且 Phase 4 的spec命令检查依赖spec.md能加载因此不能只在孤立目录里跑。副作用说明运行前必读该脚本会递归删除packages/cli/dist/目录Phase 2 的清理步骤随后重新构建并会在系统临时目录创建一个check-pkg-前缀的临时目录、结束后尽力清理。npm pack --dry-run只生成文件清单不产出 tarball更不会发布包脚本只读取package.json不会修改它。启动检查确认packages/cli/dist可以被删除产物会重建后在packages/cli目录下运行bun run scripts/check-package.ts这是脚本头部注释给出的用法package.json也把它注册为check-package脚本因此bun run check-package等价。脚本会依次执行 5 个函数调用执行顺序见下逐项打印✅或❌最后一行输出✅ N passed ❌ M failed汇总。构建步骤Phase 2 的 #7实际执行的是 CLI package.json 里的build脚本即bun build src/index.ts src/linter/index.ts --outdir dist --target node npx tsc --project tsconfig.build.json --emitDeclarationOnly --skipLibCheck cp src/linter/spec-config.yaml dist/linter/ cp src/linter/spec-config.yaml dist/ cp ../../docs/spec.md dist/linter/ cp ../../docs/spec.md dist/如果这一步失败#7 会标记❌ Build succeedsdetail 为tsc exited with non-zero。另请注意当前仓库列表中packages/cli下只有package.json、scripts/、src/、tsconfig.json没有tsconfig.build.json。如果构建因找不到该文件而失败#7 会以❌结束需要以tsc的实际报错为准排查而不是调整其他检查项。四个阶段的检查项脚本的main执行顺序为Phase 1a配置校验→ Phase 2干净构建→ Phase 1b构建后路径解析→ Phase 3pack 审计→ Phase 4消费端冒烟测试。注意 1b 放在 Phase 2 之后是为了对刚构建出来的dist/做路径存在性验证。Phase 1apackage.json 校验直接读取 CLI package.json共 6 项编号检查内容判定标准#1files字段存在files是非空数组当前值为[dist]#2exports[.]已定义exports中存在.入口#3exports[.].types字段存在主入口带types条件#4main字段存在当前值./dist/index.js#5types字段存在当前值./dist/index.d.ts#5cbin map 暴露 Windows 友好别名至少一个 bin 名不含.#5c 的背景在脚本注释中写得很具体design.md这个 bin 名在 Windows 上因.md后缀与 Markdown 文件关联冲突PowerShell 会用 Markdown 编辑器打开 shim 而不是执行它无点别名当前为designmd指向同一入口./dist/index.js能让 npm 生成的 CMD/PowerShell shim 正常解析。Phase 2干净构建编号检查内容判定标准#6Clean dist删除既有dist/后确认其不存在脚本副作用见上文#7Build succeeds在包目录执行bun run build且退出码为 0#8No test files in distdist/下无**/*.test.*文件#9No fixture files in distdist/下无**/fixtures/**内容若构建后dist/仍不存在#8、#9 会直接以❌结束并标注dist/ does not exist after build。Phase 1b构建后路径解析验证package.json中声明的入口路径在磁盘上真实存在相对于包根目录编号检查内容判定标准#2bexports[.].import可解析./dist/index.js存在#3bexports[.].types可解析./dist/index.d.ts存在#4bmain可解析对应文件存在#5btypes可解析对应文件存在失败时 detail 会打印缺失的路径形如Missing: ./dist/index.js。Phase 3Pack 审计先执行npm pack --dry-run --json在packages/cli下解析出将要打进 tarball 的文件清单再对其做内容审计编号检查内容判定标准#10npm pack --dry-run成功命令退出码为 0 且文件清单非空#11tarball 无源码.ts文件路径以.ts结尾且不属于.d.ts/.d.ts.map的文件为 0#12tarball 无测试文件路径含.test.的文件为 0#13tarball 无配置文件路径含tsconfig的文件为 0#14tarball 无 fixtures路径含fixtures的文件为 0#15入口文件在 tarball 中同时包含dist/index.js与dist/index.d.ts如果 #10 拿不到文件清单#11–#15 会全部标记Skipped — no file list并以❌计入失败。Phase 4消费端冒烟测试模拟一个外部消费者对构建产物做导入与运行时验证。脚本在系统临时目录写入两个.mjs文件执行编号检查内容判定标准#16Import resolution (ESM)在临时目录import { lint } from dist/linter/index.jstypeof lint function且脚本输出以ok结尾#17Type declarations validdist/linter/index.d.ts同时包含export、lint与LintReport类型名#18Runtime sanity用 frontmatter 示例name: Testcolors.primary调用lint()返回对象同时含designSystem、findings、summary、tailwindConfig四个键且designSystem是对象、findings是数组、summary.errors是数字#19CLI entry point validnode dist/index.js --help成功且 stderr 不含ENOENT#20CLI spec command validnode dist/index.js spec成功且 stderr 不含Failed to load spec.md#16 与 #18 失败时脚本会额外把子进程的 STDOUT/STDERR 打印到终端便于直接定位导入或运行错误。输出判读与成功标准脚本的输出结构与判定方式逐项标记通过打印✅ label失败打印❌ label并跟一行→ detaildetail 文案即代码中写死的修复提示例如 #1 失败提示Add a files array to package.json to control what ships#17 失败提示index.d.ts missing lint export or LintReport type。汇总行结尾为✅ N passed ❌ M failedN与M是本次实际执行的计数随检查项增减而变化。退出码全部通过为0存在任何失败为1——这是把它接入 CI 做发布门禁的依据。关于17 项脚本头部注释写明 Runs 17 checks across 4 phases这也是本文标题的来源但当前源码中的检查标签已编号至 #20另含 #2b–#5b、#5c 等子项实际执行的check()调用多于 17 次。两者不一致时以运行时汇总行打印的passed/failed计数为准——它统计的是真实执行项。边界与限制该脚本只做验证不产出 tarball、不执行npm publish、不修改package.json。CLI package.json 中另有publishConfig自定义 registry、access: public发布动作本身不属于本脚本范围。Phase 4 只覆盖linter子入口的 ESM 导入、类型声明形状和--help、spec两个 CLI 命令其余命令lint、diff、export不在冒烟范围内。检查基于packages/cli这一包的结构约定入口dist/index.js、类型dist/index.d.ts、linter 子入口dist/linter/index.js#15、#16 的判定路径与这些约定硬编码绑定。运行结束后以退出码收束0表示四个阶段的检查全部通过包结构可以进入发布流程1时按❌项的→提示逐项修复后重跑即可脚本会再次清理并重建dist/。【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DESIGN.md 发布前如何验证 npm 包：check-package 四阶段 17 项检查详解
DESIGN.md 发布前如何验证 npm 包check-package 四阶段 17 项检查详解【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md如果你正在维护或参与贡献google/design.mdDESIGN.md 格式规范的 CLI 与 linter准备把packages/cli下的包发布到 npm就需要先确认package.json字段、构建产物、tarball 内容以及消费端的导入与运行行为都正确。仓库内置了验证脚本 check-package它按 4 个阶段执行一组检查全部通过时退出码为0有任何失败时退出码为1。本文说明如何运行它以及每项检查在验证什么帮助你在npm publish之前拦截结构问题。运行前提在仓库的packages/cli目录下运行该脚本需要提前满足以下条件Bun 运行时脚本 shebang 为#!/usr/bin/env bun并从bun导入Glob、$monorepo 根 package.json 声明packageManager: bun1.3.9根目录含bun.lock。npmPhase 3 会执行npm pack --dry-run需要 npm 可用脚本内部会把~/.bun/bin加入子进程PATH。Node ≥ 18CLI package.json 的engines字段要求node 18.0.0Phase 4 会用node直接执行构建产物。工作区依赖已安装脚本内部执行bun run build该构建命令依赖bun build、npx tsc等 devDependencies先按仓库的包管理器安装依赖再运行检查。完整仓库检出build 脚本会把../../docs/spec.md即 docs/spec.md和src/linter/spec-config.yaml拷贝进dist/且 Phase 4 的spec命令检查依赖spec.md能加载因此不能只在孤立目录里跑。副作用说明运行前必读该脚本会递归删除packages/cli/dist/目录Phase 2 的清理步骤随后重新构建并会在系统临时目录创建一个check-pkg-前缀的临时目录、结束后尽力清理。npm pack --dry-run只生成文件清单不产出 tarball更不会发布包脚本只读取package.json不会修改它。启动检查确认packages/cli/dist可以被删除产物会重建后在packages/cli目录下运行bun run scripts/check-package.ts这是脚本头部注释给出的用法package.json也把它注册为check-package脚本因此bun run check-package等价。脚本会依次执行 5 个函数调用执行顺序见下逐项打印✅或❌最后一行输出✅ N passed ❌ M failed汇总。构建步骤Phase 2 的 #7实际执行的是 CLI package.json 里的build脚本即bun build src/index.ts src/linter/index.ts --outdir dist --target node npx tsc --project tsconfig.build.json --emitDeclarationOnly --skipLibCheck cp src/linter/spec-config.yaml dist/linter/ cp src/linter/spec-config.yaml dist/ cp ../../docs/spec.md dist/linter/ cp ../../docs/spec.md dist/如果这一步失败#7 会标记❌ Build succeedsdetail 为tsc exited with non-zero。另请注意当前仓库列表中packages/cli下只有package.json、scripts/、src/、tsconfig.json没有tsconfig.build.json。如果构建因找不到该文件而失败#7 会以❌结束需要以tsc的实际报错为准排查而不是调整其他检查项。四个阶段的检查项脚本的main执行顺序为Phase 1a配置校验→ Phase 2干净构建→ Phase 1b构建后路径解析→ Phase 3pack 审计→ Phase 4消费端冒烟测试。注意 1b 放在 Phase 2 之后是为了对刚构建出来的dist/做路径存在性验证。Phase 1apackage.json 校验直接读取 CLI package.json共 6 项编号检查内容判定标准#1files字段存在files是非空数组当前值为[dist]#2exports[.]已定义exports中存在.入口#3exports[.].types字段存在主入口带types条件#4main字段存在当前值./dist/index.js#5types字段存在当前值./dist/index.d.ts#5cbin map 暴露 Windows 友好别名至少一个 bin 名不含.#5c 的背景在脚本注释中写得很具体design.md这个 bin 名在 Windows 上因.md后缀与 Markdown 文件关联冲突PowerShell 会用 Markdown 编辑器打开 shim 而不是执行它无点别名当前为designmd指向同一入口./dist/index.js能让 npm 生成的 CMD/PowerShell shim 正常解析。Phase 2干净构建编号检查内容判定标准#6Clean dist删除既有dist/后确认其不存在脚本副作用见上文#7Build succeeds在包目录执行bun run build且退出码为 0#8No test files in distdist/下无**/*.test.*文件#9No fixture files in distdist/下无**/fixtures/**内容若构建后dist/仍不存在#8、#9 会直接以❌结束并标注dist/ does not exist after build。Phase 1b构建后路径解析验证package.json中声明的入口路径在磁盘上真实存在相对于包根目录编号检查内容判定标准#2bexports[.].import可解析./dist/index.js存在#3bexports[.].types可解析./dist/index.d.ts存在#4bmain可解析对应文件存在#5btypes可解析对应文件存在失败时 detail 会打印缺失的路径形如Missing: ./dist/index.js。Phase 3Pack 审计先执行npm pack --dry-run --json在packages/cli下解析出将要打进 tarball 的文件清单再对其做内容审计编号检查内容判定标准#10npm pack --dry-run成功命令退出码为 0 且文件清单非空#11tarball 无源码.ts文件路径以.ts结尾且不属于.d.ts/.d.ts.map的文件为 0#12tarball 无测试文件路径含.test.的文件为 0#13tarball 无配置文件路径含tsconfig的文件为 0#14tarball 无 fixtures路径含fixtures的文件为 0#15入口文件在 tarball 中同时包含dist/index.js与dist/index.d.ts如果 #10 拿不到文件清单#11–#15 会全部标记Skipped — no file list并以❌计入失败。Phase 4消费端冒烟测试模拟一个外部消费者对构建产物做导入与运行时验证。脚本在系统临时目录写入两个.mjs文件执行编号检查内容判定标准#16Import resolution (ESM)在临时目录import { lint } from dist/linter/index.jstypeof lint function且脚本输出以ok结尾#17Type declarations validdist/linter/index.d.ts同时包含export、lint与LintReport类型名#18Runtime sanity用 frontmatter 示例name: Testcolors.primary调用lint()返回对象同时含designSystem、findings、summary、tailwindConfig四个键且designSystem是对象、findings是数组、summary.errors是数字#19CLI entry point validnode dist/index.js --help成功且 stderr 不含ENOENT#20CLI spec command validnode dist/index.js spec成功且 stderr 不含Failed to load spec.md#16 与 #18 失败时脚本会额外把子进程的 STDOUT/STDERR 打印到终端便于直接定位导入或运行错误。输出判读与成功标准脚本的输出结构与判定方式逐项标记通过打印✅ label失败打印❌ label并跟一行→ detaildetail 文案即代码中写死的修复提示例如 #1 失败提示Add a files array to package.json to control what ships#17 失败提示index.d.ts missing lint export or LintReport type。汇总行结尾为✅ N passed ❌ M failedN与M是本次实际执行的计数随检查项增减而变化。退出码全部通过为0存在任何失败为1——这是把它接入 CI 做发布门禁的依据。关于17 项脚本头部注释写明 Runs 17 checks across 4 phases这也是本文标题的来源但当前源码中的检查标签已编号至 #20另含 #2b–#5b、#5c 等子项实际执行的check()调用多于 17 次。两者不一致时以运行时汇总行打印的passed/failed计数为准——它统计的是真实执行项。边界与限制该脚本只做验证不产出 tarball、不执行npm publish、不修改package.json。CLI package.json 中另有publishConfig自定义 registry、access: public发布动作本身不属于本脚本范围。Phase 4 只覆盖linter子入口的 ESM 导入、类型声明形状和--help、spec两个 CLI 命令其余命令lint、diff、export不在冒烟范围内。检查基于packages/cli这一包的结构约定入口dist/index.js、类型dist/index.d.ts、linter 子入口dist/linter/index.js#15、#16 的判定路径与这些约定硬编码绑定。运行结束后以退出码收束0表示四个阶段的检查全部通过包结构可以进入发布流程1时按❌项的→提示逐项修复后重跑即可脚本会再次清理并重建dist/。【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考