numscript.go

package numscript

import (
	"context"

	"github.com/formancehq/numscript/internal/compiler"
	"github.com/formancehq/numscript/internal/interpreter"
	"github.com/formancehq/numscript/internal/parser"
	"github.com/formancehq/numscript/internal/vm"
)

// This struct represents a parsed numscript source code
type ParseResult struct {
	parseResult parser.ParseResult
}

// Returns a map from a variable's name to its type.
//
// doesn't include variables whose value is already defined within the script
func (p ParseResult) GetNeededVariables() map[string]string {
	m := make(map[string]string)

	if p.parseResult.Value.Vars == nil {
		return m
	}

	for _, varDecl := range p.parseResult.Value.Vars.Declarations {
		if varDecl.Name == nil || varDecl.Origin != nil {
			continue
		}

		m[varDecl.Name.Name] = varDecl.Type.Name
	}

	return m
}

// func (*ParseResult) GetDiagnostics() []Diagnostic {}

type ParserError = parser.ParserError

func Parse(code string) ParseResult {
	return ParseResult{parseResult: parser.Parse(code)}
}

var ParseErrorsToString = parser.ParseErrorsToString

func (p ParseResult) GetParsingErrors() []ParserError {
	return p.parseResult.Errors
}

type (
	VariablesMap    = interpreter.VariablesMap
	Posting         = interpreter.Posting
	ExecutionResult = interpreter.ExecutionResult
	// For each account, list of the needed assets
	BalanceQuery     = interpreter.BalanceQuery
	BalanceQueryItem = interpreter.BalanceQueryItem
	MetadataQuery    = interpreter.MetadataQuery
	AccountBalance   = interpreter.AccountBalance
	Balances         = interpreter.Balances
	BalanceRow       = interpreter.BalanceRow

	// Input account metadata (opaque, string-valued) read via meta()
	AccountMetadataRow = interpreter.AccountMetadataRow
	AccountsMetadata   = interpreter.AccountsMetadata

	// The account metadata set during the execution (tagged, typed values)
	SetAccountMetadataRow = interpreter.SetAccountMetadataRow
	SetAccountsMetadata   = interpreter.SetAccountsMetadata

	// The transaction metadata, set by set_tx_meta()
	Metadata = interpreter.Metadata

	Store = interpreter.Store

	StaticStore = interpreter.StaticStore

	Value = interpreter.Value

	InterpreterError  = interpreter.InterpreterError
	MissingFundsErr   = interpreter.MissingFundsErr
	NegativeAmountErr = interpreter.NegativeAmountErr

	ResolvedDependencies = interpreter.ResolvedDependencies
	AccountDependency    = interpreter.AccountDependency
	MetaDependency       = interpreter.MetaDependency
)

var ErrScalingNotSupported = interpreter.ErrScalingNotSupported

func (p ParseResult) Run(ctx context.Context, vars VariablesMap, store Store) (ExecutionResult, InterpreterError) {
	return p.RunWithFeatureFlags(ctx, vars, store, nil)
}

func (p ParseResult) RunWithFeatureFlags(
	ctx context.Context,
	vars VariablesMap,
	store Store,
	featureFlags map[string]struct{},
) (ExecutionResult, InterpreterError) {
	if len(p.parseResult.Errors) != 0 {
		return ExecutionResult{}, p.parseResult.Errors[0]
	}

	if featureFlags == nil {
		featureFlags = make(map[string]struct{})
	}

	res, err := interpreter.RunProgram(ctx, p.parseResult.Value, vars, store, featureFlags)
	if err != nil {
		return ExecutionResult{}, err
	}
	return *res, nil
}

// ResolveDependencies statically determines which accounts and metadata the
// script reads and writes, resolving account/asset/key expressions against the
// given vars and store.
func (p ParseResult) ResolveDependencies(ctx context.Context, vars VariablesMap, store Store) (ResolvedDependencies, error) {
	if len(p.parseResult.Errors) != 0 {
		return ResolvedDependencies{}, p.parseResult.Errors[0]
	}

	return interpreter.ResolveDependencies(ctx, store, vars, p.parseResult.Value)
}

func (p ParseResult) GetSource() string {
	return p.parseResult.Source
}

type (
	VarsEncoder     = compiler.VarsEncoder
	CompiledProgram = vm.Program
	VMStore         = vm.Store
	Vm              = vm.Vm
	Vars            = vm.Vars
)

var NewVm = vm.NewVm

var DecodeVars = vm.DecodeVars

func (p ParseResult) Compile() (VarsEncoder, CompiledProgram, error) {
	return p.CompileWithFeatureFlags(nil)
}

// CompileWithFeatureFlags compiles the program, rejecting any construct gated
// behind an experimental feature flag that isn't in featureFlags.
func (p ParseResult) CompileWithFeatureFlags(featureFlags map[string]struct{}) (VarsEncoder, CompiledProgram, error) {
	if len(p.parseResult.Errors) != 0 {
		return VarsEncoder{}, CompiledProgram{}, p.parseResult.Errors[0]
	}

	if featureFlags == nil {
		featureFlags = make(map[string]struct{})
	}

	return compiler.Compile(p.parseResult.Value, featureFlags)
}

func Compile(source string) (VarsEncoder, CompiledProgram, error) {
	return Parse(source).Compile()
}

func CompileWithFeatureFlags(source string, featureFlags map[string]struct{}) (VarsEncoder, CompiledProgram, error) {
	return Parse(source).CompileWithFeatureFlags(featureFlags)
}

var DecodeCompiledProgram = vm.DecodeProgram

// BytecodeVersion is the version of the bytecode wire format a compiled
// program or an encoded Vars was written with — major.minor, versioned
// independently of the library itself: a new library release does not imply a
// new bytecode version. A reader accepts a blob of its own major with a minor
// no newer than its own (BytecodeVersion.CanRead); anything else the decoders
// reject with UnsupportedBytecodeVersionError. Major 0 is unstable: a 0.x build
// reads only its exact version, so a host holding a 0.x blob this build
// rejects should recompile the script from source.
//
// CurrentBytecodeVersion is what this build's Compile and Encode write and the
// newest it can execute. A host that stores bytecode compiled by one build and
// executes it with another can compare it against the stored blob's version
// before trusting the bytecode to run; PeekCompiledProgramVersion and
// PeekVarsVersion read that version from the raw bytes without decoding the
// rest, and without checking that this build can read it.
type (
	BytecodeVersion                 = vm.BytecodeVersion
	UnsupportedBytecodeVersionError = vm.UnsupportedBytecodeVersionError
)

var (
	CurrentBytecodeVersion     = vm.CurrentBytecodeVersion
	PeekCompiledProgramVersion = vm.PeekProgramVersion
	PeekVarsVersion            = vm.PeekVarsVersion
)

// VerifyCompiledProgram statically checks that a program is safe to execute:
// ExecVm assumes well-formed bytecode and will panic rather than error on a
// program that is not. Compile's output always is, so this is for programs that
// came from somewhere else — DecodeCompiledProgram, most obviously.
//
// VerifyCompiledProgramWithVars additionally checks the program against the vars
// it will be given; prefer it whenever vars are in play, since a program that
// loads a variable is only safe against a pool that actually has it. On
// success it also returns a VerifiedVarsInfo: a caller that reuses the same
// compiled Program across many calls (e.g. an LRU cache keyed on the compiled
// bytes) can keep this and use its CheckVars method to skip re-running
// verification — a whole-program static pass — when it sees a Vars shape it
// already knows is compatible.
type VerifiedVarsInfo = vm.VerifiedVarsInfo

var (
	VerifyCompiledProgram         = vm.Verify
	VerifyCompiledProgramWithVars = vm.VerifyWithVars
)

// VM execution error types, aliased so ExecVm callers can classify failures
// with errors.As without reaching into internal packages — the same pattern as
// the interpreter's error types above. The Vm prefix keeps them apart from the
// interpreter's MissingFundsErr/NegativeAmountErr, which are different types
// with different fields.
type (
	VmMissingFundsError               = vm.MissingFundsError
	VmNegativeAmountError             = vm.NegativeAmountError
	VmNegativeBalanceError            = vm.NegativeBalanceError
	VmAssetMismatchError              = vm.AssetMismatchError
	VmInvalidAllotmentSum             = vm.InvalidAllotmentSum
	VmNegativePortionError            = vm.NegativePortionError
	VmDivideByZeroError               = vm.DivideByZeroError
	VmInvalidAccountName              = vm.InvalidAccountName
	VmInvalidColor                    = vm.InvalidColor
	VmInvalidScope                    = vm.InvalidScope
	VmCannotCastScopedAccountToString = vm.CannotCastScopedAccountToString
	VmInvalidUncappedSource           = vm.InvalidUncappedSource
	VmMetadataNotFoundError           = vm.MetadataNotFoundError
	VmBadMetaValueError               = vm.BadMetaValueError
	VmInternalError                   = vm.InternalError
	VmInvalidPostingError             = vm.InvalidPostingError
	VmStoreError                      = vm.StoreError
)

func ExecVm[S VMStore](ctx context.Context, machine *Vm, vars *Vars, store S) (ExecutionResult, error) {
	res, execErr := vm.Exec(ctx, machine, vars, store)
	if execErr != nil {
		return ExecutionResult{}, execErr
	}

	// Postings share one type (funds.Posting), scope fields included, so they
	// pass through unchanged. Metadata is normalized to the interpreter's
	// contract: non-nil maps/slices, account rows in the SetAccountsMetadata
	// shape.
	txMeta := res.Metadata
	if txMeta == nil {
		txMeta = Metadata{}
	}
	accountsMeta := make(SetAccountsMetadata, 0, len(res.AccountsMetadata))
	for _, e := range res.AccountsMetadata {
		accountsMeta = append(accountsMeta, SetAccountMetadataRow{
			Account: e.Account,
			Key:     e.Key,
			Value:   e.Value,
			Scope:   e.Scope,
		})
	}

	return ExecutionResult{
		Postings:         res.Postings,
		Metadata:         txMeta,
		AccountsMetadata: accountsMeta,
	}, nil
}