codingest 0.1.0__cp310-abi3-win_amd64.whl

codingest/__init__.py

@@ -0,0 +1,46 @@
+"""codingest — parse polyglot codebases into kglite knowledge graphs.
+
+    import codingest
+
+    g = codingest.build(".")          # -> kglite.KnowledgeGraph
+    g.cypher("MATCH (f:Function) RETURN f.name LIMIT 10")
+
+`build()` parses the tree with codingest's native tree-sitter builder (grammars
+bundled — nothing else to install), serializes the result to a `.kgl`, and hands
+off to the separately installed `kglite` wheel: the returned object is a real
+`kglite.KnowledgeGraph`, so every downstream kglite API works unchanged. This
+restores the builder surface that kglite 0.14 removed (`kglite.code_tree`).
+
+Entry points:
+    build            - parse a directory (with optional git `rev`/`revs`).
+    repo_tree        - clone a GitHub repo and build.
+    read_manifest    - extract project metadata from a manifest file.
+    language_for_path- map a path to its parser language, or None.
+"""
+
+from __future__ import annotations
+
+from importlib import metadata as _metadata
+
+# The native extension registers `build` / `repo_tree` / `read_manifest` /
+# `language_for_path`. Renamed to `codingest.codingest` by maturin's
+# `module-name`; this pulls its public functions up to the package root.
+from .codingest import (  # noqa: F401
+    build,
+    language_for_path,
+    read_manifest,
+    repo_tree,
+)
+
+try:
+    __version__ = _metadata.version("codingest")
+except _metadata.PackageNotFoundError:  # pragma: no cover - source checkout
+    from .codingest import __version__ as __version__
+
+__all__ = [
+    "build",
+    "repo_tree",
+    "read_manifest",
+    "language_for_path",
+    "__version__",
+]

codingest/__init__.pyi

@@ -0,0 +1,131 @@
+"""Type stubs for the codingest wheel.
+
+`build()` / `repo_tree()` return a `kglite.KnowledgeGraph` — the object the
+installed `kglite` wheel produces, reached through the `.kgl`-bytes handoff
+(build native → serialize → `kglite.load`). Every downstream kglite API
+(`.cypher()`, `.describe()`, …) is available on the returned value.
+"""
+
+from typing import Any, Optional
+
+from kglite import KnowledgeGraph
+
+__version__: str
+
+def build(
+    src_dir: str,
+    *,
+    save_to: Optional[str] = None,
+    verbose: bool = False,
+    include_tests: bool = True,
+    max_loc_per_file: Optional[int] = None,
+    include_docs: bool = False,
+    rev: Optional[str] = None,
+    revs: Optional[list[str]] = None,
+    repo_root: Optional[str] = None,
+) -> KnowledgeGraph:
+    """Parse a codebase at ``src_dir`` into a :class:`kglite.KnowledgeGraph`.
+
+    The stable, public entry point for code-graph building (tree-sitter grammars
+    are bundled in the native extension — nothing else to install). codingest
+    builds the graph with its own native builder, serializes it to a ``.kgl``,
+    and loads it back through the installed ``kglite`` wheel, so the returned
+    object is a real ``kglite.KnowledgeGraph``.
+
+    Pass ``include_docs=True`` to also ingest the repo's markdown as ``:Doc``
+    nodes linked to the code they mention
+    (``(:Doc)-[:MENTIONS]->(:Function|:Class|…)`` and
+    ``(:Doc)-[:DOCUMENTS]->(:Doc|:File)``). Off by default (code-only graph).
+
+    Pass ``rev=<tag|branch|sha>`` to build the codebase as it existed at that git
+    revision instead of the working tree. The revision's tracked files are
+    materialized into a tempdir via ``git archive`` — ``HEAD`` and the working
+    tree are never touched, and uncommitted changes are excluded. The git root
+    is auto-resolved from ``src_dir`` (override with ``repo_root``); a bad rev or
+    non-git directory raises a clear error. The built graph's ``describe()``
+    records the revision it represents.
+
+    Pass ``revs=[<rev>, ...]`` (oldest → newest, mutually exclusive with
+    ``rev``) to merge N revisions into ONE multi-rev graph: one node per entity
+    across revs, each node carrying native list props ``revs: [str]`` (revisions
+    it appears in) + ``rev_fp: [int]`` (a per-rev shape fingerprint), and each
+    edge carrying ``revs: [str]``. Unchanged entities are stored once, so the
+    graph is ≈ base + deltas. Ordinary properties (``signature``,
+    ``value_preview``, …) report the NEWEST rev an entity appears in
+    (newest-wins). Because one graph holds every rev, an **unscoped**
+    ``MATCH (n:Function) RETURN count(n)`` over-counts across revs — scope a
+    query to one rev with membership::
+
+        MATCH (n:Function) WHERE 'v2' IN n.revs RETURN n.name
+
+    and use ``CALL rev_diff({from: 'v1', to: 'v2'})`` for added / removed /
+    changed deltas between two revs. ``describe()`` lists the loaded revs and
+    teaches this scoping idiom.
+
+    Args:
+        src_dir: Path to the directory (or manifest-rooted project) to parse.
+        save_to: If given, also write the built graph to this ``.kgl`` path
+            (the loaded graph is still returned).
+        verbose: Emit build progress to stderr.
+        include_tests: Include test files/dirs in the graph (default True).
+        max_loc_per_file: Skip files longer than this many lines (None = no cap).
+        include_docs: Ingest markdown as ``:Doc`` nodes (see above).
+        rev: A single git revspec to build (mutually exclusive with ``revs``).
+        revs: A list of git revspecs to merge into a multi-rev graph.
+        repo_root: Override the auto-resolved git root for ``rev``/``revs``.
+
+    Returns:
+        A :class:`kglite.KnowledgeGraph` of the parsed codebase.
+    """
+    ...
+
+def repo_tree(
+    repo: str,
+    *,
+    save_to: Optional[str] = None,
+    clone_to: Optional[str] = None,
+    branch: Optional[str] = None,
+    token: Optional[str] = None,
+    verbose: bool = False,
+    include_tests: bool = True,
+    max_loc_per_file: Optional[int] = None,
+    include_docs: bool = False,
+) -> KnowledgeGraph:
+    """Clone a GitHub repository and build its code knowledge graph.
+
+    Shallow-clones ``repo`` (shelling out to ``git``) into a tempdir (or
+    ``clone_to``) and builds it, returning a :class:`kglite.KnowledgeGraph`.
+    Set ``include_docs=True`` to also ingest the repo's markdown as ``:Doc``
+    nodes linked to the code they mention (see :func:`build`).
+
+    Args:
+        repo: ``owner/name`` or a full clone URL.
+        save_to: If given, also write the built graph to this ``.kgl`` path.
+        clone_to: Directory to clone into (default: a tempdir, removed after).
+        branch: Branch / tag / ref to check out (default: the repo default).
+        token: Auth token for private repos.
+        verbose: Emit build progress to stderr.
+        include_tests: Include test files/dirs in the graph (default True).
+        max_loc_per_file: Skip files longer than this many lines.
+        include_docs: Ingest markdown as ``:Doc`` nodes (see :func:`build`).
+
+    Returns:
+        A :class:`kglite.KnowledgeGraph` of the cloned repository.
+    """
+    ...
+
+def read_manifest(path: str) -> Optional[dict[str, Any]]:
+    """Read a project manifest and return a dict of project metadata.
+
+    Recognises ``pyproject.toml`` / ``Cargo.toml`` (and more). Returns ``None``
+    when no manifest is found at ``path``. The dict carries ``name``,
+    ``version``, ``description``, ``languages``, ``authors``, ``license``,
+    ``repository_url``, ``manifest_path``, ``build_system``, ``source_roots``,
+    and ``test_roots`` (the last two as lists of directory paths).
+    """
+    ...
+
+def language_for_path(path: str) -> Optional[str]:
+    """Map a file path to its codingest parser language, or ``None`` if no
+    parser handles the file (e.g. ``"src/app.py"`` → ``"python"``)."""
+    ...

codingest/cli.py

@@ -0,0 +1,31 @@
+"""Console-script shim for the Rust ``codingest`` CLI bundled in the wheel.
+
+The CLI implementation lives in the ``codingest-cli`` Rust library and is linked
+into this wheel's existing extension alongside the code-graph builder. This
+module only forwards argv and formats a top-level error; command parsing and
+behavior are shared with the standalone ``codingest-cli`` binary distribution
+(``cargo install codingest-cli``).
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the bundled Rust CLI with ``argv`` or ``sys.argv[1:]``."""
+    from codingest.codingest import _run_cli
+
+    args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        _run_cli(args)
+    except KeyboardInterrupt:
+        return 130
+    except RuntimeError as exc:
+        print(f"codingest: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codingest-0.1.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: codingest
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: kglite>=0.13
+License-File: LICENSE
+Summary: Parse polyglot codebases into queryable kglite knowledge graphs — `import codingest; g = codingest.build('.')` returns a real kglite.KnowledgeGraph.
+Keywords: knowledge-graph,code-analysis,tree-sitter,cypher,kglite,ast
+Author-email: Kristian dF Kollsgård <kkollsg@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# codingest
+
+[![CI](https://github.com/kkollsga/codingest/actions/workflows/ci.yml/badge.svg)](https://github.com/kkollsga/codingest/actions/workflows/ci.yml)
+[![crates.io](https://img.shields.io/crates/v/codingest.svg)](https://crates.io/crates/codingest)
+[![PyPI](https://img.shields.io/pypi/v/codingest.svg)](https://pypi.org/project/codingest/)
+[![Docs](https://readthedocs.org/projects/codingest/badge/?version=latest)](https://codingest.readthedocs.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Parse polyglot codebases into queryable
+[kglite](https://github.com/kkollsga/kglite) knowledge graphs — tree-sitter
+parsers for 14 languages, call / type / inheritance / route edges, an optional
+markdown-docs pass, and multi-git-revision merged graphs.
+
+codingest is the standalone home of KGLite's former in-tree `code_tree`
+component. The graph engine (storage backends, the Cypher pipeline, `.kgl`
+persistence) and the MCP protocol server are **imported from kglite as cargo
+libraries** — this repo owns only the code-tree component itself. Four surfaces
+ship from one workspace: a **CLI**, an **MCP server**, a **Python wheel**, and a
+**Rust crate**.
+
+Documentation: **[codingest.readthedocs.io](https://codingest.readthedocs.io)**
+
+## Requirements — kglite ≥ 0.14
+
+codingest builds against 0.14-only engine APIs (`kglite::api::code_entities`,
+`kglite_mcp_server::run_with_code_tree_hooks`) that KGLite added when it removed
+its in-tree builder. **These are not in any 0.13.x release.**
+
+- **Rust / crates.io:** codingest cannot be published, and a checkout without a
+  sibling `../KGLite` cannot build, until **kglite 0.14.0 is on crates.io**.
+  Local development uses a path dependency on the sister checkout (see
+  [Dependency policy](#dependency-policy)).
+- **Python wheel:** `pip install codingest` pulls `kglite>=0.13` for the
+  loader half of the handoff, but the *builder* half needs a kglite that
+  understands 0.14 graphs. Install **`kglite>=0.14`** alongside it.
+
+## Install
+
+```bash
+pip install codingest          # Python wheel (grammars bundled) — ALSO installs the `codingest` CLI
+cargo install codingest-cli    # pure-Rust `codingest` builder CLI (no Python)
+cargo install codingest-mcp    # the code-graph MCP server
+```
+
+The Python wheel bundles the `codingest` terminal command (the `codingest-cli`
+Rust library is linked into the wheel's extension), so `pip install codingest`
+alone gives you both `import codingest` and `codingest build`/`status` — the
+`cargo install codingest-cli` route is only needed for a pure-Rust install.
+This makes the pip-only flow `pip install kglite codingest && kglite skill
+install` self-sufficient (the installed code-review skill shells out to
+`codingest build`/`status`).
+
+(All become available once kglite 0.14.0 is published — see
+[Requirements](#requirements--kglite--014).)
+
+## Quick start
+
+### CLI
+
+```bash
+# Build a code graph from a checkout
+codingest build /path/to/repo
+# → /path/to/repo/.kglite/code-review.kgl
+
+# Build committed content at specific revisions (multi-rev merged graph)
+codingest build /path/to/repo --revs v1.0 v2.0
+
+# Check whether an existing graph is stale relative to the tree
+codingest status /path/to/repo
+```
+
+Then query or describe the `.kgl` with kglite (`kglite.load(...)`, the `kglite`
+shell, or any MCP/Bolt client).
+
+### MCP server
+
+```bash
+# Serve a live code-graph workbench over stdio for an MCP client / agent
+codingest-mcp --root-dir /path/to/repo
+```
+
+`codingest-mcp` embeds the `kglite-mcp-server` tool surface (`set_root_dir`,
+`graph_overview`, `cypher_query`, `read_code_source`, …) and injects the
+codingest builder, so `set_root_dir` builds a graph. Running plain
+`kglite-mcp-server` against a workspace **refuses to build** — it has no
+in-tree builder anymore. See the [MCP docs](https://codingest.readthedocs.io).
+
+### Python wheel
+
+```python
+import codingest
+
+g = codingest.build(".")                 # returns a real kglite.KnowledgeGraph
+g.cypher("MATCH (f:Function) RETURN f.name LIMIT 10")
+codingest.build(".", save_to="code.kgl") # also persist the .kgl
+codingest.build(".", rev="v1.0")         # build a git revision (or revs=[...])
+codingest.repo_tree("owner/name")        # clone a GitHub repo and build
+```
+
+**The `.kgl`-bytes handoff.** The `codingest` and `kglite` wheels are two
+separate compiled extensions and can't share live Rust objects, so `build()`
+constructs the graph with codingest's native builder, serializes it to a `.kgl`,
+then calls the *installed* `kglite` wheel's `load()` and returns **that** object
+— a genuine `kglite.KnowledgeGraph`, so every downstream kglite API works.
+
+**Bundled CLI.** The same wheel also provides the `codingest` terminal command
+(a `codingest/cli.py` console-script shim forwarding into the linked
+`codingest-cli` library), so `codingest build`/`status` works straight after
+`pip install codingest` — identical semantics to `cargo install codingest-cli`.
+
+### Rust crate
+
+```toml
+[dependencies]
+codingest = "0.1"   # needs kglite 0.14 on crates.io (see Requirements)
+kglite = "0.14"
+```
+
+```rust
+use codingest::build_code_tree; // = builder::run_with_options
+let graph = build_code_tree(dir, /*verbose=*/false, /*include_tests=*/true,
+                            /*save_to=*/None, /*max_loc=*/None, /*include_docs=*/false)?;
+// Query with kglite's Cypher pipeline, persist with kglite::api::io, …
+```
+
+## Workspace layout
+
+| Crate | What it is |
+|---|---|
+| `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. |
+| `crates/codingest-cli` | `codingest` binary — `build` a checkout or git revision(s) into a `.kgl` graph, `status` to check staleness. |
+| `crates/codingest-mcp` | `codingest-mcp` binary — the full MCP tool surface imported from the `kglite-mcp-server` library, with the codingest builder injected. |
+| `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`). |
+
+## CI-equivalent local gate: `make gate`
+
+`make gate` is the single-entry-point local gate that mirrors CI (`cargo fmt
+--check`, `cargo clippy --workspace --all-targets -- -D warnings`, workspace
+build + test incl. the golden oracle) and adds codingest-specific checks
+(determinism reproducer, `codingest_bench` parity smoke, the wheel build + the
+`tests/python` acceptance suite). Run it before pushing. Individual steps are
+also targets (`make clippy`, `make determinism`, …); `make fmt` auto-formats.
+
+### The golden-digest oracle
+
+KGLite deleted its in-tree `code_tree` builder on 2026-07-16, so the old
+two-builder parity sweep is gone. The authority it enforced was **frozen** while
+the builders were still verified identical, into per-corpus SHA-256 digests
+under `crates/codingest/tests/goldens/` (committed fixtures — no network). The
+`golden_parity` test builds each corpus with only the codingest builder, digests
+a canonical exhaustive graph rendering, and compares to the frozen golden. The
+multi-rev fixture is guarded instead by `rev_self_consistency`. Regenerate
+goldens only for deliberate builder-behavior changes:
+`cargo test -p codingest --test parity -- --ignored capture_goldens` (details in
+`crates/codingest/tests/goldens/README.md`).
+
+## Dependency policy
+
+`kglite` and `kglite-mcp-server` are path dependencies on the sister checkout
+`../KGLite` with a `version = "0.13"` crates.io fallback. The fallback is kept
+at `0.13` (not `0.14`) **only** because the local sister checkout is still
+versioned 0.13.4 while carrying the 0.14 APIs — a path dep's version requirement
+must be satisfiable by the path crate, so `0.14` would break the local build
+today. When kglite 0.14.0 ships, the maintainer bumps both fallbacks to `0.14`
+and flips the `CODINGEST_KGLITE_READY` CI variable (see the workspace
+`Cargo.toml` note and `.github/workflows/ci.yml`).
+
+## Parity with the (now-removed) in-tree component
+
+codingest was extracted to be feature- and performance-identical to kglite's
+in-tree `code_tree`. KGLite removed that module on 2026-07-16, so parity is now
+enforced against a **frozen record** of its last-known-good output rather than
+live cross-comparison. See `PARITY.md` (stats-diff + timing), `BENCHMARKS.md`
+(build-time + Cypher benchmarks), `crates/codingest/tests/parity.rs` (the golden
+oracle), and `docs/mcp-parity.md` (the MCP↔builder coupling and the hook).
+
+`tests/python-legacy/` preserves KGLite's full 47-file `kglite.code_tree`
+behavioral suite verbatim as the dormant behavioral spec — the source of truth
+for what the Python builder guaranteed (see its README).
+
+## License
+
+MIT © Kristian dF Kollsgård. codingest is an independent project; it depends on
+`kglite` at runtime but is not otherwise affiliated with it.
+

codingest-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+codingest/__init__.py,sha256=ZWRR1wNYROPOD6Wlyne23irAB20SsapFUY5eJB3Lc9U,1649
+codingest/__init__.pyi,sha256=69KtINplfVD-BWJGf1mqxsmmuHyQ0xHwHknsjLaTP5s,6015
+codingest/cli.py,sha256=bACzbAfoRCtUJtp-3Txxdhf8zlee5EKt-2Z3sk0PXLY,982
+codingest/codingest.pyd,sha256=11D0FkhgTogxDM11m5O--GFlARxQOCSkuqj4OfQWU7c,29216256
+codingest-0.1.0.dist-info/METADATA,sha256=7NVAX4e8h3ZdLXYI38vb6HFjWjnuVZgUg-0gWcql93c,10125
+codingest-0.1.0.dist-info/WHEEL,sha256=_qjkWZs5yrFgc7wGyX42BWq6PiACrY0XI82VSrZ_57E,96
+codingest-0.1.0.dist-info/entry_points.txt,sha256=z4H1v0B9AYriCtsIjJqVJj3910Gc-EYi0TYLtJyp5hQ,47
+codingest-0.1.0.dist-info/licenses/LICENSE,sha256=q0gXpC0K7UDWntzOORLPFJ1qRsJneOljj9IE_TBHX0I,1100
+codingest-0.1.0.dist-info/sboms/codingest-py.cyclonedx.json,sha256=TmZZ2GuWnISXL-OkUX-HlTDO4uw0y8kwM7XiYmYIr_4,209914
+codingest-0.1.0.dist-info/RECORD,,

codingest-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.14.1)
+Root-Is-Purelib: false
+Tag: cp310-abi3-win_amd64

codingest-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codingest=codingest.cli:main

codingest-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kristian dF Kollsgård
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.