Packages

Use blocks

A use block takes a requirement defined elsewhere:

code:
  - { id: FAIL_FAST, use: ./std }                          # a folder of this repository
  - id: COLOCATION
    use: gabsn/reqfile-colocation@961ed099979271c6558efd10f84c1e764997b1ca  # v0.1.3
  - id: CONTRACTS
    use: acme/reqs@3f2a9c1e0b7d4c6a8e5f1b2d3c4a5e6f7a8b9c0d   # v1.2.0
    why: The billing core must never reach an invalid state.

The definition brings its checks and its labeled examples under .reqfile/<ID>/.

Locations and pins

• Locations. A folder, relative to the folder of the use block's Reqfile (./std, ../shared), or owner/repo@<commit>, fetched from https://github.com/owner/repo ($REQFILE_GIT_BASE/owner/repo when that variable is set, for a mirror). The use block resolves to the unique definition with its id among the Reqfiles at or under that location. Use blocks are never resolution targets, so chains cannot form.
• Pins. A Reqfile pins a repository to a full 40-character commit id; the tag it came from goes in a comment. A tag, a branch, a short id or HEAD is an error: the rules of a repository must not change under it. Nobody types the commit: reqfile add writes the line and reqfile update moves it.
• Cache. A commit never changes, so it is fetched once into the user's cache ($REQFILE_CACHE, else $XDG_CACHE_HOME/reqfile, else ~/.cache/reqfile), shared by every repository and worktree, and checked offline from then on. CI can keep that folder between runs.

What a use block can set

• Types. Only code and process requirements can be taken: a product requirement describes its own repository's product. The section of the use block must match its definition's.
• Local fields. A use block takes must, ref and its type from its definition. It may set why and who, and checks, which then replace the definition's checks entirely. Setting must is an error.
• Where checks run. The checks of a use block run in the folder of its Reqfile, with its globs relative to that folder, and the settings of that folder in the repository being checked.
• $REQFILE_ASSETS is per check, never a merge: inline checks use the definition's .reqfile/<ID>/ for inherited checks, or the use block's own for checks it sets. Adapter leaves use their manifest directory. With inherited checks, local assets may hold examples/ and the consumer-owned binding.json.

Try before adopting

--use adds the requirements of a location for one run, without writing any Reqfile; --only narrows them. A tag is welcome there: it is resolved on each run and the summary names the commit it resolved to.

reqfile eval --use owner/repo@v1.2.0                 # measure its checks on its examples
reqfile check --use owner/repo@v1.2.0 --only FAIL_FAST   # run them on this code

Add and update

reqfile add owner/repo@v1.2.0 [IDS] [--dry-run]
reqfile update [--dry-run]

reqfile add writes the use blocks into the Reqfile of the current folder, under their sections, a repository pinned to the commit its tag points to, and says what their checks run; --dry-run only shows them. Without ids, it takes every code and process requirement there. reqfile update moves every pin to the commit of its repository's latest release tag (vX.Y.Z); the diff is the review.

Taking a requirement from another repository runs its commands in your CI: read what reqfile add prints before adding it. Every finding of a requirement taken with use names its use block and where its definition was resolved.

Publish a package

Put a Reqfile.yaml at the root of a repository with code or process definitions, their checks and their examples under .reqfile/<ID>/, and tag releases vX.Y.Z. A checker the commands call is fetched by its ecosystem's runner at an exact version. Examples double as documentation, and reqfile eval shows users how well the checks work before they adopt them. See gabsn/reqfile-colocation for a working package.

Use blocks need reqfile 0.2 or later, commit pins 0.3, and adapters 0.6. Nested adapter dependency pins are updated explicitly by their author; they are not rewritten by a consumer's reqfile update.

Compose checks and bind a project

A requirement definition remains unique across languages and libraries. Its checks may select named exports from Adapter.yaml manifests; each expanded leaf keeps its source and asset directory. Inline command and decision checks remain supported. An explicit use-block checks still replaces every inherited check.

A consumer may keep examples/ and binding.json under its local .reqfile/<ID>/ with inherited checks. The latter is project data for the checker, fingerprinted independently of imported assets. Eval reads it from each isolated fixture. See adapter composition.