isabelle-query 0.6.7__tar.gz

isabelle_query-0.6.7/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# Editor / OS / agent
+.claude/*
+!.claude/memory/
+.DS_Store
+
+# Reference papers (not distributed with the tool)
+papers/
+
+# End-of-session handoff scratchpad — rewritten each session, survives compaction.
+prompt.md
+
+# Generated data from batch runs — never tracked (regenerable, and bulky).
+data/
+
+# namespace_cache.py prototype scratch cache (QUERY_CACHE_DIR demo target).
+.nscache/
+
+# Scratch file for commit message bodies (see .claude/memory)
+.commit-msg
+
+# Drafted issue replies, written to be pasted into GitHub and then deleted.
+# Ignored so a `git add -A` cannot sweep one into a commit.
+.issue-*.md
+
+# Session scratch: probe output, timing logs, mutation harnesses, and the
+# throwaway session roots / HEAD checkouts a corpus comparison needs.  Same
+# reason as above — `git add -A` swept a scratch `.rootless/Bare.thy` into a
+# commit once.  Scratch lives in the working tree (not /tmp, which is gated),
+# so the working tree has to know to ignore it.
+.scratch*
+.headtree/
+.rootless/
+.batchroot/
+.census-*
+.compare*
+.mutate*
+.timing*
+.repro*
+.variants*

isabelle_query-0.6.7/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing to isabelle-query
+
+Normative rules for changing the tool. Orientation (what `query` is, how the
+package is laid out) is in `CLAUDE.md`. User-facing docs are `README.md` (the
+CLI surface), `SCANNING.md` (what counts as a declaration, a citation and a
+session) and `METRICS.md` (the `query shape` reference).
+
+## Where design decisions are recorded
+
+**In commit messages.** They carry the reasoning, the rejected alternatives and
+the before/after, and they are the only record that cannot drift from the code.
+Cross-reference a body of work with a stable `[tag]` handle, and recover it with
+
+    git log --grep='\[grep-owner-span\]'
+
+`todo.md` holds only *open* work — things not yet done. It is not a changelog.
+If you want to know why something is the way it is, read the commits.
+
+**Cite only what a reader of this repo can open.** Comments, docstrings and
+config headers must not reference paths outside it — a pointer the reader cannot
+resolve is worse than no pointer, and the design material it names may be
+unpublished. For the proof-shape metrics the public authority is
+`src/isabelle_query/shape.py` itself (definitions at each metric) plus the
+`M1`–`M6` table in `METRICS.md`. Check with:
+
+    grep -rn 'docs/' --include='*.py' --include='*.toml' src tests scripts configs
+
+## CLI contract (follow when adding or changing commands)
+
+Two families, each matching an external convention; a command's primary
+positional decides which one it is.
+
+- **lookup** (git/brew: `git show REF...`, `brew deps FORMULA`) — the
+  primary positional is a **subject** (entry/theory name), one-or-more,
+  reported in turn. Add it with `_add_subject_list_arg`. **No trailing
+  PATH positionals**: "who calls X" is corpus-global, so scope with the
+  global `-R/--root` and narrow with *semantic* flags (`--external`,
+  `-r/--recursive`), never a file subset. Members: `show`, `callers`,
+  `callees`, `deps`, `uses`, `theory`, `defs`, `outline`, `methods`.
+- **search** (grep/rg: `grep PAT PATH...`) — the primary positional is a
+  pattern (or nothing), and **paths are the trailing positionals**, added
+  with `_add_path_files_arg` (resolved by `_load_sections`). Members:
+  `grep`, `largest`, `sorry` (and `find` once it gains PATH/`--theory`
+  scope under `[theory-refs]`).
+
+**Never return an empty success for a question you could not ask.** A silent
+zero is indistinguishable from an honest zero, so a caller cannot tell a broken
+run from a real one — `query -R /typo shape census` once printed nothing and
+exited 0, and a shell path-expansion bug turned that into a run of plausible
+zero-record censuses. A root that cannot be read reports on stderr and exits
+`2`, a code deliberately distinct from `1`.
+
+Shared-feature help text comes from one helper each, so wording can't
+drift command-to-command — always add a feature through its helper, never
+inline:
+
+| helper | feature |
+|---|---|
+| `_add_subject_list_arg` | subject list |
+| `_add_path_files_arg` | trailing `PATH` |
+| `_add_names_flag` | `--names` (**no `-n`** — reserved for grep's line-number meaning) |
+| `_add_count_flag` | `-c/--count` |
+| `_add_with_comments_flag` | `--with-comments` — the *only* prose-search toggle on `find`/`grep` (**no `-a`**, which is `_add_mode_flags`' show-all) |
+| `_add_mode_flags` | the `-a` / `--names` / `-c` bundle |
+| `_add_verbatim_flag` | `-V/--verbatim` |
+| `_add_comment_flags` | `--comments-off` / `--comments-only` |
+| `_add_context_flag` | `-U/--context` — one short flag everywhere, default per-command |
+| `_add_drop_names_flag` | `--drop-names-upto` |
+
+## Verification
+
+The suite is not sufficient on its own for parser changes; unit tests cannot
+see a scanner failing at scale. Two habits catch what they miss:
+
+- **Diff the entry set** after any parser change — `scripts/dump_entries.py`
+  (add `--spans` when extents may move; a change can leave entries identical
+  while moving a thousand declaration ends).
+- **Diff the discovered theory set** after any change to session or `imports`
+  parsing — and diff it **as a set, not a count**. `dump_entries.py` walks
+  `ent.rglob("*.thy")`, so it never calls `parse_thy_imports` and cannot see a
+  discovery regression: when `[thy-header]` silently dropped 72 theories it
+  reported an identical 55,838 entries. Compare
+  `{p for s in iter_sessions(root) for _, p in session_theories(s)}` against
+  the same set from `git archive <ref> | tar -x -C .scratch-head`. A count
+  alone hides a simultaneous gain and loss, which is exactly what happened.
+- **Check a new test can fail.** Patch the behaviour it pins, run it, restore.
+  Several tests have been written that could not fail. Two traps in the loop
+  itself, both of which have produced a wrong verdict here:
+  - **Run the mutation with `PYTHONDONTWRITEBYTECODE=1`.** A mutation harness
+    rewrites the source several times a second, and CPython invalidates a
+    `.pyc` on `(mtime, size)` — so a same-second rewrite can leave the previous
+    bytecode in place and the subprocess runs code that is not on disk. That
+    reports a *live* mutation as SURVIVED. `CAUGHT` is always trustworthy;
+    `SURVIVED` is not, until the cache is off.
+  - **A survivor may be masked, not dead.** A unit test can be shadowed by a
+    downstream guard that ends the scan anyway. Before concluding a branch is
+    unreachable, diff the entry set with the mutation applied: two branches
+    that survived every unit test moved 706 and 330 entries.
+  When a branch really is unreachable from valid input, say so in the comment
+  and pin it at the helper/regex level, rather than leaving it looking tested.
+
+`pytest -q` stays green after every change.

isabelle_query-0.6.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 András Salamon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

isabelle_query-0.6.7/METRICS.md

@@ -0,0 +1,156 @@
+# Proof-shape metrics — `query shape`
+
+A command reference for the `shape` family. Where the other subcommands ask
+*what is declared* and *which facts cite which*, `shape` measures the **shape of
+individual proof steps**: how big a step is, how deeply nested, how many facts
+it holds at once, how much it re-says, and how it is discharged.
+
+Everything here is **source-level** — computed by parsing `.thy` text, with no
+Isabelle build and no proof replay. Each value is either *exact* at source level
+or a token-based *estimator*; estimator columns carry an `_est` suffix, so the
+two are never silently conflated.
+
+The authoritative definitions — each metric's exact rule, the term-level
+semantics an estimator approximates, and its known approximations — are in
+`src/isabelle_query/shape.py`, stated at the metric. This file decodes the
+identifiers and says how to invoke them; it does not restate the definitions,
+which would drift.
+
+## Views
+
+```sh
+query shape summary                         # per-theory aggregate table
+query shape steps [THEORY[:A..B]]           # per-step records
+query shape lemma <name>...                 # one proof: every step + M6 curve
+query shape widest [-N n] [PATH...]         # the widest steps
+query shape census                          # stream per-proof JSONL over a corpus
+```
+
+| view | takes | output |
+|---|---|---|
+| `summary` | — | one row per theory |
+| `steps` | an optional `THEORY` or `THEORY:A..B` span | one row per Isar step |
+| `lemma` | one or more entry names | every step, an aggregate footer, and the M6 curve |
+| `widest` | optional trailing `PATH`s | the *n* widest steps by a chosen metric |
+| `census` | — | one JSON object per proof, streamed and resumable |
+
+Flags, beyond the global `-R/--root` and `--version`:
+
+| flag | views | meaning |
+|---|---|---|
+| `--json` | all but `census` | one JSONL record per line instead of the table |
+| `-a`, `--all` | `steps` | include non-goal steps (context / plumbing / closing); the default shows goal steps only, where the metrics attach |
+| `--scope {proof,entry}` | `summary` | size columns over the proof body (default) or the whole entry including its statement, as `largest` counts |
+| `--content {all,code,prose}` | `summary` | size columns over all lines (default), code only (prose stripped), or prose only |
+| `-N n` | `widest` | how many steps to rank |
+| `--metric {w2,w1,fanin,live}` | `widest` | rank by as-written token width (default), free variables, cited facts, or simultaneously-live facts |
+| `--config TOML`, `--corpus NAME` | `steps`, `lemma` | add the M3 `frame_ratio` columns; see [Corpus configs](#corpus-configs-m3) |
+| `--resume FILE` | `census` | skip records already present in a prior run |
+
+## Metrics
+
+| id | column | measures | kind |
+|----|--------|----------|------|
+| M1 | `w1_est` | distinct free variables in the stated proposition | estimator |
+| — | `const_est` | distinct constants in the stated proposition (names + operator notation) | estimator |
+| — | `const_canon_est` | `const_est` with operator glyphs canonicalised to their Isabelle constant (`\<le>`/`\<subseteq>` → one) | estimator |
+| M2 | `w2_src` | as-written proposition width, in tokens | exact |
+| M3 | `frame_ratio` | delta-tracing overhead (components mentioned / changed) | definitional¹ |
+| M4 | `dag_ratio_est` | cross-step redundancy (repeated bracketed subterms / block) | estimator |
+| M5a | `fanin` | distinct facts cited for a step | exact |
+| M5b | `live` | named facts simultaneously live at a step | exact |
+| M5c | `introduce`/`consume` | fact-introducing vs fact-citing lines | exact |
+| M6 | extension curve | width remaining after naming the *k* most-repeated subterms | estimator |
+
+¹ M3 is defined purely syntactically, so it has no estimator/reference split —
+but it needs a per-corpus config.
+
+The columns group into axes, which is how the `summary` table is laid out:
+
+| axis | asks | columns |
+|------|------|---------|
+| Length | how big is the proof? | `n_steps`, `n_goals`, `proof_lines`, `proof_tokens` (raw + `_code`), `entry_lines` |
+| Depth | how deeply nested? | `depth_max` |
+| Width | how big is one step? | `w1_est`, `const_est`/`const_canon_est`, `w2_src` |
+| Space | how many facts held at once? | `fanin`, `live`, `introduce`/`consume` |
+| Redundancy | how much is re-said? | `dag_ratio_est`, M6 extension curve |
+| Automation | how is it discharged? | `trivial_frac`, `method_kinds`, induction discipline (`n_induct`, `induct_arbitrary_max`, `induct_recursion`) |
+| Framing | how much to say to change a little? | `frame_ratio` |
+
+They are separate measurements, not components of a single score: a proof can be
+long and shallow, or short and wide.
+
+## JSONL records
+
+`--json` (and `census`) emit one JSON object per line, keyed by a stable
+`(theory, lemma, line)` position so records join across runs without
+re-instrumentation. Two record shapes — per-step (`steps` / `lemma` / `widest`)
+and per-proof aggregate (`summary --json` / `census`). **The full field lists are
+in the `shape_cmds` module docstring.**
+
+Per-proof records also carry `session` (`null` when the load had no session
+context), which a corpus run needs: AFP theory names are not unique across
+entries, so `(theory, lemma)` alone cannot identify one.
+
+## Running a census over a corpus
+
+```sh
+query -R AFP/thys shape census > afp.jsonl
+```
+
+One process for the whole corpus, one session at a time — do not loop `query`
+over entries in a shell, which pays interpreter and process startup per entry
+and dominates the run. Memory is bounded by the largest single session rather
+than by the corpus, and a session that fails to parse is reported on stderr and
+skipped rather than aborting the run.
+
+Output is flushed per session, so a killed run leaves a valid JSONL prefix, and
+`--resume FILE` skips records already present:
+
+```sh
+query -R AFP/thys shape census --resume afp.jsonl >> afp.jsonl
+```
+
+Exit status follows the usual rule: `2` if no session could be read at all,
+`0` with a stderr summary if some were skipped, `0` in silence for an honest
+zero. A directory with no `ROOT` is still a corpus (the `*.thy` fallback),
+censused as a single unnamed group.
+
+## The method table, and where it limits the numbers
+
+The one place Isabelle informs a result is the method/attribute table that tells
+a proof method (`by auto`) from a fact citation.
+
+`census` uses a fixed, committed **approximate** table — the union of the
+distribution sessions most AFP entries build on (HOL, HOL-Library, HOL-Analysis,
+HOL-Eisbach, HOL-Decision_Procs) — so it needs no Isabelle and regenerates
+identically anywhere. Being fixed, it is an approximation: methods an entry
+defines itself (an Eisbach `cs_concl`) or that come from a niche logic (Nominal's
+`nominal_induct`) are not in it, so the **Automation** axis under-counts on those
+steps. This affects a few percent of proofs, only in method-defining entries;
+fan-in and width are unaffected.
+
+The per-project verbs (`callers` / `callees` / `unused` / `methods` / `shape`)
+instead resolve a **session-exact** table from a loaded Isabelle heap when one is
+built — cached, and never a build — falling back to the committed table with a
+warning. Heaps are looked for where Isabelle looks: `$ISABELLE_HEAPS` first, then
+`$ISABELLE_HEAPS_SYSTEM`, so a stock install with nothing built locally still
+resolves the exact table from the distribution's own `HOL`.
+
+A second, smaller committed table backs `const_canon_est`: a notation table
+mapping operator glyphs to their Isabelle constant (`\<le>` → `less_eq`),
+resolved once from a heap by `scripts/extract_notation.py` and checked in, so
+runtime stays pure-Python. A glyph the table does not carry falls back to itself,
+so it only ever dedups, never loses, a constant — and the raw-glyph `const_est`
+beside it stays table-independent.
+
+## Corpus configs (M3)
+
+Source parsing cannot resolve types, so M3's "configuration type" degrades to a
+per-corpus list of selector / constructor / relation names. Supply it as TOML —
+one `[corpus]` table per entry — and pass `--config FILE [--corpus NAME]` to
+`steps` / `lemma` to add the `frame_ratio` columns. `configs/m3.toml` ships a
+`Cook_Levin` table. Without a config the rest of the family runs unchanged.
+
+When comparing across corpora, normalize per proof or per goal step, never per
+kloc — line counts confound formatting.

isabelle_query-0.6.7/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: isabelle-query
+Version: 0.6.7
+Summary: Query the live theory index of an Isabelle/Isar project — entries, call graph, dependencies, and dead code — by parsing .thy files on every invocation.
+Project-URL: Homepage, https://github.com/ott2/isabelle-query
+Project-URL: Source, https://github.com/ott2/isabelle-query
+Author-email: András Salamon <Andras.Salamon@st-andrews.ac.uk>
+License: MIT
+License-File: LICENSE
+Keywords: afp,formal-verification,isabelle,isar,proof-engineering,theorem-proving
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Requires-Dist: isabelle-layout>=0.2.2
+Description-Content-Type: text/markdown
+
+# isabelle-query
+
+`query` is a command-line tool for **querying an Isabelle/Isar project** — its
+entries (definitions, lemmas, theorems, datatypes), call graph, theory
+dependencies, outstanding `sorry`s, dead code, and the shape of its proofs.
+
+It parses the project's `.thy` sources on every invocation, so results always
+match the current tree: **no Isabelle build, no proof replay**. A large project
+parses in a fraction of a second, and the whole AFP in a couple of minutes. It is
+aimed at projects big enough that grep-and-examine has stopped working — AFP
+entries, the AFP itself, or industrial verification.
+
+Pure Python. One runtime dependency,
+[isabelle-layout](https://pypi.org/project/isabelle-layout/) — the ROOT and
+theory-header parser, split out so that reading an Isabelle project's structure
+does not require installing a CLI. `pip` fetches it for you.
+
+## Commands
+
+```sh
+query summary              # theory overview table (-S: corpus/session aggregate)
+query theory MyTheory      # entries in a theory (-n for terse names)
+query find <regex>         # search entry names (--statement: search statements)
+query show <name>          # a named entry's declaration + body
+query enclosing FILE:LINE  # which entry + proof block owns a line; inverse of outline
+query callers <name> [-r]  # who references a name  (reverse; -r = transitive)
+query callees <name> [-r]  # what a name references (forward)
+query deps <theory> [-r]   # what a theory imports  (forward; reverse: uses)
+query sorry                # outstanding sorry's
+query unused               # dead-code / unused-entry analysis
+query shape <view>         # proof-shape metrics (summary|steps|lemma|widest|census)
+```
+
+Every subcommand takes `-h`; `query -h` lists all 18.
+
+## Examples
+
+Point `query` at any session directory with `-R` (or `--root`):
+
+```sh
+query -R AFP/thys largest                          # the biggest entries, by line count
+query -R AFP/thys callers metric_domain_tfin_def   # every proof step that cites a fact
+query -R AFP/thys find --statement tfin            # lemmas *stated about* tfin, whatever their name
+query -R AFP/thys enclosing Tfin.thy:412           # the lemma and nearest proof block a build error sits in
+query -R AFP/thys enclosing Tfin:88..140           # every entry a diff hunk touches
+query -R AFP/thys grep simp Tfin.thy:88..140       # search just a hunk
+```
+
+Locations and spans share one grammar (`theory:line`, `theory:A..B`), so the
+tool's output is valid input: a locus from `callers` / `sorry` pastes into
+`enclosing`, and a span from `outline` / `largest` — or a proof block from
+`enclosing`'s own drill-down (`▸ have key 11..14`) — pastes into `lines`.
+
+## What it reads
+
+Only **live Isar text**. A name in a comment, a `\<comment>` note, a `text`
+block or an `ML` body is not a citation, so it never invents a caller or hides a
+dead lemma — and a `definition` left behind in a comment is not an entry.
+Regions are found by a character-level scan, not by line, so
+`by (simp add: foo) (* not bar *)` keeps `foo` and drops `bar`.
+
+Layout carries no meaning: Isar is whitespace-insensitive, so a declaration is
+recognised wherever a *command* can start, at any indentation and any block
+depth. Discovery loads what `isabelle build` compiles — each session's declared
+theories plus the closure of their in-entry imports.
+
+See **[SCANNING.md](SCANNING.md)** for the details: locale scope, method names
+that collide with fact names, corpus aggregation, and the prose view.
+
+## Proof-shape metrics
+
+`query shape` measures the shape of individual proof steps — how big a step is,
+how deeply nested, how many facts it holds at once, how much is re-said, and how
+it is discharged. All source-level, no build.
+
+```sh
+query shape summary                  # per-theory aggregate table
+query shape lemma <name>             # one proof: every step
+query -R AFP/thys shape census       # per-proof JSONL over a whole corpus
+```
+
+See **[METRICS.md](METRICS.md)** for the command reference, the metric table, and
+the JSONL record schema.
+
+## Exit status
+
+`0` the command ran; `1` the request could not be resolved (unknown theory or
+path, no subcommand); `2` bad usage — an argparse error, or **a root that could
+not be read**; `141` a downstream reader closed the pipe (`query shape census |
+head`), as a shell reports for SIGPIPE.
+
+A root that yields no theories is reported on stderr and never as an empty
+success, so a script can tell a broken run from an honestly empty one:
+
+```
+$ query -R /typo/path shape census
+query: /typo/path: no such directory (given to -R/--root)
+$ echo $?
+2
+```
+
+## Installation
+
+Requires Python 3.9 or greater. Installs a `query` command on your `PATH`, and
+pulls `isabelle-layout` from PyPI.
+
+```sh
+pip install isabelle-query     # from PyPI
+pip install .                  # from a checkout
+```
+
+An editable install, for working on the tool itself:
+
+```sh
+git clone https://github.com/ott2/isabelle-query
+cd isabelle-query
+python -m venv .venv && source .venv/bin/activate   # optional but recommended
+pip install -e .
+```
+
+## Documentation
+
+| file | what |
+|---|---|
+| [SCANNING.md](SCANNING.md) | how `query` reads a project — what counts as a declaration, a citation, and a session |
+| [METRICS.md](METRICS.md) | `query shape` command reference and metric definitions |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | the CLI contract and where design decisions are recorded |
+
+## Authors & license
+
+By András Salamon, with Claude Opus 4.6, 4.7, 4.8, and 5. [MIT](LICENSE).

isabelle_query-0.6.7/README.md

@@ -0,0 +1,131 @@
+# isabelle-query
+
+`query` is a command-line tool for **querying an Isabelle/Isar project** — its
+entries (definitions, lemmas, theorems, datatypes), call graph, theory
+dependencies, outstanding `sorry`s, dead code, and the shape of its proofs.
+
+It parses the project's `.thy` sources on every invocation, so results always
+match the current tree: **no Isabelle build, no proof replay**. A large project
+parses in a fraction of a second, and the whole AFP in a couple of minutes. It is
+aimed at projects big enough that grep-and-examine has stopped working — AFP
+entries, the AFP itself, or industrial verification.
+
+Pure Python. One runtime dependency,
+[isabelle-layout](https://pypi.org/project/isabelle-layout/) — the ROOT and
+theory-header parser, split out so that reading an Isabelle project's structure
+does not require installing a CLI. `pip` fetches it for you.
+
+## Commands
+
+```sh
+query summary              # theory overview table (-S: corpus/session aggregate)
+query theory MyTheory      # entries in a theory (-n for terse names)
+query find <regex>         # search entry names (--statement: search statements)
+query show <name>          # a named entry's declaration + body
+query enclosing FILE:LINE  # which entry + proof block owns a line; inverse of outline
+query callers <name> [-r]  # who references a name  (reverse; -r = transitive)
+query callees <name> [-r]  # what a name references (forward)
+query deps <theory> [-r]   # what a theory imports  (forward; reverse: uses)
+query sorry                # outstanding sorry's
+query unused               # dead-code / unused-entry analysis
+query shape <view>         # proof-shape metrics (summary|steps|lemma|widest|census)
+```
+
+Every subcommand takes `-h`; `query -h` lists all 18.
+
+## Examples
+
+Point `query` at any session directory with `-R` (or `--root`):
+
+```sh
+query -R AFP/thys largest                          # the biggest entries, by line count
+query -R AFP/thys callers metric_domain_tfin_def   # every proof step that cites a fact
+query -R AFP/thys find --statement tfin            # lemmas *stated about* tfin, whatever their name
+query -R AFP/thys enclosing Tfin.thy:412           # the lemma and nearest proof block a build error sits in
+query -R AFP/thys enclosing Tfin:88..140           # every entry a diff hunk touches
+query -R AFP/thys grep simp Tfin.thy:88..140       # search just a hunk
+```
+
+Locations and spans share one grammar (`theory:line`, `theory:A..B`), so the
+tool's output is valid input: a locus from `callers` / `sorry` pastes into
+`enclosing`, and a span from `outline` / `largest` — or a proof block from
+`enclosing`'s own drill-down (`▸ have key 11..14`) — pastes into `lines`.
+
+## What it reads
+
+Only **live Isar text**. A name in a comment, a `\<comment>` note, a `text`
+block or an `ML` body is not a citation, so it never invents a caller or hides a
+dead lemma — and a `definition` left behind in a comment is not an entry.
+Regions are found by a character-level scan, not by line, so
+`by (simp add: foo) (* not bar *)` keeps `foo` and drops `bar`.
+
+Layout carries no meaning: Isar is whitespace-insensitive, so a declaration is
+recognised wherever a *command* can start, at any indentation and any block
+depth. Discovery loads what `isabelle build` compiles — each session's declared
+theories plus the closure of their in-entry imports.
+
+See **[SCANNING.md](SCANNING.md)** for the details: locale scope, method names
+that collide with fact names, corpus aggregation, and the prose view.
+
+## Proof-shape metrics
+
+`query shape` measures the shape of individual proof steps — how big a step is,
+how deeply nested, how many facts it holds at once, how much is re-said, and how
+it is discharged. All source-level, no build.
+
+```sh
+query shape summary                  # per-theory aggregate table
+query shape lemma <name>             # one proof: every step
+query -R AFP/thys shape census       # per-proof JSONL over a whole corpus
+```
+
+See **[METRICS.md](METRICS.md)** for the command reference, the metric table, and
+the JSONL record schema.
+
+## Exit status
+
+`0` the command ran; `1` the request could not be resolved (unknown theory or
+path, no subcommand); `2` bad usage — an argparse error, or **a root that could
+not be read**; `141` a downstream reader closed the pipe (`query shape census |
+head`), as a shell reports for SIGPIPE.
+
+A root that yields no theories is reported on stderr and never as an empty
+success, so a script can tell a broken run from an honestly empty one:
+
+```
+$ query -R /typo/path shape census
+query: /typo/path: no such directory (given to -R/--root)
+$ echo $?
+2
+```
+
+## Installation
+
+Requires Python 3.9 or greater. Installs a `query` command on your `PATH`, and
+pulls `isabelle-layout` from PyPI.
+
+```sh
+pip install isabelle-query     # from PyPI
+pip install .                  # from a checkout
+```
+
+An editable install, for working on the tool itself:
+
+```sh
+git clone https://github.com/ott2/isabelle-query
+cd isabelle-query
+python -m venv .venv && source .venv/bin/activate   # optional but recommended
+pip install -e .
+```
+
+## Documentation
+
+| file | what |
+|---|---|
+| [SCANNING.md](SCANNING.md) | how `query` reads a project — what counts as a declaration, a citation, and a session |
+| [METRICS.md](METRICS.md) | `query shape` command reference and metric definitions |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | the CLI contract and where design decisions are recorded |
+
+## Authors & license
+
+By András Salamon, with Claude Opus 4.6, 4.7, 4.8, and 5. [MIT](LICENSE).