diff --git a/docs/research/competitive-scan-2026-04.md b/docs/research/competitive-scan-2026-04.md index 0d10921..cadd164 100644 --- a/docs/research/competitive-scan-2026-04.md +++ b/docs/research/competitive-scan-2026-04.md @@ -71,8 +71,9 @@ Items the scan called out as "watch / defer / future" — most still live in [do - ✅ **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. - ✅ **Recipes-as-content registry + project-local recipes (`.codemap/recipes/`)** — shipped in PR [#37](https://github.com/stainless-code/codemap/pull/37). Catalog gains `source` / `body` / `shadows` fields so agents see project overrides at session start. - ✅ **Targeted-read CLI (`codemap show `)** — shipped as `show` + `snippet` siblings in PR [#39](https://github.com/stainless-code/codemap/pull/39). -- 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 +- ✅ **`--format sarif` + `--format annotations`** — shipped in PR [#43](https://github.com/stainless-code/codemap/pull/43). GitHub Code Scanning + PR-inline annotations for any recipe row-set. +- ✅ **HTTP API (`codemap serve`)** — shipped in PR [#44](https://github.com/stainless-code/codemap/pull/44). Same tool taxonomy as MCP, `POST /tool/{name}`, loopback default, optional `--token`. +- See [`research/fallow.md` § Status snapshot](./fallow.md#status-snapshot-as-of-2026-05-02) for the full ship summary. - Watch mode (`codemap watch`) — still backlog - Cross-agent handoff artifact (speculative) — still backlog diff --git a/docs/research/fallow.md b/docs/research/fallow.md index 6d71553..41d7d77 100644 --- a/docs/research/fallow.md +++ b/docs/research/fallow.md @@ -11,28 +11,29 @@ 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 ` | ✅ 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 ` 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/.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 | See § 1 Defer / skip table for the per-row reasoning. | +| 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 ` | ✅ 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 ` 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` | ✅ Shipped | PR [#43](https://github.com/stainless-code/codemap/pull/43). `codemap query --format sarif\|annotations` (also on MCP `query` / `query_recipe` tools as `format: "sarif"\|"annotations"`); `rule.id = codemap.` (`codemap.adhoc` for ad-hoc SQL); auto-detects `file_path` / `path` / `to_path` / `from_path`; aggregate recipes (`index-summary`, `markers-by-kind`) emit `results: []` + stderr warning. Per-recipe `sarifLevel` / `sarifMessage` / `sarifRuleId` overrides via frontmatter deferred to v1.x. | +| C | C.9 | Framework plugin layer | ❌ Open | Big surface; worth a `plans/.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 | See § 1 Defer / skip table for the per-row reasoning. | **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). +- **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 transport (`codemap serve`) shipped post-MCP — see PR #44 entry below. - **Recipes-as-content registry** — bundled recipes are now `.{sql,md}` file pairs in `templates/recipes/`; project teams ship internal SQL via git-tracked `/.codemap/recipes/.{sql,md}`. PR [#37](https://github.com/stainless-code/codemap/pull/37). Catalog gains `source` / `body` / `shadows` fields so agents see project overrides at session start; YAML frontmatter actions on `.md` mean project recipes feel first-class. Load-time DML/DDL deny-list + runtime `PRAGMA query_only=1` backstop. - **Targeted-read CLI** — `codemap show ` + `codemap snippet ` for precise lookup-by-symbol-name without composing SQL. PR [#39](https://github.com/stainless-code/codemap/pull/39). Both verbs share the same flag set (`--kind`, `--in `) and an agent-friendly `{matches, disambiguation?}` envelope; `snippet` adds `source` / `stale` / `missing` per match (read + flag, no auto-reindex side-effects). Registered as MCP tools too — every read verb maps to a tool. PR also shipped defence-in-depth security fixes (LIKE-wildcard escape on `--in`, path-traversal rejection in `agents-init`, non-blocking `bun audit` CI job). - **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. - **`cli/*` → `application/*` engine lift (internal)** — PR [#41](https://github.com/stainless-code/codemap/pull/41) closed the last layer-reversal imports `application/mcp-server.ts` had on `cli/*` (called out in the PR #35 self-audit). New engines `context-engine` / `validate-engine`; `query-recipes` moved to `application/`; envelope builders + helpers consolidated in `audit-engine` / `show-engine`. Pure refactor — no behavior or public API change — but unblocks the HTTP transport (B-tier `serve`) since that engine reuse is now clean. +- **`codemap serve` HTTP API** — PR [#44](https://github.com/stainless-code/codemap/pull/44). Same tool taxonomy as `codemap mcp` over `POST /tool/{name}` for non-MCP consumers (CI scripts, simple `curl`, IDE plugins). Loopback default (`127.0.0.1:7878`); optional `--token` for Bearer auth. Bare `node:http` (no Express/Fastify dep). Tool bodies + resource fetchers live in shared `application/{tool,resource}-handlers.ts` — both transports dispatch the same pure handlers. CSRF + DNS-rebinding guard rejects `Sec-Fetch-Site: cross-site|same-site`, mismatched `Host` (loopback bind), and any `Origin` header — defends against malicious local webpages `fetch`-ing the API while the dev browses. Per-tool Zod validation at the HTTP boundary; ToolResult error arm carries `status?: 400|404|500` so unknown recipe / baseline → 404 and engine throws → 500. **Open-questions resolution** (from § 6 below):