Skip to content

docs(research): refresh fallow.md + scan against current ship state #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SutuSebastian merged 3 commits into from
May 1, 2026
Merged

docs(research): refresh fallow.md + scan against current ship state #36

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7893f88
docs(research): refresh fallow.md + scan against current ship state
SutuSebastian May 1, 2026
d1c09d0
docs(research): fix MD056 — D row in fallow.md status snapshot was 4 …
SutuSebastian May 1, 2026
d21483a
docs(research): align B.7 row title to shipped column name (symbols.v…
SutuSebastian May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/research/competitive-scan-2026-04.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,14 +66,14 @@ All shipped under PR [#23](https://github.com/stainless-code/codemap/pull/23) as

## 4. What moved to the roadmap

Items the scan called out as "watch / defer / future" that are now tracked in [docs/roadmap.md § Backlog](../roadmap.md#backlog) — go there for the latest status, not here:

- MCP server wrapping `query`
- HTTP API (`codemap serve`)
- Recipes-as-content registry + project-local recipes (`.codemap/recipes/`)
- Targeted-read CLI (`codemap show <symbol>`)
- Watch mode (`codemap watch`)
- Cross-agent handoff artifact (speculative)
Items the scan called out as "watch / defer / future" — most still live in [docs/roadmap.md § Backlog](../roadmap.md#backlog); items shipped after this scan are linked to their PRs.

- ✅ **MCP server wrapping `query`** — shipped as `codemap mcp` (agent-transports v1) in PR [#35](https://github.com/stainless-code/codemap/pull/35). Tool taxonomy, output shape, and resource catalog reserved for HTTP API to inherit. See [`research/fallow.md` § Status snapshot](./fallow.md#status-snapshot-as-of-2026-05-01) for the full ship summary.
- HTTP API (`codemap serve`) — still backlog
- Recipes-as-content registry + project-local recipes (`.codemap/recipes/`) — still backlog
- Targeted-read CLI (`codemap show <symbol>`) — still backlog
- Watch mode (`codemap watch`) — still backlog
- Cross-agent handoff artifact (speculative) — still backlog

The scan's "PASS" list (dead-code / dupes / complexity / boundaries / fix actions, runtime/V8 coverage merging, framework plugins, PageRank summarization, skyline visualization, daemon process, embedded intent classification) has been folded into [roadmap.md § Non-goals](../roadmap.md#non-goals-v1) — that's the canonical home; do not duplicate here.

Expand Down
35 changes: 34 additions & 1 deletion docs/research/fallow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,39 @@

---

## Status snapshot (as of 2026-05-01)

Adoption-candidate ship status. The tier tables in § 1 are preserved as the original assessment record; this snapshot is the single source of truth for "what's open." Update on every PR that closes a row.

| Tier | # | Item | Status | Where it landed / why deferred |
| ---- | --------- | ------------------------------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| A | A.1 | Per-row recipe `actions` | ✅ Shipped | PR [#26](https://github.com/stainless-code/codemap/pull/26) |
| A | A.2 | `--changed-since <ref>` | ✅ Shipped | PR [#26](https://github.com/stainless-code/codemap/pull/26) |
| A | A.3 | `--group-by owner\|directory\|package` | ✅ Shipped | PR [#26](https://github.com/stainless-code/codemap/pull/26) |
| A | A.4 | `--summary` flag | ✅ Shipped | PR [#26](https://github.com/stainless-code/codemap/pull/26) |
| B | B.5 | `codemap audit` (structural-drift) | ⚠️ Partial — v1 shipped | v1 in PR [#33](https://github.com/stainless-code/codemap/pull/33). Reuses B.6 baselines instead of `--base <ref>` worktree+reindex (deferred to v1.x — trigger: a real consumer asks). `verdict` / threshold config also deferred to v1.x — trigger: 2 consumers ship `jq`-based threshold scripts with similar shapes. Schema landed on `symbols` (not `exports`) per actual usage. |
| B | B.6 | `--save-baseline` / `--baseline` on `query` | ✅ Shipped | PR [#30](https://github.com/stainless-code/codemap/pull/30). Implemented as a `query_baselines` table inside `.codemap.db` (not parallel JSON files) — survives `--full` and SCHEMA bumps because the table is intentionally absent from `dropAll()`. |
| B | B.7 | `symbols.visibility` column | ✅ Shipped | PR [#28](https://github.com/stainless-code/codemap/pull/28). Landed on `symbols` (not `exports`) — `visibility` is a property of the symbol's docstring, not its export status. |
| B | B.8 | `--format sarif` + `--format annotations` | ❌ Open | Pure output-formatter; needs a small design pass for SARIF rule-id taxonomy across recipes. |
| C | C.9 | Framework plugin layer | ❌ Open | Big surface; worth a `plans/<name>.md` before any code. |
| C | C.10 | LSP server + Code Lens | ❌ Open | Independent but tangles with persistent-daemon non-goal. |
| C | C.11 | Static coverage ingestion | ❌ Open | Schema bump; one-shot ingester. |
| D | D.12-D.16 | Suppressions / per-rule severity / `fix` / suffix-array dupes / runtime intelligence | ⏸️ Skip per § 1 reasoning |

Comment thread
coderabbitai[bot] marked this conversation as resolved.
**Adjacent — also shipped post-refresh:**

- **MCP server (agent-transports v1)** — `codemap mcp` ships every CLI verb (plus MCP-only `query_batch`) as JSON-RPC tools over stdio with four lazy-cached resources. PR [#35](https://github.com/stainless-code/codemap/pull/35). Output shape verbatim from each tool's CLI `--json` envelope (no re-mapping). HTTP API (`codemap serve`) stays in roadmap backlog — design points (tool taxonomy, output shape) reserved in [`architecture.md` § MCP wiring](../architecture.md#cli-usage).
- **Doc-governance Rule 10** added during PR [#29](https://github.com/stainless-code/codemap/pull/29) — every core-surface change must update both `templates/agents/` (ships to npm) and `.agents/` (this clone) in lockstep.

**Open-questions resolution** (from § 6 below):

- "Should `actions` (A.1) live in recipe definitions or be derived?" — **(a) recipe-defined**, settled in PR [#26](https://github.com/stainless-code/codemap/pull/26).
- "`codemap audit` (B.5) verdict threshold defaults?" — **defer verdict to v1.x; ship raw deltas + `jq` idiom in v1**, settled in PR [#33](https://github.com/stainless-code/codemap/pull/33).
- "Coverage ingestion (C.11) — column on `symbols` or separate `coverage` table?" — still open, blocked on C.11 prioritisation.
- "How invasive should the framework plugin layer (C.9) be?" — still open.

---

## 0. Fresh evidence — what a hands-on graph audit surfaced

This refresh is grounded in a third-party graph audit run against a TanStack-Router / TS app, where both Codemap and Fallow were used side-by-side across ~14 sections (ownership map, owner→owner dependency matrix, fan-in / fan-out hotspots, hook-heavy components, file LoC, external consumers, cycles, folder-size discipline, dead code, public-surface barrel usage). The exercise is the most recent bottom-up evidence of where each tool stops and the other starts.
Expand Down Expand Up @@ -80,7 +113,7 @@ If any of these get prioritised, fallow's CLI flag shape is the closest preceden

PR [#23](https://github.com/stainless-code/codemap/pull/23) shipped fallow-inspired items in 2026-04 — see [`research/competitive-scan-2026-04.md` § 3](./competitive-scan-2026-04.md#3-what-shipped-from-this-scan). Highlights:

- `deprecated-symbols` and `visibility-tags` recipes (inspired by fallow's JSDoc visibility tags) — currently regex-based on `doc_comment`; B.7 above proposes promoting to a structured column.
- `deprecated-symbols` and `visibility-tags` recipes (inspired by fallow's JSDoc visibility tags) — B.7 (now shipped in PR [#28](https://github.com/stainless-code/codemap/pull/28)) promoted the parser output into a structured `symbols.visibility` column, so `visibility-tags` queries `WHERE visibility IS NOT NULL` instead of `LIKE '%@beta%'`.
- "Grep/Read vs Codemap" capability table in the root README (inspired by fallow's "Linter vs Fallow" framing).

The dated scan stays the canonical record of that pass; this file picks up where it left off.
Expand Down
Loading