callidescope-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telling callidescope what to do

告诉 callidescope 该做什么

Two surfaces, read together on every run: the flags on the command line, and the

callidescope.config.ts

they layer over. Neither is complete on its own:

--check

names a limit the configuration has to have set, and a file destination is only written when a flag asks for it.

每次运行都要同时读取两个层面：命令行上的 flags，以及它们所叠加的

callidescope.config.ts

。二者单独看都不完整：

--check

指定一个配置必须已经设置的限制，而只有 flag 提出要求时才会写入文件目标。

The two decisions a run makes

一次运行所做的两个决定

Every invocation answers two independent questions, neither implying the other:

Question	Answered by
What does this run fail on?	`--check` , a comma-separated set
What does this run rewrite?	`--write` , plus the destinations in the configuration

A run given neither

--write

nor

--check reports

reads no destination and rewrites none: it traces, prints, and exits. That is what makes a bare run safe to type inside somebody's checkout, and why a gate on a pull request leaves every committed report exactly as it found it.

每次调用都会回答两个彼此独立的问题，二者互不蕴含：

问题	由什么回答
本次运行会在什么情况下失败？	`--check` ，后接一组逗号分隔的值
本次运行会重写什么？	`--write` ，以及配置中的目标位置

如果既未传入

--write

，也未传入

--check reports

，本次运行就不会读取任何目标，也不会重写任何目标：它只会进行 trace、打印结果并退出。正因如此，在某个 checkout 中直接输入裸命令是安全的；而 PR 上的门禁也会让所有已提交的报告保持原样。

The flags

Flags

Flag	Meaning
`-a, --addresses`	Comma-separated callable addresses, each `<file>#<qualified-name>` . `depth` and `breadth` only. Prompted for when omitted
`--config`	Path to a `callidescope.config.ts` . Searched for when omitted
`-d, --directories`	Comma-separated project directories to trace, each holding its own `tsconfig.json`
`--entry-point-addresses` , `--entry-point-decorators` , `--include-exported-functions` , `--include-orphans` , `--include-tests`	Override the matching `entryPoints` field. The two lists are comma-separated; the three switches take `true` or `false` , or the bare flag for `true`
`--exclude` , `--exclude-callees`	Comma-separated globs and callee patterns, overriding the authored field. The tool's own default exclusions are folded back in, exactly as they are under a configured `exclude`
`-f, --format`	`markdown` , `mermaid` , or `json` , for what it prints. Markdown by default. Anything else is refused rather than rewritten. Command-line only — no configuration field corresponds to it
`--json` , `-m, --markdown` , `--mermaid`	Where each report goes. Overrides the path of that declared `write` destination, and nothing else about it. Needs `--write` or `--check reports`
`--maximum-depth` , `--maximum-breadth`	A number, overriding that limit wherever a project declared it. `--maximum-breadth` is refused against a configuration declaring none, breadth having no default to override
`--check` , `--write`	The two decisions above: fail on a comma-separated set drawn from `breadth` , `depth` , and `reports` ; write every configured destination

Every configured field has an overriding flag, save one.

excludeFrom

names the ignore files a run reads — no flag corresponds to it. An override may change a declared value and may not supply one, so no flag makes an under-configured run legal, and a list written empty reads as absent.

depth

and

breadth

take every override above but the destinations and the limits, plus

--config

and

--format

;

--addresses

is theirs alone.

Flag	含义
`-a, --addresses`	逗号分隔的可调用项地址，每个地址的格式为 `<file>#<qualified-name>` 。仅用于 `depth` 和 `breadth` 。省略时会提示输入
`--config`	`callidescope.config.ts` 的路径。省略时会自动查找
`-d, --directories`	要 trace 的项目目录，多个目录以逗号分隔；每个目录都必须包含自己的 `tsconfig.json`
`--entry-point-addresses` 、 `--entry-point-decorators` 、 `--include-exported-functions` 、 `--include-orphans` 、 `--include-tests`	覆盖对应的 `entryPoints` 字段。前两个列表以逗号分隔；后三个开关可取 `true` 或 `false` ，也可仅写 flag 以表示 `true`
`--exclude` 、 `--exclude-callees`	逗号分隔的 glob 和被调用项模式，覆盖显式编写的对应字段。工具自身的默认排除项会重新合并进来，其行为与配置中的 `exclude` 完全相同
`-f, --format`	指定打印内容使用 `markdown` 、 `mermaid` 或 `json` 。默认使用 Markdown。其他值会被拒绝，而不是被改写。仅限命令行使用，没有对应的配置字段
`--json` 、 `-m, --markdown` 、 `--mermaid`	指定各类报告的写入位置。仅覆盖已声明的相应 `write` 目标的路径，不会改变该目标的其他设置。需要搭配 `--write` 或 `--check reports` 使用
`--maximum-depth` 、 `--maximum-breadth`	指定数值，覆盖项目声明的相应限制。如果配置未声明 `maximumBreadth` ，使用 `--maximum-breadth` 会被拒绝，因为 `breadth` 没有可供覆盖的默认值
`--check` 、 `--write`	决定前述两个问题：在一组逗号分隔的值（取自 `breadth` 、 `depth` 和 `reports` ）上决定何时失败；写入所有已配置的目标位置

每个已配置字段都有一个对应的覆盖 flag，只有一个例外。

excludeFrom

指定一次运行会读取哪些 ignore 文件，因此没有对应的 flag。覆盖项可以改变已声明的值，却不能提供配置中未声明的值；所以没有任何 flag 能让配置不完整的运行变得合法，而显式写出的空列表会被视为未声明。用于

depth

和

breadth

的检查可以采用除目标位置和限制覆盖项之外的所有上述覆盖 flag，另加

--config

和

--format

；

--addresses

则仅供它们使用。

One precedence rule governs every override

所有覆盖项都遵循同一条优先级规则

Every combination of a command-line value with a configured one is resolved in one place,

FlagResolutionService

, under one rule:

A flag that changes what a run judges or writes may only override a value the configuration already declares. A flag that selects mode or presentation is command-line only, because neither can make an under-configured run legal.

--check

--write

, and

--format

are mode or presentation and are never written into the configuration.

--config

is neither: it chooses the file everything else is resolved against, so it has already done its whole job by the time the rest of resolution runs. Every other flag is an override, and an override answers a question the configuration already asked: a path flag replaces only the

path

of a destination already declared, keeping its heading, description, anchors, and hooks;

--maximum-breadth

cannot conjure a limit a project's own file left unset, the same way

--json

cannot conjure a

write.json

the workspace file never declared. A limit override reaches the number each project is really gated by — applied to every project that declared the limit being overridden, and to no project that declared none, because overriding a decision and reversing one are not the same act.

Every complaint from resolution is collected rather than thrown at the first one, so a command line with two mistakes is two mistakes to fix, not two runs.

命令行值与配置值之间的每一种组合，都会在同一个位置

FlagResolutionService

中按照同一条规则解析：

改变一次运行评判什么或写入什么的 flag，只能覆盖配置已经声明的值。选择模式或展示形式的 flag 仅限命令行使用，因为二者都不能让配置不完整的运行变得合法。

--check

、

--write

和

--format

决定模式或展示形式，因此绝不会被写入配置。

--config

两者皆非：它负责选择其余所有内容所依据的文件，因此当其余解析开始时，它已经完成了全部工作。其他所有 flag 都是覆盖项，而覆盖项只能回答配置已经提出的问题：路径 flag 只替换已声明目标的

path

，并保留其 heading、description、anchors 和 hooks；

--maximum-breadth

无法凭空创造项目自身文件未设置的限制，正如

--json

无法凭空创造 workspace 文件从未声明的

write.json

一样。限制覆盖项会作用于每个确实声明了相应限制的项目，而不会作用于任何未声明该限制的项目，因为覆盖一个决定与撤销一个决定并不是同一操作。

解析过程中的所有问题都会被一并收集，而不是遇到第一个就立即抛出；因此，包含两处错误的命令行需要修复两处问题，而不需要运行两次。

--check

takes a set, and the set matters

--check

接收一组值，而这组值很重要

Value	What fails the run
`depth`	A call stack deeper than `limits.maximumDepth`
`breadth`	A callable calling more callables directly than `limits.maximumBreadth`
`reports`	A configured destination no longer holding what a fresh run would write

Two refusals to expect, both deliberate:

--check
with no value is refused. A set with nothing in it is indistinguishable from the flag left off, so
```
--check "$GATES"
```
with the variable unset would pass forever over a stack twice as deep as anything allowed — worse than no gate, because it looks like protection.
An unrecognized value is refused, and the message lists what is accepted.

值	导致运行失败的情况
`depth`	调用栈深度超过 `limits.maximumDepth`
`breadth`	一个可调用项直接调用的可调用项数量超过 `limits.maximumBreadth`
`reports`	已配置的目标位置不再包含新一次运行将会写入的内容

需要预期两种拒绝情况，二者都是有意设计的：

不带值的
--check
会被拒绝。没有任何值的集合与完全省略该 flag 无法区分，因此当变量未设置时，
```
--check "$GATES"
```
会对一个深度达到允许值两倍的调用栈永远通过；这比没有门禁更糟，因为它看起来像是存在保护。
无法识别的值会被拒绝，错误消息会列出所有可接受的值。

Why

depth

and

reports

belong on opposite sides of a pull request

为什么

depth

和

reports

应位于 PR 流程的两侧

Depth is the gate. A stack got longer in this change, and this change is what fixes it. Run it on every pull request, and on every commit if you like — depth reads source and needs no build, which is what keeps it cheap enough for a commit hook.

bash

npx callidescope --check depth

In an Nx workspace, prefer the per-project
gate
target to this flag. A whole-workspace

--check depth

reaches the right verdict the expensive way: one uncacheable run over the repository on every commit.

@callidescope/nx

infers a

gate

onto each project instead, tracing it with its Nx dependencies and failing only on the findings that project owns, so

nx affected --target=gate

judges what a change touched and nothing else. Depth is gated on every project, since it has a default; breadth is gated only on a project whose own

callidescope.config.ts

declares

limits.maximumBreadth

. The flag remains the answer without Nx.

Staleness is not a gate. A report goes stale whenever the call graph moves anywhere, which is nearly every change, so gating on it fails pull requests for drift they did not cause. Publish on the default branch instead, where nothing else competes to rewrite the same block:

bash

npx callidescope --write

--write --check reports

is refused outright: a report cannot be stale in the run that just wrote it, so it would pass whatever it was meant to catch. Name the gate directly alongside whatever else gates a pull request, not off a lint-style aggregate that might one day forward

--configuration=write

from a branch.

depth
是门禁。某次变更让调用栈变得更长，而这次变更也正是修复它的地方。可以在每个 PR 上运行它；如果愿意，也可以在每次 commit 上运行。

depth

只读取源代码，不需要构建，这正是它足够轻量、适合用于 commit hook 的原因。

bash

npx callidescope --check depth

在 Nx workspace 中，应优先使用每个项目自己的
gate
target，而不是这个 flag。对整个 workspace 执行

--check depth

也能得出正确结论，但采用的是代价高昂的方式：每次 commit 都要对整个 repository 进行一次无法缓存的运行。

@callidescope/nx

则会为每个项目自动推导

gate

，结合其 Nx dependencies 进行 trace，并且只在失败项确实属于该项目本身时判定失败；因此，

nx affected --target=gate

只评判变更触及的项目，不会评判其他项目。每个项目都会受到

depth

门禁，因为它具有默认值；只有项目自己的

callidescope.config.ts

声明了

limits.maximumBreadth

时，才会受到

breadth

门禁。如果没有 Nx，该 flag 仍然是适用的解决方案。

报告过期不是门禁。 只要调用图中的任何位置发生变化，报告就可能过期，而这几乎发生在每次变更中；因此，对报告过期设置门禁，会因为并非本次变更造成的漂移而使 PR 失败。应在默认分支上发布报告；在那里，没有其他流程会竞争重写同一区块：

bash

npx callidescope --write

--write --check reports

会被直接拒绝：刚刚写入报告的同一次运行中，报告不可能过期，否则它就会通过，而无法捕获原本要检测的问题。应将门禁直接与其他 PR 门禁并列指定，不要依赖某种 lint 风格的聚合门禁，因为后者将来可能会从某个分支转发

--configuration=write

。

--directories

, and why a run is slow without it

--directories

，以及不指定它时运行缓慢的原因

The difference between a whole-workspace analysis and a check that finishes in seconds. Each directory named needs its own

tsconfig.json

, and the programs built are those plus every project they transitively import, so a call into a dependency still resolves to a real frame:

bash

npx callidescope -d packages/foo,packages/bar --check depth

Omit it and callidescope walks the working directory for every

tsconfig.json

it finds — the workspace-wide picture, not an answer about one package.

It takes paths, not project names: callidescope knows nothing of workspace tooling, and a directory holding a

tsconfig.json

is the whole contract. The same list can be set once as

directories

in the workspace configuration file.

There is a real trade-off when narrowing a

breadth

lookup: callers outside the named directories and the closure below them do not exist to the run, since the closure runs downward and a dependent that calls in is never built. For a rename whose blast radius is the point, trace wide enough to contain every consumer.

An Nx workspace can hand the selecting to Nx instead, through the separate

@callidescope/nx

plugin, which infers

trace

depth

breadth

, and

gate

targets onto every project and traces each one with its Nx dependencies, so those are projects the run is scoped to rather than ones it merely reached through a closure. The first three only print;

gate

decides an exit code and is what a branch runs. An excluded project keeps the three that print and is denied the gate, since its own code is never traced. It is a separate package on purpose: this CLI depends on nothing Nx-shaped.

它决定了整个工作区分析与几秒内完成的检查之间的差异。每个指定目录都需要自己的

tsconfig.json

，而构建出的 programs 包括这些目录及其传递导入的所有项目；因此，对依赖项的调用仍会解析为真实的栈帧：

bash

npx callidescope -d packages/foo,packages/bar --check depth

省略它时，callidescope 会遍历工作目录，查找它能找到的每一个

tsconfig.json

；这样得到的是整个 workspace 的视图，而不是针对某一个 package 的答案。

它接收的是路径，而不是项目名称：callidescope 不了解任何 workspace 工具，拥有

tsconfig.json

的目录就是完整约定。同一个列表也可以在工作区配置文件中通过

directories

一次性设置。

缩小

breadth

查询范围时确实存在取舍：指定目录及其下方闭包之外的调用方对本次运行而言并不存在，因为闭包只向下延伸，而调用进入该目录的上游 dependent 不会被构建。对于重命名任务，如果其影响范围正是关注重点，就应 trace 到足以包含所有使用方的范围。

Nx workspace 还可以通过独立的

@callidescope/nx

插件，把选择过程交给 Nx。该插件会为每个项目推导

trace

、

depth

、

breadth

和

gate

target，并结合各项目的 Nx dependencies 进行 trace；因此，这些项目属于运行明确限定的范围，而不是仅仅通过依赖闭包触及到的项目。前三个 target 只负责打印；

gate

决定退出码，也是分支实际运行的 target。被排除的项目仍保留前三个打印 target，但不会被允许运行

gate

，因为它自身的代码从未被 trace。之所以将它设计为独立 package，是因为这个 CLI 不依赖任何 Nx 形态的组件。

--format

decides what prints, not what is written

--format

决定打印什么，而不决定写入什么

Printing and writing are independent, and both can be on at once.

--format

names one of

markdown

(the default),

mermaid

, or

json

for standard output; the destinations declared under a project's or the workspace's own

write

decide what reaches a file.

markdown

leads because it is the one rendering that reads in a terminal, pastes into an issue, and is already what the files hold. There is no

write.format

field — the console rendering is a command-line concern only.

打印与写入彼此独立，而且可以同时启用。

--format

为标准输出指定

markdown

（默认）、

mermaid

或

json

；项目自身配置或工作区自身配置中

write

下声明的目标位置，则决定哪些内容会写入文件。以 Markdown 为主，是因为它是唯一既能直接在终端中阅读、又能粘贴到 issue 中，而且已经用于现有文件内容的渲染形式。不存在

write.format

字段；控制台渲染方式只属于命令行关注点。

Prompting, and why it will not hang a script

提示输入，以及为什么它不会使脚本挂起

callidescope

depth

, and

breadth

all prompt for a value left off the command line —

depth

and

breadth

for a missing

--addresses

, all three for a missing

--format

. There is no flag to turn that off, because an attached terminal is the whole condition: a script, a hook, or a CI job never has one and so is never prompted. A missing

--addresses

is then refused, exit non-zero, since nothing else can supply it; a missing

--format

falls back to its default,

markdown

, and the run proceeds.

The refusal is the load-bearing half.

prompts

does not fail on a non-terminal stdin — it draws its menu, never resolves, and lets the process exit 0 having done nothing — so a required value asserts a terminal before prompting at all and reports a rejected command line instead. Without it, a CI run that forgot an argument would read as a green one.

对于命令行中遗漏的值，

callidescope

、

depth

和

breadth

都会提示输入：

depth

和

breadth

会在缺少

--addresses

时提示，三者都会在缺少

--format

时提示。没有任何 flag 可以关闭提示，因为附加了终端这一条件本身就是全部依据：脚本、hook 或 CI job 不会有终端，因此永远不会被提示。在非交互环境中，缺失的

--addresses

会被拒绝并以非零状态退出，因为没有其他方式可以提供它；缺失的

--format

则会回退到默认值

markdown

，并继续运行。

拒绝行为才是其中真正承担关键作用的部分。

prompts

在 stdin 不是终端时不会失败：它会绘制菜单，却永远无法解析出结果，并让进程在什么都没做的情况下以 0 退出。因此，所需值会先确认存在终端，然后才尝试提示；一旦不满足条件，就直接报告命令行已被拒绝。否则，一个忘记传参的 CI 运行会显示为绿色。

The workspace configuration file

工作区配置文件

Any of

callidescope.config.{ts,mts,cts,js,mjs,cjs,json,jsonc}

, searched for upward from the working directory, TypeScript first because that is the form that gets type checking. This is the workspace configuration — the file a run is pointed at. A repository with none is traced with defaults rather than told to write one.

import { type CallidescopeConfiguration } from "@callidescope/configuration";

const callidescopeConfiguration: CallidescopeConfiguration = {
  excludeFrom: ["configuration/.callidescopeignore"],
  limits: { maximumDepth: 6 },
};

export default callidescopeConfiguration;

The whole surface is seven top-level keys:

directories

entryPoints

exclude

excludeCallees

excludeFrom

limits

, and

write

. The workspace file also exports

projectDefaults

alongside its default export — a separate binding, not a member of this type — for a project's own

callidescope.config.ts

to spread.

可以使用

callidescope.config.{ts,mts,cts,js,mjs,cjs,json,jsonc}

中的任意一种格式。工具会从工作目录向上查找，并优先使用 TypeScript，因为这种形式可以获得类型检查。这是工作区配置，也就是一次运行所指向的文件。没有任何配置的 repository 仍会使用默认设置进行 trace，而不会被要求先编写一个配置文件。

import { type CallidescopeConfiguration } from "@callidescope/configuration";

const callidescopeConfiguration: CallidescopeConfiguration = {
  excludeFrom: ["configuration/.callidescopeignore"],
  limits: { maximumDepth: 6 },
};

export default callidescopeConfiguration;

整个配置界面包含七个顶层键：

directories

、

entryPoints

、

exclude

、

excludeCallees

、

excludeFrom

、

limits

和

write

。工作区文件还会在默认导出之外导出

projectDefaults

，供项目自己的

callidescope.config.ts

展开使用；它是独立的绑定，并不是该类型的一个成员。

limits

limits

There are two, both per project, both gated.

Limit	Default	Meaning
`maximumDepth`	`6`	Frames a call stack may hold, entry point inclusive
`maximumBreadth`	none	Callables one callable may call directly

maximumBreadth
has no default, on purpose. Until something picks a number, breadth is reported without being gated, and

--check breadth

is refused rather than falling back to an unbounded limit that looks exactly like passing. It also takes a project's own number, never a workspace one alone — see What a project may set.

Picking a first

maximumDepth

: run once with no gate, read the deepest stacks, and set the limit at the shape you want rather than at whatever the code currently is — a limit set to today's worst number gates nothing.

Per project, pick each one by boundary-testing rather than by reading a number off a run. Write a candidate, run that project's gate, then run it one lower: a limit worth having passes at the number written and fails at one below. A scoped run's printed summary covers the whole trace, dependency closure included, so the depth it reports is routinely deeper than anything the judged project owns — only a gate's verdict knows which findings belong to the project.

A limit is a schema field and nothing else now. The schema is strict, and

limits

accepts only

maximumDepth

and

maximumBreadth

. A retired field —

spreadThreshold

directSpreadThreshold

minimumCallers

callerMajorityRatio

— is refused rather than silently stripped. Those four limits, the two findings they tuned, and the module-identity concept behind them are gone from the tool entirely — see the repository's ADR 0006, "Narrow callidescope to depth and breadth".

The implementation-candidate cap is a constant, not a configuration field. It decides where structural interface resolution stops guessing, which is a property of the resolution rather than a number any run judges by, so it lives in

@callidescope/graph

and is not written anywhere in

callidescope.config.ts

这里有两个限制，二者都按项目设置，也都用于门禁。

限制	默认值	含义
`maximumDepth`	`6`	调用栈最多允许包含的栈帧数量，包含入口点
`maximumBreadth`	无	一个可调用项可直接调用的可调用项数量

maximumBreadth
有意不设默认值。在明确选择数值之前，

breadth

只会出现在报告中而不会受到门禁；

--check breadth

会被拒绝，而不会回退到一个看起来与通过完全相同的无限限制。它只采用项目自身声明的数值，绝不会单独采用工作区数值，详见项目可以设置哪些内容。

首次选择

maximumDepth

时：先不带门禁运行一次，查看最深的调用栈，并将限制设置为你希望代码呈现的形状，而不是当前代码恰好达到的数值；如果把限制设为今天的最差数值，它就几乎无法门禁任何东西。

按项目分别选择限制时，应采用边界测试，而不是直接采用某次运行显示的数值。 写下一个候选值，运行该项目的 gate，再把限制降低一级运行一次：一个真正有价值的限制，应当在写下的数值上通过，并在低一级的数值上失败。限定范围的运行所打印摘要涵盖整个 trace，包括依赖闭包，因此它报告的深度通常比被评判项目自身拥有的任何调用栈都深；只有 gate 的判定结果知道哪些 findings 属于该项目。

目前，限制仅是 schema 字段，不承担其他职责。 Schema 是严格的，

limits

只接受

maximumDepth

和

maximumBreadth

。已经退役的字段——

spreadThreshold

、

directSpreadThreshold

、

minimumCallers

、

callerMajorityRatio

——会被拒绝，而不是被静默移除。这四个限制、它们调节的两类 findings，以及背后的模块身份概念，都已从工具中彻底移除；详见 repository 的 ADR 0006《Narrow callidescope to depth and breadth》。

实现候选上限是常量，而不是配置字段。 它决定结构化接口解析在何处停止猜测。这是解析过程本身的属性，并不是任何运行用于判定结果或门禁的数值，因此它位于

@callidescope/graph

中，不会写入任何

callidescope.config.ts

。

entryPoints

entryPoints

Option	Default	Meaning
`addresses`	none	Callables named outright as roots, each `<file>#<qualified-name>`
`decorators`	13 framework decorators	Decorators whose methods a framework invokes
`includeExportedFunctions`	`true`	Treat every `src/index.ts` export as a root
`includeOrphans`	`true`	Promote callables nothing in the repository calls
`includeTests`	`false`	Trace test files too

addresses
is how a package states the surface it means to be measured on, in the same

<file>#<qualified-name>

form

depth

and

breadth

accept and every frame prints, so an address is copied out of a report straight into the configuration — with a trailing

:<line>

when one file declares the name twice:

entryPoints: {
  addresses: ["packages/foo/src/modules/read/read.service.ts#ReadService.read"],
},

Declared addresses add roots and take none away: the rules below still run first, orphan promotion still catches whatever nobody named, and an already-rooted callable stays one root.

Reach for it when a package sits low in the graph: a stack is filed under the project owning its root, and most of what such a package publishes is called from above, so it roots nothing and any limit on it gates nothing. An address resolving to nothing, to several declarations, or to nothing parseable fails the whole run —

callidescope-triage

carries each message and its fix.

decorators

replaces the built-in list rather than adding to it, so a configuration naming its own framework's decorator should restate the ones it still wants — a report where nearly everything is an orphan root usually means the decorators in use are missing from it.

includeOrphans
is a safety net rather than a feature. Without it, a missing entry-point rule silently removes whole subtrees from every measurement; with it they surface as orphan roots — either dead code, or a rule that needs adding.

选项	默认值	含义
`addresses`	无	明确指定为根节点的可调用项，每个地址的格式为 `<file>#<qualified-name>`
`decorators`	13 个框架 decorator	其方法会被框架调用的 decorator
`includeExportedFunctions`	`true`	将每个 `src/index.ts` 的导出都视为根节点
`includeOrphans`	`true`	将 repository 中无人调用的可调用项提升为根节点
`includeTests`	`false`	同时 trace 测试文件

addresses
是一个 package 声明其预期测量范围的方式，采用与

depth

和

breadth

所接受格式以及每个栈帧打印格式相同的

<file>#<qualified-name>

。因此，可以把报告中的地址直接复制到配置中；如果一个文件声明了两次同名项，则地址末尾会附带

:<line>

：

entryPoints: {
  addresses: ["packages/foo/src/modules/read/read.service.ts#ReadService.read"],
},

声明的 addresses 只会增加根节点，不会移除根节点：下面的规则仍会先行执行，orphan 提升仍会捕获所有未命名项，而已经成为根节点的可调用项仍只保留一个根节点身份。

当一个 package 位于调用图底层时，应使用它：调用栈会归入拥有其根节点的项目，而这类 package 发布的多数内容都从上层调用，因此它不会产生根节点，针对它的任何限制也就不会产生门禁效果。如果一个地址无法解析、解析到多个声明，或完全没有可解析内容，整次运行都会失败；

callidescope-triage

会给出每条消息及其修复方法。

decorators

会替换内置列表，而不是向其中追加。因此，如果配置声明了自有框架的 decorator，就应重新列出仍然需要保留的其他 decorator；报告中几乎所有内容都成为 orphan root，通常意味着正在使用的 decorator 没有包含在列表中。

includeOrphans
是一张安全网，而不是一项功能。如果不启用它，遗漏入口点规则会悄无声息地从每次测量中移除整棵子树；启用后，这些内容会以 orphan root 的形式显现出来——它们要么是死代码，要么表明需要补充规则。

Keeping code out of a run

让代码不参与运行

Two tools, for two different questions:

exclude
takes globs and is additive to the built-in defaults (
```
node_modules
```
,
```
dist
```
,
```
coverage
```
,
```
output
```
,
```
.nx
```
,
```
.conformetry
```
), so a configuration naming its own noise does not restate them.
excludeFrom
names gitignore-syntax files, workspace-only. This is how a long exclusion list stays out of the configuration file itself, and it is the right home for fixture packages written to be deliberately bad.
excludeCallees
takes globs matched against a callable's display name (
```
Type.member
```
) and drops matching calls from the graph entirely, counting toward neither depth nor breadth. This is for cross-cutting instrumentation: a call to a logger is a fact about instrumentation rather than about the shape of the code around it, and counting it would move every other callable's numbers on a change that has nothing to do with them.

exclude

and

excludeFrom

drop files from collection;

excludeCallees

drops edges, and reaching for the first when you meant the second deletes real findings. Neither leaves the

ts.Program

: an excluded file is still compiled, a call into it becomes unfollowable rather than vanishing, and no

exclude

can un-project a directory holding a

tsconfig.json

. A project's own

exclude

behaves the same way.

这里有两种工具，分别回答两个不同的问题：

exclude
接受 glob，并且会叠加到内置默认项（
```
node_modules
```
、
```
dist
```
、
```
coverage
```
、
```
output
```
、
```
.nx
```
、
```
.conformetry
```
）之上。因此，配置只需声明自有噪声项，无需再次列出这些默认值。
excludeFrom
指定采用 gitignore 语法的文件，并且仅限工作区使用。较长的排除列表可以因此留在配置文件之外；这里也是存放那些故意编写得很糟糕的 fixture package 的合适位置。
excludeCallees
接受根据可调用项显示名称（
```
Type.member
```
）匹配的 glob，并从调用图中彻底移除匹配调用，调用它们既不计入
```
depth
```
，也不计入
```
breadth
```
。这项能力适用于横切式插桩：例如，对 logger 的调用反映的是插桩事实，而不是周围代码的形状；如果将其计数，那么与这些调用无关的变更也会改变其他每个可调用项的数值。

exclude

和

excludeFrom

会从收集阶段移除_文件_；

excludeCallees

会移除_边_。如果本想移除边却使用了前两者，就会删除真实 findings。二者都不会让文件离开

ts.Program

：被排除的文件仍会被编译，对它的调用会变成不可继续追踪，而不会彻底消失；任何

exclude

都无法让一个包含

tsconfig.json

的目录失去项目身份。项目自身的

exclude

行为也完全相同。

directories

directories

The same list

--directories

takes, set once, workspace-only.

与

--directories

相同，只是通过工作区配置一次性设置，且仅限工作区使用。

write

write

Every destination is optional, and unconfigured is the normal case: a run naming no destination reports to the console and exits non-zero on violations, so nothing it writes can go stale.

Key	Purpose
`write.json`	A machine-readable report at `path` , indented by `indentation` . Workspace-only
`write.markdown`	A marker-delimited block spliced into `path`
`write.mermaid`	The same block with the stacks drawn as one flowchart

write.mermaid

takes the same keys as

write.markdown

— they differ in what goes between the markers, not in how a block is placed — and is separate so one run publishes both: the tree says what each frame takes, returns, and documents, the diagram what shape they make together.

write: {
  json: { indentation: 2, path: "output/callidescope.json" },
  markdown: { path: "docs/call-stacks.md" },
  mermaid: { path: "docs/call-stacks-diagram.md" },
},

Both take a

description

, placed under the heading, a

heading

(defaults to

# 🔭 Callidescope

, and should be set when the block is spliced into a file that already has a title, since most markdown linters reject a second first-level heading), and

previewCount

— how many stacks are shown before the rest go behind a disclosure, three by default.

previewCount

belongs to the destination rather than to the run because it is a fact about the document the block lands in: a project's own README wants three and a whole-workspace report file wants all of them. A whole-run block opens with the summary counts, one row per project against its own depth limit, and a scoreboard of how many sit over, on, or clear of theirs; the findings tables follow.

There is no fan-out that writes a section into every project's readme. Each project declares its own

write.markdown

(and

write.mermaid

, if it wants a diagram) in its own

callidescope.config.ts

— see What a project may set. The workspace's own

write.markdown

is the block that really is about the workspace: the summary counts, one row per project against its own depth limit, and the scoreboard.

A markdown destination may also supply

render

, to replace the built-in tables, or

writeBlock

, to place the block itself — handed

syncAnchoredBlock

and

wrapInAnchors

, so it reuses the same splice. Returning
false
reports the destination as stale; anything else,

undefined

included, counts as current.

每个目标位置都是可选的，未配置属于正常情况：没有指定目标位置的运行会向控制台报告结果，并在发现违规时以非零状态退出，因此它所写的内容不会过期。

键	用途
`write.json`	在 `path` 处生成机器可读报告，并按 `indentation` 缩进。仅限工作区使用
`write.markdown`	将带有标记分隔符的区块嵌入 `path`
`write.mermaid`	使用相同区块，但将调用栈绘制为一张 flowchart

write.mermaid

接受与

write.markdown

相同的键；二者区别仅在于标记之间的内容，而不在于区块的放置方式。之所以将二者分开，是为了允许一次运行同时发布两种报告：树状报告说明每个栈帧接收什么、返回什么、记录了什么，图表则展示这些栈帧共同形成的结构。

write: {
  json: { indentation: 2, path: "output/callidescope.json" },
  markdown: { path: "docs/call-stacks.md" },
  mermaid: { path: "docs/call-stacks-diagram.md" },
},

二者都可提供

description

，内容会放在 heading 下方；还可提供

heading

，默认值为

# 🔭 Callidescope

。当区块被嵌入一个已经有标题的文件时，应设置 heading，因为大多数 Markdown linter 都不允许出现第二个一级标题。二者还可提供

previewCount

，用于指定在将其余调用栈放入 disclosure 之前显示多少个，默认是三个。

previewCount

属于目标位置，而不是整次运行，因为它描述的是最终承载该区块的文档：项目自己的 README 可能只展示三个，而整个工作区的报告文件可能希望展示全部。整次运行的区块开头会显示汇总计数、每个项目相对于自身深度限制的一行结果，以及超过、等于或低于各自限制的项目数量统计；随后才是 findings 表格。

不存在把某个区块写入每个项目 README 的扇出机制。 每个项目都在自己的

callidescope.config.ts

中声明自己的

write.markdown

（如果需要图表，还需声明

write.mermaid

），详见项目可以设置哪些内容。工作区自身的

write.markdown

对应的才是真正面向整个工作区的区块：汇总计数、每个项目相对于自身深度限制的一行结果，以及相应的统计信息。

Markdown 目标位置还可以提供

render

，用于替换内置表格；或者提供

writeBlock

，用于放置区块本身。该函数会收到

syncAnchoredBlock

和

wrapInAnchors

，从而复用相同的嵌入机制。返回
false
会将目标位置报告为过期；其他任何返回值，包括

undefined

，都视为内容为最新。

Every traced project's own configuration is required and complete

每个被追踪项目自身的配置都是必需且完整的

A second

callidescope.config.ts

sits at each traced project's own root, the directory holding the

tsconfig.json

that makes it a project, found by name in that directory alone with no upward walk, in any of the same eight extensions.

Every traced project has one, and every one of them is complete. A traced project with no configuration file at all is refused by name, and so is a file that leaves a field out. Completeness is deliberate: an absent field and a field set to the value it would have defaulted to look identical in a diff, and only one of them was a decision —

maximumBreadth

absent and

maximumBreadth: undefined

used to mean "somebody forgot" and "this project gates depth and not breadth" respectively, and per-field fallback could not tell them apart. See the repository's ADR 0007, "Require a complete configuration from every traced project".

The file a run was pointed at is never also read as a project's — one file, one role per run. A package whose task names its own configuration and then traces itself would otherwise have it refused for the workspace-only fields it legitimately sets, so a package needing both keeps two files under two names.

每个被追踪项目的根目录中还有第二个

callidescope.config.ts

。该项目根目录就是包含

tsconfig.json

、从而使该目录成为项目的目录。该文件只按名称在这个目录中查找，不向上查找，并支持前述八种扩展名中的任意一种。

每个被追踪项目都有一个这样的文件，而且每个文件都是完整的。 完全没有配置文件的被追踪项目会被按名称拒绝，遗漏任何字段的文件也会被拒绝。完整性要求是有意为之：缺失字段与把字段设置为默认值时，在 diff 中看起来完全相同，但二者只有一个代表明确决定。过去，

maximumBreadth

缺失和

maximumBreadth: undefined

会分别被理解为“有人忘了写”和“该项目只对 depth 设置门禁、不对 breadth 设置门禁”，按字段回退无法区分二者。详见 repository 的 ADR 0007《Require a complete configuration from every traced project》。

一次运行所指向的文件绝不会被同时当作项目配置读取；一次运行中，一个文件只承担一个角色。如果某个 package 的 task 声明了自己的配置，随后又 trace 自己，那么该文件会因为包含仅限工作区使用的合法字段而被拒绝。因此，需要同时具备两种角色的 package 应在两个不同名称下保留两个文件。

What a project may set

项目可以设置哪些内容

Field	What it does
`entryPoints`	Which of that project's callables root a stack, `addresses` included
`limits.maximumDepth`	The depth every stack rooted in that project is judged against
`limits.maximumBreadth`	The breadth every callable that project declares is judged against
`exclude`	Globs naming that project's own files to leave untraced
`write.markdown`	Where that project's own published section goes
`write.mermaid`	Where that project's own diagram goes, when it wants one

A project's own destinations and
exclude
globs are anchored to that project's root, never to the workspace:

exclude: ["src/generated/**"]

packages/thing

's own file names

packages/thing/src/generated/**

, and

write: { markdown: { path: "docs/CALLS.md" } }

there writes

packages/thing/docs/CALLS.md

. No spelling of either reaches a sibling. A destination left

undefined

publishes nothing for that project.

The run's own

exclude

stays workspace-relative and is layered underneath, so a project can leave more out and never put back what the run left out. Noise spanning several projects still belongs in the workspace file.

write.json

stays workspace-only: it is the run's single report, not a project's to redirect.

Every other field is refused by name, before anything is traced, and the message names the six above so it is actionable without opening this skill.

字段	作用
`entryPoints`	指定该项目中哪些可调用项成为调用栈根节点，包括 `addresses`
`limits.maximumDepth`	评判以该项目为根节点的所有调用栈时采用的深度限制
`limits.maximumBreadth`	评判该项目声明的每个可调用项时采用的广度限制
`exclude`	指定不 trace 该项目自身哪些文件的 glob
`write.markdown`	该项目自己发布的区块写入何处
`write.mermaid`	该项目自己的图表写入何处；如果项目需要图表则可设置

项目自身的目标位置和
exclude
glob 始终以该项目根目录为基准，绝不会以工作区为基准：例如，

packages/thing

自身文件中的

exclude: ["src/generated/**"]

指向

packages/thing/src/generated/**

，同一文件中的

write: { markdown: { path: "docs/CALLS.md" } }

则写入

packages/thing/docs/CALLS.md

。无论采用哪种写法，都无法影响 sibling project。目标位置保持为

undefined

时，该项目不会发布任何内容。

本次运行自身的

exclude

仍以工作区为基准，并作为底层规则叠加其上。因此，项目可以排除更多内容，但无法恢复已被本次运行排除的内容。跨越多个项目的噪声仍应放在工作区文件中。

write.json

仍仅限工作区使用：它是整次运行唯一的报告，不能由单个项目重定向。

其他所有字段都会在开始 trace 之前按名称被拒绝，错误消息会列出上表中的六个字段，使操作无需打开本 skill 也能明确。

Spread the defaults, then override

先展开默认值，再进行覆盖

The workspace configuration exports

projectDefaults

beside its default export. A project spreads it and overrides what it means to, which is what makes a complete file cost one line:

import { projectDefaults } from "../../configuration/callidescope.config.js";

export default {
  ...projectDefaults,
  limits: { maximumBreadth: undefined, maximumDepth: 10 },
};

Both limits are named even though only one is a real number.

maximumBreadth: undefined

is this project saying outright that it gates depth and not breadth — the one statement an absent field could never distinguish from a project that forgot. The same holds for

write.mermaid: undefined

and publishing no diagram.

Spread
projectDefaults
, never the workspace's default export. The two are different objects on purpose: the default export carries

directories

excludeFrom

write.json

, and the rest of what only the workspace may set, so spreading it earns a refusal naming the first such field.

projectDefaults

holds exactly the surface a project is entitled to, so spreading it cannot adopt an output destination or an ignore file by accident.

Nothing is resolved across two files, and there is no longer a record of where a number came from. Every number a project is judged by is written in that project's own file — there is no per-field fallback to the workspace once a project's file exists, and no

declared

versus

inherited

distinction left to draw, because the spread already put the number here where a reader can see it. Documentation that still talks about a limit being "inherited", or a project readme carrying an "Origin" column, describes the tool before this requirement — see the

callidescope-triage

skill for the refusal this replaced.

The workspace number

projectDefaults

carries is a default rather than a ceiling: a project spreading it and then overriding to a higher limit keeps its own, because a workspace number pinned by the single worst stack anywhere gates nothing for the projects nowhere near it.

entryPoints

is replaced whole rather than merged member by member: writing an

entryPoints

object of its own replaces the spread one outright for that project's callables, so a project that wants the workspace's decorator list alongside its own

addresses

has to carry the decorator list across explicitly, via

...projectDefaults.entryPoints

Why the other fields cannot vary per project.

maximumDepth

and

maximumBreadth

judge a call graph built once, so two projects asking different questions of the same edges is coherent.

excludeCallees

directories

excludeFrom

, and

write.json

are different: they name what a run reads, where its own report lands, or how it partitions the workspace, and a project cannot answer those differently from the run tracing it.

工作区配置会在默认导出之外导出

projectDefaults

。项目展开它，再覆盖自己需要覆盖的内容；这使一个完整文件只需增加一行：

import { projectDefaults } from "../../configuration/callidescope.config.js";

export default {
  ...projectDefaults,
  limits: { maximumBreadth: undefined, maximumDepth: 10 },
};

虽然两个限制中只有一个是实际数值，但二者都必须明确写出。

maximumBreadth: undefined

表示该项目明确只对 depth 设置门禁、不对 breadth 设置门禁；这是缺失字段永远无法与“项目忘记填写”区分开的唯一明确声明。

write.mermaid: undefined

以及不发布图表，也遵循同样的原则。

应展开
projectDefaults
，绝不能展开工作区的默认导出。二者有意使用不同对象：默认导出包含

directories

、

excludeFrom

、

write.json

以及其他仅限工作区设置的内容，因此展开它会立刻触发拒绝，并指出第一个不允许的字段。

projectDefaults

恰好包含项目有权设置的界面，因此展开它不会意外继承输出目标或 ignore 文件。

不会跨两个文件解析任何内容，也不再保留数值来源记录。 项目评判所依据的每个数值都写在项目自己的文件中；一旦项目文件存在，就不会按字段回退到工作区设置，也不再需要区分

declared

与

inherited

，因为展开操作已经将数值放在读者可以看到的当前位置。仍在讨论限制被“继承”的文档，或仍带有 “Origin” 列的项目 README，描述的都是这项要求出现之前的工具；关于它所替代的拒绝行为，请参阅

callidescope-triage

skill。

projectDefaults

中携带的工作区数值是一个默认值，而不是上限：项目展开它之后可以覆盖为更高的限制，并保留自己的数值；因为由整个 workspace 中最差调用栈决定的统一上限，对那些与其相距很远的项目根本起不到门禁作用。

entryPoints

会整体替换，而不是逐个成员合并：项目一旦编写自己的

entryPoints

对象，就会完全替换展开得到的对象。因此，如果项目希望在工作区 decorator 列表之外再加入自己的

addresses

，就必须通过

...projectDefaults.entryPoints

显式携带 decorator 列表。

为什么其他字段不能按项目变化。

maximumDepth

和

maximumBreadth

用于评判同一份只构建一次的调用图，因此两个项目针对同一批边提出不同问题是可以理解的。

excludeCallees

、

directories

、

excludeFrom

和

write.json

则不同：它们定义一次运行读取什么、自己的报告写到哪里，或如何划分工作区；项目不能针对同一次 trace 给出不同答案。

Reading the whole set back

回读完整集合

A ratchet written one file per project is no longer reviewable in the single file it used to live in. The

limits

command is where it is reviewable as a set instead:

bash

npx callidescope limits

A markdown table, one row per project per limit —

Project

Limit

Value

Declared in

— naming the file each number is written in.

none

means nothing anywhere declares that limit, the usual case for breadth. The

workspace

row comes first and is the only one that may carry no file: it is the default every project's own file spreads, not a number any file wrote down for itself. It resolves configuration and measures nothing, so it costs milliseconds rather than a trace.

如果棘轮式约束改成每个项目一个文件，就无法再像过去那样在单个文件中完成审查。

limits

命令可以按集合形式进行审查：

bash

npx callidescope limits

它会输出一个 Markdown 表格，每个项目的每项限制各占一行——

Project

、

Limit

、

Value

、

Declared in

——并指出写入相应数值的文件。

none

表示任何地方都没有声明该限制，这也是

breadth

的常见情况。

workspace

行位于最前面，并且是唯一可能没有对应文件的行：它表示每个项目自身文件所展开的默认值，而不是任何文件为自己明确写下的数值。该行只解析配置，不执行任何测量，因此只需数毫秒，而不必执行 trace。

After changing any of this

修改这些内容之后

A configuration change usually moves the numbers, making every committed report stale. Re-run the write configuration in the same change, and lint before regenerating: every frame carries a

file:line

, so a formatter that sorts class members moves the line numbers after it, and a report written before that sort is stale the moment it lands.

When a run is refused or a report reads stale, reach for

callidescope-triage

. To read what a run printed, reach for

callidescope-trace

配置变更通常会改变数值，从而使所有已提交报告过期。应在同一次变更中重新运行 write 配置，并且先执行 lint，再重新生成报告：每个栈帧都带有

file:line

，因此，如果 formatter 对 class member 进行了排序，生成报告后行号就会发生变化；在排序前生成的报告会在写入瞬间立刻过期。

当运行被拒绝或报告显示过期时，请使用

callidescope-triage

。要阅读一次运行的输出，请使用

callidescope-trace

。

callidescope-configure

Original

Translation

Telling callidescope what to do

告诉 callidescope 该做什么

The two decisions a run makes

一次运行所做的两个决定

The flags

Flags

One precedence rule governs every override

所有覆盖项都遵循同一条优先级规则

--check takes a set, and the set matters

--check 接收一组值，而这组值很重要

Why depth and reports belong on opposite sides of a pull request

为什么 depth 和 reports 应位于 PR 流程的两侧

--directories, and why a run is slow without it

--directories，以及不指定它时运行缓慢的原因

--format decides what prints, not what is written

--format 决定打印什么，而不决定写入什么

Prompting, and why it will not hang a script

提示输入，以及为什么它不会使脚本挂起

The workspace configuration file

工作区配置文件

limits

limits

entryPoints

entryPoints

Keeping code out of a run

让代码不参与运行

directories

directories

write

write

Every traced project's own configuration is required and complete

每个被追踪项目自身的配置都是必需且完整的

What a project may set

项目可以设置哪些内容

Spread the defaults, then override

先展开默认值，再进行覆盖

Reading the whole set back

回读完整集合

After changing any of this

修改这些内容之后

`--check`
takes a set, and the set matters

`--check`
接收一组值，而这组值很重要

Why
`depth`
and
`reports`
belong on opposite sides of a pull request

为什么
`depth`
和
`reports`
应位于 PR 流程的两侧

`--directories`
, and why a run is slow without it

`--directories`
，以及不指定它时运行缓慢的原因

`--format`
decides what prints, not what is written

`--format`
决定打印什么，而不决定写入什么

`limits`

`limits`

`entryPoints`

`entryPoints`

`directories`

`directories`

`write`

`write`