Measuring what is there¶

Two subcommands report what the analyzer found. Neither decides anything. The exit status is zero whatever the counts say, since gating is what the analyzer and a baseline are for.

Command	Unit	Answers
`declscope survey [packages]`	package	Which package do I open first?
`declscope inspect <package>`	namespace, crossing	What shape is this package in?

$ declscope survey -config .declscope-strict.yaml ./internal/measure/...
## Checks in force

| check      | value                                                   | packages |
| ---------- | ------------------------------------------------------- | -------: |
| config     | `.declscope-strict.yaml`                                |        1 |
| rules      | boundary on, qualify ondemand, exported, surplus strict |        1 |
| type check | 1 package ok, 0 failed                                  |          |

## Findings

| rule        | found | ignored | baselined | reported |
| ----------- | ----: | ------: | --------: | -------: |
| `boundary`  |     0 |       0 |         0 |        0 |
| `qualify`   |     0 |       0 |         0 |        0 |
| `surplus`   |     0 |       0 |         0 |        0 |
| `directive` |     0 |       0 |         - |        0 |
| `filter`    |     0 |       0 |         - |        0 |

## Packages — boundary

| package                                      | reported | baselined | declared | largest crossing                 |
| -------------------------------------------- | -------: | --------: | -------: | -------------------------------- |
| `github.com/mpyw/declscope/internal/measure` |        0 |         0 |       20 | markdown → cell (7 declarations) |

That is one package of this repository. A codebase adopting declscope has numbers in the first two columns, and a row per package.

The state of the checks comes first, because a count means nothing without it. A zero from a rule that was off, a package that did not compile, or a baseline that absorbed everything looks like a zero from clean code.
A rule prints - rather than 0 where it was not asked. It may be switched off, or it may stand itself down, as surplus does for a package with a file it cannot read.
A package that does not type-check stops the run. -allow-errors continues and names it under type check.
Rows are ordered by how much is outstanding: undecided, reported and baselined together. largest crossing names where it is concentrated.

Tip

Look for the row with nothing reported, much baselined and nothing declared. Nothing was decided there, everything was deferred, and the analyzer alone calls it clean.

$ declscope inspect -config .declscope-strict.yaml ./internal/measure
## Crossings

| crossing          | mutual | declared | baselined | reported | clears |  reached | uses |
| ----------------- | -----: | -------: | --------: | -------: | -----: | -------: | ---: |
| markdown → cell   |        |        7 |         0 |        0 |      0 |  7 of 10 |   15 |
| markdown → sink   |        |        5 |         0 |        0 |      0 |  5 of 17 |   28 |
| golden → (core)   |        |        4 |         0 |        0 |      0 |  4 of 78 |    9 |
| format → json     |        |        2 |         0 |        0 |      0 | 2 of 105 |    2 |

114 declarations are further: open, package-scoped by default rather than by decision, so left out of the table and of the diagram.

Declarations crossed: 0 reported, 0 baselined, 20 declared.

One row per directed edge, so a mutual pair is two rows. clears is the number the decision turns on: how many findings would go away if the two namespaces became one.

Both commands take -test=false. On a large package it changes the picture. In net/http the heaviest crossing is export_test.go reaching the transport internals, which is what that file is for.

The other columns, and the formats

Column	What it says
`clears`	Findings that would go away if these two namespaces merged. A declaration a third namespace also reaches survives the merge, so a heavy crossing can clear much less than it reaches
`reached`	Declarations of the reached namespace this edge touches, over every declaration it holds. `12 of 19` says the second namespace holds the working parts of the first. Open crossings are counted under the table, not in the rows
`declared` / `baselined` / `reported`	Declarations on this edge, by what became of each. A declaration reached from two namespaces is two rows and one finding, so these sum to more than the rule found. The line under the table gives the rule's own count, which is the survey's
`saturation`, in the `Qualify` table	How much of a namespace the naming rule is unsatisfied by. Near the top, the namespace name is usually what is wrong

`-format`	For
`markdown` (default)	A terminal and an issue or pull request. Cells are padded, so the output aligns in both. `inspect` adds a Mermaid diagram
`json`	An agent, and anything scripted

There is no third format. A plain-text renderer beside this one caused most of the defects found in review, and one renderer cannot disagree with itself.

The JSON carries four arrays.

Array	Holds
`edges`, `names`	One flat row each
`crossings`	The fold the crossing table prints, `clears` included
`namespaces`	The denominators every ratio divides by

findings carries the same asked flag the tables print a dash for. Markdown is a rendering of the same data.

Neither command asks the analyzer's questions a second way. Both walk the same findings through the same entry point, and add only the outcome: reported, baselined, silenced by a directive, or never asked.