litnik 0.2.1

An embedded Lit and FileCheck runner for compiler test suites.
Documentation
# Lit and FileCheck compatibility

Litnik implements the parts of Lit that an integrated compiler test uses at
run time. It does not load Python suite configuration. Configure roots,
suffixes, tools, substitutions, features, time limits, and retries with
`litnik::Suite` or `litnik::LitConfig`.

## Integrated test directives

Litnik scans test files for these directives:

| Directive | Behavior |
| --- | --- |
| `RUN:` | Executes a command after substitutions. A trailing `\` continues on the next `RUN:` line. |
| `DEFINE:` | Defines a `%{name}` substitution at that point in the file. |
| `REDEFINE:` | Replaces an existing exact `%{name}` substitution. |
| `REQUIRES:` | Skips the test when a comma-separated expression is false. |
| `UNSUPPORTED:` | Skips the test when a comma-separated expression is true. |
| `XFAIL:` | Converts `FAIL` to `XFAIL` and `PASS` to `XPASS` when an expression is true. `*` always matches. |
| `ALLOW_RETRIES:` | Replaces the suite retry count for that test. Only `FAIL` is retried. |
| `END.` | Stops directive scanning when no text follows the directive. |

Feature expressions accept identifiers, `!`, `&&`, `||`, and parentheses.
Text inside `{{` and `}}` is a Rust regular-expression fragment matched against
the available feature names. The identifier `true` is always available.

A test without a `RUN:` line is `UNRESOLVED`. Invalid directives,
substitutions, feature expressions, or shell syntax also produce
`UNRESOLVED`.

## Substitutions

The main path substitutions are:

| Form | Value |
| --- | --- |
| `%s` | Test source file. |
| `%S`, `%p` | Directory that contains the source file. |
| `%t` | Per-test temporary path below `Output`, with a `.tmp` suffix. |
| `%T` | Per-test `Output` directory. |
| `%/s`, `%/S`, `%/p`, `%/t`, `%/T` | The corresponding path with forward slashes. |
| `%{s:basename}` | Source file base name. |
| `%{s:stem}` | Source file name without its extension. |
| `%basename_t`, `%{t:stem}` | Temporary path base name. |
| `%(line)`, `%(line+N)`, `%(line-N)` | Directive line number with optional arithmetic. |
| `%%` | A literal percent sign. |

Real-path, colon-normalized, filesystem-root, separator, and
regex-replacement path forms are also available. Conditional substitutions use
`%if <feature-expression> %{...%} %else %{...%}`; the `%else` branch is
optional and conditionals may nest.

`Suite::substitution` and `LitConfig::substitution` accept Rust regular
expressions. Replacement text is literal, so `$` does not expand capture
groups. Substitutions run in insertion order before the built-in forms.

One substitution pass runs unless a recursive expansion limit is set. With a
limit, expansion must stabilize within that number of additional passes.

## Shell

Litnik parses and executes `RUN:` commands without invoking a host shell. The
embedded `FileCheck` command takes precedence over registered tool paths, which
take precedence over `PATH` lookup.

The executor supports:

- single and double quotes, escapes, and pathname globs;
- pipelines with `|`;
- sequencing with `;`, `&&`, and `||`;
- input redirection with `<`;
- output redirection with `>`, `>>`, `2>`, and `2>>`;
- descriptor duplication with `2>&1` and `1>&2`;
- combined output redirection with `&>`;
- Lit negation with `not` and `not --crash`, shell negation with `!`, and the
  `env` command prefix;
- `cd`, `pushd`, `popd`, `export`, `echo`, `mkdir`, `rm`, `umask`, and `:` as
  in-process commands.

Background execution with `&`, here-documents, and other redirection forms are
rejected. `ulimit` is recognized but rejected because the runner cannot apply
the requested resource limit. Other commands must be registered with
`Suite::tool` or resolve through `PATH`.

Pipeline stages backed by child processes run concurrently. Embedded commands
receive buffered input at their pipeline boundary. With pipefail enabled, the
last nonzero stage determines a failed pipeline status.

## Embedded FileCheck

The command name is exactly `FileCheck`. `FILECHECK_OPTS` is split as shell
arguments and prepended to options written in the `RUN:` line.

The embedded implementation supports `CHECK`, `CHECK-NEXT`, `CHECK-SAME`,
`CHECK-NOT`, `CHECK-DAG`, `CHECK-LABEL`, `CHECK-EMPTY`, and `CHECK-COUNT`, with
custom check and comment prefixes. It also supports string variables, numeric
variables and expressions, implicit negative checks, variable scope,
full-line matching, strict whitespace, and case-insensitive matching.

Check files and input must be UTF-8. Patterns use Rust regular-expression
semantics. Response files are not expanded. A FileCheck mismatch exits with
status 1; option, validation, and input errors exit with status 2.

The embedded engine has these known output differences from LLVM FileCheck:

- `--dump-input=always` does not dump passing input;
- `--dump-input-context` is not implemented;
- `-v` does not report successful matches;
- `--color` has no effect;
- diagnostic text and layout differ.

These differences affect diagnostics, not the `RUN:` pipeline contract: zero
means success, one means a check mismatch, and two means an invocation error.