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.
- topomark-0.4.0/LICENSE +21 -0
- topomark-0.4.0/PKG-INFO +332 -0
- topomark-0.4.0/README.md +308 -0
- topomark-0.4.0/pyproject.toml +62 -0
- topomark-0.4.0/setup.cfg +4 -0
- topomark-0.4.0/src/topomark/__init__.py +31 -0
- topomark-0.4.0/src/topomark/__main__.py +3 -0
- topomark-0.4.0/src/topomark/changes.py +169 -0
- topomark-0.4.0/src/topomark/cli.py +209 -0
- topomark-0.4.0/src/topomark/commands/__init__.py +53 -0
- topomark-0.4.0/src/topomark/commands/_common.py +27 -0
- topomark-0.4.0/src/topomark/commands/agent_hook.py +338 -0
- topomark-0.4.0/src/topomark/commands/brief.py +272 -0
- topomark-0.4.0/src/topomark/commands/capabilities.py +47 -0
- topomark-0.4.0/src/topomark/commands/changes.py +217 -0
- topomark-0.4.0/src/topomark/commands/check.py +41 -0
- topomark-0.4.0/src/topomark/commands/diff.py +81 -0
- topomark-0.4.0/src/topomark/commands/doctor.py +67 -0
- topomark-0.4.0/src/topomark/commands/draft.py +149 -0
- topomark-0.4.0/src/topomark/commands/find.py +64 -0
- topomark-0.4.0/src/topomark/commands/gen.py +33 -0
- topomark-0.4.0/src/topomark/commands/hook.py +104 -0
- topomark-0.4.0/src/topomark/commands/impact.py +82 -0
- topomark-0.4.0/src/topomark/commands/init.py +609 -0
- topomark-0.4.0/src/topomark/commands/locate.py +109 -0
- topomark-0.4.0/src/topomark/commands/map.py +140 -0
- topomark-0.4.0/src/topomark/commands/outline.py +143 -0
- topomark-0.4.0/src/topomark/commands/owner.py +44 -0
- topomark-0.4.0/src/topomark/commands/refs.py +72 -0
- topomark-0.4.0/src/topomark/commands/search.py +82 -0
- topomark-0.4.0/src/topomark/commands/stale.py +49 -0
- topomark-0.4.0/src/topomark/commands/stamp.py +91 -0
- topomark-0.4.0/src/topomark/commands/symbol.py +98 -0
- topomark-0.4.0/src/topomark/commands/sync.py +38 -0
- topomark-0.4.0/src/topomark/commands/syntax.py +61 -0
- topomark-0.4.0/src/topomark/commands/tests_for.py +96 -0
- topomark-0.4.0/src/topomark/config.py +188 -0
- topomark-0.4.0/src/topomark/context.py +58 -0
- topomark-0.4.0/src/topomark/contract.py +28 -0
- topomark-0.4.0/src/topomark/docs.py +174 -0
- topomark-0.4.0/src/topomark/errors.py +75 -0
- topomark-0.4.0/src/topomark/graph.py +133 -0
- topomark-0.4.0/src/topomark/imports.py +321 -0
- topomark-0.4.0/src/topomark/index.py +421 -0
- topomark-0.4.0/src/topomark/lang/__init__.py +0 -0
- topomark-0.4.0/src/topomark/lang/_decl.py +140 -0
- topomark-0.4.0/src/topomark/lang/_imports.py +82 -0
- topomark-0.4.0/src/topomark/lang/base.py +160 -0
- topomark-0.4.0/src/topomark/lang/brace.py +404 -0
- topomark-0.4.0/src/topomark/lang/cfamily.py +340 -0
- topomark-0.4.0/src/topomark/lang/csharp.py +275 -0
- topomark-0.4.0/src/topomark/lang/dart.py +119 -0
- topomark-0.4.0/src/topomark/lang/go.py +104 -0
- topomark-0.4.0/src/topomark/lang/js_ts.py +275 -0
- topomark-0.4.0/src/topomark/lang/kotlin.py +83 -0
- topomark-0.4.0/src/topomark/lang/python.py +235 -0
- topomark-0.4.0/src/topomark/lang/registry.py +72 -0
- topomark-0.4.0/src/topomark/lang/rust.py +117 -0
- topomark-0.4.0/src/topomark/lang/scan.py +466 -0
- topomark-0.4.0/src/topomark/lang/simple.py +408 -0
- topomark-0.4.0/src/topomark/lang/swift.py +91 -0
- topomark-0.4.0/src/topomark/locate.py +342 -0
- topomark-0.4.0/src/topomark/masking.py +36 -0
- topomark-0.4.0/src/topomark/navigate.py +536 -0
- topomark-0.4.0/src/topomark/ranking.py +115 -0
- topomark-0.4.0/src/topomark/repo.py +376 -0
- topomark-0.4.0/src/topomark/runners.py +167 -0
- topomark-0.4.0/src/topomark/search.py +426 -0
- topomark-0.4.0/src/topomark/stamps.py +118 -0
- topomark-0.4.0/src/topomark/syntax.py +288 -0
- topomark-0.4.0/src/topomark/templates/L0.md +82 -0
- topomark-0.4.0/src/topomark/templates/_TEMPLATE.md +67 -0
- topomark-0.4.0/src/topomark/templates/__init__.py +5 -0
- topomark-0.4.0/src/topomark/templates/area.md +30 -0
- topomark-0.4.0/src/topomark/testsel.py +291 -0
- topomark-0.4.0/src/topomark/workspace.py +436 -0
- topomark-0.4.0/src/topomark.egg-info/PKG-INFO +332 -0
- topomark-0.4.0/src/topomark.egg-info/SOURCES.txt +96 -0
- topomark-0.4.0/src/topomark.egg-info/dependency_links.txt +1 -0
- topomark-0.4.0/src/topomark.egg-info/entry_points.txt +2 -0
- topomark-0.4.0/src/topomark.egg-info/top_level.txt +1 -0
- topomark-0.4.0/tests/test_agent_hook.py +290 -0
- topomark-0.4.0/tests/test_brief.py +121 -0
- topomark-0.4.0/tests/test_cache.py +245 -0
- topomark-0.4.0/tests/test_changes.py +189 -0
- topomark-0.4.0/tests/test_docsystem.py +301 -0
- topomark-0.4.0/tests/test_init_draft.py +231 -0
- topomark-0.4.0/tests/test_lang.py +676 -0
- topomark-0.4.0/tests/test_lang_scan.py +136 -0
- topomark-0.4.0/tests/test_locate.py +182 -0
- topomark-0.4.0/tests/test_meta.py +324 -0
- topomark-0.4.0/tests/test_navigation.py +736 -0
- topomark-0.4.0/tests/test_output_economy.py +149 -0
- topomark-0.4.0/tests/test_regressions.py +37 -0
- topomark-0.4.0/tests/test_safety.py +446 -0
- topomark-0.4.0/tests/test_search.py +117 -0
- topomark-0.4.0/tests/test_syntax.py +109 -0
- 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.
|
topomark-0.4.0/PKG-INFO
ADDED
|
@@ -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
|
+

|
|
34
|
+

|
|
35
|
+

|
|
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.
|
topomark-0.4.0/README.md
ADDED
|
@@ -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
|
+

|
|
10
|
+

|
|
11
|
+

|
|
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.
|