用途:本技能说明如何通过命令行标志与 callidescope.config.ts 配置 callidescope 的运行行为。每次运行同时读取两个来源:命令行标志,以及被其叠加覆盖的 callidescope.config.ts;两者单独都不完整,例如 --check 指定的限制必须已在配置中设置,文件目标只有在标志要求时才会被写入。
两个独立决策:每次调用回答两个互不蕴含的问题——本次运行在什么上失败(--check,逗号分隔集合),以及本次运行重写什么(--write,加上配置中的目标)。两者都未给出时,运行不会读取或重写任何目标,只追踪、打印并退出。
主要标志:-a/--addresses 指定可调用地址(<file>#<qualified-name>,仅 depth 与 breadth,省略时提示);--config 指定配置文件路径,省略时自动搜索;-d/--directories 指定要追踪的目录,每个目录需自带 tsconfig.json;--entry-point-addresses、--entry-point-decorators、--include-exported-functions、--include-orphans、--include-tests 覆盖同名 entryPoints 字段;--exclude、--exclude-callees 覆盖对应字段;-f/--format 选择打印格式(markdown 默认、mermaid、json,仅命令行);--json、-m/--markdown、--mermaid 覆盖对应写入目标路径;--maximum-depth、--maximum-breadth 覆盖限制(后者在配置未声明时被拒绝);--check、--write 决定上述两个决策。
使用方式:--check depth 可作为提交钩子门禁;无 Nx 环境下用 npx callidescope --write 发布报告;缩小范围时用 npx callidescope -d packages/foo,packages/bar --check depth。配置文件支持 callidescope.config.{ts,mts,cts,js,mjs,cjs,json,jsonc},含七个顶层键:directories、entryPoints、exclude、excludeCallees、excludeFrom、limits、write。
限制:--check 无值会被拒绝;未识别值会被拒绝;--write --check reports 被直接拒绝;maximumBreadth 无默认值,未声明时 breadth 只报告不门禁;excludeFrom 没有对应标志;被退役字段(spreadThreshold 等)会被拒绝。提示行为仅在附加终端时发生,脚本与 CI 环境不会被提示。