Guardrails / Collectors

Scala build

The sbt build in the project directory: the Scala and sbt versions it pins, every subproject the reader saw, the library dependencies each build file names with their configurations, and the plugins the build itself runs. build.sbt is Scala rather than a declaration, so what it declares indirectly is not seen and scanned says so.

Facts key	scala
Version	v1
Script	scala.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": ["scala"]
}

scala = guardrail.facts("scala")

Facts

The document scala 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 projectDir input, as the guardrail configured it.
exists	Whether that directory is there. Nothing else is collected when it is not.
manifest	Path of the primary manifest, relative to projectDir, always build.sbt.
sources	Every build file that was read, in the order they were read.
scanned	Every build file that is Scala rather than a declaration and was read by pattern. A dependency built by a function, added inside a condition or held in a variable is not seen, so a guardrail reading dependencies from one of these is reading a floor rather than the whole list.
declared	The Scala version the build declares, or null when the reader could not see one.
declared.version	Version exactly as written, such as 3.4.1.
declared.source	Build file declaring it, relative to projectDir.
declared.pinned	Whether it names one exact version. sbt takes a literal version rather than a range, so this is true wherever a version was read and false only when it is an unresolved reference.
sbt	The sbt version project/build.properties pins, such as 1.9.9, or null when the checkout pins none and whatever launcher the runner has decides.
projects	The root build, followed by every subproject the reader saw declared with project in file(...).
projects[].path	Directory of the subproject, relative to projectDir, . for the project directory itself.
projects[].manifest	The build file declaring it, relative to projectDir.
projects[].name	Name the lazy val binds it to, or null for the root.
dependencies	What the build files declare, split by whether the build asks for it itself.
dependencies.direct	Every libraryDependencies entry the reader saw, in the order they appear.
dependencies.direct[].name	Coordinates as group:artifact, such as org.typelevel:cats-effect. An artifact declared with %% keeps its base name, without the Scala binary version sbt appends.
dependencies.direct[].version	Revision exactly as written, such as 3.5.4, or null when it is an unresolved reference rather than a literal.
dependencies.direct[].scopes	The configuration the entry names, such as Test or Provided, or default when it names none and the dependency is on the compile classpath.
dependencies.direct[].source	Build file declaring it, relative to projectDir.
dependencies.direct[].pinned	Whether the revision is a literal version rather than a reference or a latest.integration style moving revision.
dependencies.direct[].crossVersion	Whether the entry uses %%, which makes sbt append the Scala binary version to the artifact name.
dependencies.transitive	Always empty. sbt resolves at build time and commits nothing by default: lockfiles says whether a locking plugin wrote one.
plugins	Every sbt plugin project/plugins.sbt adds, as group:artifact, which is code the build runs with the build's own privileges.
lockfiles	Every dependency lock file committed, relative to projectDir. sbt writes none by default, so an empty list is the usual answer rather than a finding on its own.
unparsed	Every build file the reader could not open, so a guardrail can tell a build that declares nothing from one nobody could read.
unparsed[].path	Path of that build file, relative to projectDir.
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 scala collector:

{
  "directory": ".",
  "exists": true,
  "manifest": "build.sbt",
  "sources": [
    "build.sbt",
    "project/build.properties",
    "project/plugins.sbt"
  ],
  "scanned": [
    "build.sbt",
    "project/plugins.sbt"
  ],
  "declared": {
    "version": "3.4.1",
    "source": "build.sbt",
    "pinned": true
  },
  "sbt": "1.9.9",
  "projects": [
    {
      "path": ".",
      "manifest": "build.sbt",
      "name": null
    },
    {
      "path": "core",
      "manifest": "build.sbt",
      "name": "core"
    },
    {
      "path": "server",
      "manifest": "build.sbt",
      "name": "server"
    }
  ],
  "dependencies": {
    "direct": [
      {
        "name": "org.typelevel:cats-effect",
        "version": "3.5.4",
        "scopes": [
          "default"
        ],
        "source": "build.sbt",
        "pinned": true,
        "crossVersion": true
      },
      {
        "name": "com.lihaoyi:upickle",
        "version": "3.3.0",
        "scopes": [
          "default"
        ],
        "source": "build.sbt",
        "pinned": true,
        "crossVersion": true
      },
      {
        "name": "org.http4s:http4s-ember-server",
        "version": "0.23.27",
        "scopes": [
          "default"
        ],
        "source": "build.sbt",
        "pinned": true,
        "crossVersion": true
      },
      {
        "name": "org.scalameta:munit",
        "version": "1.0.0",
        "scopes": [
          "Test"
        ],
        "source": "build.sbt",
        "pinned": true,
        "crossVersion": true
      }
    ],
    "transitive": []
  },
  "plugins": [
    "org.scalameta:sbt-scalafmt"
  ],
  "lockfiles": [],
  "unparsed": []
}

Collected for

Guardrail	Category	Inputs
scala/dependencies-pinned	scala	projectDir
scala/no-snapshot-dependencies	scala	projectDir
scala/sbt-version-pinned	scala	projectDir
scala/version-declared	scala	projectDir

All collectors