// 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.

/*
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
*/

package noder