Skip to content

Commit 7893f88

Browse files
SutuSebastianSutuSebastian
committed
docs(research): refresh fallow.md + scan against current ship state
fallow.md gains a "Status snapshot (as of 2026-05-01)" section that tabulates every adoption candidate's ship status — single source of truth for "what's open" without munging the original tier tables. Captures: - Tier A all shipped (PR #26) - B.5 partial (v1 in PR #33; --base <ref> + verdict deferred to v1.x) - B.6 shipped (PR #30) — table-in-DB, not parallel JSON files - B.7 shipped (PR #28) — landed on `symbols`, not `exports` - B.8 / C.9 / C.10 / C.11 / D.* still as-was - MCP server (agent-transports v1) shipped in PR #35 (adjacent — not a numbered fallow candidate but worth surfacing here) § 6 open questions: marks the 2 settled ones (actions ownership, audit verdict default) with their resolution PRs; preserves the 2 still-open ones (coverage column shape, plugin layer scope). § 3 already-shipped block: updates the visibility-tags note to acknowledge B.7 promoted it from regex to structured column instead of saying "B.7 proposes promoting" (which it doesn't anymore). competitive-scan-2026-04.md § 4: marks MCP server wrapping `query` as ✅ shipped via PR #35 with a cross-link to fallow.md's status snapshot. Other items still tracked there. No behavior change; pure docs refresh to match current reality.
1 parent 119db38 commit 7893f88

2 files changed

Lines changed: 42 additions & 9 deletions

File tree

‎docs/research/competitive-scan-2026-04.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -66,14 +66,14 @@ All shipped under PR [#23](https://github.com/stainless-code/codemap/pull/23) as
6666

6767
## 4. What moved to the roadmap
6868

69-
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:
70-
71-
- MCP server wrapping `query`
72-
- HTTP API (`codemap serve`)
73-
- Recipes-as-content registry + project-local recipes (`.codemap/recipes/`)
74-
- Targeted-read CLI (`codemap show <symbol>`)
75-
- Watch mode (`codemap watch`)
76-
- Cross-agent handoff artifact (speculative)
69+
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.
70+
71+
- ✅ **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.
72+
- HTTP API (`codemap serve`) — still backlog
73+
- Recipes-as-content registry + project-local recipes (`.codemap/recipes/`) — still backlog
74+
- Targeted-read CLI (`codemap show <symbol>`) — still backlog
75+
- Watch mode (`codemap watch`) — still backlog
76+
- Cross-agent handoff artifact (speculative) — still backlog
7777

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

‎docs/research/fallow.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,39 @@
77
88
---
99

10+
## Status snapshot (as of 2026-05-01)
11+
12+
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.
13+
14+
| Tier | # | Item | Status | Where it landed / why deferred |
15+
| ---- | --------- | ------------------------------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
16+
| A | A.1 | Per-row recipe `actions` | ✅ Shipped | PR [#26](https://github.com/stainless-code/codemap/pull/26) |
17+
| A | A.2 | `--changed-since <ref>` | ✅ Shipped | PR [#26](https://github.com/stainless-code/codemap/pull/26) |
18+
| A | A.3 | `--group-by owner\|directory\|package` | ✅ Shipped | PR [#26](https://github.com/stainless-code/codemap/pull/26) |
19+
| A | A.4 | `--summary` flag | ✅ Shipped | PR [#26](https://github.com/stainless-code/codemap/pull/26) |
20+
| 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. |
21+
| 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()`. |
22+
| 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. |
23+
| B | B.8 | `--format sarif` + `--format annotations` | ❌ Open | Pure output-formatter; needs a small design pass for SARIF rule-id taxonomy across recipes. |
24+
| C | C.9 | Framework plugin layer | ❌ Open | Big surface; worth a `plans/<name>.md` before any code. |
25+
| C | C.10 | LSP server + Code Lens | ❌ Open | Independent but tangles with persistent-daemon non-goal. |
26+
| C | C.11 | Static coverage ingestion | ❌ Open | Schema bump; one-shot ingester. |
27+
| D | D.12-D.16 | Suppressions / per-rule severity / `fix` / suffix-array dupes / runtime intelligence | ⏸️ Skip per § 1 reasoning |
28+
29+
**Adjacent — also shipped post-refresh:**
30+
31+
- **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).
32+
- **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.
33+
34+
**Open-questions resolution** (from § 6 below):
35+
36+
- "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).
37+
- "`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).
38+
- "Coverage ingestion (C.11) — column on `symbols` or separate `coverage` table?" — still open, blocked on C.11 prioritisation.
39+
- "How invasive should the framework plugin layer (C.9) be?" — still open.
40+
41+
---
42+
1043
## 0. Fresh evidence — what a hands-on graph audit surfaced
1144

1245
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.
@@ -80,7 +113,7 @@ If any of these get prioritised, fallow's CLI flag shape is the closest preceden
80113

81114
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:
82115

83-
- `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.
116+
- `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%'`.
84117
- "Grep/Read vs Codemap" capability table in the root README (inspired by fallow's "Linter vs Fallow" framing).
85118

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

0 commit comments

Comments
 (0)