Requirements Specification

1. Purpose

Define normative requirements for meta-ast, a standalone Rust static analyzer for polyglot source trees. The tool extracts symbol surfaces, builds cross-file dependency graphs, and computes SCCs. MetaCall FaaS deployment manifest generation is an optional capability behind the metacall-deploy feature flag.

2. Functional requirements

FR-1: Parsing and language support

The analyzer shall parse source files for a growing set of languages, starting with:

• Python
• JavaScript
• TypeScript (including TSX)
• C
• C++
• Rust
• Go

Additional languages (C#, Java, and others) are planned in later phases.

FR-2: Symbol extraction

The analyzer shall extract top-level symbols and language-appropriate nested symbols into a normalized intermediate representation:

• Functions
• Classes / structs / interfaces / traits
• Objects (constants, globals, module-level bindings)

FR-3: Dependency graph

The analyzer shall construct a directed graph of symbol-level dependencies:

• File import/usage edges
• Intra-project symbol references
• Cross-language reference candidates

FR-4: SCC and Deployment Unit identification

The analyzer shall compute Strongly Connected Components (Tarjan) and annotate each SCC as a Deployment Unit, classifying it as:

• Independent (acyclic, Function Mesh separation candidate)
• Co-deployment required (cyclic, must remain grouped)

FR-5: Incremental updates (Planned)

The analyzer is designed to support update workflows from file changes with a target incremental response of under 100ms for files below 5k LOC. Note: This is planned for Phase 4 of the roadmap and is not yet implemented.

FR-6: CLI and library modes

The project shall expose:

• Rust library interface
• CLI entrypoint for project analysis and output emission

FR-7: C ABI (Planned)

The project will provide a stable C ABI header (mc_ast.h) for embedding scenarios in a later phase.

FR-8: Datagraph export (Planned)

The project will support exporting a datagraph model suitable for external graph sinks (including Dgraph) in a later phase.

FR-9: Deploy Manifest generation (feature-gated: metacall-deploy, Implemented)

When built with --features metacall-deploy, the deploy subcommand:

• Scans source files for cross-language call sites (metacall_load_from_file, metacall_load_from_memory, metacall_load_from_package, metacall_load_from_configuration)
• Extracts (language_tag, script_paths[]) pairs from call-site arguments
• Partitions files into same-language pods via Union-Find over dependency edges
• Resolves external dependencies per-language from lockfiles and package manifests
• Generates a pod manifest (metacall.pods.json) with per-pod deployments, inter-pod edges with fused confidence scores, and scoped dependency lists with pinned versions
• Inlines referenced metacall_load_from_configuration targets when present; emits low-confidence annotations for computed/dynamic arguments
• Runs fairness checks when --check is passed: every cut edge must have a corresponding RPC stub entry in the manifest

FR-10: Mesh Annotation (feature-gated: metacall-deploy, Implemented)

When built with --features metacall-deploy, the deploy subcommand also emits metacall.mesh.json containing:

• SCC-derived deployment units with constituent symbol lists
• Cross-language boundary flags per unit
• Independent mesh candidate classification per unit
• Cross-language edges with call-site file attribution

3. Non-functional requirements

NFR-1: Correctness

Incorrect symbol labeling is a high-severity defect. Correctness takes priority over throughput.

NFR-2: Resilience

Malformed source files shall not crash analysis. Partial extraction shall be allowed when parser recovery is possible. Unresolvable Cross-Language Call Site arguments (dynamic values) shall be annotated, not silently discarded.

NFR-3: Portability

Build and test shall pass on Linux, macOS, and Windows.

NFR-4: Determinism

Given identical input set and tool version, emitted output shall be deterministic.

NFR-5: Observability

The implementation shall provide structured diagnostics suitable for CI and local debugging.

4. Acceptance criteria

1. Parse all supported languages and emit valid symbol JSON.
2. Correct SCC identification for multi-language project fixtures.
3. CI pipeline green on Linux/macOS/Windows.
4. (Planned) Incremental-update target under 100ms for files below 5k LOC.
5. (Planned with metacall-deploy) Deploy Manifests generated match expected fixtures for all example projects in tests/fixtures/mixed/.
6. (Planned with metacall-deploy) Mesh Annotation correctly classifies Deployment Units for the auth-function-mesh fixture.

5. Out-of-scope for MVP

• Incremental watch-mode and C ABI embedding (post-MVP).
• metacall-deploy manifest/mesh generation and --check mode (post-MVP).
• Dgraph sink/export adapter (post-MVP).
• Full inter-procedural global dataflow with alias analysis.
• Sound cross-language type inference.
• Mandatory online graph database dependency.
• Dynamic Cross-Language Call Site resolution (runtime tag/path values).

6. Versioning policy

Breaking changes to output schema or graph semantics require:

1. ADR update.
2. Traceability matrix update.
3. Migration note in roadmap/changelog.