#Repository structure

• packs/<id>/: pack.json, package.json, README.md, LICENSE, NOTICE, licenses/, rules/ (shipped), candidates/ (scored, never shipped), upstream/<tool>/ (generators and locks; test data, expected findings included, is one S3 archive per tool named by its test-data.lock, not in git, #3).
• plugins/<agent>/: the installer plugins listed in the Claude, OpenAI and Cursor plugin directories (claude/, codex/, cursor/): one skill each, install, running npx @neralabs/rerail@<version> setup --relay; no hooks or binaries.

The only inputs are git ls-files (tracked files present in the working tree) and file contents. No build, network or clock: two runs print the same bytes.

Each metric is a module, scripts/check/check-structure/metrics/<NN>-<slug>.mjs, exporting { id, title, target, check(repo) }. check returns { actual, findings: [{ path, line?, message }] }; no findings means pass. The module's header comment is the authoritative predicate. Exemptions exist only as named rules inside a module, each with its reason.

Shared code sits beside the metrics: repo.mjs (the repository view; memoryRepo builds one in memory for tests), lib.mjs, generated.mjs (#6, #20, #25) and fixtures.mjs (#3, #10). Tests are in test/structure/; boundaries.test.mjs covers the layer boundary lint #13 runs.

• engine-test-inputs: a rule document may be an engine or host test input under fixtures/ (fixtures/<family>/compile/…, fixtures/host/…), never shipped (#23). No directory on its path below fixtures/ may be named rules, candidates, probes or policies: those names mark rule sets, which belong in a pack.
• validator-inputs: fixtures/packs/**, whose pack format puts rule documents in rules/.

Fixture data is:

• any file with a fixtures or __fixtures__ directory in its path;
• *.expected.json (expected findings), *.cases.json (case lists) and code-rule documents;
• non-TS/JS, non-Markdown files in a test root (test/, integration/, conformance/, benchmark/);
• files in test/ or integration/ with a fixture name.

Exemptions:

• packs/<id>/candidates/** (pack data).
• gate-pins: the conformance gate's lists (conformance/languages/ungated-rules.json, conformance/languages/pending.json) and scripts/pack-data/runtimes/**, the manifests that pin each runtime the derivation runs upstream on.
• For code-rule documents, packs/<id>/rules/**.

No tracked file matches PACK_FIXTURE_PATTERNS in scripts/s3/pack-fixtures.mjs, the pulled layout: under packs/*/upstream/*/, the patterns fixtures/**, tests/**, *.expected.json, cases.json, *.cases.json, fixtures.upstream-check.json, lizard-*.tsv, authored/**, provenance.json, LICENSES.md (CONTRIBUTING.md, "Pack test data"). Each tool-pack's test data, derived and authored alike, is one archive, pinned by sha256.

While any publish/ is tracked, the metric fails once per tool-pack ("Pack data waiting to publish"), naming the workflow to run. Publish pack data (.github/workflows/pack-data-publish.yml) then uploads the data, commits the new locks and deletes publish/ on the pull request's branch. The pull request cannot merge before its data is in S3 and its locks name it.

Every tool directory has a tracked test-data.lock that parseLock in scripts/s3/test-data-archive.mjs accepts. A tool directory is a packs/<id>/upstream/<tool>/ with a tracked file outside publish/; files directly under packs/<id>/upstream/, such as common.py, are in none. A tool-pack with a tracked publish/ needs no lock: the publish writes it.

• Format: { "format": 1, "sha256", "files", "bytes" }; sha256 is 64-digit lowercase hex, counts are non-negative integers.
• samples.lock (optional) pins the tool-pack's real-code samples archive the same way; parseLock must accept it too.
• Findings: a missing lock is reported at the path it would have; a malformed one carries parseLock's message.

These checks have no exemptions.

String-literal paths resolve against the including file and concat!(env!("CARGO_MANIFEST_DIR"), "…") against the crate. Other arguments, such as fixtures_dir!() or OUT_DIR, are skipped.

Exemption test-inputs: a test-only include may read fixtures/**, packs/** or a *.generated.* file. An include is test-only when it is:

• in tests.rs, *_tests.rs, test_support.rs or under native/tests/; or
• inside the item a #[cfg(test)] attribute applies to: its brace-matched body (comments and string and character literals skipped), or up to its ; when it has none.

#[cfg(test)] mod tests; declares a module in another file and exempts nothing after it.

A generator is any of:

• every manifest row's generator (scripts/generate/README.md, #25);
• every path a generated file's Generated by <path>; do not edit. header names;
• any script named generate, generate_* or generate-* (extension .mjs .cjs .js .ts .mts .py .php).

Exemption data-roots: pack generators sit beside the expected findings they write, under fixtures/ or packs/<id>/upstream/; generated files there are not scanned for headers.

The document's REUSE-resolved licence, as a set of AND terms, is compared with the pack's license. In REUSE.toml the last matching [[annotations]] applies: override wins outright, otherwise an in-file SPDX-License-Identifier or a .license sidecar wins; aggregate combines.

• packs/<id>/rules/**: equal (the package's licence describes exactly what it ships).
• packs/<id>/candidates/**: only terms the pack declares (Rerail's own probe rules are Apache-2.0 alone).

Copied pack test data is not in git, so this metric checks rule documents only. packs/<id>/licenses/<project>/UPSTREAM.md records copied files by pattern; pack check 6 checks the pulled data against those patterns.

• Files: every packs/<id>/ has pack.json, package.json, README.md, LICENSE, NOTICE.
• <id>: lowercase letters, digits and dashes.
• pack.json: rerail.rule-pack/v1 with id = <id>; lists only tracked documents, and every file in rules/.
• name: no brackets, digits or tool from the pack's conformance.json. README.md opens with # Rerail rule pack: <name> and candidates/README.md with # Rerail rule pack: <name>, candidates. A published pack has a row for it in the docs/rule-packs.md table.
• package.json: @neralabs/rerail-pack-<id>, with a license, no dependencies, and files publishing pack.json, rules, LICENSE.

Every fixtures/<family>/ has languages/<family>.json or packs/<family>/, or is a declared shared family: ecma (ECMAScript oracles shared by the javascript and typescript languages and their packs), host or packs (not tied to a language). Every pack holds at least one rule document in rules/, or in candidates/rules/ while it ships none because all its ports are candidates.

The lint's entry is checkBoundaries(root, { files }). Its rules are stated in its header and tested in test/structure/boundaries.test.mjs:

• engine-isolation: src/engine/ imports no other layer.
• host-isolation: no host imports another.
• layer-order: each layer imports only the layers listed for it, the order in src/README.md.
• src-self-contained: src/ imports nothing outside src/.
• entry-points: code outside src/ imports a layer's index.ts or src/index.ts. Unit tests under test/<layer>/ may import their own layer's internals, and a vitest mock seam names the module it replaces.

A file resolves a fixtures root when it writes any of:

• on a path-building line (join(, resolve(, URL(, Path::new(, PathBuf::from(, ||, ??, pathlib /), a relative path literal whose first component is fixtures;
• the bare segment "fixtures" as a direct argument of a join(/resolve( call whose earlier arguments are one root (any balanced expression) and then only "."/".." segments. The call may span lines: join(here, "..", "fixtures"), resolve(process.cwd(), "fixtures"), path.join(repoRoot(), "fixtures");
• the bare segment anywhere on a path-building line of a file that reads the RERAIL_ORACLES_DIR override.

Compared literals (startsWith(, ===, …), name lists and deeper segments (join(root, "labels", "fixtures")) do not count.

Exemptions: data-roots (generators write beside themselves) and structure-gate (this gate and its tests).

• rule-id: no rule id is defined by two rule documents across packs/*/{rules,candidates}/**. Exemption option-variant: documents under packs/<p>/candidates/<rule>/ (any depth) whose id is <rule> or ends :<rule> may share it with each other and with packs/<p>/rules/<rule>.json.
• pack-format, conformance-format: all pack.json files share one format, and all conformance.json files share one (absent = untagged). Files differing from the most common are reported. Exemption validator-inputs: fixtures/** (deliberately malformed inputs included).
• harness-import: code in a pack-specific directory (packs/<id>/, conformance/<id>/, test/conformance/<id>/ for a pack <id>) is imported only by code for the same pack.

The .generated infix (#20) is not part of a stem: builtins.generated.rs is checked as builtins. Exemptions: data-roots (named after upstream tools and engine modules), vendored, fixture-trees (framework route files such as pages/_app.tsx).

A binary has a NUL byte in the first 8000 bytes, or a known binary extension. The last matching .gitattributes line wins; -filter, !filter or another filter= unsets. Patterns follow gitattributes: a pattern without / matches the basename anywhere; otherwise it is anchored to the declaring .gitattributes. A checkout without LFS content holds text pointers, which pass.

A file is generated when it is named *.generated.*, or its first five lines say "generated by", carry the at-sign generated tag, or say "do not edit". Commentable means not JSON and not binary.

Exemptions: data-roots (pack test data follows the fixtures convention) and tool-owned (*.lock, package-lock.json, .changeset/README.md). The manifest and this gate are not scanned.

• The manifest exists whenever a *.generated.* file does.
• Every row's generated path and generator are tracked, the generator under scripts/generate/ (#6).
• Every *.generated.* file is covered by a row.
• A header naming a generator names the row's.

The gate expands every run: script in .github/workflows/ci.yml through npm scripts, transitively (npm run, npm test, npm --prefix <dir>, cd). It collects what runs:

• vitest, by --dir, --config directory and filters, minus the package's vitest.config.* exclude globs;
• node --test and pytest;
• playwright test, the spec files under its config's testDir;
• entry points: node/tsx/python/bash files.