@ebowwa/repo-ontology

Builds ontologies of codebases: walk any repo and get a deterministic, cross-language dictionary of every named symbol — modules, classes, functions, methods, types, constants — with kind, file:line location, signature, and a one-line doc summary — plus edges (imports/exports, symbol references, and declared cross-language provenance).

Sibling of @ebowwa/codegen-kit (which powers the write/--check drift machinery here).

npx @ebowwa/repo-ontology init                    # ontology.config.json skeleton
npx @ebowwa/repo-ontology build --format all      # deterministic artifacts
npx @ebowwa/repo-ontology build --check           # CI drift gate (byte-exact)
npx @ebowwa/repo-ontology query search "SupervisorAdapter"
npx @ebowwa/repo-ontology graph --edge-kinds imports | dot -Tsvg -o graph.svg

Languages

| language | engine | notes | | --- | --- | --- | | Python | tree-sitter | module-name import resolution via python.roots | | TypeScript / TSX / JS | tree-sitter | specifier resolution via codegen-kit | | Swift | tree-sitter | module imports → dir-typed edges (swift.modules or inferred) | | C / C++ | tree-sitter | quoted includes resolved against the scan set | | ObjC | tree-sitter | .m disambiguated from MATLAB by content probe | | MATLAB | regex | no grammar in tree-sitter-wasms — disclosed in stats.engineFallbacks |

Missing grammars degrade per-language to regex, never crash a build, and are disclosed. --strict flips fallbacks to errors.

Artifacts (--format json|compact|md|all)

| file | consumer | | --- | --- | | ontology.json | full repo.ontology/v1 document — query/graph/validate operate on it | | ontology.txt | agent-compact tier, the fixed LLM-context contract (docs) | | dictionary/<language>.md | human-readable symbol tables |

Deterministic by construction: no timestamps or absolute paths, sorted arrays, byte-identical rebuilds — so build --check is plain byte equality.

Edges

• imports — resolved in-repo file→file (swift: file→dir); externals dropped
• exports — file→symbol for externally visible symbols
• refs — symbol→symbol usages, scope-stack resolution (~85% precision by design, no type checker; same-language unique-name fallback)
• provenance — declarative cross-language edges from ontology.config.json, e.g. Swift mirrors generated from Python contracts

API

import { buildOntology, OntologyIndex, loadOntology, toModuleGraph } from "@ebowwa/repo-ontology";

const ontology = await buildOntology(root, { config });
const index = new OntologyIndex(ontology);
index.search("TensorSpec");            // ranked symbol search
index.refsOf("src/spec.py#TensorSpec"); // who uses it, what it uses
toModuleGraph(ontology);               // feed codegen-kit shapes/probes/drift

Docs

• Artifact schema — repo.ontology/v1
• Agent-compact format — the ontology.txt contract
• Adding a language — one subclass + a defs table

Development

bun install && bun run typecheck && bun test && bun run build
node scripts/dump-tree.mjs <language> <file>   # CST dumper for grammar onboarding

License

MIT