Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1835,7 +1835,7 @@ and requires stdout, stderr and exit code to match on each. The gate count above
are the dated counts snapshot in `docs/counts.tsv` (`python3 docs/counts_snapshot.py show` prints today's
numbers beside it), so two open changes that each add a gate or a cap never conflict on a total.

Another gate derives the cap inventory. At the counts snapshot 2026-11-22 the tool had 454 compile-time caps and 10 ranking parameters.
Another gate derives the cap inventory. At the counts snapshot 2026-11-22 the tool had 456 compile-time caps and 10 ranking parameters.
[`docs/LIMITS.md`](docs/LIMITS.md) lists each cap, its value, and whether the file discloses a truncation
when the cap fires, and `python3 docs/limits_build.py --check` proves that list against `src/`.
[`docs/TUNING.md`](docs/TUNING.md) lists the measured cost of the caps the sweep has measured, and names
Expand Down
4 changes: 2 additions & 2 deletions docs/COMMANDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3828,7 +3828,7 @@ $ ./build/ripwire . --whereis=rankGraphTeleport --whereis-listing=all

**Answers:** the dark-content dashboard: what is built but switched OFF in this repo the dark-content dashboard: what is BUILT but OFF in this repo.

Harvests all three gate patterns — #ifndef/#define header gates, CMake option(), and getenv() reads — and reports gate, kind (compile/cmake/env), default, the size of the code it guards (#if regions and their LOC), and its read sites. When a name is BOTH a header gate and a CMake option the CMake default WINS (that is what the build actually passes) and both sites are listed. A gate whose default IS another gate's name (#define F_WALLS F_ALL) is resolved: it inherits the master's default and rolls its guarded size up, so a master switch shows <aliases n=..> rather than a misleading loc="0". LIMITS: lexical, not preprocessed — a gate computed at configure time or set only in a CI script shows its in-repo default, never the value your build used. A gate needs a VALUE (#ifndef F / #define F 0) to be a gate: valueless pairs are include guards and are excluded, and a gate read as a VALUE (constexpr bool k = F != 0, then if constexpr) reports regions="0" honestly — its code is a C++ branch, not an #if region. Pair it with --flip=NAME below to size ONE gate instead of listing them all. BASH: in .sh/.bash/.zsh every $X / ${X...} expansion is an env read unless the same file assigned X before it (X=, export X=, local/declare/readonly, read, for, mapfile, getopts, printf -v, ((X=…)); read/select/getopts/mapfile also set REPLY/OPTARG/ MAPFILE). An assignment takes effect where its command ends; a prefix X=v cmd is not a write; a function's local/declare (and any later write of that name in it) hides reads only to that function's end, a write inside $( ) or ( ) only to that subshell's end, and a write in a pipeline component or a background job (cmd | read X, X=1 &, a piped while loop) nothing past its command (after shopt -s lastpipe the pipeline's last command runs in the script itself). Each read row carries form= (required ${X:?}/${X?}, default ${X:-d}, unset-default ${X-d}, settest ${X:+w}/${X+w} or a -n/-z operand of [ / [[ / test, assign ${X:=d}, plain $X), colon=1|0 (does an EMPTY value count as unset), default= the literal word, and test=n|z; write rows list the name's assignments repo-wide; ambient="1" tags a name Bash or the login always sets (PWD, HOME, BASH_SOURCE, RANDOM and the like). A shell file whose header is a GENERATED/DO-NOT-EDIT banner is skipped (generated_skipped=N). Bash LIMITS: lexical order within one file, no flow — a name set only by eval, by printf -v "$1", in a function defined below the read, or in a sourced file still reads as external (the write rows let a consumer that follows source join them). An expansion nested more than 32 deep in another's word is not read past that depth, and the root counts such files (nesting_cut=N). A file --flags cannot open or read to its end is counted as unreadable=N on the root: every count is then a floor. .zsh files are read with Bash's rules (no zsh-only expansion flags), and a script with no .sh/.bash/.zsh extension (a bare #!/bin/bash file) is not scanned. --flags --json emits the same rows as JSON (raise --limit to lift the site cap).
Harvests all three gate patterns — #ifndef/#define header gates, CMake option(), and getenv() reads — and reports gate, kind (compile/cmake/env), default, the size of the code it guards (#if regions and their LOC), and its read sites. When a name is BOTH a header gate and a CMake option the CMake default WINS (that is what the build actually passes) and both sites are listed. A gate whose default IS another gate's name (#define F_WALLS F_ALL) is resolved: it inherits the master's default and rolls its guarded size up, so a master switch shows <aliases n=..> rather than a misleading loc="0". LIMITS: lexical, not preprocessed — a gate computed at configure time or set only in a CI script shows its in-repo default, never the value your build used. A gate needs a VALUE (#ifndef F / #define F 0) to be a gate: valueless pairs are include guards and are excluded, and a gate read as a VALUE (constexpr bool k = F != 0, then if constexpr) reports regions="0" honestly — its code is a C++ branch, not an #if region. Pair it with --flip=NAME below to size ONE gate instead of listing them all. BASH: in .sh/.bash/.zsh every $X / ${X...} expansion is an env read unless the same file assigned X before it (X=, export X=, local/declare/readonly, read, for, mapfile, getopts, printf -v, ((X=…)); read/select/getopts/mapfile also set REPLY/OPTARG/ MAPFILE). An assignment takes effect where its command ends; a prefix X=v cmd is not a write; a function's local/declare (and any later write of that name in it) hides reads only to that function's end (a local run in a child shell, ( local X ), binds nothing past that shell, and declare -g writes the global), a write inside $( ) or ( ) only to that subshell's end, and a write in a pipeline component or a background job (cmd | read X, X=1 &, a piped while loop) nothing past its command (after shopt -s lastpipe the pipeline's last command runs in the script itself). Each read row carries form= (required ${X:?}/${X?}, default ${X:-d}, unset-default ${X-d}, settest ${X:+w}/${X+w} or a -n/-z operand of [ / [[ / test, assign ${X:=d}, plain $X), colon=1|0 (does an EMPTY value count as unset), default= the literal word, and test=n|z; write rows list the name's assignments repo-wide; ambient="1" tags a name Bash or the login always sets (PWD, HOME, BASH_SOURCE, RANDOM and the like). A shell file whose header is a GENERATED/DO-NOT-EDIT banner is skipped (generated_skipped=N). Bash LIMITS: lexical order within one file, no flow — a name set only by eval, by printf -v "$1", in a function defined below the read, or in a sourced file still reads as external (the write rows let a consumer that follows source join them). An expansion nested more than 32 deep in another's word is not read past that depth, and the root counts such files (nesting_cut=N). A file --flags cannot open or read to its end is counted as unreadable=N on the root, and one too big to read (over the crawl's --max-file-size, a data lane's own ceiling (YAML 512 KB), or --flags' own 64 MB cap) as oversize=N, with oversize_limit= the smallest ceiling that dropped one. JSON over its 256 KB ceiling is not counted: no gate is live in a .json file. With either count present, gates= is a floor, and dark_gates= and the per-kind counts are incomplete in either direction (a declaration in a missing file can reclassify a gate). .zsh files are read with Bash's rules (no zsh-only expansion flags), and a script with no .sh/.bash/.zsh extension (a bare #!/bin/bash file) is not scanned. --flags --json emits the same rows and root counts as JSON, read the same way (raise --limit to lift the site cap).

**Try it**

Expand Down Expand Up @@ -4956,7 +4956,7 @@ $ ./build/ripwire . --max-file-size=8K --top-k=3
... [17 more line(s); run it to see the whole thing]
```

**Shaped by:** `--expand`, `--skipped`
**Shaped by:** `--expand`, `--flags`, `--skipped`

**Caveats (stated by the binary):**

Expand Down
10 changes: 6 additions & 4 deletions docs/LIMITS.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,10 +51,10 @@ cap do not both rewrite the same line; the per-file tables are re-read from `src

| total caps | files | caps whose file discloses | caps whose file discloses NOTHING |
| --- | --- | --- | --- |
| 454 | 156 | 289 | **165** |
| 456 | 156 | 291 | **165** |

Plus 10 ranking and apportionment parameters, in their own table below: they are not caps, they
are not counted as caps, and 454 + 10 is the 464 constants this generator parses out of `src/`.
are not counted as caps, and 456 + 10 is the 466 constants this generator parses out of `src/`.

## INDEXING, OUTPUT or BOUNDARY — which half of the answer a cap bounds

Expand All @@ -72,8 +72,8 @@ None of them truncates anything, so none can be judged by `shown=`/`total=` and
a disclosure — labelling them OUTPUT would ask for a `capped="1"` that could never honestly fire.
The distinction was named in review on #108 and the rows below now carry it.

The `class` column below carries that answer where it is known. **146 of 454 caps are classified
(54 INDEXING, 46 OUTPUT, 46 BOUNDARY); the remaining 308 render `—`, which means NOT YET
The `class` column below carries that answer where it is known. **148 of 456 caps are classified
(56 INDEXING, 46 OUTPUT, 46 BOUNDARY); the remaining 308 render `—`, which means NOT YET
CLASSIFIED — never "neither".** Classifications live in `docs/limits_classes.tsv`, a sidecar with
a known expiry:
the tag belongs on the declaration itself, and this file exists only because the round that
Expand Down Expand Up @@ -274,6 +274,8 @@ Discloses: `capped`, `reads_capped`, `writes_capped`
| --- | --- | --- | --- |
| `kMaxAliasDepth` | `8` | INDEXING | — |
| `kMaxEnvNameLen` | `128` | BOUNDARY | longest plausible environment-variable name |
| `kMaxFlagFileBytes` | `67108864` | INDEXING | 64 MiB read cap; a file past it counts in oversize= (#699) |
| `kMaxReadWholeBytes` | `4194304` | INDEXING | 4 MiB read cap for every verb but --flags; a file past it is disclosed unread |
| `kMaxShellNesting` | `32` | INDEXING | — |
| `kMaxSitesShown` | `8` | OUTPUT | <read> sites per gate; a DEFAULT, raisable by --limit=N (effectiveRowCap), lifted by --detail |

Expand Down
8 changes: 4 additions & 4 deletions docs/counts.tsv
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@
taken 2026-11-22
gates.scripts 865
limits.boundary 46
limits.caps 454
limits.constants 464
limits.disclosing 289
limits.caps 456
limits.constants 466
limits.disclosing 291
limits.files 156
limits.indexing 54
limits.indexing 56
limits.output 46
limits.parameters 10
limits.silent 165
Expand Down
2 changes: 2 additions & 0 deletions docs/limits_classes.tsv
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ kMaxExtLen BOUNDARY
kMaxExtentParens BOUNDARY
kMaxFamily INDEXING
kMaxFieldsShown OUTPUT
kMaxFlagFileBytes INDEXING
kMaxFlipRows OUTPUT
kMaxFnsShown OUTPUT
kMaxHexDigits BOUNDARY
Expand All @@ -96,6 +97,7 @@ kMaxPlanScout OUTPUT
kMaxProbeCommits INDEXING
kMaxQualifierHops INDEXING
kMaxQueryNesting BOUNDARY
kMaxReadWholeBytes INDEXING
kMaxRefs INDEXING
kMaxRenameProbeFiles INDEXING
kMaxSample INDEXING
Expand Down
16 changes: 12 additions & 4 deletions src/cli.h
Original file line number Diff line number Diff line change
Expand Up @@ -2359,7 +2359,9 @@ inline constexpr char kHelpTail[] =
" getopts, printf -v, ((X=…)); read/select/getopts/mapfile also set REPLY/OPTARG/\n"
" MAPFILE). An assignment takes effect where its command ends; a prefix X=v cmd is not a\n"
" write; a function's local/declare (and any later write of that name in it) hides reads\n"
" only to that function's end, a write inside $( ) or ( ) only to that subshell's end,\n"
" only to that function's end (a local run in a child shell, ( local X ), binds nothing\n"
" past that shell, and declare -g writes the global), a write inside $( ) or ( ) only\n"
" to that subshell's end,\n"
" and a write in a pipeline component or a background job (cmd | read X, X=1 &, a piped\n"
" while loop) nothing past its command (after shopt -s lastpipe the pipeline's last\n"
" command runs in the script itself). Each read row carries form= (required\n"
Expand All @@ -2374,10 +2376,16 @@ inline constexpr char kHelpTail[] =
" as external (the write rows let a consumer that follows source join them). An\n"
" expansion nested more than 32 deep in another's word is not read past that depth, and\n"
" the root counts such files (nesting_cut=N). A file --flags cannot open or read to its\n"
" end is counted as unreadable=N on the root: every count is then a floor. .zsh files\n"
" are read with Bash's rules (no zsh-only expansion flags), and a script with no\n"
" end is counted as unreadable=N on the root, and one too big to read (over the crawl's\n"
" --max-file-size, a data lane's own ceiling (YAML 512 KB), or --flags' own 64 MB cap)\n"
" as oversize=N, with oversize_limit= the smallest ceiling that dropped one. JSON over\n"
" its 256 KB ceiling is not counted: no gate is live in a .json file. With either count\n"
" present, gates= is a floor, and dark_gates= and the per-kind counts are incomplete\n"
" in either direction (a declaration in a missing file can reclassify a gate). .zsh\n"
" files are read with Bash's rules (no zsh-only expansion flags), and a script with no\n"
" .sh/.bash/.zsh extension (a bare #!/bin/bash file) is not scanned.\n"
" --flags --json emits the same rows as JSON (raise --limit to lift the site cap).\n"
" --flags --json emits the same rows and root counts as JSON, read the same way (raise\n"
" --limit to lift the site cap).\n"
" --flip=NAME (with --flags) the blast radius of turning ONE gate on\n"
" (with --flags) the BLAST RADIUS of turning ONE gate ON: which code becomes live, how\n"
" much, which SYMBOLS hold it, what those transitively reach, and which TESTS cover it —\n"
Expand Down
Loading
Loading