Guardrails / Collectors

Go build

The Go build in the project directory: the module it declares, the Go version it asks for, every module of a workspace, the modules it requires directly and indirectly, and the replacements and lock file beside them.

Facts key	golang
Version	v1
Script	golang.py
Timeout	30 seconds

Inputs

Input	Description	Default	Environment
projectDir	Directory holding the project, relative to the directory the CLI runs in.	.	GUARDRAIL_INPUT_PROJECTDIR

A guardrail that declares an input of the same name passes it through, so the guardrail's configuration in buildnote.json is what decides these values.

A guardrail asks for these facts by name, and reads them back the same way:

{
  "collect": ["golang"]
}

golang = guardrail.facts("golang")

Facts

The document golang collects. A path carrying [] is an entry of the list before it, and one carrying [path] is a key of the object before it.

Fact	Meaning
directory	The project directory the guardrail configured with projectDir, from the directory the CLI runs in. Every path this collector states is stated from there too, so a path it names resolves from where the CLI was invoked rather than from the directory it happened to run in.
exists	Whether that directory is there. Nothing else is collected when it is not.
manifest	Path of the primary manifest, from the directory the CLI runs in: go.work when the checkout is a workspace, go.mod otherwise.
sources	Every manifest that was read and understood, in the order they were read. A manifest the reader could not handle is in unparsed instead.
declared	The Go version the build declares, or null when it declares none.
declared.version	Version as the go directive writes it, such as 1.22.
declared.source	Manifest declaring it, from the directory the CLI runs in.
declared.pinned	Whether the constraint names one exact version rather than a floor or a range. Always false for Go, because the go directive is the lowest version the module builds with rather than the one the toolchain uses.
toolchain	Version the toolchain directive selects, such as go1.22.3, or null when the module names none and the go directive decides.
projects	Every module in the build: the workspace's use entries, or the one module the checkout is.
projects[].path	Directory of the module, from the directory the CLI runs in; directory itself for the project directory.
projects[].manifest	That module's go.mod, from the directory the CLI runs in, or null when the workspace names a directory carrying none.
projects[].name	Module path the module directive declares, such as github.com/acme/widget, or null when it declares none.
dependencies	What the manifests require, split by whether the module asks for it itself.
dependencies.direct	Every module required without an // indirect marker, which is what this build imports itself.
dependencies.direct[].name	Module path required, such as github.com/spf13/cobra.
dependencies.direct[].version	Version required, as written.
dependencies.direct[].scopes	Always ["default"]. Go modules carry no scope, so a dependency used only by tests is indistinguishable from one the binary links.
dependencies.direct[].source	Manifest that requires it, from the directory the CLI runs in.
dependencies.transitive	Every module required with an // indirect marker, which is there to pin what a dependency of a dependency resolves to. Shaped as direct.
replaced	Every module a replace directive redirects, which is a dependency whose source is not the one its path names.
replaced[].name	Module path being replaced.
replaced[].with	What it is replaced by, as written, a module path or a directory.
replaced[].source	Manifest declaring the replacement, from the directory the CLI runs in.
lockfiles	Every lock file committed beside a manifest, from the directory the CLI runs in. go.sum records the checksum of every module in the graph.
unparsed	Every manifest the reader could not handle, so a guardrail can tell a build that declares nothing from one nobody could read.
unparsed[].path	Path of that manifest, from the directory the CLI runs in.
unparsed[].reason	What stopped the reader.

A collector that cannot finish prints what it had along with an incomplete key saying why, so the facts below the point it stopped are absent. A check that cares reads incomplete before the rest.

Example facts

The example facts collected by golang collector:

{
  "directory": ".",
  "exists": true,
  "manifest": "go.mod",
  "sources": [
    "go.mod"
  ],
  "declared": {
    "version": "1.22",
    "source": "go.mod",
    "pinned": false
  },
  "toolchain": "go1.22.3",
  "projects": [
    {
      "path": ".",
      "manifest": "go.mod",
      "name": "github.com/acme/widget"
    }
  ],
  "dependencies": {
    "direct": [
      {
        "name": "github.com/spf13/cobra",
        "version": "v1.8.1",
        "scopes": [
          "default"
        ],
        "source": "go.mod"
      },
      {
        "name": "golang.org/x/sync",
        "version": "v0.7.0",
        "scopes": [
          "default"
        ],
        "source": "go.mod"
      }
    ],
    "transitive": [
      {
        "name": "github.com/inconshreveable/mousetrap",
        "version": "v1.1.0",
        "scopes": [
          "default"
        ],
        "source": "go.mod"
      },
      {
        "name": "github.com/spf13/pflag",
        "version": "v1.0.5",
        "scopes": [
          "default"
        ],
        "source": "go.mod"
      }
    ]
  },
  "replaced": [
    {
      "name": "github.com/acme/queue",
      "with": "./internal/queue",
      "source": "go.mod"
    }
  ],
  "lockfiles": [
    "go.sum"
  ],
  "unparsed": []
}

Collected for

Guardrail	Category	Inputs
golang/checksums-committed	golang	projectDir
golang/no-local-replacements	golang	projectDir
golang/toolchain-pinned	golang	projectDir
golang/version-declared	golang	projectDir

All collectors