Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

meta-ast Documentation

This directory contains the implementation-facing technical documentation for meta-ast.

The structure is intentionally traceable: specs -> architecture -> structure -> ADRs -> roadmap -> validation artifacts, so design decisions are easy to trace back to requirements and forward to tests.

Document map

  • ARCHITECTURE.md - system architecture, component boundaries, runtime flow, output formats, and the metacall-deploy feature layer.
  • STRUCTURE.md - code structure, data structures, design patterns, module layout, and implementation order.
  • DEPLOY.md - MetaCall deploy manifests: scanner, pod partitioning, mesh annotation.
  • DEV_CRATE_DECISIONS.md - crate selection rationale and trade-offs.
  • CI_CD.md - CI/CD architecture and quality gates.
  • ROADMAP.md - phase-aligned implementation milestones and measurable exit gates.
  • BENCHMARKS.md - criterion benchmark results for pipeline, graph, and incremental.
  • DEMO.md - recorded CLI walkthroughs (GIFs) aligned to the delivered artifacts.
  • FINAL_REPORT.md - GSoC 2026 completion report.

Specs

  • specs/requirements.md - normative requirements and acceptance criteria.
  • specs/graph-model.md - symbol graph and datagraph contracts, including language_id, project-root-relative path, snapshot_id, file_id, visibility, and DataNode semantics.
  • specs/symbol-extraction.md - language-pack extraction contracts.
  • specs/traceability.md - mapping from deliverables to implementation/docs/tests.

Architecture Decision Records (ADRs)

  • adr/0001-stateful-import-resolver.md - Stateful import resolver trait seam
  • adr/0002-scope-resolution-heuristics.md - Scope resolution heuristics
  • adr/0003-unresolved-import-policy.md - Unresolved import handling policy
  • adr/0004-global-scope-synthetic-symbols.md - Global scope synthetic symbol generation

Requests for Comments (RFCs)

  • rfcs/0001-language-loading-model.md - Language loading model
  • rfcs/0002-error-semantics-and-recovery.md - Error semantics and recovery
  • rfcs/0003-incremental-parsing-strategy.md - Incremental parsing strategy
  • rfcs/0004-graph-representation-and-scc.md - Graph representation and SCC
  • rfcs/0005-output-contract-policy.md - Output contract policy
  • rfcs/0006-type-inference-scope.md - Type inference scope
  • rfcs/0007-dgraph-integration-scope.md - Dgraph integration scope
  • rfcs/0008-graph-module.md - Graph module design
  • rfcs/0009-cross-file-dependency-mapping.md - Cross-file dependency mapping
  • rfcs/0010-deploy-manifests.md - MetaCall deploy manifests (superseded by the pod model)
  • rfcs/0011-metacall-client-api-support.md - MetaCall client call support: metacall() and the full invocation surface
  • rfcs/0012-polyglot-lsp-server.md - Polyglot LSP Server proposal: architecture, protocol, and deployment

Scope policy

  • MVP (must ship): symbol extraction, dependency graph + SCC/Deployment Unit analysis, cross-platform CI.
  • metacall-deploy feature: Cross-Language Call Site detection, Deploy Manifest generation, Root Manifest assembly, Mesh Annotation from SCC.
  • Stretch: intra-procedural dataflow beyond simple def-use, live Dgraph sink, advanced cross-language type matching, expanded language support.

Update policy

When implementation changes any public contract (schema, CLI behavior, graph semantics, language support), update the corresponding file in this directory in the same pull request.