topomark 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. topomark-0.4.0/LICENSE +21 -0
  2. topomark-0.4.0/PKG-INFO +332 -0
  3. topomark-0.4.0/README.md +308 -0
  4. topomark-0.4.0/pyproject.toml +62 -0
  5. topomark-0.4.0/setup.cfg +4 -0
  6. topomark-0.4.0/src/topomark/__init__.py +31 -0
  7. topomark-0.4.0/src/topomark/__main__.py +3 -0
  8. topomark-0.4.0/src/topomark/changes.py +169 -0
  9. topomark-0.4.0/src/topomark/cli.py +209 -0
  10. topomark-0.4.0/src/topomark/commands/__init__.py +53 -0
  11. topomark-0.4.0/src/topomark/commands/_common.py +27 -0
  12. topomark-0.4.0/src/topomark/commands/agent_hook.py +338 -0
  13. topomark-0.4.0/src/topomark/commands/brief.py +272 -0
  14. topomark-0.4.0/src/topomark/commands/capabilities.py +47 -0
  15. topomark-0.4.0/src/topomark/commands/changes.py +217 -0
  16. topomark-0.4.0/src/topomark/commands/check.py +41 -0
  17. topomark-0.4.0/src/topomark/commands/diff.py +81 -0
  18. topomark-0.4.0/src/topomark/commands/doctor.py +67 -0
  19. topomark-0.4.0/src/topomark/commands/draft.py +149 -0
  20. topomark-0.4.0/src/topomark/commands/find.py +64 -0
  21. topomark-0.4.0/src/topomark/commands/gen.py +33 -0
  22. topomark-0.4.0/src/topomark/commands/hook.py +104 -0
  23. topomark-0.4.0/src/topomark/commands/impact.py +82 -0
  24. topomark-0.4.0/src/topomark/commands/init.py +609 -0
  25. topomark-0.4.0/src/topomark/commands/locate.py +109 -0
  26. topomark-0.4.0/src/topomark/commands/map.py +140 -0
  27. topomark-0.4.0/src/topomark/commands/outline.py +143 -0
  28. topomark-0.4.0/src/topomark/commands/owner.py +44 -0
  29. topomark-0.4.0/src/topomark/commands/refs.py +72 -0
  30. topomark-0.4.0/src/topomark/commands/search.py +82 -0
  31. topomark-0.4.0/src/topomark/commands/stale.py +49 -0
  32. topomark-0.4.0/src/topomark/commands/stamp.py +91 -0
  33. topomark-0.4.0/src/topomark/commands/symbol.py +98 -0
  34. topomark-0.4.0/src/topomark/commands/sync.py +38 -0
  35. topomark-0.4.0/src/topomark/commands/syntax.py +61 -0
  36. topomark-0.4.0/src/topomark/commands/tests_for.py +96 -0
  37. topomark-0.4.0/src/topomark/config.py +188 -0
  38. topomark-0.4.0/src/topomark/context.py +58 -0
  39. topomark-0.4.0/src/topomark/contract.py +28 -0
  40. topomark-0.4.0/src/topomark/docs.py +174 -0
  41. topomark-0.4.0/src/topomark/errors.py +75 -0
  42. topomark-0.4.0/src/topomark/graph.py +133 -0
  43. topomark-0.4.0/src/topomark/imports.py +321 -0
  44. topomark-0.4.0/src/topomark/index.py +421 -0
  45. topomark-0.4.0/src/topomark/lang/__init__.py +0 -0
  46. topomark-0.4.0/src/topomark/lang/_decl.py +140 -0
  47. topomark-0.4.0/src/topomark/lang/_imports.py +82 -0
  48. topomark-0.4.0/src/topomark/lang/base.py +160 -0
  49. topomark-0.4.0/src/topomark/lang/brace.py +404 -0
  50. topomark-0.4.0/src/topomark/lang/cfamily.py +340 -0
  51. topomark-0.4.0/src/topomark/lang/csharp.py +275 -0
  52. topomark-0.4.0/src/topomark/lang/dart.py +119 -0
  53. topomark-0.4.0/src/topomark/lang/go.py +104 -0
  54. topomark-0.4.0/src/topomark/lang/js_ts.py +275 -0
  55. topomark-0.4.0/src/topomark/lang/kotlin.py +83 -0
  56. topomark-0.4.0/src/topomark/lang/python.py +235 -0
  57. topomark-0.4.0/src/topomark/lang/registry.py +72 -0
  58. topomark-0.4.0/src/topomark/lang/rust.py +117 -0
  59. topomark-0.4.0/src/topomark/lang/scan.py +466 -0
  60. topomark-0.4.0/src/topomark/lang/simple.py +408 -0
  61. topomark-0.4.0/src/topomark/lang/swift.py +91 -0
  62. topomark-0.4.0/src/topomark/locate.py +342 -0
  63. topomark-0.4.0/src/topomark/masking.py +36 -0
  64. topomark-0.4.0/src/topomark/navigate.py +536 -0
  65. topomark-0.4.0/src/topomark/ranking.py +115 -0
  66. topomark-0.4.0/src/topomark/repo.py +376 -0
  67. topomark-0.4.0/src/topomark/runners.py +167 -0
  68. topomark-0.4.0/src/topomark/search.py +426 -0
  69. topomark-0.4.0/src/topomark/stamps.py +118 -0
  70. topomark-0.4.0/src/topomark/syntax.py +288 -0
  71. topomark-0.4.0/src/topomark/templates/L0.md +82 -0
  72. topomark-0.4.0/src/topomark/templates/_TEMPLATE.md +67 -0
  73. topomark-0.4.0/src/topomark/templates/__init__.py +5 -0
  74. topomark-0.4.0/src/topomark/templates/area.md +30 -0
  75. topomark-0.4.0/src/topomark/testsel.py +291 -0
  76. topomark-0.4.0/src/topomark/workspace.py +436 -0
  77. topomark-0.4.0/src/topomark.egg-info/PKG-INFO +332 -0
  78. topomark-0.4.0/src/topomark.egg-info/SOURCES.txt +96 -0
  79. topomark-0.4.0/src/topomark.egg-info/dependency_links.txt +1 -0
  80. topomark-0.4.0/src/topomark.egg-info/entry_points.txt +2 -0
  81. topomark-0.4.0/src/topomark.egg-info/top_level.txt +1 -0
  82. topomark-0.4.0/tests/test_agent_hook.py +290 -0
  83. topomark-0.4.0/tests/test_brief.py +121 -0
  84. topomark-0.4.0/tests/test_cache.py +245 -0
  85. topomark-0.4.0/tests/test_changes.py +189 -0
  86. topomark-0.4.0/tests/test_docsystem.py +301 -0
  87. topomark-0.4.0/tests/test_init_draft.py +231 -0
  88. topomark-0.4.0/tests/test_lang.py +676 -0
  89. topomark-0.4.0/tests/test_lang_scan.py +136 -0
  90. topomark-0.4.0/tests/test_locate.py +182 -0
  91. topomark-0.4.0/tests/test_meta.py +324 -0
  92. topomark-0.4.0/tests/test_navigation.py +736 -0
  93. topomark-0.4.0/tests/test_output_economy.py +149 -0
  94. topomark-0.4.0/tests/test_regressions.py +37 -0
  95. topomark-0.4.0/tests/test_safety.py +446 -0
  96. topomark-0.4.0/tests/test_search.py +117 -0
  97. topomark-0.4.0/tests/test_syntax.py +109 -0
  98. topomark-0.4.0/tests/test_tools.py +397 -0
topomark-0.4.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Li, ching yu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,332 @@
1
+ Metadata-Version: 2.4
2
+ Name: topomark
3
+ Version: 0.4.0
4
+ Summary: A zero-dependency code map for AI coding agents: progressive-disclosure docs, per-file review stamps that catch stale summaries, and fast symbol/impact/test navigation for git repositories.
5
+ Author-email: "Li, ching yu" <tipo5890Li@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/tipoLi5890/topomark
8
+ Project-URL: Repository, https://github.com/tipoLi5890/topomark.git
9
+ Project-URL: Changelog, https://github.com/tipoLi5890/topomark/blob/main/CHANGELOG.md
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Topic :: Software Development :: Documentation
14
+ Classifier: Topic :: Software Development :: Quality Assurance
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Operating System :: OS Independent
20
+ Requires-Python: >=3.11
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Dynamic: license-file
24
+
25
+ # topomark
26
+
27
+ **Your agent reads a 2,000-line file to find one function. Give it a map instead.**
28
+
29
+ topomark is a zero-dependency code map for AI coding agents: layered docs that say where to look,
30
+ review stamps that fail CI when a summary goes stale, and fast symbol, impact and test navigation
31
+ for any git repository. Python 3.11+ standard library only; offline; read-only on your code.
32
+
33
+ ![license: MIT](https://img.shields.io/badge/license-MIT-blue)
34
+ ![python: 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
35
+ ![dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen)
36
+
37
+ [繁體中文](.github/README.zh-Hant.md) · [简体中文](.github/README.zh-Hans.md) · [日本語](.github/README.ja.md)
38
+
39
+ ## Let your agent install it
40
+
41
+ Paste this into Claude Code, Codex or any coding agent with a terminal, from inside your repository:
42
+
43
+ ```text
44
+ Install topomark (https://github.com/tipoLi5890/topomark), a zero-dependency code map and
45
+ navigation CLI, and set this repository up to use it:
46
+
47
+ 1. Clone it: git clone https://github.com/tipoLi5890/topomark ~/tools/topomark
48
+ (if that directory exists, run git -C ~/tools/topomark pull instead).
49
+ 2. Put it on PATH: ln -sf ~/tools/topomark/bin/topomark ~/.local/bin/topomark, and make sure
50
+ ~/.local/bin is on PATH. Check with topomark --version (it needs Python 3.11+ and git).
51
+ 3. Run topomark doctor in this repository and tell me about any problem it reports.
52
+ 4. Read ~/tools/topomark/skills/topomark/SKILL.md and follow it from now on.
53
+ 5. Add this line to AGENTS.md, or to CLAUDE.md if that is what the repository uses:
54
+ "Navigate with topomark: read docs/codemap/README.md first, then `topomark outline <file>` and
55
+ `topomark symbol <file>#<Name>` instead of reading whole files; `topomark brief <file>` before
56
+ an edit. After editing, run `topomark syntax`, run what `topomark tests-for --diff` prints and
57
+ keep `topomark check` green."
58
+ 6. Run topomark init --dry-run and show me the proposed areas. Write nothing else until I agree;
59
+ then run topomark init and topomark draft <area> --write for each area, and fill in the rows.
60
+ ```
61
+
62
+ Until a code map exists, `topomark map --tokens 2000` and the other navigation commands already
63
+ work; step 6 is what makes `check` and review stamps possible.
64
+
65
+ ## Try it in 30 seconds
66
+
67
+ Navigation needs no setup, no config and no index to build. Clone, then point it at any git repo:
68
+
69
+ ```bash
70
+ git clone https://github.com/tipoLi5890/topomark ~/tools/topomark
71
+ cd your-repo
72
+ ~/tools/topomark/bin/topomark map --tokens 2000 # a ranked map of the repo, within a token budget
73
+ ```
74
+
75
+ Nothing is installed and nothing is written to your repository.
76
+
77
+ ## Why topomark
78
+
79
+ ### A ladder, not a haystack
80
+
81
+ Agents spend much of their context reading whole files to find one function. topomark gives them
82
+ rungs, each small enough to read in full:
83
+
84
+ ```text
85
+ L0 docs/codemap/README.md one index: the areas of the repo and what each owns
86
+ L1 docs/codemap/<area>.md one row per file: what it does, how many files depend on it,
87
+ what to update when it changes
88
+ L2 the code, by symbol topomark outline / symbol / refs: one function, not the file
89
+ ```
90
+
91
+ ### Review stamps, not timestamps
92
+
93
+ Hand-written maps rot silently. So topomark stores, per file, a hash of its *interface* (header
94
+ comment, public signatures, constants) at the moment its row was reviewed.
95
+
96
+ - Change an interface without reviewing the row: `topomark check` fails.
97
+ - Change only a function body: it stays quiet.
98
+
99
+ A "last updated" date can't tell those two apart. A stamp can, so the map is either current or CI
100
+ says exactly which rows are not.
101
+
102
+ ### Zero dependencies, really
103
+
104
+ No tree-sitter, no language servers, no network. One `git clone` and a Python 3.11 interpreter; it
105
+ runs the same in CI, in a pre-commit hook and inside an agent sandbox.
106
+
107
+ ### Fast enough to run on every step
108
+
109
+ On a 3,000-file synthetic repo with a warm cache, `outline` and `symbol` take about 0.05 s of CPU
110
+ and `map`, `search`, `impact` and `brief` between 0.16 and 0.28 s (an Apple-silicon laptop;
111
+ [docs/pilots.md](docs/pilots.md) has the tables and how they were measured).
112
+
113
+ ### Link, don't restate
114
+
115
+ `init` finds the repo's existing rule files (CLAUDE.md, AGENTS.md, ARCHITECTURE.md,
116
+ REPO_MAP.md...) and links them instead of copying their content.
117
+
118
+ ## Install
119
+
120
+ Either of these works:
121
+
122
+ ```bash
123
+ git clone https://github.com/tipoLi5890/topomark ~/tools/topomark
124
+ ~/tools/topomark/bin/topomark --version # self-locating launcher, no install step
125
+ ```
126
+
127
+ Put `~/tools/topomark/bin` on your `PATH` (e.g. `ln -s ~/tools/topomark/bin/topomark ~/.local/bin/topomark`).
128
+ Or install the command from PyPI with pipx (pipx is not required; `pip install topomark` works too):
129
+
130
+ ```bash
131
+ pipx install topomark
132
+ ```
133
+
134
+ `bin/topomark` finds a Python 3.11+ interpreter itself (`python3.14` down to `python3`). It needs
135
+ `git` on `PATH`.
136
+
137
+ **As an agent plugin.** The repo is a Claude Code plugin and marketplace (`.claude-plugin/`) and a
138
+ Codex plugin (`.codex-plugin/`), bundling one skill, [`skills/topomark`](skills/topomark/SKILL.md).
139
+ In Claude Code: `/plugin marketplace add tipoLi5890/topomark`, then `/plugin install
140
+ topomark@topomark`. The plugin also brings three hooks: a short code-map pointer at session start, a
141
+ hint before reading a large file or a new area, and a syntax check after each edit (see
142
+ [Using it from an agent](#using-it-from-an-agent)).
143
+
144
+ ## Quickstart
145
+
146
+ **Navigate** (no setup at all):
147
+
148
+ ```bash
149
+ topomark map --tokens 2000
150
+ topomark outline src/core/router.py --exported-only
151
+ topomark symbol src/core/router.py#Router.add
152
+ topomark symbol src/core/router.py#Router --skeleton
153
+ topomark outline src/core/ --tokens 1200
154
+ topomark find Router --exact
155
+ topomark search route handler registration
156
+ topomark locate "no such file: src/app.py"
157
+ topomark locate --trace crash.txt
158
+ topomark refs Router --no-tests
159
+ topomark impact Router
160
+ topomark brief src/core/router.py
161
+ topomark tests-for --since main
162
+ topomark syntax
163
+ topomark changes --staged
164
+ ```
165
+
166
+ **Build a code map** that stays honest:
167
+
168
+ ```bash
169
+ cd your-repo
170
+ topomark doctor # Python, git, config, tracked secrets
171
+ topomark init --dry-run # the proposed areas, excludes and files; writes nothing
172
+ topomark init # write topomark.toml and the code-map skeleton
173
+ topomark draft backend --write # rows for one area, summary and fan-in prefilled; then edit them
174
+ topomark gen # generated fan-in table and module graph
175
+ topomark stamp --baseline # once, after the rows were read
176
+ topomark check # from now on: is the map in sync with the code?
177
+ topomark hook install # optional pre-commit gate
178
+ ```
179
+
180
+ ## Using it from an agent
181
+
182
+ The bundled skill teaches the loop: read L0, read one area file, `outline`, `symbol`; `brief` before
183
+ an edit, `syntax` after it; run what `tests-for` prints; `changes` before committing; then `check` /
184
+ `diff` / `stamp`. It works without slash commands or a plugin runtime: every step is a shell
185
+ command, so the same instructions work in Claude Code, Codex or any agent with a terminal. An
186
+ `AGENTS.md` or `CLAUDE.md` line is enough:
187
+
188
+ ```text
189
+ Navigate with topomark: read docs/codemap/README.md first, then `topomark outline <file>` and
190
+ `topomark symbol <file>#<Name>` instead of reading whole files; `topomark brief <file>` before an
191
+ edit. After editing, run `topomark syntax`, run what `topomark tests-for --diff` prints and keep
192
+ `topomark check` green.
193
+ ```
194
+
195
+ **Claude Code plugin hooks.** Installed as a plugin, topomark also registers three hooks
196
+ (`hooks/hooks.json`) that only add context and never block a tool call:
197
+
198
+ - **SessionStart** (startup, clear, compact): the L0 path, each area's name and file, one line of
199
+ navigation commands and whether review stamps exist; at most 40 lines. Without a code map, one line
200
+ suggesting `topomark map --tokens 2000`.
201
+ - **PreToolUse on Read**: a file over 400 lines gets a pointer to `outline` and `symbol --skeleton`;
202
+ the first file read in an area, a pointer to its area file. Each hint once per session; ranged
203
+ reads get none.
204
+ - **PostToolUse on Edit, Write, MultiEdit**: the `syntax` check of the edited file, reported only when
205
+ the edit broke it.
206
+
207
+ Each costs one short process (about 0.15 to 0.3 s of CPU on a 3,000-file repo). topomark ships hooks for Claude Code
208
+ only; elsewhere the skill says to run `topomark syntax --diff` after every edit. Details:
209
+ [adoption.md](skills/topomark/reference/adoption.md#claude-code-plugin-hooks).
210
+
211
+ ## Commands
212
+
213
+ **Navigation**: read-only, any git repo, no setup. In the order an agent meets them: orient, find,
214
+ look before an edit, check after it.
215
+
216
+ | Command | What it does |
217
+ |---|---|
218
+ | `map` | ranked repo map within a token budget, for a repo without a code map (`--focus`, `--tokens`, `--area`) |
219
+ | `outline <path>..` | symbols with line ranges, kinds, signatures, doc summaries; several files or a directory at once, top level within a token budget (`--exported-only`, `--kinds`, `--depth`, `--tokens`) |
220
+ | `symbol <file>#<Name>` / `symbol <Name>` | print one symbol's source (`--signature`, `--skeleton` for declarations with bodies elided, `--context N`) |
221
+ | `find <Name>` | definitions by name (`--kind`, `--exact`, `--limit`) |
222
+ | `search <keywords>` | code by what it is about: BM25 over symbol names, signatures, docs and paths; a matching test leads to the code it uses. Give keywords, not a pasted issue (`--limit`, `--area`, `--tokens`) |
223
+ | `locate "<message>"` / `locate --trace [FILE]` | the code behind an error message (literal word runs, so interpolated values still match) or a stack trace (Python, Node, Java/Kotlin, C#, Dart, Go, Rust, `path:line`), code before tests before docs (`--regex`, `--limit`) |
224
+ | `owner <path>` | the owning area, unit, fan-in and stamp state |
225
+ | `refs <Name>` | reference sites, comments and strings excluded; text shows group counts and the first 20 (`--area`, `--no-tests`, `--limit`) |
226
+ | `impact <Name or file>` | callers, importers, cross-area users, tests and docs a change reaches (`--top`) |
227
+ | `brief <file or Name>` | one briefing before an edit, within a token budget: area row, outline, most-coupled callers, tests and the command that runs them (`--tokens`) |
228
+ | `syntax [paths]` | do the edited files still parse: Python, JSON and TOML exactly, bracket balance in brace languages (only when HEAD was balanced); exit 1 on findings (`--diff`, the default) |
229
+ | `tests-for [paths]` | tests covering changed files, through their callers when no test names them, as runnable commands (`--diff`, `--staged`, `--since REV`, `--depth N`) |
230
+ | `changes` | the symbols a diff touches, interface (added, removed, new signature) or body, who still references the changed interfaces, tests to run, code-map rows to review (`--staged`, `--since REV`, `--top`) |
231
+
232
+ **Code map**: writes only `topomark.toml` and `docs_dir`.
233
+
234
+ | Command | What it does |
235
+ |---|---|
236
+ | `init` | detect the stack and write the code-map skeleton (`--dry-run`, `--docs-dir`, `--force`) |
237
+ | `draft <area>` | rows an area file is missing, prefilled (`--write`) |
238
+ | `check` | coverage, dead paths, ownership, line caps, fan-in, generated files, stamps (`--area`, `--no-stamps`) |
239
+ | `stale` | rows needing review (blocking) and body-only changes (advisory) (`--area`) |
240
+ | `diff <unit>` | what changed since the unit's review stamp, interface first |
241
+ | `stamp` | record a review (`<units>`, `--area`, `--edges`, `--prune`, `--baseline`, `--force` with it) |
242
+ | `gen` | regenerate `<docs_dir>/_generated/` |
243
+ | `sync` | rewrite the fan-in numbers written in area files |
244
+
245
+ **Hooks and tooling**
246
+
247
+ | Command | What it does |
248
+ |---|---|
249
+ | `hook install\|uninstall\|status` | opt-in git pre-commit gate running `check` |
250
+ | `agent-hook session-start\|pre-read\|post-edit` | what the Claude Code plugin's hooks run: reads the hook JSON on stdin, answers in the hook protocol, always exits 0 |
251
+ | `doctor` | environment and repository health |
252
+ | `capabilities` | every command and flag, from the live parser (use `--json`) |
253
+
254
+ Global flags work before or after the command: `--json`, `-C/--repo DIR`, `--config PATH`, `-q`,
255
+ `-v`, `--debug`.
256
+
257
+ ## Languages
258
+
259
+ | | |
260
+ |---|---|
261
+ | **Symbols** (`outline`, `symbol`, `find`) | Python, JavaScript and TypeScript (JSX and TSX included), C#, Java, Kotlin, Swift, Dart, Go, Rust, C, C++ and Objective-C, shell, SQL, data files (JSON, JSONC, JSON5, TOML, YAML, Unity `.asmdef`) and Markdown |
262
+ | **Import edges** (who imports this file, and the walk from a changed file to its tests) | Python, JS/TS, C-family `#include "x.h"`, Dart, Go, Rust, Java and Kotlin. C# and Swift name namespaces and modules, not files, so there topomark has name references only |
263
+ | **Plain text** | other extensions named in `required_ext`: no symbols, and the whole text is the review surface |
264
+ | **No adapter** | Ruby, PHP, Scala, Lua or Elixir, among others: `outline`, `symbol` and `find` have nothing to show there, while `locate` and `search` over paths still work |
265
+
266
+ ## Configuration
267
+
268
+ Everything is optional. `topomark.toml` at the repo root:
269
+
270
+ ```toml
271
+ [topomark]
272
+ docs_dir = "docs/codemap"
273
+
274
+ [files]
275
+ exclude = ["**/l10n/app_localizations*.dart"]
276
+
277
+ [[tests.runner]]
278
+ match = "tests/"
279
+ command = "python3 -m unittest {names}"
280
+ names = "file"
281
+ ```
282
+
283
+ Areas are not configured here: each area file's frontmatter (`scope`, `granularity`) is the single
284
+ source of truth. Full reference: [docs/config.md](docs/config.md). Concepts (layers, ownership,
285
+ units, stamps, fan-in): [docs/concepts.md](docs/concepts.md).
286
+
287
+ ## Built for scripts: exit codes and JSON
288
+
289
+ | Exit | Meaning |
290
+ |---|---|
291
+ | 0 | ok |
292
+ | 1 | findings (`check`, `stale`, `doctor`, `syntax`): the tool worked and found problems |
293
+ | 2 | usage error, or a refused action that would lose information |
294
+ | 3 | invalid `topomark.toml` |
295
+ | 4 | path, symbol or area not found |
296
+ | 5 | no language adapter for the operation |
297
+ | 6 | not inside a git work tree |
298
+ | 7 | internal error (rerun with `--debug`) |
299
+
300
+ `--json` prints exactly one JSON object on stdout, stamped `"schema_version": "topomark/1"` and
301
+ `"command"`. Errors print `{"error": {"code", "message", "exit", "remediation"}}`, also on stdout.
302
+ `agent-hook` is the one exception: it answers in the Claude Code hook protocol and always exits 0.
303
+
304
+ ## Design notes and honest limits
305
+
306
+ - **Files come from git**, never from a directory walk: what `.gitignore` excludes is already out.
307
+ - **Secret-looking paths are never read** (`.env`, `*.pem`, `keys/`, `credentials*`...), and the
308
+ list cannot be switched off. `doctor` warns about secrets git tracks.
309
+ - **Parsing is lexical, not semantic.** Adapters mask comments and strings, track scopes and read
310
+ declarations; references are identifier matches. That makes `refs` a superset and `fan-in`
311
+ approximate, and keeps the tool fast, dependency-free and tolerant of code that doesn't compile.
312
+ - **The surface hash ignores bodies** so refactors inside a function don't demand a review, while a
313
+ new public method, a changed constant or a rewritten header comment does.
314
+ - **The cache lives outside the repo** (`$TOPOMARK_CACHE`, `$XDG_CACHE_HOME/topomark`,
315
+ on Windows `%LOCALAPPDATA%\topomark\Cache`, else `~/.cache/topomark`), keyed by file mtime and size and dropped when the adapters change. It is
316
+ sharded, so a single-file `outline` costs the same in a 3,000-file repo as in a small one, and the
317
+ first whole-repo command on a large repository parses in worker processes (`TOPOMARK_JOBS`). The
318
+ plugin hooks keep their once-per-session markers there too.
319
+
320
+ ## Acknowledgments
321
+
322
+ topomark borrows ideas, not code. The ranked repository map follows [Aider's repo
323
+ map](https://aider.chat/docs/repomap.html) (Apache-2.0); the symbol-level tools follow
324
+ [Serena](https://github.com/oraios/serena) (GPL-3.0-or-later); the impact summary was inspired by
325
+ [GitNexus](https://github.com/abhigyanpatwari/GitNexus)'s impact analysis (PolyForm Noncommercial:
326
+ concepts only). **topomark copies no code from any of them.** Details:
327
+ [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md).
328
+
329
+ ## Contributing, security, license
330
+
331
+ [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [CHANGELOG.md](CHANGELOG.md) ·
332
+ MIT, see [LICENSE](LICENSE). Copyright (c) 2026 Li, ching yu.
@@ -0,0 +1,308 @@
1
+ # topomark
2
+
3
+ **Your agent reads a 2,000-line file to find one function. Give it a map instead.**
4
+
5
+ topomark is a zero-dependency code map for AI coding agents: layered docs that say where to look,
6
+ review stamps that fail CI when a summary goes stale, and fast symbol, impact and test navigation
7
+ for any git repository. Python 3.11+ standard library only; offline; read-only on your code.
8
+
9
+ ![license: MIT](https://img.shields.io/badge/license-MIT-blue)
10
+ ![python: 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
11
+ ![dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen)
12
+
13
+ [繁體中文](.github/README.zh-Hant.md) · [简体中文](.github/README.zh-Hans.md) · [日本語](.github/README.ja.md)
14
+
15
+ ## Let your agent install it
16
+
17
+ Paste this into Claude Code, Codex or any coding agent with a terminal, from inside your repository:
18
+
19
+ ```text
20
+ Install topomark (https://github.com/tipoLi5890/topomark), a zero-dependency code map and
21
+ navigation CLI, and set this repository up to use it:
22
+
23
+ 1. Clone it: git clone https://github.com/tipoLi5890/topomark ~/tools/topomark
24
+ (if that directory exists, run git -C ~/tools/topomark pull instead).
25
+ 2. Put it on PATH: ln -sf ~/tools/topomark/bin/topomark ~/.local/bin/topomark, and make sure
26
+ ~/.local/bin is on PATH. Check with topomark --version (it needs Python 3.11+ and git).
27
+ 3. Run topomark doctor in this repository and tell me about any problem it reports.
28
+ 4. Read ~/tools/topomark/skills/topomark/SKILL.md and follow it from now on.
29
+ 5. Add this line to AGENTS.md, or to CLAUDE.md if that is what the repository uses:
30
+ "Navigate with topomark: read docs/codemap/README.md first, then `topomark outline <file>` and
31
+ `topomark symbol <file>#<Name>` instead of reading whole files; `topomark brief <file>` before
32
+ an edit. After editing, run `topomark syntax`, run what `topomark tests-for --diff` prints and
33
+ keep `topomark check` green."
34
+ 6. Run topomark init --dry-run and show me the proposed areas. Write nothing else until I agree;
35
+ then run topomark init and topomark draft <area> --write for each area, and fill in the rows.
36
+ ```
37
+
38
+ Until a code map exists, `topomark map --tokens 2000` and the other navigation commands already
39
+ work; step 6 is what makes `check` and review stamps possible.
40
+
41
+ ## Try it in 30 seconds
42
+
43
+ Navigation needs no setup, no config and no index to build. Clone, then point it at any git repo:
44
+
45
+ ```bash
46
+ git clone https://github.com/tipoLi5890/topomark ~/tools/topomark
47
+ cd your-repo
48
+ ~/tools/topomark/bin/topomark map --tokens 2000 # a ranked map of the repo, within a token budget
49
+ ```
50
+
51
+ Nothing is installed and nothing is written to your repository.
52
+
53
+ ## Why topomark
54
+
55
+ ### A ladder, not a haystack
56
+
57
+ Agents spend much of their context reading whole files to find one function. topomark gives them
58
+ rungs, each small enough to read in full:
59
+
60
+ ```text
61
+ L0 docs/codemap/README.md one index: the areas of the repo and what each owns
62
+ L1 docs/codemap/<area>.md one row per file: what it does, how many files depend on it,
63
+ what to update when it changes
64
+ L2 the code, by symbol topomark outline / symbol / refs: one function, not the file
65
+ ```
66
+
67
+ ### Review stamps, not timestamps
68
+
69
+ Hand-written maps rot silently. So topomark stores, per file, a hash of its *interface* (header
70
+ comment, public signatures, constants) at the moment its row was reviewed.
71
+
72
+ - Change an interface without reviewing the row: `topomark check` fails.
73
+ - Change only a function body: it stays quiet.
74
+
75
+ A "last updated" date can't tell those two apart. A stamp can, so the map is either current or CI
76
+ says exactly which rows are not.
77
+
78
+ ### Zero dependencies, really
79
+
80
+ No tree-sitter, no language servers, no network. One `git clone` and a Python 3.11 interpreter; it
81
+ runs the same in CI, in a pre-commit hook and inside an agent sandbox.
82
+
83
+ ### Fast enough to run on every step
84
+
85
+ On a 3,000-file synthetic repo with a warm cache, `outline` and `symbol` take about 0.05 s of CPU
86
+ and `map`, `search`, `impact` and `brief` between 0.16 and 0.28 s (an Apple-silicon laptop;
87
+ [docs/pilots.md](docs/pilots.md) has the tables and how they were measured).
88
+
89
+ ### Link, don't restate
90
+
91
+ `init` finds the repo's existing rule files (CLAUDE.md, AGENTS.md, ARCHITECTURE.md,
92
+ REPO_MAP.md...) and links them instead of copying their content.
93
+
94
+ ## Install
95
+
96
+ Either of these works:
97
+
98
+ ```bash
99
+ git clone https://github.com/tipoLi5890/topomark ~/tools/topomark
100
+ ~/tools/topomark/bin/topomark --version # self-locating launcher, no install step
101
+ ```
102
+
103
+ Put `~/tools/topomark/bin` on your `PATH` (e.g. `ln -s ~/tools/topomark/bin/topomark ~/.local/bin/topomark`).
104
+ Or install the command from PyPI with pipx (pipx is not required; `pip install topomark` works too):
105
+
106
+ ```bash
107
+ pipx install topomark
108
+ ```
109
+
110
+ `bin/topomark` finds a Python 3.11+ interpreter itself (`python3.14` down to `python3`). It needs
111
+ `git` on `PATH`.
112
+
113
+ **As an agent plugin.** The repo is a Claude Code plugin and marketplace (`.claude-plugin/`) and a
114
+ Codex plugin (`.codex-plugin/`), bundling one skill, [`skills/topomark`](skills/topomark/SKILL.md).
115
+ In Claude Code: `/plugin marketplace add tipoLi5890/topomark`, then `/plugin install
116
+ topomark@topomark`. The plugin also brings three hooks: a short code-map pointer at session start, a
117
+ hint before reading a large file or a new area, and a syntax check after each edit (see
118
+ [Using it from an agent](#using-it-from-an-agent)).
119
+
120
+ ## Quickstart
121
+
122
+ **Navigate** (no setup at all):
123
+
124
+ ```bash
125
+ topomark map --tokens 2000
126
+ topomark outline src/core/router.py --exported-only
127
+ topomark symbol src/core/router.py#Router.add
128
+ topomark symbol src/core/router.py#Router --skeleton
129
+ topomark outline src/core/ --tokens 1200
130
+ topomark find Router --exact
131
+ topomark search route handler registration
132
+ topomark locate "no such file: src/app.py"
133
+ topomark locate --trace crash.txt
134
+ topomark refs Router --no-tests
135
+ topomark impact Router
136
+ topomark brief src/core/router.py
137
+ topomark tests-for --since main
138
+ topomark syntax
139
+ topomark changes --staged
140
+ ```
141
+
142
+ **Build a code map** that stays honest:
143
+
144
+ ```bash
145
+ cd your-repo
146
+ topomark doctor # Python, git, config, tracked secrets
147
+ topomark init --dry-run # the proposed areas, excludes and files; writes nothing
148
+ topomark init # write topomark.toml and the code-map skeleton
149
+ topomark draft backend --write # rows for one area, summary and fan-in prefilled; then edit them
150
+ topomark gen # generated fan-in table and module graph
151
+ topomark stamp --baseline # once, after the rows were read
152
+ topomark check # from now on: is the map in sync with the code?
153
+ topomark hook install # optional pre-commit gate
154
+ ```
155
+
156
+ ## Using it from an agent
157
+
158
+ The bundled skill teaches the loop: read L0, read one area file, `outline`, `symbol`; `brief` before
159
+ an edit, `syntax` after it; run what `tests-for` prints; `changes` before committing; then `check` /
160
+ `diff` / `stamp`. It works without slash commands or a plugin runtime: every step is a shell
161
+ command, so the same instructions work in Claude Code, Codex or any agent with a terminal. An
162
+ `AGENTS.md` or `CLAUDE.md` line is enough:
163
+
164
+ ```text
165
+ Navigate with topomark: read docs/codemap/README.md first, then `topomark outline <file>` and
166
+ `topomark symbol <file>#<Name>` instead of reading whole files; `topomark brief <file>` before an
167
+ edit. After editing, run `topomark syntax`, run what `topomark tests-for --diff` prints and keep
168
+ `topomark check` green.
169
+ ```
170
+
171
+ **Claude Code plugin hooks.** Installed as a plugin, topomark also registers three hooks
172
+ (`hooks/hooks.json`) that only add context and never block a tool call:
173
+
174
+ - **SessionStart** (startup, clear, compact): the L0 path, each area's name and file, one line of
175
+ navigation commands and whether review stamps exist; at most 40 lines. Without a code map, one line
176
+ suggesting `topomark map --tokens 2000`.
177
+ - **PreToolUse on Read**: a file over 400 lines gets a pointer to `outline` and `symbol --skeleton`;
178
+ the first file read in an area, a pointer to its area file. Each hint once per session; ranged
179
+ reads get none.
180
+ - **PostToolUse on Edit, Write, MultiEdit**: the `syntax` check of the edited file, reported only when
181
+ the edit broke it.
182
+
183
+ Each costs one short process (about 0.15 to 0.3 s of CPU on a 3,000-file repo). topomark ships hooks for Claude Code
184
+ only; elsewhere the skill says to run `topomark syntax --diff` after every edit. Details:
185
+ [adoption.md](skills/topomark/reference/adoption.md#claude-code-plugin-hooks).
186
+
187
+ ## Commands
188
+
189
+ **Navigation**: read-only, any git repo, no setup. In the order an agent meets them: orient, find,
190
+ look before an edit, check after it.
191
+
192
+ | Command | What it does |
193
+ |---|---|
194
+ | `map` | ranked repo map within a token budget, for a repo without a code map (`--focus`, `--tokens`, `--area`) |
195
+ | `outline <path>..` | symbols with line ranges, kinds, signatures, doc summaries; several files or a directory at once, top level within a token budget (`--exported-only`, `--kinds`, `--depth`, `--tokens`) |
196
+ | `symbol <file>#<Name>` / `symbol <Name>` | print one symbol's source (`--signature`, `--skeleton` for declarations with bodies elided, `--context N`) |
197
+ | `find <Name>` | definitions by name (`--kind`, `--exact`, `--limit`) |
198
+ | `search <keywords>` | code by what it is about: BM25 over symbol names, signatures, docs and paths; a matching test leads to the code it uses. Give keywords, not a pasted issue (`--limit`, `--area`, `--tokens`) |
199
+ | `locate "<message>"` / `locate --trace [FILE]` | the code behind an error message (literal word runs, so interpolated values still match) or a stack trace (Python, Node, Java/Kotlin, C#, Dart, Go, Rust, `path:line`), code before tests before docs (`--regex`, `--limit`) |
200
+ | `owner <path>` | the owning area, unit, fan-in and stamp state |
201
+ | `refs <Name>` | reference sites, comments and strings excluded; text shows group counts and the first 20 (`--area`, `--no-tests`, `--limit`) |
202
+ | `impact <Name or file>` | callers, importers, cross-area users, tests and docs a change reaches (`--top`) |
203
+ | `brief <file or Name>` | one briefing before an edit, within a token budget: area row, outline, most-coupled callers, tests and the command that runs them (`--tokens`) |
204
+ | `syntax [paths]` | do the edited files still parse: Python, JSON and TOML exactly, bracket balance in brace languages (only when HEAD was balanced); exit 1 on findings (`--diff`, the default) |
205
+ | `tests-for [paths]` | tests covering changed files, through their callers when no test names them, as runnable commands (`--diff`, `--staged`, `--since REV`, `--depth N`) |
206
+ | `changes` | the symbols a diff touches, interface (added, removed, new signature) or body, who still references the changed interfaces, tests to run, code-map rows to review (`--staged`, `--since REV`, `--top`) |
207
+
208
+ **Code map**: writes only `topomark.toml` and `docs_dir`.
209
+
210
+ | Command | What it does |
211
+ |---|---|
212
+ | `init` | detect the stack and write the code-map skeleton (`--dry-run`, `--docs-dir`, `--force`) |
213
+ | `draft <area>` | rows an area file is missing, prefilled (`--write`) |
214
+ | `check` | coverage, dead paths, ownership, line caps, fan-in, generated files, stamps (`--area`, `--no-stamps`) |
215
+ | `stale` | rows needing review (blocking) and body-only changes (advisory) (`--area`) |
216
+ | `diff <unit>` | what changed since the unit's review stamp, interface first |
217
+ | `stamp` | record a review (`<units>`, `--area`, `--edges`, `--prune`, `--baseline`, `--force` with it) |
218
+ | `gen` | regenerate `<docs_dir>/_generated/` |
219
+ | `sync` | rewrite the fan-in numbers written in area files |
220
+
221
+ **Hooks and tooling**
222
+
223
+ | Command | What it does |
224
+ |---|---|
225
+ | `hook install\|uninstall\|status` | opt-in git pre-commit gate running `check` |
226
+ | `agent-hook session-start\|pre-read\|post-edit` | what the Claude Code plugin's hooks run: reads the hook JSON on stdin, answers in the hook protocol, always exits 0 |
227
+ | `doctor` | environment and repository health |
228
+ | `capabilities` | every command and flag, from the live parser (use `--json`) |
229
+
230
+ Global flags work before or after the command: `--json`, `-C/--repo DIR`, `--config PATH`, `-q`,
231
+ `-v`, `--debug`.
232
+
233
+ ## Languages
234
+
235
+ | | |
236
+ |---|---|
237
+ | **Symbols** (`outline`, `symbol`, `find`) | Python, JavaScript and TypeScript (JSX and TSX included), C#, Java, Kotlin, Swift, Dart, Go, Rust, C, C++ and Objective-C, shell, SQL, data files (JSON, JSONC, JSON5, TOML, YAML, Unity `.asmdef`) and Markdown |
238
+ | **Import edges** (who imports this file, and the walk from a changed file to its tests) | Python, JS/TS, C-family `#include "x.h"`, Dart, Go, Rust, Java and Kotlin. C# and Swift name namespaces and modules, not files, so there topomark has name references only |
239
+ | **Plain text** | other extensions named in `required_ext`: no symbols, and the whole text is the review surface |
240
+ | **No adapter** | Ruby, PHP, Scala, Lua or Elixir, among others: `outline`, `symbol` and `find` have nothing to show there, while `locate` and `search` over paths still work |
241
+
242
+ ## Configuration
243
+
244
+ Everything is optional. `topomark.toml` at the repo root:
245
+
246
+ ```toml
247
+ [topomark]
248
+ docs_dir = "docs/codemap"
249
+
250
+ [files]
251
+ exclude = ["**/l10n/app_localizations*.dart"]
252
+
253
+ [[tests.runner]]
254
+ match = "tests/"
255
+ command = "python3 -m unittest {names}"
256
+ names = "file"
257
+ ```
258
+
259
+ Areas are not configured here: each area file's frontmatter (`scope`, `granularity`) is the single
260
+ source of truth. Full reference: [docs/config.md](docs/config.md). Concepts (layers, ownership,
261
+ units, stamps, fan-in): [docs/concepts.md](docs/concepts.md).
262
+
263
+ ## Built for scripts: exit codes and JSON
264
+
265
+ | Exit | Meaning |
266
+ |---|---|
267
+ | 0 | ok |
268
+ | 1 | findings (`check`, `stale`, `doctor`, `syntax`): the tool worked and found problems |
269
+ | 2 | usage error, or a refused action that would lose information |
270
+ | 3 | invalid `topomark.toml` |
271
+ | 4 | path, symbol or area not found |
272
+ | 5 | no language adapter for the operation |
273
+ | 6 | not inside a git work tree |
274
+ | 7 | internal error (rerun with `--debug`) |
275
+
276
+ `--json` prints exactly one JSON object on stdout, stamped `"schema_version": "topomark/1"` and
277
+ `"command"`. Errors print `{"error": {"code", "message", "exit", "remediation"}}`, also on stdout.
278
+ `agent-hook` is the one exception: it answers in the Claude Code hook protocol and always exits 0.
279
+
280
+ ## Design notes and honest limits
281
+
282
+ - **Files come from git**, never from a directory walk: what `.gitignore` excludes is already out.
283
+ - **Secret-looking paths are never read** (`.env`, `*.pem`, `keys/`, `credentials*`...), and the
284
+ list cannot be switched off. `doctor` warns about secrets git tracks.
285
+ - **Parsing is lexical, not semantic.** Adapters mask comments and strings, track scopes and read
286
+ declarations; references are identifier matches. That makes `refs` a superset and `fan-in`
287
+ approximate, and keeps the tool fast, dependency-free and tolerant of code that doesn't compile.
288
+ - **The surface hash ignores bodies** so refactors inside a function don't demand a review, while a
289
+ new public method, a changed constant or a rewritten header comment does.
290
+ - **The cache lives outside the repo** (`$TOPOMARK_CACHE`, `$XDG_CACHE_HOME/topomark`,
291
+ on Windows `%LOCALAPPDATA%\topomark\Cache`, else `~/.cache/topomark`), keyed by file mtime and size and dropped when the adapters change. It is
292
+ sharded, so a single-file `outline` costs the same in a 3,000-file repo as in a small one, and the
293
+ first whole-repo command on a large repository parses in worker processes (`TOPOMARK_JOBS`). The
294
+ plugin hooks keep their once-per-session markers there too.
295
+
296
+ ## Acknowledgments
297
+
298
+ topomark borrows ideas, not code. The ranked repository map follows [Aider's repo
299
+ map](https://aider.chat/docs/repomap.html) (Apache-2.0); the symbol-level tools follow
300
+ [Serena](https://github.com/oraios/serena) (GPL-3.0-or-later); the impact summary was inspired by
301
+ [GitNexus](https://github.com/abhigyanpatwari/GitNexus)'s impact analysis (PolyForm Noncommercial:
302
+ concepts only). **topomark copies no code from any of them.** Details:
303
+ [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md).
304
+
305
+ ## Contributing, security, license
306
+
307
+ [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [CHANGELOG.md](CHANGELOG.md) ·
308
+ MIT, see [LICENSE](LICENSE). Copyright (c) 2026 Li, ching yu.