codingest 0.2.34__cp312-abi3-win_amd64.whl
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.
- codingest/__init__.py +46 -0
- codingest/__init__.pyi +138 -0
- codingest/cli.py +31 -0
- codingest/codingest.pyd +4 -0
- codingest/mcp_server.py +38 -0
- codingest-0.2.34.dist-info/METADATA +301 -0
- codingest-0.2.34.dist-info/RECORD +11 -0
- codingest-0.2.34.dist-info/WHEEL +4 -0
- codingest-0.2.34.dist-info/entry_points.txt +3 -0
- codingest-0.2.34.dist-info/licenses/LICENSE +21 -0
- codingest-0.2.34.dist-info/sboms/codingest-py.cyclonedx.json +11710 -0
codingest/__init__.py
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
"""codingest — parse polyglot codebases into kglite knowledge graphs.
|
|
2
|
+
|
|
3
|
+
import codingest
|
|
4
|
+
|
|
5
|
+
g = codingest.build(".") # -> kglite.KnowledgeGraph
|
|
6
|
+
g.cypher("MATCH (f:Function) RETURN f.name LIMIT 10")
|
|
7
|
+
|
|
8
|
+
`build()` parses the tree with codingest's native tree-sitter builder (grammars
|
|
9
|
+
bundled — nothing else to install), serializes the result to a `.kgl`, and hands
|
|
10
|
+
off to the separately installed `kglite` wheel: the returned object is a real
|
|
11
|
+
`kglite.KnowledgeGraph`, so every downstream kglite API works unchanged. This
|
|
12
|
+
restores the builder surface that kglite 0.14 removed (`kglite.code_tree`).
|
|
13
|
+
|
|
14
|
+
Entry points:
|
|
15
|
+
build - parse a directory (with optional git `rev`/`revs`).
|
|
16
|
+
repo_tree - clone a GitHub repo and build.
|
|
17
|
+
read_manifest - extract project metadata from a manifest file.
|
|
18
|
+
language_for_path- map a path to its parser language, or None.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
from importlib import metadata as _metadata
|
|
24
|
+
|
|
25
|
+
# The native extension registers `build` / `repo_tree` / `read_manifest` /
|
|
26
|
+
# `language_for_path`. Renamed to `codingest.codingest` by maturin's
|
|
27
|
+
# `module-name`; this pulls its public functions up to the package root.
|
|
28
|
+
from .codingest import ( # noqa: F401
|
|
29
|
+
build,
|
|
30
|
+
language_for_path,
|
|
31
|
+
read_manifest,
|
|
32
|
+
repo_tree,
|
|
33
|
+
)
|
|
34
|
+
|
|
35
|
+
try:
|
|
36
|
+
__version__ = _metadata.version("codingest")
|
|
37
|
+
except _metadata.PackageNotFoundError: # pragma: no cover - source checkout
|
|
38
|
+
from .codingest import __version__ as __version__
|
|
39
|
+
|
|
40
|
+
__all__ = [
|
|
41
|
+
"build",
|
|
42
|
+
"repo_tree",
|
|
43
|
+
"read_manifest",
|
|
44
|
+
"language_for_path",
|
|
45
|
+
"__version__",
|
|
46
|
+
]
|
codingest/__init__.pyi
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
"""Type stubs for the codingest wheel.
|
|
2
|
+
|
|
3
|
+
`build()` / `repo_tree()` return a `kglite.KnowledgeGraph` — the object the
|
|
4
|
+
installed `kglite` wheel produces, reached through the `.kgl`-bytes handoff
|
|
5
|
+
(build native → serialize → `kglite.load`). Every downstream kglite API
|
|
6
|
+
(`.cypher()`, `.describe()`, …) is available on the returned value.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from typing import Any, Optional
|
|
10
|
+
|
|
11
|
+
from kglite import KnowledgeGraph
|
|
12
|
+
|
|
13
|
+
__version__: str
|
|
14
|
+
|
|
15
|
+
def build(
|
|
16
|
+
src_dir: str,
|
|
17
|
+
*,
|
|
18
|
+
save_to: Optional[str] = None,
|
|
19
|
+
verbose: bool = False,
|
|
20
|
+
include_tests: bool = True,
|
|
21
|
+
max_loc_per_file: Optional[int] = None,
|
|
22
|
+
include_docs: bool = False,
|
|
23
|
+
rev: Optional[str] = None,
|
|
24
|
+
revs: Optional[list[str]] = None,
|
|
25
|
+
repo_root: Optional[str] = None,
|
|
26
|
+
embed_skills: bool = False,
|
|
27
|
+
) -> KnowledgeGraph:
|
|
28
|
+
"""Parse a codebase at ``src_dir`` into a :class:`kglite.KnowledgeGraph`.
|
|
29
|
+
|
|
30
|
+
The stable, public entry point for code-graph building (tree-sitter grammars
|
|
31
|
+
are bundled in the native extension — nothing else to install). codingest
|
|
32
|
+
builds the graph with its own native builder, serializes it to a ``.kgl``,
|
|
33
|
+
and loads it back through the installed ``kglite`` wheel, so the returned
|
|
34
|
+
object is a real ``kglite.KnowledgeGraph``.
|
|
35
|
+
|
|
36
|
+
Pass ``include_docs=True`` to also ingest the repo's markdown as ``:Doc``
|
|
37
|
+
nodes linked to the code they mention
|
|
38
|
+
(``(:Doc)-[:MENTIONS]->(:Function|:Class|…)`` and
|
|
39
|
+
``(:Doc)-[:DOCUMENTS]->(:Doc|:File)``). Off by default (code-only graph).
|
|
40
|
+
|
|
41
|
+
Pass ``rev=<tag|branch|sha>`` to build the codebase as it existed at that git
|
|
42
|
+
revision instead of the working tree. The revision's tracked files are
|
|
43
|
+
materialized into a tempdir via ``git archive`` — ``HEAD`` and the working
|
|
44
|
+
tree are never touched, and uncommitted changes are excluded. The git root
|
|
45
|
+
is auto-resolved from ``src_dir`` (override with ``repo_root``); a bad rev or
|
|
46
|
+
non-git directory raises a clear error. The built graph's ``describe()``
|
|
47
|
+
records the revision it represents.
|
|
48
|
+
|
|
49
|
+
Pass ``revs=[<rev>, ...]`` (oldest → newest, mutually exclusive with
|
|
50
|
+
``rev``) to merge N revisions into ONE multi-rev graph: one node per entity
|
|
51
|
+
across revs, each node carrying native list props ``revs: [str]`` (revisions
|
|
52
|
+
it appears in) + ``rev_fp: [int]`` (a per-rev shape fingerprint), and each
|
|
53
|
+
edge carrying ``revs: [str]``. Unchanged entities are stored once, so the
|
|
54
|
+
graph is ≈ base + deltas. Ordinary properties (``signature``,
|
|
55
|
+
``value_preview``, …) report the NEWEST rev an entity appears in
|
|
56
|
+
(newest-wins). Because one graph holds every rev, an **unscoped**
|
|
57
|
+
``MATCH (n:Function) RETURN count(n)`` over-counts across revs — scope a
|
|
58
|
+
query to one rev with membership::
|
|
59
|
+
|
|
60
|
+
MATCH (n:Function) WHERE 'v2' IN n.revs RETURN n.name
|
|
61
|
+
|
|
62
|
+
and use ``CALL rev_diff({from: 'v1', to: 'v2'})`` for added / removed /
|
|
63
|
+
changed deltas between two revs. ``describe()`` lists the loaded revs and
|
|
64
|
+
teaches this scoping idiom.
|
|
65
|
+
|
|
66
|
+
Args:
|
|
67
|
+
src_dir: Path to the directory (or manifest-rooted project) to parse.
|
|
68
|
+
save_to: If given, also write the built graph to this ``.kgl`` path
|
|
69
|
+
(the loaded graph is still returned).
|
|
70
|
+
verbose: Emit build progress to stderr.
|
|
71
|
+
include_tests: Include test files/dirs in the graph (default True).
|
|
72
|
+
max_loc_per_file: Skip files longer than this many lines (None = no cap).
|
|
73
|
+
include_docs: Ingest markdown as ``:Doc`` nodes (see above).
|
|
74
|
+
embed_skills: Also write codingest's ``code_review`` skill and its
|
|
75
|
+
recipe catalogue into the graph as graph-carried records
|
|
76
|
+
(``KgliteSkill`` / ``KgliteRecipe``), for a ``.kgl`` served by a
|
|
77
|
+
plain ``kglite-mcp-server --graph``. Off by default: the default
|
|
78
|
+
graph is byte-identical to earlier releases, and ``codingest-mcp``
|
|
79
|
+
serves the methodology by itself. ``repo_tree`` never embeds.
|
|
80
|
+
rev: A single git revspec to build (mutually exclusive with ``revs``).
|
|
81
|
+
revs: A list of git revspecs to merge into a multi-rev graph.
|
|
82
|
+
repo_root: Override the auto-resolved git root for ``rev``/``revs``.
|
|
83
|
+
|
|
84
|
+
Returns:
|
|
85
|
+
A :class:`kglite.KnowledgeGraph` of the parsed codebase.
|
|
86
|
+
"""
|
|
87
|
+
...
|
|
88
|
+
|
|
89
|
+
def repo_tree(
|
|
90
|
+
repo: str,
|
|
91
|
+
*,
|
|
92
|
+
save_to: Optional[str] = None,
|
|
93
|
+
clone_to: Optional[str] = None,
|
|
94
|
+
branch: Optional[str] = None,
|
|
95
|
+
token: Optional[str] = None,
|
|
96
|
+
verbose: bool = False,
|
|
97
|
+
include_tests: bool = True,
|
|
98
|
+
max_loc_per_file: Optional[int] = None,
|
|
99
|
+
include_docs: bool = False,
|
|
100
|
+
) -> KnowledgeGraph:
|
|
101
|
+
"""Clone a GitHub repository and build its code knowledge graph.
|
|
102
|
+
|
|
103
|
+
Shallow-clones ``repo`` (shelling out to ``git``) into a tempdir (or
|
|
104
|
+
``clone_to``) and builds it, returning a :class:`kglite.KnowledgeGraph`.
|
|
105
|
+
Set ``include_docs=True`` to also ingest the repo's markdown as ``:Doc``
|
|
106
|
+
nodes linked to the code they mention (see :func:`build`).
|
|
107
|
+
|
|
108
|
+
Args:
|
|
109
|
+
repo: ``owner/name`` or a full clone URL.
|
|
110
|
+
save_to: If given, also write the built graph to this ``.kgl`` path.
|
|
111
|
+
clone_to: Directory to clone into (default: a tempdir, removed after).
|
|
112
|
+
branch: Branch / tag / ref to check out (default: the repo default).
|
|
113
|
+
token: Auth token for private repos.
|
|
114
|
+
verbose: Emit build progress to stderr.
|
|
115
|
+
include_tests: Include test files/dirs in the graph (default True).
|
|
116
|
+
max_loc_per_file: Skip files longer than this many lines.
|
|
117
|
+
include_docs: Ingest markdown as ``:Doc`` nodes (see :func:`build`).
|
|
118
|
+
|
|
119
|
+
Returns:
|
|
120
|
+
A :class:`kglite.KnowledgeGraph` of the cloned repository.
|
|
121
|
+
"""
|
|
122
|
+
...
|
|
123
|
+
|
|
124
|
+
def read_manifest(path: str) -> Optional[dict[str, Any]]:
|
|
125
|
+
"""Read a project manifest and return a dict of project metadata.
|
|
126
|
+
|
|
127
|
+
Recognises ``pyproject.toml`` / ``Cargo.toml`` (and more). Returns ``None``
|
|
128
|
+
when no manifest is found at ``path``. The dict carries ``name``,
|
|
129
|
+
``version``, ``description``, ``languages``, ``authors``, ``license``,
|
|
130
|
+
``repository_url``, ``manifest_path``, ``build_system``, ``source_roots``,
|
|
131
|
+
and ``test_roots`` (the last two as lists of directory paths).
|
|
132
|
+
"""
|
|
133
|
+
...
|
|
134
|
+
|
|
135
|
+
def language_for_path(path: str) -> Optional[str]:
|
|
136
|
+
"""Map a file path to its codingest parser language, or ``None`` if no
|
|
137
|
+
parser handles the file (e.g. ``"src/app.py"`` → ``"python"``)."""
|
|
138
|
+
...
|
codingest/cli.py
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
"""Console-script shim for the Rust ``codingest`` CLI bundled in the wheel.
|
|
2
|
+
|
|
3
|
+
The CLI implementation lives in the ``codingest-cli`` Rust library and is linked
|
|
4
|
+
into this wheel's existing extension alongside the code-graph builder. This
|
|
5
|
+
module only forwards argv and formats a top-level error; command parsing and
|
|
6
|
+
behavior are shared with the standalone ``codingest-cli`` binary distribution
|
|
7
|
+
(``cargo install codingest-cli``).
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import sys
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def main(argv: list[str] | None = None) -> int:
|
|
16
|
+
"""Run the bundled Rust CLI with ``argv`` or ``sys.argv[1:]``."""
|
|
17
|
+
from codingest.codingest import _run_cli
|
|
18
|
+
|
|
19
|
+
args = list(sys.argv[1:] if argv is None else argv)
|
|
20
|
+
try:
|
|
21
|
+
_run_cli(args)
|
|
22
|
+
except KeyboardInterrupt:
|
|
23
|
+
return 130
|
|
24
|
+
except RuntimeError as exc:
|
|
25
|
+
print(f"codingest: {exc}", file=sys.stderr)
|
|
26
|
+
return 1
|
|
27
|
+
return 0
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
if __name__ == "__main__":
|
|
31
|
+
raise SystemExit(main())
|
codingest/codingest.pyd
ADDED
codingest/mcp_server.py
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""Console-script shim for the Rust ``codingest-mcp`` server in the wheel.
|
|
2
|
+
|
|
3
|
+
Codingest supplies the source-builder hooks; KGlite supplies graph/Cypher
|
|
4
|
+
serving and pulls the generic MCP lifecycle from ``mcp-methods``. All three are
|
|
5
|
+
linked into the wheel's existing native extension, so users need only
|
|
6
|
+
``pip install codingest``.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import json
|
|
12
|
+
import os
|
|
13
|
+
import sys
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def main(argv: list[str] | None = None) -> int:
|
|
17
|
+
"""Run the bundled MCP server with ``argv`` or ``sys.argv[1:]``."""
|
|
18
|
+
from codingest.codingest import _run_mcp_server
|
|
19
|
+
|
|
20
|
+
args = list(sys.argv[1:] if argv is None else argv)
|
|
21
|
+
# In a wheel console script, current_exe() is Python rather than the Rust
|
|
22
|
+
# server. Give KGlite's selftest the exact command needed to re-enter this
|
|
23
|
+
# module with the same interpreter and environment.
|
|
24
|
+
os.environ["KGLITE_MCP_RESPAWN"] = json.dumps(
|
|
25
|
+
[sys.executable, "-m", "codingest.mcp_server"]
|
|
26
|
+
)
|
|
27
|
+
try:
|
|
28
|
+
_run_mcp_server(args)
|
|
29
|
+
except KeyboardInterrupt:
|
|
30
|
+
return 130
|
|
31
|
+
except RuntimeError as exc:
|
|
32
|
+
print(f"codingest-mcp: {exc}", file=sys.stderr)
|
|
33
|
+
return 1
|
|
34
|
+
return 0
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
if __name__ == "__main__":
|
|
38
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codingest
|
|
3
|
+
Version: 0.2.34
|
|
4
|
+
Classifier: Development Status :: 3 - Alpha
|
|
5
|
+
Classifier: Intended Audience :: Developers
|
|
6
|
+
Classifier: Programming Language :: Python :: 3
|
|
7
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
8
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
11
|
+
Classifier: Programming Language :: Rust
|
|
12
|
+
Classifier: Topic :: Software Development
|
|
13
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
14
|
+
Requires-Dist: kglite>=0.21.4,<0.22
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Summary: Build fast, queryable code graphs for AI agents, MCP code review, and local or GitHub repository analysis.
|
|
17
|
+
Keywords: ai-agents,mcp,code-review,knowledge-graph,code-analysis,github,tree-sitter,cypher
|
|
18
|
+
Author-email: Kristian dF Kollsgård <kkollsg@gmail.com>
|
|
19
|
+
License-Expression: MIT
|
|
20
|
+
Requires-Python: >=3.12
|
|
21
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
22
|
+
Project-URL: Documentation, https://codingest.readthedocs.io
|
|
23
|
+
Project-URL: Homepage, https://github.com/kkollsga/codingest
|
|
24
|
+
Project-URL: Issues, https://github.com/kkollsga/codingest/issues
|
|
25
|
+
Project-URL: Repository, https://github.com/kkollsga/codingest
|
|
26
|
+
|
|
27
|
+
# codingest
|
|
28
|
+
|
|
29
|
+
[](https://github.com/kkollsga/codingest/actions/workflows/ci.yml)
|
|
30
|
+
[](https://crates.io/crates/codingest)
|
|
31
|
+
[](https://pypi.org/project/codingest/)
|
|
32
|
+
[](https://codingest.readthedocs.io)
|
|
33
|
+
[](LICENSE)
|
|
34
|
+
|
|
35
|
+
Give AI agents a live, queryable map of any codebase — locally, privately, and
|
|
36
|
+
without running the code you are analysing.
|
|
37
|
+
|
|
38
|
+
codingest turns polyglot source into a
|
|
39
|
+
[KGLite](https://github.com/kkollsga/kglite) knowledge graph of functions,
|
|
40
|
+
types, calls, imports, inheritance, routes, documentation, and git revisions.
|
|
41
|
+
Use it from Python, the command line, or as an MCP server for coding agents.
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
pip install codingest
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
import codingest
|
|
49
|
+
|
|
50
|
+
graph = codingest.build(".")
|
|
51
|
+
graph.cypher("MATCH (f:Function) RETURN f.name LIMIT 10")
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
No language servers, databases, or repository-specific build steps are
|
|
55
|
+
required. The native Rust builder bundles parsers for 17 languages and returns
|
|
56
|
+
a real `kglite.KnowledgeGraph`, ready for Cypher queries.
|
|
57
|
+
|
|
58
|
+
## Built for agents and code analysis
|
|
59
|
+
|
|
60
|
+
- **Agent-ready MCP:** give an MCP client `graph_overview`, `cypher_query`,
|
|
61
|
+
`read_code_source`, repository switching, automatic graph refresh, and the
|
|
62
|
+
code-review methodology itself — a `code_review` skill and a catalogue of
|
|
63
|
+
parameter-checked review recipes (`run_recipe_query`) served for every graph.
|
|
64
|
+
[opencode is set up and verified end to end](https://codingest.readthedocs.io/en/latest/mcp.html#using-codingest-mcp-with-opencode)
|
|
65
|
+
— including a config that needs no absolute paths — and `codingest skill
|
|
66
|
+
install` packages the review skill for Claude Code and Codex, which opencode
|
|
67
|
+
also discovers with no extra step.
|
|
68
|
+
- **Fast local review:** map definitions, callers, dependencies, routes,
|
|
69
|
+
inheritance, and affected tests without uploading or executing the project.
|
|
70
|
+
- **Open-source intelligence:** clone and analyse a GitHub repository with one
|
|
71
|
+
Python call, or let an agent manage cached public repositories through MCP.
|
|
72
|
+
- **Polyglot by default:** one graph across Python, Rust, TypeScript,
|
|
73
|
+
JavaScript, Java, Go, C/C++, C#, Swift, PHP, HTML, CSS, Dart, Julia, R,
|
|
74
|
+
and AGC assembly — capabilities per language in
|
|
75
|
+
[docs/languages.md](docs/languages.md).
|
|
76
|
+
- **Revision-aware:** analyse a tag, branch, commit, or multiple revisions in
|
|
77
|
+
one graph and query what changed.
|
|
78
|
+
|
|
79
|
+
AGC assembly receives architecture-aware control and data relationships rather
|
|
80
|
+
than a generic text-level call graph; see the [AGC graph model](https://codingest.readthedocs.io/en/latest/agc-assembly.html).
|
|
81
|
+
|
|
82
|
+
## Give your agent a code-review MCP server
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
pip install codingest
|
|
86
|
+
codingest-mcp --watch /absolute/path/to/repo
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Point an MCP client at the same command:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"mcpServers": {
|
|
94
|
+
"code-review": {
|
|
95
|
+
"command": "codingest-mcp",
|
|
96
|
+
"args": ["--watch", "/absolute/path/to/repo"]
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The server builds the graph at startup, refreshes it when source files change,
|
|
103
|
+
and gives the agent schema discovery, Cypher, and source-reading tools over
|
|
104
|
+
stdio. For a multi-repository agent sandbox with runtime `set_root_dir`, use
|
|
105
|
+
the local-workspace manifest described in the [MCP guide](https://codingest.readthedocs.io/en/latest/mcp.html).
|
|
106
|
+
|
|
107
|
+
For a zero-configuration CLI workflow, install the packaged code-review Agent
|
|
108
|
+
Skill instead:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
pip install codingest
|
|
112
|
+
codingest skill install
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The skill teaches compatible agents to build a fresh graph, discover its
|
|
116
|
+
schema before querying, combine Cypher with the git diff, and verify findings
|
|
117
|
+
against source lines. See the [MCP guide](https://codingest.readthedocs.io/en/latest/mcp.html)
|
|
118
|
+
and [CLI guide](https://codingest.readthedocs.io/en/latest/cli.html).
|
|
119
|
+
|
|
120
|
+
## Analyse a local codebase
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
import codingest
|
|
124
|
+
|
|
125
|
+
graph = codingest.build(
|
|
126
|
+
".",
|
|
127
|
+
include_docs=True,
|
|
128
|
+
)
|
|
129
|
+
|
|
130
|
+
rows = graph.cypher("""
|
|
131
|
+
MATCH (caller:Function)-[:CALLS]->(target:Function)
|
|
132
|
+
RETURN target.qualified_name, count(caller) AS callers
|
|
133
|
+
ORDER BY callers DESC
|
|
134
|
+
LIMIT 10
|
|
135
|
+
""")
|
|
136
|
+
|
|
137
|
+
codingest.build(".", save_to="code-review.kgl")
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The bundled terminal command offers the same workflow:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
codingest build /path/to/repo
|
|
144
|
+
codingest status --output /path/to/repo/.kglite/code-review.kgl
|
|
145
|
+
codingest query -g /path/to/repo/.kglite/code-review.kgl \
|
|
146
|
+
"MATCH (f:Function)-[:CALLS]->(g:Function) RETURN f.name, g.name LIMIT 20"
|
|
147
|
+
kglite describe /path/to/repo/.kglite/code-review.kgl --connections
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`codingest query` prints unbounded TSV to stdout (use `--format csv|json`, or
|
|
151
|
+
Cypher `LIMIT` to bound rows), warns on stderr when the graph has gone stale,
|
|
152
|
+
and with `--require-fresh` refuses a stale graph with exit code 3 — see
|
|
153
|
+
[docs/cli.md](docs/cli.md).
|
|
154
|
+
|
|
155
|
+
## Analyse an open-source repository
|
|
156
|
+
|
|
157
|
+
```python
|
|
158
|
+
import codingest
|
|
159
|
+
|
|
160
|
+
graph = codingest.repo_tree("pallets/flask")
|
|
161
|
+
graph.cypher("""
|
|
162
|
+
MATCH (route:Function)-[:CALLS]->(dependency:Function)
|
|
163
|
+
RETURN route.qualified_name, dependency.qualified_name
|
|
164
|
+
LIMIT 25
|
|
165
|
+
""")
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
`repo_tree()` shallow-clones the requested repository into a temporary
|
|
169
|
+
directory, builds the graph, and cleans up afterward. Pass `branch=`,
|
|
170
|
+
`clone_to=`, or `token=` for a specific revision, a reusable cache, or a
|
|
171
|
+
private repository.
|
|
172
|
+
|
|
173
|
+
## Compare revisions
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
graph = codingest.build(".", revs=["v1.0", "v2.0"])
|
|
177
|
+
graph.cypher("""
|
|
178
|
+
MATCH (f:Function)
|
|
179
|
+
WHERE 'v2.0' IN f.revs AND NOT 'v1.0' IN f.revs
|
|
180
|
+
RETURN f.qualified_name
|
|
181
|
+
""")
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Revision builds use tracked git content without changing the working tree.
|
|
185
|
+
Multi-revision graphs store shared entities once and expose revision membership
|
|
186
|
+
for direct Cypher analysis.
|
|
187
|
+
|
|
188
|
+
## Install options
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
pip install codingest # Python API + CLI + MCP server + KGLite runtime
|
|
192
|
+
codingest skill install # code-review Agent Skill
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
The wheel bundles every grammar plus the `codingest` and `codingest-mcp`
|
|
196
|
+
commands. KGLite ≥0.21.4 is installed automatically as the query/storage
|
|
197
|
+
engine; its MCP server and the transitive `mcp-methods` framework power the
|
|
198
|
+
builder-aware Codingest server. Nothing else needs to be installed.
|
|
199
|
+
|
|
200
|
+
Rust-only environments can instead use `cargo install codingest-cli
|
|
201
|
+
codingest-mcp`; these are alternative distributions of the same commands, not
|
|
202
|
+
Python prerequisites.
|
|
203
|
+
|
|
204
|
+
### Rust crate
|
|
205
|
+
|
|
206
|
+
```toml
|
|
207
|
+
[dependencies]
|
|
208
|
+
codingest = "0.2"
|
|
209
|
+
kglite = "0.21.4"
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
```rust
|
|
213
|
+
use codingest::build_code_tree;
|
|
214
|
+
|
|
215
|
+
let graph = build_code_tree(
|
|
216
|
+
dir,
|
|
217
|
+
false, // verbose
|
|
218
|
+
true, // include tests
|
|
219
|
+
None, // save path
|
|
220
|
+
None, // max lines per file
|
|
221
|
+
false, // include docs
|
|
222
|
+
)?;
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## How it fits together
|
|
226
|
+
|
|
227
|
+
codingest owns code-graph construction, the Python/CLI interfaces, the
|
|
228
|
+
builder-backed MCP executable, and the code-review Agent Skill. KGLite provides
|
|
229
|
+
the graph engine, Cypher, persistence, and reusable query/read tools. Keeping
|
|
230
|
+
that boundary explicit lets codingest focus on accurate code understanding
|
|
231
|
+
while reusing a dedicated graph engine.
|
|
232
|
+
|
|
233
|
+
Documentation: **[codingest.readthedocs.io](https://codingest.readthedocs.io)**
|
|
234
|
+
|
|
235
|
+
## Workspace layout
|
|
236
|
+
|
|
237
|
+
| Crate | What it is |
|
|
238
|
+
|---|---|
|
|
239
|
+
| `crates/codingest` | The component library (`codingest`): builder, parsers, manifest reader, docs pass, multi-rev merge, cross-language edges. Extracted from the former `KGLite/crates/kglite/src/code_tree/` (removed upstream 2026-07-16) and re-targeted at the public `kglite::api` facade. Ships the `codingest_stats` + `codingest_bench` binaries. |
|
|
240
|
+
| `crates/codingest-cli` | `codingest` binary — `build` a checkout or git revision(s) into a `.kgl` graph, `status` to check staleness, and `skill` to install Codingest's code-review Agent Skill. |
|
|
241
|
+
| `crates/codingest-mcp` | `codingest-mcp` binary — the full MCP tool surface imported from the `kglite-mcp-server` library, with the codingest builder injected and codingest's `code_review` skill + recipe catalogue registered as the producer's methodology. |
|
|
242
|
+
| `crates/codingest-py` | PyO3 wrapper built by maturin into the `codingest` wheel (`pip install codingest`). Python package source is `codingest/`; `pyproject.toml` drives the maturin build. Not published to crates.io (`publish = false`). |
|
|
243
|
+
|
|
244
|
+
## CI-equivalent local gate
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
cargo build --workspace
|
|
248
|
+
cargo clippy --workspace --all-targets -- -D warnings
|
|
249
|
+
cargo test --workspace
|
|
250
|
+
cargo test --workspace --test parity
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### The golden-digest oracle (also the determinism gate)
|
|
254
|
+
|
|
255
|
+
KGLite deleted its in-tree `code_tree` builder on 2026-07-16, so the old
|
|
256
|
+
two-builder parity sweep is gone. The authority it enforced was **frozen** while
|
|
257
|
+
the builders were still verified identical, into per-corpus SHA-256 digests
|
|
258
|
+
under `crates/codingest/tests/goldens/` (committed fixtures — no network). The
|
|
259
|
+
`golden_parity` test builds each corpus **three times** with only the codingest
|
|
260
|
+
builder, digests a canonical exhaustive graph rendering, and requires every
|
|
261
|
+
build to match every other build *and* the frozen golden. Repeating the build is
|
|
262
|
+
what makes this the determinism gate: hash iteration order is randomized per
|
|
263
|
+
`HashMap`, so an order-dependent builder fails it (the
|
|
264
|
+
`tests/corpus/dup_minified_assets` fixture reproduces the original DEFINES-edge
|
|
265
|
+
nondeterminism bug). Disagreement between builds is reported as NONDETERMINISM;
|
|
266
|
+
agreement between builds but not with the golden is reported as a behaviour
|
|
267
|
+
change. The multi-rev fixture is guarded instead by `rev_self_consistency`.
|
|
268
|
+
Regenerate goldens only for deliberate builder-behavior changes:
|
|
269
|
+
`cargo test --workspace --test parity -- --ignored capture_goldens` (details in
|
|
270
|
+
`crates/codingest/tests/goldens/README.md`).
|
|
271
|
+
|
|
272
|
+
Everything the gate needs is committed to this repository, so it is hermetic and
|
|
273
|
+
runs in CI. It replaced a local-only `make` step that asserted an exact edge
|
|
274
|
+
count against a *sibling* checkout — a verdict this project did not control.
|
|
275
|
+
`make determinism-soak REPO=…` keeps the large-repo reproducer available as a
|
|
276
|
+
diagnostic.
|
|
277
|
+
|
|
278
|
+
## Dependency policy
|
|
279
|
+
|
|
280
|
+
`kglite` and `kglite-mcp-server` use matching crates.io requirements with a
|
|
281
|
+
0.21.4 minimum and a shared lockfile. This keeps the builder, persistence
|
|
282
|
+
handoff, and embedded MCP server on one compatible engine patch line.
|
|
283
|
+
|
|
284
|
+
## Parity with the (now-removed) in-tree component
|
|
285
|
+
|
|
286
|
+
codingest was extracted to be feature- and performance-identical to kglite's
|
|
287
|
+
in-tree `code_tree`. KGLite removed that module on 2026-07-16, so parity is now
|
|
288
|
+
enforced against a **frozen record** of its last-known-good output rather than
|
|
289
|
+
live cross-comparison. See `PARITY.md` (stats-diff + timing), `BENCHMARKS.md`
|
|
290
|
+
(build-time + Cypher benchmarks), `crates/codingest/tests/parity.rs` (the golden
|
|
291
|
+
oracle), and `docs/mcp-parity.md` (the MCP↔builder coupling and the hook).
|
|
292
|
+
|
|
293
|
+
`tests/python-legacy/` preserves KGLite's full 47-file `kglite.code_tree`
|
|
294
|
+
behavioral suite verbatim as the dormant behavioral spec — the source of truth
|
|
295
|
+
for what the Python builder guaranteed (see its README).
|
|
296
|
+
|
|
297
|
+
## License
|
|
298
|
+
|
|
299
|
+
MIT © Kristian dF Kollsgård. codingest is an independent project; it depends on
|
|
300
|
+
`kglite` at runtime but is not otherwise affiliated with it.
|
|
301
|
+
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
codingest/__init__.py,sha256=ZWRR1wNYROPOD6Wlyne23irAB20SsapFUY5eJB3Lc9U,1649
|
|
2
|
+
codingest/__init__.pyi,sha256=sr2tovS7XJIKnj03AmFFPK9_vUCdCCtUlLufOImi8lg,6505
|
|
3
|
+
codingest/cli.py,sha256=bACzbAfoRCtUJtp-3Txxdhf8zlee5EKt-2Z3sk0PXLY,982
|
|
4
|
+
codingest/codingest.pyd,sha256=C3SIeRXr1gX1yLnTX8KFZGXdwW0x7gQFRmgcSas4PZY,66061824
|
|
5
|
+
codingest/mcp_server.py,sha256=Lp72lAEvLj87f5BcxyNRn9JmALNw-qLr-jO2vNgG8Y8,1259
|
|
6
|
+
codingest-0.2.34.dist-info/METADATA,sha256=CVVnCxcrNKqxYsH9C3XbPz9-mT88F1L95tyQCDnpHEw,12701
|
|
7
|
+
codingest-0.2.34.dist-info/WHEEL,sha256=rjikdQI6uHLAgYXPVkr7bTnnX2G_U4MjYuRag5dSWZs,96
|
|
8
|
+
codingest-0.2.34.dist-info/entry_points.txt,sha256=GhjPNm4tJElg6cuggI4OoHJLx48nV9EP8PYZF5QqIcs,87
|
|
9
|
+
codingest-0.2.34.dist-info/licenses/LICENSE,sha256=q0gXpC0K7UDWntzOORLPFJ1qRsJneOljj9IE_TBHX0I,1100
|
|
10
|
+
codingest-0.2.34.dist-info/sboms/codingest-py.cyclonedx.json,sha256=RtnTdwNHV4iC1APVVpqyLLBPy2oCS97aQ2KOgjBB1K0,376938
|
|
11
|
+
codingest-0.2.34.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Kristian dF Kollsgård
|
|
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.
|