codegraphx 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. codegraphx-0.1.0/.gitignore +44 -0
  2. codegraphx-0.1.0/CHANGELOG.md +72 -0
  3. codegraphx-0.1.0/LICENSE +21 -0
  4. codegraphx-0.1.0/PKG-INFO +262 -0
  5. codegraphx-0.1.0/README.md +219 -0
  6. codegraphx-0.1.0/benchmarks/README.md +21 -0
  7. codegraphx-0.1.0/pyproject.toml +119 -0
  8. codegraphx-0.1.0/src/codegraph/__init__.py +37 -0
  9. codegraphx-0.1.0/src/codegraph/cli.py +106 -0
  10. codegraphx-0.1.0/src/codegraph/commands/__init__.py +1 -0
  11. codegraphx-0.1.0/src/codegraph/commands/conflicts.py +154 -0
  12. codegraphx-0.1.0/src/codegraph/commands/diff.py +189 -0
  13. codegraphx-0.1.0/src/codegraph/commands/export.py +141 -0
  14. codegraphx-0.1.0/src/codegraph/commands/graph.py +200 -0
  15. codegraphx-0.1.0/src/codegraph/commands/index.py +924 -0
  16. codegraphx-0.1.0/src/codegraph/commands/serve.py +62 -0
  17. codegraphx-0.1.0/src/codegraph/commands/why.py +645 -0
  18. codegraphx-0.1.0/src/codegraph/decisions/__init__.py +18 -0
  19. codegraphx-0.1.0/src/codegraph/decisions/conflicts.py +238 -0
  20. codegraphx-0.1.0/src/codegraph/decisions/extractor.py +698 -0
  21. codegraphx-0.1.0/src/codegraph/decisions/llm_extractor.py +161 -0
  22. codegraphx-0.1.0/src/codegraph/decisions/sources.py +298 -0
  23. codegraphx-0.1.0/src/codegraph/git/__init__.py +5 -0
  24. codegraphx-0.1.0/src/codegraph/git/diff.py +115 -0
  25. codegraphx-0.1.0/src/codegraph/git/history.py +156 -0
  26. codegraphx-0.1.0/src/codegraph/git/incremental.py +75 -0
  27. codegraphx-0.1.0/src/codegraph/git/refs.py +70 -0
  28. codegraphx-0.1.0/src/codegraph/models.py +211 -0
  29. codegraphx-0.1.0/src/codegraph/parser/__init__.py +1 -0
  30. codegraphx-0.1.0/src/codegraph/parser/base.py +164 -0
  31. codegraphx-0.1.0/src/codegraph/parser/common.py +147 -0
  32. codegraphx-0.1.0/src/codegraph/parser/parallel.py +96 -0
  33. codegraphx-0.1.0/src/codegraph/parser/registry.py +83 -0
  34. codegraphx-0.1.0/src/codegraph/parser/treesitter_cpp.py +102 -0
  35. codegraphx-0.1.0/src/codegraph/parser/treesitter_go.py +113 -0
  36. codegraphx-0.1.0/src/codegraph/parser/treesitter_java.py +79 -0
  37. codegraphx-0.1.0/src/codegraph/parser/treesitter_js.py +15 -0
  38. codegraphx-0.1.0/src/codegraph/parser/treesitter_py.py +163 -0
  39. codegraphx-0.1.0/src/codegraph/parser/treesitter_rust.py +120 -0
  40. codegraphx-0.1.0/src/codegraph/parser/treesitter_ts.py +178 -0
  41. codegraphx-0.1.0/src/codegraph/storage.py +767 -0
  42. codegraphx-0.1.0/src/codegraph/web/__init__.py +1 -0
  43. codegraphx-0.1.0/src/codegraph/web/app.py +271 -0
  44. codegraphx-0.1.0/src/codegraph/web/static/app.js +356 -0
  45. codegraphx-0.1.0/src/codegraph/web/static/index.html +59 -0
  46. codegraphx-0.1.0/src/codegraph/web/static/styles.css +92 -0
  47. codegraphx-0.1.0/tests/_parser_helpers.py +25 -0
  48. codegraphx-0.1.0/tests/fixtures/sample.cpp +15 -0
  49. codegraphx-0.1.0/tests/fixtures/sample.go +14 -0
  50. codegraphx-0.1.0/tests/fixtures/sample.java +14 -0
  51. codegraphx-0.1.0/tests/fixtures/sample.js +14 -0
  52. codegraphx-0.1.0/tests/fixtures/sample.py +12 -0
  53. codegraphx-0.1.0/tests/fixtures/sample.rs +16 -0
  54. codegraphx-0.1.0/tests/fixtures/sample.ts +14 -0
  55. codegraphx-0.1.0/tests/test_call_resolution.py +59 -0
  56. codegraphx-0.1.0/tests/test_category_persistence.py +87 -0
  57. codegraphx-0.1.0/tests/test_changelog_sources.py +111 -0
  58. codegraphx-0.1.0/tests/test_clause_cleanup.py +40 -0
  59. codegraphx-0.1.0/tests/test_cli.py +99 -0
  60. codegraphx-0.1.0/tests/test_cli_contract.py +44 -0
  61. codegraphx-0.1.0/tests/test_commit_body_wrapping.py +76 -0
  62. codegraphx-0.1.0/tests/test_conflicts.py +118 -0
  63. codegraphx-0.1.0/tests/test_console_encoding.py +110 -0
  64. codegraphx-0.1.0/tests/test_date_refs.py +115 -0
  65. codegraphx-0.1.0/tests/test_decision_binding.py +121 -0
  66. codegraphx-0.1.0/tests/test_decision_extractor.py +118 -0
  67. codegraphx-0.1.0/tests/test_decision_link_uniqueness.py +133 -0
  68. codegraphx-0.1.0/tests/test_decision_text_quality.py +105 -0
  69. codegraphx-0.1.0/tests/test_decision_tiers.py +254 -0
  70. codegraphx-0.1.0/tests/test_decisions_command.py +86 -0
  71. codegraphx-0.1.0/tests/test_diff.py +141 -0
  72. codegraphx-0.1.0/tests/test_edge_dedup.py +79 -0
  73. codegraphx-0.1.0/tests/test_extractor_recall.py +62 -0
  74. codegraphx-0.1.0/tests/test_git_diff_lines.py +81 -0
  75. codegraphx-0.1.0/tests/test_git_history.py +67 -0
  76. codegraphx-0.1.0/tests/test_governed_binding.py +86 -0
  77. codegraphx-0.1.0/tests/test_incremental_index.py +230 -0
  78. codegraphx-0.1.0/tests/test_json_contract.py +158 -0
  79. codegraphx-0.1.0/tests/test_line_binding.py +116 -0
  80. codegraphx-0.1.0/tests/test_llm_extractor.py +55 -0
  81. codegraphx-0.1.0/tests/test_node_lifecycle.py +162 -0
  82. codegraphx-0.1.0/tests/test_parallel_parser.py +100 -0
  83. codegraphx-0.1.0/tests/test_parser_cpp.py +115 -0
  84. codegraphx-0.1.0/tests/test_parser_go.py +73 -0
  85. codegraphx-0.1.0/tests/test_parser_java.py +27 -0
  86. codegraphx-0.1.0/tests/test_parser_js.py +36 -0
  87. codegraphx-0.1.0/tests/test_parser_parity.py +89 -0
  88. codegraphx-0.1.0/tests/test_parser_py.py +36 -0
  89. codegraphx-0.1.0/tests/test_parser_rust.py +57 -0
  90. codegraphx-0.1.0/tests/test_parser_ts.py +36 -0
  91. codegraphx-0.1.0/tests/test_readme_screenshots.py +74 -0
  92. codegraphx-0.1.0/tests/test_rst_literals.py +47 -0
  93. codegraphx-0.1.0/tests/test_stable_uid.py +78 -0
  94. codegraphx-0.1.0/tests/test_web_api.py +56 -0
  95. codegraphx-0.1.0/tests/test_web_scope.py +254 -0
  96. codegraphx-0.1.0/tests/test_why_db_discovery.py +77 -0
  97. codegraphx-0.1.0/tests/test_why_fallback.py +207 -0
  98. codegraphx-0.1.0/vscode-extension/LICENSE +21 -0
  99. codegraphx-0.1.0/vscode-extension/README.md +31 -0
@@ -0,0 +1,44 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .eggs/
6
+ dist/
7
+ build/
8
+ .venv/
9
+ .venv_ci_test/
10
+ venv/
11
+ .pytest_cache/
12
+ .coverage
13
+ htmlcov/
14
+ .mypy_cache/
15
+ .ruff_cache/
16
+
17
+ # CodeGraph 本地图库
18
+ .codegraph/
19
+
20
+ # 环境与密钥
21
+ .env
22
+ .env.local
23
+
24
+ # 系统
25
+ .DS_Store
26
+ Thumbs.db
27
+
28
+ # 编辑器
29
+ .idea/
30
+ .vscode/
31
+
32
+ # Node / packaging
33
+ node_modules/
34
+ docs-site/.vitepress/dist/
35
+ docs-site/.vitepress/cache/
36
+ vscode-extension/out/
37
+ *.vsix
38
+
39
+ # Video edit intermediates
40
+ submission/video_work/
41
+
42
+ # 已发布的 demo(根目录 demo.html / demo.cast)由 GitHub Pages 提供,需要提交,勿忽略
43
+ tests.xml
44
+ coverage.xml
@@ -0,0 +1,72 @@
1
+ # Changelog
2
+
3
+ ## Changed
4
+
5
+ - Index walks real Git history and versions CodeNodes with valid_from / valid_to because time travel must reflect actual commits rather than a static snapshot.
6
+ - Decision extraction prefers commit messages, ADRs, and CHANGELOG over bundled samples because provenance should point at real sources.
7
+ - A second `index` merges into the stored graph instead of clearing it, so re-running the command no longer destroys Git history.
8
+ - Decision records carry a `decision` / `event` tier, and only records that state a reason or a rejected alternative are shown as decisions.
9
+ - ADRs and CHANGELOG entries bind to the code they name, so a design rule can be reached from the line it governs.
10
+ - A decision that claims more than 10 files or 250 lines keeps only a commit-level binding, so one noisy commit cannot claim thousands of lines.
11
+ - Conflict detection matches whole words and requires a shared topic, so unrelated documents in one folder no longer contradict each other.
12
+ - `codegraph index --json` writes progress to stderr, so stdout is a single JSON document that editors can parse.
13
+ - `codegraph why` accepts an absolute path, which is what an editor hands over for the current file.
14
+ - The web API filters by scope instead of widening it: `/api/graph` used to fall back to every decision in the repository when a scope had none, and reported the unscoped count in its stats. A scope now matches on a path boundary (`src` no longer matches `src2`) and a decision is in scope when it was recorded there **or** governs code there, so an ADR bound with `governs:` shows up for the files it governs.
15
+ - `/api/timeline` honours its `scope` parameter. It previously ignored it, so the slider ticks came from every file in the graph.
16
+ - `/api/why` uses the same resolution as the `codegraph why` command, including the symbol-range lookup, so the UI and the CLI cannot disagree about whether a decision exists for a line.
17
+ - `codegraph serve` opens the browser only after the port is bound, instead of before uvicorn starts.
18
+ - C++ in-class methods are nodes with the class as their parent, and their calls produce edges. Name resolution walks the declarator chain, so `int Calculator::compute(int)` and `int spin(int n)` inside a class are no longer anonymous, and a prototype (`int helper(int);`) is a function while `int limit = 3;` is not.
19
+ - Rust `impl` blocks and Go methods now hang off the type they belong to: `impl Scale for Meter { fn scale }` attaches to `Meter`, and `func (c *Calculator) Add()` attaches to `Calculator`. Previously `impl_item` and `type_declaration` were dead entries in the kind maps.
20
+ - Call edges resolve against every symbol live at that commit, not just the file being parsed. The git path previously produced **zero** cross-file `uses` edges while the working-tree path produced them, so the same repository gave two different graphs. Express: 1308 → 3951 `uses` edges, 2515 of them cross-file.
21
+ - Git and working-tree parsing now share one edge rule; `ingest_commit` versions all changed files first, then resolves edges.
22
+ - A call to a name defined in several files prefers the definition in the caller's own file, and only fans out across files when nothing local matches. `helper()` next to its definition no longer links to every same-named `helper` in the repository: Express edges 2409 → 1460, and the share of cross-file edges pointing at an ambiguous name fell from 21% to 17% on this repository.
23
+ - The public materials carry only measured numbers, and the CI suite is green again: 22 lint findings and one real typing bug had kept `ruff` failing since 2026-09-24, so `mypy` and `pytest` never ran in CI.
24
+ - Indexing reuses one Git repo handle and caches each commit's parsed diff, because decision binding asked for the same commit once per record: on `got`, 85 records shared 50 commits, and the redundant git calls cost a third of the index time. `got` depth 200: 111s → 75s, identical graph.
25
+ - `codegraph why` on a line with no bound record now reports the decisions that govern the whole file, so a line inside a governed module returns that module's ADR instead of "no record". The JSON payload gains a `related` array for the same case.
26
+ - Date refs use the local calendar, not UTC: a commit's `git log --date=short` date now resolves with `diff` and `graph --at`. Comparing against the UTC date made every date fail for part of the day east of Greenwich (a commit at 00:30 in UTC+8 is still the previous day in UTC), and `graph --at` placed its cut-off eight hours late. Both are covered by timezone tests that do not depend on the machine clock.
27
+ - Changelogs are read from `CHANGELOG`, `CHANGES`, `HISTORY` and `NEWS` files in both markdown and reStructuredText, and every bullet is a candidate instead of only a `## Changed` section. The tier classifier keeps the ones with a rationale, so this raises recall without lowering precision: Flask went from **1 decision to 56** on the same checkout, because a Python project ships `CHANGES.rst` rather than `CHANGELOG.md`.
28
+ - `codegraph decisions --timeline` works without `--file`: omitting it lists the decisions of every file, which is the natural first look after indexing. `--file` is now a filter instead of a required argument.
29
+ - `codegraph graph` and `codegraph decisions` gained `--json`, joining `why` and `index`. All four decision payloads now come from one serializer, and the shapes are documented in [json-contract.md](docs/json-contract.md) and pinned by tests, so the editor extension has a stable contract instead of whatever the models happen to emit.
30
+ - Decision text is polished at extraction time: structural section headings are dropped (`Changed: …`, `🚀 Improvements: …`), sentences are capitalised unless they start with a name (`demo.html`), and clause fragments are no longer stored as decisions (`now bracket the range`, `Same run`, `Update`). A plain commit subject is still kept as a history event — only decisions have to read as a statement.
31
+ - Changelog discovery is case-insensitive. Express ships `History.md`; a case-sensitive lookup found it on Windows but not on macOS or Linux, so the same checkout produced different graphs per platform. Reading it took Express from 5 decisions to **22 of 242**, 17 of them bound to a code line.
32
+ - Console output is now UTF-8 on a non-UTF-8 console. On Chinese Windows (GBK)
33
+ the middle dot arrived as a Chinese character (· read as 路) in any redirected
34
+ log, and characters GBK cannot encode (•, ✅) raised UnicodeEncodeError
35
+ mid-card. Both came from errors="replace" without reconfiguring the
36
+ encoding; the streams are reconfigured to UTF-8 instead.
37
+ - The README shows real screenshots, generated from captured output rather
38
+ than drawn: docs/assets/captures/*.txt hold text produced by an actual
39
+ run, scripts/render_terminal_svg.py embeds it in an SVG, and CI
40
+ re-renders and fails if the images no longer match. Captures use --full
41
+ so the same command does not report a different graph on a cold database.
42
+ - Clause tails are trimmed before a record is stored: a sentence split at
43
+ "because" left reasons such as "to avoid errors from version mismatches (e.g."
44
+ hanging inside a parenthesis. Unbalanced brackets and trailing connectors are
45
+ removed without inventing text, and the same cleanup runs on content and
46
+ alternatives -- but never changes an identifier's spelling.
47
+ - A fifth measured project, google/gson (Java), closes the ecosystem gap: 8439
48
+ nodes / 78211 edges / 223 records / **29 decisions** (13.0%), 23 of them bound
49
+ to code. Ten of the decisions come from javadoc comments that explain a design
50
+ choice, which is the comment extractor working on a language it had not been
51
+ measured on before.
52
+ - Fixed a crash on real repositories: `decision_code_links` is unique on (decision, file, line) and two nodes can share a start line — a class and its first method — which aborted `index` with an `IntegrityError`. Duplicate line links are now collapsed at the write boundary, keeping the first node.
53
+ - Prose decisions bind through a backticked symbol name that is **unique** in the graph, even when it is short and lowercase (`redirect`), while a name shared by several files still needs the distinctive spelling. Flask: 6 → 10 of 56 decisions reachable from a code line.
54
+ - reStructuredText literals are read as identifiers: a Python changelog writes `` `redirect` `` with two backticks where markdown writes it with one, and only the single form was matched, so most of Flask's nameable decisions were invisible to the binder. The measured effect on binding is small — of its 54 decisions, 32 backticked words are not node names at all (HTTP methods, config keys, prose) — but the ones that do name code now reach it.
55
+ - `scripts/sample_why.py` measures whether `why` **answers**, not just whether records bind: it asks about 40 real locations per repository (half of them decision-linked, half random live symbols) and classifies each reply. The results are published in [extraction-recall.md](docs/extraction-recall.md) instead of asserted: gson 40% line-level, express 27%, cobra 12%, flask 12%.
56
+
57
+ - A sixth measured project, `BurntSushi/ripgrep` (Rust), exercises the sixth parser on real code: 20883 nodes / 121893 edges / 227 records / **28 decisions**, 22 of them bound. Its 121893 edges are the largest graph measured, and 82% of its decisions reach a code line — the highest of the six, because ripgrep writes commit bodies that name what changed. Only the C++ parser now has no measured project behind it.
58
+ - `scripts/summarize_graph.py` prints one graph's languages, decision counts, bound decisions and structural sanity, so a measurement does not have to be retyped into a document by hand.
59
+
60
+ - A C macro with a body is no longer parsed as a function. TEST(suite, name) { ... } arrives from tree-sitter as a unction_definition named after the macro, so every TEST in a file became a node called TEST; because call edges match on name, those nodes then fanned out to each other. On mtlib/fmt that turned 1500 nodes into 416k edges. An all-caps name is now treated as a macro, which is the C/C++ convention.
61
+ - The edge table stores one row per (from, to, kind). A call site used to emit one row per occurrence, so a function calling ormat fifty times wrote fifty identical rows: measured across five repositories, 6-12% of edge rows were duplicates, and on fmt one template helper held 1026 rows pointing at 18 targets. Counts drop 8-26% per project (express 1460 -> 1124, gson 78211 -> 61905, ripgrep 121893 -> 90380).
62
+ - A seventh measured project, mtlib/fmt (C++), closes the last unmeasured parser: 24899 nodes / 104335 edges / 248 records / **55 decisions**, 47 of them bound. All seven parsers now have a real repository behind them, so "7 languages" is measured rather than a list of grammars.
63
+ - scripts/measure_all_projects.py prints every project's index-time node count, live symbol count, edge count and decision breakdown in one run, so a table is filled from measurement instead of from memory.
64
+
65
+ ## Removed
66
+
67
+ - Conventional-commit subjects are no longer presented as decisions; they stay queryable as events with `--include-events`.
68
+ - The generic `use` / `avoid` opposite pair, which matched inside ordinary English words.
69
+ - The bundled sample decisions. `SAMPLE_DECISIONS` was written into the graph whenever a repository recorded no rationale, so a project with no decisions was shown five invented ones (including "PR #48 · Issue #31"). `why` now reports that it has no record instead.
70
+ - The Dgraph backend and the `--backend` flag on every command ([ADR-006](docs/adr/006-drop-dgraph-backend.md)): `src/codegraph/graph/` (503 lines), `docker-compose.yml`, `.env.example`, `pydgraph`, the Dgraph tests and the `codegraph.backend` editor setting. One of its paths printed sample data, one ignored the flag, one always crashed, and no shipped query needed a graph database.
71
+ - `docs/prompts/`, an internal agent-prompt pack that did not belong in a public repository.
72
+ - The dead `method` filter in the web UI. No parser emits a node of kind `method` (methods are `function`), so ticking it filtered the graph to nothing.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CodeGraph Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,262 @@
1
+ Metadata-Version: 2.5
2
+ Name: codegraphx
3
+ Version: 0.1.0
4
+ Summary: Turn code structure, history, and design decisions into one queryable graph
5
+ Project-URL: Homepage, https://github.com/fourwich/codegraph
6
+ Project-URL: Repository, https://github.com/fourwich/codegraph
7
+ Project-URL: Documentation, https://github.com/fourwich/codegraph#readme
8
+ Project-URL: Bug Tracker, https://github.com/fourwich/codegraph/issues
9
+ Author: CodeGraph Contributors
10
+ License: MIT
11
+ License-File: LICENSE
12
+ Keywords: code-graph,developer-tools,git,provenance,tree-sitter
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Software Development :: Quality Assurance
19
+ Classifier: Topic :: Software Development :: Version Control :: Git
20
+ Requires-Python: >=3.10
21
+ Requires-Dist: fastapi>=0.110.0
22
+ Requires-Dist: gitpython>=3.1.40
23
+ Requires-Dist: httpx>=0.27.0
24
+ Requires-Dist: pydantic>=2.5.0
25
+ Requires-Dist: python-dotenv>=1.0.0
26
+ Requires-Dist: rich>=13.7.0
27
+ Requires-Dist: tree-sitter-cpp>=0.21.0
28
+ Requires-Dist: tree-sitter-go>=0.21.0
29
+ Requires-Dist: tree-sitter-java>=0.21.0
30
+ Requires-Dist: tree-sitter-python>=0.23
31
+ Requires-Dist: tree-sitter-rust>=0.21.0
32
+ Requires-Dist: tree-sitter-typescript>=0.23
33
+ Requires-Dist: tree-sitter>=0.22
34
+ Requires-Dist: typer>=0.12.0
35
+ Requires-Dist: uvicorn[standard]>=0.29.0
36
+ Provides-Extra: dev
37
+ Requires-Dist: httpx>=0.27.0; extra == 'dev'
38
+ Requires-Dist: mypy>=1.8.0; extra == 'dev'
39
+ Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
40
+ Requires-Dist: pytest>=8.0.0; extra == 'dev'
41
+ Requires-Dist: ruff>=0.4.0; extra == 'dev'
42
+ Description-Content-Type: text/markdown
43
+
44
+ # CodeGraph
45
+
46
+ ![tests](https://img.shields.io/badge/tests-235%20passing-brightgreen)
47
+ ![CI](https://github.com/fourwich/codegraph/actions/workflows/ci.yml/badge.svg)
48
+ ![python](https://img.shields.io/badge/python-3.10%2B-blue)
49
+ ![license](https://img.shields.io/badge/license-MIT-lightgrey)
50
+
51
+ **English:** Turn code structure, git history, and design decisions into one queryable graph — ask “why is this line here?” and get a decision card, not just a blame line.
52
+
53
+ Why not just ask an AI? Because AI cannot read a closed issue from two years ago — and because a commit subject is not an answer. CodeGraph shows a decision card only when the record states a reason or a rejected alternative; everything else is kept as history you can ask for explicitly. On Express.js that means **22 decisions out of 242 records**, not 174 "decisions" that were mostly version bumps.
54
+
55
+ **中文:** 把代码结构、历史变更和设计决策变成一张可查询的图。不只回答「谁改的」,更回答「为什么这么写」。
56
+
57
+ **Status:** alpha · 8 CLI commands · 7 languages · SQLite storage · 235 tests
58
+
59
+ > **Note on the Devpost numbers.** The hackathon entry was submitted before two
60
+ > bugs were found while measuring a sixth and seventh project, and the page was
61
+ > frozen at the deadline. An all-caps C macro was being parsed as a function
62
+ > (`fmt` reported 416k edges instead of 104k), and the edge table stored one row
63
+ > per call site rather than one per relationship (6–12% of rows were duplicates).
64
+ > Every table in this repository carries the corrected figures; the Devpost page
65
+ > shows the pre-fix ones. [docs/devpost_edit_kit.md](docs/devpost_edit_kit.md)
66
+ > keeps the published text as the record of what the judges saw.
67
+
68
+ See [docs/architecture.md](docs/architecture.md) for the full architecture overview.
69
+
70
+ - GitHub: https://github.com/fourwich/codegraph
71
+ - Live demo: https://fourwich.github.io/codegraph
72
+
73
+ ### What it looks like
74
+
75
+ `codegraph why` on a line of this repository — the card is the ADR that decided
76
+ the line, reached from the line itself:
77
+
78
+ ![codegraph why showing a decision card](docs/assets/why.svg)
79
+
80
+ `codegraph index` builds the graph; the counts below are real output from this
81
+ repository:
82
+
83
+ ![codegraph index output](docs/assets/index.svg)
84
+
85
+ `codegraph decisions --timeline` lists decisions oldest first, and
86
+ `codegraph conflicts` reports contradictions it can justify:
87
+
88
+ <p>
89
+ <img src="docs/assets/decisions.svg" alt="decision timeline" width="46%" />
90
+ <img src="docs/assets/conflicts.svg" alt="conflict report" width="52%" />
91
+ </p>
92
+
93
+ These are not mockups: `scripts/render_terminal_svg.py` renders text captured
94
+ from an actual run, so a screenshot cannot drift from the tool.
95
+
96
+ See [benchmarks](docs/benchmarks.md) for real-project attempts and synthetic performance numbers.
97
+ See [case study on Express.js](docs/case-study.md) for real-world results after JavaScript support.
98
+ See [decision extraction](docs/extraction-recall.md) for how `decision` and `event` records are separated, and how to reproduce the precision numbers.
99
+
100
+ ### Reviewing this in five minutes
101
+
102
+ ```bash
103
+ pip install -e ".[dev]" # or: uv pip install -e ".[dev]"
104
+ pytest -q # 235 tests, no network needed
105
+ codegraph index . # builds the graph for this repository
106
+ codegraph why src/codegraph/storage.py:200 # one decision card, end to end
107
+ codegraph graph --at 2026-09-28 --scope src # the same repository in the past
108
+ ```
109
+
110
+ Then: [the architecture](docs/architecture.md) ·
111
+ [what was measured and what is still a limitation](docs/extraction-recall.md) ·
112
+ [the JSON contract for editors](docs/json-contract.md) ·
113
+ [the 5-minute pitch script](docs/pitch_5min.md).
114
+
115
+ ## Status
116
+
117
+ Verified with `pytest -q` and `codegraph --help` (235 tests passing, over 80% coverage).
118
+
119
+ Every test count in this README and in `docs/` is checked against `pytest --collect-only` by `scripts/check_materials.py`, which runs in CI — a stale number fails the build instead of shipping.
120
+
121
+ - [x] Product site (HTML / CSS / JS)
122
+ - [x] CLI with 8 commands (`index` / `why` / `graph` / `decisions` / `conflicts` / `export` / `serve` / `diff`)
123
+ - [x] tree-sitter parsing (7 languages)
124
+ - [x] SQLite storage
125
+ - [x] Real Git history traversal
126
+ - [x] Decision extraction from commits, ADRs, CHANGELOG — with a `decision` / `event` tier split
127
+ - [x] Real time-travel queries (`graph --at`)
128
+ - [x] 235 tests passing
129
+ - [x] Local web visualization (`codegraph serve`)
130
+ - [x] VSCode extension + `why --json` (vsix packaged and installable)
131
+ - [x] Optional Ollama hook (`--use-llm`)
132
+
133
+ ## Language support
134
+
135
+ | Language | Extensions | Parser |
136
+ |---|---|---|
137
+ | TypeScript | `.ts` `.tsx` | `treesitter_ts.py` |
138
+ | JavaScript | `.js` `.mjs` `.cjs` | `treesitter_js.py` |
139
+ | Python | `.py` | `treesitter_py.py` |
140
+ | Java | `.java` | `treesitter_java.py` |
141
+ | Go | `.go` | `treesitter_go.py` |
142
+ | Rust | `.rs` | `treesitter_rust.py` |
143
+ | C++ | `.cpp` `.cc` `.cxx` `.hpp` `.hh` `.hxx` `.h` | `treesitter_cpp.py` |
144
+
145
+ ## Quick start
146
+
147
+ CodeGraph is not on PyPI yet. Install from source:
148
+
149
+ ```bash
150
+ git clone https://github.com/fourwich/codegraph
151
+ cd codegraph
152
+
153
+ # recommended: uv
154
+ uv venv
155
+ uv pip install -e ".[dev]"
156
+
157
+ # or: venv + pip
158
+ python -m venv .venv
159
+ .venv\Scripts\pip install -e ".[dev]" # Windows
160
+ # source .venv/bin/activate && pip install -e ".[dev]" # macOS/Linux
161
+
162
+ # then, from any repository you want to inspect
163
+ codegraph index .
164
+ codegraph why src/main.py:42
165
+ ```
166
+
167
+ ## Commands (8)
168
+
169
+ ```bash
170
+ codegraph --help
171
+ codegraph index . [--depth N] [--use-llm] [--json] [--full]
172
+ codegraph why docs/adr/001-use-sqlite-default.md:1 [--json] [--include-events]
173
+ codegraph graph --at 2026-09-23 --scope src
174
+ codegraph decisions --timeline [--file PATH] [--include-events]
175
+ codegraph diff 2026-09-23 2026-09-24 --scope src
176
+ codegraph conflicts --scope src # opposite / supersede / temporal
177
+ codegraph export --for-ai --scope src
178
+ codegraph serve --port 8080
179
+ ```
180
+
181
+ `why` answers about a code location; a decision that is only bound at file level
182
+ says so, and a location with no decision says so instead of guessing. Add
183
+ `--include-events` to see the commit history behind a line.
184
+
185
+ Decisions that have no commit of their own (ADRs, CHANGELOG entries) bind to the
186
+ code they declare, so a design rule is reachable from the line it governs:
187
+
188
+ ```markdown
189
+ # ADR-001: SQLite as the default graph store
190
+
191
+ <!-- governs: src/codegraph/storage.py -->
192
+ ```
193
+
194
+ ## Tech stack
195
+
196
+ | Layer | Choice |
197
+ |---|---|
198
+ | CLI | Python · Typer · Rich |
199
+ | Models | pydantic |
200
+ | Parsing | tree-sitter (+ language grammars) |
201
+ | Git | GitPython |
202
+ | Storage | SQLite (local `.codegraph/graph.db`) |
203
+ | Web | FastAPI · Uvicorn · Cytoscape.js |
204
+ | LLM (optional) | Ollama via httpx |
205
+ | Editor | VSCode extension (TypeScript, `vscode-extension/`) |
206
+ | Tests | pytest |
207
+
208
+ ## Tests
209
+
210
+ ```bash
211
+ pytest -q
212
+ # with coverage
213
+ pytest --cov=src/codegraph
214
+ ```
215
+
216
+ ## Storage
217
+
218
+ Everything lives in one local SQLite database at `.codegraph/graph.db`, created
219
+ by `codegraph index`. There is no server, no Docker and no network dependency.
220
+
221
+ A native graph backend (Dgraph or similar) was prototyped and **removed**: it was
222
+ 503 lines of untested client code behind `--backend dgraph`, with no multi-hop
223
+ query that needed it, and two of its code paths returned sample data or silently
224
+ ignored the flag. It comes back when a real multi-hop query justifies it — see
225
+ [docs/adr/006-drop-dgraph-backend.md](docs/adr/006-drop-dgraph-backend.md).
226
+
227
+ ## Project layout
228
+
229
+ ```text
230
+ src/codegraph/
231
+ cli.py # Typer entrypoint
232
+ models.py # CodeNode / Edge / Decision
233
+ storage.py # SQLite graph store
234
+ parser/ # tree-sitter parsers (7 languages)
235
+ commands/ # index / why / graph / decisions / conflicts / export / serve / diff
236
+ tests/
237
+ docs/ # case study, benchmarks, ADRs, demo script, submission copy
238
+ index.html # product site
239
+ ```
240
+
241
+ ## Docs
242
+
243
+ - Architecture: `docs/architecture.md`
244
+ - Decision extraction and precision: `docs/extraction-recall.md`
245
+ - Case study on Express.js: `docs/case-study.md`
246
+ - Architecture decisions: `docs/adr/`
247
+ - 60s demo voiceover: `docs/demo_voiceover.md`
248
+ - Competition copy: `docs/competition_submission.md`
249
+ - Contributing: `CONTRIBUTING.md`
250
+
251
+ ## Development notes
252
+
253
+ Built with AI coding assistants for API discovery, debugging, and documentation. Architecture, design decisions, and final code review are my own.
254
+
255
+ ## License
256
+
257
+ MIT
258
+
259
+
260
+
261
+
262
+
@@ -0,0 +1,219 @@
1
+ # CodeGraph
2
+
3
+ ![tests](https://img.shields.io/badge/tests-235%20passing-brightgreen)
4
+ ![CI](https://github.com/fourwich/codegraph/actions/workflows/ci.yml/badge.svg)
5
+ ![python](https://img.shields.io/badge/python-3.10%2B-blue)
6
+ ![license](https://img.shields.io/badge/license-MIT-lightgrey)
7
+
8
+ **English:** Turn code structure, git history, and design decisions into one queryable graph — ask “why is this line here?” and get a decision card, not just a blame line.
9
+
10
+ Why not just ask an AI? Because AI cannot read a closed issue from two years ago — and because a commit subject is not an answer. CodeGraph shows a decision card only when the record states a reason or a rejected alternative; everything else is kept as history you can ask for explicitly. On Express.js that means **22 decisions out of 242 records**, not 174 "decisions" that were mostly version bumps.
11
+
12
+ **中文:** 把代码结构、历史变更和设计决策变成一张可查询的图。不只回答「谁改的」,更回答「为什么这么写」。
13
+
14
+ **Status:** alpha · 8 CLI commands · 7 languages · SQLite storage · 235 tests
15
+
16
+ > **Note on the Devpost numbers.** The hackathon entry was submitted before two
17
+ > bugs were found while measuring a sixth and seventh project, and the page was
18
+ > frozen at the deadline. An all-caps C macro was being parsed as a function
19
+ > (`fmt` reported 416k edges instead of 104k), and the edge table stored one row
20
+ > per call site rather than one per relationship (6–12% of rows were duplicates).
21
+ > Every table in this repository carries the corrected figures; the Devpost page
22
+ > shows the pre-fix ones. [docs/devpost_edit_kit.md](docs/devpost_edit_kit.md)
23
+ > keeps the published text as the record of what the judges saw.
24
+
25
+ See [docs/architecture.md](docs/architecture.md) for the full architecture overview.
26
+
27
+ - GitHub: https://github.com/fourwich/codegraph
28
+ - Live demo: https://fourwich.github.io/codegraph
29
+
30
+ ### What it looks like
31
+
32
+ `codegraph why` on a line of this repository — the card is the ADR that decided
33
+ the line, reached from the line itself:
34
+
35
+ ![codegraph why showing a decision card](docs/assets/why.svg)
36
+
37
+ `codegraph index` builds the graph; the counts below are real output from this
38
+ repository:
39
+
40
+ ![codegraph index output](docs/assets/index.svg)
41
+
42
+ `codegraph decisions --timeline` lists decisions oldest first, and
43
+ `codegraph conflicts` reports contradictions it can justify:
44
+
45
+ <p>
46
+ <img src="docs/assets/decisions.svg" alt="decision timeline" width="46%" />
47
+ <img src="docs/assets/conflicts.svg" alt="conflict report" width="52%" />
48
+ </p>
49
+
50
+ These are not mockups: `scripts/render_terminal_svg.py` renders text captured
51
+ from an actual run, so a screenshot cannot drift from the tool.
52
+
53
+ See [benchmarks](docs/benchmarks.md) for real-project attempts and synthetic performance numbers.
54
+ See [case study on Express.js](docs/case-study.md) for real-world results after JavaScript support.
55
+ See [decision extraction](docs/extraction-recall.md) for how `decision` and `event` records are separated, and how to reproduce the precision numbers.
56
+
57
+ ### Reviewing this in five minutes
58
+
59
+ ```bash
60
+ pip install -e ".[dev]" # or: uv pip install -e ".[dev]"
61
+ pytest -q # 235 tests, no network needed
62
+ codegraph index . # builds the graph for this repository
63
+ codegraph why src/codegraph/storage.py:200 # one decision card, end to end
64
+ codegraph graph --at 2026-09-28 --scope src # the same repository in the past
65
+ ```
66
+
67
+ Then: [the architecture](docs/architecture.md) ·
68
+ [what was measured and what is still a limitation](docs/extraction-recall.md) ·
69
+ [the JSON contract for editors](docs/json-contract.md) ·
70
+ [the 5-minute pitch script](docs/pitch_5min.md).
71
+
72
+ ## Status
73
+
74
+ Verified with `pytest -q` and `codegraph --help` (235 tests passing, over 80% coverage).
75
+
76
+ Every test count in this README and in `docs/` is checked against `pytest --collect-only` by `scripts/check_materials.py`, which runs in CI — a stale number fails the build instead of shipping.
77
+
78
+ - [x] Product site (HTML / CSS / JS)
79
+ - [x] CLI with 8 commands (`index` / `why` / `graph` / `decisions` / `conflicts` / `export` / `serve` / `diff`)
80
+ - [x] tree-sitter parsing (7 languages)
81
+ - [x] SQLite storage
82
+ - [x] Real Git history traversal
83
+ - [x] Decision extraction from commits, ADRs, CHANGELOG — with a `decision` / `event` tier split
84
+ - [x] Real time-travel queries (`graph --at`)
85
+ - [x] 235 tests passing
86
+ - [x] Local web visualization (`codegraph serve`)
87
+ - [x] VSCode extension + `why --json` (vsix packaged and installable)
88
+ - [x] Optional Ollama hook (`--use-llm`)
89
+
90
+ ## Language support
91
+
92
+ | Language | Extensions | Parser |
93
+ |---|---|---|
94
+ | TypeScript | `.ts` `.tsx` | `treesitter_ts.py` |
95
+ | JavaScript | `.js` `.mjs` `.cjs` | `treesitter_js.py` |
96
+ | Python | `.py` | `treesitter_py.py` |
97
+ | Java | `.java` | `treesitter_java.py` |
98
+ | Go | `.go` | `treesitter_go.py` |
99
+ | Rust | `.rs` | `treesitter_rust.py` |
100
+ | C++ | `.cpp` `.cc` `.cxx` `.hpp` `.hh` `.hxx` `.h` | `treesitter_cpp.py` |
101
+
102
+ ## Quick start
103
+
104
+ CodeGraph is not on PyPI yet. Install from source:
105
+
106
+ ```bash
107
+ git clone https://github.com/fourwich/codegraph
108
+ cd codegraph
109
+
110
+ # recommended: uv
111
+ uv venv
112
+ uv pip install -e ".[dev]"
113
+
114
+ # or: venv + pip
115
+ python -m venv .venv
116
+ .venv\Scripts\pip install -e ".[dev]" # Windows
117
+ # source .venv/bin/activate && pip install -e ".[dev]" # macOS/Linux
118
+
119
+ # then, from any repository you want to inspect
120
+ codegraph index .
121
+ codegraph why src/main.py:42
122
+ ```
123
+
124
+ ## Commands (8)
125
+
126
+ ```bash
127
+ codegraph --help
128
+ codegraph index . [--depth N] [--use-llm] [--json] [--full]
129
+ codegraph why docs/adr/001-use-sqlite-default.md:1 [--json] [--include-events]
130
+ codegraph graph --at 2026-09-23 --scope src
131
+ codegraph decisions --timeline [--file PATH] [--include-events]
132
+ codegraph diff 2026-09-23 2026-09-24 --scope src
133
+ codegraph conflicts --scope src # opposite / supersede / temporal
134
+ codegraph export --for-ai --scope src
135
+ codegraph serve --port 8080
136
+ ```
137
+
138
+ `why` answers about a code location; a decision that is only bound at file level
139
+ says so, and a location with no decision says so instead of guessing. Add
140
+ `--include-events` to see the commit history behind a line.
141
+
142
+ Decisions that have no commit of their own (ADRs, CHANGELOG entries) bind to the
143
+ code they declare, so a design rule is reachable from the line it governs:
144
+
145
+ ```markdown
146
+ # ADR-001: SQLite as the default graph store
147
+
148
+ <!-- governs: src/codegraph/storage.py -->
149
+ ```
150
+
151
+ ## Tech stack
152
+
153
+ | Layer | Choice |
154
+ |---|---|
155
+ | CLI | Python · Typer · Rich |
156
+ | Models | pydantic |
157
+ | Parsing | tree-sitter (+ language grammars) |
158
+ | Git | GitPython |
159
+ | Storage | SQLite (local `.codegraph/graph.db`) |
160
+ | Web | FastAPI · Uvicorn · Cytoscape.js |
161
+ | LLM (optional) | Ollama via httpx |
162
+ | Editor | VSCode extension (TypeScript, `vscode-extension/`) |
163
+ | Tests | pytest |
164
+
165
+ ## Tests
166
+
167
+ ```bash
168
+ pytest -q
169
+ # with coverage
170
+ pytest --cov=src/codegraph
171
+ ```
172
+
173
+ ## Storage
174
+
175
+ Everything lives in one local SQLite database at `.codegraph/graph.db`, created
176
+ by `codegraph index`. There is no server, no Docker and no network dependency.
177
+
178
+ A native graph backend (Dgraph or similar) was prototyped and **removed**: it was
179
+ 503 lines of untested client code behind `--backend dgraph`, with no multi-hop
180
+ query that needed it, and two of its code paths returned sample data or silently
181
+ ignored the flag. It comes back when a real multi-hop query justifies it — see
182
+ [docs/adr/006-drop-dgraph-backend.md](docs/adr/006-drop-dgraph-backend.md).
183
+
184
+ ## Project layout
185
+
186
+ ```text
187
+ src/codegraph/
188
+ cli.py # Typer entrypoint
189
+ models.py # CodeNode / Edge / Decision
190
+ storage.py # SQLite graph store
191
+ parser/ # tree-sitter parsers (7 languages)
192
+ commands/ # index / why / graph / decisions / conflicts / export / serve / diff
193
+ tests/
194
+ docs/ # case study, benchmarks, ADRs, demo script, submission copy
195
+ index.html # product site
196
+ ```
197
+
198
+ ## Docs
199
+
200
+ - Architecture: `docs/architecture.md`
201
+ - Decision extraction and precision: `docs/extraction-recall.md`
202
+ - Case study on Express.js: `docs/case-study.md`
203
+ - Architecture decisions: `docs/adr/`
204
+ - 60s demo voiceover: `docs/demo_voiceover.md`
205
+ - Competition copy: `docs/competition_submission.md`
206
+ - Contributing: `CONTRIBUTING.md`
207
+
208
+ ## Development notes
209
+
210
+ Built with AI coding assistants for API discovery, debugging, and documentation. Architecture, design decisions, and final code review are my own.
211
+
212
+ ## License
213
+
214
+ MIT
215
+
216
+
217
+
218
+
219
+
@@ -0,0 +1,21 @@
1
+ # Benchmarks
2
+
3
+ ## Goals
4
+
5
+ - 1000 files index < 30s
6
+ - 10000 files index < 5min
7
+ - `why` P99 < 50ms
8
+ - `graph --at` P99 < 200ms
9
+ - memory < 2GB for 10k files (working-tree mode)
10
+
11
+ ## Run
12
+
13
+ ```bash
14
+ .venv\Scripts\python.exe benchmarks\bench_index.py --files 1000 --out bench_repo
15
+ .venv\Scripts\python.exe benchmarks\bench_query.py --root . --iterations 200
16
+ ```
17
+
18
+ ## Notes
19
+
20
+ This repository (multi-commit Python/TS/HTML) indexes ~244 node versions quickly.
21
+ Use `bench_index.py` for synthetic scale tests on your machine.