Skip to content

Commit 759869d

Browse files
SutuSebastianSutuSebastian
committed
chore: bootstrap repository (README, MIT license, roadmap)
Initial package metadata for @stainless-code/codemap. Implementation follows per docs/ROADMAP.md extraction phases.
0 parents  commit 759869d

6 files changed

Lines changed: 170 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
node_modules/
2+
.codebase.db
3+
.codebase.db-wal
4+
.codebase.db-shm
5+
.DS_Store
6+
dist/
7+
*.log
8+
.env
9+
.env.*

‎CONTRIBUTING.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Contributing
2+
3+
Codemap is in **bootstrap / extraction** phase. Before large PRs, please open an issue so we can align on:
4+
5+
- **Core vs adapter** — core should stay small; language-specific logic belongs in **adapters** (see [docs/ROADMAP.md](docs/ROADMAP.md)).
6+
- **Bun-first** — v1 targets Bun APIs (`bun:sqlite`, `Worker`); Node compatibility is a later concern.
7+
8+
When the codebase lands here, we will add:
9+
10+
- `CONTRIBUTING.md` — dev setup, `bun test`, PR checklist
11+
- Issue templates for **adapter proposals** vs **core bugs**
12+
13+
Thank you for helping make structural codebase queries fast and reusable for agents.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 stainless-code contributors
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.

‎README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Codemap
2+
3+
**Query your codebase.** Codemap builds a **local SQLite index** of structural metadata (symbols, imports, exports, dependencies, routes, CSS tokens, markers, and more) so **AI agents and tools** can answer “where / what / who” questions with **SQL** instead of scanning the whole tree.
4+
5+
- **Not** a replacement for full-text search or grep on arbitrary strings — use those when you need file-body search.
6+
- **Is** a fast, token-efficient way to navigate **structure**: definitions, imports, dependency direction, route tables, etc.
7+
8+
## Status
9+
10+
Early stage: **implementation is being extracted** into this repository. See [docs/ROADMAP.md](docs/ROADMAP.md) for phases, adapter plans, and how to contribute.
11+
12+
**Runtime (planned v1):** [Bun](https://bun.sh) (`bun:sqlite`, workers). Broader runtime support may follow.
13+
14+
## Package
15+
16+
```bash
17+
bun add @stainless-code/codemap
18+
```
19+
20+
(`0.0.0` placeholder until the first published release.)
21+
22+
## Organization
23+
24+
Developed under **[stainless-code](https://github.com/stainless-code)** on GitHub.
25+
26+
## License
27+
28+
MIT — see [LICENSE](LICENSE).

‎docs/ROADMAP.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Roadmap
2+
3+
**Package:** `@stainless-code/codemap`
4+
**Tagline:** *Query your codebase* — structural index for AI agents (SQLite + SQL), not full-text grep.
5+
6+
## Repository
7+
8+
- **GitHub:** [github.com/stainless-code/codemap](https://github.com/stainless-code/codemap)
9+
10+
## Extraction phases
11+
12+
Each phase should end with a **tagged release** and **working CLI + tests**.
13+
14+
### Phase A — Bootstrap (in progress)
15+
16+
- [x] MIT `LICENSE`, `README.md`, `package.json`, `.gitignore`
17+
- [ ] CI: lint, typecheck, tests on `ubuntu` (macOS optional)
18+
- [ ] Import implementation (verbatim port first, then generalize): SQLite schema, parsers, CLI, benchmarks
19+
20+
### Phase B — Config
21+
22+
- [ ] Replace single hardcoded project root with **`root`** from config (default `process.cwd()`)
23+
- [ ] **`codemap.config.ts`** (or JSON + schema): include/exclude globs, database path, `tsconfig` for import resolution
24+
25+
### Phase C — Public API
26+
27+
- [ ] Exports: `buildIndex({ mode })`, `openDatabase()`, `query(sql)`
28+
- [ ] CLI: `codemap`, `codemap query`, `codemap --full`, `codemap --files`
29+
30+
### Phase D — Language adapters
31+
32+
Stable internal interface so new languages do not fork core:
33+
34+
```text
35+
LanguageAdapter
36+
id: string
37+
extensions: string[]
38+
parseFile(path, content, ctx): ParsedFileFragment
39+
```
40+
41+
- [ ] **Built-in:** TypeScript/JavaScript (oxc), CSS (lightningcss), text/markers
42+
- [ ] **Optional packages:** e.g. `@stainless-code/codemap-adapter-rust` (Tree-sitter, peers on core)
43+
44+
### Phase E — Consumers
45+
46+
- [ ] Downstream apps use `bunx @stainless-code/codemap` or a workspace dependency
47+
- [ ] Agent-facing docs: when to **query Codemap** vs **grep / read files**
48+
49+
## Multi-language strategy
50+
51+
| Layer | Role |
52+
| ----- | ---- |
53+
| **Core** | Schema, incremental indexing, git invalidation, `dependencies`, CLI, `query` |
54+
| **Built-in adapters** | Shipped in `@stainless-code/codemap` |
55+
| **Community adapters** | Separate packages; **peerDependency** on `codemap` semver range |
56+
57+
## Non-goals (v1)
58+
59+
- Full-text search across all file bodies (use ripgrep / IDE)
60+
- Replacing LSP or language servers
61+
- Guaranteed Node.js runtime (v1 may stay Bun-only)
62+
63+
## Backlog
64+
65+
- [ ] Optional FTS5 for opt-in full-text
66+
- [ ] MCP server wrapping `query`
67+
- [ ] Watch mode for dev
68+
- [ ] Pluggable route extractors (e.g. Next.js, Remix) alongside TanStack-style routes

‎package.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "@stainless-code/codemap",
3+
"version": "0.0.0",
4+
"description": "Query your codebase — structural SQLite index for AI agents",
5+
"license": "MIT",
6+
"type": "module",
7+
"engines": {
8+
"bun": ">=1.1.0"
9+
},
10+
"repository": {
11+
"type": "git",
12+
"url": "https://github.com/stainless-code/codemap.git"
13+
},
14+
"bugs": {
15+
"url": "https://github.com/stainless-code/codemap/issues"
16+
},
17+
"homepage": "https://github.com/stainless-code/codemap#readme",
18+
"keywords": [
19+
"codebase",
20+
"index",
21+
"sqlite",
22+
"ai",
23+
"agents",
24+
"symbols",
25+
"imports",
26+
"dependencies"
27+
],
28+
"publishConfig": {
29+
"access": "public"
30+
}
31+
}

0 commit comments

Comments
 (0)