omp packages

@xynogen/pix-graph0.3.1

Pi extension — native TS code knowledge graph (extract, cluster, analyze, query)

GitHub Actions Published 13 days ago MIT ~512 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

pix-graph

Native-TS code knowledge graph — extract, cluster, analyze, and query a codebase without Python or an external service. TS/JS is parsed with the TypeScript compiler API into a graph of files and symbols; communities are found with Louvain; questions are answered by BFS/DFS traversal over the graph.

Ships three ways: a model-callable graph tool, a CLI, and a library. Standalone/opt-in — not bundled by pix-core, so the one recurring tool schema is only present when you install it.

graph tool

One tool, two modes:

Call Effect
graph(action:"build", path?) (Re)build/update the graph from source into .pi/graph/. Run again after edits to refresh.
graph(action:"query", question, dfs?) Answer a codebase question by traversing the existing graph. BFS (default) for broad context, dfs:true to trace a path.

pix-nudge also drops a one-line reminder to prefer graph(action:"query") over grepping when .pi/graph/graph.json exists (it also detects a legacy graphify-out/graph.json). Output lives under the gitignored .pi/ dir.

CLI

pix-graph build [path] [--out DIR] [--root DIR]   # extract + cluster + analyze
pix-graph query "<question>" [--graph FILE] [--dfs] [--depth N]
pix-graph path "<from>" "<to>" [--graph FILE]      # shortest path between nodes

build writes into --out (default .pi/graph/):

Output Description
graph.json Full graph: nodes, links, community assignments
graph.cleaned.json Inferred calls edges validated against real TS bindings; false ones removed
GRAPH_REPORT.md Communities, god nodes, surprising cross-file connections
graph.html Interactive view of graph.cleaned.json: community colors, search, node details. Open it with /graph.

Library

import { buildCodeGraph, query, analyzeGraph } from "@xynogen/pix-graph";

const result = buildCodeGraph("src", process.cwd(), ".pi/graph");
// → { nodes, links, communities, outputDir }
Export Purpose
collectFiles, extract Walk a tree and parse TS/JS into { nodes, links }
buildGraph, cluster, cohesionScore, scoreAll Assemble + Louvain community detection
godNodes, surprisingConnections Graph analysis
query, shortestPath Traversal over a built graph
renderGraphReport Human-readable report
analyzeGraph, renderPatternReport Validate/clean an existing graph + extract repeated patterns
buildCodeGraph Full pipeline orchestrator

The graph JSON schema (nodes/links/hyperedges, EXTRACTED/INFERRED confidence) is compatible with external graphify — a graph built by either tool works with the other's query.

Scope ceilings

  • TS/JS only. Other languages need a tree-sitter extractor (not built). Upgrade path: add per-language extractors behind collectFiles.
  • Louvain, not Leiden. Leiden needs the native graspologic library. Upgrade path: add a Leiden refinement pass over the Louvain communities.
  • Lexical query seeds, no embeddings. Upgrade path: rank seed nodes with a similarity model if recall proves weak.
  • Code only. For docs, PDFs, images, or video, use external graphify.

Install

pi install npm:@xynogen/pix-graph

Standalone and opt-in. @xynogen/pix-core does not bundle it. You run it on demand. Its graph tool schema loads only when you install it.

Full distro

This package is part of Pix. The installer sets up Pi and the full distro. See Install for the notes for each OS.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex

License

MIT