repograph-codeintel 0.1.0__tar.gz

repograph_codeintel-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

repograph_codeintel-0.1.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.4
+Name: repograph-codeintel
+Version: 0.1.0
+Summary: Evidence-backed codebase intelligence and change-impact analysis for AI coding agents
+Author: RepoGraph contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/INDEX0-RESEARCH-LABS/repograph
+Project-URL: Documentation, https://github.com/INDEX0-RESEARCH-LABS/repograph/tree/main/docs
+Keywords: code-intelligence,code-graph,mcp,change-impact,dependency-graph,static-analysis,tree-sitter,ai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: mcp<3,>=2.0
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero-dark.svg">
+    <img src="docs/assets/hero.svg" alt="RepoGraph — local code graph and change impact analysis for AI coding agents" width="620">
+  </picture>
+</h1>
+
+<p align="center">
+  <a href="https://github.com/INDEX0-RESEARCH-LABS/repograph/actions/workflows/ci.yml"><img src="https://github.com/INDEX0-RESEARCH-LABS/repograph/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-3776AB" alt="Python 3.10+"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache-2.0"></a>
+  <a href="STATUS.md"><img src="https://img.shields.io/badge/status-alpha-orange" alt="alpha"></a>
+</p>
+
+<p align="center">
+  <b>See what a code change touches — before you ship it.</b><br>
+  Local. No account, no API key, no code execution.
+</p>
+
+**RepoGraph is a local code graph and change impact analysis tool for AI coding agents.** It reads your repository, records what imports what, and answers one question:
+
+> **"If I change this file, what else might break?"**
+
+You get the files, tests and routes that depend on it. Every item carries its evidence (file and line) and a confidence label. It also tells you what it **could not see**.
+
+```bash
+repograph index .
+repograph impact src/payments/refund.py
+```
+
+Real output from the test fixture, with the route and documentation-mention lines removed for length:
+
+```
+changed files (1): src/shop/services/subscription.py
+changed symbols: 1
+  function  cancel  src/shop/services/subscription.py:6
+
+direct dependents (4):
+  [confirmed] src/shop/__init__.py  (imports-changed-file at line 1)
+  [confirmed] src/shop/api/routes.py  (imports-changed-file at line 3)
+  [confirmed] src/shop/services/billing.py  (imports-changed-file at line 1)
+  [confirmed] tests/test_subscription.py  (imports-changed-file at line 1)
+transitive dependents: 1
+  [confirmed] depth 2 src/shop/app.py
+
+related tests (1):
+  [inferred] tests/test_subscription.py  (test-imports-changed-file, test-name-matches-changed-file, test-name-matches-dependent)
+
+blind spots:
+  - repo-dynamic-imports (2): Dynamic imports exist in the repository; their runtime targets may include the changed files.
+  - repo-parse-errors (1): Files with parse errors contribute no symbols or edges anywhere in the index.
+
+note: absence of static evidence is not evidence of safety.
+```
+
+Python, TypeScript, JavaScript, JSX and TSX. Static analysis only. **Alpha.**
+
+## Install
+
+Python 3.10 or newer. Nothing else — no database server, no Docker, no cloud.
+
+```bash
+git clone https://github.com/INDEX0-RESEARCH-LABS/repograph.git
+cd repograph && python -m venv .venv && .venv/bin/pip install -e .
+.venv/bin/repograph version
+```
+
+Not on PyPI yet. `pipx install --editable .` works too. Linux is tested in CI; macOS and Windows should work but are untested.
+
+## Use
+
+Run this inside **your** project:
+
+```bash
+repograph init .              # create .repograph/
+repograph index .             # build the map
+repograph status .            # check what was found
+repograph impact src/app.py   # ask what depends on it
+```
+
+That is the loop. Re-index after you edit: `repograph index . && repograph impact --diff`.
+
+If `repograph` is not found, activate the venv (`source .venv/bin/activate`). These commands only read files.
+
+## Find the tests a change reaches
+
+```bash
+repograph tests --diff
+```
+
+On `pallets/click` (44 test files), changing `src/click/core.py`:
+
+```
+run these (6, 14% of 44):
+  [inferred] tests/test_context.py  (test-imports-changed-file, test-name-matches-dependent)
+  [inferred] tests/test_defaults.py  (test-imports-changed-file, test-name-matches-dependent)
+  [inferred] tests/test_deprecations.py  (test-imports-changed-file, test-name-matches-dependent)
+  [inferred] tests/test_parser.py  (test-name-matches-dependent)
+  [inferred] tests/test_shell_completion.py  (test-imports-changed-file, test-name-matches-dependent)
+  [inferred] tests/test_testing.py  (test-name-matches-dependent)
+
+cannot rule out (0):
+
+reachable but not selected (37):
+  tests/conftest.py
+  tests/test_abort_interrupt.py
+  tests/test_arguments.py
+  ...
+```
+
+`--command` prints only the pytest line, for CI. `--strict` exits `3` when a test cannot be ruled out or nothing was selected.
+
+**Measured, and the number is bad.** On 22 one-function mutations across click, Flask and packaging, the selected set caught **41 of 180 failing test files (pooled recall 0.23, median 0.38)** while selecting a median 6.7% of test files. Adding every disclosed "reachable but not selected" file catches 179/180 — but that is 98.9% of the suite, i.e. no saving. Details: `research/TEST_SELECTION_GATE_RESULTS.md`.
+
+So treat this command as **a disclosure aid, not a gate**: it tells you some files a change reaches, and it names the ones it cannot justify selecting. It does not know which tests exercise which behaviour, and it will omit files that fail. **Run the suite before trusting it.**
+
+## Give it to your agent
+
+One command registers the server **and** installs the instructions that make the agent actually use it:
+
+```bash
+repograph setup .
+```
+
+It writes a project `.mcp.json` plus a Claude Code skill (and a Cursor rule when `.cursor/` exists), shows the diff first, and backs up any file it changes. Add `--client codex` to register it in `~/.codex/config.toml`; `--dry-run` writes nothing.
+
+Restart your agent, then ask:
+
+> What breaks if I change the refund calculation?
+
+Without the instructions an agent tends to keep grepping — a measured failure mode, not a guess. The skill tells it when the graph is the cheaper answer, in what order to call the tools, and to read `blind_spots` before acting.
+
+<details>
+<summary><b>Manual MCP config</b></summary>
+
+```bash
+repograph serve --root /path/to/your/project
+```
+
+```json
+{
+  "mcpServers": {
+    "repograph": {
+      "command": "repograph",
+      "args": ["serve", "--root", "/absolute/path/to/your/project"]
+    }
+  }
+}
+```
+
+Claude Code and Cursor accept this JSON shape. Use an absolute `--root` and put `repograph` on the client's `PATH`.
+
+</details>
+
+| Tool | What it returns |
+| --- | --- |
+| `analyze_change_impact` | Dependents, tests, routes, models and blind spots. |
+| `find_related_tests` | Candidate tests. Heuristic — always run the suite. |
+| `find_references` | Definition and resolved reference sites. |
+| `get_dependency_graph` | What a file imports and what imports it. |
+| `search_symbols` | Names with file and line. |
+| `get_architecture_summary` | Languages, layers, hubs, entry points, routes, models. |
+
+> **Security:** `serve --http` has **no authentication** and binds to `127.0.0.1` by default. Do not expose it to an untrusted network.
+
+## What the labels mean
+
+| Label | Plain meaning |
+| --- | --- |
+| `confirmed` | The code says it directly: a real import, or a call in the same file. |
+| `inferred` | Worked out from project setup: a TypeScript alias or workspace package. |
+| `heuristic` | A guess from patterns: route decorators, model base classes, test names. |
+| `unresolved` | Seen in the code, but the target could not be found. Kept and reported. |
+
+## How accurate is it?
+
+Measured in October 2026 with a pre-registered protocol and two independent AI labelers, on three repositories never used to build the tool.
+
+| Repository | Correct links (precision) | Links found (recall) |
+| --- | ---: | ---: |
+| [httpx](https://github.com/encode/httpx) (Python) | 100% (30/30) | 100% (30/30) |
+| [zustand](https://github.com/pmndrs/zustand) (TypeScript) | 96.7% (58/60) | 100% (58/58) |
+| [mocha](https://github.com/mochajs/mocha) (JavaScript) | 100% (30/30) | 78.9% (30/38) |
+| **Overall** | **98.3%** (118/120) | **93.7%** (118/126) |
+
+- 95% intervals: precision 94.1%–99.5%, recall 88.0%–96.8%.
+- Both mistakes were one bug (a config alias leaking into example apps). Fixed and rechecked; the measured figure stays 118/120.
+- All eight missed links were JSON files in mocha, which is why mocha's recall is shown on its own.
+- Recall is an estimate, not a census. JSON/config imports, some Node aliases and non-code assets (`.css`, images, `.vue`) are not mapped.
+
+Method, raw samples and threats to validity: [research/EDGE_ACCURACY_RESULTS.md](research/EDGE_ACCURACY_RESULTS.md).
+
+## How fast is it?
+
+One Linux machine, one run per project (Python 3.14.8, October 2026). Index step only.
+
+| Repository | Files | Symbols | First index | Update (no changes) | Impact query |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| [express](https://github.com/expressjs/express) | 142 | 63 | 0.28 s | 0.08 s | 2.1 ms |
+| [click](https://github.com/pallets/click) | 91 | 2,077 | 0.57 s | 0.06 s | 18.4 ms |
+| [vue-core](https://github.com/vuejs/core) | 528 | 2,273 | 1.79 s | 0.24 s | 22.4 ms |
+| [fastapi](https://github.com/fastapi/fastapi) | 1,223 | 7,125 | 5.26 s | 1.10 s | 82.1 ms |
+
+Express is a known weak spot: its CommonJS export style yields few symbols from many files. The report says so instead of hiding it.
+
+## What it cannot do
+
+- **No execution.** Reflection, computed imports and runtime wiring are invisible.
+- **Two language families.** Python and JavaScript/TypeScript. Others are ignored.
+- **No type checking or data flow.** It follows imports and names, not values.
+- **Tests are heuristic.** A measured run on Flask found **24% of failing test files** (60% counting indirect dependents). Run the suite.
+- **Routes and models are partial.** Common frameworks only.
+- **An empty result is not proof.** It says "no dependents found", not "safe".
+
+It is not a compiler, a type checker, a semantic search engine, or a replacement for tests.
+
+<details>
+<summary><b>All commands</b></summary>
+
+| Command | What it does |
+| --- | --- |
+| `repograph init [path]` | Create `.repograph/` with a config file. |
+| `repograph index [path]` | Build or update the map. `--force`, `--reset`, `--json`. |
+| `repograph status [path]` | Counts, parse errors, whether an update is needed. |
+| `repograph search <text>` | Find symbols and source text. `--kind`, `--limit`. |
+| `repograph refs <name>` | Definition and the places that use it. |
+| `repograph graph [path]` | Imports in, out or both. `--depth 1-5`, `--format dot`, `--cycles`. |
+| `repograph arch` | Languages, layers, hubs, entry points, routes, models. |
+| `repograph impact <paths>` | Dependents, tests, routes, blind spots. `--symbol`, `--diff`, `--depth`, `--tests/--no-tests`. |
+| `repograph tests [paths]` | Test files a change reaches, files that cannot be ruled out, and reachable files not selected (heuristic; measured recall 0.23). `--diff`, `--base`, `--strict`, `--command`. |
+| `repograph setup [path]` | Register the MCP server and install agent instructions. `--client`, `--yes`, `--dry-run`, `--no-skill`. |
+| `repograph serve` | MCP server. `--http`, `--host`, `--port`. |
+
+Every read command accepts `--json`.
+
+</details>
+
+<details>
+<summary><b>Common problems</b></summary>
+
+| Problem | Fix |
+| --- | --- |
+| `impact --diff` finds nothing | The edit is not indexed. Run `repograph index .` first. |
+| Fewer symbols than expected | The code may use a pattern the parser does not cover. Check `status` and `arch` for parse errors. |
+| A dependency is missing | It may be dynamic, unresolved, or in another language. Check the blind spots block. |
+| MCP client cannot connect | Use an absolute `--root`, and put `repograph` on the client's `PATH`. |
+| Agent never calls the tools | Re-run `repograph setup .`, restart the agent, and confirm the skill landed in `.claude/skills/repograph/SKILL.md`. |
+
+</details>
+
+## Project
+
+- [STATUS.md](STATUS.md) — what is tested, measured and still missing.
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — modules, schema, algorithms.
+- [docs/LIMITATIONS.md](docs/LIMITATIONS.md) — analysis gaps and security model.
+- [research/](research/) — accuracy protocols, raw results, decision log.
+- [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md)
+
+```bash
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest
+```
+
+75 tests, 69% direct coverage, CI on Python 3.10, 3.12 and 3.13. The CLI and MCP server are tested through subprocesses, so coverage does not attribute those runs to their modules.
+
+Apache-2.0. See [LICENSE](LICENSE).