@graphpilot-oss/graphpilot 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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 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 2026 Akshay Sharma
+
+   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.

package/README.md

@@ -0,0 +1,132 @@
+<p align="center">
+  <img src="assets/logo.png" alt="GraphPilot" width="120" />
+</p>
+
+<h1 align="center">GraphPilot</h1>
+
+> **The refactor-safe code graph for coding agents.** Branch-aware. Evidence-backed.
+> A structural memory layer that knows what changed since `main`, cites every claim
+> with `file:line @ sha`, and re-roots itself to the git worktree automatically.
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#status)
+
+---
+
+**On 10 standardized structural questions** about a real TypeScript codebase:
+GraphPilot returns the correct answer with **F1 0.89** vs grep's **0.42**, while
+the agent reads **99.9 % fewer bytes** (721 B vs 528 KB) to reach the same
+conclusion. [Reproduce in 30 s →](bench/README.md)
+
+---
+
+## Status
+
+Pre-alpha, in active development. Not yet published to npm. Expect breaking changes.
+
+## Quickstart (local dev)
+
+```bash
+git clone https://github.com/graphpilot-oss/graphpilot.git
+cd graphpilot
+pnpm install
+pnpm build
+
+# Index a repo
+node dist/cli.js index /path/to/your/repo
+
+# See what got indexed
+node dist/cli.js status /path/to/your/repo
+
+# Keep the index fresh as you edit (Ctrl+C to stop)
+node dist/cli.js watch /path/to/your/repo
+```
+
+Then wire it into Claude Code (or any MCP client): see
+[docs/mcp-setup.md](docs/mcp-setup.md).
+
+## What it does
+
+Five MCP tools that any MCP-compatible agent (Claude Code, Cursor, Cline,
+Windsurf, Continue) can call:
+
+| Tool         | Use it for                                                                                                                                                                           |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `gp_index`   | Re-index a repo from inside the agent                                                                                                                                                |
+| `gp_recall`  | Look up a function/class/type/interface by name                                                                                                                                      |
+| `gp_callers` | List callers (or callees) of a symbol                                                                                                                                                |
+| `gp_impact`  | Blast radius: direct + transitive callers, tests affected, public-API flag — answers _"what breaks if I rename X?"_ in one call. Pass `since: <commit\|branch>` for PR-scoped impact |
+| `gp_stats`   | Index health probe                                                                                                                                                                   |
+
+Plus `graphpilot watch` for sub-second incremental updates on file save.
+
+The index lives in `~/.graphpilot/<repo-id>/graph.json` (mode 0600). Everything
+stays local. No accounts, no telemetry, no remote calls — enforced by an
+ESLint policy on the codebase itself.
+
+## What's different
+
+Other code-graph tools (CodeGraphContext, Serena, the 15+ existing MCP servers
+in this space) treat your repo as a static blob: index once, query forever, no
+awareness of branches, no proof of where an answer came from. GraphPilot is
+built around three things none of them ship:
+
+- **Evidence anchors.** Every tool response includes `file:line @ sha` for
+  every symbol and call site. The agent can quote the anchor verbatim and
+  you can verify it instantly — fabrications get exposed the moment the user
+  jumps to the line.
+- **Differential impact (`gp_impact({since: <ref>})`).** Ask "of all the
+  callers of `X`, which ones live in code my PR touches?" — answered in one
+  call instead of `git diff | xargs grep`. Branch-scoped refactors without
+  the false-positive noise.
+- **Worktree-aware by default.** Run `graphpilot index ./src/feature` from a
+  subdir and it transparently re-roots to the git worktree top, so two
+  `git worktree add`-ed branches naturally get two separate indexes. Opt out
+  with `--no-worktree`.
+
+## Roadmap
+
+| Milestone                                        | Status            |
+| ------------------------------------------------ | ----------------- |
+| Parser + symbol extraction (TS/JS)               | ✅                |
+| Directory indexer + JSON storage                 | ✅                |
+| Call-edge extraction + resolver                  | ✅                |
+| MCP server (5 tools)                             | ✅                |
+| Watch mode                                       | ✅                |
+| Impact analysis (`gp_impact`)                    | ✅                |
+| Tier-A benchmark (this codebase)                 | ✅                |
+| Tier-B agent benchmark (Claude Code vs baseline) | ⏭                |
+| npm publish                                      | ⏭                |
+| Python language support                          | ⏭ (demand-gated) |
+
+## Why
+
+Most coding agents (Claude Code, Cursor, Aider) re-grep the codebase every
+conversation. That burns tokens, hallucinates function names, and misses
+structural relationships (_"what calls this?"_, _"what breaks if I rename it?"_).
+
+GraphPilot indexes the structural memory of your repo once. The agent reuses
+it across sessions. Token cost drops. Hallucinations drop. Refactors get safer.
+
+The benchmark above is the floor: it measures what's reachable via tool calls,
+not what the agent does with it. The agent-eval Tier B is spec'd in
+[bench/run-agent-tier.md](bench/run-agent-tier.md) and pending a focused
+launch-prep session.
+
+## Documentation
+
+- [docs/quickstart.md](docs/quickstart.md) — 5-minute walkthrough
+- [docs/mcp-setup.md](docs/mcp-setup.md) — per-client config
+- [docs/architecture.md](docs/architecture.md) — how the pipeline works
+- [docs/limitations.md](docs/limitations.md) — v1 caveats (read this)
+- [bench/README.md](bench/README.md) — benchmark methodology + results
+
+## Contributing
+
+We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) before
+opening a PR.
+
+## License
+
+[Apache-2.0](LICENSE). Copyright 2026 Akshay Sharma.

package/SECURITY.md

@@ -0,0 +1,44 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security issue, **please do not open a public GitHub issue.**
+
+Email: `codewithakki@gmail.com`
+
+Include:
+
+- A description of the issue
+- Steps to reproduce
+- Affected version(s)
+- Any proof-of-concept code
+
+We will:
+
+- Acknowledge your report within **72 hours**
+- Investigate and confirm the issue
+- Ship a fix within **14 days** for high-severity issues
+- Credit you in the release notes (unless you ask us not to)
+
+## Supported Versions
+
+GraphPilot is pre-1.0; only the latest release receives security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x     | :white_check_mark: |
+
+Once we hit 1.0, this table will be expanded to cover the last two minor versions.
+
+## Scope
+
+In scope:
+
+- The `graphpilot` npm package itself
+- The MCP server implementation
+- Any data written to `~/.graphpilot/`
+
+Out of scope:
+
+- Third-party MCP clients (Claude Code, Cursor, etc.) — report those upstream
+- Tree-sitter grammar bugs — report to the relevant tree-sitter-\* repo

package/assets/logo.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="utf-8" ?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="1024" height="1024" viewBox="0 0 1024 1024"><path fill="#1D1A1B" d="M0 0L1024 0L1024 1024L0 1024L0 0Z"/><path fill="#E6E6E6" d="M623.952 307.851C616.946 299.401 612.137 292.66 608.918 281.902C600.373 253.345 608.714 225.118 631.759 206.258C646.698 193.899 665.933 187.979 685.235 189.8C725.89 193.898 755.417 228.241 750.233 269.06C748.248 284.694 743.061 296.671 732.459 308.328C738.951 320.16 747.166 332.759 754.121 344.519L813.444 442.737C853.186 433.897 894.116 455.566 903.14 496.388C907.467 515.328 903.929 535.212 893.336 551.498C883.03 567.447 865.762 578.676 847.303 582.608C827.731 586.626 807.364 582.693 790.696 571.675C775.479 561.635 765.859 546.863 761.328 529.368L659.193 529.426C660.829 518.644 662.635 506.716 660.947 495.806C694.142 495.192 728.301 496.58 761.361 495.535C766.124 478.953 770.847 470.281 783.556 458.278L732.041 374.089C723.334 360.023 711.322 341.708 703.46 327.53C686.66 332.845 667.666 333.246 651.145 326.69C639.184 346.945 626.372 366.769 614.298 386.97C610.915 392.629 607.129 399.182 603.108 404.365C598.655 395.8 591.263 383.342 582.096 379.103L581.206 378.191C581.675 376.606 590.933 361.589 592.364 359.305C602.843 342.579 612.959 324.17 623.952 307.851Z"/><path fill="#1D1A1B" d="M825.433 473.465C846.916 469.82 867.27 484.332 870.826 505.83C874.382 527.328 859.786 547.622 838.274 551.089C816.886 554.537 796.736 540.044 793.201 518.671C789.665 497.298 804.075 477.089 825.433 473.465Z"/><path fill="#1D1A1B" d="M673.831 220.952C695.507 218.429 715.084 234.059 717.423 255.756C719.762 277.452 703.966 296.896 682.25 299.05C660.794 301.179 641.633 285.612 639.322 264.175C637.011 242.737 652.414 223.445 673.831 220.952Z"/><path fill="#E6E6E6" d="M183.789 441.198C196.642 439.122 216.91 443.217 228.059 450.018C246.683 461.38 257.046 475.231 262.608 495.984C298.863 495.654 335.119 495.661 371.373 496.005C373.542 498.345 375.952 500.449 378.562 502.284C390.734 510.755 402.696 512.43 416.908 509.93C416.981 521.221 417.821 528.552 421.297 539.456C428.931 563.525 445.964 583.489 468.531 594.817C492.106 606.886 517.427 607.999 542.437 600.014C540.934 620.868 548.872 632.725 567.716 641.332C561.22 656.663 548.885 679.497 541.178 694.771L527.934 720.767C525.22 726.036 521.77 734.957 516.474 737.757C500.829 746.029 492.742 718.742 487.625 707.333C474.688 679.409 460.734 651.551 448.031 623.506C444.017 621.383 440.117 619.051 436.347 616.519C406.555 596.178 388.002 564.606 381.269 529.489L262.463 529.467C260.019 538.626 254.775 549.288 248.92 556.721C236.723 572.152 218.804 581.996 199.239 584.015C180.091 586.161 159.562 579.806 144.661 567.673C130.373 555.974 121.274 539.113 119.337 520.748C115.267 480.366 143.257 445.211 183.789 441.198Z"/><path fill="#1D1A1B" d="M185.242 473.557C206.734 470.139 226.91 484.838 230.245 506.343C233.579 527.847 218.801 547.967 197.284 551.217C175.885 554.45 155.9 539.771 152.584 518.385C149.268 496.998 163.869 476.956 185.242 473.557Z"/><path fill="#1FCBEE" d="M582.096 379.103C591.263 383.342 598.655 395.8 603.108 404.365C604.543 407.945 607.631 422.989 608.098 423.571C651.912 478.165 651.165 554.704 600.211 604.405C594.819 609.664 587.965 617.769 579.03 617.597C574.108 617.54 569.423 615.474 566.062 611.877C562.785 608.355 561.093 603.811 561.262 599.009C561.435 590.259 569.475 585.395 575.121 579.942C615.702 540.747 614.117 483.467 576.755 443.327C596.464 423.499 594.265 402.404 582.096 379.103Z"/><path fill="#6C4FE3" d="M499.806 384.211C519.838 381.435 548.724 388.708 564.656 400.39C581.268 412.572 566.969 435.585 547.614 426.146C544.065 424.415 535.644 421.694 531.689 420.935C522.104 419.181 512.331 418.679 502.617 419.442C475.541 421.528 453.509 435.095 436.072 455.382C428.36 465.159 425.093 473.64 419.518 484.392C417.145 487.642 411.808 489.95 408.129 490.357C398.555 491.415 388.431 484.818 388.106 474.668C387.865 467.131 391.862 460.112 395.001 453.488C399.49 444.015 405.59 435.623 412.461 427.757C434.496 402.035 466.003 386.328 499.806 384.211Z"/></svg>