pharaoh-parser

Open-source AST parser used by Pharaoh to extract structural metadata from TypeScript and Python codebases.

This is the exact code that runs in production. The main Pharaoh repository consumes this package as a dependency. You can audit every line to verify what Pharaoh extracts from your code.

What it extracts

Extracted	Example
Function names	authenticateUser
Function signatures	async function authenticateUser(email: string, password: string): Promise<User>
Line numbers	lineStart: 15, lineEnd: 48
Complexity scores	complexity: 7 (cyclomatic)
Export status	isExported: true
Import statements	{ source: "./db", symbols: ["findUser"] }
Class names and methods	{ name: "UserService", methods: ["create", "delete"] }
Body hashes	a3f8c2e1b9d04567 (one-way SHA-256 for dedup detection)
Module boundaries	{ name: "auth", files: ["src/auth/login.ts", ...] }
JSDoc/docstring summaries	First line, truncated to 200 chars
Top-level constant values	MAX_RETRIES = 3, API_BASE = "https://api.example.com" (strings and numbers up to 128 characters)
Decorators	@Get("/users"), @app.route("/api")

What it does NOT extract

• Source code — function bodies are never captured
• String literals inside functions — only top-level constant values are captured (see above), and Pharaoh encrypts them per customer
• Comments — only JSDoc/docstring first-line summaries (see note below)
• Environment variables — .env values are never read
• File contents — only structural metadata is extracted

Note on JSDoc/docstrings: The parser extracts the first line of JSDoc comments and Python docstrings (truncated to 200 characters) as function documentation. If your documentation contains sensitive information, the parser output will include it. This mirrors what any code review tool or IDE would show.

Quick start

git clone https://github.com/Pharaoh-so/pharaoh-parser.git
cd pharaoh-parser
npm install
node bin/inspect.js /path/to/your/repo

Output: JSON to stdout showing all structural metadata for every TypeScript and Python file in the repository.

Save to file

node bin/inspect.js /path/to/your/repo --output result.json

Example output

{
  "metadata": {
    "parserVersion": "1.0.0",
    "repoPath": "/home/user/my-project",
    "repoName": "my-project",
    "fileCount": 47,
    "parseFailures": 0,
    "timestamp": "2026-03-05T12:00:00.000Z"
  },
  "files": [
    {
      "path": "src/auth/login.ts",
      "language": "typescript",
      "loc": 142,
      "functions": [
        {
          "name": "authenticateUser",
          "signature": "async function authenticateUser(email: string, password: string): Promise<User>",
          "lineStart": 15,
          "lineEnd": 48,
          "loc": 34,
          "complexity": 7,
          "isExported": true,
          "isAsync": true,
          "bodyHash": "a3f8c2e1b9d04567",
          "paramCount": 2
        }
      ],
      "imports": [
        { "source": "./db", "symbols": ["findUser"], "isDefault": false, "isNamespace": false, "line": 1 }
      ],
      "exports": [
        { "name": "authenticateUser", "kind": "function", "isDefault": false }
      ],
      "classes": []
    }
  ]
}

How this connects to Pharaoh

This parser is step 1 of Pharaoh's pipeline, and the extraction you can run yourself. Pharaoh's hosted pipeline reads the same temporary clone to add more: which function calls which, HTTP routes, cron schedules, database tables, event handlers, environment variable names (never their values), and each file's last-modified date and how often it changed in the last 90 days. It deletes the clone when the run ends. Function signatures, doc comments, API routes and constant values are encrypted per customer before they're stored.

What Pharaoh adds on top:

• MCP tools that answer architectural questions from the graph
• Neo4j knowledge graph with cross-file dependency resolution
• Auto-remapping on every git push via GitHub App webhooks
• Multi-tenant infrastructure with tenant isolation

The parser extracts the raw data. Pharaoh turns it into architectural intelligence.

Learn more at pharaoh.so.

Supported languages

• TypeScript (.ts, .tsx) via tree-sitter-typescript
• Python (.py) via tree-sitter-python

Dependencies

Package	Purpose
web-tree-sitter	WASM-based parser runtime
tree-sitter-typescript	TypeScript/TSX grammar
tree-sitter-python	Python grammar
ignore	.gitignore pattern matching

Four dependencies. No network calls. No telemetry. Pure local computation.

Running tests

npm install
npm test

License

MIT