Metamodel

The trait-based, multi-language code metamodel (FamixNG lineage). Every concept is described with its attributes and its relations to other concepts.

METAMODEL.md in the repository is the canonical source for these pages. Its executable form is @codegraph/core (Zod schemas) and the generated schemas/ contract; where the document and the code disagree, the code is authoritative.

Pages

Page	Concepts
Identity	the natural key, rendered ids, `SourceAnchor`, `Space`, `CodeFile`
Traits	the closed trait vocabulary and the attributes each contributes
Edges	the single relationship concept and its eleven kinds
Provenance	the four values that qualify how a dependency is known
Profiles	what a language profile is, and the validity rule
Stubs	degraded entities for what the corpus does not declare
Measures and literals	`TMetrics` and the `Literal` union

The nine shipped profiles are rendered on Language profiles.

Concept map

    graph TB
  subgraph Model["Model (one extraction run)"]
    E[Entity]
    ED[Edge]
  end
  P[Language Profile] -- "licenses kinds & trait\ncompositions, edge kinds" --> E
  P -- licenses --> ED
  T[Trait] -- "composes into\n(traits set)" --> E
  ED -- "from / to" --> E
  A[SourceAnchor] -- "evidence on" --> E
  A -- "evidence on" --> ED
  PR[Provenance] -- "qualifies" --> ED
  CF[CodeFile] -- "definedIn / anchors" --> E
  S[Stub] -- "degraded Entity\n(isStub = true)" --> E

Entity

The single node concept. There is no entity class hierarchy: an entity is a kind plus a sum of traits, and each trait contributes attributes.

Attribute	Type	Always present	Meaning
`id`	EntityId	yes	the natural key, rendered — compared, never parsed
`kind`	string	yes	language-profile-defined classification (`class`, `method`, `function`, `namespace`, …)
`traits`	TraitName[]	yes	the capabilities this entity composes
`space`	Space[]	no	TypeScript-family only
(trait keys)	—	per trait	every trait in `traits` contributes its keys

Validity (per the owning language profile): required(kind) ⊆ traits ⊆ required(kind) ∪ optional(kind), and every declared trait’s keys are present and well-typed.

Relations: composed of traits; source or target of edges; classified and licensed by a language profile; may be a stub.

The model

The unit of exchange between an extractor and the analyzer: the result of one extraction run. Its content is format-independent.

Attribute	Type	Meaning
`schemaVersion`	semver string	version of the interchange contract
`lang`	string	profile id of the extractor
`extractor`	`{name, version, ...flags}`	provenance of the model itself (e.g. `noClasspath: true`)
`root`	string	analyzed source root (anchors are relative to it)
`repository`	`{remote, commit, root, provider?}`	optional — where the analyzed root lives in a hosted repository
`entities`	Entity[]	all nodes, stubs included
`edges`	Edge[]	all relations, outgoing direction

repository records provenance of the corpus, as facts:

Field	Meaning
`remote`	normalized https clone URL (`https://github.com/google/gson` — never the ssh form, never trailing `.git`)
`commit`	the sha the corpus was extracted at — a permalink; a branch name moves and is not a fact
`root`	path of the analyzed root relative to the repository root; anchors are relative to the analyzed root, which may sit below it
`provider`	`github` \| `gitlab`, only when the hostname does not say (self-hosted)

The blob URL of a particular host is a projection consumers derive, never serialized.

Integrity properties

Whatever encodes it, a model satisfies:

closure — every reference resolves to a declared entity or a stub, the ids inside Literal values included;
no self-reference — from ≠ to on every edge;
provenance set on every edge, from the closed set;
profile validity for every entity;
natural-key uniqueness — no two entities share (lang, module, symbol, disambiguator);
canonical order — entities and edges sorted by natural key, so two runs over one corpus are diffable.

A model conforms to exactly one language profile; multi-language analysis is the union of models, queried through profile intersection. The interchange encoding is model.jsonl; the derived cache is model.db.

Reified impl block

A block like impl Display for Order attaches to two entities and owns methods, so it is reified as an anonymous entity:

traits: [TWithChildren, TAttachedTo, TSourceAnchor] — no TNamed;
attachedTo → the type (Order);
the interfaceImplementation edge Order → Display takes the block as its anchor;
its methods are its children.

Derived concepts

Computed by the analyzer from the stored model; part of the vocabulary even though no encoding stores them.

Concept	Derived from	Definition
Incoming indexes	all edges	callers-of, importers-of, subtypes-of, accessors-of — inverse of stored outgoing edges
Children index	`parent`	children-of — the inverse of the stored containment link
Type-level dependency graph	all edge kinds	edges folded up to the containing `TType` entities
Module import graph	`import` edges	the cross-language comparison layer
Coupling metrics	folded graphs	fan-in/fan-out, afferent/efferent coupling, instability
Cycles	folded graphs	strongly connected components at module or type level
Tangle / minimum feedback set	folded graphs	per-SCC minimal weighted edge set whose removal leaves the component acyclic; tangle metric = feedback references / cyclic references
Internal view	`isStub`	model minus stubs and their edges
Facts-only view	`provenance`	model restricted to `declared` edges
Source links	`repository` + anchors	per-anchor host permalink — `{remote}/blob/{commit}/{root}/{file}#L{s}-L{e}` on GitHub, `{remote}/-/blob/{commit}/{root}/{file}#L{s}-{e}` on GitLab; template chosen by hostname, `provider` overriding
Framework roles	`annotationUse` edges + a framework profile	stereotype classification of types and identification of injection points
DI wiring	injection points + the interfaceImplementation inverse index	`dynamic-candidate` edges from a consumer to every corpus implementation of the injected interface

Last updated on September 21, 2026