Skip to content
SLCR

Reference

Validator files

The normative definition of validator files, which tie requirements to the tools that check them.

This page defines validator files. The key words MUST, MUST NOT, SHOULD, and MAY are used as defined in RFC 2119⁠ (external site). For the ideas behind validators, see Validators.

Names and discovery⁠Link to this section

  • A validator file MUST be named .validators.slcr.toml, .validators.slcr.yaml, .validators.slcr.yml, or .validators.slcr.json. The extension selects the format.
  • A directory MUST hold at most one validator file. slcr vet reports a second one as duplicate-validator-file.
  • slcr finds validator files by walking the project root. The walk includes hidden files and directories, other than .git, and skips anything git ignores. No entry in SLCR.toml is needed.

Fields⁠Link to this section

FieldRequiredValue
formatVersionYesThe string "1".
validatorYesAn array of validator entries. In TOML, each entry is a [[validator]] table.

Each validator entry has these fields:

FieldRequiredValue
requirementYesA qualified requirement ID, <spec-name>/REQ-NNN, even in a project with one specification. The qualifier is the specification's spec.name, not its path.
toolYesA key under [tools] in SLCR.toml.
criterionNoAn acceptance criterion ID, AC-NNN. It MUST belong to the named requirement.
descriptionNoText shown in reports. If present, it MUST NOT be empty.
withSee belowThe tool's settings.

with MUST satisfy the validator schema in the tool's descriptor. It MAY be omitted only when that schema accepts an empty object.

Unknown fields MUST NOT appear.

TOML
# src/views/items/.validators.slcr.toml
formatVersion = "1"

[[validator]]
requirement = "todo-api/REQ-002"
criterion = "AC-004"
tool = "ast-grep"
description = "POST handler is defined and registered with the router"
with = { rule = "rules/post-handler.yml" }

[[validator]]
requirement = "todo-api/REQ-002"
tool = "cargo-nextest"
with = { test = "items::post::creates_item" }

Identity⁠Link to this section

Validators have no names. Reports identify each one by its file and its 1-based position in that file, as in src/.validators.slcr.toml validator 2. Two identical entries in one file MUST NOT appear.

Findings reported by slcr vet⁠Link to this section

slcr vet checks each entry in this order. When a check fails, checks that depend on it are skipped.

CodeMeaning
(parse error)The file is malformed, or has an unknown or empty field.
unknown-specrequirement names a specification the project doesn't have.
unknown-requirementrequirement names a requirement the specification doesn't have.
unknown-criterioncriterion isn't an acceptance criterion of the named requirement.
tool-not-declaredtool isn't a key under [tools].
invalid-withwith doesn't satisfy the tool's validator schema. Each schema error is reported separately.
duplicate-validatorThe entry is identical to an earlier one in the same file.

Results⁠Link to this section

Running a validator produces one of three results:

ResultMeaning
GreenThe tool exited with a code its descriptor lists as passing.
RedThe tool exited with any other code, was killed by a signal, or timed out.
Could not be runThe tool couldn't be started, for example because it isn't on PATH or its working directory doesn't exist. slcr check fails.