Guardrails / Collectors

Repository files

Presence, size and line counts of the well known files a repository is expected to carry, plus any extra path the guardrail asks for.

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

Inputs

Input	Description	Default	Environment
paths	Comma separated paths to describe, relative to the directory the CLI runs in.	README.md,README.rst,LICENSE,LICENSE.md,CONTRIBUTING.md,CODE_OF_CONDUCT.md,SECURITY.md,.gitignore	GUARDRAIL_INPUT_PATHS
path	One further path to describe, so a guardrail configured with its own path is collected too.	``	GUARDRAIL_INPUT_PATH

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": ["files"]
}

files = guardrail.facts("files")

Facts

The document files 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
files	Every requested path, by path exactly as it was asked for. A path nobody asked for is absent, so read the one the guardrail configured rather than iterating. The key is the guardrail's own lookup key and is deliberately left as it was asked for rather than resolved from the directory the CLI runs in, which is what every other collector's paths are: files["AGENTS.md"] means the same thing whichever directory a policy holds to account, and files[path].location is where it was actually looked for.
files[path].present	Whether the path is a file.
files[path].location	Where the path was looked for, from the directory the CLI runs in, so a policy holding several directories to account tells one module's AGENTS.md from another's.
files[path].bytes	Size in bytes. Absent when the file is not present or could not be read.
files[path].lines	Line count. Absent when the file is not present or could not be read.
files[path].nonBlankLines	Lines carrying something other than whitespace. Absent when the file is not present or could not be read.
files[path].unreadable	Why the file could not be read, present only when it could not be.

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 files collector:

{
  "files": {
    "README.md": {
      "present": true,
      "location": "README.md",
      "bytes": 22,
      "lines": 3,
      "nonBlankLines": 2
    },
    "README.rst": {
      "present": false,
      "location": "README.rst"
    },
    "LICENSE": {
      "present": true,
      "location": "LICENSE",
      "bytes": 12,
      "lines": 1,
      "nonBlankLines": 1
    },
    "LICENSE.md": {
      "present": false,
      "location": "LICENSE.md"
    },
    "CONTRIBUTING.md": {
      "present": false,
      "location": "CONTRIBUTING.md"
    },
    "CODE_OF_CONDUCT.md": {
      "present": false,
      "location": "CODE_OF_CONDUCT.md"
    },
    "SECURITY.md": {
      "present": false,
      "location": "SECURITY.md"
    },
    ".gitignore": {
      "present": true,
      "location": ".gitignore",
      "bytes": 7,
      "lines": 1,
      "nonBlankLines": 1
    }
  }
}

Collected for

Guardrail	Category	Inputs
build/dependency-updates-configured	build	paths
docs/agent-instructions	docs	paths
docs/changelog	docs	path
docs/code-of-conduct	docs	path
docs/contributing	docs	path
docs/license-present	docs	paths
docs/readme	docs	path
docs/security-policy	docs	path
secrets/gitignore-present	secrets	path
secrets/no-credential-files-committed	secrets	paths

All collectors