Skip to content

analysis-ir.org

Latest commit

 

History

History
100 lines (80 loc) · 4.66 KB

analysis-ir.org

File metadata and controls

100 lines (80 loc) · 4.66 KB
Raw

Analysis IR v1

Scope

astdiff.analysis.v1 is a deterministic, language-neutral analysis profile for one source artifact. The first producer is the JavaScript tree-sitter adapter. It records the complete syntax-tree shape, lexical scopes, nested bindings, lexical references, def-use resolution, static call shape, source identity, producer identity, and explicit loss records.

Symbols are lexical bindings. Property names, including class method names, remain syntax nodes and call properties rather than lexical symbol rows.

The profile is an in-memory analysis contract. It is separate from the legacy comparison dump and is not yet a portable interchange format. In particular, v1 does not perform temporal-dead-zone or flow-sensitive resolution, infer member/dynamic call targets, infer cross-version lineage, or record matcher fingerprint evidence. Each omission is represented by a machine-readable loss record.

Identity and ordering

All rows are emitted in deterministic order. Node rows use syntax-tree pre-order. Scope rows are ordered by depth, span, kind, and the source adapter’s deterministic scope key. Symbol rows are ordered by scope and declaration position. References are grouped by resolved symbol and then by source position, making each symbol’s neighborhood contiguous. Calls are ordered by source position.

Rows use u32 indexes for relationships inside one artifact. These indexes are not durable identities. SHA-256 IDs use length-delimited, domain-separated inputs:

  • Node ID: parent row, child ordinal, node-kind bytes, and node flags.
  • Scope ID: parent row, language-neutral scope kind, depth, and byte span.
  • Symbol ID: binding node ID and language-neutral symbol kind.
  • Reference ID: identifier node ID and read/write/call role.
  • Def-use ID: reference ID, resolved symbol ID (or zero), and resolution kind.
  • Call ID: call node ID, call kind, callee/target identities, and property row.

Symbol spelling and absolute span are deliberately absent from the symbol ID, so a same-shape rename does not change it even when spelling width changes. These IDs are artifact-local structural identities, not a promise of cross-version lineage. Insertions that move spans may change them. Cross-version matching and propagated identities belong to the later lineage pass.

In-memory model and validation

Analysis::from_javascript(source, tree) produces deterministic row tables:

  • Metadata records the profile, producer, language, front-end, source digest, and source length.
  • A shared UTF-8 string table holds interned strings.
  • Nodes contain parent, child ordinal, kind, byte span, and flags.
  • Scopes contain parent, kind, depth, and byte span.
  • Symbols contain declaration-node, scope, name, kind, and contiguous reference-range fields.
  • References contain identifier-node, scope, name, and lexical operation role.
  • Def-use edges contain reference/symbol rows and explicit resolved, unresolved, or ambiguous status.
  • Calls contain call-node, optional callee reference, optional target symbol, optional member property, and call-shape kind.
  • Losses contain stable codes and explanatory messages.

Validation checks row references, parent ordering, stable IDs, symbol reference ranges, def-use consistency, and source-span bounds. Source artifacts must fit the profile’s 32-bit byte-span address space. The model is an unreleased development contract, without a persisted-artifact migration promise.

Comparison and analysis share lexical scope resolution; comparison normalizes resolved bindings without materializing the full analysis tables. Lineage matches artifacts through structural evidence; naming records approved display labels against validated identities. Neither requires a cache.

Experimental persistence

Isoform-backed positioned analysis and source-map caches, their schemas, and the analyze, analysis, and map cache* commands are maintained on the separate isoform-cache branch. That branch requires the joint-development Isoform checkout. Master has no Isoform dependency and builds from a standalone checkout. Packaging and reintegration of the cache remain deferred.

Commands and verification

The analysis model is consumed directly by the library and these commands:

astdiff lineage old.js new.js --output old-to-new.lineage.json
astdiff names export old.js --output old.names.json
astdiff names validate old.names.json --source-file old.js
tools/benchmark-lineage.sh old.js new.js 3
tools/check.sh

Tests cover deterministic model generation, patterns/imports, lexical shadowing, assignment roles, property boundaries, call shapes, identity validation, lineage, and semantic-name review and propagation.