{"_id":"@0xjasonn/solql","name":"@0xjasonn/solql","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@0xjasonn/solql","version":"0.1.0","description":"CodeQL for Solidity — composable static analysis for AI agents","type":"module","license":"MIT","bin":{"solql":"dist/index.js"},"engines":{"node":">=22"},"dependencies":{"glob":"11.1.0","incur":"0.3.4"},"devDependencies":{"@types/node":"25.4.0","@vitest/coverage-v8":"4.0.18","oxfmt":"0.35.0","oxlint":"1.52.0","typescript":"5.9.3","vitest":"4.0.18"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/index.js","check":"oxlint src/ --fix --ignore-pattern package.json && oxfmt src/","check:types":"tsc --noEmit","test":"vitest run","test:watch":"vitest","check:all":"pnpm audit --audit-level=moderate && pnpm check:types && pnpm check && pnpm test","audit":"pnpm audit --audit-level=moderate"},"_id":"@0xjasonn/solql@0.1.0","_integrity":"sha512-Qi+OiUKIxBCxhZWtMNjKCb5gAlruaBHDAWq3/AurTticahKHZCHB9odgn1Q9kILwGjTzHEYw14UzgMrs6CGPnw==","_resolved":"/tmp/5205e7604a627c790538342b5e27b345/0xjasonn-solql-0.1.0.tgz","_from":"file:0xjasonn-solql-0.1.0.tgz","_nodeVersion":"24.13.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-Qi+OiUKIxBCxhZWtMNjKCb5gAlruaBHDAWq3/AurTticahKHZCHB9odgn1Q9kILwGjTzHEYw14UzgMrs6CGPnw==","shasum":"2d9484fc237534bccd20c83bc199cf9fdc0f97a2","tarball":"https://registry.npmjs.org/@0xjasonn/solql/-/solql-0.1.0.tgz","fileCount":164,"unpackedSize":866388,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDzINhLPuhU2EbAlHhR1WvgmZOHkR9kZt0AZubli3tedwIgHVXPtrCRL7JCDUN9bjKhe26Y9AHMcfoKoz15hXQd2GI="}]},"_npmUser":{"name":"0xjasonn","email":"0xjasonn@pm.me"},"directories":{},"maintainers":[{"name":"0xjasonn","email":"0xjasonn@pm.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/solql_0.1.0_1774470119157_0.2130789737616754"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-25T20:21:59.067Z","0.1.0":"2026-03-25T20:21:59.371Z","modified":"2026-03-25T20:21:59.589Z"},"maintainers":[{"name":"0xjasonn","email":"0xjasonn@pm.me"}],"description":"CodeQL for Solidity — composable static analysis for AI agents","license":"MIT","readme":"# solql\n\n[![CI](https://github.com/0xJasonn/solql/actions/workflows/ci.yml/badge.svg)](https://github.com/0xJasonn/solql/actions/workflows/ci.yml)\n\n**solql** is a composable static analysis framework for Solidity, written in TypeScript. It runs 17 analysis commands over Solidity ASTs, provides a `query` command for custom analyses, and serves as an MCP server for AI agents. Built for security auditors who want deterministic answers, not heuristics.\n\n**Note**: This is beta software. Use at your own risk and please provide feedback.\n\n- [solql](#solql)\n  - [Features](#features)\n  - [Usage](#usage)\n  - [How to Install](#how-to-install)\n    - [Using pnpm (Recommended)](#using-pnpm-recommended)\n    - [Using npm](#using-npm)\n    - [Agent Setup](#agent-setup)\n    - [Shell Completions](#shell-completions)\n  - [Commands](#commands)\n  - [Makefile](#makefile)\n  - [Composable Queries](#composable-queries)\n  - [MCP Server (Optional)](#mcp-server-optional)\n  - [Global Options](#global-options)\n  - [How It Works](#how-it-works)\n  - [Getting Help](#getting-help)\n  - [Development](#development)\n  - [License](#license)\n\n## Features\n\n- 17 analysis commands covering data flow, control flow, call graphs, pattern detection, and more\n- Forward taint analysis with path-sensitive (CFG-aware) mode\n- CEI compliance checking and reentrancy risk detection\n- State variable lifecycle analysis with coupled state and ordering edge detection\n- Cross-contract trust boundary analysis\n- Graph intersection queries: vulnerability = reachable(CFG) ∩ tainted(DDG) ∩ ¬guarded\n- Composable `query` command with 30+ primitives available as TypeScript globals\n- First-class MCP server support for AI agents (Claude, etc.)\n- Average execution time of less than 1 second per command (after initial build)\n\n## Usage\n\nRun solql on a Foundry project:\n\n```console\nsolql overview .\n```\n\nPoint it at a project in another directory:\n\n```console\nsolql overview ~/projects/my-protocol\n```\n\nAnalyze a specific contract:\n\n```console\nsolql surface Vault ~/projects/my-protocol\n```\n\nTrace where a parameter flows:\n\n```console\nsolql taint amount ~/projects/my-protocol --contract Vault --function deposit\n```\n\nUse `--skip-build` to reuse cached Forge artifacts for repeated analysis.\n\n## How to Install\n\n> **Note**\n> solql requires Node.js >= 22 and [Foundry](https://getfoundry.sh/) (for `forge build --ast`).\n\n### Using pnpm (Recommended)\n\n```console\ngit clone https://github.com/0xJasonn/solql.git && cd solql\npnpm install && pnpm build\npnpm link --global\n```\n\n### Using npm\n\n```console\ngit clone https://github.com/0xJasonn/solql.git && cd solql\nnpm install && npm run build\nnpm install -g .\n```\n\n`solql` is now available system-wide.\n\n### Agent Setup\n\nRegister solql as an MCP server with your AI agent:\n\n```console\n# Auto-detect and register with all installed agents\nsolql mcp add\n\n# Or target a specific agent\nsolql mcp add --agent cursor\n```\n\nSupported agents: Claude Code, Cursor, VS Code, Codex, Amp, Gemini CLI, GitHub Copilot CLI, Cline, Goose, Zed, OpenCode.\n\nFor Claude Code, you can also install skills (lighter on tokens):\n\n```console\nsolql skills add\n```\n\n### Shell Completions\n\n```console\neval \"$(solql completions bash)\"    # add to ~/.bashrc\neval \"$(solql completions zsh)\"     # add to ~/.zshrc\nsolql completions fish | source     # add to ~/.config/fish/config.fish\n```\n\n## Commands\n\n| Num | Command              | What it Does                                                                                |\n| --- | -------------------- | ------------------------------------------------------------------------------------------- |\n| 1   | `overview`           | [List all contracts, files, and inheritance chains](docs/commands.md#overview)              |\n| 2   | `surface`            | [Entry points, state vars, modifiers for a contract](docs/commands.md#surface)              |\n| 3   | `recon`              | [Full protocol recon: access control, state writes, parameter flow](docs/commands.md#recon) |\n| 4   | `taint`              | [Forward taint: trace where a parameter flows](docs/commands.md#taint)                      |\n| 5   | `branch-taint`       | [CFG-aware taint with branch condition tracking](docs/commands.md#branch-taint)             |\n| 6   | `state-changes`      | [State variables a function mutates](docs/commands.md#state-changes)                        |\n| 7   | `msg-sender`         | [Trace msg.sender flow and constraints](docs/commands.md#msg-sender)                        |\n| 8   | `impact`             | [Blast radius: transitive state changes + external calls](docs/commands.md#impact)          |\n| 9   | `cfg`                | [Control flow graph (branches, loops, returns, reverts)](docs/commands.md#cfg)              |\n| 10  | `cei`                | [Checks-Effects-Interactions compliance / reentrancy risk](docs/commands.md#cei)            |\n| 11  | `guards`             | [Conditions on the path from entry to a target node](docs/commands.md#guards)               |\n| 12  | `callgraph`          | [Call paths to/from a function](docs/commands.md#callgraph)                                 |\n| 13  | `patterns`           | [AST anti-patterns (unchecked-return, tx-origin, etc.)](docs/commands.md#patterns)          |\n| 14  | `modifiers`          | [Modifier usage, flag unguarded state-changers](docs/commands.md#modifiers)                 |\n| 15  | `lifecycle`          | [State variable lifecycle: writers, readers, coupled state](docs/commands.md#lifecycle)     |\n| 16  | `trust-boundary`     | [Cross-contract trust boundaries and callback risks](docs/commands.md#trust-boundary)       |\n| 17  | `graph-intersection` | [Reachable ∩ tainted ∩ ¬guarded vulnerability query](docs/commands.md#graph-intersection)   |\n\nFor full documentation with usage examples and JSON output format for every command, see the [Command Documentation](docs/commands.md).\n\n## Makefile\n\nCommands can get verbose. The repo ships a [`Makefile`](Makefile) with shorthand targets for every command:\n\n```bash\n# Before\nsolql taint to . --contract Token --function transfer --skip-build\n\n# After\nmake taint C=Token F=transfer P=to\n```\n\nRun `make help` to see all targets.\n\n| Variable | Meaning    | Example                 |\n| -------- | ---------- | ----------------------- |\n| `ROOT`   | Project    | `ROOT=~/my-protocol`    |\n| `C`      | Contract   | `C=Vault`               |\n| `F`      | Function   | `F=deposit`             |\n| `P`      | Parameter  | `P=amount`              |\n| `V`      | Variable   | `V=totalSupply`         |\n| `N`      | Node ID    | `N=1234`                |\n| `FILE`   | Query file | `FILE=queries/recon.ts` |\n\n## Composable Queries\n\nThe `query` command lets you write TypeScript scripts with access to all analysis primitives as globals:\n\n```console\nsolql query . --skip-build --inline '\n  const CONTRACT = \"MyVault\";\n  const eps = stateChangingEntryPoints(CONTRACT);\n  return eps.map(ep => ({\n    name: ep.name || ep.kind,\n    stateChanges: stateChanges(CONTRACT, ep.name),\n    cei: cei(CONTRACT, ep.name),\n    impact: impact(CONTRACT, ep.name),\n  }));\n'\n```\n\n32 reusable query templates ship in the [`queries/`](queries/) directory. See the [query documentation](docs/commands.md#query) for the full list of available globals.\n\n## MCP Server (Optional)\n\nThe MCP server is **not required** — the CLI works standalone. MCP adds structured JSON responses for AI agents.\n\nThe recommended setup is `solql mcp add` (see [Agent Setup](#agent-setup)). To configure manually:\n\n```json\n{\n  \"mcpServers\": {\n    \"solql\": {\n      \"command\": \"npx\",\n      \"args\": [\"solql\", \"--mcp\"]\n    }\n  }\n}\n```\n\nAll 17 CLI commands become MCP tools. Use `solql --llms` to output an agent-readable command manifest.\n\n## Global Options\n\nEvery command supports these built-in flags:\n\n| Flag                     | Description                                           |\n| ------------------------ | ----------------------------------------------------- |\n| `--json`                 | Output as JSON instead of default TOON format         |\n| `--format <fmt>`         | Output format: `toon`, `json`, `yaml`, `md`           |\n| `--filter-output <keys>` | Filter output by key paths (e.g. `contractList.name`) |\n| `--skip-build`           | Reuse cached Forge artifacts                          |\n| `--schema`               | Show JSON Schema for a command's args/options         |\n| `--llms`                 | Print agent-readable command manifest                 |\n| `--help`                 | Show help                                             |\n\n## How It Works\n\n1. **Load** — Runs `forge build --ast` and parses the Solidity compiler's JSON AST output\n2. **Index** — Builds O(1) node lookup, contract registry, and C3 linearization from solc\n3. **Analyze** — 15 modular analysis engines (taint, CFG, guards, CEI, dominance, etc.) operate as pure functions over the index\n4. **Query** — Compose primitives in TypeScript scripts or call them individually via CLI/MCP\n\n## Getting Help\n\n- See the [Command Documentation](docs/commands.md) for detailed usage and output format for every command\n- Run `make help` for a quick reference of all Makefile targets\n- [Open an issue](https://github.com/0xJasonn/solql/issues) for bugs or feature requests\n\n## Development\n\n```console\npnpm build        # Compile TypeScript\npnpm dev          # Watch mode\npnpm test         # Run tests\npnpm check:all    # Type check + lint + test\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-90f2a66871b7b70eae834476eb60f49f"}