Trellis

Trellis turns Raintree Technology's shared engineering standards into a small, strict Biome preset. It catches correctness mistakes, risky shortcuts, security footguns, and structural debt in editors and CI. It can also export active findings as deterministic JSON todo lists with durable IDs and approved replacements for coding-agent handoffs.

Shared rules stay objective and useful across repositories. Product architecture, framework constraints, and justified exceptions stay in the repository that owns them.

Package surface

Trellis exports a Biome configuration for enforcement:

@raintree-technology/trellis/biome

It also exposes trellis todo, a reporting command that turns active Biome findings into agent-readable JSON. The command does not replace or wrap the repository's blocking Biome command.

Product-specific accessibility, framework, architecture, and file-scope settings stay in each repository.

Install

Install exact versions at the consumer repository root:

bun add --dev --exact @raintree-technology/trellis@0.3.0 @biomejs/biome@2.5.6

At the consumer repository root, create a small biome.json:

{
  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
  "extends": ["@raintree-technology/trellis/biome"]
}

The consumer keeps its own file scope, framework rules, import boundaries, and other local settings. Do not copy Trellis configuration or plugins into the consumer.

The shared plugin paths assume a physical node_modules directory at the consumer root. Yarn Plug'n'Play without a physical root node_modules install is not supported.

No Trellis command is required. The repository's existing biome lint or biome check command automatically includes the shared rules.

JSON todo report

Run Trellis from a consumer repository to turn its active policy findings into a deterministic JSON todo list:

bun run trellis todo
bun run trellis todo --output trellis-todo.json

The report is a handoff format for coding agents and reviewers: policy remains the enforcement layer, while the JSON list makes the active work explicit and diffable. The default report contains only Trellis findings. Use --all to include every diagnostic from the repository's Biome configuration, including local rules. Each todo includes a durable ID, severity, rule, source location, diagnostic, and approved replacement. IDs are based on the file, category, message, and same-message occurrence, so unrelated line movement does not change them. Generating a report succeeds even when it contains error-level todos; repository lint remains the blocking command.

In a monorepo, declare both packages in the root package.json. Keep the package export in the root Biome configuration. Nested configurations inherit from the root so plugin paths continue to resolve from one place:

{
  "root": false,
  "extends": ["//"]
}

Trellis covers .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, and .cts files. Consumers still own generated-file exclusions and source scope.

Current rules

Policy	Implementation	Status
Reject common correctness mistakes	Biome recommended rules	Biome defaults
Reject type-system escape	Biome noExplicitAny	Error
Reject parameter reassignment	Biome noParameterAssign	Error
Flag hard-to-follow functions	Cognitive complexity above 25	Warning
Flag oversized functions	More than 150 nonblank lines per function	Warning
Flag oversized files	More than 500 nonblank lines per file	Warning
Flag overloaded signatures	More than 5 parameters	Warning
Flag unchecked assumptions	Biome noNonNullAssertion	Warning
RT005: no dynamic execution	Biome noGlobalEval and noImpliedEval	Error and audit warning
RT006: do not disable TLS verification	Two Trellis GritQL plugins	Error

Errors cover shortcuts with a direct replacement: use a concrete type or unknown, and copy a parameter into a local variable before changing it. Warnings identify structural debt that needs human judgment before refactoring. Trellis does not ban console output, nested ternaries, comments, UI patterns, or other context-dependent choices.

Prefer a narrow inline suppression:

// biome-ignore lint/nursery/noImpliedEval: Required by the reviewed sandbox protocol.
const evaluator = new Function(source);

Adding a rule

A shared rule belongs in Trellis only when it is objective, useful in more than one repository, and has one clear replacement. Prefer a built-in Biome rule. Keep rules with product-specific exceptions in the product repository.

See RT005 and RT006 for the current catalog.