bonsai-lint --domain web                       # one declared domain only
bonsai-lint --baseline PATH .                  # one baseline file for the whole repo, wherever you choose
bonsai-lint --config packages/web src/         # discover config from here, not from the first path
bonsai-lint --no-toplevel src/                 # skip code outside any function
bonsai-lint --stdin --stdin-path src/a.php < buffer   # score an unsaved buffer as that file
bonsai-lint --jobs 4 .                         # cap the workers; 0 or absent uses every core
bonsai-lint --allow-no-files a.d.ts gen.go     # pass when none of the paths can be scored

bonsai-lint --format json .

{
  "thresholds": {
    "go": 15,
    "java": 15,
    "php": 15,
    "python": 15,
    "typescript": 15,
    "vue": 15
  },
  "breaches": 3,
  "findings": [
    {
      "path": "packages/billing/src/invoice-mapper.service.ts",
      "line": 47,
      "name": "InvoiceMapperService::mapLineItems",
      "score": 69,
      "language": "typescript",
      "domain": "root"
    },
    {
      "path": "services/api/src/Controller/CheckoutController.php",
      "line": 207,
      "name": "CheckoutController::applyDiscounts",
      "score": 25,
      "language": "php",
      "domain": "root"
    },
    {
      "path": "packages/web/src/parser/lexer.js",
      "line": 19,
      "name": "Lexer",
      "score": 22,
      "language": "typescript",
      "domain": "root"
    }
  ]
}

findings is already ranked, worst first, so a consumer does not have to sort it. thresholds is keyed by language id and reports what the scan actually applied, which is the domain's threshold rather than the root's when the scan was scoped to one. breaches counts the findings over that threshold, and is what the exit code follows; with --all the array also carries everything under it, and breaches still counts only the ones that failed.

domain names the domain a file resolved to — root when there is no bonsai-lint.toml declaring any — and path is always forward-slashed, so a report generated on Windows compares against one generated in CI.

The language id is what --lang, --over LANG=N and a [section] in the config take, so typescript covers every JavaScript and TypeScript file however it is parsed. An id that is not one of these is an error, not a silent no-op.

.js is parsed with the TypeScript grammar, which accepts a superset of JavaScript. Flow annotations are the one thing this misparses.

A declaration file and a minified one are both skipped outright, for opposite reasons: the first holds only signatures so every unit scores zero, and the second is generated output whose whole body rolls up into one unit nobody will refactor. The skipped names are whole suffixes, listed by the TypeScript and TSX descriptors' unscored_suffixes, so app.mini.js, jasmine.js and a file simply called min.js are all still scanned.

A .vue file scores its <script> and <script setup> blocks, with lang="ts" choosing the TypeScript grammar and anything else (including no lang) choosing the JSX-capable one, which is the grammar .js already uses. Each block is parsed on its own, and their file-level code is added together into the one <toplevel> a component reports. Reported lines are lines in the .vue file, so editing a template moves a finding without changing its baseline key.

Two consequences are worth knowing:

• The template is deliberately not scored. A v-if chain is real branching, but the the metric is defined over script code, and counting a template would make a component incomparable with the same logic written in TypeScript. A render() function is scored, because it is ordinary script code, so moving logic out of a template and into render() makes it visible, and a component that never had a template was never hidden.
• A src= block belongs to the file it points at. That file is scored as typescript, so a [vue] threshold does not reach it.

A Python method is keyed by its class, OrderService::process. A property's getter, setter and deleter redefine one name on purpose, so the accessor a decorator declares joins the key: Cart::total, Cart::total.setter and Cart::total.deleter are baselined apart. A def whose body is only ..., such as an @overload stub or a protocol method, declares a signature and is not a unit. A .py file is skipped as generated by the same header rule as Java below, which covers protobuf, gRPC and Thrift output. A Django migration says only "Generated by Django", because it is meant to be edited, so it stays scored.

Java overloads freely, so a Java method or constructor is keyed by its parameter types as well as its name: OrderService::process(Order, User). Each type is its simple name, without type arguments or annotations, so two overloads are baselined apart and switching between an import and a qualified name never re-keys one. Java has no single generated-code convention, so a .java file is skipped when the comments before its first line of code say both "generated" and "do not edit". That covers protobuf, Thrift, Avro and JavaCC output. Most generated sources sit in a gitignored target/ or build/ directory and are never scanned in the first place.

Go marks generated code in the file rather than its name, so a .go file is read first and then turned away if a // Code generated … DO NOT EDIT. line comes before its package clause, which is the convention the Go toolchain itself follows. Such a file is neither scored nor counted, on disk and through --stdin alike. vendor/ and testdata/ get no special treatment: if a repository commits them, exclude = ["vendor/**", "**/testdata/**"] keeps them out.

A Go method is keyed by its receiver type, so func (s *Stack[T]) Push() reports as Stack::Push and keeps its baseline entry when the receiver switches between pointer and value.

foreach ($orders as $order) {          //  +1
    if ($order->isActive()) {          //  +2
        array_map(function ($item) {   //  +0, nesting is now 3
            if ($item->qty > 0) {      //  +4
                return $item->qty > 10 ? 'bulk' : 'single';   // +5

  12  backend/Orders.php:3   OrderRepository::syncLineItems
  12  frontend/orders.ts:1   syncLineItems

Identical logic, identical number. That is what makes one threshold meaningful across a monorepo.

A misspelt key is an error rather than a silent default, named with a suggestion when one is close, and so is a negated glob: !pattern is not supported.

Add domains and each team owns its own thresholds and its own baseline, without editing a shared file. The root declares where domains may live, so a stray config cannot quietly create one.

# bonsai-lint.toml at the repository root
domains   = ["packages/*", "services/*"]
threshold = 15

# packages/web/bonsai-lint.toml
name      = "web"
threshold = 20

packages/web/.bonsai-lint-baseline.json       # each domain keeps its own
services/billing/.bonsai-lint-baseline.json

--write-baseline then writes one file per domain and prints what it wrote, or says that there was nothing to record. Baseline keys are relative to the domain root, so they survive being checked out anywhere, on any platform. A domain's own exclude is relative to its root too; the root's applies everywhere.

--baseline PATH keeps every domain in one file of your choosing instead. Its keys are relative to the repository root, so two domains with a src/index.ts cannot collide. Which to use is your call: one file is simpler for a small repository, while per-domain files stay short and put each team's accepted debt in the directory that team owns.

Wherever you point the CLI, the workspace is the same one. Discovery walks up from the first scanned path and takes the outermost bonsai-lint.toml that declares domains as the root, so bonsai-lint packages/web applies the same root excludes, inherited thresholds and domain list as bonsai-lint ., and so does an editor buffer. Without a domains declaration anywhere, the nearest config is the root. --config PATH starts the walk somewhere else.

bonsai-lint --write-baseline src/

Records everything currently above the threshold as accepted. Later runs fail only on scores that got worse, or on units the baseline has never seen. An unknown key is treated as a regression, never as an acceptance. A renamed function is reported rather than silently inheriting someone else's amnesty. Two units in one file that share a key, such as a def redefined under if/else, share one entry holding the higher score. Entries that match nothing are reported too, so a baseline cannot quietly rot into a permanent exemption, but only by a scan that covered the whole domain, so a single file from a pre-commit hook or an editor buffer never cries stale.

Without a bonsai-lint.toml, the directory holding the baseline is the project root, so bonsai-lint --write-baseline . followed by bonsai-lint src/Foo.php finds the same entries.

// bonsai-lint-ignore: hand-tuned state machine, splitting it hurts more than it helps
function parse(string $input): Ast { /* ... */ }

Works above the declaration, inside the docblock, or trailing the signature line, in every supported language. In Python it goes in a # comment above the def or its decorators: a docstring is a string inside the body, not a comment, so it cannot carry a marker. It works for a bound function too, such as const handler = () => {}, Python's handler = lambda e: …, a Java field Runnable handler = () -> {}, $handler = function () {} or Go's var handler = func() {}, even when a call wraps it, as in const useCart = defineStore('cart', () => {}). A marker after a closing brace on its own line belongs to nobody. A marker without a reason is refused, reported on stderr, and the finding stands. Suppression hides a finding but never changes a score, and --all always shows the real number.

A <toplevel> finding is reported on line 1, so its marker goes in the comment block at the top of the file: on the first line of a script, behind a shebang if there is one; in Python, behind a shebang or coding line and above the module docstring; just above or trailing the package line in Java or Go; or trailing <?php, or in the file's docblock, in PHP. One comment silences one unit, so a marker directly above the first function is that function's; write it on the package or <?php line to address the file instead.

Most complexity tools only score functions and methods, so a 200-line procedural template, a route table or a module-level bootstrap is invisible to them. bonsai-lint scores whatever is left over as a <toplevel> unit, one per file:

  84  services/api/templates/report/summary.php:1  <toplevel>
  37  services/api/scripts/migrate-tenants.php:1  <toplevel>

Files with no top-level logic report nothing, so this costs you no noise. Turn it off with --no-toplevel or toplevel = false.

Numbers from bonsai-lint will not always match another implementation. Every difference is a deliberate choice, and this is all of them, so you can judge which suits you:

The last three rows are limits rather than preferences: recursion is recognised by syntax alone, with no scope or type analysis.

The first row moves numbers the most. Scoring every function from zero means a pyramid of callbacks costs almost nothing:

if (a) { for (const x of xs) { xs.forEach(item => { if (b) { … } }); } }

bonsai-lint reports that as a single unit scoring 7. Scored per function it is two units, at 3 and 1. Neither is wrong. They answer different questions. Per-function tells you how hard each piece is on its own; bonsai-lint tells you how hard the whole thing is to read where it stands. If you care about callback depth, the second is the more useful number.

Migrating? Expect your numbers to move, mostly upward, for these reasons and no others.