big-code-analysis

本書には英語版もあります。

big-code-analysis is a Rust library and command line tool (bca) that computes maintainability metrics from source code in many programming languages. It parses with tree-sitter, an incremental parsing library with a grammar per language, so it needs no compiler or language runtime.

This book is task-oriented: metric definitions, the command reference, CI recipes, and guides for the Rust crate and the Python bindings. The source code is on GitHub, and issues and feature requests go to the issue tracker.

対応プラットフォーム

big-code-analysis runs on Linux, macOS, and Windows. The GitHub releases page carries prebuilt binaries for all three.

API ドキュメント

The complete Rustdoc reference for the crate (every public type, trait, and function, including the feature-gated vcs module) lives on docs.rs, generated straight from the source.

For task-oriented guides on embedding the crate (quick start, in-memory analysis, walking FuncSpace results, and error handling), see Using as a Library.

For the PyO3 bindings (pip install big-code-analysis, batch processing, flat-record iteration, SARIF output, and async patterns), see Python Bindings.

ライセンス

• The vendored grammar crates (tree-sitter-ccomment, tree-sitter-mozcpp, tree-sitter-mozjs, tree-sitter-preproc, tree-sitter-tcl) are released under the MIT license.

• big-code-analysis, big-code-analysis-ast, big-code-analysis-cli, big-code-analysis-web, and big-code-analysis-py are released under the Mozilla Public License v2.0.

対応言語

This is the list of programming languages big-code-analysis parses. Each entry is a LANG variant (defined by the mk_langs! invocation in big-code-analysis-ast/src/langs.rs) and is gated behind the matching per-language Cargo feature documented in Per-language Cargo features.

• Bash
• C
• C/C++
• C#
• Elixir
• Go
• Groovy
• Irules
• Java
• JavaScript
• Kotlin
• Lua
• Mozcpp
• Mozjs
• Objective-C
• Perl
• Php
• Python
• Ruby
• Rust
• Tcl
• Tsx
• Typescript

Every variant’s slug is its LANG::name, lowercase and punctuation-free so it round-trips through FromStr (C# reports csharp). Some entries are variants of a shared grammar pipeline:

• JavaScript (the upstream tree-sitter-javascript grammar) is the default for .js, .mjs, .cjs, and .jsx files. Mozjs is the Mozilla / SpiderMonkey fork, opt-in: it owns only the .jsm (Firefox module) extension and reports the slug mozjs. The two are metric-equivalent on ordinary JavaScript.
• Tsx is Typescript (upstream tree-sitter-typescript) with JSX syntax enabled and reports the distinct slug tsx.
• Since #721 C has its own variant C (slug c, upstream tree-sitter-c), owning .c and the c emacs mode; the C/C++ variant (slug cpp, upstream tree-sitter-cpp since #720) keeps .cpp / .cc / .h and the rest. .h deliberately stays on Cpp: a C++ header through the C grammar ERROR-cascades on class / template, whereas a C header through the C++ grammar only trips on C++-keyword identifiers.
• The Mozilla/Gecko C++ dialect is the opt-in Mozcpp variant (slug mozcpp), which owns no file extensions and is selected only by name, exactly as Mozjs relates to JavaScript.
• Since #724 Objective-C (slug objc, upstream tree-sitter-objc) owns .m and the objc / objective-c emacs modes. Objective-C++ (.mm) stays on Cpp. These files mix Objective-C and C++, but tree-sitter-objc cannot parse C++ templates, namespaces, or ::. The C++ grammar struggles only with the Objective-C portions, so it gives the better result, using the same trade-off as .h. Metrics for those Objective-C portions remain approximate.

K&R definitions with a wrapped return type

A pre-ANSI (K&R) function definition opens no function space under C or Objective-C when its return type wraps the declarator; int *, char **, struct S *, and a static pointer return all reproduce it:

int *krptr(a, b) int a; int b; { if (a) { return 0; } return 1; }

tree-sitter-c 0.24.2 builds its old-style function definition from a declarator nested inside the old-style declarator, so an outer pointer_declarator is unreachable and the parser prefers a plain declaration that swallows the first parameter declaration, orphaning the body as a bare compound_statement. No ERROR node is produced: the parse silently succeeds wrongly, and there is no dispatch arm missing on our side.

The consequence is that the body’s decisions are charged to the file’s unit space: the line above reports cyclomatic.sum 2 and nom.functions 0, a file-level count no function-level row accounts for. A K&R definition whose return type does not wrap the declarator (int krplain(a, b) int a; int b; { … }) is unaffected, as is any ANSI definition. C/C++ and Mozcpp open no space for either K&R form, because tree-sitter-cpp has no rule for the syntax at all. This is an upstream grammar limitation, tracked here as #1209.

内部ヘルパーバリアント

The following LANG variants are internal helpers, not user-facing languages. They belong to the C-family analysis pipeline (they ride every C-family Cargo feature: cpp, c, and mozcpp) and are not selected directly when analysing source files:

• Ccomment: C/C++ comments.
• Preproc: C/C++ preprocessor macros.

Note: Since #720 the Mozilla/Gecko C++ dialect is exposed as the Mozcpp LANG variant (backed by the vendored bca-tree-sitter-mozcpp crate, pulled in by the opt-in mozcpp feature). It is a public, name-selectable language that owns no file extensions. Unlike the Ccomment / Preproc helpers above, it is not internal.

対応コードメトリクス

This chapter describes every metric that big-code-analysis computes. Each section starts from the original research paper, walks through the algorithm, and explains both how the metric was originally meant to be used and how the industry uses it today. If you are new to software metrics, read the sections in order: the later metrics (the Maintainability Index in particular) are built on the earlier ones (Halstead, Cyclomatic, LOC).

Three framing notes:

• A metric is a measurement, not a verdict. Every number on this page summarises a structural property of source code. None of them measures correctness, productivity, or developer skill. The first question for any metric is “compared with what?”: the same module a month ago, this module versus its siblings, this codebase versus an industry baseline. Absolute thresholds are rough heuristics.
• Most metrics here are computed at three scopes: per function / method, per class or unit-like space, and per file. The underlying tree-sitter parser produces a tree of “spaces” (functions, closures, classes, namespaces, and so on) and every metric is rolled up through that tree.
• オブジェクト指向メトリクスは、オブジェクト指向の構文に対してのみ反応します。 WMC、NPA、NPM は、impl ブロックのない Rust ファイルやクラスのない Python モジュールでは 0 を報告します。これは正しい答えであり、バグではありません。

一覧

ABC

ABC メトリクスは、コード片のサイズを 3 次元ベクトルとして測定します。各成分は 1 種類の操作をカウントします：

• Assignments: anything that stores a value into a variable, including compound assignments (+=, ++) and explicit initialisation.
• Branches: function and method calls. Despite the name, this is not the count of conditional jumps; it is the number of points where control branches out to other code.
• Conditions: boolean tests. These are comparison operators (==, !=, <=, >=, <, >), ternary operators (?), and the fixed keyword set (else, case, try, catch). The default / wildcard arm is not counted in any language (see the per-language deviations below). The short-circuit logical operators && and || are not counted on their own; instead, each non-comparison operand of a && / || chain contributes one condition via Fitzpatrick’s “unary conditional expression” rule. The next subsection walks through the rules, the per-language deviations, and worked examples.

Jerry Fitzpatrick introduced the metric in the 1997 C++ Report article Applying the ABC metric to C, C++ and Java. The current canonical specification, including the rules for what counts as an A, B, or C in modern languages, is maintained on Fitzpatrick’s Software Renovation site.

カウント規則

Fitzpatrick’s paper enumerates the rules in three figures: Figure 2 (C), Figure 3 (C++, which extends Figure 2), and Figure 4 (Java). The tables below summarise the paper’s rule set, with each row attributed to the figure that introduces it. Big-code-analysis implements them per language, with the exceptions listed under Per-language deviations and these paper rows that no language implements today: the delete operator, the goto / labeled break / labeled continue jumps, the preprocessor #else / #elif, and the C++ initializing constructor invocation (S s(1);). Each scores zero.

代入

分岐

条件

The short-circuit logical operators (&&, ||, and the per-language equivalents: Ruby and / or, Python and / or, Perl and / or, Lua and / or, Tcl && / ||, iRules && / || / and / or) do not contribute a condition on their own. Each non-comparison operand contributes one instead, via the unary-conditional rule. Perl and PHP xor evaluate both operands, so like ^ they are a value: the slot holding one pays a single condition. The paper makes this explicit twice:

1. Listing 2 annotates (am >= 0 && am <= 0xF) ? '/' : 'C' as accc: one assignment plus three conditions, where the three conditions are the two comparisons (>=, <=) and the ternary (?). The && itself contributes zero.
2. 一方 Rule 7 / Rule 9 は各オペランドをカウントします。if (x || y) printf("test failure\n"); について、論文は「x と y の両方が条件式として評価されるため、単項条件は 2 つある」と記しています。ここでも || の寄与はゼロで、x と y がそれぞれ 1 ずつ寄与します。

言語別の逸脱

言語ごとの impl Abc ブロックは、その言語に相当する構文がない場合や、論文の規則を字義どおり適用すると過剰カウントになる場合に、規則集合を絞り込んでいます。

Where a constructor call lands

Fitzpatrick’s branch rule is “function invocation or object creation”, so object construction and constructor delegation count as branches even though they are not call sites. They do not appear in bca find --type call, which reports invocations only; see Semantic filters.

Which space a constructor call is charged to depends on how it is spelled, and C# 12 and Kotlin both let you spell it two ways:

class Sub(int x) : Base(x) { }            // charged to the class space
class Classic : Base {
    public Classic(int x) : base(x) { }   // charged to the constructor
}

A primary constructor has no body. Its superclass call sits in the class header (C#’s base_list, Kotlin’s delegation_specifiers), outside every member, so no function space encloses it and the branch belongs to the class. The classic spelling puts the same call inside a constructor declaration, which does open a function space.

File-level abc.branches is identical either way, so nothing shifts at the aggregate. Per-function figures do: branches_max, branches_average, and a per-space bca check --threshold abc=N all see the primary-constructor form on a class row and never on a function row. A codebase migrating to primary constructors will therefore see its per-function ABC distribution move without any behaviour change. That is the intended reading: there is no function to attribute the call to.

実例

次の C 関数を考えます。

char digit_or_C(int am) {
    char c;
    if (am >= 0 && am <= 0xF) {
        c = '/';
    } else {
        c = 'C';
    }
    return c;
}

関数本体を走査すると、次のようになります。

合計: <A,B,C> = <2, 0, 3>、マグニチュードは √13 ≈ 3.61 です。

If the same body is rewritten with a unary conditional:

if (am_in_range || force_letter) {
    c = 'C';
}

ウォーカーは am_in_range と force_letter をそれぞれ 1 回ずつカウントします（Rule 7 / 9 の単項条件）。|| 演算子自体の寄与はゼロです。これは論文にある Fitzpatrick の Rule 7 / 9 の実例 if (x || y) printf("test failure\n"); — 「x と y の両方が条件式として評価されるため、単項条件は 2 つある」— と一致します。

他の ABC ツールとの比較

The project follows Fitzpatrick’s original paper for && / ||: the operator does not count; each non-comparison operand counts once as a unary conditional. This deviates from RuboCop’s Metrics/AbcSize (which counts and / or directly) and matches StepicOrg/abcmeter and eoinnoble/python-abc. Operator-counting choices cause ABC results to differ across tools on the same source.

アルゴリズム

The metric walk passes syntax-tree nodes to the language’s Abc implementation. It counts assignments, calls and conditions, inspecting child expressions where a construct requires it. The four headline values are:

• 3 つのコンポーネントそのもの（assignments、branches、conditions）。
• マグニチュード |<A,B,C>| = √(A² + B² + C²)。Fitzpatrick がベクトルを単一の数値へ要約する方法として推奨しているものです。

The full serialised output (src/metrics/abc.rs) emits these four together with value (the per-space magnitude the CLI thresholds against, which equals magnitude at a leaf space), the per-component averages (assignments_average, branches_average, conditions_average), and per-component *_min / *_max at the file scope, for fourteen fields total. The metric is specialised per language in src/metrics/abc/<lang>.rs, matching on the node kinds generated into big-code-analysis-ast/src/languages/language_*.rs.

読み方

ABC is a size metric, not a complexity metric: a long, dull function with no decisions still scores high if it does many assignments. Fitzpatrick’s original recommendation was to use the magnitude as a relative ruler: rank a file’s functions by ABC magnitude and look at the top decile.

In practice the Ruby community adopted ABC most widely; the rubocop linter and the flog tool both default to threshold-based warnings. A Ruby method with an ABC magnitude over about 17 is conventionally a refactoring candidate; over 30 is considered hard to maintain. Those thresholds are language-specific. Expect higher values in C++ and Java, which use explicit getter/setter assignments more often.

認知的複雑度

G. Ann Campbell at SonarSource introduced Cognitive Complexity in the 2017 white paper Cognitive Complexity: A new way of measuring understandability and the follow-up IEEE TechDebt 2018 paper Cognitive Complexity: An Overview and Evaluation.

The metric was designed as a replacement for Cyclomatic Complexity in code-quality tooling. Campbell’s argument is that cyclomatic complexity measures how hard code is to test, not how hard it is to understand: a 1024-arm switch statement scores the same as a deeply nested chain of ifs that perform identical logic, yet a human reader finds the nested code much harder to follow.

アルゴリズム

認知的複雑度はゼロから始まり、木を走査しながら次の 3 つの規則を適用します。

1. Ignore “shorthand” control flow. Constructs that route to a single block (a top-level if with no nesting, an else without conditions of its own, the head of a for, a ?: ternary) add a baseline +1 each, but they do not punish you for the pattern.
2. Penalise breaks in linear flow. Conditionals, switches, loops, catch clauses and labeled jumps add increments under the rules below. A try block alone adds nothing. big-code-analysis does not score the recursive-call increment in any language: it performs no call resolution, so a recursive call costs nothing (see the per-language deviations below).
3. ネストを罰します。 すでにネストされたブロックの 内側 に制御フローが現れるたびに、メトリクスは ネストの深さごとに 追加の +1 を加えます。メソッド内の外側の if の中の for の中の if は 1 + 2 + 3 = 6 になりますが、同じ 3 つの構文をフラットに並べた場合は 1 + 1 + 1 = 3 です。

Sequences of identical boolean operators (a && b && c) score +1 for the whole run, on the grounds that a chain of &&s is no harder to read than a single &&. Switching operators (a && b || c) is where the cognitive load jumps, so the second operator earns its own +1. “Identical” means the same logical operation, not the same token: where a language spells conjunction and disjunction both ways (C++, Ruby, PHP, Perl, Elixir, iRules), a && b and c is one sequence. Precedence still decides what nests where, so Ruby’s a || b and c is (a || b) and c and scores two. ?? and Perl’s // are operations of their own; xor, like ^, is no sequence.

big-code-analysis exports the per-space structural score as value along with the subtree sum, min, max, and a per-function average. The implementation is in src/metrics/cognitive.rs.

読み方

A Cognitive Complexity of 0 means the function is purely linear: no branches, no loops. SonarSource’s tooling defaults to flagging functions above 15 as “too complex”, and Campbell’s recommendation in the white paper is that a function should rarely exceed about 25. Unlike Cyclomatic Complexity, the metric scales smoothly: deeply nested code scores well above flat code with the same number of decisions.

The common use is refactoring guidance during code review: because the metric penalises nesting specifically, it flags the kind of function that benefits from an early-return or “extract method” refactor. SonarLint’s IDE plugins (IntelliJ, VS Code, Visual Studio, Eclipse) all surface it as the headline complexity number on hover, and several language servers and code-review platforms outside the Sonar ecosystem have since adopted it.

言語別の逸脱

• No language scores the recursion increment (B1): the metric walk resolves no calls, so a function calling itself costs nothing beyond its explicit control flow.

• Elixir does not score jump statements either. Elixir control flow (if / unless / cond / case / with / receive) is built from macro-shaped Call nodes rather than dedicated grammar productions, and the language has no break / continue / goto. The implementation therefore scores only the nesting-bearing constructs it can identify and omits the unstructured-jump (B1) increments that the SonarSource specification adds for languages that expose those shapes syntactically. A with expression’s else clauses act like case arms. The with expression already contributes the nesting increment, so its else adds nothing, just as Ruby’s case/else does. An if / unless / try else still adds +1. The keyword forms (else:, rescue:, catch:, bare or bracketed) score as their do … end blocks do, and Kernel.||(a, b) is a boolean sequence like a || b (#1574), as Kernel.or(a, b) is like a or b (#1582). A receive is a case over the mailbox and pays +nesting as one; its after timeout adds nothing, and a receive holding only an after is a timed wait that scores nothing (#1581).

• For every language with a syntactic function-definition node, a nested function (a local function, or a method on a local or inner class) resets the nesting counter to zero at its boundary and adds a function-depth surcharge, so control flow inside it is scored against the nested function’s own depth rather than the enclosing function’s nesting. Byte-equivalent constructs therefore score identically across languages.

• ラムダやクロージャ（x -> …、|x| …、lambda x: …、Ruby のブロック、Objective-C のブロック）は、その意味での関数境界ではありません。外側のネストを置き換えるのではなく、その「上に」上乗せ分を追加するため、if の内側に書かれたラムダの中の決定には両方の分が課されます。

• That surcharge stops at the next function boundary. A function declared inside a closure body opens a fresh lexical scope, so it does not inherit the closure’s surcharge: fn g inside a || { … } scores what it would score outside one. Until #1187 only the JavaScript family applied this, so the same body scored differently in Rust, Java, C++, PHP and C# depending on whether something two levels up happened to be a closure. Python cannot express the shape at all: a def is a statement and a lambda body is a single expression.

• Rust’s let-else (let Some(a) = y else { continue };) postdates the specification. It is scored as the if let it replaces: +1 plus the current nesting, with everything under it, the else block included, one level deeper. Its else token does not pay again. A for holding it scores 3, the same as one holding if let Some(a) = y { … }. Before #1548 the let-else paid a flat +1 through its else token whatever its depth, so that for scored 2.

• Python は、ブール演算子に対して、ブール演算子の連なり自体が得る +1 に加えて、それを囲む lambda 1 つごとに追加の +1 を課します。これを行う言語は他にありません。上乗せ分を支払うのは、あるラムダ本体の中で最も外側にある演算子だけであり、これらのラムダを数える走査は最も近い外側の expression_list で停止します。（if、for、while でも停止しますが、ラムダ本体は単一の式であるため、ラムダがこれらの文の上に位置することはなく、この 3 つのアームがカウントを変えることはありません。）連なりの増分自体は上記の演算子切り替え規則に従うため、1 つのラムダ内の混合連鎖は増分 2 つと上乗せ分 1 つを支払います。実測値は次のとおりです。

  Python ソース	cognitive.sum
  g = a and b	1
  g = lambda y: y and a	2
  g = lambda y: y and a and b	2
  g = lambda y: y and a or b	3
  g = lambda x: (lambda y: y and a)	3
  k = lambda q: (yield a and b, c)	1
  def f(a): g = lambda x: x	0

  最後の 2 行が境界です。括弧で囲まれた yield は演算子と lambda の間に expression_list を挟み、走査がラムダに到達する前に終了させるため、基本の +1 だけが残ります。また、ブール演算子を含まないラムダはそれ自体では何のコストも生じません。

  Campbell はブール演算子の連なりに基本増分を与え、ネスト増分は与えていないため、これは仕様の実装というより仕様への追加です。Issue #1150 はこの規則をレビューし、意図的に維持しました。Python のブール演算子のコストは、同じコードに対する他言語のスコアとは比較できません。

循環的複雑度（CC）

Cyclomatic Complexity is the original software complexity metric. Thomas J. McCabe introduced it in 1976 in A Complexity Measure (IEEE Transactions on Software Engineering, SE-2(4), pages 308–320).

McCabe のアイデアは、関数の 制御フローグラフ にグラフ理論を適用することでした。各基本ブロックをノード、ブロック間の各ジャンプをエッジとして描くと、そのグラフのサイクロマティック数は次のようになります。

M = E − N + 2P

where E is the number of edges, N the number of nodes, and P the number of connected components. M counts linearly independent control-flow paths. Basis-path testing uses this count; branch coverage alone can require fewer tests.

アルゴリズム

big-code-analysis does not build a control-flow graph. Instead it uses the equivalent, much cheaper formulation McCabe proved in the 1976 paper for structured programs:

循環的複雑度 = 1 + (判断点の数)

「判断点」とは、制御が分岐しうるあらゆるノードのことです。

• if、else if、三項演算子 ?:
• switch / match / select 内の case / when アーム
• while、do … while、あらゆる種類の for
• 例外ハンドラの catch 節
• short-circuit boolean operators && and ||, including their word spellings (and / or in C++, Python, Ruby, Lua, Perl, PHP, Elixir and iRules)

A && or || counts only where it applies the operator. C++ also spells the token in rvalue references (int&& x), the ref-qualifier (void f() &&), overload names (operator&&) and requires-clause constraints, and none of those is a decision (#1525). Nothing inside a requires clause or a requires expression is a decision, written with parentheses or without (#1533); cognitive complexity and ABC conditions skip it too, though a call in it is still an ABC branch. Any other compile-time expression still counts, as if constexpr does: static_assert(A && B), and a concept body concept C = A && B.

src/metrics/cyclomatic.rs にある言語別の Cyclomatic トレイトが、各 tree-sitter ノードに「これは判断か」を問い合わせてカウンタをインクリメントします。このメトリクスは関数ごととファイルごとにロールアップされます。メソッド本体をまたぐクラス単位の集約は、後述の WMC が別途提供します。

修正循環的複雑度

big-code-analysis also reports a modified variant that collapses all case / match / when arms inside a single switch statement into one decision point, regardless of how many arms it has. This undercounts big dispatch tables in a way that often matches developer intuition better than the strict McCabe definition: a 30-arm enum dispatch reads as one decision, not thirty. The convention is not original to this project; it echoes the -m mode of Terry Yin’s lizard tool, where many readers will first have seen it. Both numbers are exported side by side; pick one and be consistent.

Only alternatives collapse. A sequence of tests is still one decision per test in both variants. Elixir’s with is the case where the two meet: each pattern <- expr clause is a separate test, scored once in both variants, as Rust’s if let and ? are. The clauses of its else are alternatives, so modified scores them once, and only when one of them is a decision: else _ -> 0 selects nothing, like a plain else, and is free in both variants (#1535). Rust’s let-else (let Ok(a) = g(x) else { return 0 };) is one such test too. It binds or diverges, so it scores one in both variants, as its if let twin does. Before #1542 it scored nothing.

Elixir’s receive is a case over the mailbox, and modified scores its clauses once, as it does a case’s. Like a case it has one free arm: its bare _ -> when the do section holds one, otherwise its after clause (the timeout, the path taken when no clause matched in time). So receive do {:a, y} -> y after 10 -> :t end scores one decision in standard, as the two-clause case does, and receive do {:a, y} -> y; _ -> 0 after 10 -> :t end two: beside the catch-all the timeout is a path of its own. A receive holding only an after is a timed wait and scores nothing at all (#1581).

Rust の ? 演算子のカウント

By default Rust’s ? operator (the try_expression grammar node) adds +1 to both standard and modified cyclomatic, matching upstream rust-code-analysis: ? is an early-return branch. When cyclomatic is used as a maintainability gate, this can over-penalise linear but fallible code that threads a handful of ? through a happy path. You can opt out so ? is treated as linear error propagation:

• ライブラリ: MetricsOptions::default().with_count_cyclomatic_try(false)。
• CLI: --cyclomatic-count-try=false（または非推奨の --no-cyclomatic-try エイリアス）、あるいは bca.toml の cyclomatic_count_try = false（CLI の値はどちらの方向でもこのキーを上書きします）。
• A repo gate: set cyclomatic_count_try = false in the auto-discovered bca.toml. This project’s own make self-scan does exactly this, with no flag or env var. Toggling the policy shifts cyclomatic values, so regenerate .bca-baseline.toml in the same change.

The default is unchanged (? keeps counting), so published metric values are preserved. The toggle is Rust-only; no other language emits try_expression.

読み方

McCabe の当初の推奨は、1976 年の論文で繰り返し述べられ、NIST の Structured Testing レポート（Special Publication 500-235、1996 年）にも引き継がれているもので、単一の関数の上限を 10 とすることです。これを超えると、分岐カバレッジに必要なテストケース数が不快なほど増大します。

Cyclomatic complexity is used for three things:

1. Defect prediction. Complexity correlates, imperfectly, with the probability of a function containing a bug, and most static-analysis tools flag high-CC functions as risky.
2. Test planning. CC measures the size of a basis-path test set, not the minimum test count for branch coverage.
3. リファクタリングのトリアージ。 循環的複雑度はほぼすべてのコード品質ダッシュボードで筆頭に挙げられる「複雑度」の数値であり、長さが同程度に見える 2 つの関数の優先順位を決めるタイブレーカーとしてもよく使われます。

The metric’s known blind spot is that it treats every decision as equal weight. A 30-arm switch over an enum and a function with two nested ifs each containing nested ifs both score around 30, even though they read very differently. Cognitive Complexity (above) was designed to fix exactly that.

Halstead

The Halstead suite is the oldest size-and-effort metric family on this page. Maurice H. Halstead introduced it in his 1977 book Elements of Software Science (Elsevier, ISBN 0-444-00205-7); the Wikipedia page on Halstead complexity measures summarises the formulas. Halstead’s aim was a quantitative, empirical science of software, in the same way that physics is the empirical science of matter.

4 つの基本カウント

Halstead はプログラムをトークンに還元し、それらを 2 つのカテゴリに分割します。

• Operators, anything that does something: keywords (if, return, while), arithmetic and logical operators, assignment, function-call syntax, punctuation that controls flow.
• Operands, anything that is something: identifiers and literals.

これらから 4 つの基本カウントを導出します。

シリアライズされた出力では説明的な JSON キー列の名前を使用します。後述の導出メトリクスの公式では、同じ 4 つのカウントに対して Halstead の古典的な n1/N1/n2/N2 表記を使用します。

big-code-analysis records these four numbers in src/metrics/halstead.rs per function and per file. The per-language trait classifies tokens as operator vs. operand on a token-by-token basis. Punctuation counts as an operator: a bracket pair is one operator, billed once at its opener and listed by bca ops as (), [] or {}, and ,, ;, . and : count once per occurrence. Closing brackets, comments and a literal’s own delimiters count as nothing, which is why the Halstead totals are not the same as the Tokens count.

The following rules define which syntax contributes to Halstead’s vocabulary. Context matters because grammars reuse punctuation for operators, literal delimiters and other syntax:

• A literal’s own delimiters are not operators. A JavaScript regex, a Groovy slashy string, a C++ raw string, a Tcl braced word and a Perl or Ruby pattern each contribute one operand, the literal, and no operator for the punctuation around it. Otherwise the score would move with the author’s choice of delimiter, which says nothing about the code. The same holds for punctuation the grammar spells inside a literal: Perl’s bare /[a]#/ bills no [] or #, matching m/[a]#/, whose text the grammar does not split into tokens (#1549). Tcl and iRules need one extra step to honour this, because their grammars spell a braced literal and a braced script body the same way. {a b} is a block or a quoted value depending on the command it is passed to, so the classifier reads that command’s name. eval {…}, uplevel, after, time, an on or trap handler clause written outside a try, and Tcl’s for and switch take scripts and keep their {} operator, as does every construct the grammar models with a node of its own (proc, if, while, foreach, catch, try, namespace, an iRules when handler). Every other command (lappend, puts, list, and any user-defined proc) is taken to receive a value, so its braces score no operator.

  Recognising the command is only half of it, because most of those signatures mix the two roles. A braced word in a slot the command’s documented syntax reserves for a value scores no operator either, however script-like the command around it: after’s delay (after {100} {puts hi} scores the one {} its script earns, the same as after 100 {puts hi}), time’s iteration count, a braced proc name (proc {my proc} {} {}), a defaulted proc parameter (proc p {a {b {x y}}}), namespace export’s pattern list, namespace ensemble create -map’s dictionary, and a trap or on handler’s error code and variable list. The slots come from the Tcl 8.6 manual pages. The two proc cases are positions the grammar names, so the classifier reads them off the tree; the rest are recorded as per-command signatures in big-code-analysis-ast/src/lang_helpers/tcl_family.rs. Where a command’s argument list does not match the signature (a top-level try … trap … finally parses its whole tail as one trap command, five arguments rather than three), no position in it is read, and every brace stays a block.

  This decides the operator only. The words inside a braced argument are counted either way, because an unrecognised command is as likely to have been handed real code (an oo::class create C {…} body, a tcltest -body {…}) as a list. So a script passed to a command outside the list (a Tk -command {…} callback, a dict for body) gives up one {} occurrence per block and nothing else, with one visible consequence: a space whose only blocks are of that kind has no operator left, and because Halstead’s difficulty multiplies by the operator count, its effort reads 0.0 rather than slightly low. A proc keeps its own proc keyword and body brace, so this reaches top-level script fragments, not functions.

  The consequence for the operand column is an asymmetry, and it is the contract rather than an open defect: a braced value scores one operand where the grammar names the command (set x {a b} → the operand {a b}) and one per word where only the command name would (lappend x {a b} → the operands a and b). Both ways of removing it were weighed and neither is available. Deciding from the contents (no substitution, no nested block, therefore a list) was built and measured: on a file holding an oo::class body, a tcltest -body and an apply lambda it took n2 from 25 to 15 and N2 from 32 to 15, each of those three collapsing into a single operand. And listing the value-taking commands instead needs an open set where the script-taking one is closed, since every user proc belongs to it, so the list would be incomplete by construction and would make three behaviours where there are two.

• A string-interpolation opener is not an operator. "{$x}" in PHP, "#{x}" in Ruby and Elixir, "${x}" in Kotlin and Groovy, $"{x}" in C#, f"{x}" in Python and Java 21’s STR."\{x}" all count the interpolated expression’s own operators and nothing for the opener itself, and the wrapping literal is not an operand either. Before #1703, Java counted the wrapping string template as an operand as well as the interpolated x. The : that opens a Python format spec (f"{x:>10}") counts nothing either, because the spec after it is string content (#1486). Nor does the self-documenting = of f"{x=}", which prints the expression’s text and assigns nothing (#1551). C#’s format : and alignment , ($"{x,8:F2}") count nothing for the same reason (#1573), but the alignment is an expression and keeps its own vocabulary: 8 is an operand, and {x,-w} counts - and w. A Python literal width (f"{x:>10}") is format-spec text and counts nothing.

• A delimiter around syntax is an operator, whatever it delimits. The rule above is about a literal’s own punctuation, and it stops there. Halstead counts the vocabulary a program is written in and has no notion of a decision. Halstead uses the same < vocabulary entry for comparisons, JSX tag delimiters, Lua <const> attributes, C# operator < declarations and Perl <FH> readlines, and bca ops reports every one of them. This is the deliberate counterpart to the ABC deviation that excludes the same tokens from conditions: ABC asks whether a branch is taken, and these are not branches; Halstead asks what alphabet the source uses, and these are part of it. Expect the two metrics to disagree here. The same reading bills Python’s (, [, {, ; and block, slice, dict and annotation :, and Rust’s annotation, field, bound and label :, which is a separate operator from ::. Both languages left these out until #1486, so their Halstead scores rose with it.

• A declaration keyword is an operator. Python’s class is billed like def since #1550, as Ruby, Kotlin, C# and PHP bill their class. Java, Groovy, the JavaScript family, C, C++ and Objective-C followed in #1552 with their type-declaration keywords: class, struct, union, enum, interface, record, trait, @interface, @implementation and @protocol. The class tail of Java’s C.class is an operand, not this keyword (see the class literal below). Groovy’s var bills as its def does since #1704, once per local declaration however many declarators follow it. A var used as a name stays an operand (def var = 3, [var: 1]), or bills nothing where the grammar cannot parse the statement (var = 4), and the var of a field (var field = 1) or of final var, which the grammar reads as a type name, still bills as a type-name operand (#1706). Kotlin’s interface followed in #1556. #1557 added C++’s namespace, template, typename, typedef and using (C and Objective-C bill typedef too), so template <class T> and template <typename T> each bill their keyword and score alike. It also added TypeScript’s type, namespace, module, declare and global. #1561 made TypeScript’s type-level operator keywords operators, as their value-level siblings as, typeof and extends already were: satisfies, keyof, infer, and the is and asserts of a type predicate. #1564 made Kotlin’s typealias, init, where, by, get and set operators, as C# bills its get, set, init and where. The @get: and @set: annotation targets bill nothing, like @field:. The backing field in an accessor is an operand, and the words used as names (val by = 1, x.get(i)) stay operands.

• A declaration modifier is an operator, keyed by its keyword and never its wrapper node. C#, Kotlin, Java, Groovy, TypeScript and TSX, C, C++, Mozcpp and Objective-C bill every modifier once, as the keyword and never as the node that wraps it: Kotlin’s and Java’s modifiers, TypeScript’s accessibility_modifier and override_modifier, and the C family’s storage_class_specifier, type_qualifier and virtual_specifier. So the const of void f() const and of int * const p each bill once. C# already did; the others followed in #1558 (Kotlin), #1563 (TypeScript), #1565 (Java and Groovy), #1578 (C, C++ and Mozcpp) and #1579 (Objective-C). The exceptions:

  • The same word used as a name stays an operand (val open = 1, let readonly = 1, obj.static, var sealed = 1, int override = 1;). Where Kotlin’s grammar cannot parse the name (open = !open at the start of a statement, val suspend = 1, a parameter named vararg), the word bills nothing.

  • The static of import static and requires static bills nothing, as import does not: Java and Groovy bill no directive keyword (package, import, module, requires, exports), and the word a directive qualifies follows it. C# is the outlier here: it bills using, and so using static in full. Each reading is consistent with the language’s own directive rule, and #1600 kept both rather than move one.

  • C++’s auto is a placeholder type and stays unbilled. Attributes, the MS calling conventions, the Gecko MOZ_* macros and the Apple SDK macros (NS_INLINE, FOUNDATION_EXPORT, IBOutlet) bill nothing. The words each language bills:

  • Kotlin: the enum of enum class, data, sealed, the visibility keywords, open, override, suspend, reified, out and the rest.

  • TypeScript and TSX: the member modifiers public, private, protected, override, readonly, abstract, accessor and static. JavaScript and Mozjs bill static too. Their grammars lex static get followed by a newline as one static get token, which bills as one operator, so that spelling scores one entry where static get y() on one line bills static and get.

  • Java and Groovy: the visibility keywords, static, native, strictfp, volatile, sealed and non-sealed, where before #1565 they billed only abstract, final, transient, synchronized and default; plus the permits clause keyword beside extends and implements.

  • C, C++ and Mozcpp: every storage class, function specifier and type qualifier: static, extern, register, inline, thread_local, const, volatile, restrict, _Atomic, constexpr, alignas and their vendor spellings (__inline, __forceinline, __restrict__, __thread, __volatile__, __extension__, …), plus C++’s virtual, mutable, constinit, consteval, explicit, friend, the access labels, override, final and noexcept. C bills its storage class auto. extern "C" bills extern and keeps "C" an operand.

  • Objective-C: C’s list, plus the @public, @private, @protected and @package ivar labels, the @optional and @required protocol sections, the ownership qualifiers (__weak, __strong, __block, …), the nullability qualifiers (nullable, _Nullable, __nullable, …), __kindof, the __covariant and __contravariant variance, and the in, out, inout, bycopy, byref and oneway method-type qualifiers. A property attribute (nonatomic, copy, getter) bills as its word; a getter= or setter= value stays an operand.

• A type name is an operand. #1557 made every TypeScript type name an operand (x: Foo, interface I, Map<K, V>), as C#, Rust and the C family already did. Java followed in #1560: Foo f, implements I, List<Foo> and each segment of java.util.List bill their names as operands. The inferred type var does not, as C# bills nothing for its own. Java’s primitive types are operators everywhere. Groovy, whose grammar parses a primitive type as a name, bills it the same way since #1568: int, boolean, void and the other primitives are operators keyed by their spelling, as a declared type and as a class literal’s receiver. Groovy reserves these words, and they bill as operators; in the positions Groovy nonetheless allows them as names (x.int, [int: 1]), they stay operands. Java’s boolean is listed as boolean rather than its node kind boolean_type, so both languages report it alike.

• A class literal bills its parts. Since #1566 a Java class literal bills its parts rather than one operand spelled by its whole text, since JLS §15.8.2 defines it as an expression rather than a literal: in java.util.List.class and Foo[].class each name and the class tail are operands and each . and [] an operator, as Groovy’s Foo.class and Kotlin’s and PHP’s Foo::class bill theirs. The int of int.class and the void of void.class stay operators, as Java bills them everywhere.

• Angle brackets that enclose types are one bracket pair. The < and > around type arguments and type parameters count as one <> operator, billed at the < as () is at the (, and the > counts nothing (#1559). That covers Vec<u8>, fn f<T>, a turbofish h::<u8>(), for<'a>, use<T> and a qualified path’s <T as Trait>:: or <T>:: in Rust; C++’s template <class T> and std::vector<int>; and the type-argument and type-parameter lists of Java, Groovy, C#, Kotlin, TypeScript and TSX, plus C#’s delegate*<int, void> pointer type and Kotlin’s super<A> (#1567). Objective-C has four generic lists: NSArray<NSString *>, id<NSCopying>, the protocol list in @interface A : NSObject <NSCopying>, and a type passed as a call argument, f(NSArray<NSString *>). A comparison’s < and > and a shift’s << and >> stay separate operators, and a C++ >> that closes two template lists parses as two >, so it bills nothing. The rule follows the parse: where tree-sitter-cpp reads comparisons as a template argument list, as in x = a < b || c > (d), their brackets bill as <> too, since only name lookup tells that from a template call spelled the same. The comparisons Objective-C and C# misread as a call argument’s generic list, g(a<b, c>d) and F(a < b, c > d), keep < and >. The exception is C#’s >= spelling, F(a < b, c >= d), which the grammar parses as an assignment and which still bills <> and =. Go’s generics use square brackets and already billed []. Angle brackets around anything other than types still bill < and >: the JSX, Lua and Perl constructs above. So does a Kotlin generic call with arguments, id<Int>(a), which tree-sitter-kotlin-ng parses as two comparisons (#1394), and a generic inside a Rust macro call, vec![Vec::<u8>::new()], whose token tree tree-sitter-rust leaves unparsed; a >> closing two lists there bills as the shift. Before #1559 each bracket billed under the comparison’s own entry, so Vec<u8> and a < b shared one. Every generic now costs one operator occurrence less, so N1 falls in any code that uses generics. n1 rises by one where a comparison < or > remains beside the new <>, so halstead.effort falls in most files and rises in the rest; on the C++ and Rust corpora it fell in 87% of the files that moved, and MI rose in most of them.

• An alternative spelling is an operator of its own. C++ spells && equally as and, != as not_eq and so on through all eleven alternative tokens. Each counts once in total_operators, exactly like its symbol, but a && b and c has two entries in unique_operators where a && b && c has one. Operators are distinct by token, and bca ops lists and and && separately, so the metric matches what it reports (#1522).

• A self-reference is an operand. this, self, $this, super and base name the receiver of a member access, so this.x counts the way p.x does: one . operator and two operands. Java, Groovy, C#, Kotlin (labelled this@Outer included), Python, Rust and PHP all agree. The keyword is an operator only where it declares something, as the operator keyword of an overload does: C#’s indexer public int this[int i], and the wildcard bound ? super T in Java and Groovy (#1380).

• A keyword’s role follows its text, not its node kind. C#’s grammar parses the bare this, ref, out, in, scoped and readonly of a parameter, and the static / async of a lambda, as a modifier node, a different kind from the one the same keyword has anywhere else. Each keeps the role its text has elsewhere: an extension method’s this Foo f is an operand, the ref in M(ref int a) is the same operator as the ref in the call M(ref x), and static (int x) => x bills the same static as static void M(). A repeated operator keyword adds to total_operators but not to unique_operators (#1418, #1482).

• Perl’s __END__ and __DATA__ end the program. Neither marker nor the data section after it is an operator or an operand, so two files that differ only in their data section score alike. The grammar holds the marker and every byte after it in the same special_literal node it uses for __FILE__, which until #1644 billed the whole section as one operand spelling its contents, and billed each of __FILE__, __LINE__, __PACKAGE__ and __SUB__ twice, once as that wrapper and once as the keyword inside it. Each constant is now one operand, billed once. The marker and the opaque data leaf are still leaves, so tokens still counts them.

• JSX element text is an operand. In JavaScript, Mozjs and TSX, the hi of <p>hi</p> counts the way a string’s contents do. It is keyed on its text with leading and trailing whitespace trimmed, so a line of text at two indentation depths is one operand, and the spaces between two tags on one line count as nothing. Whitespace inside a multi-line text is kept. A character reference (&) splits the text into separate operands (a & b is three). Inside an attribute string, the reference is part of that string’s one operand (#1483).

• An overloaded operator’s name is an operator. The + of operator + was always one, and the names a grammar spells as whole tokens now agree: C#’s operator true / operator false, and C++’s operator[], operator(), operator""_x and operator co_await. The operator keyword is an operator in both languages, as is C++’s co_await in an expression. C++’s [] and () names are tokens of their own, so bca ops lists operator[] beside a subscript’s [] as a second operator, as Ruby does for def [](i) (#1296). C++’s coroutine keywords co_return and co_yield are operators as return is (#1547).

• Only written tokens count. When tree-sitter cannot parse a construct, its error recovery may insert zero-width tokens the source does not contain: a ;, a ), an identifier. None of them is billed in either half. Before #1546 an inserted identifier became an operand whose text is the empty string. One case is a C++ destructor called through a template name (p->~T<A>()), which tree-sitter-cpp cannot parse. Another is a statement-position typename cast, which made every inserted ; a second ; operator.

• A named operator is one operand. Elixir names an operator in a capture (&==/2, &and/2) and as the function of a remote call (Kernel.||(a, b)), and its grammar wraps the token in an operator_identifier. That wrapper is the operand, as foo is in &foo/2, so the token inside it adds no operator; &==/2 scores what &foo/2 does. A captured && / || / and / or is no decision either (#1534), but the remote call applies the operator, so Kernel.||(a, b) scores what a || b does in cyclomatic, ABC and cognitive alike, and a user module’s Foo.||(a, b) in none (#1574). Kernel.and(a, b) and Kernel.or(a, b) decide the same way, though their names are plain identifiers with no operator token (#1582). This differs from a C# operator <, whose < has no wrapper and so stays the operator the rule above makes it.

導出メトリクス

Halstead then derives a set of formulas. big-code-analysis reports all of the standard ones, plus three less common derivations (estimated_program_length, purity_ratio, level) that are part of the original suite:

vocabulary               n  = n1 + n2
length                   N  = N1 + N2
estimated_program_length N̂  = n1·log2(n1) + n2·log2(n2)
purity_ratio                = N̂ / N
volume                   V  = N · log2(n)                          (bits)
difficulty               D  = (n1 / 2) · (N2 / n2)
level                    L  = 1 / D
effort                   E  = D · V          (elementary mental discriminations)
time                     T  = E / 18                               (seconds)
bugs                     B  = E^(2/3) / 3000 (estimated delivered defects)

The numeric constants come from Halstead’s empirical fits against a heterogeneous corpus of CDC-era programs including FORTRAN, PL/I, and Algol-family languages. The T = E / 18 “Stroud number” comes from psychology instead: Halstead borrowed John Stroud’s estimate that the human mind makes about 18 elementary discriminations per second.

読み方

Halstead’s original intent was to predict three things about a program before it was written: how big it would be in bits, how long it would take to implement, and how many bugs to expect in deployment. The empirical evidence for the volume and length predictions is reasonable; the time and bugs predictions are more controversial and have been criticised at length, notably in the Purdue technical report Software Science Revisited.

現代の実践では、Halstead の数値は 3 つの用途に使われます。

1. As inputs into composite metrics, most importantly the Maintainability Index (next section), which depends on Halstead volume.
2. 言語に依存しないサイズの代理指標として。ビット単位のボリュームは、LOC では実現できない形で言語をまたいで滑らかにスケールします。
3. 相対的な工数見積もりのため。2 つのリファクタリング候補の循環的複雑度が同程度の場合、Halstead の difficulty が高いほうがリグレッションを持ち込む可能性が高くなります。

コード行数

This section covers the LOC variants: SLOC, PLOC, LLOC, CLOC, BLANK, and DLOC. “Counting lines” sounds trivial until you have to define exactly what counts. SLOC through BLANK are the de-facto standard breakdown, going back to Samuel Conte, Hubert Dunsmore and Vincent Shen’s 1986 textbook Software Engineering Metrics and Models (Benjamin/Cummings, ISBN 0-8053-2162-4), which codified the distinction between physical and logical lines. The Wikipedia entry on source lines of code summarises that physical-versus-logical distinction.

アルゴリズム

big-code-analysis derives every count from a single pass over the tree-sitter syntax tree (see src/metrics/loc.rs). Comments and strings are identified by their AST node type rather than by lexical scanning, so multi-line strings, raw strings, doc comments, and string interpolations are all handled correctly. The per-language Loc trait specifies which node kinds count as a “statement” for LLOC; this is the subtle one, because what counts as a statement is language-defined.

Documentation rows are comment rows that are also reported on their own as DLOC (loc.dloc), so CLOC can be read with or without them. Each language’s own documentation tool decides which comments are documentation; there is no single rule for all:

• Where the grammar marks it, the mark decides: a Rust ///, //!, /** */ or /*! */ comment (tree-sitter’s doc_comment child; //// and /**/ carry none), a Groovy groovydoc_comment (but not the empty /**/ that grammar also marks), a Perl POD block (but not one that is nothing but =begin comment and =for comment regions, Perl’s idiom for commenting code out; POD after such a region’s end documents, and makes the block documentation).

• Where the grammar emits one comment kind for every form, the opening marker decides, as the language’s documentation tool reads it: Doxygen’s /**, /*!, /// and //! (and their after-member < forms) for C, C++ and Objective-C; /** for Javadoc, KDoc, JSDoc and PHPDoc, plus /// for Java’s Markdown doc comments; /// and /** for C# XML docs. The tools disagree at the edges and so does DLOC: /*** is documentation to javac, Kotlin, Groovydoc and tsc (so TypeScript and TSX read it, while plain JavaScript follows JSDoc) but not to Doxygen, JSDoc, Roslyn or PHP; /**/ is documentation nowhere; PHP needs whitespace after /**; and //// is never documentation, which is stricter than Doxygen’s lexer.

• A doc comment counts only where its tool reads it. A Rust, Java, Kotlin, Groovy, C# or PHP doc comment inside a function or closure body, inside a Java or Groovy initializer, or inside a Kotlin accessor or init block, is an ordinary comment: rustc warns that one on a statement is unused, Roslyn raises CS1587, javadoc and Dokka document declarations only, and an in-body PHPDoc /** @var */ is a type hint. A working note spelled /// … inside such a function therefore stays charged by MI. C, C++ and Objective-C keep in-body doc blocks: Doxygen appends them to the function’s documentation as its in-body description, and HIDE_IN_BODY_DOCS defaults to NO. Two placements inside a function still document: a Rust inner doc comment (//!, /*! */) opening a function’s body is that function’s own documentation, and a doc comment in a signature counts where its tool reads it there (a Doxygen /**< parameter block or a block after [[attributes]], a PHPDoc after #[…] or on a promoted constructor property, a KDoc after an annotation), but not in Java or C#, which bind a doc comment only before a declaration’s first token. JavaScript, TypeScript and TSX keep in-body JSDoc, which documents inner symbols, and Perl keeps POD wherever it sits, as perldoc does, after __END__ or __DATA__ too, where every other non-blank row of the data section counts as PLOC.

• In Rust, Java, Kotlin and Groovy, a doc comment also has to be attached: it counts only when the declaration after it is one its tool documents. Attributes, annotations, modifiers and blank rows may come between the comment and the declaration. A Rust 2024 safe fn in an extern block counts too, although tree-sitter-rust parses its safe as an error. A doc comment above anything else stays a plain comment row: an import (Rust’s use and extern crate take one), a statement, a macro call, a Rust extern block, a closing brace, or the end of the file. A KDoc nested in an argument or type-parameter list documents nothing. The tools also differ on a run of several doc comments. rustc attaches every outer doc comment above an item, so all of them count. javac and Kotlin keep only the last one; javac’s -Xlint:dangling-doc-comments names the earlier ones, and they do not count. Consecutive /// lines are one Java Markdown doc comment. Groovydoc reads only the comment nearest the declaration, so a plain // comment in between detaches it. A Java doc comment above package counts only in a file with no type after it, which is the shape of package-info.java. Rust’s inner //! is unaffected: it documents the item it sits in.

• C#, PHP, JavaScript and TypeScript bind doc comments the same way. Each language still follows its own tool:

  • C#: Roslyn keeps the nearest run of doc comments that only blank rows separate, reading past plain comments and directives such as #region to find it. Every other doc comment is CS1587, and so is a doc comment above a namespace, a using directive, or an accessor such as get;.
  • PHP: phpDocumentor gives a class, function, method, property, constant or enum case the last DocBlock before it. A DocBlock above a statement, a use or a namespace counts only as the file DocBlock. phpDocumentor takes the file’s first DocBlock as the file DocBlock when no class, function, constant, interface or trait follows the DocBlocks at the top of the file. It also takes it when exactly two DocBlocks come before the first such element.
  • JavaScript: JSDoc gives a declaration or an assignment the nearest block comment before it, reading past // lines, so a plain /* */ in between detaches a doc comment. A call or another statement takes nothing. A block tagged @file, @fileoverview, @overview or @module, or with a tag that names a symbol (@typedef {Object} T), documents that symbol wherever it sits. @license does not make a block stand alone.
  • TypeScript: tsc keeps the last /** before a declaration, reading past every plain comment, and documents no assignment statement. A doc comment after a decorator, a modifier such as static, or export or declare is inside the declaration and documents nothing, and so does one after code on its own row, except before a parameter. A @module or @packageDocumentation block documents the file, as TypeDoc reads it. In a JavaScript or TypeScript function body every doc comment still counts, since JSDoc documents inner symbols.

• C, C++ and Objective-C follow Doxygen, which keeps every doc block it meets and gives them all to the next entry. A doc block counts when what follows it is something Doxygen documents: a declaration, a definition, a macro, a typedef or using, a namespace, a template, an enumerator, a macro call such as FOO(bar);, or an Objective-C @interface, @property or method. Doxygen reads past blank rows, plain comments, #include, #import, #pragma and an empty ;, and into an include guard or another #if that holds a declaration. A doc block above a forward declaration (struct s;, @class C;), a closing } or @end, or the end of the file stays a plain comment row. A block carrying a structural command documents an entry of its own, so it counts wherever it sits: \file, \mainpage, \page, \defgroup, \addtogroup and \name always, and a command that names its subject, such as \class X or \def M, when it has a name. The doc blocks above a \file block count with it. \brief and \ingroup are not structural. A member-after comment (/**<, ///<) documents the member before it and always counts, as do the blocks in a function body, which Doxygen publishes as the function’s in-body description.

• In Python, every bare string statement (a string whose value is discarded) is a comment row, but only one where Python reads documentation is DLOC, following PEP 257: the first statement of a module, class or function (the string stored as __doc__, which must be a str literal, never an f-string or bytes), successive strings after any docstring, and an attribute docstring directly after an assignment to a name or a type alias at module or class level, or after an assignment to self.<name> at the top of a class’s __init__, alone or in a tuple of targets, which Sphinx autodoc reads. Sphinx also reads such an assignment inside an if, with, loop or try suite; PEP 257 names the top level only, and DLOC follows the PEP there. PEP 258 also includes successive strings after attribute docstrings. Comments between them do not count as statements. Any other bare string, such as a triple-quoted string wrapping commented-out code in the middle of a function, stays a comment row and is charged by MI like a # comment. This is narrower than radon’s multi, which takes every bare multi-line string. A docstring row that also holds code (def f(): """doc""") is code too. An implicitly concatenated literal ("""doc""" "more") is one string and a bare tuple of strings is none, the same test Halstead applies when it drops a bare string’s operands. A parenthesized string (("""doc""")) is the same string, because CPython drops the parentheses, and its ( and ) rows are its rows. A comment is documentation in Python only in Sphinx’s #: form: consecutive #: lines directly above one of those attribute assignments or aliases, or a #: after the code on its line (MAX = 10 #: in bytes). A plain # line breaks a #: block.

Go, Ruby and Lua have no marker to read, so a comment is documentation by where it sits, decided once per run: the chain of comment siblings on consecutive rows that hold nothing but comments (a trailing x := 1 // t never joins one, and a blank row ends one):

• Go: a run directly above a declaration is go/doc’s lead comment, where a declaration is the package clause, a func or method, a top-level type / var / const declaration or one of its grouped specs, a struct field, or an interface method; never an import, and never a declaration inside a function body, which go/doc does not read. A directive row such as //go:generate belongs to the group but is not documentation, and is not counted.
• Ruby: a run directly above a def, def self., class, module, class << Const, a constant or class-variable assignment (MAX = 10, Foo::BAR = 1, @@count = 0), a method alias (alias new old, alias_method :new, :old), an attr or attr_* call or a visibility-wrapped def (private def m), alone or under an if / unless modifier, as YARD attaches it, including the first statement of a class body or of an if, elsif or unless body. In a method body YARD reads only a nested def, and nothing in a singleton class or conditional opened there; no YARD handler claims a case, a begin or a loop, so nothing in their bodies counts anywhere. A shebang, an encoding line or a frozen_string_literal magic comment is dropped from the run, as YARD drops it. Unlike YARD, one blank row between the run and the def is a gap, not a tolerance; a trailing comment on the statement’s own row (MAX = 3 # The maximum.) documents nothing; and a statement in a call’s block (included do, an RSpec describe block, in either do … end or { } form), which YARD never reads, still counts. A block that opens with RDoc’s ## (exactly two #, so a #### banner or a ##### Helpers ##### divider opens nothing) or a YARD @! directive (# @!method, # @!attribute, # @!parse) documents a method with no def to sit above (define_method, a DSL call), so it counts whatever follows it, in a namespace body but never in a method’s.
• Lua: a run that opens with an LDoc --- row (a row of dashes alone opens too; --- x --- is LDoc’s end marker and does not) and continues over the -- rows below it, or a --[[- long comment. A long comment ends a run, as LDoc’s lexer ends a block there. A block with no text (a row of dashes alone) is a comment, as LDoc discards it. A --- row directly under a line that ends in a trailing -- note is no block at all: LDoc’s lexer keeps a line comment’s newline and gathers consecutive comments into one group, whose first token (the trailing note) decides it. Otherwise a block counts when it is the first block of a file that opens with a comment or a shebang, which LDoc skips (the module’s documentation), when one of its lines opens with an @ tag (-- @param x, LuaLS’s ---@class), or when an item follows it on the next row (the first statement of an if, do or loop body included): a function, an assignment to one name or dotted name (local x = 1, M.a.b = 1; not a bare local x, local a, b = …, local x <const> = … or M[1] = …), a named table field (new = function … end), or a return of a function or a table. Any other block is a comment, as LDoc drops it with a “definition cannot be parsed” warning. Three deviations from LDoc: a tagged block counts even with no item or name to attach to; a blank row between a block and its item is a gap; and a file that opens with code still has its blocks read, where LDoc reads none of them without a module() call. A block inside a function body is a comment: LDoc documents what a module declares, and an in-body --- annotates the code there instead (LuaLS’s ---@type on a local), as PHP’s in-body @var does.

Nothing else counts: an Elixir @doc heredoc is an assignment the compiler stores and is code, and Bash, Tcl and iRules have no documentation syntax.

The counts satisfy a few useful identities:

SLOC = PLOC + BLANK + (lines that are comment-only)
CLOC ≥ (lines that are comment-only)        # CLOC also counts mixed code+comment lines
DLOC ≤ CLOC                                 # every documentation row is a comment row

読み方

• SLOC は、多くの人が口語的に「コード行数」と言うときに指すものです。標準的なサイズの代理指標ですが、フォーマットの影響を受けやすく、言語の慣習をまたいだ移植性はありません。
• PLOC strips away the visual noise. It is the measure to gate file length on (loc.ploc), and the size term of the Maintainability Index below.
• LLOC は最も信頼できる 文 の数です。文ごとのテストケースを見積もる場合や、Python ファイルと Java ファイルの密度を比較する場合に適した指標です。
• CLOC, combined with PLOC, gives you a comment density: CLOC / PLOC is a rough proxy for how much of the file is documentation versus implementation.
• BLANK is mostly diagnostic: a file with a very low BLANK proportion is often hard to read.
• DLOC is the slice of CLOC that is documentation: doc comments, docstrings, POD. CLOC − DLOC is the count of working comments, the numerator of the Maintainability Index’s SEI comment share.

LOC variants are used well beyond raw size. They are the most common input into cost-estimation models (COCOMO and COCOMO II both use KSLOC, thousands of source lines, as their base unit), they feed effort prediction in product-portfolio dashboards, and they are the normalising denominator for almost every other metric: defects per KSLOC, churn per KSLOC, test cases per KSLOC. The weakness is that LOC is easy to game: a 10× difference in coding style can produce a 2× difference in LOC. That is why this chapter has so many other metrics in it.

保守容易性指数（MI）

The Maintainability Index is a composite metric that rolls several of the metrics above into a single number, roughly 0 to 100, meant to be read as “how maintainable is this code?”. Paul Oman and Jack Hagemeister proposed it in their 1992 ICSM paper Metrics for assessing a software system’s maintainability, and Don Coleman, Dan Ash, Bruce Lowther, and Paul Oman refined it in the 1994 IEEE Computer paper Using metrics to evaluate software system maintainability (IEEE Computer 27(8), pages 44-49). Their method was empirical: they collected expert maintainability ratings on a handful of production Hewlett-Packard systems, computed forty candidate metrics on each, and let regression analysis pick the best linear combination. The combination that survived used Halstead volume, cyclomatic complexity, lines of code, and comment density.

big-code-analysis reports the three formulas that have stuck in practice. The three values nest under the mi object as the keys original, sei, and visual_studio (the dotted threshold names mi.original, mi.sei, mi.visual_studio):

mi.original      = 171 − 5.2·ln(HV) − 0.23·CC − 16.2·ln(PLOC)
mi.sei           = mi.original + 50·sin(√(2.4·CM))
mi.visual_studio = max(0, mi.original · 100 / 171)

CM               = (CLOC − DLOC) / (SLOC − DLOC rows that carry no code), in [0, 1]

• mi.original は Coleman–Oman の公式です。病的なファイルでは負になることがあります。
• mi.sei is the Software Engineering Institute’s refinement, which adds a comment-density term. The sin(√(...)) shape was chosen so that some comments help, but adding more after a point does not, and never hurts. CM is the share of working (non-documentation) comment rows among the space’s rows, a ratio in [0, 1]. On that scale the term rises monotonically from 0 with no comment to about 50 (50·sin(√2.4) ≈ 49.99) when every row is a comment, so mi.sei is never below mi.original and equals it in a comment-free space.
• mi.visual_studio is the linear rescaling Microsoft chose for Visual Studio, where the score is clamped to [0, 100] and shown to developers traffic-light style: green ≥ 20, yellow ≥ 10, red below.

The size term is PLOC, the rows that carry code (#1607). Comment, documentation and blank rows never enter it, so a // TODO, a commented-out block, a Rust /// block, a docstring or a run of blank lines leaves mi.original and mi.visual_studio exactly where they were, with Halstead and cyclomatic unchanged. A row a doc comment or docstring shares with code, as in def f(): """doc""" or int x; /** doc */, is a code row and stays counted.

Documentation also leaves both sides of CM in every language (#1597), so a function’s mi.sei is the same with and without its /// block, its Javadoc comment, its POD or its docstring, which keeps MI consistent with Halstead, where a docstring’s operands are already ignored. Blank rows stay in CM’s denominator: adding one to a space with a working comment dilutes the comment share and lowers mi.sei slightly, while a comment-free space is unmoved.

Two details differ from some published statements of the SEI formula. Its ln matches mi.original’s; releases before #1607 took log2 of the volume and size in mi.sei alone. And CM is a ratio rather than a percentage: on the 0–100 scale the sin term swings between −50 and +50 several times across ordinary comment densities.

Charging documentation

With mi_charges_docs on, mi.sei counts documentation as comment: it takes its comment share as CLOC / SLOC, the inputs that releases without loc.dloc fed that share. Nothing else moves. The size term is PLOC in both modes, so mi.original and mi.visual_studio read the same either way, and since the comment term only rises with CM, charging documentation can only raise mi.sei. It does not reproduce an earlier release’s numbers: those sized every variant on SLOC and took mi.sei on a different scale. It changes no other metric: loc.dloc is reported either way.

• Library: MetricsOptions::default().with_mi_charges_docs(true).
• CLI: --mi-charges-docs (or --mi-charges-docs=false to say the default out loud), or mi_charges_docs = true in bca.toml; the CLI value overrides the key in either direction.
• Python: mi_charges_docs=True on analyze, analyze_source, analyze_batch, analyze_paths and Ast.metrics.
• The REST server has no request field for it; an embedder sets WebMetricsCfg::with_mi_charges_docs.

The LOC inputs it reads are the current ones, so a Python file whose docstring is an implicit concatenation ("""doc""" "more") or whose bare "a", "b" tuple statement was once a comment row reads a different comment share from a release that classified those rows the other way.

A baseline records which mode wrote it, and bca check --baseline warns when it reads mi.* entries under the other mode. Only mi.sei entries can disagree, and in one direction: a value recorded with documentation charged sits above the default’s, so reading it under the default can fire on untouched code, and a value recorded under the default can cover a real regression under the charged mode. Switching the mode therefore means reviewing any mi.sei threshold and regenerating the baseline in the same change, as for cyclomatic_count_try. bca check --print-effective-config names the mode in force.

A baseline also records the MI formula revision that computed its values (mi_formula in [provenance]; revision 2 since #1607, and an unstamped file reads as revision 1). When a baseline holding any mi.* entry was written under another revision, bca check --baseline warns that its values are not comparable, in place of the mode warning; refresh it with --write-baseline.

Arie van Deursen’s blog post Think Twice Before Using the Maintainability Index collects the historical context and a sharp critique of the metric.

アルゴリズム

The implementation is purely arithmetic: src/metrics/mi.rs consumes the already-computed Halstead, Cyclomatic, and LOC metrics and applies the three formulas. Because the formulas use the natural log of Halstead volume and of PLOC, MI is undefined for empty files; big-code-analysis returns 0.0 for any space with zero code lines or zero Halstead volume (a comment-only file or a docstring-only module has no volume). That 0.0 is a sentinel, not a score, and it cannot be told apart from a measured 0 or from mi.visual_studio’s clamp: mi::Stats::is_empty() identifies such a space in the library, and bca report’s averages skip it. The JSON value stays 0.0 until 3.0, which is planned to emit null instead (#1621).

読み方

MI was originally designed as a portfolio-level score: “how much maintenance pain should we expect from this codebase over the next year?”. It is stable across releases of a healthy system and tends to drop measurably before a system enters the “legacy” quadrant.

The common use is the Visual Studio traffic-light rendering: Visual Studio exposes mi.visual_studio through green, yellow and red indicators on a method, which is where many .NET developers meet it, and also why it has attracted much criticism. Treat it as a smoke detector, not a thermostat: a sudden drop is a useful signal, but the absolute number is noisy.

NArgs

NArgs counts the number of arguments declared by a function, method, or closure. The metric has no well-known origin paper; guidance on limiting argument counts appears in Kernighan and Plauger’s The Elements of Programming Style (1974) and Robert C. Martin’s Clean Code (2008), which suggests three arguments as a soft ceiling.

big-code-analysis splits the count by callable kind: every aggregate is reported separately for functions and closures so a Rust file heavy on |…| … closures and a Java file with only methods produce comparable numbers. The serialised output (src/metrics/nargs.rs) is function_args, closure_args, function_args_average, closure_args_average, total, value, average, function_args_min, function_args_max, closure_args_min, closure_args_max. The implementation handles default arguments, variadic arguments, keyword-only arguments, and destructured parameters consistently per language. Comments written inside the parameter list are not parameters, including the C++ idiom that puts one where an unused parameter’s name would go: void f(int /*unused*/) is one argument.

Macro-obscured C-family declarators

C, C++, Mozcpp and Objective-C are parsed without running the preprocessor, so a function-like macro standing where the declared name belongs is still there in the tree. The idiom is the JNI shim:

#define RUN_STATS_METHOD(name) JNICALL Java_org_tensorflow_RunStats_##name

JNIEXPORT jlong RUN_STATS_METHOD(allocate)(JNIEnv *env, jclass clazz) { … }

Read as written, RUN_STATS_METHOD(allocate) is the declarator and (JNIEnv *env, jclass clazz) belongs to the return type: one argument. big-code-analysis reads it the other way and reports two, because neither language lets a function return a function type (C11 6.7.6.3p1, C++ [dcl.fct]): a declarator nested directly inside another one cannot be a declarator chain, so the outer list is the function’s own. Every legitimate function-returning-a-function-pointer form, such as int (*fp(int a, int b))(int c), puts parentheses in between and is unaffected, as is C++ operator().

The space is named for the macro, not the function. There is no other candidate: the real symbol is assembled by ## token pasting and never appears in the source. So several shims in one file share a name, which bca check shows as several rows with the same label at different lines, and which .bca-baseline.toml disambiguates by body hash the way it does an overload set.

しきい値ゲートが測定するもの

bca check --threshold nargs=N gates each callable on its own parameter list, which is what every comparable tool measures: RuboCop Metrics/ParameterLists, ESLint max-params, Clippy too_many_arguments, lizard, SonarQube S107 and Pylint R0913 all count one callable at a time.

This is not the serialized total. The function_args and closure_args keys above are subtree sums: a function that declares two parameters and contains a three-parameter nested function reports function_args: 5. Before #1196 the gate read that sum, so a three-parameter function with a two-parameter sort comparator was flagged at 5, and the remediation its number implied, fewer parameters, was not the one that would clear it.

The number the gate does read is serialized as value, added in #1236 so a JSON-consuming front-end can reproduce the gate. Until then the Python to_sarif binding had nothing but total to compare and reported breaches bca check did not.

Nothing escapes the narrower rule. In the twelve grammars whose closures open their own space — Rust, JavaScript, TypeScript, TSX, MozJS, C#, Go, PHP, Perl, Ruby, Lua and Elixir — a closure is gated on its own offender row, which is also where its fix belongs. In Python, Java, Kotlin, C++ (and its Mozilla dialect), Groovy and Objective-C a lambda, closure or block opens no space, so its arguments can only be attributed to the enclosing function; there the offender row shows the split:

small: nargs = 8 (1 own + 7 lambda) (limit 5)

The split identifies how many arguments come from the enclosing signature and how many come from lambdas.

Both lists are read from the per-language role tables rather than maintained by hand: a language is in the first when every kind its Closure row owns is also an opener of its FuncOpener row, and in the second when none is (closures_that_open_a_space_are_what_the_book_says in big-code-analysis-ast/src/roles/space_tree_tests.rs pins the two against this paragraph; Bash, C, Tcl and iRules have no closure at all).

0 と表示される言語

A metric that silently reports 0 reads as “no offenders” rather than “not measured”, so know where the count is inert:

• Bash: correct and permanent. The shell has no formal parameter list; arguments arrive as $1, $2, and so on. It is the only language where every function reads 0.
• Perl subs without a signature: correct. Signatures (sub add($x, $y)) are counted; a sub that reads its arguments from @_ declares no formal parameters to count.
• Perl anonymous subs: a gap, and an upstream one. The grammar parses an anonymous sub’s signature inside an error node, so my $f = sub ($x) {…} reads 0 even though it has a signature.

したがって nargs の制限は、Bash のコードベースでは不活性であり、use v5.36 以前に書かれた Perl ではまばらにしか効きません。リポジトリ全体ではなく言語ごとにゲートしてください。しきい値の選択を参照してください。

読み方

A function with many arguments is hard to call correctly and harder to test exhaustively, since the test matrix grows roughly exponentially. The classic refactoring advice is the introduce parameter object pattern: when a function takes more than four related arguments, group them into a record / struct / dataclass.

The common use is as a review-blocking lint rule: most linters (Pylint’s R0913, ESLint’s max-params, Checkstyle’s ParameterNumber) flag functions with more than a configurable threshold. NArgs is also a useful component of API-design dashboards: public APIs whose average NArgs has crept upward over time tend to be ones that have accreted “just one more parameter” feature flags.

NExits

NExits counts the number of distinct exit points from a function: every explicit return, every throw / raise, and (in Rust) every ? early-return. A generator’s yield counts in Python, the JavaScript family, C# and PHP, because it hands control back to the caller, and so does C++’s co_yield; C++’s co_return is a return (#1547). The implicit fall-through return at the end of a function is not counted; only explicit exits are (see issue #243).

The metric goes back to the structured-programming literature of the 1970s, where Edsger Dijkstra and others argued that functions should have a single entry and a single exit point (the “SESE” rule). Modern thinking is more nuanced; see Steve McConnell’s Code Complete, 2nd edition (Microsoft Press, 2004), which recommends early returns as a clarity-improving pattern when they reduce nesting.

big-code-analysis は各関数の構文木を走査し、言語固有の出口ノードを特定し（src/metrics/nexits.rs の言語ごとの Exit トレイトを参照）、関数ごとのカウントに加えてファイルレベルの sum、average、min、max を報告します。シリアライズされたフィールド名は nexits で、本文で使っている略語表記と一致します。

読み方

Strict SESE coding standards (DO-178C for avionics, MISRA C for embedded automotive) still require an NExits of 1 per function, because multiple exit points complicate certified control-flow analysis. Outside those domains, an NExits of 2-4 is usually a good sign: it almost always means the function uses guard clauses to handle preconditions and then proceeds in a flat body.

A very high NExits, say above 8, is the warning sign. It usually means the function should have been split into several smaller functions, with each “successful branch” becoming its own helper.

NOM

NOM stands for Number Of Methods and counts every function, method, and closure defined inside a given scope (file, class, or namespace). It is one of the first metrics Mark Lorenz and Jeff Kidd introduced in their 1994 book Object-Oriented Software Metrics (Prentice Hall, ISBN 0-13-179292-X), where it is treated as the primary class-size indicator.

big-code-analysis は src/metrics/nom.rs で、呼び出し可能要素の種類ごとに分割してカウントを報告します。シリアライズされるフィールドは functions、closures、functions_average、closures_average、total、average（内包するスペース全体での平均）、および種類ごとの functions_min、functions_max、closures_min、closures_max です。

この分割により、同じコードに対して異なる問いを立てられます。クロージャが多く関数が少ない Rust クレートはイテレータ中心のコードに典型的であり、関数が多くクロージャが少ない Python モジュールはスクリプト風のコードに典型的です。

Some constructs that carry executable code are deliberately counted by neither field: Kotlin property accessors (get() / set()) and init blocks, Java and Groovy static { … } initialisers, and JavaScript class static blocks. Each opens a function space, so it has its own complexity scores, bca check can flag it, and it contributes to WMC. But none is a callable you name at a call site, and counting an accessor as a method would make NPM bill the same property once as an attribute and again as a method, skewing the NPA/NPM ratio the OOP metrics exist to report. A Kotlin file of nothing but property accessors therefore reports nom.functions == 0 while still reporting their complexity (#1184).

読み方

NOM is the input to several other metrics: WMC sums cyclomatic complexity across the same set of methods that NOM counts, and NPM filters that same set down to public methods. As a standalone metric, the Lorenz–Kidd recommendation is ≤ 20 methods per class. The common use is as a God-class detector: a class with NOM in the dozens is almost always doing too much, and is a strong candidate for “extract collaborator” refactoring as documented in Martin Fowler’s Refactoring catalogue entry on Large Class.

NPA

NPA counts the number of public attributes (also called fields, properties, or instance variables) declared by a class or interface. It is part of the metric family introduced by Lorenz and Kidd in Object-Oriented Software Metrics (1994) and was later folded into the MOOD (“Metrics for Object-Oriented Design”) suite proposed by Brito e Abreu and Carapuça (1994).

big-code-analysis splits the count by definition-site kind: classes (concrete types with state) and interfaces (abstract contracts). The serialised output (src/metrics/npa.rs) is class_npa_sum (sum of NPA across all classes), interface_npa_sum (sum across interfaces), class_attributes (sum of all attributes, public or not, across classes), interface_attributes, class_cda (class density of public attributes, an accessibility ratio rather than an average), interface_cda, total, total_attributes, and cda. The per-language Npa trait decides what counts as “public” (Java public, C# public, Rust pub, Python’s “no leading underscore” convention, and so on) and what counts as “attribute” rather than “method”.

Which spaces carry NPA, NPM and WMC

NPA and NPM are emitted on container spaces (class, struct, trait, impl, namespace, interface) and on the whole-file unit root, which carries the roll-up across every container in the file. WMC follows the same rule wherever it is computed at all, which is narrower in two ways set out below. A function space does not carry any of them: a method owns no methods or attributes of its own, so the block would be all zeros. Before big-code-analysis 2.1.0, NPA and NPM did emit that all-zero block on function spaces in C#, JavaScript, MozJS, TypeScript, TSX, PHP and Ruby, and on the Kotlin, Java, Groovy and JS-family accessor / init / static spaces. In the same release Go, Rust, Python, C++, Objective-C and Elixir went the other way: they decided from their own grammar node kinds, so a struct declared inside a function put the block on that function space, while a namespace or a file root with no container at file scope carried none. Both deviations are gone; the space’s kind is now the only input, for every language.

That rule governs the block, not the numbers behind it: the counts roll up through every enclosing space regardless. So a type declared inside a function body is reported by the nearest enclosing container, or by the file root when there is none.

Four things read differently. A Go file’s NPA and NPM live on the unit root and nowhere else, because Go is the one language that emits them without having a container kind in its space tree: type … struct and type … interface open no space of their own. (Bash, C, Lua, Perl, Tcl and iRules have no container kind either, but they emit neither block anywhere, so the question does not arise.)

Neither WMC narrowing moves NPA or NPM, which is why the rule above still holds as stated for those two. The first is language-level: Go emits no wmc block at all, on any space including the unit root, because its flat space model cannot attribute a method to a receiver class. So a Go file carries npa and npm at the root and wmc nowhere. The second is space-kind-level: a namespace space carries npa and npm but no wmc, because a namespace’s member functions are free functions rather than methods of a class, so there is no per-class complexity to weight. That covers every construct mapping to SpaceKind::Namespace (a C++ or Mozcpp namespace, and a Ruby module), not just the C++ spelling. Objective-C has no namespace construct of its own, so the case does not arise there. The class inside the namespace carries all three, and so does the file root.

Finally, the CSV projection is a fixed-column format: it writes the npa.* / npm.* columns on every row regardless of space kind, carrying the real accessor values rather than eliding them.

Thresholds are narrower still: bca check gates npa / npm on container spaces only, never the file root (see Threshold scope). Taken with the paragraph above, that has a direct consequence: since a Go file’s NPA and NPM are only ever reported at the root, no npa or npm threshold can fire on Go source.

読み方

NPA is a direct measure of encapsulation. Every public attribute is a piece of internal state that callers can read or write without going through a method, which means it is a piece of internal state the class cannot validate or evolve without breaking callers. The canonical guidance, first stated in Bertrand Meyer’s Object-Oriented Software Construction (Prentice Hall, 1988) and known as the Uniform Access Principle, is to keep NPA at or near zero and to expose state through public methods instead.

The common use is API-stability auditing: a public library class whose NPA grows over time accumulates breaking-change liability faster than its public-method surface.

NPM

NPM は、クラスまたはインターフェイスが宣言する公開メソッドの数を数えます。NPA のメソッド側の対になるもので、こちらも Lorenz と Kidd（1994 年）によって体系化されました。

As with NPA, big-code-analysis splits NPM by definition-site kind (classes vs. interfaces). The serialised output (src/metrics/npm.rs) is class_npm_sum (sum of NPM across classes), interface_npm_sum, class_methods (sum of all methods, public or not, across classes), interface_methods, class_coa, interface_coa (operation-accessibility ratios, not averages), total, total_methods, and coa. It follows the same emission rule as NPA (above). The language-specific Npm trait decides what counts as public (for example, Rust’s pub, Python’s leading-underscore convention, C++’s public: section) and folds together regular methods, constructors, and operator overloads as appropriate.

NPM は、Mark Hitz と Behzad Montazeri の Class Interface Size メトリクス や、Chidamber と Kemerer の Response For a Class（RFC）への入力の 1 つでもあります。

読み方

NPM is the public interface size. A class with NPM in the dozens is a class with too large an API contract: every public method is something callers can come to depend on, and every change to it is a breaking change. The Lorenz–Kidd guidance is ≤ 20 public methods per class, with anything over 40 considered a strong refactoring candidate. The same rule applies with particular force to interfaces in Java and C#, where the contract is the shape clients pin against.

The common use is as a public-API change tracker for libraries: monitoring NPM at the package level catches accidental expansion of a library’s surface area in the same way that NPA catches accidental exposure of internal fields.

Tokens

Tokens is a per-function and per-file count of the tree-sitter leaf tokens (identifiers, literals, keywords, punctuation), excluding any token whose AST ancestor is a comment node. It is a lexer-driven size proxy intended as a more formatting-resilient alternative to LOC. The same idea is known from Terry Yin’s lizard command-line tool, where many readers will first have seen a token-count metric.

The implementation lives in src/metrics/tokens.rs. Because Tokens counts every leaf, including punctuation that Halstead deliberately skips, the value will not equal Halstead N1 + N2, and because it counts tokens rather than lines it is not equivalent to any LOC variant. Whitespace-only reformatting, renaming a variable, and removing a comment all leave Tokens unchanged. Edits that change the tokens themselves (adding an if, adding optional braces around a single-statement block, or inserting or removing semicolons in a language where they are optional) do change the count.

読み方

Tokens is less sensitive to formatting than LOC. It is the right size measure when you are normalising another metric across languages or across teams with different style conventions: bugs per KSLOC is sensitive to formatting, while bugs per 1000 tokens is much less so.

The common use is as the defect-density denominator of choice in cross-language research: a 1000-line Java file and a 1000-line Lisp file contain very different amounts of code, but a 1000-token slice of each contains roughly the same amount of information. This makes Tokens useful for machine-learning code-quality models that train across many languages.

WMC

WMC (Weighted Methods per Class) is the first metric in the Chidamber and Kemerer suite, introduced in their 1994 IEEE Transactions on Software Engineering paper A Metrics Suite for Object Oriented Design (volume 20, issue 6, pages 476-493). The CK suite comprises WMC, DIT, NOC, CBO, RFC and LCOM. big-code-analysis currently implements WMC and the simpler size metrics (NOM, NPA, NPM), with the inheritance- and coupling-based ones tracked for future work.

WMC is the sum of the cyclomatic complexity of every method defined in a class. The original paper deliberately left the “weighting” abstract: Chidamber and Kemerer wrote that “if all method complexities are considered to be unity, then WMC = n, the number of methods”. The empirical follow-up literature has settled on cyclomatic complexity as the weight, and that is what big-code-analysis uses.

アルゴリズム

For each class or interface found by the per-language parser, big-code-analysis sums the standard cyclomatic complexity of every method body inside it (src/metrics/wmc.rs). The file-level serialised output is three fields: class_wmc_sum (sum of WMC across all classes in the file), interface_wmc_sum (sum across interfaces), and total (the two combined). No min/max/average aggregation is emitted at the file scope. To rank individual classes by WMC, use the report subcommand, which surfaces a Type hotspots (top N by WMC) section (see Commands → Report).

読み方

Chidamber と Kemerer は WMC について 3 つの仮説を提示し、そのすべてがその後繰り返し検証されてきました。

1. WMC が高いほど保守工数の増加を予測します。 個々のメソッドが複雑なクラスは、理解しにくくなります。
2. WMC が高いほど再利用が減ります。 多くの複雑なことを行うクラスは、新しいコンテキストに投入しにくいのです。
3. WMC が高いほどアプリケーション固有の振る舞いが広いことを示唆します。 そのようなクラスは、再利用可能な部品ではなく「メインループ」型のコーディネーターになりがちです。

The common use is God-class detection: combined with NOM, WMC is one of the clearest signals that a class needs to be split. For a class with high NOM but low WMC, check whether the methods form a cohesive data API before splitting the class. A class with low NOM and high WMC has a few gargantuan methods (split the methods, not the class). A class with both high NOM and high WMC is the classic God class.

次のステップ

• 対応言語 の章では、対応しているすべての言語と文法を一覧しています。一部のメトリクス定義（NPA、NPM、WMC）はクラスを持つ言語でしか意味をなさないため、メトリクスの対応範囲は言語によって異なります。
• The Supported Change-history (VCS) Metrics chapter covers the complementary family derived from version-control history rather than from the source AST: commit frequency, churn, ownership, and the composite risk and hotspot scores.
• Commands → Metrics のページでは、これらの数値の JSON / YAML / TOML / CBOR 出力を生成するための bca metrics の呼び出し方を説明しています。
• レシピ の章では、これらのメトリクスから品質レポートを生成するエンドツーエンドの例を示します。ダッシュボードへのパイプライン連携も含みます。

対応する変更履歴（VCS）メトリクス

This chapter describes the change-history metrics: the signals big-code-analysis derives from version-control history rather than from the source AST. Where the Supported Code Metrics chapter measures the shape of the code as it exists today, these metrics measure how that code got there: how often it changes, how much, by how many people, and in what kind of commits. Each section starts from the empirical paper that first connected the signal to defects, walks through how big-code-analysis computes it, and explains how to read the number in practice.

このファミリー全体は bca vcs コマンドで計算され、bca metrics --vcs の出力に付加されます。Commands → Change-history (VCS) metrics のページが、フラグ、ウィンドウ、出力形式、キャッシュを説明しています。この章が 「なぜ」 を、あちらのページが どうやって を担います。

Four framing notes:

• These metrics predict where defects cluster, not whether code is correct. The defect- and vulnerability-prediction literature consistently finds that process signals (how a file has been edited over time) out-predict product signals like size or complexity. Graves and colleagues put it bluntly in 2000: the number of times a module has been changed is a better predictor of its fault count than its length. None of these numbers measures correctness; they rank files by the probability that a bug is hiding in one.
• すべては 2 つのウィンドウで測定されます。 呼び出しごとの 1 回の履歴走査で、長期ウィンドウ（デフォルト 12mo ≈ 365 日）と直近ウィンドウ（デフォルト 90d）の両方についてすべてのシグナルが生成されます。直近性はジャストインタイム欠陥予測の系譜における最も強い単独シグナルであるため、全体を通じて直近の活動は古い活動より重く重み付けされます。
• 複合スコアは順序尺度であり、基数尺度ではありません。 risk_score、hotspot_score、コミットレベルの JIT スコアは温度計ではなく物差しです。意味を持つのは相対的な順位だけです。リポジトリのファイル（またはコミット）を互いに対して、あるいはそのリポジトリ自身の時間的な分布に対してランク付けしてください。絶対値を確率として読んだり、無関係なプロジェクト間で生のスコアを比較したりしないでください。
• レコードが存在しないことはゼロではありません。 追跡されていないファイルにはレコードがまったく存在せず、これはウィンドウ内の活動がゼロの追跡対象ファイルとは区別されます。計算結果としての 0.0（たとえば、常に単独でしか変更されなかったファイルの共変更エントロピーはゼロです）は実際の測定値です。

一覧

コミット頻度

最も単純な変更履歴シグナルは、ファイルにいくつの個別コミットが触れたかです。big-code-analysis はこれをウィンドウごとに commits_long と commits_recent として記録します。

このメトリクスの欠陥予測指標としての評価は、Todd Graves、Alan Karr、J. S. Marron、Harvey Siy による 2000 年の IEEE TSE 論文 Predicting Fault Incidence Using Software Change History に由来します。大規模な電話交換システムを研究した彼らは、変更履歴から導かれるプロセス指標が、コードそのもののどのプロダクトメトリクスよりも欠陥率をよく予測すること、なかでも過去の変更回数が最も強力な指標のひとつであることを見出しました。直観は単純です。誰も触れないファイルは、誰も壊していないファイルだということです。

アルゴリズム

A single history walk visits each commit reachable from the analysed ref (first-parent only by default; --full-history follows all parent links in the commit graph) and attributes it to every file it modifies. Merge commits are excluded unless --include-merges is passed, and renames are followed by default so a file’s history survives a move. The walk counts distinct commits per file per window, not diffs or hunks, so a commit that touches a file once and a commit that touches it in three hunks both count as one.

読み方

Commit frequency is a rate, so it is only meaningful relative to a baseline: this file versus its siblings, or this file this quarter versus last. A consistently high count flags a file that is under active feature development or structurally unstable; pairing it with code churn tells the two apart, since heavy churn on few commits is a different story from light churn on many.

コードチャーン

コードチャーンは変更の量です。ファイルに触れた追加行数と削除行数の合計で、ウィンドウごとに churn_long と churn_recent として記録されます。

チャーンの欠陥予測としての系譜は、Nachiappan Nagappan と Thomas Ball による 2005 年の ICSE 論文 Use of Relative Code Churn Measures to Predict System Defect Density にあります。Windows Server 2003 で検証された彼らの主要な発見は、絶対 チャーン単独では予測力が乏しい一方、ファイルサイズや変更の時間的な広がりに対する 相対 チャーンは欠陥密度を高い精度で予測する、というものです。big-code-analysis はウィンドウごとの生のチャーンをシグナルとして保持し、単一の絶対値を判定として報告するのではなく、複合スコアがそれをサイズや新しさと組み合わせられるようにしています。

アルゴリズム

For every in-window commit touching a file, the walk adds that diff’s added-plus-deleted line count to the file’s churn total for the window. Because added and deleted lines are summed, a one-line edit counts as two (one deletion, one addition): churn measures activity, not net growth.

読み方

Churn is the natural numerator for a density ratio. Churn per commit distinguishes steady editing from a few large rewrites; churn against file size recovers Nagappan and Ball’s relative measure. A file whose recent churn is high relative to its long-window churn is changing faster now than its history would predict, which is the burst signal below.

バースト

バーストは、ファイルの活動のうち直近ウィンドウに集中している割合で、commits_recent / commits_long を [0, 1] の比率として報告します。1 に近い値はファイルのコミットのほぼすべてが直近のものであることを、0 に近い値はファイルが昔は活発だったがその後静かになったことを意味します。

The signal follows from the recency principle that runs through the change-history literature. Graves and colleagues found that recent changes weigh more heavily on fault incidence than old ones, and the just-in-time defect-prediction line (see the JIT score) is built on the same observation. A file whose change history is front-loaded into the present is in active flux, and active flux is when defects enter.

読み方

バーストは単独の警報ではなく、判定の決め手（タイブレーカー）です。総履歴の少ないファイルでの高いバーストは、若く動きの速いファイルを意味します。深い履歴を持つファイルでの高いバーストは、突然目を覚ました古いファイルであり、多くの場合こちらの方が興味深いケースです。経過日数と合わせて読むことで両者を見分けられます。

作者数と所有権

関連する 2 つのシグナルが、ファイルを 誰が 変更しているかを表します。作者数（authors_long、authors_recent）は、各ウィンドウでそのファイルに触れた個別の人数を数えます。所有権（ownership_top_share、[0, 1] の比率）は、最も活発な単一の作者に帰属する編集の割合です。低いシェアは所有権が分散していることを、高いシェアは一人が支配的であることを意味します。

Both trace to empirical work on ownership and security. Christian Bird and colleagues’ 2011 FSE paper Don’t Touch My Code! Examining the Effects of Ownership on Software Quality found, on Windows Vista and 7, that diffuse ownership (many low-expertise contributors, a low top-owner share) predicts both pre-release faults and post-release failures. On the security side, Andrew Meneely and Laurie Williams’ 2009 CCS paper Secure Open Source Collaboration: An Empirical Study of Linus’ Law reported that Red Hat Enterprise Linux 4 files touched by nine or more developers were roughly sixteen times more likely to harbour a vulnerability.

アルゴリズム

Author identities are canonicalised through the repository .mailmap and counted by lowercased email, so a contributor who commits under two addresses counts once. Co-authored-by: trailers add participants. Bot identities (dependabot[bot], renovate[bot], github-actions[bot], and similar) are excluded by default so automated churn does not inflate the count. ownership_top_share is the top author’s edit count over the file’s total edits in the window.

読み方

A rising author count on a long-lived file is a knowledge-diffusion signal: more people are now obliged to understand it. The composite risk score folds this in two ways. It scales the author factor by an ownership-dilution term (1 - ownership_top_share), so the same head-count counts for more when ownership is spread thin, and it adds categorical bumps at the six- and nine-developer marks that encode Meneely and Williams’ RHEL4 thresholds. For knowledge concentration across a set of files rather than within one, see the bus factor.

修正・セキュリティ・リバートコミット

big-code-analysis は、ファイルに触れる長期ウィンドウ内の各コミットをメッセージの意図で分類し、3 つのカウントを保持します。bug_fix_commits（バグ修正キーワードに一致するメッセージ）、security_fix_commits（CVE-####、security、vuln、exploit、sanitize などに一致するメッセージ）、revert_commits（リバートまたはロールバックである件名）です。

Reading a commit’s purpose from its message is the technique introduced by Jacek Śliwerski, Thomas Zimmermann, and Andreas Zeller’s 2005 MSR paper When Do Changes Induce Fixes?, the work now abbreviated SZZ. The premise is that a file’s history of corrective change is itself predictive: a file that has needed many fixes is a file likely to need more. A security fix is a sharper signal than an ordinary bug fix, and a revert marks a change that had to be undone, a localized admission that something went wrong there.

アルゴリズム

Classification is keyword-based on the commit subject and body (see src/vcs/classify.rs). It is deliberately simple and language- and tracker-agnostic: there is no issue-tracker linkage and no blame back-tracing to the fix-inducing commit, so this is the message-classification half of SZZ, not the full algorithm. The counts are kept over the long window only.

読み方

A high bug_fix_commits count is a file that keeps needing repair. The weighted composite score combines bug-fix and security-fix counts in a log-scaled term, with security fixes double-weighted, so a file with a history of security fixes ranks above an otherwise-identical file with only ordinary bug fixes. The file-level formula does not use revert_commits; only the just-in-time commit score reads the revert classification. Because the classifier reads messages, its accuracy tracks your project’s commit hygiene: a repository with terse or templated messages will under-count.

経過日数と最終更新

2 つのタイミングシグナルがファイルの履歴を区切ります。age_days はファイルの 最初の ウィンドウ内コミットからの経過日数（長期ウィンドウを上限とする）、last_modified_days は 最新の ウィンドウ内コミットからの経過日数です。

These anchor the recency reasoning the rest of the family depends on. A small age_days marks a new file, and newly added code carries elevated risk, an observation from the just-in-time line and from Chromium’s own defect analysis, where freshly added features were disproportionately fault-prone. A small last_modified_days marks a file edited recently, which the windows already weight.

読み方

age_days の最大の用途は、リスクスコアに供給される新規ファイルトリガーです。直近ウィンドウ内で初めて観測されたファイルは小さな加点を得ます。これは、できたばかりのコードが実行やレビューを経る機会を最も持っていないことを反映しています。last_modified_days は逆方向の陳腐化の読み取りです。何か月も触れられていない高リスクファイルと、今日編集されているファイルとでは、保守上の位置付けが異なります。

変更エントロピー

変更エントロピーは、ファイルに触れるコミットがどれだけ 「分散」 しているかを測ります。ウィンドウごとに change_entropy_long と change_entropy_recent として、ビット単位で報告されます。

The metric is Ahmed Hassan’s History Complexity Metric from the 2009 ICSE paper Predicting Faults Using the Complexity of Code Changes. The idea adapts Shannon entropy to commits: for each commit, take the distribution of its churn across the files it touched and compute that distribution’s entropy in bits. A commit that touches one file scores 0; a commit that spreads its churn evenly across n files approaches log₂(n). A scattered, cross-cutting commit is harder to reason about than a focused one. Hassan reported that this change-process complexity predicts faults better than prior code-based or change-count models; later work measured file-level change entropy at a Pearson correlation up to 0.54 with defect counts on eight Apache projects (see co-change entropy).

アルゴリズム

For each commit, big-code-analysis computes the Shannon entropy H of its churn distribution across the touched files (see src/vcs/entropy.rs). Each participating file is then credited its churn share pᵢ·H of that commit (Hassan’s History Complexity Metric), and these shares are summed per file per window. A file repeatedly caught up in diffuse, multi-file changes accumulates high change entropy; a file that only ever changes in tightly focused commits stays low.

読み方

変更エントロピーは、生のチャーンが同一であっても、大きく散漫な編集の一部として 変更されるファイルと、自己完結したコミットで変更されるファイルを区別します。高い変更エントロピーは 横断的関心事 の兆候です。このファイルへの編集が、いつも多くの他ファイルを巻き込んでいるということです。これは直近ウィンドウのリスク項に加算的に入り、チャーンやコミット数の言い換えではなく補完として働きます。

共変更エントロピー

Co-change entropy measures how wide a file’s change blast radius is: how many different files it tends to change alongside. It is reported per window as cochange_entropy_long and cochange_entropy_recent, in bits.

The signal comes from the 2025 study Co-Change Graph Entropy: A New Process Metric for Defect Prediction (arXiv 2504.18511). Build a weighted graph in which two files share an edge whenever they change in the same commit, the weight being the number of shared commits. A file’s co-change entropy is the Shannon entropy of its edge-weight distribution: low when it always co-changes with the same one partner, high when its changes ripple out across many different files. The study found that adding co-change entropy to change entropy improved the area under the receiver operating characteristic curve (AUROC, a measure of ranking discrimination) in 82.5% of cases over the prior signal set across eight Apache projects.

アルゴリズム

The walk records, per commit, which in-scope files changed together and accumulates the co-change graph’s edge weights, then computes each file’s edge-weight entropy per window. Bulk-import commits touching more than 1000 files are excluded from the co-change graph, whose edge count grows with the square of commit width, though they still contribute their (linear-cost) change entropy. A computed 0.0 means the file has no co-change neighbours or only one neighbour in the window. It is a real measurement, not a missing record.

読み方

Where change entropy asks “how scattered are the commits that touch this file?”, co-change entropy asks “how many other files does touching this one drag along?”. A high value flags a file whose edits have unpredictable, far-reaching consequences: a coupling hotspot. The two entropy signals complement each other, and the risk score v2 adds both recent-window terms together.

複合リスクスコア

リスクスコアは、上記のすべてのシグナルをファイルごとの単一の数値 risk_score に集約します。これは bca vcs の主要な出力であり、ランキングテーブルのソートキーとなるフィールドです。2 つの式が用意されており、どちらも単一の risk_score_version（現在は 2）で一緒にバージョン付けされるため、下流の消費者は変更を検出できます。

重み付き式（デフォルト）

The default formula is a log-scaled weighted sum with categorical multiplicative bumps. Counts are passed through ln(1 + x) so that the difference between 10 and 20 commits matters more than the difference between 110 and 120, matching how change activity saturates:

base = 0.30 · ln(1 + churn_recent)
     + 0.25 · ln(1 + commits_recent)
     + 0.15 · ln(1 + commits_long)
     + 0.15 · ln(1 + authors_long) · (1 + dilution)
     + 0.10 · ln(1 + bug_fix_commits + 2 · security_fix_commits)
     + 0.05 · ln(1 + churn_long)
     + 0.10 · change_entropy_recent + 0.05 · cochange_entropy_recent
     + ln(1 + sloc)² / 100

risk_score = base · (1 + dev_bonus + new_file_bonus)

ここで dilution = 1 - ownership_top_share であり、dev_bonus は長期ウィンドウの作者が 9 人以上で 0.35、6 人以上で 0.15、new_file_bonus は直近ウィンドウ内で初めて観測されたファイルに対して 0.15 です。重みは、本章で引用した文献に項ごとに根拠づけられています。直近のチャーンとコミット頻度が最大の重みを持ち（Nagappan & Ball、JIT 系）、作者ファクターは所有権の希薄化でスケーリングされ（Bird et al.）、RHEL4 の開発者数しきい値で加点され（Meneely & Williams）、セキュリティ修正は 2 倍に重み付けされ、2 つの直近ウィンドウのエントロピー項は加算的に入ります（Hassan、arXiv 2504.18511）。完全な導出は src/vcs/score.rs にあります。

The size term ln(1 + sloc)² / 100 is a real contributor, not the tie-breaker its position at the end of the sum might suggest: it reaches about 0.85 at 10k SLOC and exceeds 1.0 past roughly 50k SLOC, comparable in magnitude to the churn terms. Large files are only weakly correlated with defects, but the squared-log scaling keeps size a first-class additive signal rather than letting it dominate.

パーセンタイル式

--risk-formula percentile is the alternative: each signal is re-ranked to its percentile within the analysed set, and the per-file mean of those percentiles becomes the score. This formula replaces fixed weights with relative ranks within the analysed file set. Prediction research recommends relative triggers over fixed absolute thresholds, but this score is meaningful only within one run’s file set.

読み方

The score is ordinal. Sort a repository’s files by it and look at the top of the list; that is the ranking the score exists to produce. Do not compare a raw risk_score between two repositories, and do not read its magnitude as a defect probability. To watch a single file move over time, use bca vcs trend, which re-anchors the walk at each historical point so the series reflects what the file looked like then.

ホットスポットスコア

The hotspot score is the product of a file’s complexity and its recent churn: hotspot_score = cyclomatic_sum × churn_recent. It is an Option, present only when an AST complexity figure is computed alongside the history (for example bca metrics --metrics cyclomatic --vcs), because it needs both halves. A per-function block uses the space’s own cyclomatic instead of the subtree sum, so a nested function’s complexity is not counted again in every enclosing space.

The metric is the central idea of Adam Tornhill’s 2015 book Your Code as a Crime Scene and the CodeScene tooling built on it. The argument is that complexity on its own is cheap to ignore (a complex file nobody touches costs nothing) and churn on its own is cheap too. The danger is their intersection: code that is both complicated and changing often is where defects concentrate and where developer effort is repeatedly spent. Tornhill observes that a small fraction of a codebase typically accounts for a large majority of its change activity, and the hotspot score is built to find that fraction.

読み方

リスクスコアと同様、ホットスポットの積は順序尺度です。ファイルをこれでランク付けし、大きさそのものは読まないでください。CLI は慣例として複雑度の軸にファイルレベルの cyclomatic 合計を使いますが、どの AST 複雑度の数値でも役割を果たします。このスコアの価値は 優先順位付け にあります。複雑なファイルすべての中から、現に編集されているものを浮かび上がらせます。それらは最も壊れやすく、かつ誰かの画面ですでに開かれている今こそ最も安上がりにリファクタリングできるファイルです。

バスファクター

ownership_top_share が単一ファイル 「内」 の知識集中を測るのに対し、バスファクター（トラックファクター とも呼ばれます）はそれを ファイル集合をまたいで 測ります。その離脱によってディレクトリのファイルの半分超が知識ある保守者を失うことになる、最小の開発者数です。この概念全般には Wikipedia の概説があります。big-code-analysis はこれを、リポジトリ全体、各トップレベルディレクトリ、およびその直下のサブディレクトリを対象とする vcs_aggregate オブジェクトとして出力します。

推定手法は、Guilherme Avelino、Leonardo Passos、Andre Hora、Marco Tulio Valente による 2016 年の ICPC 論文 A Novel Approach for Estimating Truck Factors のものです。各開発者の各ファイルに対する作者性は、彼らの Degree-of-Authorship ヒューリスティックでスコア付けされます。

DoA(d, f) = 3.293 + 1.098 · FA + 0.164 · DL − 0.321 · ln(1 + AC)

ここで FA は最初の作者性（開発者 d がファイル f を作成していれば 1）、DL は d の f への提供（変更）回数、AC は 「他の」 開発者による変更数です。開発者は、ファイルの最大値で正規化した DoA が 0.75（論文のしきい値）を超えるとき、そのファイルの作者とみなされます。

アルゴリズム

トラックファクターは貪欲な除去法で計算されます（src/vcs/bus_factor.rs を参照）。まだカバーされているファイルを最も多く作者として持つ開発者を繰り返し取り除き、--bus-factor-threshold（デフォルト 0.5、Avelino に準拠）を超える割合のファイルが孤児化した時点で停止し、取り除いた開発者数を報告します。集約は 1 回のウォークでスコープ内の全ファイルをカバーするため、by_directory の各エントリは各ディレクトリ配下の全ファイルを再帰的に対象として計算されます。

読み方

A bus factor of 1 means losing one person orphans the set, which is common, and correct, for a repository of mostly single-author files. Treat the number as a planning signal, not a guarantee: it is a heuristic over observed authorship within the long window, so “first authorship” means the earliest commit seen in that window, not necessarily a file’s true creation. Use it to find the directories where knowledge is dangerously concentrated and spread review accordingly.

ジャストインタイムコミットスコア

Everything above ranks files at a point in time. The just-in-time (JIT) score estimates the defect-induction risk of a single commit. A continuous-integration gate reviews that commit at check-in. bca vcs commit <commit> reports an ordinal risk_score and a per-group contributions breakdown.

特徴量グループとその符号は、Yasutaka Kamei らによる 2013 年の IEEE TSE 論文 A Large-Scale Empirical Study of Just-in-Time Quality Assurance に始まり、公開追試の Commit Guru（FSE 2015）および Shane McIntosh と Yasutaka Kamei の Are Fix-Inducing Changes a Moving Target?（IEEE TSE 2018）で確認された、ジャストインタイム欠陥予測の文献から採られています。big-code-analysis は学習済みモデルではなく静的なルールベースのスコアラーを実装しているため、プロジェクトが古びても何もドリフトしません。

アルゴリズム

5 つの特徴量グループがスコアを動かします。各グループはコミットの第一親に対して評価されます（src/vcs/jit.rs を参照）。

contributions ブロックは各グループの符号付き寄与を報告するため、消費者はコミットが 「なぜ」 その位置にランクされたかを確認できます。マージコミットはフラグ付けされ、第一親に対してスコア付けされます。ルートコミットと新規ファイルは構造上、事前値がゼロになるため、スコアはサイズと作者の経験に依拠します。これはファイル履歴のない変更に対して文献が定める通りの挙動です。素の git diff もスコア付けできます（bca vcs commit --diff）が、diff から計算できるのはサイズと拡散度のグループだけなので、その経路は意図的に部分的な partial_risk_score を出力します。

読み方

Like the file-level score, the JIT score is ordinal: rank commits by it, or compare a commit against the repository’s own commit-score distribution, but do not read the magnitude as a probability. Its intended use is a check-in gate: bca vcs commit HEAD --fail-above <N> exits non-zero when a commit scores at or above a threshold, with the threshold calibrated against your own history rather than treated as an absolute. Any change to the formula bumps a jit_score_version that is independent of the file-level risk_score_version.

次のステップ

• コマンド → 変更履歴（VCS）メトリクスのページでは、bca vcs の呼び出し方、ウィンドウの設定、出力形式の選択、永続的な履歴キャッシュの使い方を説明しています。
• The Supported Code Metrics chapter covers the AST-derived metrics these change-history signals complement; the hotspot score in particular combines the two families.
• Python バインディング → 変更履歴（VCS）メトリクスのページでは、同じファミリーを big_code_analysis.vcs モジュールから利用する方法を示します。

移行: フラグ CLI からサブコマンド CLI へ

This page is for users of the old flag-style CLI (one process, many mutually exclusive --action flags) who are moving to the subcommand CLI (bca <verb>). It maps every old invocation to its replacement. The mapping table is the quick reference; the side-by-side examples show each in context.

変更の理由

The flag CLI overloaded --output-format with two unrelated meanings: per-file serialization (-O json/yaml/toml/cbor) and a post-walk aggregated report (-O markdown). It needed two clap ArgGroups plus runtime checks to police invalid combinations, and --top / --strip-prefix lived as global flags that only applied to one format. Each further aggregated format (HTML, for example) would have compounded the fragility.

サブコマンド CLI はこの構造を修正します。bca metrics と bca ops はファイルごとの出力を、bca report <FORMAT> は集約レポートを出力し、各動詞は自分専用にスコープされたフラグ集合を持ちます。

移行対応表

新旧対照の例

集約 Markdown レポート

# 旧
big-code-analysis-cli \
    --metrics \
    --paths "$PWD" \
    --output-format markdown \
    --jobs $(nproc) \
    --top 20 \
    --strip-prefix "$PWD/"

# 新
bca \
    report \
    --paths "$PWD" \
    --format markdown \
    --top 20 \
    --strip-prefix "$PWD/"

ファイル単位のメトリクス抽出

# 旧
big-code-analysis-cli --metrics --paths ./src --output-format json --output ./out/

# 新（ファイル単位ツリー: --output は 2.0 で --output-dir になりました）
bca metrics --paths ./src -O json --output-dir ./out/

ファイル単位の ops 抽出

# 旧: big-code-analysis-cli --ops --paths ./src -O json -o ./out/
# 新: bca ops --paths ./src -O json --output-dir ./out/

AST ダンプ

# 旧: big-code-analysis-cli --dump --paths ./file.rs
# 新: bca dump --paths ./file.rs

ノードの検索 / カウント

# 旧: big-code-analysis-cli --find call_expression --paths ./src
# 新: bca find --paths ./src -t call_expression

# 旧: big-code-analysis-cli --count if_statement,for_statement --paths ./src
# 新: bca count --paths ./src -t if_statement -t for_statement

Note: find and count now take one node type per -t / --type flag (repeat it for several) rather than a positional or a comma-separated string; the positional slot holds input paths.

関数のスパン

# 旧: big-code-analysis-cli --function --paths ./src
# 新: bca functions --paths ./src

コメントの除去

# 旧: big-code-analysis-cli --comments --in-place --paths ./src
# 新: bca strip-comments --paths ./src --in-place

Preproc data: producer

# 旧
big-code-analysis-cli --metrics --preproc a.h --preproc b.h \
    --paths ./src -o /tmp/p.json

# 新
bca preproc --paths ./src -o /tmp/p.json

Preproc data: consumer

# 旧
big-code-analysis-cli --metrics --preproc /tmp/p.json \
    --paths ./src -O json -o ./out/

# 新
bca metrics --paths ./src --preproc-data /tmp/p.json \
    -O json --output-dir ./out/

メトリクス一覧

# 旧: big-code-analysis-cli --list-metrics descriptions
# 新: bca list-metrics descriptions

実行時の移行ヒント

If you run a legacy invocation, the CLI prints a hint naming the recognized old flags and their new equivalents before clap’s own error:

$ bca --metrics -O markdown
note: the CLI was restructured into subcommands. See the migration guide for the full mapping:
  https://dekobon.github.io/big-code-analysis/migration.html
  --metrics  ->  bca metrics
  -O markdown  ->  bca report markdown|html [--top N] [--strip-prefix P]
  Run `bca --help` for the new command list.

error: unexpected argument '--metrics' found

コマンド

bca is the command-line tool. Each subcommand performs one analysis and takes its own flags. This section covers what every subcommand shares: installation, how flags and input paths are placed, which files the walk visits, and the exit-code contract. The subcommands themselves each have a page: Metrics, Change-history (VCS) metrics, Report, Check, Suppression markers, Nodes, the REST API, and Operating bca-web.

インストール

The bca command-line tool ships as a pip-installable wheel. The distribution name is big-code-analysis-cli and the installed command is bca. The two differ on purpose: the bca name on PyPI belongs to an unrelated project, and big-code-analysis is this project’s importable library bindings.

pip install big-code-analysis-cli   # PATH に `bca` コマンドをインストールします
bca --version

This puts the compiled bca binary on your PATH the way pip install ruff gives you the ruff command, with no Rust toolchain required. The wheel carries the full all-languages grammar set, so every supported language works out of the box. A single py3-none-<platform> wheel covers every CPython 3.x (and PyPy) on that platform. Prebuilt wheels ship for Linux (manylinux_2_28 x86_64 / aarch64), macOS (x86_64 / arm64), and Windows (x86_64). On any other platform pip falls back to a source build, which needs a Rust toolchain.

This is the binary CLI, distinct from the importable Python bindings (pip install big-code-analysis). The repository README describes the other install paths: Homebrew, .deb / .rpm / .apk packages, prebuilt release archives, and cargo install big-code-analysis-cli.

wheel のビルドと公開のマトリクスは .github/workflows/python-cli-wheels.yml で定義されています。

メトリクス

Metrics are quantitative measures of source code. They help to:

• compare programming languages;
• describe the quality of a codebase;
• show developers where their code is hardest to handle;
• surface potential problems early in development.

bca computes its metrics from the source text alone, without running the program; such metrics are called static metrics. See Metrics for the command and Supported Metrics for each metric’s definition.

ノード

To represent the structure of program code, bca builds an Abstract Syntax Tree (AST). A node is an element of this tree and denotes one syntactic construct of the language. The Nodes commands use them to:

• print the syntactic structure of a source file;
• find whether a construct is present in the analyzed code;
• count the constructs of a given kind;
• detect syntax errors in the source.

REST API

bca-web runs a server offering a REST API. Clients send source code over HTTP and receive the corresponding metrics as JSON.

フラグの位置と入力パス

Most subcommands read the input they analyze as a trailing positional path, so the common case reads like every other code tool (tokei, cloc, scc, rg). The exceptions: report and vcs select input with --paths, diff compares two result sets, and init targets a directory via --dir.

bca metrics src/            # src/ ツリーを解析する
bca check src/ tests/       # 2 つのサブツリーをゲートする
bca find -t function_item . # 現在のツリー内のすべての関数を検索する

フラグは それを消費するサブコマンドにスコープされ、サブコマンドのトークンの後に 書く必要があります:

bca metrics --exclude '*.generated.rs' src/   # 正しい
bca --exclude '*.generated.rs' metrics src/   # エラー（終了コード 1）

Only -w / --warnings and --report-skipped are universal and accepted in any position. Every other shared flag lives in a help-grouped section on the subcommands that read it:

• Input selection: -p / --paths, -I / --include, -X / --exclude, -l / --language, --paths-from, --exclude-from, --no-ignore, --no-skip-generated, --no-config.
• Walker tuning: -j / --jobs, --exclude-tests, --cyclomatic-count-try, --mi-charges-docs.
• Preprocessor: --preproc-data.
• Output: --color.

A flag passed to a subcommand that never consumes it is a hard usage error (exit 1) rather than a silent no-op, so bca vcs commit --exclude-tests and bca list-metrics --paths both error, and bca list-metrics --help does not advertise walker flags.

-p / --paths フラグは引き続き機能し、位置引数のパスと 和集合 になります。つまり bca metrics a.rs --paths b.rs は両方を走査します。find と count サブコマンドは、繰り返し指定できる -t / --type フラグでノード種別を受け取ります（そのため位置引数のスロットはパス用に空いています）: bca find -t function_item -t struct_item src/。

生成コードのスキップ

Generated files inflate metrics for code no human will refactor. By default, bca scans the first ~50 lines / 5 KiB of each file for a generated-code marker and skips matches before parsing, so the skipped file pays no tree-sitter parse cost.

認識されるマーカー（大文字小文字を区別しません）:

• @generated: a marker emitted by code generators.
• DO NOT EDIT: a marker used by Go’s generated-code convention and other generators.
• GENERATED CODE: Lizard’s marker, recognized for compatibility.

A marker phrase that appears only deep in the file body (past the scan window) does not trigger the skip; the detector deliberately looks only at the file header.

このスキップは bca metrics、bca report、およびしきい値エンジンに一律に適用されます。

フラグ

• --no-skip-generated: disable the auto-skip, so every file is parsed.
• --report-skipped: log skipped (generated): <path> to stderr for each file the detector excludes, so you can audit the exclusions. If a file is wrongly tagged, pass --no-skip-generated; an include filter does not override the detector.

さらに bca check は、ゲート実行で検出器がファイルを除外した場合に 1 行のサマリーを stderr に出力します（bca: 1 file not checked (1 generated) — pass --report-skipped to list them）。また、--strict プロファイルは検出器そのものを無効にします。マーカーはテスト対象のブランチが管理するコンテンツなので、プルリクエストのゲートでは、それによって検査対象のファイル集合が狭められるべきではありません。

.gitignore の尊重

--paths にディレクトリが渡されると、bca はデフォルトで .gitignore を考慮して走査します。次のいずれかに一致するファイルは、パース前にスキップされます:

• 走査対象ツリー内の .gitignore ファイル。
• .ignore files (the ripgrep / fd convention).
• .git/info/exclude。
• グローバル gitignore（~/.config/git/ignore、または core.excludesFile が指す先）。
• 起点の祖先ディレクトリにある .gitignore ファイル（そのため、プロジェクトルートから bca metrics src/ を実行すると、プロジェクト最上位の .gitignore が反映されます）。

ウォーカーは、チェックインされた git リポジトリの外でも .gitignore を尊重します。そのため、.gitignore ファイルを含む展開済みのソース tarball も、git clone した直後と同じ扱いになります。

Hidden files (those whose basename starts with .) are filtered during the walk.

明示的なパスはフィルターを迂回する

Files passed by name (via --paths, --paths-from, or a trailing positional path) are always analyzed, even when the project’s ignore rules cover them. This makes it safe to run bca metrics --paths-from - from a git diff --name-only pipeline without losing files that happen to match a wildcard ignore rule.

The override is deliberate, and it is the same rule rg and fd apply: a path you named is a direct request. It spans every deny-set the walk consults: .gitignore and friends, -X / --exclude, --exclude-from, a .bcaignore, and a manifest exclude list alike. rg --glob '!x.txt' pattern x.txt searches x.txt for exactly this reason.

これには 2 つの境界があります。

• -I / --include は引き続き適用されます。 許可リストは、名指しされたファイルの「どれ」を解析するかを絞り込むため、bca metrics -I '*.rs' notes.md は何も解析しません。上書きされるのは拒否セットだけです。
• [check] exclude still applies. The gate-exemption set (--check-exclude / --check-exclude-from, or exclude under [check] in bca.toml) is not a walk filter: it drops violations, not files. It therefore survives an explicit path and reports bca: skipped N violations via [check.exclude] when it fires. A glob written in bca.toml resolves against the manifest’s directory whichever directory you run from (#1164); one passed as --check-exclude resolves against the working directory. See What a relative glob is relative to.

That second point is the one to reach for. A walker exclude shapes what gets analyzed; a check exclude shapes what gets gated. Anything you want kept out of the threshold gate permanently (dev tooling, generated code you still want measured, a subtree under active rewrite) belongs in [check] exclude, because any caller that names paths one at a time bypasses the walker excludes by design. Per-file callers are not hypothetical: that is the shape the agent feedback hooks use on every edit.

明示的に名指しされたパスが実際にウォーカーの除外を上書きした場合、bca は stderr でそのことを伝え、該当するグロブを名指しします。

warning: utils/gate.py matches an exclude pattern (./utils/**) but was named explicitly; analyzing anyway

パス探索フラグ

• --no-ignore: disable .gitignore / .ignore / global-gitignore awareness when expanding directory seeds. bca check counts the analyzable files ignore rules dropped from a gate run in its not-checked summary, lists every dropped entry under --report-skipped (note: skipped (ignored): <path>, note: skipped (ignored directory): <path>), and disables the awareness under its --strict profile, since an ignore file committed in the branch under test otherwise shrinks the checked set.
• --paths-from <FILE>: read newline-separated input paths from <FILE>, or from stdin when <FILE> is -. Combined as a union with any --paths values. -I globs still apply; -X globs do not reach an entry that names a file directly, per Explicit paths bypass the filter. Blank lines are skipped; # is treated as a path character (not a comment). To pass a file literally named -, write ./-.
• --exclude-from <FILE>: read newline-separated --exclude glob patterns from <FILE>, or from stdin when <FILE> is -. Patterns are unioned with any inline --exclude / -X values into a single deny-set; order does not matter. .gitignore-style: blank lines and lines whose first non-whitespace character is # are skipped, and a leading UTF-8 BOM is stripped. Convention is a .bcaignore at the repo root, mirroring .gitignore / .dockerignore. To pass a file literally named -, write ./-.

終了コード

bca はすべてのサブコマンドで単一の終了コード規約に従うため、CI スクリプトは出力を検査せずにプロセスのステータスで分岐できます:

Codes 2–5 are gate signals, emitted only by check, vcs commit --fail-above, and diff / diff-baseline under the opt-in --exit-code flag; they report a metric result, not a failure of the tool. Every other subcommand (metrics, ops, report, diff, diff-baseline, exemptions, init, and the rest) exits 0 on success and 1 on error. Code 1 is reserved for tool errors, usage errors included, so a mistyped flag never lands in the gate band and CI can always tell “the gate found a regression” (2–5) from “the tool itself failed” (1).

読み取れない入力

Every source-walking subcommand (metrics, ops, report, functions, find, count, dump, exemptions, preproc, strip-comments, check) exits 1 if any selected input file cannot be read: permission denied, or a path that vanished between the walk and the read. This includes init, which uses check to scaffold its baseline, and diff --since. Each failure names the path on stderr as error processing <path>: …, followed by a summary.

The rule is “any read failure”, not “no output at all”, because a missing file is invisible in the result. A partial metrics --output document, a report, or a count looks complete; a diff --since side that lost a file reports it as added or removed rather than as the I/O error it was. The exit code is the only place the failure can be observed, so it has to carry it.

Output streamed during the walk is still emitted, because the check runs after it. A mixed run therefore still shows the files that were read: the stdout trees of metrics / ops / dump / find / functions, and the per-file documents of --output-dir.

Output assembled after the walk is suppressed entirely, because a partial one is indistinguishable from a complete one. That covers the metrics --output / ops --output aggregate document, the report document, count’s tally, preproc’s JSON, and the exemptions report; none of them is printed or written.

開けないファイルがツリーに正当に含まれている場合は、--exclude で除外してください（あるいは --include でより狭い集合を指定します）。これらのフィルタで除去されたファイルは開かれないため、読み取り失敗にはなりません。

列挙できないディレクトリ

A directory the walk cannot list is the same failure one level up, and carries the same exit 1. Its whole subtree drops out of the analysed set before any file is selected, so every count downstream (the metrics document, the count tally, a diff --since side, vcs rank’s ranking) is short by an amount nothing in the output reveals. bca check is the worst case: a gate that reports clean on a tree it could not read is indistinguishable from a gate that passed.

Each unlistable entry warns on stderr as warning: skipping walk entry in …. The walk continues, so one bad directory does not take down the rest of the tree, and the run ends with a summary line and exit 1.

To exempt a directory you knowingly cannot list, name it in an ignore file (.gitignore, .ignore) or narrow --paths so the walk never reaches it. --exclude does not work here, though it is the right answer for an unreadable file: --exclude filters the paths the walk yielded, and a directory that could not be listed yielded none, because the failure happened before the filter could apply.

隣接する 2 つのケースは、設計上、致命的にはなりません。

• 不正な形式の ignore ファイル、またはその中のコンパイルできないパターン。 ウォーカーはこれらを同じチャネルで報告し、警告の形も同一ですが、これらが記述するのは走査が失ったファイルではなく、走査がどう「構成」されたかです。カウントされるのは基盤に I/O エラーを伴うエラーだけなので、.gitignore に紛れ込んだタイポがビルドを失敗させることはありません。
• A broken symlink discovered by walking. It is dropped for not being a regular file and never surfaces as an error at all. The walk does not follow links, so it deliberately does not resolve symlinks and has nothing to report. Treating one as fatal would make a stale symlink in a vendored tree a hard CI failure.

An explicitly named path is the exception to that last point, and a pre-existing one: --paths resolves a symlink seed once, and a seed that does not exist (a dangling link or a typo) is its own error, also exit 1.

書き込めない出力

The mirror image is the same rule, and it holds for every emission path: a run whose output could not be written exits 1. That covers a per-file document under an unwritable --output-dir, and a full disk on stdout: dump’s banners and trees, find‘s matches, strip-comments’ rewritten source, count’s tally, preproc’s JSON, and the single-document reports from vcs, vcs commit, and vcs trend alike, in every format. A per-file failure is named on stderr and counted in a summary line; output assembled after the walk reports the operating system’s error directly.

唯一の免除は、閉じられた下流のパイプです。bca dump | head は失敗ではなく日常的な操作であるため、BrokenPipe は握りつぶされ、実行はそれでも 0 で終了します。

メトリクス

bca metrics computes per-file metrics and emits them to stdout, to a single aggregate file (--output), or to a directory of per-file structured files (--output-dir). It is the command for feeding downstream tooling; for a human-readable summary see bca report, and for a pass/fail gate see bca check. The shared walker flags (paths, includes, ignore handling) are described in Commands.

Migrating? This command replaces the pre-restructure --metrics flag. The aggregated report previously selected with -O markdown now lives under bca report, and the CI/IDE offender formats (Checkstyle, SARIF, code-climate, clang-warning, msvc-warning) moved to bca check --report-format <fmt>. See the migration guide.

メトリクスの表示

指定したファイルまたはディレクトリのメトリクスを計算して表示するには、次を実行します:

bca metrics --paths /path/to/your/file/or/directory

• --paths（または -p）: 解析するファイルまたはディレクトリ。ディレクトリを指定すると、その中のすべての対応ファイルについてメトリクスが計算されます。パスは位置引数でも指定できます（bca metrics file.rs dir/）。

Explicitly named files must be parseable. When you name a file directly (positionally or via --paths / --paths-from) whose language the tool cannot recognize, bca prints a warning on stderr. If the run produced no output at all it exits 1, the same way a nonexistent explicit path fails; a mixed run that analyzed at least one file still exits 0 with the warning. Pass --language <lang> to force a parser when a file’s extension lies about its contents. Files reached only by walking a directory are skipped silently, since a tree full of READMEs and configs must not be noisy; pass -w to surface those skips too.

A file that is recognized but cannot be read is a stricter case and follows the unreadable-input rule: the run exits 1 even when other files analyzed fine, because a silently shorter metrics document reads as a complete one.

メトリクスのエクスポート

bca metrics supports five per-file output formats: CBOR, CSV, JSON, TOML, and YAML. JSON and TOML can also be pretty-printed.

トップレベルの 3 種類の出力は 3 つの別々のコマンドに対応しており、それぞれが自身のデータモデルとの一貫性を保ちます:

The CI/IDE offender formats (Checkstyle, SARIF, code-climate, clang-warning, msvc-warning) used to live on bca metrics -O <fmt>. They moved to bca check --report-format <fmt> because their input is a list of threshold violations, not the per-file metric tree the other formats carry. See Exporting offender records for the new invocation.

エクスポートコマンド

メトリクスを JSON ファイルとしてエクスポートするには:

bca metrics --paths /path/to/your/file/or/directory \
    -O json --output metrics.json

• -O, --format: output format. Defaults to text, a human-readable colored metric tree printed to stdout; pass --format text to request that default explicitly (for example to override a bca.toml that set a structured format). The structured per-file serializers are cbor, csv, json, toml, and yaml. --output-format is accepted as a deprecated alias and is slated for removal in the next major.
• -o, --output: a single file holding one aggregate document for the whole run, a top-level array of the per-file results (TOML wraps the array under a files key; CSV concatenates each file’s rows). If omitted, results are printed to stdout.
• --output-dir: 入力ファイルごとに 1 つのドキュメントを保持するディレクトリで、各ドキュメントは入力パスにフォーマットの拡張子を付けた名前になります。--output とは相互排他で、両方を渡すとエラーです。
• CBOR はバイナリのため、出力先（--output または --output-dir）が必須です。構造化された --format なしでいずれかの出力先を渡すとエラーになります（デフォルトの text フォーマットは stdout にストリームし、ファイルを書きません）。これにより、出力先の指定が黙って無視されることはありません（#661）。
• --metrics <name,…>: restrict computation to a subset of metrics, comma-separated or repeated (--metrics cyclomatic,cognitive --metrics loc). Names are the canonical ids bca list-metrics prints, the same vocabulary bca check --threshold and bca diff --metric use. Dotted (cyclomatic.modified) and bare loc sub-metric (sloc) spellings are accepted, as is a family name (loc). Each selects its whole family: --metrics sloc prints the full loc block. The Python bindings’ metrics= takes the same names. Derived metrics pull in their dependencies automatically. An unknown name errors with a “did you mean” hint. Omit it to compute every metric (#691).

CSV (spreadsheets and pandas)

bca metrics --paths /path/to/your/code \
    -O csv --output-dir csv-output

The CSV writer emits one row per FuncSpace (function, class, struct, unit, and so on) with the entire metric matrix as columns, a shape a spreadsheet or pandas loads directly. Header order is fixed; CSV_HEADER in src/output/csv.rs is the canonical list. Identity columns come first (path, space_name, space_kind, start_line, end_line), followed by every leaf metric under the same dotted JSON-style names (loc.lloc, halstead.volume, cyclomatic.modified.average), so a single column name addresses the metric in both CSV and JSON.

Empty cells (no value, not 0) signal “not applicable for this space”; for example, the OOP-only metrics (wmc.*, npm.*, npa.*) appear empty for procedural code. RFC 4180 quoting is delegated to the csv crate, so paths and names containing commas, quotes, or newlines round-trip cleanly.

Redirect stdout to collect the CSV output in one file:

bca metrics --paths /path/to/your/code -O csv \
    > metrics.csv

CSV はファイル単位のフォーマットです。--output-dir <dir> を指定すると、各入力ファイルは出力ディレクトリ配下に <input>.csv のミラーを生成します。--output <file> を指定すると、すべてのファイルの行が 1 つの集約 CSV に連結されます。

An aggregated HTML report covering the whole walk is available via bca report html. The previous per-file bca metrics -O html writer was removed because it degraded to an unopenable single-file table on real-world repos; CSV is the right shape for flat per-FuncSpace rows.

整形出力

bca metrics --paths /path/to/your/file/or/directory \
    --pretty -O json

インラインテストコードの除外

bca metrics --paths /path/to/your/code --exclude-tests

デフォルトでは、インラインのテスト項目を含む AST 内のすべてのノードがカウントされます。そのため、慣用的な #[cfg(test)] mod tests { ... } レイアウトに従う Rust ファイルでは、主要メトリクスに本番コードとテストコードが混在します。

Pass --exclude-tests to elide test-only subtrees before any metric is computed. The flag is recognised by every subcommand that walks a source tree (metrics, ops, report, check, dump, find, count, functions, and the rest of the walker group), and currently understands the following Rust attribute shapes:

• #[test] および #[rstest] / #[test_case] / #[wasm_bindgen_test]
• #[cfg(test)]、#[cfg(all(test, ...))]、#[cfg(any(test, ...))]
• #[tokio::test]、#[async_std::test]、#[test_log::test] など（::test で終わる任意のパス）
• mod アイテムに付く #![cfg(test)]（内部属性形式）

Languages without a Checker::should_skip_subtree override ignore the flag; only Rust applies the pruning today. The default remains off so existing metric numbers stay byte-identical for users who do not opt in.

To opt a whole project in without repeating the flag, set exclude_tests = true in the repo’s bca.toml manifest. Because --exclude-tests is presence-only (no =false form), the manifest key can only turn pruning on; a CLI --exclude-tests still wins, but the manifest cannot turn it back off.

Pruning lowers the node-counted metrics (cyclomatic, cognitive, Halstead, nom, nargs, and the rest), and loc.sloc drops with them. Unlike node-counted metrics, loc.sloc comes from source spans. The walker subtracts each pruned subtree’s rows from every enclosing span, up to the file. Rows a pruned item shares with retained code or comments are kept, so sloc never falls below the ploc and cloc that survive the prune.

集約レポート

For a human-readable quality report, use bca report markdown. That command aggregates metrics across all analyzed files and produces per-language hotspot tables.

利用可能なメトリクスの一覧

CLI を駆動するツールは、メトリクスのカタログをハードコードする代わりに実行時に検出できます。

bca list-metrics

はメトリクス名を 1 行に 1 つずつ出力します。各メトリクスの 1 行要約を得るには descriptions を渡します。

bca list-metrics descriptions

変更履歴（VCS）メトリクス

bca vcs ranks files by change-history risk: signals derived from git history rather than the source AST. It is the project’s one language-agnostic, non-AST metric family. The goal is to surface the files most likely to harbour bugs or vulnerabilities, using the signals the empirical defect- and vulnerability-prediction literature most consistently backs. This page is the command reference; Change-history metrics defines each signal and cites its source.

A single history walk runs once per invocation (never per file) and produces per-file signals over two configurable windows: a long window (default 12mo, about 365 days) and a recent window (default 90d).

クイックスタート

$ bca vcs --paths src --top 20
Change-history risk (long window 365d, recent 90d, formula v2)
 RANK      RISK  COMMITS rec/long  CHURN rec/long  AUTHORS long  FILE
    1       7.2             68/68     11634/11634             1  src/metrics/cyclomatic.rs
    2       6.9             68/68       7299/7299             1  src/metrics/npa.rs
    ...

With no --format, a human-readable ranked table is printed. Pass --format markdown|html for a rendered report page, or --format json|yaml|toml|cbor|csv for structured output. Unlike bca metrics / bca ops (whose --output-dir is a directory of per-file emissions), a change-history report is a single whole-repo document, so bca vcs --output <file> writes one file (CBOR, being binary, requires --output). The shared --paths / --include / --exclude / --no-ignore filters pick which tracked files to report.

bca vcs exits with an error when run outside a git working tree.

ファイルタイプのスコープ

By default bca vcs ranks only the files bca computes metrics for, the same set bca metrics would analyse. High-churn non-source files (CHANGELOG.md, Cargo.lock, generated config) carry no maintainability meaning yet maximise the churn / commit / author signals, so ranking them beside source code is noise. Scoping to files-with-metrics also keeps the standalone ranking aligned with the AST hotspot tables in bca report --vcs.

--file-types <SCOPE> でスコープを選択します。

bca vcs                          # ソースファイルのみをランク付け（デフォルト）
bca vcs --file-types all         # 追跡中のすべてのテキストファイルをランク付け
bca vcs --file-types rs,py       # Rust と Python のファイルのみをランク付け

The check is extension-only (no file content is read) and ANDs with the --paths / --include / --exclude / --no-ignore filters: a file must pass both to be ranked. Extension-less files (Makefile, Dockerfile, LICENSE) and unknown extensions are out of the metrics scope; a custom list is a literal extension filter, so it can include a non-metrics type like toml. An empty or all-blank custom list is a clear error rather than a scope that silently ranks nothing.

レンダリングされたレポートページ

bca vcs --top 50 --format html --output vcs.html
bca vcs --top 50 --format markdown --output vcs.md

--format html produces a self-contained, sortable page styled like bca report html (click any column header to re-sort); --format markdown produces the same ranked table as GitHub-Flavored Markdown. Both render every signal column, the same data the structured formats carry. The column set is defined once and shared by both renderers, so they cannot drift.

ランキングをスタンドアロンページではなく集約品質レポートに組み込むには、bca report --vcs を渡します。これは report markdown / report html に「Change-history risk」セクションを追加します。

シグナル

Author identities are canonicalised through the repository .mailmap and counted by lowercased email; Co-authored-by: trailers add participants. Bot identities (dependabot[bot], renovate[bot], github-actions[bot], and the like) are excluded by default. Both the built-in bot pattern and a custom --bot-pattern match case-insensitively against substrings of the author name and email. For example, --bot-pattern renovate matches Renovate Bot. Prefix the pattern with (?-i) for case-sensitive matching. Binary files and symlinks are skipped; an untracked file has no record at all (distinct from a tracked file with zero in-window activity).

変更エントロピーと共変更エントロピー

2 つのプロセスエントロピーシグナル（risk_score_version 2 で追加）は、ファイルの変更量だけでなく、「どのように」変更されるかを捉えます。

• Change entropy (Hassan, 2009, Predicting Faults Using the Complexity of Code Changes). For each commit, the Shannon entropy (in bits) of its churn distribution across the files it touched measures how scattered that change was: a one-file commit is 0; a commit spreading churn evenly across n files approaches log₂(n). Each file is then credited its churn share pᵢ·H of every commit it took part in (Hassan’s History Complexity Metric). Higher means the file is repeatedly caught up in diffuse, cross-cutting changes. Later work (arXiv 2504.18511, below) measured file-level change entropy at a Pearson correlation up to 0.54 with defect counts on eight Apache projects.
• Co-change graph entropy (arXiv 2504.18511, 2025). Files that change in the same commit are joined by a weighted edge (weight = number of shared commits). A file’s co-change entropy is the Shannon entropy of its edge-weight distribution: low when it always co-changes with the same partner, high when its changes ripple across many different files. Combined with change entropy it improved the area under the receiver operating characteristic curve (AUROC) in 82.5% of cases over the v1 signal set on eight Apache projects.

Both are reported per window. A 0.0 is computed, not missing: the file only ever changed alone (no co-change neighbours, or single-file commits with zero change entropy). Bulk-import commits touching more than 1000 files are excluded from the co-change graph, whose edge count grows O(width²), but still contribute their O(width) change entropy.

複合リスクスコア

デフォルトの加重（weighted） 式は、カテゴリ別の乗法的ボーナスを伴う、対数スケールの加重和です。

recency_churn  = ln(1 + churn_recent)
recency_count  = ln(1 + commits_recent)
long_count     = ln(1 + commits_long)
long_churn     = ln(1 + churn_long)
author_factor  = ln(1 + authors_long)
dilution       = (1 - ownership_top_share).clamp(0, 1)
fix_factor     = ln(1 + bug_fix_commits + 2 * security_fix_commits)
size_factor    = ln(1 + sloc)^2 / 100              // タイブレーカーではなく本来の係数
entropy_factor = 0.10 * change_entropy_recent + 0.05 * cochange_entropy_recent
new_file_bonus = 0.15 if age_days < recent_window_days else 0
dev_bonus      = 0.35 if authors_long >= 9 else 0.15 if authors_long >= 6 else 0

base = 0.30 * recency_churn
     + 0.25 * recency_count
     + 0.15 * long_count
     + 0.15 * author_factor * (1 + dilution)
     + 0.10 * fix_factor
     + 0.05 * long_churn
     + entropy_factor
     + size_factor

risk_score = base * (1 + dev_bonus + new_file_bonus)

各項の重みは文献に基づいています。直近のチャーンとコミット頻度が最大の重みを持ちます（Nagappan & Ball の相対チャーン、just-in-time 欠陥予測、Firefox の NumChanges PD 86）。作者ファクターは所有権の希薄化でスケールされます（Avelino の DoA / トラックファクター、Bird ら）。カテゴリ別の開発者数ボーナスは、9 人以上の開発者が触れたファイルは脆弱性を抱える可能性が約 16 倍だったという RHEL4 の知見をエンコードしています。セキュリティ修正には 2 倍の重みが付きます（Sentence-Level VFC 研究、PySecDB）。そして直近ウィンドウの変更エントロピーおよび共変更エントロピーの項は加算的に入ります（Hassan 2009、arXiv 2504.18511）。完全な導出は src/vcs/score.rs にあります。

The score is ordinal: only relative ranks have meaning. A single risk_score_version (now 2) versions both formulas: any change to the weighted sum or the --risk-formula percentile blend bumps it, and the recent entropy pair joins both.

--risk-formula percentile is an alternative: each signal is re-ranked to its percentile within the analyzed set, then averaged. The literature recommends relative triggers over hard thresholds for cross-project robustness.

フラグ

キャッシュ

On large, active repositories, walking the long-window history dominates runtime. Most consecutive CI runs add only a few commits. bca vcs therefore keeps a persistent cache of history walks, keyed by the resolved HEAD SHA and repository identity:

• 変更のないツリーでは前回の結果が再生され、履歴走査は行われません。
• HEAD が前進した場合、走査は新しいコミットのみを訪れ、それをキャッシュ済み履歴に継ぎ足します。
• フォースプッシュ（キャッシュされた head が新しい head の祖先でなくなった状態）では、完全走査にフォールバックします。

The cache is a pure optimization: a hit is bit-identical to a fresh walk, and the time windows are recomputed against the current moment on every run rather than frozen when the entry was written. An entry is ignored, and the history recomputed, whenever the schema, the score-formula version, the walk-affecting options, the repository’s effective .mailmap, or the git diff configuration that decides how gix diffs (diff.algorithm, core.bigFileThreshold, and a diff.<driver> section’s algorithm, binary, and whether it sets a textconv; a driver’s command never runs here and does not count), or the shallow boundary of a shallow clone (a git fetch --deepen or --unshallow leaves HEAD where it was but reaches commits the entry never saw) differ; in particular changing a window forces a fresh walk. One walk input is not covered: the diff attribute bindings (.gitattributes, .git/info/attributes, the global attributes file) that route a path to a diff driver or mark it -diff, so after changing those run once with --clear-cache. A bca release that adds a term retires every existing entry, so the first bca vcs after such an upgrade re-walks the whole long window once. Nothing deletes an entry that no longer matches, since a run with other options may still use it; --clear-cache removes the repository’s entries, retired ones included. Finalization-only knobs such as --risk-formula, --emit-author-details, --author-hash-key, and --include-deleted are applied on replay, so they reuse the same cached walk; a cached walk even re-finalizes under a different author-hash key without re-walking.

By default the cache lives under $XDG_CACHE_HOME/big-code-analysis/vcs (%LOCALAPPDATA% on Windows, ~/.cache otherwise). Author identities are stored only as their SHA-256 digests, never plaintext, so the cache holds no raw author emails. This is pseudonymization, not anonymization: the digests are recoverable against a candidate email set (see --emit-author-details). The same cache transparently accelerates bca metrics --vcs and bca report --vcs.

# 最初の実行がキャッシュを準備し、2 回目はそれを再生します。
bca vcs --paths .
bca vcs --paths .                 # 前回の作業を再利用

bca vcs --no-cache --paths .      # この実行ではキャッシュを無視
bca vcs --clear-cache --paths .   # ゼロから再構築
bca vcs --cache-dir /tmp/bca-cache --paths .

REST（POST /v1/vcs）と Python（vcs.rank）の各インターフェースは、省略可能な no_cache / cache_dir パラメータを通じて同じ挙動を提供します。

The cache is specific to the file ranking. The trend and commit subcommands, and the /v1/vcs/trend and /v1/vcs/jit endpoints, do not use it, so the cache flags do not apply there: passing --no-cache / --cache-dir alongside a subcommand is a usage error, and the trend endpoint rejects a no_cache / cache_dir field rather than silently ignoring it (issue #961).

bca metrics での利用

bca metrics --vcs を渡すと、各ファイルの metrics に vcs ブロック（およびファイルの cyclomatic 合計から計算される hotspot_score）が付加されます：

$ bca metrics --vcs --paths src/parser.rs --format json
{ "name": "src/parser.rs",
  "metrics": { "cyclomatic": { ... },
    "vcs": { "commits_long": 15, "churn_recent": 211,
             "risk_score": 3.7, "hotspot_score": 7596.0, ... } } }

bca metrics --vcs はデフォルトのウィンドウと重み付き計算式を使用します。ウィンドウや計算式を調整したい場合は bca vcs を使用してください。

関数単位の帰属

bca metrics --vcs-per-function (which implies --vcs) additionally attaches a vcs block to every nested function, method, and class space. It blames each file once with git blame and buckets the surviving lines into the AST function spans, so you can rank the risky function inside a risky file:

$ bca metrics --vcs-per-function --paths src/parser.rs --format json
{ "name": "src/parser.rs",
  "metrics": { "vcs": { "risk_score": 3.7, ... } },   // ファイルレベルのブロック
  "spaces": [
    { "name": "parse", "kind": "function",
      "metrics": { "vcs": { "commits_long": 4, "churn_recent": 12,
                            "risk_score": 2.1, "hotspot_score": 144.0 } } } ] }

関数単位のブロックは現時点の blame のスナップショットであり、ファイルレベルのブロックと直接比較「できません」。その churn は、最終変更がウィンドウ内に収まる現存行を数えるものであり（過去の追加+削除のチャーンではありません）、所有権は変更したコミットごとに加算されます。ウィンドウ内で誰も変更していない関数のカウントはゼロと報告されます。最終変更が長期ウィンドウより前の行は、関数のサイズには寄与しますが、ウィンドウ付きのどのカウントにも寄与しません。

Each nested space’s hotspot_score multiplies its own cyclomatic (cyclomatic.value) by its churn_recent, not its subtree cyclomatic.sum, so a nested function’s complexity is not counted again at every enclosing level; the file-level block keeps the subtree sum. When cyclomatic is computed, the Python bindings’ vcs_per_function=True reports the same scores.

Limitations. Blame follows file renames (so edits under a former path still attribute), but attributes a line moved between functions to its current position only. A function split into two has no record of its pre-split identity, and a deleted-then-recreated function attributes to the recreating commits. If a file cannot be blamed (untracked, or the rare gix-blame failure on pathologically repetitive content), its per-function blocks are omitted while the file-level block and the AST metrics still emit.

ジャストインタイム（コミットレベル）スコアリング

Where everything above ranks files at a ref, bca vcs commit <commit> scores a single commit for defect-induction risk, the unit a CI gate reviews at check-in. (The subcommand was renamed from bca vcs jit in 2.0; the old jit spelling keeps working as a hidden alias for one release cycle. “Just-in-time (JIT)” stays the literature term, below.) It is a static, rule-based scorer (no trained model, so nothing drifts as the project ages), with the feature groups and signs taken from the just-in-time defect-prediction literature: Kamei et al., A Large-Scale Empirical Study of Just-in-Time Quality Assurance, IEEE TSE 2013, with the open replications Commit Guru (FSE 2015) and McIntosh & Kamei, Are Fix-Inducing Changes a Moving Target? (IEEE TSE 2018).

$ bca vcs commit HEAD --pretty
{
  "jit_schema_version": 3,
  "jit_score_version": 1,
  "source": "commit",
  "risk_score": 4.40,
  "commit": { "id": "5176d3e…", "parent_count": 1, "is_merge": false,
              "purpose": { "is_fix": true, "is_security_fix": false,
                           "is_revert": false } },
  "features": {
    "size":       { "lines_added": 942, "lines_deleted": 60,
                    "files_touched": 19, "hunks": 78 },
    "diffusion":  { "subsystems": 5, "directories": 8, "entropy": 3.48 },
    "history":    { "prior_changes": 275, "prior_distinct_authors": 1,
                    "prior_bug_fix_commits": 237,
                    "prior_security_fix_commits": 21,
                    "file_risk_max": 10.97, "file_risk_mean": 3.87,
                    "new_files": 2 },
    "experience": { "author_prior_commits": 962,
                    "author_recent_commits": 962 }
  },
  "contributions": { "size": 2.74, "diffusion": 0.97, "history": 1.57,
                     "purpose": 0.15, "experience": -1.03 }
}

5 つの特徴量グループと、それぞれがスコアをどう動かすか：

contributions ブロックは、順序尺度である risk_score への各グループの符号付き寄与を報告するため、コミットが「なぜ」その順位になったのかを利用側が確認できます。ファイルレベルの risk_score と同様、このスコアは順序尺度です。スコアでコミットをランク付けしたり、リポジトリ自身の分布とコミットを比較したりできますが、その大きさを確率として読み取らないでください。計算式が変更されると jit_score_version が上がります（ファイルレベルの risk_score_version とは別です）。

The commit is scored against its first parent. A merge commit is flagged (is_merge, parent_count ≥ 2) and scored against that first parent. A root commit and any new files carry zero priors by construction; the score then leans on size and author experience, as the literature prescribes for changes with no file history.

ウィンドウ / --ref / ボット / マージ / リネームの各フラグは親コマンドの bca vcs と共有されます。commit 専用のフラグは、位置引数の <commit>（デフォルト HEAD）、--format json|yaml|toml|cbor（デフォルト json）、--output、--pretty、および次のとおりです：

# CI ゲート：コミットのスコアがしきい値以上のとき exit 2 で終了する。
bca vcs commit HEAD --fail-above 6.0

--fail-above は終了コード 2 を使用します（bca check と同じ「メトリクスゲート」の慣例です。終了コード 1 はツールエラー用に予約されたままです）。スコアは順序尺度なので、しきい値は絶対値として扱うのではなく、リポジトリ自身のコミットスコア分布に対して調整してください。

任意の diff のスコアリング（--diff）

bca vcs commit --diff <file> scores a git diff instead of a commit (use --diff - to read the diff from stdin). This suits a pre-commit hook or a code-review bot, where the change exists only as a diff and has not been committed yet.

git diff --cached | bca vcs commit --diff - --pretty

The input must be a git-style unified diff carrying diff --git file headers, as produced by git diff or git format-patch. Plain diff -u / diff -ru output (which has ---/+++ header lines but no diff --git header) parses to zero files, and combined / merge diffs (git diff --cc, with @@@ hunk headers) are rejected as a malformed diff; pipe a regular two-way git diff instead.

A bare diff carries no author, parent, or file history, so only the size and diffusion groups are computable. The output is therefore a deliberately partial report, a distinct shape from a commit report:

$ git diff | bca vcs commit --diff - --pretty
{
  "jit_schema_version": 3,
  "jit_score_version": 1,
  "source": "diff",
  "partial_risk_score": 1.83,
  "size":      { "lines_added": 42, "lines_deleted": 8,
                 "files_touched": 3, "hunks": 6 },
  "diffusion": { "subsystems": 2, "directories": 3, "entropy": 1.46 },
  "contributions": { "size": 1.18, "diffusion": 0.65 }
}

The source field is a permanent "diff" marker, and the history / experience / purpose groups are absent from the report entirely, not present as zero. Zero is a real value (a commit genuinely with no prior history scores those groups at zero); an absent group means “unavailable”, so a consumer can never mistake an unscored group for “low risk”. For the same reason the score field is named partial_risk_score, not risk_score.

A diff-only score is not comparable to a commit score. The partial score sums only size + diffusion; the full commit score for the same change also folds in history, experience, and purpose, and because experience is negatively signed the two are not even ordered (an experienced author can push the full score below the partial one). Rank diffs against other diffs, never against commit scores. --diff and the positional <commit> are mutually exclusive; --fail-above works in both modes (calibrate the diff-mode threshold against your own diff-score distribution).

パーサーは git のデフォルトである C 形式のパス引用（core.quotePath=true）を理解するため、非 ASCII 文字や空白を含む名前のファイル（git は "a/na\303\257ve.txt" のように出力します）に触れる diff は、diffusion の特徴量では引用付きの生文字列ではなく、デコードされたパスの下にグループ化されます。

REST と Python のパリティ

JIT スコアは CLI 以外からも利用できます：

• REST: POST /v1/vcs/jit に { "id", "repo_path", "commit" } を渡すとコミットの JitReport JSON が返り、{ "id", "diff" } を渡すと部分的な diff レポートが返ります。REST API の利用を参照してください。
• Python: vcs.commit(repo_path, commit=...) はコミットレポートを dict として返し、vcs.score_diff(diff) は部分的な diff レポートを返します。変更履歴（VCS）メトリクスを参照してください。

ML ベースの JIT モデルとサーバーサイドフック統合は、引き続きスコープ外です。

履歴トレンド（時系列）

A single bca vcs run answers “what is risky now”. bca vcs trend answers “is it getting better or worse”, the question a technical-debt programme acts on, by sampling the metrics at several points in time and emitting a per-file time series.

$ bca vcs --top 20 trend --points 12 --span 24mo --pretty
{
  "trend_schema_version": 1,
  "vcs_schema_version": 2,
  "risk_score_version": 2,
  "long_window_days": 365,
  "recent_window_days": 90,
  "truncated_shallow_clone": false,
  "as_of_points": [ 1700000000, 1705259520, ... ],
  "files": {
    "src/parser.rs": [
      null,                       // 最古の時点では存在しなかった
      { "as_of": 1705259520, "vcs": { "risk_score": 4.1, ... } },
      { "as_of": 1710519040, "vcs": { "risk_score": 6.8, ... } }
    ]
  },
  "deltas": {
    "improved":  [ { "path": "src/old.rs",    "delta": -3.2, ... } ],
    "regressed": [ { "path": "src/parser.rs", "delta":  2.7, ... } ]
  }
}

--points N 個の等間隔サンプル（両端点を含む）が --span DURATION をカバーし、--as-of（指定がなければ現在時刻）で終わります。as_of_points はサンプルのタイムスタンプを古い順に列挙し、各ファイルの配列はそれと 1:1 で対応します。null 要素は、その時点でファイルがまだ存在しなかったことを示します。deltas は、各ファイルの最初と最後に存在した時点の間で risk_score が最も下がったファイル（improved）と最も上がったファイル（regressed）をランク付けします。--top-deltas で各リストを切り詰められます。

Each point re-anchors at the mainline tip that existed at or before that moment; it does not just re-window today’s HEAD tree. That is what makes a file born later show as null at older points rather than leaking its present-day metrics backwards. Files kept in the series are the --top highest-risk by their most-recent sample.

親コマンド bca vcs から再利用されるフラグ：ウィンドウ（--long-window / --recent-window）、--ref、--file-types、ボット / マージ / リネームのトグル、--as-of（最新のアンカー）、および --top。-O は json（デフォルト）、yaml、cbor を受け付けます。存在しない時点は null としてシリアライズされ、TOML はこれを表現できないため、TOML は除外されています。時点数は、深い履歴でも時点ごとの履歴走査が扱いきれる範囲に収まるよう、2–120 に制限されています。

リネームに関する注意。 リネームは各サンプルの走査「内」では追跡されますが、2 つのサンプルの「間」でリネームされたファイルは、1 本の連続した線ではなく、2 つの別々のパス系列（旧名、次に新名）として現れます。サンプル間のリネームの縫合は後回しのフォローアップです。

バスファクター（ディレクトリ・リポジトリレベル）

Where the per-file ownership_top_share measures concentration within a file, the bus factor (also called the truck factor) measures it across a set of files: the minimum number of developers whose departure would leave more than half of a directory’s files without a knowledgeable maintainer. bca vcs emits it as a top-level vcs_aggregate object alongside the ranked files:

{
  "vcs_aggregate": {
    "bus_factor": {
      "bus_factor_schema_version": 2,
      "coverage_threshold": 0.5,
      "doa_threshold": 0.75,
      "repo": { "bus_factor": 3, "files": 412, "authors": 11 },
      "by_directory": [
        { "directory": "src", "bus_factor": 2, "files": 180, "authors": 7 },
        { "directory": "src/vcs", "bus_factor": 1, "files": 24, "authors": 3 }
      ]
    }
  }
}

Each developer’s authorship of each file is scored with the Avelino Degree-of-Authorship heuristic (Avelino, Passos, Hora & Valente, A Novel Approach for Estimating Truck Factors, ICPC 2016):

DoA(d, f) = 3.293 + 1.098·FA + 0.164·DL − 0.321·ln(1 + AC)

ここで FA は最初の作者性（d が f を作成したなら 1）、DL は d の f への提供（変更）回数、AC は「他の」開発者による変更回数です。ファイルの最大値で正規化した DoA が 0.75（論文のしきい値）を超えるとき、その開発者は f の作者とみなされます。トラックファクターは貪欲な除去で求めます。すなわち、まだカバーされているファイルを最も多く作者として持つ開発者を除去し、ファイルの --bus-factor-threshold（デフォルト 0.5、Avelino に準拠）超が孤児になるまで繰り返し、除去した人数を報告します。by_directory は各トップレベルディレクトリとその直下のサブディレクトリをカバーし、それぞれ再帰的に配下のすべてのファイルに対して計算されます。

構造上の注意点：

• With the default threshold, a repository whose files all share one sole author has a bus factor of 1. Single-author files owned by different developers can produce a higher bus factor. This is the heuristic working as intended, not a bug; treat the number as a planning signal, not a guarantee.
• ボットのアイデンティティは（ファイルごとのシグナルと同様に）フィルタリングされ、ウィンドウ内に活動のないファイルは作者性を持たず、分母から除外されます。
• 「最初の作者性」は「長期ウィンドウ内で観測された」最古のコミットを意味し、必ずしもファイルの真の作成を意味しません。

The aggregate reflects the whole repository within the file-type scope: one history walk covers every in-scope file, by default the files-with-metrics set (see File-type scope), so --file-types all widens the bus factor to every tracked file. --paths / --include / --exclude scope only the ranked per-file list, not the bus factor. To focus on a subsystem, read its entry in by_directory rather than filtering the walk.

--emit-author-details adds a key_author_ids list to each group: the SHA-256-hashed identities of the removed key developers, in removal order (plaintext identities never leave the process). The aggregate is computed only for the dedicated bca vcs / bca report --vcs reports and the REST / Python endpoints; the per-file bca metrics --vcs injection path does not pay for it.

作者詳細のプライバシー

The key_author_ids digests are a stable pseudonym, not anonymization. Hashing keeps plaintext emails out of the report and the cache and deters casual disclosure, but the hash is not cryptographically irreversible. The pre-image is an email, which is low-entropy and enumerable, and commit histories are public, so anyone with a candidate set of emails can recover which digest belongs to whom by hashing each candidate or with a precomputed email→hash table. This is the same weakness that broke Gravatar’s email hashing.

公開された key_author_ids（およびファイルごとの author_ids）は、平文のメールアドレスの出力を避ける仮名化として扱い、執念深い攻撃者によって作者が再識別されないことの保証としては扱わないでください。その保証が必要なら、ダイジェストを公開しないでください。

強化モード：--author-hash-key

For stronger resistance, pass a secret key with --author-hash-key <KEY> (requires --emit-author-details). The emitted digests then become an HMAC, HMAC-SHA256(key, SHA-256(email)), instead of a bare hash: an attacker without the key can no longer hash a candidate email to recognise its digest, nor use a precomputed email→hash table, because both attacks need the secret key. Pick a high-entropy key and keep it secret; anyone who learns it can re-run the enumeration.

鍵は安定しています。同じ鍵なら、すべてのレポートにわたって、また永続キャッシュのリプレイをまたいでも同じダイジェストが得られるため、レポート間の相関付けとキャッシュは引き続き機能します。異なる鍵は無関係なダイジェストを生成するため、履歴を共有する 2 つのチームは、鍵を共有しない限り作者を相互にひも付けることはできません。

Prefer the BCA_AUTHOR_HASH_KEY environment variable over the flag: a key on the command line is visible to other local users via the process list (ps) and is saved in shell history. The flag takes precedence when both are set:

export BCA_AUTHOR_HASH_KEY="$(cat ~/.config/bca/author-key)"
bca vcs --emit-author-details

鍵がカバーしないもの：ディスク上の履歴キャッシュ（issue #334）は意図的に「鍵なしの」内側の SHA-256 ダイジェストを保存します。鍵は確定処理の段階で適用されるため、キャッシュ済みの走査は再走査なしに任意の鍵で再確定できるからです。キャッシュはローカル限定で公開されることはありませんが、脅威モデルにローカルのキャッシュディレクトリを読む攻撃者が含まれる場合は、キャッシュを無効化（--no-cache）するかクリア（--clear-cache）してください。同じ鍵オプションは REST エンドポイント（author_hash_key）と Python（vcs.Options(author_hash_key=…)）でも利用できます。

このリポジトリでのドッグフーディング

This project runs bca vcs on its own source. make vcs prints the ranked table; path selection and the .bcaignore deny-set come from the repo-root bca.toml manifest, the same config make self-scan and make report use, and BCA_VCS_TOP overrides the row cap. The manifest’s [vcs] file_types key sets the default scope (the --file-types CLI flag replaces it when given). On every push to main, the Pages CI job includes the ranking in the published quality report (bca report html --vcs / report markdown --vcs), so reports/index.html shows the change-history risk section beside the AST hotspots. The same job publishes the full top-100 ranking as reports/vcs-report.json for tooling.

REST と Python

• REST: JSON ボディ { "id": "...", "repo_path": "/path/to/repo", ... } を伴う POST /v1/vcs はランク付けされたレポートを返し、POST /v1/vcs/trend（同じフィールドに加えて points / span / top_deltas）は履歴の時系列を返します。REST API の利用を参照してください。
• Python: big_code_analysis.vcs.rank(repo_path, …) はランク付けされたレポートを dict として返し、vcs.trend(repo_path, points=…, span=…, …) は時系列を返します。また analyze(path, vcs=True) は単一ファイルのメトリクスに vcs ブロックを付加します。

POST /v1/vcs と vcs.rank()（vcs.Options 経由）のどちらも、ランク付け対象のファイルをスコープする省略可能な file_types（"metrics" / "all" / "rs,py"）を受け付けます。これは CLI の --file-types に対応します。

どちらも結果に vcs_aggregate のバスファクターを含み、カバレッジの割合を調整する bus_factor_threshold（範囲は (0, 1)）を受け付けます。

レポート

bca report [--format <FORMAT>] produces an aggregated quality-metrics report across every file walked, for pasting into pull requests, wikis, or issue trackers. For per-file data meant for tooling, use bca metrics; for a pass/fail gate, use bca check.

Two formats are available: markdown (plain text, suited to PR comments) and html (a self-contained dashboard with sortable tables, suited to a build artifact). Pick one with --format / -O (bca report --format html); the default is markdown. The bare positional form (bca report markdown) still works as a deprecated alias and is slated for removal in the next major; prefer --format.

CI integration. For runnable GitHub Actions and GitLab CI recipes that post the Markdown report as a PR/MR comment, see the CI integration recipe.

移行の際は。 このコマンドは、再構成前の --metrics -O markdown 呼び出しを置き換えるものです。移行ガイドを参照してください。

クイックスタート

標準出力に表示：

bca report --paths /path/to/project markdown

ファイルに書き出し：

bca report --paths /path/to/project markdown --output report.md

注： --output はディレクトリではなく「ファイル」パスでなければなりません。

フラグ

抑制マーカー

By default, bca report markdown|html honours in-source suppression markers: the same // bca: suppress, // bca: suppress-file, and Lizard #lizard forgives comments that bca check and the SARIF emitter respect (see Suppression). A function is omitted from a metric’s hotspot table when that metric is suppressed for it, so the published report agrees with the threshold gate instead of re-surfacing every silenced offender.

Suppression is per-metric: a // bca: suppress(cyclomatic) marker drops the function from the Cyclomatic table only; it still appears in the Cognitive, Halstead, and other tables. A bare // bca: suppress (or // bca: suppress-file) covers every metric.

マーカーに関係なくすべての違反を列挙する生の監査ビューには --no-suppress を渡します。この設定は bca.toml マニフェストに固定することもできます：

[report]
no_suppress = true

The CLI flag wins in either direction: a bare --no-suppress forces the audit view on, and --no-suppress=false restores the marker-honoring default even when the manifest enabled the audit view. The manifest only fills the value when the CLI left it unset.

使用例

セクションごとに最悪のホットスポット 5 件のみを表示：

bca report -p src/ markdown --top 5

表示されるパスからワークスペースルートを取り除く：

bca report -p /home/user/project markdown \
    --strip-prefix /home/user/project/

A typical day-to-day invocation:

bca report \
    --paths "$PWD" \
    markdown \
    --top 20 \
    --strip-prefix "$PWD/"

レポートの構成

生成されたレポートには以下のセクションが含まれます（データが存在しないセクションは省略されます）。すべてのホットスポットテーブルには SLOC と並んで Tokens 列（Lizard 方式の葉トークン数、コメントは除外）が含まれ、行ごとに補完的な 2 つのサイズ指標を確認できます。

1. Project summary: files analyzed, languages, total SLOC / PLOC / comment counts, function and class counts, comment ratio.
2. Per-language overview table: one row per language with file count, SLOC, function count, the SLOC-weighted average Maintainability Index (MI), average Cyclomatic Complexity (CC), and average Cognitive Complexity. The MI average is size-weighted and uses the unclamped Visual Studio value, so a language whose files are mostly unmaintainable reads negative instead of saturating at the 0 floor of the per-file MI column.
3. Per-language hotspot sections (repeated for each language). Every hotspot title follows one template, <Concept> hotspots (top N by <column>), where the truncation clause states the actual --top state (top 20 by CC, or all, by CC for --top 0):
   • Summary: file count, SLOC, PLOC, comment ratio, and Average MI (SLOC-weighted) with a GOOD / MODERATE / LOW rating. The headline is the SLOC-weighted mean of the unclamped Visual Studio MI: large files dominate, and a file whose displayed MI clamps to 0 still contributes its true (often negative) maintainability rather than a misleading 0. A file with no code to measure (an #include-only header, an empty module) is left out of every MI average and of the MI hotspot table, because its MI of 0.0 is a placeholder, not a score; it still counts toward Files and SLOC. A language with no file to measure reads n/a.
   • Actionable Summary: counts of functions exceeding common thresholds (by default CC > 10, cognitive > 15, SLOC > 100, args > 3, Halstead bugs > 1; a manifest [thresholds] table overrides each cutoff). The Actionable Summary appears immediately after the Summary and before the hotspot tables. It counts raw measurements without applying suppression; the section is captioned to say so, naming how many suppressed functions are folded in. When suppression empties a hotspot table whose metric this summary still counts, the table is replaced by a one-line “table omitted: all N matching functions suppressed” note so a summary bullet never points at a missing table.
   • Maintainability Index hotspots (lowest N by MI): files sorted ascending by MI.
   • Cyclomatic complexity hotspots (top N by CC): functions sorted descending by CC, with summary statistics (average, max, counts above 10 and 20).
   • Cognitive complexity hotspots (top N by Cognitive): functions sorted descending by cognitive complexity.
   • Halstead effort hotspots (top N by Effort): functions sorted descending by Halstead effort, including volume and estimated bugs. Effort and Volume render as rounded integers with thousands separators (8,845); full precision lives in JSON/CSV.
   • Function size hotspots (top N by SLOC): functions sorted descending by source lines of code.
   • Many parameters hotspots (top N by Args): functions with more than three parameters, sorted descending.
   • Type hotspots (top N by WMC): types sorted descending by Weighted Methods per Class, with NOM, NPA, and NPM. “Type” covers all six kinds the report counts: class, struct, trait, impl, interface, namespace (the legend’s WMC entry lists them).
   • Exit points hotspots (top N by Exits): functions with more than two exit points, sorted descending. A single return is the baseline, not a hotspot, so the table admits only nexits > 2; when nothing clears the floor the section is omitted.
   • ABC magnitude hotspots (top N by ABC): functions sorted descending by ABC metric magnitude.

フォーマット間の一貫性

The Markdown and HTML renderers share one data model. They use the same summaries, hotspot membership, and captions, so both formats report identical numbers.

Both formats carry a Legend that defines every metric column abbreviation (CC, MI, ABC, WMC, and so on) plus the global-header stats (PLOC, Comments, Comment ratio). It is a ## Legend section in Markdown (its own outline entry, not nested under the last language) and an expanded (<details open>) block in HTML, so it survives print, mobile, and screen readers as well as a hover tooltip. Each entry links to its chapter in the Supported Metrics reference, so a one-line definition can hand the reader the full explanation. The definitions come from the same shared column specs the tooltips use, so the two formats cannot drift.

Both formats close with a provenance footer stating the bca version — followed, for a bca built from a source checkout, by the first twelve digits of its build-inputs digest in parentheses, the same digest bca --version prints in full — the generation date, the seed paths scanned, the per-table --top value, and whether suppression markers were honored, so a detached artifact (a PR comment, a Pages deployment, a file on a ticket) records what it was generated from. The date honors SOURCE_DATE_EPOCH for reproducible builds. The HTML report additionally carries a <meta name="viewport"> tag and wraps every table in a horizontal-scroll container so wide tables stay reachable on mobile and narrow windows, and its table of contents nests each language’s hotspot subsections under a collapsible entry.

Source suppression markers apply per metric to both report hotspot tables and bca check’s offender formats (code-climate, sarif, checkstyle, clang-warning, msvc-warning). Check baselines additionally filter check violations; they do not filter report hotspot tables. The Code Climate, SARIF, and Checkstyle documents are themselves three renderings of one offender set, so they agree by construction; the reports honour the same per-metric suppression decisions.

The single deliberate exception is the Actionable Summary, a whole-codebase health indicator that counts raw measurements regardless of suppression: silencing a function in one metric’s hotspot table does not erase it from that aggregate concern count. Every other figure, including each hotspot table’s caption, reflects the suppression-filtered set. To stop a reader mistaking the two populations for a double-count, each is captioned: the cyclomatic note adds “(excluding suppressed functions)”, and the Actionable Summary names the raw, suppression-ignoring basis of its counts.

HTML フォーマット

bca report html emits a single self-contained HTML page covering the same sections as the Markdown report. It is built to be served as a static artifact: inline CSS, inline vanilla JavaScript for click-to-sort on every hotspot table, and no external dependencies (no CDN, no fonts, no template engine). The page renders identically offline.

Write it to a file and open it in any browser:

bca report --paths /path/to/project \
    html --top 10 --output report.html

任意の列ヘッダーをクリックするとそのテーブルが昇順でソートされ、もう一度クリックすると降順に切り替わります。各テーブルは独立してソートされます。空のセル（メトリクスが測定されなかった箇所）は正の無限大であるかのようにソートされるため、「データなし」の行がホットスポットの見える上位に紛れ込むことはありません。

Hover (or keyboard-focus, where the browser supports it) any metric column header (SLOC, MI, CC, ABC, WMC, NPA, NPM, Exits, and the rest) for a one-sentence plain-English explanation of the metric. The tooltip is delivered through the native HTML title attribute, so it works offline with no JavaScript.

Because title tooltips are hover-only (invisible in print, on mobile, and to screen readers), the page also ends with a visible, collapsible Legend (<details>) listing every metric column’s one-line definition. Both the tooltips and the legend draw from the same column specs, so a definition cannot say one thing on hover and another in the legend.

Every interpolated string (function name, file path, language label) is HTML-escaped on the way out, so a crafted source path or symbol name cannot inject markup or break out of an attribute value.

Each per-language <section> carries a stable lang-<name> class (lang-rust, lang-python) styled with a low-alpha background tint and matching left border so a multi-language report’s section boundaries are obvious at a glance. Languages without an explicit palette entry fall back to a neutral lang-other tint, and a prefers-color-scheme: dark adapter raises the alpha so contrast holds in both themes.

メトリクス値のゼロ

Zero can be a valid measurement or a placeholder for unavailable data, depending on the metric. Each hotspot table applies its own eligibility rule; a measured MI of zero remains eligible. A table with no eligible entries is omitted.

チェック

bca check compares metrics against thresholds at each metric’s own scope (function, file, or container) and exits non-zero when any value exceeds its limit. It is the CI integration point: wire it into a build step and a regression in code complexity fails the pipeline before the change lands.

This page documents the command. The first half covers what most runs need: declaring thresholds, exit codes, offender output, baselines, and CI wiring. The second half covers the exemption mechanisms, per-language limits, the soft tier, and the edge cases in how they combine. For runnable pipeline examples see the CI integration recipe, which covers the --report-format matrix, GitHub Actions and .gitlab-ci.yml examples, the baseline ratchet, and the GitLab Code Quality path.

しきい値の宣言

Pass --threshold <metric>=<limit> once per metric (repeatable). Metric names match bca list-metrics; sub-metrics use a dotted form. A value violates its limit only when it exceeds it, so 0 is a valid limit that permits exactly zero.

bca check --paths src/ \
    --threshold cyclomatic=15 \
    --threshold cognitive=20 \
    --threshold loc.lloc=200

Or keep thresholds in the bca.toml manifest, so CI thresholds are versioned alongside the code. A manifest at the repo root is discovered automatically: a bare bca check reads it with no --config flag.

# bca.toml
paths = ["src"]

[thresholds]
cyclomatic = 15
cognitive = 20
"loc.lloc" = 200
"halstead.volume" = 1000

bca check

1 回の実行でマニフェストの上に別のしきい値ファイルをマージするには、--config で明示的に渡します。CLI フラグと --config の値は、同じメトリクス名についてマニフェストを上書きするため、プロジェクト全体のデフォルトを保ちながら、特定の実行でひとつのメトリクスだけを厳しくできます。

bca check --paths src/ --config bca.toml

bca init は出発点となるテーブルをスキャフォールドします。それらの数値の出どころ、ゲート対象の言語に合わせて上書きすべき項目、エージェントフィードバック・レガシートリアージ・セーフティクリティカルな作業向けに別のセットを選ぶ方法については、しきい値の選択を参照してください。

使用できるメトリクス名

トップレベルのスカラーメトリクスは list-metrics の名前をそのまま使います：cognitive、cyclomatic、nargs、nexits、nom、tokens、abc、wmc、npm、npa。複数のサブフィールドを持つメトリクススイートはドット区切り形式を使います。

不明なしきい値名はツールエラー（終了コード 1）となり、黙って無視されることはありません。

しきい値のスコープ

A threshold is checked only against the space kind its metric measures, so a metric’s whole-file or whole-impl aggregate is never mistaken for a per-function limit. Each metric has a fixed scope; there is nothing to configure.

The Function-scoped metrics include the subtree sums (nargs, nexits, tokens, halstead.*). These still roll a function’s own nested closures into its figure, but they are not summed across an entire file or impl. The Container-scoped metrics describe a type’s method set (methods per class, weighted methods, public members), so they gate the container rather than every leaf function. A file whose functions are individually fine therefore never trips an additive limit on the file-wide total, which is the false positive bca: suppress-file markers used to mask.

The bare bca diff --metric spelling of a loc sub-metric is accepted as an alias for its dotted form (sloc for loc.sloc, and so on for ploc/lloc/cloc/blank/dloc), so a name copied from a diff run gates correctly. A bare family head with no single threshold scalar (halstead, mi) is ambiguous and rejected with a “did you mean” hint listing the concrete sub-metrics; pick one, such as halstead.volume.

The two spellings name one metric, so they override each other wherever limits merge: a per-language [thresholds.lang.c] ploc = 100 replaces the global "loc.ploc", and --threshold ploc=100 replaces either. Within a single table, writing both is an error rather than a silent winner. Set the metric once, under whichever spelling you prefer.

終了コード

1 は予約されており、CI がリグレッション（2）とツールの設定ミス（1）を区別できるようになっています。

A gate that could not read all of its input has no verdict to report, so three input problems exit 1 rather than 0: nothing matched --paths / --include / --exclude, any input file that failed to read, and any directory the walk could not list. The last two are the workspace-wide unreadable-input rule. check is not special here; it is where the rule matters most, because a gate reporting clean on a tree it could not read looks the same as a gate that passed. All three checks run before the gate is evaluated. --no-fail does not suppress them, since it suppresses threshold failures rather than broken input, so none of them lets --write-baseline record a partial run.

段階的終了コード（--exit-codes=tiered）

--exit-codes=tiered (or [check] exit_codes = "tiered" in bca.toml) splits the single violation code 2 by severity so CI can branch on it without parsing the [new] / [regr …] row tags a baseline run prints:

The tiered codes are opt-in; the default contract above stays 0/1/2. Every fail-state remains non-zero, so exit != 0 → fail wrappers keep working. Only tooling that tests $? -eq 2 explicitly needs to widen to 2-5. --no-fail still forces exit 0. Code 5 is emitted only at the soft tier; at the hard tier every violation is a hard breach by definition, so the 2/3/4 split applies instead.

--exit-codes <default|tiered> takes a value, and the CLI value overrides the [check] exit_codes manifest key in either direction. An invalid exit_codes value is a tool error (1). --print-effective-config reports the resolved exit_codes style. The deprecated --strict-exit-codes flag is a one-cycle alias for --exit-codes tiered (warns; removed at the next major).

違反の出力

違反した (function, metric) の各ペアは、次の安定したフォーマットで 1 行ずつ stdout に出力されます。

<path>:<start_line>-<end_line>: <function_name>: <metric> = <value> (limit <limit>)

例：

src/parser.rs:42-117: parse_expression: cyclomatic = 22 (limit 15)
src/parser.rs:42-117: parse_expression: cognitive = 31 (limit 20)

行はパス、開始行、メトリクス名の順でソートされるため、同じツリーに対する実行間で出力は決定的です。

どちらのストリームか

違反行はこのコマンドの成果物なので stdout に出力されます。bca check | wc -l、| head、| rg -c、2>/dev/null のいずれでも違反行に届きます。

実行が「自分自身について」語る内容はすべて stderr に出力されます：

• ファイルごとの --- summary --- フッター、
• --- next steps --- の修復ブロック、
• GitHub Actions の ::error アノテーション、
• bca: skipped N violations via [check.exclude] と bca: filtered N violations via baseline の件数表示、
• すべての warning: および error: 診断メッセージ。

One combination inverts this. --report-format <dialect> without --output puts the aggregated SARIF / Checkstyle / Code Climate document on stdout, so the human rows move to stderr rather than corrupting it (the first example counts results with jq):

bca check --report-format sarif | jq '.runs[0].results | length'   # ドキュメントは stdout に
bca check --report-format sarif --output report.sarif | wc -l      # 違反行は stdout に戻る

--summary-file のダイジェストはストリームではなくファイルであり、どちらのストリームにも現れません。

Earlier releases sent the rows to stderr along with everything else, which made | wc -l and 2>/dev/null report an empty offender list, indistinguishable from a clean tree. A pipeline that reads the rows through 2>&1 needs no change; one that captured them with 2>file should now use >file.

ベースライン

Adopting thresholds on an existing codebase usually presents a choice between “raise the limit until nothing fires” and “fix every offender before turning the gate on”. A baseline file is the ratchet-down alternative: record today’s offenders, fail only on regressions and new offenders, and shrink the file over time as the team pays down debt.

Baselines complement the suppression markers; they are not a substitute. A suppression says “this function is intentionally exempt forever” and lives in source; a baseline says “this is tech debt we are paying down” and lives in a committed TOML file. bca check applies in-source suppressions first, then [check.exclude] globs, then the baseline filter.

ベースラインの書き出し

bca check --paths src/ \
    --write-baseline .bca-baseline.toml

This walks the tree, captures every threshold violation that would otherwise fail the check, and writes them to the file as sorted TOML. The run exits 0 regardless of offender count, since the point is to capture them.

# bca ベースラインファイル。`bca check --write-baseline` により生成。
# 記載された違反はしきい値チェックから除外されます。記録値より
# 悪化した関数は引き続き失敗します。エントリが古くなったら
# `--write-baseline` で更新してください。
version = 6

[provenance]
tier = "hard"

[[entry]]
path = "src/parser.rs"
qualified = "Parser::parse_expression"
metric = "cyclomatic"
value = 22.0

The qualified field is the function’s qualified symbol: the ::-joined chain of enclosing named containers plus the function name. An entry carries a start_line only when another entry shares its (path, qualified, metric) identity, the one case where matching consults a line number. Recording it elsewhere would rewrite the file every time an edit above the function shifted it. With --baseline-fuzzy-match, each entry also carries a body_hash for rename-tolerant matching.

Functions already covered by an in-source suppression marker are excluded. Pass --no-suppress together with --write-baseline to include violations hidden by source markers (the CI-auditor flow); [check.exclude] exemptions still apply.

--write-baseline cannot be combined with --baseline, --report-format, --output, --since, or --changed-only, because the baseline file is the output.

ベースラインの読み込み

bca check --paths src/ \
    --baseline .bca-baseline.toml

違反は、次の両方の条件が成り立つときに抑制されます。

• An entry matches by (path, qualified_symbol, metric), independent of line number, or, failing that and with --baseline-fuzzy-match, by body hash. See the Baselines recipe for the full resolution order.
• 現在の value が記録された値以下である。

A function that gets worse than its baseline value still fails. New offenders not listed in the baseline still fail. Improvements pass silently; the entry keeps its older, higher value until the next --write-baseline refresh.

存在しない、空である、version が欠落もしくは未対応である、またはパースに失敗するベースラインファイルはツールエラー（終了コード 1）であり、黙ってゼロマッチ扱いにはなりません。

Path keys are canonicalised relative to the baseline file’s own directory (the anchor), so --paths ., --paths src/, and --paths "$PWD" produce byte-identical baselines, and a --baseline run matches whichever --paths form generated the file. Switch between them freely without re-running --write-baseline.

制限事項

• Ambiguous symbols and anonymous functions. Entries key on the qualified symbol, so inserting code above a named function does not re-key it. Two exceptions re-key as “new” on movement: functions sharing a qualified symbol that drift more than --baseline-line-tolerance apart, and anonymous closures or lambdas, whose synthetic symbol embeds the line. Refresh with --write-baseline.
• OS 間の可搬性。 パスはスラッシュ区切りで保存されるため、ある OS で書かれたベースラインは別の OS 上の同じツリーにマッチします。有効な UTF-8 でないパスは損失のある表示形式（U+FFFD 置換）にフォールバックし、正確にラウンドトリップしない場合があります。

エンドツーエンドの導入フローと CI 統合パターンについては、ベースラインレシピを参照してください。

失敗させずに報告する

--no-fail reports offenders as usual but exits 0. Use it while adopting baselines without turning CI red. Other CI tools call this behavior --report-only or --soft-fail; here the flag is spelled --no-fail.

bca check --paths src/ --no-fail

CI の例（GitHub Actions）

- name: Check code complexity thresholds
  run: |
    bca check
  # Thresholds and paths come from the auto-discovered `bca.toml`
  # manifest at the repo root. The default non-zero exit fails the
  # step, which is the behaviour wanted here. No extra wiring.

To keep the job green and surface offenders as a build annotation while you reduce the count, swap in --no-fail:

- name: Surface complexity hot spots (non-blocking)
  run: |
    bca check --paths src/ --no-fail

対処しやすい失敗出力

When bca check fails, five flags shape the failure stream so a developer skimming a CI log can see what tripped, where in their PR it tripped, and what to do next. Each flag is independent, and all of them auto-detect from GitHub Actions environment variables when present, so the common CI case needs no explicit configuration.

The per-violation rows and the per-file rollup footer keep the same content when none of the above are active, so CI tooling that grep-anchors on the legacy text keeps working. See Which stream for where each now lands.

See the CI integration recipe for worked examples, including a GitHub Actions snippet that composes all five flags into one step, and the Baselines recipe for the --write-baseline refresh flow the remediation block links to.

diff ベース自動検出の優先順位

When --since is omitted, bca consults environment variables in this order:

1. BCA_DIFF_BASE: an explicit override for local shells or CI runners other than GitHub Actions.
2. GITHUB_BASE_REF: set by GitHub Actions on pull_request events. Expanded to origin/<value>; the runner is responsible for the corresponding git fetch (fetch-depth: 0 on actions/checkout).
3. GITHUB_EVENT_BEFORE: set by GitHub Actions on push events to the SHA at HEAD before the push. The all-zeroes sentinel (force push, brand-new branch) is treated as no signal.

Failing to resolve a base is non-fatal unless --changed-only is passed, in which case the gate dies. Silently suppressing every violation under a misconfigured base is the failure mode this feature exists to prevent. --write-baseline also conflicts with --since / --changed-only: a partial baseline would silently mask every offender outside the diff scope on the next full-tree run.

違反レコードのエクスポート

bca check also emits a single CI/IDE document covering every offender in the walk. Pass --report-format <fmt> to pick the shape and --output <file> to write it to disk (stdout if omitted). The --format, -O, and --output-format spellings are accepted as deprecated aliases and will be removed in a future release. These flags do not change the exit-code contract: 0 clean, 2 on any violation (unless --no-fail), 1 on tool error.

When --output is given without --report-format, the format is inferred from the output extension: .sarif selects sarif and .xml selects checkstyle. An extension with no unique format (notably .json, which both sarif and code-climate produce) or no extension at all is a usage error (exit 1) naming --report-format, so an explicit --output is never silently ignored. An explicit --report-format always wins over the extension.

When no offenders exist the writer emits a well-formed but empty document, so CI consumers can ingest clean runs unchanged: an empty runs[].results array for SARIF, an empty JSON array ([]) for Code Climate, no <file> children under the <checkstyle> root for Checkstyle, and zero bytes for the two warning-line formats.

Checkstyle（CI 統合）

bca check --paths src/ \
    --threshold cyclomatic=15 \
    --report-format checkstyle \
    --output report.checkstyle.xml

Checkstyle ライターは、ソースパスごとに 1 つの <file> 要素を含む単一の <checkstyle version="4.3"> ドキュメントを出力し、各 <file> はメトリクスしきい値違反ごとに 1 つの <error> を保持します。スキーマは Checkstyle 4.3 の XSD で、Jenkins および SonarQube の「Warnings Next Generation」/「Generic Issue」インポーターが直接取り込めます。

SARIF（GitHub Code Scanning）

bca check --paths src/ \
    --threshold cyclomatic=15 \
    --report-format sarif \
    --output report.sarif.json

SARIF ライターは、1 つの runs[] 要素を持つ単一の SARIF 2.1.0 JSON ドキュメントを出力します。各メトリクスしきい値違反は runs[0].results[] 配下の result になり、実行結果に現れるメトリクス名は重複排除されて、短い説明とともに runs[0].tool.driver.rules[] に格納されます。

ワークフローから GitHub Code Scanning に SARIF ファイルをアップロードするには:

name: bca-sarif
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - name: Run big-code-analysis
        run: |
          bca check --paths . \
              --report-format sarif \
              --output report.sarif.json \
              --no-fail
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: report.sarif.json

--no-fail はジョブを成功（グリーン）のまま保つため、違反が存在しても SARIF アップロードステップは実行されます。メトリクスの悪化でワークフローを失敗させたくなったら外してください。

GitLab Code Quality（Code Climate JSON）

bca check --paths src/ \
    --threshold cyclomatic=15 \
    --report-format code-climate \
    --output gl-code-quality-report.json

The Code Climate writer emits a single JSON array of issue objects matching GitLab’s strict subset of the upstream Code Climate engine spec: one entry per metric-threshold violation, no byte-order-mark, one trailing newline (empty input renders as []\n).

Each issue carries three fields of note. The check_name is namespaced as big-code-analysis/<metric>. The fingerprint is a stable SHA-256 over path \0 function \0 metric; it ignores line and value, so cosmetic edits still dedup in the MR widget. The severity maps GitLab’s five-level enum from the same severity key bca check ranks its own offenders by: ≤ 1.5 → minor, ≤ 2 → major, ≤ 4 → critical, > 4 → blocker.

For a count the key is value / limit, and a breach of a zero limit is always blocker. For the mi.* family, where lower is worse and the index has no true zero, it is 1 + (limit − value) / unit: one step per maintainability band (17.1 points of mi.original / mi.sei, 10 of mi.visual_studio) below the floor. An mi.original of 0 against a floor of 20 is critical; one of −40 is blocker. The full enum is info/minor/major/critical/blocker; bca never emits info, because a threshold violation always lands at minor or higher.

アーティファクトを GitLab の MR Code Quality ウィジェットに接続するには:

code_quality:
  stage: quality
  script:
    - bca check --paths "$CI_PROJECT_DIR"
          --report-format code-climate
          --output gl-code-quality-report.json
          --no-fail
  artifacts:
    when: always
    reports:
      codequality: gl-code-quality-report.json
    paths:
      - gl-code-quality-report.json

パイプライン全体（Code Climate + Checkstyle + Markdown レポートの組み合わせ）とローカルでの jq によるスモークチェックについては、GitLab Code Quality ウィジェットのレシピを参照してください。

--no-fail はジョブを成功（グリーン）のまま保つため、違反が存在しても Code Quality レポートはアップロードされます。メトリクスの悪化でパイプラインを失敗させたくなったら外してください。

Clang/GCC 警告行（エディタの quickfix と CI アノテーター）

bca check --paths src/ \
    --threshold cyclomatic=15 \
    --report-format clang-warning \
    --output report.txt

Clang フォーマットは、慣例的なコンパイラ警告の形式で違反を 1 行に 1 件ずつ出力します:

path/to/file.rs:42:5: warning: cyclomatic 17 exceeds limit 15 [big-code-analysis-cyclomatic]

This is the format clang -fdiagnostics-format= produces and the shape editor quickfix parsers (VS Code, IntelliJ, Vim) and most CI annotators understand without configuration.

GitHub Actions surfaces the lines as inline annotations on the PR diff through the built-in GCC problem matcher (or any community compiler-problem-matchers action):

name: bca-clang-warnings
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Enable GCC problem matcher
        run: echo "::add-matcher::$RUNNER_TOOL_CACHE/problem-matchers/gcc.json"
      - name: Run big-code-analysis
        run: |
          bca check --paths . \
              --report-format clang-warning \
              --no-fail

ランナーに GCC matcher が同梱されていない場合は、これらの行をストリーム処理して ::warning file=...,line=...:: ワークフローコマンドとして再出力する方法にフォールバックしてください。

MSVC 警告行（Visual Studio と Windows CI）

bca check --paths src/ \
    --threshold cyclomatic=15 \
    --report-format msvc-warning \
    --output report.txt

MSVC フォーマットは、Visual Studio の cl.exe 診断形式で違反を 1 行に 1 件ずつ出力します:

path\to\file.rs(42,5): warning : cyclomatic 17 exceeds limit 15

The space before the colon after warning/error is the MSVC convention. On Windows the path is normalized to \ separators, matching cl.exe output; on other platforms the path is emitted as-is. Visual Studio, VS Code with the C/C++ extension, and Windows CI runners (Azure Pipelines, GitHub Actions on windows-latest) parse these inline without extra configuration.

抑制マーカーによる違反の抑制

ソース内コメントによって、問題のコードを編集したりウォークから除外したりせずに、個々の関数またはファイル全体のしきい値違反を抑制できます。ネイティブの記法は bca: suppress / bca: suppress-file で、Lizard の #lizard forgives は互換シムとして認識されます。完全なリファレンスと --no-suppress CI 監査フラグについては抑制マーカーを参照してください。

ファイルカテゴリ全体の除外（[check.exclude]）

Some files should be analysed and reported but never gated: test fixtures that intentionally trip cognitive or cyclomatic, generated bindings, macro-dispatch modules whose complexity is structural and will never be “fixed”. Putting these in .bcaignore is too blunt: it removes them from the walk entirely, so bca report loses them too. Baselining them is also wrong, because they are not debt being paid down, and they churn the baseline diff forever.

[check.exclude] is the glob-level middle ground. Matching files are walked, parsed, measured, and shown by bca report, but bca check drops their violations before emitting offenders and before --write-baseline records anything, so the structural exemptions stay out of .bca-baseline.toml.

bca.toml の場合：

[check]
exclude = [
    "tests/**",
    "big-code-analysis-ast/src/languages/language_*.rs",
    "xtask/**",
]

またはコマンドラインで指定します（--check-exclude は繰り返し指定可能で、--check-exclude-from と結合されます）。

bca check --check-exclude "tests/**" --check-exclude "xtask/**"
bca check --check-exclude-from .bcacheckignore

--check-exclude-from reads a .gitignore-style file (blank lines and # comments skipped); the conventional name is .bcacheckignore, mirroring .bcaignore for the walker. Globs match the path exactly as the walker matched it for --exclude. As a negative filter key, an explicit --check-exclude list unions with the manifest [check] exclude list rather than replacing it. A CLI exemption is added to the project’s, so you cannot accidentally re-gate a path the manifest deliberately exempted. Duplicates collapse; CLI patterns sort first. Pass --no-config to drop the manifest’s exemptions entirely. Positive scope keys like paths / include still replace on the CLI; only the exclude filters merge.

相対グロブは何に対して相対か

The source of a glob determines its root:

So exclude = ["./vendor/**"] in a manifest at the repo root means <repo>/vendor/, whichever directory you invoke bca check from, including from inside vendor/ itself. The same glob passed as --check-exclude './vendor/**' means vendor/ under your shell’s current directory, because that is where you typed it.

This matters most for per-file callers (editor integrations, pre-commit hooks, the agent hooks in Agent feedback), which run bca check <one file> from whatever directory they happen to be in. Their exemptions belong in the manifest, where the anchor is the project’s and not the caller’s.

The walker’s exclude / --exclude pair is split by origin the same way: a --exclude glob is matched against each file’s path relative to the seed you named, and a manifest exclude glob is resolved against the manifest’s own directory, whatever seed you name and wherever you run from. So bca metrics and bca metrics -p sub honour the same manifest exclusions (#1189), and the warning that a named file overrode an exclude resolves each glob at its own root (#1164).

他の抑制メカニズムとの優先順位

bca check は、最も特異的なものから順に、次の順序で除外を解決します。

1. In-source markers (bca: suppress / bca: suppress-file) always win; they apply during the walk, so the function never becomes a violation.
2. [check.exclude] globs exempt categories of files (tests, generated code).
3. .bca-baseline.toml lists known offenders being paid down.

--print-effective-config は、他のゲート入力と併せて解決後の check_exclude グロブを報告します。

check_exclude lists the combined CLI and manifest globs. manifest_check_exclude identifies the manifest subset; resolve those globs relative to the reported manifest directory. The walker uses exclude and manifest_exclude in the same way. The manifest-specific keys are absent when the manifest contributes no globs.

manifest_exclude_from and manifest_check_exclude_from follow the same idea for the exclude_from files, with one difference: a command-line --exclude-from replaces the manifest’s file rather than adding to it, so the manifest key is present only when the manifest’s file is the one in effect. The inline glob lists union; the files do not.

言語別の制限（[thresholds.lang.<slug>]）

Metric distributions vary by language more than by project: the measured 97.5th-percentile per-function cognitive value runs from 4 in C# to 50 in C. A [thresholds.lang.<slug>] table gives one language its own limits, layered over the project-wide table:

[thresholds]
cognitive = 15
cyclomatic = 15
"loc.ploc" = 600

[thresholds.lang.c]
cognitive = 30
"loc.ploc" = 1200

[thresholds.lang.elixir]
nom = 150
wmc = 300

C is now gated at cognitive = 30 and loc.ploc = 1200 while keeping the project’s cyclomatic = 15; every other language keeps all three. The override is per metric, not a replacement table: a language inherits every limit it does not restate. Which numbers to change, and the two cases where an override is a correction rather than tuning, are in Choosing thresholds.

The key is the canonical language slug, the same vocabulary --language accepts: rust, python, cpp, csharp, objc, tsx, mozcpp, mozjs, and so on. bca check --language nonsense prints the full list. Two rules point in opposite directions here:

• マニフェスト内の未知のスラッグは、did-you-mean ヒント付きのツールエラー（終了コード 1）です。タイポした [thresholds.lang.rust-lang] が、作者は緩めたつもりでいるのにゲートを黙ってプロジェクトの制限のままにしておく、という事態があってはなりません。
• An unrecognised file language falls through to the global table, as does any language with no override of its own. Nothing is silently ungated. A file whose extension maps to no grammar at all is skipped by the walk before the gate sees it, with a warning if you named it explicitly.

コマンドラインの --threshold はグローバルのままで、これまでどおり最後に絶対的に適用されます。プロジェクトのテーブル「と」すべての言語別テーブルの両方を上書きするため、あなたが入力した制限が実際に動く制限になります。

--print-effective-config prints one fully resolved table per overridden language, inherited limits included rather than a diff, so the number that will fire is the number you read:

[thresholds]
cognitive = 15.0
cyclomatic = 15.0

[thresholds.lang.c]
cognitive = 30.0
cyclomatic = 15.0

Per-path limits ([[thresholds.path]])

A [[thresholds.path]] entry re-limits the files its glob matches for the metrics it names, and inherits everything else. It is for a population of files whose shape the project limit misreads — a directory of dispatch tables, a generated layer — and it keeps those files gated, at a limit chosen for them, where a suppression marker would remove them:

[[thresholds.path]]
glob = "src/metrics/{abc,cognitive,cyclomatic,loc}/*.rs"
cyclomatic = 40
"halstead.effort" = 150000

The glob is matched relative to the directory of the config that declared it — the bca.toml, or the --config file — with the engine and anchor [check] exclude uses. Where several entries match one file the last wins, per metric. An unknown metric, a missing or empty glob, and tokens are each a tool error naming the entry. The soft tier derives from the overridden limit, and --threshold still outranks it; the full order is stated once in How the layers compose, and when to reach for an entry rather than a marker is in Per-path overrides.

--print-effective-config prints each entry after the per-language tables, with the metrics it declares at their hard-tier limit — --threshold applied last, the tier not applied — so the printed file replays the gate at the hard tier through --config. That is the whole guarantee. The resolved view carries no [thresholds.soft] table and does not record which limits came from --threshold, so a soft-tier run is not replayed by the printout alone: loading it with the same --tier re-derives a band from the printed hard limits, which matches the original only when the original’s soft configuration is still in scope (the manifest is still discovered, not --no-config) and it used no --threshold (a CLI limit is absolute and unscaled on the original run; reloaded, it is a hard limit the band scales). The reason the printed path limits are hard, not banded, is in Per-path overrides:

[thresholds]
cyclomatic = 15.0

[[thresholds.path]]
glob = "src/metrics/{abc,cognitive,cyclomatic,loc}/*.rs"
cyclomatic = 40.0
"halstead.effort" = 150000.0

二層しきい値（--tier）

--tier <hard|soft|soft=RATIO> は、ゲートが比較に使うしきい値の層を選択します。hard（デフォルト）は [thresholds] テーブルをそのまま使います。soft はハードゲートの「前に」発火する早期警告の層で、すべての制限を RATIO 倍に引き締めます。--tier 単独指定は soft を意味し、soft だけならデフォルト比率 0.95 を使い、soft=0.90 は比率を 0.90 に固定し、soft=1.0 は一括スケールを無効にします。

RATIO scales the band, not the number. For most metrics a limit is a ceiling, so tightening it means multiplying: cognitive = 15 with soft=0.9 warns at 13.5.

The lower-is-worse mi.* family is different. Its limit is a floor, a value below it is the violation, and the index has no true zero (mi.original and mi.sei go negative on large functions). So the floor is raised by 1 − RATIO of one maintainability band rather than scaled. One band is 10 points of mi.visual_studio, whose 20/10 cut-offs Visual Studio and radon use, and the same 17.1 points on the 171-point mi.original / mi.sei scale. "mi.original" = 20 with soft=0.9 warns at 20 + 0.1 × 17.1 = 21.71, and a floor of -50 at -48.29. Multiplying a floor would move the warning to 18, under the hard gate, and dividing a negative one would do the same (-50 / 0.9 = -55.6). Either way nothing could reach the soft band first.

Limits must be finite. A count limit must also be non-negative; an mi.original or mi.sei floor may be negative. A limit that cannot fire, or fires on every value, still parses but prints a warning: mi.visual_studio is clamped to [0, 100], so = 0 reads warning: limit mi.visual_studio=0 cannot fire: 0 is the metric's floor; gate mi.original instead, and = 101 warns that it fires on every value.

[thresholds.soft] テーブルはメトリクスごとのソフト制限を設定します。各値は絶対値の数値か、そのメトリクスのハード制限をスケールする "<ratio>x" 文字列のいずれかです。

[thresholds]
cognitive  = 25
cyclomatic = 15
nargs      = 7

[thresholds.soft]
cognitive  = 22       # 絶対値のソフト制限
cyclomatic = "0.9x"   # ハード制限の 90% → 13.5
# nargs は未指定 → ソフト層はハード制限を継承（ソフト帯なし）

bca check --paths src/ --tier=soft

The soft tier is one step of the layering order stated in How the layers compose. Within that step: if a [thresholds.soft] table exists, its overrides merge onto the resolved hard limits and metrics absent from it inherit their hard limit — the blanket RATIO does not apply, since explicit per-metric limits win; otherwise every limit is tightened by the soft RATIO (default 0.95 for a bare soft; soft=1.0 disables scaling). Repeated --threshold name=value flags still apply after it, absolutely.

The step runs once per table — the project’s, each language’s, and each [[thresholds.path]] combination’s — against that table’s own resolved hard limits. There is no [thresholds.lang.<slug>].soft table and none is needed. With [thresholds] cognitive = 15, [thresholds.lang.c] cognitive = 30, and --tier=soft=0.9, C’s soft band is 27, nine tenths of its limit, and the ceiling a C offender is measured against for the exit-5 escalation is 30, not 15. Derive either from the project’s 15 and every C function between 15 and 30 reports “also breaches the hard limit” while sitting inside the limit the project configured for it.

The one combination that can invert the two tiers is an absolute [thresholds.soft] value looser than the hard limit it shadows: [thresholds.soft] cognitive = 12 alongside [thresholds.lang.csharp] cognitive = 4, or an mi.* soft floor below its hard floor. That is a tool error (exit 1) naming the offending table, for the same reason a "<ratio>x" factor above 1 is rejected at parse time: a soft tier that fires after the hard gate is never the intent.

The soft RATIO (and the scale factor in a "<ratio>x" string) must be in (0, 1]. The [check] headroom manifest key supplies the ratio for a bare --tier=soft. The deprecated --headroom <R> flag is a one-cycle alias for --tier=soft=<R> (warns; removed at the next major); it now promotes a hard run to the soft tier. Both tiers ratchet through the same --baseline, and --print-effective-config reports the resolved tier alongside the post-merge limits. See the Local threshold gates recipe for the migration tip and rationale.

候補制限のプレビュー（--explain-threshold）

--explain-threshold <metric>=<limit> reports what a candidate limit would cost at both tiers instead of gating. It is repeatable, takes one candidate per metric, and writes nothing.

$ bca check --explain-threshold nargs=6
nargs: candidate limit 6
  hard tier (limit 6): 60 offenders, 60 already baselined, 0 new
  soft tier (limit 5.7, 0.95x): 135 offenders, 61 already baselined, 74 new
  cluster: 75 of 75 soft-band offenders sit at exactly 6 — the candidate
  limit itself. The soft tier measures distance to the limit, so a limit
  of 6 places them inside the 5.7 band by construction and none of them
  can clear it without real work.

The new column is the figure to weigh: it is how many baseline entries adopting the limit would add. Here the hard tier reads as free and the soft tier costs 74 entries, none of which any amount of tidying can retire. Making that visible is the reason the flag exists.

--threshold nargs=6 はこれを教えてくれません。その制限は最後に、絶対的に、決してスケールされずに適用されるため、この方法で試した候補にはソフト層がまったくありません。同じメトリクスに両方のフラグを渡すと、黙って解決されるのではなく拒否されます。

The soft limit is derived from the candidate exactly as a real run would derive it: a [thresholds.soft] entry for the metric wins, then the --tier=soft=RATIO ratio if one was given, then 0.95. A [thresholds.lang.<slug>] table that overrides the metric keeps its own limit, since a candidate global limit does not reach it, and the report says so on its own line. A ratio-derived soft limit names its arithmetic: 5.7, 0.95x for a count, and for an mi.* floor the additive step, as in mi.original=20 → 20.855, +0.855 (0.05 × 17.1).

それ以外はすべて、予測対象の実行と一致します。exclude_tests、[check] exclude、ソース内の抑制マーカー、--changed-only、ベースラインはいずれも通常どおり適用されます。唯一の違いは、ベースラインでカバーされた違反者が、落とされるのではなくカウントされることです。これによって already baselined / new の分割が可能になっています。

The preview replaces the gate, so it never fails: the exit code is 0 unless a tool error (exit 1) stops the run, and a one-line reminder of that goes to stderr. It conflicts with --write-baseline, --print-effective-config, --report-format, --output, and an explicit --summary-file <path> (the auto / never keywords are still accepted), each of which would produce a second, different artifact.

このフラグが可視化するために存在する規則については、しきい値の選択を参照してください。

信頼できない入力に対するモード（--strict）

ゲートが検査するファイル集合を狭める既定の動作が 2 つあり、どちらもテスト対象のツリーから入力を読み取ります。生成コード検出器はヘッダにマーカー語句を含むファイルをスキップし、ウォーカーは走査対象ツリー内の .gitignore ファイルを解釈します。どちらも信頼できるチェックアウトの分析には適切な既定値です。しかしプルリクエストのゲートでは、レビュー対象の変更が引けるレバーになります。コメント 1 行の追加、または .gitignore への 1 エントリで、ファイルがゲートから外れます。CI レシピに両方の再現手順があります。

--strict は両者を 1 つのフラグで無効にします。--no-skip-generated --no-ignore を渡すのと等価です。

bca check --strict --paths src/

プロジェクトはワークフローごとではなく、bca.toml で一度だけオプトインします。

[check]
strict = true

このキーはトップレベルの exclude_tests と同様に presence-only です。プロファイルを有効にすることはできますが、無効に戻すことはできません（--no-strict はありません）。そのため CI ワークフローがコミット済みのポリシーを黙って弱めることはできません。

プロファイルが無効でも、bca check は検査しなかったものを報告します。いずれかの仕組みがファイルを除外した場合は、1 行のサマリーを stderr に出力して件数を示します。

bca: 2 files not checked (1 generated, 1 ignored) — pass --report-skipped to list them

クリーンな実行では何も出力されず、サマリーが終了コードを変えることもありません。--report-skipped は除外された各エントリを note: skipped (generated): <path>、note: skipped (ignored): <path>、または note: skipped (ignored directory): <path> の行で一覧表示します。--strict の下では何もスキップされないため、要約するものもありません。

The counts come from the walk’s prune points: for every directory the walker entered, the gate checks which immediate children the ignore rules dropped. Only files a parser owns are counted, on both sides. An ignored log file, or a generated Cargo.lock (whose header matches @generated), would have been read and dropped rather than checked, and counting either would make the summary fire on every run. A file named explicitly on the command line bypasses ignore rules and is analyzed, so it is never counted.

Ignored directories are reported only under --report-skipped, as N ignored directories not walked entries, and are never entered. Nearly every checkout has an ignored build tree on disk, and enumerating a target/-sized tree would cost a full second traversal for a million-file count with no signal in it. The ignored tally reflects every source the walker honors (in-tree .gitignore and .ignore files, the global gitignore, and ancestor ignore files), so local and CI counts can differ.

With content sniffing off, generated trees still need an exemption. Give them one the reviewers own, either a committed walker deny-set (--exclude-from .bcaignore) or a [check.exclude] glob, rather than a marker the submitter controls.

抑制マーカー

In-source suppression markers silence threshold violations without editing the offending function or excluding the file from the walk. Drop a marker in any comment in the source file and bca check treats the covered metrics as if they were within limits for that scope. Metric computation is unaffected: raw bca metrics output still reports every number. Suppression is a display concern. bca check drops the covered violations from the gate, and bca report markdown|html omits the covered functions from the matching hotspot tables by default (pass bca report --no-suppress for the raw audit view; see report).

Markers exist for the cases where editing the code is not an option: legacy modules awaiting rewrite, accepted exceptions documented in the comment, and migration from Lizard’s #lizard forgives convention. This page is the marker reference: the syntax, the metric names it accepts, where a marker may sit, and the flags that audit or bypass markers.

ネイティブマーカー（bca:）

ネイティブ方言は bca: 名前空間と suppress 動詞を使用し、プロジェクト内部の「suppression（抑制）」語彙（SuppressionPolicy、FuncSpace::suppressed、--no-suppress）と一致しています。形式は 4 つあります:

The two metric-list forms may carry a rationale: free text on the same line, after the marker itself:

#![allow(unused)]
fn main() {
// bca: suppress(nargs) — 引き回されるコンテキストであって、神関数ではない
}

No separator is required and none is privileged: — why, - why, : why, // why, and bare prose all read the same. The two bare verbs take no trailing text at all; bca: suppress see #123 is not a marker, whatever punctuation opens the trailing words. See Rationale text for why.

A function-scope marker attaches to the innermost FuncSpace (see the FuncSpace rustdoc) whose source range contains the comment. A function-scope marker outside every function body is silently ignored; for file-wide silencing use the explicit suppress-file verb. A file-scope marker may appear anywhere in the source; there is no “must be in first N lines” rule.

bca: suppress: function-scoped, all metrics (Rust)

#![allow(unused)]
fn main() {
// bca: suppress
fn legacy_dispatch(opcode: u8) -> Action {
    // サポートされる全オペコードに対する高密度な match
    match opcode { /* ... */ }
}
}

bca: suppress(metric, ...): function-scoped, listed metrics (Python)

def parse_token_stream(tokens):
    # bca: suppress(cognitive)
    # 認知的複雑度はこのステートマシンに本質的なもの。
    # 循環的複雑度は依然として制限内に収まっている。
    ...

その他のしきい値（cyclomatic、halstead、loc など）は引き続き適用されます。

bca: suppress-file: file-scoped, all metrics (JavaScript)

// bca: suppress-file
// 手動チューニングされたホットパス。しきい値を満たすための書き換えはしないこと。
function transform(input) { /* ... */ }
function validate(input) { /* ... */ }

bca: suppress-file(metric, ...): file-scoped, listed metrics (C++)

/* bca: suppress-file(halstead) */
// Halstead の volume は下の生成テーブルによって膨らんでいる。
// それ以外のメトリクスはファイル全体で引き続き適用される。

Prefer a narrower tool first. Thresholds apply at each metric’s defined scope. A file-wide or impl-wide aggregate does not trigger a per-function limit, so muting a file-level halstead / nargs / nexits / nom total is no longer a reason to reach for suppress-file (#969). Use suppress-file when you intend to silence the metric throughout the file. To excuse one irreducibly complex function, use a function-scoped bca: suppress(...) inside it. To grandfather existing offenders without blinding the gate to future regressions, prefer a baseline entry, which keeps firing once a function gets worse than its recorded value.

Lizard 互換マーカー

既存の Lizard 対応コードベースを書き換えずに済むよう、2 つの Lizard 形式マーカーがそのまま認識されます:

The compatibility layer is intentionally narrow: only these two shapes are accepted. Other Lizard directives parse as ordinary comments. Lizard offers no per-metric scoping, so the native form’s bca: suppress(metric, ...) list has no Lizard analogue; every Lizard-style marker silences every metric.

Lizard の GENERATED CODE マーカーはここでは扱いません。これは生成コードの自動スキップ機構の一部です（生成コードのスキップと --no-skip-generated フラグを参照）。

ネイティブと Lizard の対照表

メトリクス識別子

bca: suppress(...) と bca: suppress-file(...) の内側で受け付けられる識別子は次のとおりです:

abc, cognitive, cyclomatic, halstead, loc, mi, nargs, nexits, nom, npa, npm, wmc.

これらは、しきい値名および CodeMetrics に出力される JSON フィールド名と一致しますが、意図的な除外が 1 つあります:

• nexits is the canonical spelling: bca: suppress(nexits) silences a nexits threshold violation. The legacy exit alias was retired in #555 and is no longer accepted. Spelling it exit is an unknown identifier, which warns and is skipped; the recognized names beside it still suppress (see below).
• tokens はしきい値チェック可能なメトリクス（かつ CodeMetrics の JSON フィールド）ですが、意図的に抑制リストから外されています: マーカーで無効化することはできません。tokens は保守性のヒューリスティックではなく、ハードなリソース上限として扱ってください。

ファミリー（例えば halstead）を沈黙させると、その配下のすべてのサブメトリクスしきい値（halstead.volume、halstead.effort など）が対象になります。抑制の語彙にドット付きの形式はありません。

bca: suppress(...) リスト内の未知の識別子は、次の形式の stderr 警告を出力します

warning: path/to/file.rs:42: unknown metric 'no_such_metric' in bca suppression marker; known metrics: abc, cognitive, ...

Only the offending identifier is dropped: bca: suppress(cognitive, exit) still silences cognitive. Skipping can only shrink what a marker covers, so a typo never widens scope to a metric the author did not name. Rejecting the whole marker, which is what earlier releases did, would also discard valid metric names, leaving intended suppressions inactive.

Unknown verbs (anything other than suppress / suppress-file) and bodies that parse to no directive at all (an unbalanced parenthesis, a bare verb followed by any trailing text) produce the same shape of warning, and those do void the marker, since there is nothing left of it to honour. None of these are fatal: a typo in one file does not derail a workspace walk, and a doc comment that merely mentions the syntax does not fail your gate.

根拠テキスト

メトリクスリストの後のテキストは書き手のものです。bca はそこを読み飛ばし、解釈しません。2 つの形式の間の非対称性は意図的なものです：

• After a metric list (bca: suppress(nargs) threaded context) anything goes. The parentheses are a positive signal that this comment is a marker, and the list has already stated the intent unambiguously, so whatever follows is prose.

• After a bare verb (bca: suppress — irreducible dispatch) there is no trailing text. Nothing in this shape separates a rationale from a sentence about the feature, and no separator can: -, :, //, # and the dashes are exactly the punctuation someone writing // bca: suppress - we removed this marker, see #123 reaches for. Accepting them silences every metric in the enclosing function on the strength of a comment, so the whole shape warns instead.

  To record a reason, name the metrics (bca: suppress(cognitive, cyclomatic) — reason), which is more precise than the All hammer anyway. If All really is what you mean, put the reason on the line above the marker.

マーカーを書ける場所

マーカーは、コメントスタイルを問わず、任意のソースコメント内で認識されます。スキャナーはマッチングの前に、先頭の区切り文字 /、*、!、#、;、- と ASCII 空白を取り除きます。これは bca が現在パースするすべてのコメント形式をカバーします:

• C 系の行コメント: // bca: suppress
• C 系のブロックコメント: /* bca: suppress */
• Rust の内部ドキュメントコメント: //! bca: suppress と /*! bca: suppress */
• Python / シェル / Ruby / Perl の # コメント: # bca: suppress
• Lisp / Lua / SQL の行コメント: ;; bca: suppress、-- bca: suppress

Function-scope markers attach to the innermost Function-kind FuncSpace whose (start_line..=end_line) range contains the comment’s line. Markers buried in a class or struct body but outside every method are silently ignored; for class-wide silencing use bca: suppress-file or repeat the marker on each method.

ファイルスコープのマーカーはトップレベルの Unit スペースにマージされ、ネストに関係なくファイル内のすべての関数に適用されます。

マーカーはコメントの先頭近くに配置してください。スキャナーは両端の区切り文字を取り除いた後、先頭に bca:（または #lizard）が来ることを期待します。複数行ブロックコメントの奥深くに埋もれたマーカーは認識されません。

--no-suppress（CI での監査）

bca check --no-suppress ignores every suppression marker, native and Lizard alike, and reports every threshold violation in the walk. Use it in audit pipelines that need the raw, un-silenced offender list:

bca check --paths src/ --no-suppress

このフラグはメトリクスの値自体には影響しません: 生の bca metrics 出力は常にすべての数値を報告します。bca report markdown|html はデフォルトでホットスポットテーブルにおいてマーカーを尊重し、同じ生の監査ビューのために独自の --no-suppress フラグを受け付けます。

抑制された負債の可視化（--report-suppressed）

Suppression keeps an offender out of the gate, which also keeps it out of the --report-format document, so a suppressed module disappears from the code-scan report entirely. bca check --report-suppressed puts it back, as suppressed rather than active:

bca check --report-format sarif --no-fail --report-suppressed \
    --tier=soft=0.95 --output bca.sarif

Offenders silenced by an in-source marker or covered by the baseline are emitted into the SARIF document with a SARIF suppressions entry: kind: "inSource" for markers, kind: "external" for the baseline. The suppression never fails the gate (exit code and the human offender rows are unaffected); the suppressions entry lets downstream tooling tell suppressed debt apart from active offenders.

GitHub Code Scanning. GitHub renders a result that carries a suppressions entry as a suppressed (closed) alert, so the debt stays visible on the Security tab without failing the gate. If you only want active offenders to appear, omit --report-suppressed from the upload (this repo’s own Pages workflow does exactly that).

注記:

• Use SARIF to export suppressed offenders; other report formats emit only active offenders.
• Match the tier to your baseline’s provenance (--tier=soft=0.95 for a soft-0.95 baseline) so offenders below the hard limit still appear.
• Do not combine --report-suppressed with --no-suppress or --write-baseline.

適用除外の監査（bca exemptions）

--no-suppress shows you the offenders a marker silences, but not the markers themselves; to find every silencer you previously had to diff a --no-suppress run against a normal one. bca exemptions replaces that workaround with a direct listing of everything the bca check gate skips, across all three exemption tiers, in one report:

# ツリー内のすべての適用除外を一覧表示します（ソース内マーカーは
# 他のすべての走査コマンドと同様に [walker.exclude] を尊重します）。
bca exemptions --paths src/

# In-source markers (2)
  src/parser.rs:120  bca: suppress       metrics=all  parse_long
  src/lib.rs:1       bca: suppress-file  metrics=halstead  (whole file)

# [check.exclude] globs (1)
  tests/**

# Baseline (.bca-baseline.toml, 1 entry)
  src/markdown_report.rs write_language_section cognitive 29

The surrounding function (for function-scoped markers) gives scope context; file-scoped markers read (whole file), and a function-scoped marker written outside any function, which silences nothing, reads (no enclosing fn) so dead markers are visible.

フォーマットとセクションフィルタ

--format markdown は PR コメント向けのテーブルを出力します。--format json は、ダッシュボードや jq によるフィルタリングのために、3 つのティアすべてを単一の suppressions エンベロープの下にネストします：

bca exemptions --paths src/ --format json | jq '.suppressions.markers[] | select(.dialect == "lizard")'

JSON 形式では、省略されたセクション（--*-only フラグで要求されなかったもの）は null になり、要求されたが空だったセクションは [] になるため、フィルタは両者を区別できます。

The mutually exclusive --markers-only / --excludes-only / --baseline-only flags narrow the report to a single tier for a specialised PR bot, such as one that only comments on newly added in-source markers. The baseline (bca.toml top-level baseline) and [check.exclude] ([check] exclude) inputs default to the same sources bca check reads, so the audit reflects exactly what the gate would skip; override the baseline with --baseline <path>.

以前の --only-markers / --only-excludes / --only-baseline の綴りは、既存の PR ボットの呼び出しを動かし続けるため、1 リリースサイクルの間は非表示のエイリアスとして残ります。diff-baseline のセクションフィルタと一致する --<section>-only 形式を優先してください。

Unlike bca check, bca exemptions is informational and always exits 0 on success. It is a review surface, not a gate.

PR レビュー中に bca exemptions を bca diff-baseline と併用する方法については、ベースラインのレシピ も参照してください。

JSON 出力

FuncSpace は、マージされた抑制スコープを JSON 出力のオプションフィールド suppressed として公開します。スペースに適用されるマーカーがない場合、このフィールドは省略されるため、既存のスナップショット利用者には変化がありません。マーカーが発動した場合、このフィールドは次の 2 つの形のいずれかになります：

{ "suppressed": { "kind": "all" } }

{ "suppressed": { "kind": "some", "metrics": ["cognitive", "loc"] } }

kind: all は素のマーカー（bca: suppress、bca: suppress-file、または任意の Lizard 形式のマーカー）に対応します。kind: some は bca: suppress(...) / bca: suppress-file(...) で指定された明示的なメトリクスのリストを保持します。どちらの形も、ダッシュボードや監査ログに適した安定したシリアライズ出力です。

Lizard からの移行

互換レイヤーがあるため、移行は段階的に行えます：

1. Keep existing #lizard forgives and #lizard forgive global markers during migration; bca check recognizes them.
2. Replace markers with bca: suppress(...) when you need per-metric scoping; the Lizard form silences every metric.

本プロジェクトは Lizard 互換レイヤーを無期限に維持します。削除予定日はありません。

予約済み構文

次の形は将来の使用のために予約されており、現時点ではパースされません：

• bca: suppress-next: silence the immediately following declaration rather than the enclosing function. Rejected today as an unknown verb; it will be promoted to first-class behavior in a future release without breaking existing markers.

The reason = "..." argument this section used to reserve is no longer planned. Write the rationale after the metric list instead (see Rationale text), which is the spelling authors already reach for. Inside the parentheses, reason = "..." is still an unknown metric identifier and is skipped with a stderr warning.

ノード

The find, count, dump, and functions subcommands inspect the Abstract Syntax Tree (AST) that tree-sitter builds for a source file, rather than computing metrics from it. A node is one syntactic construct in that tree, and a node type is the grammar’s name for it (function_item, if_statement). Use these commands to locate constructs, count them, spot parse errors, or see how a grammar shapes a file.

移行しますか？ 以下の動詞は、再構成前のフラグによるアクション（-d、-f、--count など）を置き換えるものです。移行ガイド を参照してください。

エラー検出

コード内の構文エラーを検出するには、次を実行します：

bca find -t ERROR -I "*.ext" /path/to/your/file/or/directory

• [PATHS]... / -p, --paths：分析対象のファイルまたはディレクトリ（ディレクトリを指定するとすべてのファイルを分析します）。パスは位置引数または --paths で指定でき、両者は和集合になります。フラグはサブコマンドの後に置きます。
• -t, --type: the node type to match. Repeat the flag for several types (-t function_item -t struct_item); at least one is required. A string value matches the node-type name exactly (for example function_item). A purely numeric value is instead interpreted as a raw tree-sitter kind_id and matches nodes whose internal symbol id equals that number; for example, -t 65535 matches the ERROR sentinel. Prefer -t ERROR for error detection. The numeric form is an escape hatch for grammar inspection and is unstable: a kind_id is an index into the grammar’s symbol table, so the same number names a different node after a grammar-version bump. Prefer the string form unless you specifically need a kind that has no stable name.
• -I, --include: glob filter for selecting files by extension (*.js, *.rs). Each -I takes exactly one value, so a following positional path is never swallowed.

Semantic filters

Six -t/--type values are not node-type names but semantic filters, resolved per language so that one spelling works across every grammar. They take precedence over an identically named node type, so a grammar with a literal call node cannot be matched by name; use its numeric kind_id for that.

• all: every node, named and anonymous. bca count -t all therefore always reports 100%.
• function: a named function, method or other callable declaration. Anonymous ones are excluded where the language distinguishes them: in the JavaScript family an arrow function or function expression bound to a name (const add = (a, b) => …) is a function match, while the same expression passed inline as a callback (xs.map(x => x * 2)) is a closure and is not.
• call: a call site, meaning a function, method or command invocation a reader would navigate to. Object construction (new T(…)) and constructor delegation (C#’s : base(x) and a C# 12 primary constructor’s : Base(x), Java’s super(…), Kotlin’s superclass call) are deliberately excluded. They are counted by the ABC branches axis, whose Fitzpatrick rule is “function invocation or object creation”, a wider question than “where is this called”. Expect abc.branches to exceed a file’s call count in C#, Java, Groovy, Kotlin, C++, JavaScript, TypeScript, PHP, Ruby and Rust; see Where a constructor call lands. Each call matches once. In Perl, where the grammar parses a call’s name as a call of its own, foo(1) matches as the whole call only, and an auto-quoted hash key ((name => 1), $h{-name}), which it parses as a call too, does not match at all.
• comment: a comment of any of the language’s forms.
• string: a string literal. Type-annotation keywords that share the literal’s node name (TypeScript’s and PHP’s : string) are excluded.
• error: a node that is or contains a parse error, so a match covers every ancestor of an ERROR node up to the root as well as the node itself. -t ERROR is the narrower spelling used above: it matches the error nodes alone, by name.

ノードのカウント

count コマンドで、1 つ以上のノード種別の出現回数をカウントします：

bca count -t <NODE_TYPE> [-t <NODE_TYPE>...] -I "*.ext" \
    /path/to/your/file/or/directory

AST の表示

To visualize the AST of a source file, use the dump command. It requires an explicit path, since a whole-tree AST dump is never useful:

bca dump /path/to/your/file/or/directory

コードの一部の分析

コードの特定の部分だけを分析するには、dump サブコマンドの --line-start と --line-end オプションを使用します。例えば、5 行目から 10 行目までの単一の関数の AST を表示するには：

bca dump --line-start 5 --line-end 10 /path/to/your/file/or/directory

これらのフラグは dump と find に固有のものであるため、サブコマンドの後に置く必要があります。短い綴りの --ls / --le は非推奨のエイリアスとして引き続き機能しますが、次のメジャーバージョンで削除される予定です。

関数の一覧表示

すべての関数またはメソッドとその行範囲の一覧を得るには、次を使用します：

bca functions /path/to/your/file/or/directory

REST API

bca-web serves the big-code-analysis library over HTTP. This page is the reference for a client author: every route, its request and response shape, the error envelope, and the status codes. For running the daemon (flags, environment variables, resource limits, and the trust boundaries to respect before exposing it) see Operating bca-web; for end-to-end curl examples see Driving the REST API.

The source-in-body endpoints remove comments, list function spans, return the tree-sitter syntax tree, and compute metrics. Three further endpoints compute change-history (VCS) metrics over a repository on the server’s filesystem.

Running the server

bca-web --host 127.0.0.1 --port 9090

• --host: the address to bind (default 127.0.0.1).
• --port: the TCP port (default 8080).
• -j: the number of worker threads (optional).
• --cors: enable CORS for browser-based tooling (off by default).

CORS

By default bca-web emits no CORS headers: a browser script served from a different origin cannot read the API’s responses. This keeps a local bca-web (the default 127.0.0.1 bind) from exposing its repository paths and metrics to any website the operator happens to be visiting.

オプトインするには --cors を渡します。引数は オリジン の明示的なカンマ区切り許可リストです。許可リストに含まれるオリジンだけが Access-Control-Allow-Origin ヘッダーを受け取り、マッチしたオリジンがそのままエコーバックされます（それ以外のオリジンからのリクエストはヘッダーを受け取らず、ブラウザによってブロックされます）：

bca-web --cors https://app.example,https://tools.example

すべてのオリジンに Access-Control-Allow-Origin: * で応答するには、リテラルの * を渡します：

bca-web --cors '*'

全開放の * は、サーバーのメトリクスとリポジトリのパスをあらゆるオリジンに公開するため、信頼できるネットワークでのみ使用してください。

CORS が有効な場合、プリフライトの OPTIONS リクエストには 204 No Content で応答し、Access-Control-Allow-Origin、Access-Control-Allow-Methods（そのリソース自身が受け付けるメソッド。Allow ヘッダーが広告するのと同じ集合）、および Access-Control-Allow-Headers（リクエストの Access-Control-Request-Headers をエコーし、素のプローブに対しては Content-Type, Accept）を付与します。この API には認証も Cookie もないため、Access-Control-Allow-Credentials は決して送信されません。

API バージョニング

すべてのエンドポイントは /v1 プレフィックスの下にマウントされます（例えば /v1/metrics）。ルートの全集合は /v1/ping、/v1/version、/v1/languages、/v1/ast、/v1/comment、/v1/function、/v1/metrics、/v1/vcs、/v1/vcs/trend、/v1/vcs/jit、およびルートインデックス /v1 です。プログラムから発見するには GET /v1 を使用します（ルートインデックス を参照）。

以前の 1.x リリースが非推奨エイリアスとして提供していたプレフィックスなしのパス（/metrics、/comment、/ast、/、…）は 2.0 で削除されました。現在それらをリクエストすると 404 が返ります。どこでも /v1 形式を使用してください。

エラーレスポンス

Errors are reported with an HTTP status code, not inside a 200 body. Every error (on the JSON endpoints, the raw/octet-stream endpoints, and the 415/405/404 fallbacks alike) returns one uniform machine-readable JSON body, so clients parse a single error shape regardless of the success content-type:

{
  "error": "human-readable message",
  "error_kind": "stable_machine_token",
  "id": "echoed-request-id"
}

error is the specific human-readable cause; error_kind is a stable snake_case machine token (unknown_field, unsupported_language, bad_request, parse_timeout, and so on) so clients branch on the cause without string-matching the prose (issue #631). The token vocabulary is closed and governed by STABILITY.md.

The id key is always present. It carries the client-supplied correlation id when the request had one (the JSON endpoints), and an empty string otherwise: the octet-stream / query endpoints carry no id, and the content-type / method / not-found fallbacks, like any request whose body failed to parse before the id was read, have no parsed id to echo.

ステータスコード：

• 400 Bad Request: a malformed body or query parameter: invalid JSON, a missing required field, an unrecognised key (the strict deny_unknown_fields parse, including the removed unit flag; see Compute metrics below), or a scope value that is not full / file.
• 422 Unprocessable Entity: the file_name extension (and content sniffing) maps to no supported language. The route matched and the body parsed; only the submitted entity cannot be processed. The response carries the stable machine token "error": "unsupported_language"; query GET /v1/languages for the supported set. (Before 2.0 this was a 404, indistinguishable from an unknown URL; see issue #634.)
• 404 Not Found: the URL matches no endpoint.
• 415 Unsupported Media Type: a known POST endpoint received a Content-Type that is neither application/json nor application/octet-stream (a charset parameter is allowed).
• 405 Method Not Allowed: a known endpoint was called with the wrong HTTP method. The analysis endpoints accept POST; /v1/ping, /v1/version, /v1/languages, and /v1 accept GET and HEAD.
• 406 Not Acceptable: the request Accept header named only media types the server cannot produce. The structured analysis endpoints serve application/json, application/yaml, and application/cbor; any other concrete type (application/xml, say) is a 406 carrying the not_acceptable token. See Content negotiation.
• 413 Payload Too Large: the request body exceeded the server limit.
• 500 Internal Server Error: metric computation or AST construction failed for an otherwise-valid request, or a /vcs history walk failed on the server side. This also covers a response too deeply nested to serialize (serialize_failed); see Nesting limits below.
• 503 Service Unavailable: the parse pool is saturated by orphaned (timed-out) tasks; retry later.
• 504 Gateway Timeout: the parse (or history walk) exceeded the server’s configured deadline.

ネストの上限

Responses are trees, and the server’s serializers recurse through nested response trees, one native stack frame per level. A deeply nested response could overflow the stack, which aborts the whole process and takes every in-flight request with it. So the server refuses to serialize past a fixed depth and answers 500 with the serialize_failed token:

Both limits sit far above anything real source reaches. Across the integration corpus under tests/repositories (TensorFlow, DeepSpeech, serde, and others) the deepest AST measured 188 nodes and the deepest function-space nesting 10 when the limits were set (#1056). The /metrics limit is also more generous than the read side: a JSON document of nested spaces cannot be parsed back past ~61 levels, because serde_json’s own 128-level recursion limit charges two levels per space.

コンテンツネゴシエーション

The structured analysis endpoints (/v1/ast, /v1/comment in its JSON variant, /v1/function, /v1/metrics, /v1/vcs, /v1/vcs/trend, and /v1/vcs/jit) choose their response serialization from the request Accept header, mirroring the CLI’s -O json|yaml|cbor outputs. The same value serializes byte-for-byte identically whether it comes from the CLI or the server.

ルール：

• JSON is the default. Without an Accept header, the server returns JSON: the same body and Content-Type earlier releases always returned, so existing clients need no change. JSON entries and wildcards (*/*, application/*) make JSON a candidate.
• q weights are honored. The supported candidate with the highest q weight wins (Accept: application/json;q=0.5, application/yaml;q=0.9 returns YAML), with ties resolved by list order; q=0 refuses a type.
• サポートされないタイプは 406 になり、 暗黙の JSON フォールバックは行われません。ボディは error_kind: "not_acceptable" を持つ統一の {error, error_kind, id} エンベロープで、メッセージにはサポートされるメディアタイプが列挙されます。
• Only structured serializations are offered. TOML and CSV are excluded: TOML is awkward for the deeply nested space tree and CSV is flat and tabular. The error-envelope body is always JSON and the /v1/comment octet-stream variant (raw byte-in / byte-out) is always raw bytes; neither negotiates. The introspection routes (/v1, /v1/version, /v1/languages) return JSON metadata only.

# YAML メトリクス
curl --silent \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/yaml' \
  --data '{"file_name": "foo.py", "code": "def f():\n    pass\n"}' \
  http://127.0.0.1:8080/v1/metrics

# CBOR メトリクス（バイナリ。デコーダーにパイプしてください）
curl --silent \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/cbor' \
  --data '{"file_name": "foo.py", "code": "def f():\n    pass\n"}' \
  http://127.0.0.1:8080/v1/metrics --output metrics.cbor

エンドポイント

1. Ping the server

Checks that the server is running.

リクエスト：

GET http://127.0.0.1:8080/v1/ping

レスポンス：

• Status code: 200 OK
• ボディ：空。

Use curl -sf http://127.0.0.1:8080/v1/ping && echo ok to script a liveness check; -f makes curl exit non-zero on any HTTP error.

2. Remove comments

Removes comments from the submitted source. The endpoint accepts two Content-Type variants: application/octet-stream for raw byte-in / byte-out, and application/json for a JSON envelope.

リクエスト：

POST http://127.0.0.1:8080/v1/comment

ペイロード：

{
  "id": "unique-id",
  "file_name": "filename.ext",
  "code": "source code with comments"
}

• id: a correlation identifier for the request. Optional (issue #645); omitting it defaults to an empty string (treated as “no correlation id”).
• file_name: the name of the file being analyzed.
• code: the source code with comments.

レスポンス（JSON バリアント）:

{
  "id": "unique-id",
  "language": "cpp",
  "code": "print"
}

The response envelope reports id, the detected language (the canonical lowercase slug; see Compute metrics below), and the code result key. The code field is a string holding the stripped source: the request code arrived as a JSON string, so the stripped output is guaranteed valid UTF-8 and is handed back as a string, matching the request and every other JSON endpoint. The application/octet-stream variant returns the stripped source as the raw response body (no envelope), which suits binary-faithful round-trips and shell pipelines; its errors still use the uniform JSON error body above.

ソースに除去可能なコメントが含まれない場合、どちらのバリアントも 200 ステータスと空のペイロードで空の結果を通知します。JSON バリアントは "code": ""（空文字列）を返し、octet-stream バリアントは空のボディを返します。したがって、要求された Content-Type にかかわらずステータスコードとエンベロープの形は同一です。octet-stream バリアントは 204 No Content ではなく空の 200 ボディを返します。

3. Retrieve function spans

Returns the line span of every function in the submitted source.

リクエスト：

POST http://127.0.0.1:8080/v1/function

ペイロード：

{
  "id": "unique-id",
  "file_name": "filename.ext",
  "code": "source code with functions"
}

• id: a correlation identifier for the request. Optional (issue #645); omitting it defaults to an empty string (treated as “no correlation id”).
• file_name: the name of the file being analyzed.
• code: the source code with functions.

レスポンス：

{
  "id": "unique-id",
  "language": "cpp",
  "spans": [
    {
      "name": "function_name",
      "start_line": 1,
      "end_line": 10
    }
  ]
}

The envelope reports id, the detected language slug, and the spans result key. name is null when the parser could not resolve the function’s name from the AST (an anonymous or malformed definition). A null name is the malformed-span signal.

4. AST の取得

Returns bca’s JSON representation of the parsed syntax tree, as a recursive node tree. The dump normalizes some node kinds and flattens some constructs, including string literals.

リクエスト：

POST http://127.0.0.1:8080/v1/ast

ペイロード：

{
  "id": "unique-id",
  "file_name": "filename.ext",
  "code": "source code to parse",
  "comment": false,
  "span": true
}

• id: a correlation identifier for the request. Optional; omitting it defaults to an empty string (treated as “no correlation id”).
• file_name: the name of the file being analyzed.
• code: the source code to parse.
• comment: when true, comment nodes are omitted from the tree. Optional; defaults to false.
• span: when true, each node carries its source span; when false, span is null. Optional; defaults to false.

id、comment、span は省略可能で、デフォルトは上記のとおりです（issue #645）。file_name と code は必須です。未知のキーは 400 で拒否されます（issue #633）。

レスポンス：

{
  "id": "unique-id",
  "language": "rust",
  "root": {
    "type": "source_file",
    "value": "",
    "span": { "start_line": 1, "start_col": 1, "end_line": 2, "end_col": 1,
              "start_byte": 0, "end_byte": 13 },
    "field_name": null,
    "children": [
      {
        "type": "function_item",
        "value": "",
        "span": { "start_line": 1, "start_col": 1, "end_line": 1, "end_col": 13,
                  "start_byte": 0, "end_byte": 12 },
        "field_name": null,
        "children": [
          {
            "type": "identifier",
            "value": "main",
            "span": { "start_line": 1, "start_col": 4, "end_line": 1, "end_col": 8,
                      "start_byte": 3, "end_byte": 7 },
            "field_name": "name",
            "children": []
          }
        ]
      }
    ]
  }
}

The envelope reports id, the detected language slug, and root, the root AST node. Each node carries:

• type: tree-sitter 文法のノード種別です（文法固有です。どの文法が生成したかは language スラッグで分かります）。
• value: リーフ／名前付きトークンのソーステキストです（内部ノードでは空です）。
• span: a { start_line, start_col, end_line, end_col, start_byte, end_byte } object (lines and columns 1-based; byte offsets 0-based and half-open, indexing into the submitted code), or null when span was false. These span keys use the *_line vocabulary shared with /function and /metrics (issue #638 renamed the former *_row keys).
• field_name: the tree-sitter grammar field through which the parent reaches this node (name, left, body, and so on), or null for the root, anonymous tokens, and unfielded children.
• children: ノードの子ノードです（再帰的に続きます）。

Unlike the metric and function endpoints, the AST endpoint reports node coordinates over the exact bytes the client submitted: the source is not EOL-normalised, so spans line up with the client’s own copy (issue #640).

5. Compute metrics

Computes the maintainability metrics for the submitted source.

リクエスト：

POST http://127.0.0.1:8080/v1/metrics

ペイロード：

{
  "id": "unique-id",
  "file_name": "filename.ext",
  "code": "source code for metrics",
  "scope": "full"
}

• id: a correlation identifier for the request. Optional (issue #645); omitting it defaults to an empty string (treated as “no correlation id”).
• file_name: the filename of the source code file.
• code: the source code to analyze.
• scope: how much of the space tree to return. full (the default) returns the complete nested space tree: the file-level root plus a recursive spaces list for every function, class, and other unit. file returns only the file-level root with its spaces children cleared. This field replaces the pre-2.0 boolean unit flag (issue #638); sending the old unit key now fails with 400.

ペイロードは厳密に検証されます。認識されないキー（タイプミスや、削除済みの unit）は 400 と統一 JSON エラーボディで拒否され、問題のフィールド名が示されます（issue #633）。

application/octet-stream バリアントでは、ソースは生のリクエストボディで渡し、scope はクエリパラメータとして指定します（?file_name=…&scope=full）。パラメータを省略するとデフォルトの full になり、認識されない値は 400 で拒否されます。

レスポンス：

{
  "id": "unique-id",
  "language": "rust",
  "root": {
    "name": "sample.rs",
    "start_line": 1,
    "end_line": 7,
    "kind": "unit",
    "spaces": [
      {
        "name": "double",
        "start_line": 1,
        "end_line": 7,
        "kind": "function",
        "spaces": [],
        "metrics": {
          "cyclomatic": { "sum": 2, "average": 2.0, "min": 2, "max": 2 },
          "loc": { "sloc": 7, "ploc": 7, "lloc": 1, "cloc": 0, "blank": 0, "dloc": 0 },
          "nom": { "functions": 1, "closures": 0, "total": 1 }
        }
      }
    ],
    "metrics": { "...": "the same metric block, aggregated over the file" }
  }
}

The response envelope reports id, the detected language slug, and root, the single file-level space object (issue #638 renamed this key from the misleading plural spaces). root carries name (the request file_name), the start_line / end_line span, a kind discriminator (unit, function, class, …), its metrics block, and a recursive spaces list of child units. The example above is trimmed: each real metrics block contains every metric family (cyclomatic, cognitive, halstead, loc, nom, nargs, nexits, tokens, mi, abc, and, on the file root and container spaces, wmc, npm, and npa) with the same nested fields the bca CLI emits. When scope is file, root.spaces is an empty list.

The language value is the canonical lowercase slug (rust, cpp, csharp, tsx), the same token the language vocabulary accepts, not a human-pretty display name. Every analysis endpoint (/ast, /comment, /function, /metrics) reports this language field so clients can confirm which grammar was selected.

6. Server and library version

実行中のサーバーのバージョンと、そのビルドに使用された big-code-analysis ライブラリのバージョンを報告します。

リクエスト：

GET http://127.0.0.1:8080/v1/version

レスポンス：

{
  "server": "2.4.0",
  "library": "2.4.0"
}

7. Supported languages

対応言語と、登録されているファイル拡張子の一覧を返します。名前は正規の小文字スラッグです。一覧と拡張子はライブラリの言語テーブルから取得され、ハードコードされることはありません。

リクエスト：

GET http://127.0.0.1:8080/v1/languages

レスポンス：

{
  "languages": [
    { "name": "cpp", "extensions": ["cpp", "cc", "hpp", "..."] },
    { "name": "rust", "extensions": ["rs"] }
  ]
}

他のすべてのエンドポイントと同様に、/version と /languages は /v1 プレフィックスの下でのみ提供されます。プレフィックスなしの 1.x エイリアスは 2.0 で削除されました（API バージョニングを参照）。

8. ルートインデックス

Returns a machine-readable index of every registered route (its path, the HTTP methods it accepts, and a one-line description) so clients can discover the API surface without scraping this chapter. The index is generated from the same route table the server registers, so it cannot drift from the live routing.

リクエスト：

GET http://127.0.0.1:8080/v1

レスポンス：

{
  "service": "bca-web",
  "version": "2.4.0",
  "routes": [
    { "path": "/v1", "methods": ["GET", "HEAD"], "description": "This route index." },
    { "path": "/v1/metrics", "methods": ["POST"], "description": "Compute maintainability metrics for the source." }
  ]
}

service は常に bca-web です。version は GET /v1/version の server フィールドと一致します。以前のリリースでこのエンドポイントのエイリアスとして提供されていたプレフィックスなしのルート / は、2.0 で削除されました。

変更履歴（VCS）メトリクス

Three endpoints expose the change-history (version-control) metrics, the same numbers bca vcs computes from the CLI. Unlike every other endpoint, these analyse a git repository already present on the server’s filesystem rather than source code carried in the request body: VCS metrics derive from commit history, which has no in-request representation.

Operator warning: repo_path is a trust boundary. The repo_path field is a server-side filesystem path. These endpoints make the server walk any git repository it can read and return that repository’s relative file paths, churn, and author signals. This is materially different from the source-in-body endpoints, which only ever see code the client sends. The optional cache_dir field is a second caller-supplied server-side path that grants a write capability: with caching enabled (the default), the server creates directories and writes JSON cache files under it (<cache_dir>/<repo>/<head_sha>.json), so a caller controlling cache_dir can direct the server to write cache files at any path the server process can write to. (cache_dir is accepted only by /vcs; /vcs/trend and /vcs/jit do not cache.) The endpoint’s filesystem reach is therefore an arbitrary read of any readable git repository and an arbitrary write of cache files under any writable path. Do not expose /vcs, /vcs/trend, or /vcs/jit to untrusted clients without an authorization layer in front of bca-web. The default 127.0.0.1 bind keeps them local. Each walk runs under the same parse-timeout and blocking-pool guard as the analysis endpoints.

All three endpoints are POST-only, accept application/json, echo the request id, and report errors with the uniform {error, error_kind, id} body; its error_kind tokens are the vcs_* family (vcs_not_a_repository, vcs_invalid_window, and so on). A client mistake is a 400: a repo_path that does not exist or is not a git working tree (both carry vcs_not_a_repository), an unresolvable ref/commit, a malformed or non-diff diff, an unusable author_hash_key (vcs_invalid_author_hash_key), or a malformed window / timestamp / formula / file-type / threshold / trend parameter. A failure of the history walk itself is a 500. A nonexistent repo_path is a typo, the most common client error here, so it answers 400 like a path that exists but is not a repository, not a 500 (issue 653).

9. Rank files by risk: /vcs

リポジトリの履歴を一度だけ走査し、複合リスクスコアでランク付けしたファイル一覧を返します（issue #328）。

リクエスト：

POST http://127.0.0.1:8080/v1/vcs

ペイロード：

{
  "id": "unique-id",
  "repo_path": "/srv/repos/my-project"
}

repo_path is required; every other field is optional and defaults to the bca vcs default. id is optional too (issue #645); omitting it defaults to an empty string, echoed back unchanged. The optional fields are:

• long_window / recent_window: window specs such as 12mo or 90d. Defaults 12mo / 90d.
• top: リスク上位 N 件のファイルのみを保持します。未指定の場合のデフォルトは 50（bca vcs --top のデフォルト）で、明示的に 0 を指定するとすべてのファイルを返します。
• ref: 解析対象のリビジョンです（デフォルトは HEAD）。
• risk_formula: weighted（デフォルト）または percentile です。
• file_types: metrics (default: only files bca has metrics for), all (every tracked text file), or a comma-separated extension allow-list (rs,py).
• full_history: 第一親のみではなく、完全な DAG を走査します。
• include_merges: マージコミットを含めます。
• follow_renames: リネームを追跡します（デフォルト true）。
• exclude_bots: ボットの識別情報を除外します（デフォルト true）。
• bot_pattern: ボット作者を除外する正規表現を上書きします。
• as_of: reference “now” (RFC 3339 / @unix / git date) for snapshots.
• emit_author_details: SHA-256 でハッシュ化した作者の識別情報を出力します。
• author_hash_key: emit_author_details を鍵付き HMAC-SHA256 に強化する秘密鍵です（emit_author_details が必要です。空の鍵、またはフラグなしでの指定は 400 になります）。
• include_deleted: 対象の ref で削除済みのファイルを含めます。
• bus_factor_threshold: (0, 1) の範囲で指定するバスファクターのカバレッジしきい値です（デフォルト 0.5）。
• no_cache: このリクエストで永続的な変更履歴キャッシュを無効にします（デフォルト false）。
• cache_dir: サーバー側のキャッシュディレクトリを上書きします。

レスポンス：

{
  "id": "unique-id",
  "vcs_schema_version": 2,
  "risk_score_version": 2,
  "long_window_days": 365,
  "recent_window_days": 90,
  "truncated_shallow_clone": false,
  "vcs_aggregate": { "...": "directory- / repo-level bus factor" },
  "files": [
    {
      "path": "src/main.rs",
      "vcs": {
        "commits_long": 12,
        "commits_recent": 3,
        "churn_long": 540,
        "churn_recent": 80,
        "authors_long": 4,
        "authors_recent": 2,
        "risk_score": 1.42
      }
    }
  ]
}

files は vcs.risk_score の降順に並びます。各エントリはリポジトリ相対の path と、入れ子の vcs メトリクスブロック（bca vcs が出力するものと同じ形式、issue #684）を持ちます。含まれるのは、長期・直近ウィンドウでのコミット数とチャーン数、作者数、所有権シェア、バースト、バグ修正 / セキュリティ修正 / リバートの各カウント、経過期間、変更エントロピーと共変更エントロピー、そして合成値の risk_score です。hotspot_score とハッシュ化された author_ids は、計算可能な場合 / 要求された場合にのみそのブロック内に現れます。4 つの定数スタンプ vcs_schema_version、risk_score_version、long_window_days、recent_window_days はトップレベルに一度だけ置かれ、行ごとには現れません（issue #635）。vcs_aggregate はディレクトリレベルおよびリポジトリレベルのバスファクターを持ちます（issue #332）。

10. Historical trend: /vcs/trend

変更履歴メトリクスを等間隔の複数時点でサンプリングし、ファイルごとの時系列を返します（issue #333）。応答はランク付けされたスナップショットではなく系列であるため、/vcs とは別のルートになっています。

リクエスト：

POST http://127.0.0.1:8080/v1/vcs/trend

Payload: every /vcs field above except the cache controls (no_cache / cache_dir), plus the three below. Trend does not use the persistent cache, so sending either cache field is a 400 (issue #961) rather than a silent no-op.

• points: 等間隔のサンプル点の数（>= 2）。省略時は 12（bca vcs trend --points のデフォルト）になります。
• span: サンプル点全体がカバーする遡及期間（デフォルト 12mo）。
• top_deltas: 改善 / 悪化それぞれのリストに載せる上位 N ファイル数。未指定の場合は 10、明示的な 0 は全件を返します。

レスポンス：

{
  "id": "unique-id",
  "trend_schema_version": 1,
  "vcs_schema_version": 2,
  "risk_score_version": 2,
  "long_window_days": 365,
  "recent_window_days": 90,
  "truncated_shallow_clone": false,
  "as_of_points": [1704067200, 1711929600],
  "files": {
    "src/main.rs": [ { "as_of": 1704067200, "vcs": { "risk_score": 1.1 } }, null ]
  },
  "deltas": { "improved": [], "regressed": [] }
}

as_of_points はサンプル時刻を古い順に列挙します。files 内の各ファイルの配列はこれと 1:1 で対応し、その時点でファイルがまだ存在しなかった場合は null 要素になります。存在する各要素は { "as_of": ..., "vcs": { ... } } の形で、その時点のそのファイルの VCS ブロックが vcs の下に入れ子になります（issue #684）。4 つの定数スタンプはトップレベルに一度だけ置かれ、時点ごとには現れません（issue #635）。deltas は、系列全体でのリスクスコアの変動に基づいて、最も改善したファイルと最も悪化したファイルをランク付けします。

11. Just-in-time risk: /vcs/jit

Scores the just-in-time risk of a single change: either one commit on a server-side repository, or an arbitrary unified diff carried in the request body (issues #331 / #580). The two modes are mutually exclusive.

コミットモードは repo_path 上のコミットをスコアリングします:

{
  "id": "unique-id",
  "repo_path": "/srv/repos/my-project",
  "commit": "HEAD"
}

コミットモードは、経験ウィンドウを調整する long_window、recent_window、full_history、include_merges、follow_renames、as_of も受け付けます。応答は source が "commit" の完全なレポートで、その risk_score は 5 つの特徴グループ（サイズ、拡散、履歴、経験、目的）すべてを織り込みます:

{
  "id": "unique-id",
  "jit_schema_version": 3,
  "jit_score_version": 1,
  "source": "commit",
  "long_window_days": 365,
  "recent_window_days": 90,
  "risk_score": 0.87,
  "commit": { "id": "…", "parent_count": 1, "is_merge": false, "purpose": {} },
  "features": { "size": {}, "diffusion": {}, "history": {}, "experience": {} },
  "contributions": { "size": 0.4, "diffusion": 0.2, "history": 0.1, "purpose": 0.0, "experience": -0.1 }
}

diff モードはリポジトリなしで任意の unified diff をスコアリングします:

{
  "id": "unique-id",
  "diff": "--- a/x\n+++ b/x\n@@ -1 +1 @@\n-old\n+new\n"
}

A bare diff carries no author, parent, or history, so only the size and diffusion groups are computable. The diff report’s source is "diff" and it reports partial_risk_score, not risk_score, because the missing groups are absent from the body entirely, never present as zero:

{
  "id": "unique-id",
  "jit_schema_version": 3,
  "jit_score_version": 1,
  "source": "diff",
  "partial_risk_score": 0.6,
  "size": {},
  "diffusion": {},
  "contributions": { "size": 0.4, "diffusion": 0.2 }
}

Branch on the source discriminator ("commit" vs "diff") to read the right score field. partial_risk_score sums only the size and diffusion contributions, while a commit’s risk_score also folds in history, purpose, and the negatively signed experience group, so the two are neither ordered nor on the same scale: rank diffs against other diffs, never against commit scores.

Mode conflict. Supplying diff together with any commit-mode field (repo_path, commit, a window, history, rename, or as_of knob) is rejected with a 400 rather than silently honouring the diff and dropping the rest. The two modes answer different, non-comparable questions, so the combination is treated as a client mistake (issue number 632).

Non-diff diff. A diff value that is not a git unified diff (the wrong field, an accidentally-mangled string, arbitrary text) is rejected with a 400 (vcs_invalid_diff) rather than scored as a confident partial_risk_score of 0.0. On a risk-gating endpoint a spurious “zero risk” is the most dangerous failure mode, so non-diff input is a hard error (issue 652). An empty or whitespace-only diff is the one exception: it legitimately means “no changes”, so it still returns a valid 0.0, and a CI step that computed an empty diff gets the zero-risk answer it expects.

bca-web の運用

bca-web は big-code-analysis ライブラリをラップする HTTP デーモンで、コメント除去、関数スパン、AST ダンプ、保守性メトリクス、変更履歴（VCS）メトリクスを REST API として公開します。このページはデーモンを運用するオペレーター向けに、ビルドと起動の方法、チューニングに使うフラグと環境変数、そして公開前に守るべき信頼境界を説明します。

Use the REST API reference for request and response fields, and Driving the REST API for complete curl examples. This page covers the process itself and links to those two rather than repeating them.

ビルドと実行

bca-web は big-code-analysis-web クレートのバイナリです。チェックアウトからは Cargo 経由で実行します:

cargo run -p big-code-analysis-web -- --host 127.0.0.1 --port 8080

バイナリを PATH 上に置くには、リリースアーティファクトをビルドしてコピーするか、クレートからインストールします:

cargo install big-code-analysis-web   # `bca-web` コマンドをインストールします
bca-web --host 127.0.0.1 --port 8080

bca-web は指定されたアドレスにバインドし、中断されるまでサービスを提供します。ポートをバインドできない場合や I/O エラーに遭遇した場合は非ゼロで終了するため、スーパーバイザー（systemd、コンテナオーケストレーター、CI のスモークチェック）が失敗を検知して再起動や警告を行えます。

言語のサブセットでのビルドは機能しません

The shipped bca-web binary compiles every supported tree-sitter grammar in. The big-code-analysis-web crate pins the library’s all-languages feature set explicitly, so passing --no-default-features or a custom --features list to cargo build -p big-code-analysis-web does not drop grammars from the resulting binary. Dropping a grammar silently from a user-facing daemon would surface as “language X stopped working” at request time rather than as a build error, so the crate forbids it (issue #252).

文法セットを削減する必要がある場合は、自分の Rust コードに big-code-analysis ライブラリを組み込み、自分の Cargo.toml でフィーチャを選択してください。言語別 Cargo フィーチャの章に、すべてのフィーチャと実際の例が載っています。

コマンドラインフラグ

デフォルト値付きの全フラグ一覧:

--num-jobs auto is cgroup-quota- and cpuset-aware on Linux: in a container with a CPU quota it resolves to the quota rather than the host’s physical core count, matching the bca CLI’s --num-jobs. This count sizes the worker pool and the parse-admission semaphore, so it caps how many parses run concurrently. The minimum is 1; 0 is rejected when the flag is parsed.

--parse-timeout-secs は、リクエストが 504 Gateway Timeout を返すまでに 1 回のパースが実行できる時間を制限します。デフォルトの 30 は、病的な入力がワーカーを無期限に塞ぐことを防ぎます。0 に設定すると期限がなくなり、それとともに後述の負荷制御も無効になります。無制限のパースが許容できる場合にのみ 0 を使ってください。タイムアウト時に返されるレスポンスボディは REST API リファレンスを参照してください。

CORS is off by default. The CORS section of the reference documents it in full, covering preflight handling, the wildcard form, and the absence of credentials. The short version: pass --cors with an explicit origin allow-list to let browser tooling read responses; omit it to emit no Access-Control-* headers at all.

環境変数

RUST_LOG は EnvFilter の構文を使います（例: RUST_LOG=big_code_analysis_web=debug）。デーモンは完了したリクエストごとに、メソッド、ルート、ステータス、レイテンシを含むアクセスログを 1 行出力します。

リソース制限とバックプレッシャー

単一のクライアントによるリソース枯渇からデーモンを守る制限が 2 つあります。

リクエストボディサイズ。 すべてのエンドポイントは、4 MiB を超えるリクエストボディを 413 Payload Too Large で拒否します。この制限は JSON と raw オクテットストリームのコンテンツタイプに一律に適用されるため、どちらも同じしきい値で過大なボディを拒否します。

Orphaned-task admission control. When a parse exceeds --parse-timeout-secs, the request returns 504, but the blocking thread keeps running on the pool until the parse finishes on its own, because tree-sitter cannot be interrupted mid-parse. To stop sustained pathological input from piling up unbounded background work, new requests are rejected with 503 Service Unavailable once the count of orphaned tasks reaches a soft cap. The cap defaults to max(num_jobs * 2, 4); BCA_MAX_ORPHANED_TASKS overrides it (parsed as an unsigned integer; an invalid or zero value falls back to the default). Setting --parse-timeout-secs 0 disables this mechanism entirely, since with no deadline no task is ever orphaned.

セキュリティと信頼境界

bca-web 自体には認証、認可、レート制限がありません。デフォルト値はローカルの単一オペレーター運用向けに選ばれています。広げる場合は意図的に行ってください。

デフォルトのバインド先はループバックです。 サーバーは --host で指定しない限り 127.0.0.1 にバインドします。ネットワークに公開する前は、そのままにしておくか、前段に認証プロキシを置いてください。0.0.0.0 にバインドすると、ポートに到達できる誰もが以下のすべての機能に到達できるようになります。

CORS はデフォルトで無効です。 --cors フラグがなければ、別オリジンのブラウザースクリプトは API レスポンスを読めないため、オペレーターがたまたま訪れたページがループバックの bca-web をこっそり操作することはできません。ワイルドカード形式（--cors '*'）はすべてのオリジンに応答し、サーバーのメトリクスやリポジトリパスを任意のサイトに公開するため、信頼できるネットワークでのみ使ってください。完全なセマンティクスは CORS にあります。

VCS エンドポイントはサーバー側のリポジトリを読み取ります。 ソースコードをボディで受け取るエンドポイントと異なり、/v1/vcs、/v1/vcs/trend、/v1/vcs/jit は、リクエストの repo_path で指定される、サーバーのファイルシステム上に既にある git リポジトリを解析します。これらのエンドポイントに到達できる呼び出し元は、サーバーが読み取れる任意の git リポジトリをサーバーに走査させ、そのリポジトリのファイルパス、チャーン、作者シグナルを知ることができます。リファレンスの VCS 信頼境界の警告がこれを完全に扱っています。認可レイヤーなしで、信頼できないクライアントにこれらのエンドポイントを公開しないでください。

VCS キャッシュディレクトリはクライアントが制御する書き込みパスです。 VCS エンドポイントはオプションの cache_dir フィールドを受け付け、永続的な変更履歴キャッシュの書き込み先を上書きできます。デフォルトはプラットフォームのキャッシュ位置（$XDG_CACHE_HOME/big-code-analysis/vcs）です。cache_dir を設定できる呼び出し元は、サーバープロセスが書き込むディレクトリを選べるため、信頼できないクライアントは攻撃者が選んだパスにキャッシュ書き込みを向けられます。これも、VCS エンドポイントを認可レイヤーの背後に置き、信頼できない入力に決して開放してはならない理由の 1 つです。

レシピ

bca と bca-web で作業を進めるためのタスク指向の例です。各レシピは、バイナリがビルド済み（cargo build --release）で、bca が PATH 上にあることを前提とします。

レシピは目的別にまとめられています:

• Quality reports: generate Markdown reports for pull requests, dashboards, or wikis, including the C/C++ preprocessor-aware workflow.
• CI integration: wire bca check and bca report into GitHub Actions and GitLab CI, including the baseline / ratchet pattern and the Code Quality widget path.
• Baselines: record existing offenders in a .bca-baseline.toml so the gate only fires on new or worsened violations, and audit or diff that baseline during review.
• Local threshold gates: mirror the CI threshold gate on a developer machine with a two-tier (hard + headroom) Makefile / just / pre-commit pattern, so regressions never reach the pull request.
• Choosing thresholds: learn where the shipped defaults come from, choose language-specific overrides, and select limits for CI, agent feedback, legacy triage, or safety-critical work.
• Feeding metrics to an agent: wire bca check into an agentic coding tool’s after-edit feedback loop (Claude Code PostToolUse hook, OpenCode plugin), with the anti-gaming guidance that keeps the loop honest.
• AST queries: search for syntactic constructs, count node types, dump trees, and detect parse errors.
• Exporting metric data: emit structured output (JSON / YAML / TOML / CBOR) and consume it from shell pipelines.
• Driving the REST API: run the HTTP server and call every endpoint with curl.