Ontoly

Validation Lab npm install License: AGPL-3.0 TypeScript

Ontoly is a JavaScript- and TypeScript-native software intelligence engine that turns source code into a deterministic Software Graph.

Developer tools should not have to rediscover the same repository structure over and over. Ontoly builds one shared semantic representation that agents, MCP servers, SDK generators, documentation tools, architecture tools, static analysis, and IDEs can query without repeatedly searching files or rebuilding partial AST context.

Ontoly builds understanding. It does not answer questions, call language models, generate embeddings, or make probabilistic guesses.

Status

Ontoly v1.0.0 is the first stable release. Current release: v1.2.0.

The public contract is frozen, and the repository includes:

• a Software Graph specification
• a deterministic compiler pipeline
• a JavaScript and TypeScript semantic frontend powered by the TypeScript Compiler API
• a query engine
• MCP capabilities
• deterministic Enhancers for artifact generation
• a derived Semantics artifact for feature ownership, intent vocabulary, and concept graphs
• a derived History artifact for ownership, hotspots, co-changes, churn, and drift
• portable Agent Skills
• validation and semantic evaluation infrastructure
• release gates for docs, packaging, skills, examples, and regression checks

Links

• Website: ontoly.xyz
• Docs: ontoly.xyz/docs
• Agent Skills Catalog: ontoly.xyz/docs/skills
• Enhancers: ontoly.xyz/docs/enhancers
• Repository: github.com/0xsarwagya/ontoly
• Changelog: CHANGELOG.md
• Roadmap: ROADMAP.md
• Architecture: ARCHITECTURE.md
• RFC index: RFC_INDEX.md
• Governance: GOVERNANCE.md
• Third-party notices: THIRD_PARTY_NOTICES.md
• HOL Guard: HOL Guard

What Ontoly Is

Ontoly is the semantic layer between a software repository and every tool that needs to understand it.

Repository
  -> Compiler Frontends
  -> Semantic Model
  -> Software Graph
  -> Enhancers
  -> Semantics
  -> Query Engine
  -> MCP, Skills, SDKs, Docs, IDEs, Analysis

The Software Graph is the product. Everything else is a consumer, plugin, pass, or validation layer around it.

What Ontoly Is Not

• Not a chat interface.
• Not a coding agent.
• Not a copilot.
• Not vector search.
• Not an embeddings pipeline.
• Not hosted SaaS.
• Not a code generator by default.
• Not a replacement for TypeScript, ESLint, or test suites.

AI tools can consume Ontoly through MCP and Skills, but the graph never depends on AI output. Every LLM-facing use of Ontoly must go through LLM Enhancement so graph evidence, confidence, and fallback rules stay explicit.

Why Software Graphs

Most developer tools redo the same expensive work:

• agents search files
• documentation tools parse symbols
• architecture tools rebuild dependency graphs
• SDK generators infer API shapes
• static analyzers rebuild call and import relationships

Ontoly turns that repeated work into a reusable graph:

• deterministic IDs
• graph-native diagnostics
• explicit provenance
• stable serialization
• query indexes
• semantic concept indexes
• validation reports
• extension metadata

The goal is simple: every tool that needs software understanding should first ask whether Ontoly already knows.

Quick Start From Source

Use this path when building from source.

git clone https://github.com/0xsarwagya/ontoly.git
cd ontoly
corepack enable
pnpm install --frozen-lockfile
pnpm build

Build a graph for the included basic example:

pnpm ontoly build examples/basic

Inspect generated artifacts:

ls examples/basic/ontoly-output
pnpm ontoly inspect src/service.ts --root examples/basic
pnpm ontoly search UserService --root examples/basic
pnpm ontoly impact UserService --root examples/basic
pnpm ontoly stats examples/basic

Run the main release gates:

pnpm check-types
pnpm test
pnpm docs:check-links
pnpm skills:validate
pnpm validate:packages

Run the full gate before a release:

pnpm release:gates

Package Install

The public package names are scoped under @0xsarwagya.

Install with:

pnpm add -D @0xsarwagya/ontoly-cli
pnpm exec ontoly build .

In an interactive terminal, ontoly build without a path asks which folder to index. Press Enter for the current directory, paste a relative, absolute, or ~/ path, or pass the path explicitly:

pnpm exec ontoly build
pnpm exec ontoly build apps/api
pnpm exec ontoly build --no-prompt

If npm is unavailable in your environment, use the source checkout flow above.

Build Artifacts

ontoly build <repository> writes the rich ontoly-output/ bundle by default:

ontoly-output/
  SoftwareGraph.json
  manifest.json
  coverage.json
  quality.json
  semantic-model.json
  reports/
    architecture.json
    api.json
    dependencies.json
    configuration.json
    frameworks.json
    workspace.json
  nodes/
    all.json
    by-type/
  relationships/
    all.json
    by-type/
  communities/
    communities.json
    community-000.json
  html/
    graph.html
    architecture.html

The output bundle is deterministic and intended for humans, agents, websites, release artifacts, and debugging Ontoly's own understanding.

For the compact cache-style artifact directory, pass --output .ontoly:

ontoly build . --output .ontoly

.ontoly/
  SoftwareGraph.json
  diagnostics.json
  indexes.json
  metadata.json
  statistics.json

The JSON graph is the canonical serialization format. Binary formats are intentionally out of scope until the Software Graph specification is stable.

Remote repositories can be compiled directly:

ontoly build --remote https://github.com/0xsarwagya/ontoly.git
ontoly output --remote [email protected]:0xsarwagya/ontoly.git

Remote builds clone into a temporary checkout, write relative output paths into the directory where you ran Ontoly, and record the git URL in the output manifest.

Software Graph

The Software Graph is a versioned JSON model containing:

• repository metadata
• nodes
• edges
• diagnostics
• indexes
• statistics
• provenance
• extension metadata

Core node families include modules, packages, functions, methods, classes, interfaces, type aliases, enums, routes, controllers, services, providers, configuration, environment variables, events, and resources.

Core relationship families include IMPORTS, EXPORTS, CONTAINS, CALLS, DEPENDS_ON, USES, READS, WRITES, IMPLEMENTS, EXTENDS, HANDLES, MOUNTS, INJECTS, AUTHORIZES, REGISTERED_IN, PUBLISHES, and SUBSCRIBES.

Read the canonical spec in RFC-0001.

Deterministic IDs

Ontoly assigns stable IDs so graph output can be cached, diffed, tested, and compared across builds.

Examples:

module:src/auth/service.ts
fn:src/auth/service.ts:login
class:src/auth/user-service.ts:UserService
route:POST:/login
model:User

IDs should survive rebuilds whenever the semantic identity survives.

Compiler Pipeline

The compiler is a deterministic multi-stage pipeline:

Repository Discovery
  -> Frontend Parsing
  -> Symbol Emission
  -> Semantic Model Generation
  -> Relationship Extraction
  -> Graph Construction
  -> Diagnostics
  -> Validation
  -> Indexing
  -> Serialization

Compiler frontends emit structured facts. The compiler owns graph construction. This keeps parser packages small and keeps graph compatibility centralized.

Read the architecture in RFC-0002.

Query Engine

The query engine provides deterministic graph reasoning primitives:

• lookup by ID, name, type, file, and tag
• neighborhood expansion
• graph walks
• dependency traversal
• caller and callee lookup
• path finding
• impact analysis
• filtering
• pattern matching
• index-backed traversal

Read the query design in RFC-0003.

Example:

import { buildSoftwareGraph } from "@0xsarwagya/ontoly-compiler";
import { createQueryEngine } from "@0xsarwagya/ontoly-query";

const graph = await buildSoftwareGraph({ root: process.cwd() });
const query = createQueryEngine(graph);

const services = query.services();
const callers = query.callers("fn:src/auth/service.ts:login");
const dependencies = query.dependencies("class:src/auth/user-service.ts:UserService");

CLI

The source checkout exposes the CLI through the root ontoly script:

pnpm ontoly --help

Common commands:

Command	Purpose
pnpm ontoly build <repo>	Build a Software Graph.
pnpm ontoly output <repo>	Generate ontoly-output/ with JSON reports, graph communities, and HTML explorers.
pnpm ontoly inspect <graph-or-query>	Inspect graph artifacts or entities.
pnpm ontoly search <concept>	Resolve natural concepts to ranked graph entities.
pnpm ontoly find <concept>	Find symbols, acronyms, features, or configuration terms.
pnpm ontoly locate <feature>	Locate feature-level graph touchpoints.
pnpm ontoly evidence <query>	Generate a compact graph-backed Evidence Pack for agents and reviews.
pnpm ontoly semantics build <repo>	Generate the derived Semantics artifact and concept graph.
pnpm ontoly history build <repo>	Generate repository history, ownership, hotspot, co-change, and drift artifacts.
pnpm ontoly ownership <symbol>	Inspect deterministic Git-derived repository ownership.
pnpm ontoly hotspots	List high-churn/high-modification graph hotspots.
pnpm ontoly trace <symbol>	Trace graph relationships.
pnpm ontoly coverage <repo>	Report semantic coverage.
pnpm ontoly mcp	Start MCP capabilities.
pnpm ontoly skills list	List packaged Agent Skills.
pnpm ontoly skills validate	Validate skill metadata, links, templates, and examples.
pnpm ontoly validate all	Run the validation lab.
pnpm ontoly evaluate	Run semantic evaluation.
pnpm ontoly leaderboard	Generate semantic leaderboard output.
pnpm ontoly benchmark performance	Run performance benchmark reporting.
pnpm ontoly diff base.graph head.graph	Deterministic Software Graph diff per RFC 0005.

See docs/cli.md and docs/reference/cli.mdx.

MCP

Ontoly MCP exposes structured capabilities over the Software Graph. Capabilities validate inputs before execution and return structured diagnostics for missing, ambiguous, or unsupported requests.

When an LLM consumes Ontoly MCP responses, LLM Enhancement is mandatory. Non-LLM tools may call MCP directly, but LLM-generated answers must preserve Ontoly evidence, confidence, and fallback boundaries.

pnpm ontoly mcp --list
pnpm ontoly mcp

Representative capabilities:

• GraphStatistics
• ExplainArchitecture
• FindDependencies
• ImpactAnalysis
• TraceExecution
• FindConfigurationUsage
• FindAuthenticationFlow
• FindFeatureOwner
• SemanticContext

Every capability is deterministic and evidence-backed. Confidence is derived from graph evidence, not guessed.

See docs/mcp.md and docs/getting-started/mcp.mdx.

Agent Skills

Ontoly ships portable Agent Skills under skills. Skills teach coding agents how to use Ontoly before falling back to repository search.

Every official Skill declares ontoly.enhancement: "LLM Enhancement". This is mandatory for any LLM-capable agent using Ontoly, not an optional label.

Each Skill follows the same workflow:

1. Confirm the installed workflow declares LLM Enhancement.
2. Verify that an Ontoly graph exists.
3. Build one with ontoly build . if it is missing.
4. Check graph trust and diagnostics.
5. Use Ontoly MCP capabilities first.
6. Inspect source files only when the graph cannot answer.
7. Cite evidence and confidence in the final response.

Included Skills:

• architecture review
• impact analysis
• codebase onboarding
• request tracing
• dependency analysis
• security review
• configuration analysis
• framework analysis
• documentation
• refactoring
• performance analysis
• dead-code analysis
• migration analysis
• SDK generation

Validate the shipped Skills:

pnpm skills:validate
pnpm skills:validate-installed

Read the public Agent Skills Catalog, skills/SKILL_CATALOG.md, docs/agent-skills.md, and docs/skills-validation.md.

Validation Lab

Ontoly includes a permanent validation lab. It measures correctness, determinism, graph quality, semantic coverage, trust, diagnostics, performance, and regressions across real repositories and fixtures.

pnpm validate
pnpm evaluate
pnpm benchmark:performance

Validation outputs live under validation:

• repository registry
• per-repository reports
• semantic leaderboard
• regression baselines
• release gates
• performance reports
• website assets
• badges

Read docs/validation-lab.md and docs/semantic-evaluation-harness.md.

Release Evidence

The release evidence reports are generated artifacts from the local validation suite, not marketing claims.

Area	Evidence
Validation summary	validation/lab-summary.md
Semantic leaderboard	validation/semantic/leaderboard.md
Release gates	validation/release-gates/report.md
Skills evaluation	validation/skills/report.md

Packages

Package	Purpose
@0xsarwagya/ontoly-cli	CLI and public convenience API.
@0xsarwagya/ontoly-core	Software Graph schema, stable IDs, indexes, graph helpers, and Semantic Index APIs.
@0xsarwagya/ontoly-compiler	Repository discovery, graph build pipeline, validation, and watch mode.
@0xsarwagya/ontoly-parser-typescript	JavaScript and TypeScript frontend and relationship extraction.
@0xsarwagya/ontoly-parser-openapi	OpenAPI frontend for Software Graph facts.
@0xsarwagya/ontoly-typescript	Pure TypeScript semantic model analyzer.
@0xsarwagya/ontoly-semantic	Semantic generator and framework analyzer registry.
@0xsarwagya/ontoly-analyzers	Semantic coverage and graph quality analyzers.
@0xsarwagya/ontoly-query	Deterministic Software Graph query engine.
@0xsarwagya/ontoly-enhancer	Public Enhancer API for immutable graph artifact transformations.
@0xsarwagya/ontoly-enhancer-history	Deterministic History enhancer for ownership, hotspots, co-changes, churn, and architectural drift.
@0xsarwagya/ontoly-enhancer-semantics	Deterministic Semantics enhancer for feature ownership, vocabulary, neighborhoods, and concept graphs.
@0xsarwagya/ontoly-intelligence	Deterministic intelligence APIs over Software Graph, Semantic Index, Semantics, and History artifacts.
@0xsarwagya/ontoly-diagnostics	Shared diagnostic constructors.
@0xsarwagya/ontoly-cache	Local graph artifact persistence.
@0xsarwagya/ontoly-mcp	Structured graph capabilities for AI agents and tools.
@0xsarwagya/ontoly-plugin-mermaid	Example graph visualization plugin.
@0xsarwagya/ontoly-plugin-html	Interactive offline HTML graph visualization plugin.

Package names intentionally use @0xsarwagya/ontoly-*.

Repository Layout

packages/
  core/
  compiler/
  parser-typescript/
  parser-openapi/
  typescript/
  semantic/
  analyzers/
  query/
  diagnostics/
  cache/
  mcp/
  cli/
plugins/
  mermaid/
  html/
apps/
  site/          # ontoly.xyz — the canonical site
skills/
docs/            # Documentation source of truth (Markdown / MDX)
rfcs/
examples/
validation/

Examples

Runnable examples live in examples:

Example	Purpose
examples/basic	Small TypeScript graph build.
examples/typescript-library	Library-shaped TypeScript project.
examples/nestjs-api	Framework-style API structure.
examples/turborepo	Workspace and package graph behavior.
examples/cli-usage	CLI workflow examples.
examples/mcp	MCP capability usage.
examples/semantic-queries	Query engine examples.

Documentation Map

The root docs/ tree is the source of truth. The dedicated site ontoly.xyz is served from apps/site/ and renders those same docs — there is no separate mirror.

Start here:

• docs/index.mdx
• docs/getting-started/installation.mdx
• docs/getting-started/build-a-graph.mdx
• docs/getting-started/query-the-graph.mdx
• docs/getting-started/mcp.mdx
• docs/concepts/software-graph.mdx
• docs/concepts/compiler-pipeline.mdx
• docs/concepts/plugin-system.mdx
• docs/query-engine.md
• docs/typescript-semantic-model.md
• docs/framework-detection.md
• docs/agent-skills.md
• docs/skills-overview.md
• skills/SKILL_CATALOG.md
• docs/validation-lab.md
• docs/faq.md
• docs/troubleshooting.md

RFCs

Ontoly uses RFCs for changes affecting public graph, compiler, plugin, query, and type contracts.

• RFC-0001: Software Graph
• RFC-0002: Compiler Pipeline
• RFC-0003: Query Engine
• RFC-0004: Plugin and Compiler Pass System

Release Engineering

Release gates include:

• build
• typecheck
• tests
• package validation
• docs link checking
• markdown style checking
• license checking
• skill validation
• installed artifact skill validation
• npm pack validation
• clean first-user smoke
• validation lab
• semantic evaluation
• regression gates
• OSS site publication through .github/workflows/publish-site.yml

Run everything with:

pnpm release:gates

Known Limitations

• JavaScript and TypeScript are supported through one deterministic ECMAScript frontend.
• Some framework analyzers are intentionally partial.
• Binary graph formats are not implemented.
• Hosted SaaS, vector search, and LLM reasoning are non-goals.
• The Software Graph schema is stable as of v1.0.0.
• MCP capabilities only answer from available graph evidence.
• LLM-facing use requires LLM Enhancement; Ontoly itself remains AI-free.

Read docs/known-limitations.md.

Contributing

Contributions should preserve determinism and graph compatibility.

Before opening a pull request:

pnpm install --frozen-lockfile
pnpm build
pnpm check-types
pnpm test
pnpm release:gates

Public contract changes require an RFC first. See CONTRIBUTING.md.

Security

Please report security issues privately. See SECURITY.md.

Support

Use GitHub issues for bugs and GitHub discussions for design questions. See SUPPORT.md.

License

Ontoly is available under the GNU Affero General Public License v3.0. Commercial licenses are available for teams that need proprietary use, private modifications, commercial redistribution, hosted service use without AGPL obligations, or contractual terms.

For commercial licensing, contact [email protected]. See LICENSE, COMMERCIAL_LICENSE.md, CONTRIBUTOR_LICENSE_AGREEMENT.md, and TRADEMARK_POLICY.md.