Claude Opus 5andbdeshi
7796b0d919
Adopts ideas/token-conservation.md, parked 2026-07-28, plus the disciplines the human added: read the compressed form first, discover by mechanism, shrink output at the source, never pay twice for the same bytes. docs/context-economy.md owns all of it and leads with a floor, because every cheap failure mode is also a token saving — skipping the owning doc, guessing a signature, reporting from a diff, thinning a test — and each has already cost this repo a defect. Frugality is for presentation and discovery, never for the artifact or the evidence. Mechanical, not remembered: - scripts/surface.sh generates docs/surface.md — every top-level declaration with its line, 261 lines standing for 3757 of source. The pre-commit hook regenerates and stages it, so it cannot be stale, and verify.sh compares independently for a clone that never set core.hooksPath. The hook refuses a commit with unstaged .go changes, since what it generated describes the working tree, not the commit. - verify.sh --quiet: 48 lines of gate output become 1. The hook uses it. - CLAUDE_LOC_MAX=150, the only budget billed per turn rather than per read. Both new gates were watched failing before being kept: a doctored surface.md, and CLAUDE_LOC_MAX temporarily set to 5. state.md's inventory loses its LOC column. It had already drifted on six files (content.go 381→450, render.go 447→454, web.go 206→217, check 216→223, watch 129→137, chrome 105→110) which is what a number written in two places does; the generated file owns sizes now, the table owns purpose. The subagent question is recorded there as the one open decision, with the case for and against written out in the idea file.
56 lines
2.8 KiB
Bash
Executable File
56 lines
2.8 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# Generates the compressed form of the code: every package, its size, and every top-level declaration
|
|
# with the line to jump to.
|
|
#
|
|
# Usage: scripts/surface.sh print it
|
|
# scripts/surface.sh --write regenerate docs/surface.md (`make surface`)
|
|
#
|
|
# Why this exists: reading a 400-line file to learn what is in it costs forty times what reading its
|
|
# surface costs, and the answer to "where does X live" is almost never in the bodies. `go doc` already
|
|
# does this for *exported* identifiers; this also covers unexported ones, which is where most of khosra
|
|
# lives — nothing outside cmd/ has many exported names by design.
|
|
#
|
|
# Generated, never hand-edited, and gated: verify.sh regenerates and compares, so a stale surface fails
|
|
# the build rather than misleading a reader. Purposes and intent stay in docs/state.md — this file is
|
|
# mechanical and says only what is there.
|
|
set -uo pipefail
|
|
cd "$(dirname "$0")/.." || exit 1
|
|
|
|
emit() {
|
|
printf '# Surface\n\n'
|
|
printf 'Generated by `scripts/surface.sh` — do not edit. Regenerate with `make surface`.\n\n'
|
|
printf 'Every top-level declaration in the engine, with its line. Read this before opening a source\n'
|
|
printf 'file: it answers "where does X live" and "what is in this package" without the bodies. What each\n'
|
|
printf 'file is *for* lives in `state.md`; why it is that way lives in `decisions.md`.\n'
|
|
|
|
git ls-files '*.go' | grep -v '_test\.go$' | xargs -n1 dirname | sort -u | while read -r dir; do
|
|
files=$(git ls-files "$dir/*.go" | grep -v '_test\.go$' | sort)
|
|
[ -z "$files" ] && continue
|
|
tests=$(git ls-files "$dir/*_test.go" | sort)
|
|
code=$(echo "$files" | xargs wc -l | awk '$2!="total"{t+=$1} END{print t+0}')
|
|
testloc=0
|
|
[ -n "$tests" ] && testloc=$(echo "$tests" | xargs wc -l | awk '$2!="total"{t+=$1} END{print t+0}')
|
|
printf '\n## %s — %s lines' "$dir" "$code"
|
|
[ "$testloc" -gt 0 ] && printf ' + %s test' "$testloc"
|
|
printf '\n\n'
|
|
# One manifest line per package, so the cost of opening any file is visible before you open it.
|
|
echo "$files" | while read -r f; do printf '%s %s · ' "$(basename "$f")" "$(wc -l <"$f" | tr -d ' ')"; done |
|
|
sed 's/ · $//'
|
|
printf '\n\n'
|
|
for f in $files; do
|
|
# Top-level declarations only: in gofmt'd Go those are exactly the lines starting in column one.
|
|
# The trailing brace and any body opener go, so a signature reads as one line.
|
|
grep -nE '^(func|type|const|var) ' "$f" |
|
|
sed -e 's/ {$//' -e 's/ ($//' -e 's/[[:space:]]*$//' |
|
|
awk -F: -v n="$(basename "$f")" '{ line = $1; $1 = ""; sub(/^:/, ""); sub(/^ +/, ""); printf "- %s:%s %s\n", n, line, $0 }'
|
|
done
|
|
done
|
|
}
|
|
|
|
if [ "${1:-}" = "--write" ]; then
|
|
emit >docs/surface.md
|
|
printf 'wrote docs/surface.md (%s lines)\n' "$(wc -l <docs/surface.md | tr -d ' ')"
|
|
else
|
|
emit
|
|
fi
|