diff --git a/README.md b/README.md index 136f829..2d2abd6 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,12 @@ native binary. No AI or vector runtime inside the indexer. [English](README.md) · [简体中文](docs/readme/README.zh-CN.md) · [Website](https://firlab.app/codegraph/en/) · [Documentation](docs/README.md) · -[Contributing](CONTRIBUTING.md) +[Browser viewer](#browser-viewer) · [Community](#community) · [Contributing](CONTRIBUTING.md) + + + + The CodeGraph browser viewer showing the method IndexPaths::resolve: its callers on the left, its source with every call marked in the middle, and the functions it calls on the right. + @@ -31,6 +36,9 @@ LLM to rediscover structure through repeated text searches. exploration use one indexed representation. - **Agent-ready:** an MCP server exposes the same graph and verbatim source used by the CLI. +- **Visual (preview):** a local browser viewer reads the same index: a symbol's + callers, source and callees side by side, call paths, an architecture map, type + hierarchies and the code nothing reaches. - **Local-first:** the index lives under the project; the shared daemon and HTTP transport are local processes. - **Broad language coverage:** grammar-backed languages, embedded/template files, @@ -246,6 +254,35 @@ Full target and configuration matrices: [`docs/cli.md`](docs/cli.md), [`docs/mcp.md`](docs/mcp.md), and [`editors/zed/README.md`](editors/zed/README.md). +## Browser viewer + +`codegraph ui` opens a local, read-only reader of the index in your browser. It is a +preview, refused unless `CODEGRAPH_UI=1` is set: + +```bash +CODEGRAPH_UI=1 codegraph ui # the indexed project you are in +CODEGRAPH_UI=1 codegraph ui --read-only # also refuse saving trails +``` + +It binds `127.0.0.1` only, never builds or changes the index, and writes nothing but +the trails you choose to save under `.codegraph/ui/trails/`. It has a dark and a light +theme and follows the system's until you pick one. + + + + + + + + + + +
The Flow view: the call path from cmd_explore to explore_file_header, each hop with the code that makes the call.The Map view: this repository's crates and the dependencies between them, foundations at the bottom.
Flow: the call path from one function to anotherMap: modules and the dependencies between them
+ +A tour of every view is on the website: +[the browser viewer](https://firlab.app/codegraph/en/guide/viewer). The reference is +[`docs/ui.md`](docs/ui.md). + ## Determinism and safety The compatibility contract includes stable node IDs, canonical golden artifacts, @@ -291,6 +328,8 @@ make check ## Documentation +- [firlab.app/codegraph](https://firlab.app/codegraph/en/) — the website: guide, quick + start and a tour of the viewer ([简体中文](https://firlab.app/codegraph/)) - [`docs/README.md`](docs/README.md) — documentation map - [`docs/architecture.md`](docs/architecture.md) — workspace and runtime design - [`docs/cli.md`](docs/cli.md) — complete command reference @@ -301,6 +340,14 @@ make check - [`docs/upstream-sync/UPSTREAM.md`](docs/upstream-sync/UPSTREAM.md) — upstream ledger - [`docs/troubleshooting.md`](docs/troubleshooting.md) — diagnostic workflow +## Community + +- Questions, bug reports and feature requests: + [GitHub Issues](https://github.com/sunerpy/codegraph-rust/issues). +- WeChat: the Official Account 六月水蓝. + +QR code of the WeChat Official Account 六月水蓝 + ## License MIT — see [`LICENSE-MIT`](LICENSE-MIT). diff --git a/docs/readme/README.zh-CN.md b/docs/readme/README.zh-CN.md index 034f1a0..30514d0 100644 --- a/docs/readme/README.zh-CN.md +++ b/docs/readme/README.zh-CN.md @@ -14,7 +14,12 @@ [English](../../README.md) · [简体中文](README.zh-CN.md) · [网站](https://firlab.app/codegraph/) · [文档](../README.md) · -[参与贡献](../../CONTRIBUTING.md) +[浏览器查看器](#浏览器查看器) · [交流与反馈](#交流与反馈) · [参与贡献](../../CONTRIBUTING.md) + + + + CodeGraph 浏览器查看器中的方法 IndexPaths::resolve：左侧是调用方，中间是标出每处调用的源码，右侧是它调用的函数。 + @@ -27,6 +32,8 @@ CodeGraph 把源码树转换成本地知识图谱：符号成为节点，调用 canonical 图谱输出。 - **源码感知：** search、callers/callees、impact、文件源码和多文件探索共享同一索引。 - **代理友好：** MCP 服务器暴露与 CLI 相同的图谱和逐字源码。 +- **可视化（预览）：** 本地浏览器查看器读取同一份索引：并排显示一个符号的调用方、 + 源码和被调用方，以及调用路径、架构图、类型层级和没有代码到达的符号。 - **本地优先：** 索引位于项目内；共享 daemon 和 HTTP transport 都是本地进程。 - **广泛语言覆盖：** grammar、嵌入式/模板文件以及 Godot、Tauri、JS 生态框架 关系使用同一 schema。 @@ -225,6 +232,33 @@ codegraph skill update --dry-run --diff [`docs/mcp.md`](../mcp.md) 与 [`editors/zed/README.md`](../../editors/zed/README.md)。 +## 浏览器查看器 + +`codegraph ui` 在浏览器中以只读方式打开项目的索引。它目前是预览功能，未设置 +`CODEGRAPH_UI=1` 时会被拒绝： + +```bash +CODEGRAPH_UI=1 codegraph ui # 当前所在的已建立索引的项目 +CODEGRAPH_UI=1 codegraph ui --read-only # 同时拒绝保存 Trail +``` + +它只监听 `127.0.0.1`，从不建立或修改索引，唯一写入的是你主动保存在 +`.codegraph/ui/trails/` 下的 Trail。它有深色和浅色两种主题，在你选择之前跟随系统设置。 + + + + + + + + + + +
Flow 视图：从 cmd_explore 到 explore_file_header 的调用路径，每一跳附有发出调用的代码。Map 视图：本仓库的各个 crate 及其依赖关系，底层模块位于下方。
Flow：从一个函数到另一个函数的调用路径Map：模块及其依赖关系
+ +网站上有每个视图的介绍：[浏览器查看器](https://firlab.app/codegraph/guide/viewer)。参考文档见 +[`docs/ui.md`](../ui.md)。 + ## 确定性与安全边界 兼容性契约包括稳定 node ID、canonical golden artifact、SQLite schema parity、 @@ -263,6 +297,8 @@ canonical agent 契约 [`AGENTS.md`](../../AGENTS.md)。 ## 文档 +- [firlab.app/codegraph](https://firlab.app/codegraph/) — 网站：指南、快速开始和查看器介绍 + （[English](https://firlab.app/codegraph/en/)） - [`docs/README.md`](../README.md) — 文档地图 - [`docs/architecture.md`](../architecture.md) — workspace 与运行时设计 - [`docs/cli.md`](../cli.md) — 完整命令参考 @@ -273,6 +309,13 @@ canonical agent 契约 [`AGENTS.md`](../../AGENTS.md)。 - [`docs/upstream-sync/UPSTREAM.md`](../upstream-sync/UPSTREAM.md) — 上游台账 - [`docs/troubleshooting.md`](../troubleshooting.md) — 诊断流程 +## 交流与反馈 + +- 提问、问题报告和功能建议：[GitHub Issues](https://github.com/sunerpy/codegraph-rust/issues)。 +- 微信：公众号「六月水蓝」。 + +微信公众号「六月水蓝」的二维码 + ## 许可证 MIT，详见 [`LICENSE-MIT`](../../LICENSE-MIT)。 diff --git a/docs/site/README.md b/docs/site/README.md index fa0095e..7da2749 100644 --- a/docs/site/README.md +++ b/docs/site/README.md @@ -18,7 +18,7 @@ Site paths below are relative to `https://firlab.app/codegraph/`. | `guide/`, `reference/faq.md`, `privacy.md`, `developers.md` and the same paths under `en/` | the user guide | | `../cli.md`, `../mcp.md`, `../ui.md`, `../languages.md`, `../godot.md`, `../troubleshooting.md` | `/en/reference/`, as they are; `/reference/` is a generated Chinese pointer | | `../architecture.md`, `../data-model.md`, `../equivalence.md`, `../grammar-manifest.md`, `../embedded-extraction.md`, `../benchmark.md`, `../benchmark-results.md` | `/en/dev/`, with a generated Chinese pointer at `/dev/` | -| `public/` | the site root (`/codegraph-logo.svg`, `/screens/*.webp`) | +| `public/` | the site root (`/codegraph-logo.svg`, `/screens/*.webp`, `/community/*`) | | `tools/`, this file | not published | The canonical references stay English, as `docs/AGENTS.md` asks. The site publishes them unchanged and gives each a @@ -85,6 +85,7 @@ Pages may use these components and no others; the sync rejects any other tag. | ----------------------------------------------------------------------------------- | --------------------------------------------------------- | | `` | release state, shown as text | | `` | a screenshot; `dark` is the same screen in the dark theme | +| `` | a QR code on a white plate in both themes | | `` | VitePress's own badge | | `HomeIndex`, `HomeSteps`, `SplitBlock`, `HomePlatforms`, `HomePrivacy`, `HomeScope` | the home pages only; they render the `home:` frontmatter | @@ -137,6 +138,9 @@ light and the dark theme, and waits until the view has finished loading. It stop `CODEGRAPH_SCREENS_COMMIT` changes the corpus commit and `CODEGRAPH_SCREENS_PORT` the port. +`public/community/wechat-official-account.jpg` is the WeChat Official Account's QR code, the same image the pt-tools +and Voltip sites show. The sync stops when a page names a `/screens/` or `/community/` file that does not exist. + Look at every image before committing it. Capture again when the viewer's text or layout changes, and update the `width`/`height` in both home pages and in the `` tags if the size changes. diff --git a/docs/site/en/guide/quick-start.md b/docs/site/en/guide/quick-start.md index 214fe6e..0198053 100644 --- a/docs/site/en/guide/quick-start.md +++ b/docs/site/en/guide/quick-start.md @@ -198,12 +198,78 @@ the command line's view of `codegraph_explore`, the tool coding agents call most ## 5. Follow calls and changes -| Command | Lists | -| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| `codegraph search applyDiscount -p .` | the symbols whose name matches, best match first, with their location and signature | -| `codegraph callers applyDiscount -p .` | what calls or imports it: here `checkout` and the file `checkout.ts` | -| `codegraph callees checkout -p .` | what it calls: `applyDiscount`, `subtotal`, `tax`, and the `Cart` type it uses | -| `codegraph impact applyDiscount -p .` | everything a change would reach, through callers of callers, grouped by file: here `checkout`, `checkout.ts` and `main.ts` | +`search` finds symbols by name, best match first. `callers` and `callees` follow the calls one step, and `impact` +follows callers of callers to everything a change would reach, grouped by file: + +::: code-group + +```text [search] +$ codegraph search applyDiscount -p . + +Search Results for "applyDiscount": + +function applyDiscount + src/pricing.ts:3 + (amount: number, code?: string): number + +import ./pricing + src/checkout.ts:2 + import { applyDiscount, tax } from "./pricing"; +``` + +```text [callers] +$ codegraph callers applyDiscount -p . + +Callers of "applyDiscount" (2): + +applyDiscount (function) - src/pricing.ts:3 + +function checkout + src/checkout.ts:4 + +file checkout.ts [imports] + src/checkout.ts:1 +``` + +```text [callees] +$ codegraph callees checkout -p . + +Callees of "checkout" (4): + +checkout (function) - src/checkout.ts:4 + +function applyDiscount + src/pricing.ts:3 + +method subtotal + src/cart.ts:14 + +function tax + src/pricing.ts:8 + +class Cart [references] + src/cart.ts:7 +``` + +```text [impact] +$ codegraph impact applyDiscount -p . + +Impact of changing "applyDiscount" - 4 affected symbols: + +applyDiscount (function) - src/pricing.ts:3 + +src/checkout.ts + function checkout:4 + file checkout.ts:1 + +src/main.ts + file main.ts:1 + +src/pricing.ts + function applyDiscount:3 +``` + +::: Each of them takes `--json` for scripts. diff --git a/docs/site/en/index.md b/docs/site/en/index.md index 5d82e27..ee4dad4 100644 --- a/docs/site/en/index.md +++ b/docs/site/en/index.md @@ -277,7 +277,9 @@ The scripts check every archive against the release's `SHA256SUMS` before instal -## Feedback +## Community and feedback -Bug reports and feature requests go to [GitHub Issues](https://github.com/sunerpy/codegraph-rust/issues). CodeGraph is -MIT-licensed. +Bug reports and feature requests go to [GitHub Issues](https://github.com/sunerpy/codegraph-rust/issues). Scan the code +with WeChat to follow the Official Account 六月水蓝. CodeGraph is MIT-licensed. + + diff --git a/docs/site/en/reference/community.md b/docs/site/en/reference/community.md new file mode 100644 index 0000000..c296c1d --- /dev/null +++ b/docs/site/en/reference/community.md @@ -0,0 +1,18 @@ +--- +description: Where to ask questions, report problems and follow news about CodeGraph. +--- + +# Community + +This page lists where to ask questions, report problems and follow news about CodeGraph. + +## Problems and suggestions + +Report bugs and request features in [GitHub Issues](https://github.com/sunerpy/codegraph-rust/issues). Include the +output of `codegraph --version` and the steps that reproduce the problem. + +## WeChat + +Scan the code with WeChat to follow the Official Account 六月水蓝. + + diff --git a/docs/site/guide/quick-start.md b/docs/site/guide/quick-start.md index cf6cf7a..6136d2d 100644 --- a/docs/site/guide/quick-start.md +++ b/docs/site/guide/quick-start.md @@ -189,12 +189,77 @@ Found 10 symbols across 4 files. ## 5. 跟踪调用和改动 -| 命令 | 列出 | -| -------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `codegraph search applyDiscount -p .` | 名称匹配的符号，最匹配的排在最前，附带位置和签名 | -| `codegraph callers applyDiscount -p .` | 调用或导入它的代码：这里是 `checkout` 和文件 `checkout.ts` | -| `codegraph callees checkout -p .` | 它调用的代码：`applyDiscount`、`subtotal`、`tax`，以及它用到的类型 `Cart` | -| `codegraph impact applyDiscount -p .` | 改动它会影响的全部代码，沿调用方的调用方逐层展开，按文件分组：这里是 `checkout`、`checkout.ts` 和 `main.ts` | +`search` 按名称查找符号，最匹配的排在最前。`callers` 和 `callees` 沿调用关系前进一步；`impact` 沿调用方的调用方逐层展开，列出改动会影响的全部代码，并按文件分组： + +::: code-group + +```text [search] +$ codegraph search applyDiscount -p . + +Search Results for "applyDiscount": + +function applyDiscount + src/pricing.ts:3 + (amount: number, code?: string): number + +import ./pricing + src/checkout.ts:2 + import { applyDiscount, tax } from "./pricing"; +``` + +```text [callers] +$ codegraph callers applyDiscount -p . + +Callers of "applyDiscount" (2): + +applyDiscount (function) - src/pricing.ts:3 + +function checkout + src/checkout.ts:4 + +file checkout.ts [imports] + src/checkout.ts:1 +``` + +```text [callees] +$ codegraph callees checkout -p . + +Callees of "checkout" (4): + +checkout (function) - src/checkout.ts:4 + +function applyDiscount + src/pricing.ts:3 + +method subtotal + src/cart.ts:14 + +function tax + src/pricing.ts:8 + +class Cart [references] + src/cart.ts:7 +``` + +```text [impact] +$ codegraph impact applyDiscount -p . + +Impact of changing "applyDiscount" - 4 affected symbols: + +applyDiscount (function) - src/pricing.ts:3 + +src/checkout.ts + function checkout:4 + file checkout.ts:1 + +src/main.ts + file main.ts:1 + +src/pricing.ts + function applyDiscount:3 +``` + +::: 这些命令都支持 `--json`，供脚本使用。 diff --git a/docs/site/index.md b/docs/site/index.md index 13c1fd5..3fdcd14 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -270,6 +270,8 @@ cargo install --locked --git https://github.com/sunerpy/codegraph-rust codegraph -## 反馈 +## 交流与反馈 -问题报告和功能建议请提交到 [GitHub Issues](https://github.com/sunerpy/codegraph-rust/issues)。CodeGraph 以 MIT 许可发布。 +问题报告和功能建议请提交到 [GitHub Issues](https://github.com/sunerpy/codegraph-rust/issues)。使用微信扫码，可以关注公众号「六月水蓝」。CodeGraph 以 MIT 许可发布。 + + diff --git a/docs/site/public/community/wechat-official-account.jpg b/docs/site/public/community/wechat-official-account.jpg new file mode 100644 index 0000000..a7aaabb Binary files /dev/null and b/docs/site/public/community/wechat-official-account.jpg differ diff --git a/docs/site/reference/community.md b/docs/site/reference/community.md new file mode 100644 index 0000000..b5b2811 --- /dev/null +++ b/docs/site/reference/community.md @@ -0,0 +1,17 @@ +--- +description: 在哪里提问、报告问题，以及关注 CodeGraph 的消息。 +--- + +# 交流与反馈 + +本页列出提问、报告问题和关注 CodeGraph 消息的渠道。 + +## 问题与建议 + +问题报告和功能建议请提交到 [GitHub Issues](https://github.com/sunerpy/codegraph-rust/issues)。报告问题时，请附上 `codegraph --version` 的输出和复现步骤。 + +## 微信公众号 + +使用微信扫码，关注公众号「六月水蓝」。 + + diff --git a/scripts/docs-check.py b/scripts/docs-check.py index da04a74..3b13d6d 100755 --- a/scripts/docs-check.py +++ b/scripts/docs-check.py @@ -170,11 +170,11 @@ def main() -> int: require_headings( "README.md", - ["Why CodeGraph", "Install", "Quickstart", "CLI", "MCP", "Agents and IDEs", "Performance", "Development", "License"], + ["Why CodeGraph", "Install", "Quickstart", "CLI", "MCP", "Agents and IDEs", "Browser viewer", "Performance", "Development", "Community", "License"], ) require_headings( "docs/readme/README.zh-CN.md", - ["为什么选择 CodeGraph", "安装", "快速上手", "CLI", "MCP", "Agents 与 IDE", "性能", "开发", "许可证"], + ["为什么选择 CodeGraph", "安装", "快速上手", "CLI", "MCP", "Agents 与 IDE", "浏览器查看器", "性能", "开发", "交流与反馈", "许可证"], ) english = read("README.md")