Trellis

Active open-source package · MIT License

Trellis gives JavaScript and TypeScript teams one strict Biome policy for repeatable correctness, security, and maintainability checks. It also turns active findings into deterministic JSON todos that coding agents can implement and reviewers can diff.

Install Trellis

Install exact package and peer-dependency versions at the consumer repository root:

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

Create biome.json:

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

The repository’s existing biome check command now enforces the shared policy. No Trellis wrapper is required.

See the policy handoff

Given a risky shortcut:

process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";

Biome reports the blocking rule with its reason and replacement direction:

readme-proof.ts:1:1 plugin

  × RT006: TLS certificate verification must remain enabled.
    Fix the trust store or certificate chain instead.

  > 1 │ process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This capture is checked against the pinned Biome version and the RT006 fixture in the test suite. Trellis can also produce an agent-readable todo:

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

{
  "id": "trellis-<stable-fingerprint>",
  "status": "open",
  "severity": "error",
  "rule": "RT006",
  "message": "Do not disable TLS certificate verification.",
  "replacement": "Use a trusted CA or a scoped test transport."
}

The JSON report is a handoff artifact, not a second policy engine. Report generation succeeds when error-level todos exist; the repository’s Biome check remains the gate.

Why use Trellis

• Share objective policy. Keep repeatable rules consistent across repositories.
• Keep exceptions local. Product architecture, framework rules, and justified suppressions stay with the repository that owns them.
• Give agents stable work. Todo IDs derive from the file, category, message, and same-message occurrence, so unrelated line movement does not rewrite the list.
• Prefer clear replacements. Shared rules belong here only when they identify an objective problem with an actionable alternative.

Current policy

Policy	Implementation	Gate
Common correctness mistakes	Biome recommended rules	Biome defaults
Type-system escape	noExplicitAny	Error
Parameter reassignment	noParameterAssign	Error
Dynamic execution	noGlobalEval and noImpliedEval	Error and audit warning
Disabled TLS verification	Trellis GritQL plugins	Error
Complexity above 25	Biome cognitive complexity	Warning
Functions over 150 nonblank lines	Trellis policy	Warning
Files over 500 nonblank lines	Trellis policy	Warning
More than five parameters	Trellis policy	Warning
Non-null assertions	noNonNullAssertion	Warning

Warnings identify structural debt that needs human judgment. Trellis does not ban console output, nested ternaries, comments, UI patterns, or other context-dependent choices. The rule rationale lives in docs/rules/.

Compatibility and boundaries

Trellis covers .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, and .cts. Consumers own generated-file exclusions, source scope, framework rules, import boundaries, and architecture checks.

Plugin paths require a physical root node_modules directory. Yarn Plug’n’Play without one is not supported. In a monorepo, install both packages at the root and let nested Biome configurations extend //.

Use narrow suppressions with a reason when a reviewed exception is necessary:

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

Codex users can install the remediation workflow from the public Raintree marketplace:

codex plugin marketplace add raintree-technology/plugins
codex plugin add trellis@raintree

Raintree open-source system

Trellis owns shared JavaScript and TypeScript code policy. It can be used independently. Raintree Standards defines governed requirements, DocPull acquires evidence, HIG Doctor audits interfaces, and PolicyStrata tests cross-layer policy behavior. See the Raintree open-source portfolio.

Project policies

npm package · Contributing · Code of Conduct · Security · Changelog · Source repository · MIT License