@iasonas/codearch 0.3.0 → 0.3.1

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 (4) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +118 -118
  3. package/npm-shrinkwrap.json +2 -2
  4. package/package.json +3 -3
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Iasonassss0007
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.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Iasonassss0007
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.
package/README.md CHANGED
@@ -1,118 +1,118 @@
1
- # codearch
2
-
3
- Local code lookups for coding agents. `codearch` indexes a repository on your machine
4
- and answers three questions agents otherwise answer by grepping and guessing:
5
-
6
- - **Who imports this file?** Directly and transitively.
7
- - **What does this file import?**
8
- - **Which frontend files call this backend endpoint?** From a Django, Flask, or
9
- FastAPI route to the TypeScript files that request it. A route path works as
10
- well as a view name.
11
-
12
- Works with TypeScript, JavaScript, and Python, including `<script>` blocks in
13
- `.vue` and `.svelte` files, and monorepos (workspaces, tsconfig `paths` and
14
- `extends`).
15
-
16
- ## Install
17
-
18
- Pick one. Each installs a prebuilt binary for Windows, macOS, or Linux; no Rust needed.
19
-
20
- ```
21
- npm install -g codearch
22
- ```
23
-
24
- ```
25
- curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Iasonassss0007/Code-Arch/releases/latest/download/codearch-installer.sh | sh
26
- ```
27
-
28
- ```
29
- powershell -ExecutionPolicy Bypass -c "irm https://github.com/Iasonassss0007/Code-Arch/releases/latest/download/codearch-installer.ps1 | iex"
30
- ```
31
-
32
- From source (Rust 1.85 or newer): `cargo install --git https://github.com/Iasonassss0007/Code-Arch`.
33
-
34
- ### Teach your agent
35
-
36
- Pick the one that fits your setup:
37
-
38
- - **Skill** (Claude Code and other agents that read `SKILL.md`): `npx skills add Iasonassss0007/Code-Arch`,
39
- or copy [`skills/codearch/`](skills/codearch/SKILL.md) into `~/.claude/skills/`.
40
- The agent learns when to use each lookup and how to act on a stale index.
41
- - **MCP server**: `claude mcp add codearch -- codearch mcp --refresh`, run inside the repository.
42
- - **Per repository**: `codearch agents --write AGENTS.md` adds a short block that agents read.
43
-
44
- ## Use
45
-
46
- ```
47
- cd /path/to/repo
48
- codearch # build the index
49
- codearch importers src/lib/auth.ts # who depends on this file
50
- codearch deps src/lib/auth.ts # what this file imports
51
- codearch callers TagViewSet # which frontend files call this view
52
- codearch callers --path /tags/ # the same lookup by route path
53
- codearch agents --write AGENTS.md # tell your agents these lookups exist
54
- ```
55
-
56
- Add `--json` for machine-readable output. Re-run `codearch` when source files change.
57
- Also re-run it when `tsconfig.json`, `jsconfig.json`, `package.json`,
58
- `pnpm-workspace.yaml`, or `pyproject.toml` changes, and when an `extends` file
59
- inside the repository changes.
60
- Commit `.codearch/*.md` so a fresh clone can answer lookups right away
61
- (`.codearch/cache/` is ignored automatically).
62
-
63
- Every lookup says whether the index still matches those files: `fresh`, `stale` (with the
64
- changed files), or `unknown`. A fresh clone has no cache yet, so the lookup is unknown.
65
- A cache written by an older codearch is unknown too, until the next `codearch` run. The
66
- CLI prints this on stderr and `--json` adds a `freshness` object. Add `--refresh` to
67
- rebuild first when the answer would be stale or unknown.
68
-
69
- For MCP clients (Claude Code and others):
70
-
71
- ```
72
- claude mcp add codearch -- codearch mcp --repo /path/to/repo --refresh
73
- ```
74
-
75
- Each answer carries the same `freshness` object. With `--refresh` the server rebuilds a
76
- stale or unknown index before answering. Without it, the server never writes files.
77
-
78
- ## Results
79
-
80
- **Agents answer better with a lookup than with a codebase summary.** Asked "if I
81
- change this file, which files are affected?", models using the `codearch` lookup
82
- found the right files 98% of the time on navigation tasks and 100% on cross-language
83
- ones. With no help they scored 61% and 87%. A codebase map in the prompt did worse
84
- than no help. The lookup also cut the context read by 34–56% and the token cost by
85
- 18–77%.
86
-
87
- ![Answer quality: lookup tool 98% vs map 58% vs no help 61% on navigation; lookup tool 100% vs no help 87% on cross-language](docs/images/agent-quality.svg)
88
-
89
- Tested with Gemini models on Hono, Next.js Commerce, TypeDI and paperless-ngx. The
90
- cross-language result rests on one repository.
91
-
92
- **Cheaper than grep for transitive impact.** Context for one `codearch importers` call
93
- vs a batched grep search, one regex per depth
94
- ([`eval/grep_vs_codearch.py`](eval/grep_vs_codearch.py)):
95
-
96
- | Repo | grep | codearch | Ratio |
97
- |---|---:|---:|---:|
98
- | ~155 TS/JS files | 2,240 tokens | 1,152 tokens | 1.9x |
99
- | ~2,800 TS/JS/Python files | 148,757 tokens | 3,896 tokens | 38x |
100
-
101
- For a single direct-importer lookup, `grep -l` is just as good.
102
-
103
- **Accurate on a large monorepo.** On a pnpm monorepo with 245 packages, 99.8% of
104
- first-party imports resolve. Compared with the TypeScript compiler's import graph,
105
- codearch's transitive importers have 100% recall and 99.8–100% precision across five
106
- target files. Details are in
107
- [`eval/resolution_report.md`](eval/resolution_report.md).
108
-
109
- ## Development
110
-
111
- ```
112
- cargo test
113
- python -m pytest -q eval/test_*.py
114
- ```
115
-
116
- ## License
117
-
118
- [MIT](LICENSE)
1
+ # codearch
2
+
3
+ Local code lookups for coding agents. `codearch` indexes a repository on your machine
4
+ and answers three questions agents otherwise answer by grepping and guessing:
5
+
6
+ - **Who imports this file?** Directly and transitively.
7
+ - **What does this file import?**
8
+ - **Which frontend files call this backend endpoint?** From a Django, Flask, or
9
+ FastAPI route to the TypeScript files that request it. A route path works as
10
+ well as a view name.
11
+
12
+ Works with TypeScript, JavaScript, and Python, including `<script>` blocks in
13
+ `.vue` and `.svelte` files, and monorepos (workspaces, tsconfig `paths` and
14
+ `extends`).
15
+
16
+ ## Install
17
+
18
+ Pick one. Each installs a prebuilt binary for Windows, macOS, or Linux; no Rust needed.
19
+
20
+ ```
21
+ npm install -g @iasonas/codearch
22
+ ```
23
+
24
+ ```
25
+ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Iasonassss0007/Code-Arch/releases/latest/download/codearch-installer.sh | sh
26
+ ```
27
+
28
+ ```
29
+ powershell -ExecutionPolicy Bypass -c "irm https://github.com/Iasonassss0007/Code-Arch/releases/latest/download/codearch-installer.ps1 | iex"
30
+ ```
31
+
32
+ From source (Rust 1.85 or newer): `cargo install --git https://github.com/Iasonassss0007/Code-Arch`.
33
+
34
+ ### Teach your agent
35
+
36
+ Pick the one that fits your setup:
37
+
38
+ - **Skill** (Claude Code and other agents that read `SKILL.md`): `npx skills add Iasonassss0007/Code-Arch`,
39
+ or copy [`skills/codearch/`](skills/codearch/SKILL.md) into `~/.claude/skills/`.
40
+ The agent learns when to use each lookup and how to act on a stale index.
41
+ - **MCP server**: `claude mcp add codearch -- codearch mcp --refresh`, run inside the repository.
42
+ - **Per repository**: `codearch agents --write AGENTS.md` adds a short block that agents read.
43
+
44
+ ## Use
45
+
46
+ ```
47
+ cd /path/to/repo
48
+ codearch # build the index
49
+ codearch importers src/lib/auth.ts # who depends on this file
50
+ codearch deps src/lib/auth.ts # what this file imports
51
+ codearch callers TagViewSet # which frontend files call this view
52
+ codearch callers --path /tags/ # the same lookup by route path
53
+ codearch agents --write AGENTS.md # tell your agents these lookups exist
54
+ ```
55
+
56
+ Add `--json` for machine-readable output. Re-run `codearch` when source files change.
57
+ Also re-run it when `tsconfig.json`, `jsconfig.json`, `package.json`,
58
+ `pnpm-workspace.yaml`, or `pyproject.toml` changes, and when an `extends` file
59
+ inside the repository changes.
60
+ Commit `.codearch/*.md` so a fresh clone can answer lookups right away
61
+ (`.codearch/cache/` is ignored automatically).
62
+
63
+ Every lookup says whether the index still matches those files: `fresh`, `stale` (with the
64
+ changed files), or `unknown`. A fresh clone has no cache yet, so the lookup is unknown.
65
+ A cache written by an older codearch is unknown too, until the next `codearch` run. The
66
+ CLI prints this on stderr and `--json` adds a `freshness` object. Add `--refresh` to
67
+ rebuild first when the answer would be stale or unknown.
68
+
69
+ For MCP clients (Claude Code and others):
70
+
71
+ ```
72
+ claude mcp add codearch -- codearch mcp --repo /path/to/repo --refresh
73
+ ```
74
+
75
+ Each answer carries the same `freshness` object. With `--refresh` the server rebuilds a
76
+ stale or unknown index before answering. Without it, the server never writes files.
77
+
78
+ ## Results
79
+
80
+ **Agents answer better with a lookup than with a codebase summary.** Asked "if I
81
+ change this file, which files are affected?", models using the `codearch` lookup
82
+ found the right files 98% of the time on navigation tasks and 100% on cross-language
83
+ ones. With no help they scored 61% and 87%. A codebase map in the prompt did worse
84
+ than no help. The lookup also cut the context read by 34–56% and the token cost by
85
+ 18–77%.
86
+
87
+ ![Answer quality: lookup tool 98% vs map 58% vs no help 61% on navigation; lookup tool 100% vs no help 87% on cross-language](docs/images/agent-quality.svg)
88
+
89
+ Tested with Gemini models on Hono, Next.js Commerce, TypeDI and paperless-ngx. The
90
+ cross-language result rests on one repository.
91
+
92
+ **Cheaper than grep for transitive impact.** Context for one `codearch importers` call
93
+ vs a batched grep search, one regex per depth
94
+ ([`eval/grep_vs_codearch.py`](eval/grep_vs_codearch.py)):
95
+
96
+ | Repo | grep | codearch | Ratio |
97
+ |---|---:|---:|---:|
98
+ | ~155 TS/JS files | 2,240 tokens | 1,152 tokens | 1.9x |
99
+ | ~2,800 TS/JS/Python files | 148,757 tokens | 3,896 tokens | 38x |
100
+
101
+ For a single direct-importer lookup, `grep -l` is just as good.
102
+
103
+ **Accurate on a large monorepo.** On a pnpm monorepo with 245 packages, 99.8% of
104
+ first-party imports resolve. Compared with the TypeScript compiler's import graph,
105
+ codearch's transitive importers have 100% recall and 99.8–100% precision across five
106
+ target files. Details are in
107
+ [`eval/resolution_report.md`](eval/resolution_report.md).
108
+
109
+ ## Development
110
+
111
+ ```
112
+ cargo test
113
+ python -m pytest -q eval/test_*.py
114
+ ```
115
+
116
+ ## License
117
+
118
+ [MIT](LICENSE)
package/npm-shrinkwrap.json CHANGED
@@ -19,7 +19,7 @@
19
19
  "hasInstallScript": true,
20
20
  "license": "MIT",
21
21
  "name": "@iasonas/codearch",
22
- "version": "0.3.0"
22
+ "version": "0.3.1"
23
23
  },
24
24
  "node_modules/detect-libc": {
25
25
  "engines": {
@@ -48,5 +48,5 @@
48
48
  }
49
49
  },
50
50
  "requires": true,
51
- "version": "0.3.0"
51
+ "version": "0.3.1"
52
52
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "artifactDownloadUrls": [
3
- "https://github.com/Iasonassss0007/Code-Arch/releases/download/v0.3.0"
3
+ "https://github.com/Iasonassss0007/Code-Arch/releases/download/v0.3.1"
4
4
  ],
5
5
  "bin": {
6
6
  "codearch": "run-codearch.js"
@@ -18,7 +18,7 @@
18
18
  },
19
19
  "glibcMinimum": {
20
20
  "major": 2,
21
- "series": 31
21
+ "series": 35
22
22
  },
23
23
  "license": "MIT",
24
24
  "name": "@iasonas/codearch",
@@ -80,7 +80,7 @@
80
80
  "zipExt": ".tar.xz"
81
81
  }
82
82
  },
83
- "version": "0.3.0",
83
+ "version": "0.3.1",
84
84
  "volta": {
85
85
  "node": "18.14.1",
86
86
  "npm": "9.5.0"