开发工具静态分析代码质量【免费下载链接】dependency-cruiserValidate and visualize dependencies. Your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.项目地址https://gitcode.com/gh_mirrors/de/dependency-cruiser点击查看免费下载本篇技术指南聚焦 dependency-cruiser 仓库中的src/schema/目录讲解其 JSON Schema配置 Schema 与巡航结果 Schema如何由tools/schema/下的源定义生成、如何通过 Ajv 编译成独立校验器以及这些校验器如何在 CLI 运行时与格式化阶段被真实调用。读完本文你将掌握该项目的 Schema 生成脚本、Makefile 自动化规则、产物形态与运行时消费链路并能独立完成修改 Schema 定义 → 重新生成 → 验证生效的完整操作。一、src/schema/README.md说了什么一条源定义 → 生成产物的工作流仓库根目录下的 src/schema/README.md 用极简的篇幅定义了本目录的维护纪律是理解整个 Schema 体系的入口src/schema/下的 JSON Schema 文件由tools/generate-schemas.utl.mjs脚本生成其中的校验器文件由tools/generate-schema-validator.utl.mjs脚本生成如果需要对 Schema 做修改不要直接编辑src/schema/下的生成产物而是修改 tools/schema/ 中的源定义修改之后重新运行生成脚本既可以执行make也可以分别运行node tools/generate-schemas.utl.mjs与node tools/generate-schema-validator.utl.mjs。这条规则意味着src/schema/是一个生成目录它的内容全部是机器产物而tools/schema/才是人工维护的单一事实来源Single Source of Truth。二、单一事实来源tools/schema/下的 Schema 源定义tools/schema/目录以 ES Module.mjs形式组织 Schema 定义共约三十个模块按职责可分为几组顶层配置组合configuration.schema.mjs、cruise-result.schema.mjs、baseline-violations.schema.mjs规则集定义rule-set.mjsforbidden/allowed/allowedSeverity/required、restrictions.mjsfrom/to等约束类型、severity-type.mjs巡航选项定义options.mjs、cache-options.mjs、compound-*-type.mjsdoNotFollow、exclude、includeOnly、focus、highlight、reaches等复合类型、module-systems-type.mjs、output-type.mjs、reporter-options.mjs、experimental-stats-type.mjs巡航结果结构modules.mjs、dependencies.mjs、dependency-type.mjs、mini-dependency-type.mjs、folders.mjs、summary.mjs、violations.mjs、violation-type.mjs、rule-summary.mjs、revision-data.mjs、options-used.mjs等。以 tools/schema/configuration.schema.mjs 为例顶层配置 Schema 通过模块组合完成properties直接展开ruleSet.properties再追加options与extends两个引用definitions则合并ruleSet.definitions、options.definitions与自定义的ExtendsType支持单个字符串或字符串数组表示该配置所继承的基配置。ruleSet.properties则由 tools/schema/rule-set.mjs 提供forbidden禁止的依赖规则、allowed允许的依赖规则违反时输出not-in-allowed警告、allowedSeveritynot-in-allowed的严重级别默认warn与required模块必须具备的依赖例如每个 controller 必须直接依赖 base controller。所有规则类型均设置additionalProperties: false杜绝未知字段静默通过。三、三种产物形态.schema.json、.schema.mjs与.validate.mjs生成脚本会产出三种文件各自承担不同角色产物示例用途可读 JSON Schemasrc/schema/configuration.schema.json面向人阅读、IDE 提示与外部工具如编辑器基于$schema做自动补全紧凑 ESM Schemasrc/schema/configuration.schema.mjs中间产物Makefile 会在校验器生成后清理供生成校验器时以 JS 模块形式被import独立校验器src/schema/configuration.validate.mjs、src/schema/cruise-result.validate.mjs运行时被 CLI 直接调用校验配置与巡航结果其中 src/schema/configuration.schema.json 声明了$id: https://dependency-cruiser.js.org/schema/configuration.schema.json顶层properties仅允许$schema、forbidden、allowed、allowedSeverity、required、options、extends七个键并整体设置additionalProperties: false。四、生成脚本剖析tools/generate-schemas.utl.mjssrc/schema/README.md 指定的第一个生成脚本是 tools/generate-schemas.utl.mjs其关键行为如下1. 按目标文件扩展名分派输出格式emitConsolidatedSchema(pOutputFileName)依据扩展名决定产物形态目标是.json时用 prettier 的jsonparser 对JSON.stringify(schema.default)做格式化后写入目标是.mjs时先通过stripAttribute递归删除所有description字段减小体积拼装成/* generated - dont edit */ export default {...}形式的 ESM 模块再用 prettier 的 babel parser 格式化、最后经babel/core的transformSync(..., { minified: true })压缩后写入。2. 通过正则推导输入模块名getInputModuleName(pOutputFileName)从输出路径如./src/schema/configuration.schema.json反推输入源定义./configuration.schema.mjs即tools/schema/下同名.schema.mjs模块。3. 强制 Node 权限模型脚本开头检查process.permission并要求在 Node 的 Permission Model--permission下运行随后尝试drop对..与/的读写权限缩小脚本自身的能力边界。用法为node tools/generate-schemas.utl.mjs ./src/schema/configuration.schema.json五、校验器生成剖析tools/generate-schema-validator.utl.mjssrc/schema/README.md 指定的第二个脚本是 tools/generate-schema-validator.utl.mjs。它基于 Ajv 的 standalone 代码生成能力用new Ajv({ code: { source: true, esm: true } })创建编译器实例产出 ESM 形态的源码级校验代码import输入的.schema.mjs并ajv.compile(schema.default)调用standaloneCode(ajv, validate)把编译结果导出为不依赖 Ajv 运行时的独立模块写入输出文件。用法脚本自带 Usage 示例node tools/generate-schema-validator.utl.mjs ./src/schema/configuration.schema.mjs ./src/schema/configuration.validate.mjs生成出的 src/schema/configuration.validate.mjs 是压缩后的 ESM开头即export const validatede;export default de;全部校验逻辑内联为普通函数如对SeverityType的[error,warn,info,ignore]枚举、对dependencyTypes的约四十个枚举值的逐项检查、对additionalProperties的键白名单检查等可被任何 ESM 环境直接 import 使用。六、Makefile 自动化make build一键重建Makefile 将上述两步脚本编排成 make 规则README 中重新运行生成脚本either by runningmake...指的就是这套自动化build目标依赖三组文件GENERATED_SOURCESbaseline-violations.schema.mjs/json、configuration.schema.json、cruise-result.schema.json、src/meta.cjs、GENERATED_VALIDATORS两个.validate.mjs生产规则src/%.schema.mjs: tools/%.schema.mjs $(SCHEMA_SOURCES) tools/generate-schemas.utl.mjs与同款.json规则把tools/schema/源定义连同全部SCHEMA_SOURCES一起作为依赖用$(NODE) --allow-fs-read ./ --allow-fs-write ./src/schema/执行生成脚本这里的--permission正是脚本内部检查所要求的生产规则src/schema/%.validate.mjs: src/schema/%.schema.mjs tools/generate-schema-validator.utl.mjs先生成未压缩校验器随后npx esbuild --tree-shakingtrue --minify二次压缩最后$(RM) $删除作为中间产物的.schema.mjs所以在最终仓库里只见.schema.json与.validate.mjsclean目标删除全部生成产物help目标说明build与clean的用途。七、运行时消费链路校验器在 CLI 与格式化阶段被真实调用生成的校验器并非摆设而是贯穿 dependency-cruiser 主流程的硬性检查配置校验src/main/rule-set/assert-validity.mjs 导入#schema/configuration.validate.mjs在assertSchemaCompliance中调用validateConfigurationSchema(pConfiguration)校验失败即抛出The supplied configuration is not valid: ...并附上错误详情——这意味着任何非法配置在巡航开始前就会被拒绝结果校验src/main/format.mjs 导入#schema/cruise-result.validate.mjs在格式化输出前用validateCruiseResultSchema(pResult)校验巡航结果失败抛出The supplied dependency-cruiser result is not valid: ...错误格式化src/schema/utl.mjs 提供validateErrorsToString(pErrors)把 Ajv 错误数组instancePathmessage拼接成可读字符串供上述两处抛错使用。由此可以确认一条完整链路开发者修改tools/schema/源定义 →make build或两个node脚本重新生成src/schema/产物 → CLI 运行时经assert-validity.mjs用新校验器拦截非法配置。八、实践指引修改 Schema 的标准操作流程结合 src/schema/README.md 的约定与上述源码证据为 dependency-cruiser 扩展配置项的推荐流程是改源定义在 tools/schema/ 中编辑对应的.schema.mjs新增配置项时通常涉及options.mjs及其引用类型模块重新生成在仓库根目录执行make build若只想重建单个文件可按 README 给出的命令分别执行node tools/generate-schemas.utl.mjs与node tools/generate-schema-validator.utl.mjs注意脚本需要 Node 的--permission模式直接运行请参照 Makefile 中的$(NODE)定义补齐权限参数验证生效编写带新字段的.dependency-cruiser.cjs配置运行depcruise确认不再触发assertSchemaCompliance的抛错且旧配置仍可通过校验回归保持纪律绝不手工编辑src/schema/下的生成产物——它们带有生成标记或被压缩手工改动会在下次make build时被覆盖。对使用 dependency-cruiser 的普通用户而言同样能从这套体系受益在配置文件中声明$schema: https://dependency-cruiser.js.org/schema/configuration.schema.json编辑器即可基于仓库公开的 Schema 提供配置键补全与非法字段提示把大部分配置错误消灭在编写阶段而不是等到 CLI 运行时才收到The supplied configuration is not valid的报错。赞分享开发工具静态分析代码质量【免费下载链接】dependency-cruiserValidate and visualize dependencies. Your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.项目地址https://gitcode.com/gh_mirrors/de/dependency-cruiser点击查看免费下载相关推荐oh-my-openagent 的生成式 Schema 制品体系从 Zod 到 JSON Schema 的单一事实来源流水线oh my openagent 的生成式 Schema 制品体系从 Zod 到 JSON Schema 的单一事实来源流水线 assets/ 目录是 oh m人工智能AI Agent代码智能体多智能体MCP ClientsAgent 编排OmO 配置体系中的 telemetry 配置项从 Zod 严格校验到统一 Schema 生成的全链路实现OmO 配置体系中的 telemetry 配置项从 Zod 严格校验到统一 Schema 生成的全链路实现 导读 本文基于 oh my openagent 仓人工智能AI Agent代码智能体多智能体MCP ClientsAgent 编排Relay 开发工作流从配置 Relay Compiler 到生成运行时产物Relay 开发工作流从配置 Relay Compiler 到生成运行时产物 本篇技术指南以 Relay v14 文档中的 Workflow 章节为核心讲解前端开发工具上一篇3D打印螺纹总卡死CustomThreads完整指南让Fusion 360螺纹一次旋合下一篇radix-vue HoverCardTrigger 深度解析:悬浮卡片触发器的定位锚点、事件语义与 Props 详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考