// Copyright 2025 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package noder defines the Unified IR (UIR) export data format
// and provides utilities for reading and writing it.
package noder

/*
The Unified IR (UIR) format is implicitly defined by the package noder.

At the highest level, a package encoded in UIR follows the grammar
below.

	File        = Header Payload fingerprint .
	Header      = version [ flags ] sectionEnds elementEnds .

	version     = uint32 .     // used for backward compatibility
	flags       = uint32 .     // feature flags used across versions
	sectionEnds = [10]uint32 . // defines section boundaries
	elementEnds = []uint32 .   // defines element boundaries
	fingerprint = [8]byte .    // sha256 fingerprint

The payload is a series of sections. Each section has a kind which
determines its index in the series.

	SectionKind = Uint64 .
	Payload     = SectionString
	              SectionMeta
	              SectionPosBase
	              SectionPkg
	              SectionName
	              SectionType
	              SectionObj
	              SectionObjExt  // TODO(markfreeman) Define.
	              SectionObjDict // TODO(markfreeman) Define.
	              SectionBody    // TODO(markfreeman) Define.
	              .

# Sections

A section is a series of elements of a type determined by the section's
kind. Go constructs are mapped onto one or more elements with possibly
different types; in that case, the elements are in different sections.

Elements are accessed using an element index relative to the start of
the section.

	RelElemIdx = Uint64 .

## String Section

String values are stored as elements in the string section. Elements
outside the string section access string values by reference.

	SectionString = { String } .

Note that despite being an element, a string does not begin with a
reference table.

## Meta Section

The meta section provides fundamental information for a package. It
contains exactly two elements — a public root and a private root.

	SectionMeta = PublicRoot
	              PrivateRoot     // TODO(markfreeman): Define.
	              .

The public root element identifies the package and provides references
for all exported objects it contains.

	PublicRoot  = RefTable
	              [ Sync ]
	              PkgRef
	              [ HasInit ]
	              ObjectRefCount // TODO(markfreeman): Define.
	              { ObjectRef }  // TODO(markfreeman): Define.
	              .
	HasInit     = Bool .         // Whether the package uses any
	                             // initialization functions.

## PosBase Section

This section provides position information. It is a series of PosBase
elements.

	SectionPosBase = { PosBase } .

A base is either a file base or line base (produced by a line
directive). Every base has a position, line, and column; these are
constant for file bases and hence not encoded.

	PosBase = RefTable
	          [ Sync ]
	          StringRef       // the (absolute) file name for the base
	          Bool            // true if a file base, else a line base
	          // The below is omitted for file bases.
	          [ Pos
	            Uint64        // line
	            Uint64 ]      // column
	          .

A source position Pos represents a file-absolute (line, column) pair
and a PosBase indicating the position Pos is relative to. Positions
without a PosBase have no line or column.

	Pos     = [ Sync ]
	          Bool             // true if the position has a base
	          // The below is omitted if the position has no base.
	          [ Ref[PosBase]
	            Uint64         // line
	            Uint64 ]       // column
	          .

## Package Section

The package section holds package information. It is a series of Pkg
elements.

	SectionPkg = { Pkg } .

A Pkg element contains a (path, name) pair and a series of imported
packages. The below package paths have special meaning.

	+--------------+-----------------------------------+
	| package path |             indicates             |
	+--------------+-----------------------------------+
	| ""           | the current package               |
	| "builtin"    | the fake builtin package          |
	| "unsafe"     | the compiler-known unsafe package |
	+--------------+-----------------------------------+

	Pkg        = RefTable
	             [ Sync ]
	             StringRef      // path
	             // The below is omitted for the special package paths
	             // "builtin" and "unsafe".
	             [ StringRef    // name
	               Imports ]
	             .
	Imports    = Uint64         // the number of declared imports
	             { PkgRef }     // references to declared imports
	             .

Note, a PkgRef is *not* equivalent to Ref[Pkg] due to an extra marker.

	PkgRef     = [ Sync ]
	             Ref[Pkg]
	             .

## Type Section

The type section is a series of type definition elements.

	SectionType = { TypeDef } .

A type definition can be in one of several formats, which are identified
by their TypeSpec code.

	TypeDef     = RefTable
	              [ Sync ]
	              [ Sync ]
	              Uint64            // denotes which TypeSpec to use
	              TypeSpec
	              .

	TypeSpec    = TypeSpecBasic     // TODO(markfreeman): Define.
	            | TypeSpecNamed     // TODO(markfreeman): Define.
	            | TypeSpecPointer   // TODO(markfreeman): Define.
	            | TypeSpecSlice     // TODO(markfreeman): Define.
	            | TypeSpecArray     // TODO(markfreeman): Define.
	            | TypeSpecChan      // TODO(markfreeman): Define.
	            | TypeSpecMap       // TODO(markfreeman): Define.
	            | TypeSpecSignature // TODO(markfreeman): Define.
	            | TypeSpecStruct    // TODO(markfreeman): Define.
	            | TypeSpecInterface // TODO(markfreeman): Define.
	            | TypeSpecUnion     // TODO(markfreeman): Define.
	            | TypeSpecTypeParam // TODO(markfreeman): Define.
	              .

// TODO(markfreeman): Document the reader dictionary once we understand it more.
To use a type elsewhere, a TypeUse is encoded.

	TypeUse     = [ Sync ]
	              Bool              // whether it is a derived type
	              [ Uint64 ]        // if derived, an index into the reader dictionary
	              [ Ref[TypeDef] ]  // else, a reference to the type
	              .

## Object Sections

Information about an object (e.g. variable, function, type name, etc.)
is split into multiple elements in different sections. Those elements
have the same section-relative element index.

### Name Section

The name section holds a series of names.

	SectionName = { Name } .

Names are elements holding qualified identifiers and type information
for objects.

	Name        = RefTable
	              [ Sync ]
	              [ Sync ]
	              PkgRef    // the object's package
	              StringRef // the object's package-local name
	              [ Sync ]
	              Uint64    // the object's type (e.g. Var, Func, etc.)
	              .

### Definition Section

The definition section holds definitions for objects defined by the target
package; it does not contain definitions for imported objects.

	SectionObj = { ObjectDef } .

Object definitions can be in one of several formats. To determine the correct
format, the name section must be referenced; it contains a code indicating
the object's type.

	ObjectDef = RefTable
	            [ Sync ]
	            ObjectSpec
	            .

	ObjectSpec = ObjectSpecConst     // TODO(markfreeman) Define.
	           | ObjectSpecFunc      // TODO(markfreeman) Define.
	           | ObjectSpecAlias     // TODO(markfreeman) Define.
	           | ObjectSpecNamedType // TODO(markfreeman) Define.
	           | ObjectSpecVar       // TODO(markfreeman) Define.
	             .

To use an object definition elsewhere, an ObjectUse is encoded.

	ObjectUse  = [ Sync ]
	             [ Bool ]
	             Ref[ObjectDef]
	             Uint64              // the number of type arguments
	             { TypeUse }         // references to the type arguments
	             .

# References

A reference table precedes every element. Each entry in the table
contains a (section, index) pair denoting the location of the
referenced element.

	RefTable      = [ Sync ]
	                Uint64            // the number of table entries
	                { RefTableEntry }
	                .
	RefTableEntry = [ Sync ]
	                SectionKind
	                RelElemIdx
	                .

Elements encode references to other elements as an index in the
reference table — not the location of the referenced element directly.

	RefTableIdx   = Uint64 .

To do this, the Ref[T] primitive is used as below; note that this is
the same shape as provided by package pkgbits, just with new
interpretation applied.

	Ref[T]        = [ Sync ]
	                RefTableIdx       // the Uint64
	                .

# Primitives

Primitive encoding is handled separately by the pkgbits package. Check
there for definitions of the below productions.

  - Bool
  - Int64
  - Uint64
  - String
  - Ref[T]
  - Sync
*/