alint facts

Rules can be gated on facts about the repository (for example "is there a Cargo.toml?") through when: clauses, and bundled rulesets declare their own facts. When a rule runs or skips unexpectedly, alint facts shows what each fact resolved to.

Facts are evaluated once per run, before any rule. A rule whose when: is false is dropped without reading a file, which is how one config can carry Rust, Python and Node rules and only run the ones that apply. The cost is that a skipped rule is silent: it doesn't fail, it just never reports. alint facts makes the gate visible.

What it prints

A config that extends alint://bundled/python@v1 (which declares has_python) and adds three facts of its own:

facts:
  - id: n_py_files
    count_files: "**/*.py"
  - id: has_rust
    any_file_exists: [Cargo.toml]
  - id: branch
    git_branch: {}

alint facts

has_python  any_file_exists  true
n_py_files  count_files      1
has_rust    any_file_exists  false
branch      git_branch       "main"

One line per fact: its id, its kind and the value it resolved to. Facts from extends: rulesets come first, then the config's own. Any rule gated on facts.has_rust is skipped in this repository, and a when: such as facts.n_py_files > 5 is false.

Fact kinds

Kind	Resolves to
`any_file_exists`	`true` if any listed path or glob matches a file
`all_files_exist`	`true` only if every listed path matches
`count_files`	the number of files matching a glob
`file_content_matches`	`true` if raw file content—or strings selected by an optional JSON/YAML/TOML/XML/dotenv/properties/INI/HCL `extract`—matches a pattern
`git_branch`	the current branch name
`custom`	the result of a command, allowed only in your own top-level config

For node-specific checks, add an extract map such as { json: "$.sdk.version" } inside file_content_matches. The supported keys are json, yaml, toml, xml, dotenv, properties, ini, and hcl. The pattern then sees only selected strings; malformed input, non-string nodes, and missing paths are non-matches.

A fact that isn't declared reads as null in a when: clause, which is false. A misspelled fact name therefore turns a rule off rather than failing, and alint facts is the quickest way to see which names exist.

Debugging a rule that never fires

alint explain <rule-id> shows the rule's when: clause.
alint facts shows the value of each fact the clause reads.
If a fact has the wrong value, override it: declare a fact with the same id in your own facts: block, as the bundled rulesets suggest when their detection heuristic doesn't fit your layout.

Examples

Resolved value of every fact in the effective config:

alint facts

Against another checkout:

alint facts path/to/repo

As JSON, for a script or a CI log:

alint facts --format json

{
  "facts": [
    {
      "id": "has_python",
      "kind": "any_file_exists",
      "value": true
    },
    {
      "id": "n_py_files",
      "kind": "count_files",
      "value": 1
    }
  ],
  "kind": "facts",
  "schema_version": 1
}

(Shortened to the first two facts; the output lists every fact.)

Reference

Evaluate the config's `facts:` entries and print resolved values.

A debugging aid for `when:` clauses: prints the resolved value of every `facts:` entry in the
effective config.

Usage: alint facts [OPTIONS] [PATH]

Arguments:
  [PATH]
          Root of the repository to evaluate facts against

          [default: .]

The global options apply to alint facts too, where they are relevant.