Codegraph
Inspect TypeScript projects. Verify module contracts.
Inspect a project · Explore the API · Module contracts
Inspect a project
Use an existing tsconfig.json. No .spec/ required. Install with pnpm add @astrale-os/codegraph.
import { openTypeScriptProject } from '@astrale-os/codegraph/analysis/typescript'
await using project = await openTypeScriptProject({ root: '.' })
await project.refresh()
await using code = await project.open()
const calls = await code.calls({ paths: ['src/routes.ts'] })
console.log({
completeness: calls.completeness,
calls: calls.sites.map(({ path, occurrence, call }) => ({
path,
span: occurrence.span,
origin: call.targetOrigin,
arguments: call.arguments,
dynamic: call.dynamic,
})),
})
Calls include unresolved sites. Coverage is complete, partial or unavailable.
Navigate symbols, find usages and module dependents without extracting bodies
await using navigation = await openTypeScriptProject({
root: '.', capabilities: ['typescript.source', 'typescript.structure'],
})
await navigation.refresh()
await using snapshot = await navigation.open()
const structure = await snapshot.structure()
// A cursor or diagnostic provides the file and its UTF-16 offset.
const selected = await structure.symbolAt({ path: 'src/routes.ts', offset: 120 })
console.log(selected.target, selected.symbols) // Canonical symbols + declaration files/spans.
console.log(await structure.references({ target: { path: 'src/routes.ts', offset: 120 } }))
console.log(await structure.references({
target: { path: 'src/api.ts', name: 'route' },
}))
console.log(await structure.dependents({ path: 'src/api.ts', transitive: true }))
structure.symbolAt({ path, offset, revision?, signal? })
structure.exports({ path })
structure.references({ target, paths?, includeDeclarations?, signal? })
structure.dependencies({ paths?, signal? })
structure.dependents({ path, transitive?, signal? })
target: { path, offset, revision? } · { path, name } · { symbol } · { origin }
Aliases resolve to their compiler symbol; positions also select local and private bindings. Results retain revision-specific locations, contributing facts and explicit coverage. An expected revision rejects stale cursors. The scope is loaded project-owned sources, excluding .d.ts; computed requests stay uncertain. Structural inspection, position semantics and tracked reuse.
Follow values through helpers and closures
For a project using a library such as @acme/http:
// src/routes.ts
import { route } from '@acme/http'
const health = (status: number) => ({
path: '/health',
handler: () => ({ status }),
})
route(health(200))
Continue with the same snapshot:
import { mapValueResult } from '@astrale-os/codegraph/analysis/typescript'
const values = await code.values()
for (const { call } of calls.sites) {
if (call.targetOrigin?.package !== '@acme/http'
|| call.targetOrigin.path.join('.') !== 'route') continue
const argument = call.arguments[0]
if (argument === undefined) continue
const status = await values.value(argument)
.property('handler').invoke().property('status').resolve()
console.log(mapValueResult(status, value =>
value.kind === 'literal' ? value.value : null))
// { kind: 'known', value: 200, evidence: [...] }
}
Values retain known, unknown, ambiguous and unsupported outcomes and their evidence. An unknown value or incomplete empty inventory does not establish absence. Authored JavaScript is analyzed without executing it. Library rules also establish callee identity; declaration origins select calls to inspect.
Keep the project open across edits
// After the file watcher reports an edit:
const update = await project.refresh({ changed: ['src/routes.ts'] })
await using current = await project.open()
console.log(update.durationMs, await current.calls({ paths: ['src/routes.ts'] }))
// Or let the compiler discover source, config and resolution changes:
await project.refresh({ discover: true })
Open a new snapshot after refreshing. Earlier readers stay pinned to their version. After the initial load, bare refresh() does not scan the filesystem.
Reuse a semantic computation across edits
Keep the callback stable; pass variable parameters through input.
import type { TypeScriptSemanticReader } from '@astrale-os/codegraph/analysis/typescript'
async function inspectCalls(read: TypeScriptSemanticReader, input: { paths: string[] }) {
const calls = await read.calls({ paths: input.paths })
return {
completeness: calls.completeness,
calls: calls.sites.map(({ path, occurrence, call }) => ({
path, span: occurrence.span, origin: call.targetOrigin, dynamic: call.dynamic,
})),
}
}
const report = await current.compute(inspectCalls, { paths: ['src/routes.ts'] })
Reports can be reused when their observed inputs still hold, including across unrelated edits. Return plain data; callback readers and value plans expire when it settles. Values, budgets and reuse.
Values, library models and evaluation budgets
snapshot.values({ call, limits })
values.value(occurrence).property(name).invoke().resolve({ limits, signal })
values.evaluate(occurrence, { signal? })
values.canReuse(proof)
mapValueResult(result, project, { equals })
limits: maximumDepth · maximumSteps · maximumAlternatives
results: known · unknown · ambiguous · unsupported
call(context)
context.callee() · context.receiver() · context.argument(index)
context.propertyName
operand.property(name) · operand.invoke() · operand.resolve()
model result: atom · unknown · transferred operand · undefined (ordinary evaluation)
Models can describe a library boundary while preserving bindings, closures and proof dependencies. Model operands resolve synchronously within the active call. Complete guide · Interfaces.
Facts, types, dependencies and control flow
snapshot.facts.facts(kind, filter?, page?)
snapshot.facts.factsById(kind, ids)
snapshot.facts.export(kind, filter?)
snapshot.facts.exportAll(filter?)
fact kinds: project · diagnostic · source · symbol · occurrence · structure · body
body-demand · module · declaration
body: occurrences · relations · blocks · edges · definitions · calls · summary
call: target · targetOrigin · signature · receiver · typeArguments
arguments · bindings · callbacks · dynamic
Source, symbol, occurrence and body capabilities are enabled by default. Other facts need explicit capabilities. Structural references and file dependencies use typescript.structure; logical module surfaces, dependencies and types use module boundary descriptors.
Project options · Fact readers and payloads · Calls and body IR · Module descriptors.
Storage, repository tools and custom analysis
@astrale-os/codegraph/analysis
createMemoryAnalysisStore · selectAnalysisStore
planPasses · runPortablePasses · runAnalysisPolicies
createNodeSourceTextReader · readVerifiedSourceText
createProcessNativeAnalysisSessionFactory
@astrale-os/codegraph/analysis/sqlite
createSQLiteAnalysisStore
@astrale-os/codegraph/repository
createNodeRepositoryScanner · inventoryRepository · repositoryFacts
analyzeRepositoryStatistics · refreshRepositoryStatistics
createRepositoryPathOwnershipGrouping · createRepositorySourceService
@astrale-os/codegraph/analysis/native
openNativeDecisionSession · resolvePackagedNativeAnalysis · resolvePackagedNativeOxlint
preloadNativeArtifacts({ generic?, signal? })
@astrale-os/codegraph/analysis/typescript
openCapturedTypeScriptReader(source, capture, { capabilities?, signal? })
Use memory by default; supply a caller-owned store for custom retention or persistence. Repository tools inventory, classify, group and measure files. Native decision sessions support specialized tool integrations. All exports, including types.
Captured readers reuse a native session's compiler and fact owner. Their default capabilities are source and body demand; structural reads require an explicit capability. Capture stamps and leased readers.
Explore the API
Import the entrypoint for the task. The root package exposes the module-contract application service.
| Task | @astrale-os/codegraph entrypoint |
|---|---|
| Inspect TypeScript, resolve values, reuse observations | /analysis/typescript |
| Compose passes and policies; store/query facts | /analysis |
| Persist facts in SQLite | /analysis/sqlite |
| Integrate native decision sessions | /analysis/native |
| Inventory repositories, measure source, read evidence | /repository |
| Author capabilities, laws, states and other contracts | /authoring |
| Compile specifications and derive capability status | /specification |
| Compose contract conformance profiles | /conformance |
| Validate schemas and data | /schema |
| Refresh and inspect a module-contract application | root |
| Persist workspace checkpoints | /workspace |
Complete export inventory — every function, class, constant and type, with links to exact interfaces.
Verify module contracts
Optional and independent of the inspection workflow. Conformance connects authored contracts to implementation analysis.
cg init modules/payments
// modules/payments/.spec/api.d.ts
export interface Payment { id: string; amount: number }
export declare function charge(amount: number): Promise<Payment>
cg check . # Validate contracts and composition
cg verify . --require-pass # Once the implementation is bound to its contract
cg dev . --open # Browse contracts, source and diagnostics
cg check checks specification validity; cg verify checks implementation conformance. Contracts may exist before implementation. Contract reference.
Bind an existing implementation to its contract
Export contract-owned types and implement the declared API:
// modules/payments/index.ts
import type { Payment } from './.spec/api.js'
export type { Payment } from './.spec/api.js'
export async function charge(amount: number): Promise<Payment> {
return { id: 'receipt', amount }
}
// modules/payments/implementation.contract.ts
import type * as contract from './.spec/api.js'
import * as implementation from './index.js'
implementation satisfies typeof contract
Keep both files in the owning TypeScript project. verify also checks the public surface in both directions; the satisfies check alone is not conformance. Implementation discovery and binding.
Daily CLI: selection, changed modules, evidence and live verification
cg --version
cg preload --viewer # Prepare native analysis + viewer for offline use
cg check . --select modules/payments --exclude generated --format json
cg check . --require-complete-layout --require-exact-layout --require-law-evidence
cg changed . origin/main
cg changed . origin/main --scope-only
cg test modules/payments --root .
cg test changed origin/main --root .
cg verify . --select modules/payments --schema-root schemas --require-pass --details
cg dev . --port 5173 --open --verify
changed is an advisory targeted check; use a full check as the global gate. test runs attached evidence through the project's test:file script. --quiet is available on check/changed/test/verify; --no-cache on check/changed/test/dev.
Add contract dimensions only as needed
.spec/
api.d.ts public contract
code.ts shared private entrypoints
internal.d.ts internal vocabulary
ports/**/*.d.ts required provider interfaces
capabilities/**/*.ts independently meaningful abilities
laws/**/*.ts falsifiable semantic truths
states/**/*.ts lifecycle transitions
flows/**/*.ts semantic orchestration
schemas/*.schema.json portable value representations
layout.ts physical paths and observation policy
limits.ts measured budgets
packages/*.ts reasons for external dependencies
examples/**/*.ts canonical public-API usage
benchmarks/**/*.ts workloads and metrics
architecture.md rationale and diagrams
icon.svg visual identity
defineCapability · defineLaw · defineState
transition · statesOf · eventsOf · transitionsOf · illegalTransitionsOf
defineCode · defineLayout · definePackage · definePackagePattern · defineBenchmark
Authoring API · Ownership, grammar and examples. Tests live outside .spec/; .history/ holds explanatory, non-normative context.
Build a contract application, compose profiles and persist checkpoints
createTypeSpecApplicationService(options)
service.refresh(options?) · service.current() · service.open(snapshot?)
service.settle() · service.dispose()
reader.query(universe) · reader.source(request) · reader.dispose()
compileSpecificationSnapshot · qualifySpecification · planConformance
createTypeSpecConformanceProfiles · createModuleConformanceProfiles
loadSchema · validateData · validateSchemaFile · validateModuleSchemaCatalog
createFileWorkspaceCheckpointStore
encodeWorkspaceCheckpointJson · decodeWorkspaceCheckpointJson
Node 22 (≥22.13), 24 or 26. One npm package; native binaries and the viewer download at first use, with a verified offline cache. Preload and distribution · Qualified artifacts.