diff --git a/docs/for-me-personal/DEBUG.md b/docs/for-me-personal/DEBUG.md index 221cdbd..5c07b61 100644 --- a/docs/for-me-personal/DEBUG.md +++ b/docs/for-me-personal/DEBUG.md @@ -1,6 +1,6 @@ # Catatan Debugging DevMap -Terakhir diperbarui: 2026-10-30 +Terakhir diperbarui: 2026-10-31 Dokumen ini menyimpan masalah teknis yang pernah ditemukan selama development DevMap. Tujuannya supaya penyebab, solusi, dan cara verifikasinya tidak perlu @@ -1637,3 +1637,55 @@ yang nyata. snapshot dengan project harus menganalisis dan menyimpan di direktori yang sama. - Jika semua hasil tiba-tiba `stale: true`, periksa dulu apakah snapshot dan project yang dibandingkan memang folder yang sama sebelum mencurigai logika stale. + +--- + +## 31. Rilis 0.9.0 Gagal karena Test `staleTtlMs: 0` Flaky di Runner yang Cepat + +**Tanggal:** 2026-10-31 + +### Gejala + +Workflow `publish.yml` untuk tag `v0.9.0` gagal di langkah `Test CLI`: +`# tests 482`, `# pass 481`, `# fail 1`. Paket belum terbit ke npm. Di laptop dan +di sandbox semua 482 test lulus. Log yang ditempel terpotong sehingga nama test +yang gagal tidak kelihatan, dan log lengkap tidak bisa diambil lewat API. + +### Akar Masalah + +`snapshotProvider` memakai ulang hasil cek stale selama +`now() - staleCache.at > ttl`. Dengan `staleTtlMs: 0`, dua panggilan di +milidetik yang sama tetap memakai cache karena `0 > 0` bernilai false. Test +`results flag a stale snapshot after the project changes` memanggil `get()`, +menambah file, lalu memanggil `get()` lagi; di mesin cepat kedua panggilan jatuh +di milidetik yang sama sehingga hasilnya `stale: false`. + +Test ini tidak pernah jalan di runner sebelumnya karena workflow `ci.yml` +berstatus `disabled_manually`; hanya `publish.yml` (Linux saja) yang menjalankan +test, dan baru setelah test MCP ada. + +### Solusi + +- Ubah perbandingan menjadi `now() - staleCache.at >= ttl` (PR #138): TTL 0 + tidak pernah memakai cache. TTL default 10 detik tidak berubah. +- Tambah test dengan jam beku (`now: () => 1_000`) yang gagal tanpa perbaikan. +- Karena 0.9.0 belum terbit, versi tetap 0.9.0 dan tag `v0.9.0` dipindah ke + merge commit #138 (hapus tag remote, buat ulang, push). + +### Verifikasi + +- Reproduksi: loop `mcp-*.test.ts` 8 kali di sandbox, test itu gagal 1 kali. + Skrip dengan jam beku mereproduksi `stale: false` secara deterministik. +- Setelah perbaikan: `pnpm test:cli` 483 pass / 0 fail, loop 6 kali tanpa gagal. +- Publish ulang hijau, `npm view @flaid/devmap version` menampilkan `0.9.0`. + +### Pelajaran + +- TTL cache yang bernilai 0 harus berarti "jangan cache". Pakai `>=` (atau cek + `ttl === 0`), jangan `>`. +- Test yang bergantung pada urutan waktu nyata gampang flaky di mesin cepat. + Pakai jam yang bisa disuntik (`now`) dan uji kasus jam beku. +- Workflow yang dinonaktifkan membuat test baru tidak teruji di runner mana pun. + Satu run publish yang gagal di langkah test aman: tidak ada yang terbit. +- Jika log CI terpotong, nama test yang gagal bisa dicari dengan mereproduksi + lokal: fresh clone, `CI=true`, user non-root, `env -i`, lalu loop berulang. diff --git a/docs/for-me-personal/PROGRESS.md b/docs/for-me-personal/PROGRESS.md index bbaee12..25aac9a 100644 --- a/docs/for-me-personal/PROGRESS.md +++ b/docs/for-me-personal/PROGRESS.md @@ -1,6 +1,30 @@ # Progress DevMap -Terakhir diperbarui: 2026-10-30 +Terakhir diperbarui: 2026-10-31 + +## Update 2026-10-31 + +### Rilis 0.9.0 dan perbaikan setelahnya + +- **Rilis (#136)**: `@flaid/devmap` 0.9.0 (`devmap mcp`). Publish pertama gagal di + langkah `Test CLI` karena test flaky (lihat DEBUG #31, perbaikan #138); tag + `v0.9.0` dipindah ke merge commit #138, lalu terbit ke npm dengan GitHub Release. +- **MCP Registry**: `server.json` di `packages/cli`, dipublikasikan manual dengan + `mcp-publisher login github` lalu `mcp-publisher publish`; muncul sebagai + `io.github.itsflaid/devmap`. +- **Landing page**: bagian MCP dan docs MCP (#135), tombol npm di navbar (#137), lalu + GitHub + npm digabung jadi satu pill putih/hitam (#139). +- **Lock analisis (#140)**: `devmap analyze` sekarang ikut memegang + `.devmap/analyze.lock`. Kode lock pindah ke `src/cache/analysisLock.ts`; lock diambil + di `analyzeCommand`, bukan `runAnalyze`, karena refresher MCP sudah memegangnya. + Belum dirilis; level bump menunggu keputusan (usulan: patch 0.9.1). +- **Docs**: `docs/roadmap.md` dibuat (README sudah menautkannya tetapi filenya tidak + ada). +- **CI sengaja dinonaktifkan** (`ci.yml` disabled) untuk menghemat jatah Actions gratis. + Test tetap jalan di Linux lewat `publish.yml` sebelum tiap rilis. Test proses MCP di + Windows dan macOS belum pernah teruji di runner. +- Catatan lokal Windows: error `ENOENT ...@fontsource-variable\funnel-display` saat + `astro dev` berarti `node_modules` lama; jalankan `pnpm install` dari root. ## Update 2026-10-30 @@ -24,7 +48,7 @@ MCP hanya lapisan tipis di atas snapshot. 4. **Fase 3 (#133)** — `devmap_explain` (hanya terdaftar dengan `--allow-ai`), `test/mcp-smoke.mjs` dijalankan di `ci.yml` dan `publish.yml` sebelum `npm publish`, `mcpName: io.github.itsflaid/devmap` di `package.json`. -5. **Fase 4 (sedang jalan)** — `docs/mcp.md`, bagian MCP di README, `commands.md`, +5. **Fase 4 (selesai: #134 docs, #135 landing page)** — `docs/mcp.md`, bagian MCP di README, `commands.md`, `architecture.md` (bagian 15), `generated-files.md`, `docs/guide/commands/09-mcp.md`, `CLAUDE.md`, `CHANGELOG.md` (Unreleased); lalu landing page. diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..a44a875 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,61 @@ +# Roadmap + +What has shipped, what is likely next, and what is deliberately deferred. This is a +direction, not a promise: items move as real projects show what matters. The full +history of released changes is in [CHANGELOG.md](../CHANGELOG.md). + +## Principles + +- **Static analysis first.** Files, graph, routes, features and flows are + deterministic. AI is an optional layer on top and never blocks `devmap analyze`. +- **JS/TS depth before breadth.** Other languages stay at their current level until + the JS/TS ecosystem is mature. +- **Read-only by default.** The MCP server only writes inside `.devmap/`, and only + when asked (`devmap_analyze`, `--auto-refresh`). + +## Shipped + +**0.9.0: `devmap mcp`.** DevMap runs as an MCP server over stdio, so an agent asks +the project map questions with tool calls instead of reading a dumped context file. + +- Tools: `devmap_overview`, `devmap_map`, `devmap_flow`, `devmap_routes`, + `devmap_impact`, `devmap_find`, `devmap_analyze`, and `devmap_explain` with + `--allow-ai` +- Resources and prompts, stale-snapshot reporting on every answer, and opt-in + `--auto-refresh` +- Listed in the MCP Registry as `io.github.itsflaid/devmap` +- Guide: [mcp.md](./mcp.md) + +## Likely next + +Ideas that follow directly from what exists. None is scheduled. + +- **MCP setup help.** A `devmap doctor` check for the MCP setup, and `devmap init` + offering the `.mcp.json` snippet. +- **Cheaper staleness checks.** The MCP server re-scans project files (cached for + 10 seconds) to decide whether the snapshot is stale. That is not free on very large + repositories. +- **Import resolution for more languages.** Go, Java, C# and PHP (PSR-4) imports + are read today but produce no dependency-graph edges. This waits until JS/TS is + mature. +- **Public benchmark results.** The method is in [benchmarking.md](./benchmarking.md); + results will be published once recorded, and claims stay at "designed to reduce + repeated exploration" until then. + +## Future commands + +Commands listed in [commands.md](./commands.md#future-commands) (`features`, `docs`, +`deadcode`, `report`, `watch`, `visual`) are not part of the current scope. + +## Deferred + +Left out until evidence justifies the cost: + +- Public analyzer plugins +- Tree-sitter adapters beyond the planned language work +- Persisted graph storage and multi-project aggregation +- Fine-grained incremental computation (the graph is rebuilt on every analyze) +- MCP: a remote (HTTP) transport, serving several projects from one server, and + watching files instead of checking staleness per request + +Design reasons for each are in [architecture.md](./architecture.md).