compat

package
v0.0.10 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package compat reads the compat entries of a feature (spec 09.2), the probes that prove them (09.4), and the register of the implementations of each language.

Index

Constants

View Source
const ResultsFile = "manifests/probes.jsonl"

ResultsFile is the file of the content repository where prog compat probe records its results.

Variables

This section is empty.

Functions

func Edition

func Edition(s, def string) string

Edition returns the first edition of a statement, such as 2018 for "2018+", and def when the statement has none.

func Key

func Key(feature, impl, probe, added string) string

Key identifies the result of a probe of a feature for an implementation and a version_added.

func ProbeHash

func ProbeHash(dir, probe string, e Expect) (string, error)

ProbeHash is the hash of a probe: the bytes of the file and its expectation.

func ReadExpect

func ReadExpect(dir string) (map[string]Expect, error)

ReadExpect reads probes/probes.yaml in dir. A missing file gives an empty map.

Types

type Entry

type Entry struct {
	Key         string            `json:"key"`
	Description string            `json:"description"`
	Spec        map[string]string `json:"spec,omitempty"`
	Source      map[string]string `json:"source,omitempty"`
	// Support maps an implementation column to its statements. Most columns have one statement. A column has more than one when the answer differs by edition or by flag.
	Support map[string][]Statement `json:"support"`
	// Columns are the keys of Support in the order of the file.
	Columns []string        `json:"-"`
	Status  map[string]bool `json:"status,omitempty"`
	Line    int             `json:"-"`
	// Unknown are the keys of the entry that the schema does not have.
	Unknown []string `json:"-"`
}

Entry is one compat entry. The key of the first entry is the slug of the feature. The keys of the other entries add a dot and a sub-feature, such as match-statement.class-patterns.

func Read

func Read(path string) ([]Entry, error)

Read reads a compat file. The entries keep the order of the file.

type Expect

type Expect struct {
	// Output is the standard output that the probe must give where it passes. When it is empty, exit status 0 is enough.
	Output string `yaml:"output,omitempty" json:"output,omitempty"`
	// FailsWith is a regular expression that the output of the probe must match on the release before version_added (rule K05).
	FailsWith string `yaml:"fails_with,omitempty" json:"fails_with,omitempty"`
}

Expect is what a probe must do (spec 09.4). It comes from the file probes/probes.yaml of the feature, keyed by the name of the probe file.

type Impl

type Impl struct {
	ID   string `yaml:"id" json:"id"`
	Name string `yaml:"name" json:"name"`
	// Standard is true for a column that is the language standard, such as c++20, not a program.
	Standard bool `yaml:"standard,omitempty" json:"standard,omitempty"`
	// Main is true for the implementations that the computed status counts (spec 09.5).
	Main bool `yaml:"main,omitempty" json:"main,omitempty"`
	// Image is the container image of a release, with {v} for the version, such as python:{v}-slim. Probe runs a probe in it.
	Image string `yaml:"image,omitempty" json:"image,omitempty"`
	// Run is the command that runs a probe, with {file} for the path of the probe in the container.
	Run []string `yaml:"run,omitempty" json:"run,omitempty"`
	// Releases are the releases of the implementation, oldest first. Rule K02 checks each version_added against this list, and probe takes the release before from it.
	Releases []string `yaml:"releases,omitempty" json:"releases,omitempty"`
}

Impl is one implementation column of a language, from registers/implementations.yaml.

func (Impl) Before

func (im Impl) Before(v string) (string, bool)

Before returns the release just before v, and false when v is the first release or is not in the list.

func (Impl) Known

func (im Impl) Known(v string) bool

Known tells if v is a release in the list.

func (Impl) Ref

func (im Impl) Ref(v string) string

Ref returns the image of release v.

type Prober

type Prober struct {
	// Engine is the container command, such as docker or podman.
	Engine string
	// Timeout limits one run, including the compile step.
	Timeout time.Duration
	// Exec runs a command and returns its combined output and exit code. Tests replace it. The default runs the command with os/exec.
	Exec func(ctx context.Context, name string, args ...string) (string, int, error)
	// contains filtered or unexported fields
}

Prober runs probes in containers (spec 09.4). Each run gets a new container with no network, a read-only root and a small writable /tmp.

func NewProber

func NewProber(engine string) *Prober

NewProber returns a prober that uses engine.

func (*Prober) Probe

func (p *Prober) Probe(ctx context.Context, t Task) (Result, error)

Probe runs the task on version_added, and on the release before when the register has one. It returns the result with the hash of the probe.

type Register

type Register map[string][]Impl

Register maps a language id to its implementation columns, in the order of the file.

func ReadRegister

func ReadRegister(root string) (Register, error)

ReadRegister reads registers/implementations.yaml under root. A missing file gives an empty register.

func (Register) Impl

func (r Register) Impl(lang, id string) (Impl, bool)

Impl finds the column of a language.

type Result

type Result struct {
	// Feature is the slug of the feature, and Probe is the path of the probe file in the node directory, such as probes/match_basic.py.
	Feature string `json:"feature"`
	Impl    string `json:"impl"`
	Probe   string `json:"probe"`
	Added   string `json:"version_added"`
	// Hash is the SHA-256 of the probe file and of its entry in probes.yaml. A result with an old hash does not count.
	Hash string `json:"hash"`
	Pass Run    `json:"pass"`
	// Fail is the run on the release before version_added. It is nil when the register has no release before.
	Fail *Run   `json:"fail,omitempty"`
	Date string `json:"date"`
}

Result is the record of one probe for one implementation and one version_added (spec 09.4).

func (Result) Key

func (r Result) Key() string

Key identifies a result.

func (Result) Verified

func (r Result) Verified(hash string) bool

Verified tells if the result proves the statement: the hash is current, the pass run is OK, and the fail run is OK when there is one.

type Results

type Results map[string]Result

Results maps Key to the result.

func ReadResults

func ReadResults(root string) (Results, error)

ReadResults reads manifests/probes.jsonl under root. A missing file gives no results.

func (Results) Write

func (rs Results) Write(root string) error

Write writes the results to manifests/probes.jsonl under root, sorted by key, one result on each line.

type Run

type Run struct {
	Version string `json:"version"`
	Image   string `json:"image"`
	// OK tells if the run did what the check needs: exit 0 and the output for the pass run, a failure that matches the signature for the fail run.
	OK     bool   `json:"ok"`
	Exit   int    `json:"exit"`
	Output string `json:"output,omitempty"`
	Error  string `json:"error,omitempty"`
}

Run is one run of a probe.

type Statement

type Statement struct {
	// Added is the version_added: a version, "false" for not supported, or "preview". It is empty when the field is missing, and "true" or "null" when the file has these values, so that rule K01 can find them.
	Added      string   `json:"version_added"`
	Removed    string   `json:"version_removed,omitempty"`
	Deprecated string   `json:"version_deprecated,omitempty"`
	Flags      []string `json:"flags,omitempty"`
	Partial    bool     `json:"partial_implementation,omitempty"`
	AltName    string   `json:"alternative_name,omitempty"`
	Edition    string   `json:"edition,omitempty"`
	Std        string   `json:"std,omitempty"`
	Note       string   `json:"notes,omitempty"`
	Probe      string   `json:"probe,omitempty"`
	Source     string   `json:"source,omitempty"`
	Line       int      `json:"-"`
	Unknown    []string `json:"-"`
}

Statement is one support statement of an implementation (spec 09.2).

func (Statement) IsVersion

func (s Statement) IsVersion() bool

IsVersion tells if Added is a real version, not false or preview.

func (Statement) Supported

func (s Statement) Supported() bool

Supported tells if the statement names a version where the feature works.

type Task

type Task struct {
	Feature string
	// Dir is the node directory on the host.
	Dir    string
	Impl   Impl
	Probe  string
	Added  string
	Expect Expect
	// Edition is the edition of the statement, such as 2018 for "2018+". It fills {edition} in the run command.
	Edition string
}

Task is one probe to prove: a statement of an entry for one implementation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL