Help us shape the future of Go! Take the 2026 Go Developer Survey

specs_format

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const InputsSchemaURL = "https://raw.githubusercontent.com/formancehq/numscript/main/v1.inputs.schema.json"

InputsSchemaURL is the equivalent for the inputs format.

View Source 
const SchemaURL = "https://raw.githubusercontent.com/formancehq/numscript/main/v1.specs.schema.json"

SchemaURL is the canonical $schema of the current specs format. Generated files point at it, and it is what a migration rewrites a stale $schema to.

Variables

This section is empty.

Functions

func CompareMovements added in v0.0.26 

func CompareMovements(expected Movements, got Movements) bool

Compare movements as a set: order does not matter. Each (source, sourceScope, destination, destinationScope, asset, color) tuple is unique within a Movements list, so we match on that tuple and compare amounts.

func EndBalances added in v0.0.26 

func EndBalances(postings []interpreter.Posting, initialBalances interpreter.Balances) interpreter.Balances

EndBalances applies postings to the initial balances, yielding the end state.

func MergeBalances added in v0.0.26 

func MergeBalances(outer interpreter.Balances, inner interpreter.Balances) interpreter.Balances

Merge two balance inputs, deduping by (account, asset, color). Entries in "inner" override matching entries in "outer".

func MigrateSpecsContent added in v0.0.25 

func MigrateSpecsContent(raw []byte) (out []byte, changed bool, err error)

MigrateSpecsContent rewrites a specs file's raw JSON to the current format. Two things can be outdated, independently of each other:

  • the file's structure: v0.0.24's nested-map balances/metadata are flattened to today's row arrays (see migrate_v0024.go);
  • its asset names: v0.0.24's ASSET_COLOR encoding is split back into the separate asset/color fields (see decodeLegacyColors).

The second can be stale on its own, since the encoding hides inside a string field whose surrounding structure never changed — so it is checked on every file, not only on ones that failed to parse as the current shape.

It reports whether anything changed, so a caller can gate writing the result behind a flag while still surfacing that a file is stale.

Staleness is decided by content alone: $schema is an editor hint, not part of the format, and nothing in the CLI reads it to parse, validate or dispatch. A migrated file does get its $schema pointed at SchemaURL, since the file really did change.

Once a file IS stale, the rewrite re-marshals the whole struct, so it also canonicalizes formatting to match what the rest of the CLI generates (e.g. test-init) — this is not a minimal-diff patch.

func RunSpecs 

func RunSpecs(stdout io.Writer, stderr io.Writer, rawSpecs []RawSpec) bool

func ShowDiff 

func ShowDiff(w io.Writer, expected_ any, got_ any)

Types

type AssertionMismatch 

type AssertionMismatch[T any] struct {
	Assertion string `json:"assertion"`
	Expected  T      `json:"expected,omitempty"`
	Got       T      `json:"got,omitempty"`
}

type ExpectedTxMeta added in v0.0.25 

type ExpectedTxMeta []TxMetadataRow

ExpectedTxMeta is a test case's expected transaction metadata: a list of rows, mirroring expect.metadata. Comparison ignores order (see compareTxMeta).

type Movement added in v0.0.25 

type Movement struct {
	Source           string   `json:"source"`
	SourceScope      string   `json:"sourceScope,omitempty"`
	Destination      string   `json:"destination"`
	DestinationScope string   `json:"destinationScope,omitempty"`
	Asset            string   `json:"asset"`
	Amount           *big.Int `json:"amount"`
	Color            string   `json:"color,omitempty"`
}

type Movements 

type Movements = []Movement

func GetMovements added in v0.0.26 

func GetMovements(postings []interpreter.Posting) Movements

GetMovements folds postings into one movement per (source, destination, asset, color).

type RawSpec 

type RawSpec struct {
	NumscriptPath    string
	SpecsPath        string
	NumscriptContent string
	SpecsFileContent []byte
}

func ReadSpecsFiles 

func ReadSpecsFiles(paths []string) ([]RawSpec, error)

type Specs 

type Specs struct {
	Schema       string                       `json:"$schema,omitempty"`
	FeatureFlags []string                     `json:"featureFlags,omitempty"`
	Balances     interpreter.Balances         `json:"balances,omitempty"`
	Vars         interpreter.VariablesMap     `json:"variables,omitempty"`
	Meta         interpreter.AccountsMetadata `json:"metadata,omitempty"`
	TestCases    []TestCase                   `json:"testCases,omitempty"`
}

--- Specs:

type SpecsResult 

type SpecsResult struct {
	// Invariants: total==passing+failing
	Total   uint `json:"total"`
	Passing uint `json:"passing"`
	Failing uint `json:"failing"`
	Skipped uint `json:"skipped"`
	Cases   []TestCaseResult
}

func Check 

func Check(program parser.Program, specs Specs) (SpecsResult, interpreter.InterpreterError)

type TestCase 

type TestCase struct {
	It string `json:"it"`

	// Preconditions
	Balances interpreter.Balances         `json:"balances,omitempty"`
	Vars     interpreter.VariablesMap     `json:"variables,omitempty"`
	Meta     interpreter.AccountsMetadata `json:"metadata,omitempty"`

	// Select tests
	Focus bool `json:"focus,omitempty"`
	Skip  bool `json:"skip,omitempty"`

	// Expectations
	ExpectMissingFunds   bool `json:"expect.error.missingFunds,omitempty"`
	ExpectNegativeAmount bool `json:"expect.error.negativeAmount,omitempty"`

	ExpectPostings           []interpreter.Posting           `json:"expect.postings,omitempty"`
	ExpectTxMeta             ExpectedTxMeta                  `json:"expect.txMetadata,omitempty"`
	ExpectAccountsMeta       interpreter.SetAccountsMetadata `json:"expect.metadata,omitempty"`
	ExpectEndBalances        interpreter.Balances            `json:"expect.endBalances,omitempty"`
	ExpectEndBalancesInclude interpreter.Balances            `json:"expect.endBalances.include,omitempty"`
	ExpectMovements          Movements                       `json:"expect.movements,omitempty"`
}

type TestCaseResult 

type TestCaseResult struct {
	Skipped  bool                         `json:"skipped"`
	It       string                       `json:"it"`
	Pass     bool                         `json:"pass"`
	Balances interpreter.Balances         `json:"balances"`
	Vars     interpreter.VariablesMap     `json:"variables"`
	Meta     interpreter.AccountsMetadata `json:"metadata"`

	// Output:
	Postings []interpreter.Posting `json:"postings"`

	// Assertions
	FailedAssertions []AssertionMismatch[any] `json:"failedAssertions"`
}

type TestResult 

type TestResult struct {
	Specs  Specs
	File   string
	Result TestCaseResult
}

type TxMetadataRow added in v0.0.25 

type TxMetadataRow struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

TxMetadataRow is a single transaction metadata entry. Like SetAccountMetadataRow, the value is the rendered text produced by interpreter.MetaString: the wire format is untyped.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.