npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@q9labsai/gates

v0.4.1

Published

Diff-aware static-check orchestration for q9labs repositories

Readme

@q9labsai/gates

@q9labsai/gates is a diff-aware quality gate for pnpm repositories. It classifies a Git diff, explains why each configured lane will run or skip, schedules independent lanes concurrently, runs exclusive lanes alone, and always writes a schema-v1 gate.report.json.

The package requires Node 24 or newer. A TypeScript gate.config.ts loads through Node's native type stripping, so no config loader is needed.

Install

pnpm add -D @q9labsai/gates

Add a root script and initialize the project-owned files:

{
  "scripts": {
    "gate": "q9gate run --staged"
  }
}
pnpm q9gate init

init writes gate.config.ts, .semgrep/project.yml, gates/baselines/README.md, gates/test-presence-exclusions.json, osv-baseline.json, cspell-baseline.txt, and a Lefthook pre-commit command. It refuses to overwrite a file unless --force is present. If lefthook.yml already exists, it prints the snippet instead of changing the file.

Configuration

import { defineGate, lanes } from "@q9labsai/gates";

export default defineGate({
  workspaceRoots: ["apps", "packages", "convex"],
  targets: { web: ["apps/web", "packages/ui"] },
  classifiers: {
    source: [".ts", ".tsx", ".mjs", ".cjs", ".js", ".jsx"],
    docs: ["scratchpad/", "*.md", "*.mdx", "*.txt"],
    dependency: ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml"],
    gateDefinition: ["gate.config.ts", "lefthook.yml", "turbo.json"],
    infra: ["infra/"],
    contract: ["packages/contracts/"],
    env: ["packages/env/src/env.ts"],
  },
  concurrency: "50%",
  lanes: [
    lanes.typecheck(),
    lanes.lint(),
    lanes.format(),
    lanes.test(),
    lanes.build(),
    lanes.i18n(),
    lanes.osv(),
    lanes.cspell(),
    lanes.hygiene(),
  ],
});

classify() recognizes source, test, docs, dependency, gateDefinition, infra, contract, workflow, shell, sql, env, and ui. Configured classifier patterns extend the defaults. Paths that do not match any category fail closed and force a full gate.

The planner applies these rules before lane triggers:

  • A gate-definition change or --full runs every lane.
  • A documentation-only change runs cspell and hygiene, plus any lane whose triggers is set to "always".
  • A dependency change forces osv, syncpack, version-drift, typecheck, and build.
  • Every other lane runs when its declared categories match. The plan prints the matching count or the skip reason before execution starts.

Set triggers: "always" on a built-in or custom lane to run it for every non-empty diff, including documentation-only changes. An empty diff does not select an always-on trigger unless --full is used.

Targets may name path roots in the gate config. For example, targets: { web: ["apps/web", "packages/ui"] } lets q9gate run --target web plan only files under those roots and passes those roots to lane runners as workspaceRoots. Changes to gate-definition files still force every lane, even when they fall outside the selected target. An unknown target is an error.

Custom trigger functions and runners receive context.target, the selected target name or undefined when no target is active. context.changedFiles and context.classification contain the files remaining after target filtering; context.allChangedFiles contains the complete changed-file list before filtering. Without a target, allChangedFiles and changedFiles contain the same paths.

concurrency accepts a positive integer or a percentage such as "50%". Percentage values use os.availableParallelism(). typecheck, test, build, tofu, and generated-drift lanes are exclusive and run without another lane beside them.

CLI

q9gate run [--staged | --base <ref> | --full] [--files <path>...] [--target <name>] [--lane <id>...] [--concurrency N|N%] [--json] [--paranoid]
q9gate init [--force]
q9gate doctor
q9gate why <file>
q9gate accept-baseline <lane> --message "why"

run defaults to the union of staged files and committed changes since the merge base with the default base ref, when one exists. --base uses <ref>...HEAD; --full uses every tracked and unignored file. Repeat --files to use an explicit file list instead of the Git diff; paths must be repo-relative and exist in the worktree or the selected diff base. GATE_FILES provides the same source as a comma- or newline-separated environment value, and explicit --files takes precedence when both are set. Repeat --lane to run explicit configured lanes. The command always writes gate.report.json, returns a nonzero status when a lane fails, and also prints the JSON when --json is present. --paranoid compares git status --porcelain before and after each lane and fails a lane that changes the tree.

doctor validates declared baselines, checks tools required by configured lanes' commands with install hints, scans workspace scripts and gate wiring for unsafe or placeholder commands, and points to run --paranoid for runtime immutability checks. Custom lanes require no tool probe unless doctorTools is supplied; a configured pnpm run command is checked against the actual script name. why classifies one relative path and prints every lane's reason. accept-baseline requires an approval message and writes it with a timestamp into the lane's declared baseline data.

Lane reference

Missing required commands fail their lane with an install hint. The tofu lane treats TFLint and Trivy as optional: a missing optional tool adds a finding and increments toolsSkipped, but does not fail the lane.

| Factory and lane id | Options | Trigger categories | Baseline | Behavior | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | lanes.typecheck() / typecheck | command, args; defaults to pnpm run typecheck | source, test, dependency, contract | none | Runs alone. | | lanes.lint() / lint | config, typeAware; type-aware mode defaults on when oxlint-tsgolint resolves | source, ui | none | Runs Oxlint on matching changed files, or . for a full gate. | | lanes.format() / format | config | source, docs, gateDefinition, env, workflow, shell | none | Runs oxfmt --check on matching changed files, or . for a full gate. The docs-only planner rule still skips it. | | lanes.test() / test | command, args; defaults to pnpm run test | source, test, contract | none | Runs alone. | | lanes.build() / build | command, args; defaults to pnpm run build | source, test, dependency, contract | none | Runs alone. | | lanes.fallow() / fallow | baselineDir, default gates/baselines/fallow | source | dead-code.json, health.json, and dupes.json in baselineDir when present | Sends the staged diff to Fallow or uses --changed-since for branch scope; emits dead-code, duplication, complexity, and dependency metrics when Fallow reports them. | | lanes.semgrep() / semgrep | packs, default [".semgrep"]; optional baselinePath | source, ui | optional JSON file via baselinePath | Resolves package-exported and project YAML packs and repeats --config for each. Selective runs scan changed source files; full runs scan the whole tree. Baselines ratchet stable findings, while skipped-file parse errors remain visible warnings. | | lanes.depcruise() / depcruise | config, default .dependency-cruiser.cjs; source, default . | source, contract | none | Runs Dependency Cruiser with the project config. | | lanes.designTokens() / design-tokens | baselinePath, default gates/baselines/design-tokens.json; roots, ignore, kinds | source, ui | entries of { file, kind, value, count } | Fails on a raw color, spacing, radius, font size or shadow with no baseline slot; a moved line is neutral and a removed one fails until the baseline shrinks. | | lanes.osv() / osv | baselinePath, default osv-baseline.json; optional exclude, replacing the defaults scratchpad and .worktrees | dependency | osv-baseline.json | Runs OSV-Scanner, normalizes findings by source, package, version, ecosystem, and advisory id, and fails on findings absent from the reviewed baseline. | | lanes.gitleaks() / gitleaks | mode (dir default or git), logOpts (git only), baselinePath/baseline, config | always, except the docs-only override | optional supplied JSON path | Runs gitleaks detect --source . --redact --verbose by default; git mode passes history options. | | lanes.cspell() / cspell | baselinePath, default cspell-baseline.txt; optional tracked paths | every category | cspell-baseline.txt | Runs CSpell through a stdin file list and fails only on normalized issue lines absent from the text baseline. | | lanes.syncpack() / syncpack | optional args, replacing the default ["lint"] | dependency | none | Runs syncpack lint by default, or the supplied arguments. | | lanes.testPresence() / test-presence | sourceRoots, default ["src"]; exclusionsPath, default gates/test-presence-exclusions.json | source, test | none | Requires meaningful source files to have a nearby test, be imported by a test, or have a reviewed exclusion with a useful reason. | | lanes.reactDoctor() / react-doctor | command, default react-doctor; scanCommand, default react-scan; requireScanCli, default false | ui | none | Passes q9gate's resolved base to React Doctor when known, including during --full; without a base, React Doctor uses its normal full-scan behavior. Also verifies the React Scan runtime, lite instrumentation, and Vite plugin surfaces. | | lanes.shellcheck() / shellcheck | none | shell | none | Checks changed *.sh files, or every tracked shell file for a full gate. | | lanes.actionlint() / actionlint | none | workflow | none | Checks changed workflow files, or all workflows for a full gate. | | lanes.tofu() / tofu | none | infra | none | Runs alone: tofu fmt -check -recursive, tofu validate for each infra/stacks/* directory, TFLint per stack, and trivy config infra. | | lanes.contractDrift() / contract-drift | required generate command; optional diff paths | contract | none | Runs alone, detects generated changes, reports the scoped diff, and restores every path changed by the generator. It refuses to run when the tree already has unstaged or untracked changes because those changes cannot be restored safely. | | lanes.convexCodegenDrift() / convex-codegen-drift | none | contract | none | Applies the same restore-safe drift check to convex codegen and fails with an install hint when Convex is absent. | | lanes.envContract() / env-contract | required schema module and sources globs | env | none | Loads the schema's exported keys() or uses a static fallback, then compares it with Wrangler vars, dotenv keys, and OpenTofu outputs. | | lanes.bundleSize() / bundle-size | required budgets map; values are bytes or strings such as "250 kB" | source, ui, dependency | none | Measures raw and gzip bytes under each target's dist, build, lib, or .output directory and fails over budget. | | lanes.versionDrift() / version-drift | none | dependency | none | Reads pnpm workspace manifests only, compares dependency ranges with the root catalog, and reports duplicate majors. | | lanes.migrationSafety() / migration-safety | required migration dir | sql | none | Rejects DROP, ALTER ... TYPE, and new NOT NULL constraints unless the previous line starts with -- expand-contract:. | | lanes.hygiene() / hygiene | commitScriptPath, default scripts/gates/commit.sh; configPath, default gate.config.ts | always | none | Rejects missing root script aliases, no-op and placeholder scripts, passWithNoTests, live dev/deploy/release commands, and mutating gate commands. | | lanes.i18n() / i18n | format (po by default or json), catalogGlob, sourceLocale, allowlistPath | changed catalogs or source files; always in --full | none | Checks message parity, ICU arguments, Arabic plural categories, and untranslated strings. | | lanes.custom() / configured id | required id, title, triggers, and run; optional exclusive, doctorTools | supplied category list or trigger function | none | Runs a shell command string or a typed LaneRunner as a project escape hatch. | | | | | | | | 655ecc9 | | Factory and lane id | Options | Trigger categories | Baseline | Behavior | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | lanes.typecheck() / typecheck | command, args; defaults to pnpm run typecheck | source, test, dependency, contract | none | Runs alone. | | lanes.lint() / lint | config, typeAware; type-aware mode defaults on when oxlint-tsgolint resolves | source, ui | none | Runs Oxlint on matching changed files, or . for a full gate. | | lanes.format() / format | config | source, docs, gateDefinition, env, workflow, shell | none | Runs oxfmt --check on matching changed files, or . for a full gate. The docs-only planner rule still skips it. | | lanes.test() / test | command, args; defaults to pnpm run test | source, test, contract | none | Runs alone. | | lanes.build() / build | command, args; defaults to pnpm run build | source, test, dependency, contract | none | Runs alone. | | lanes.fallow() / fallow | baselineDir, default gates/baselines/fallow | source | dead-code.json, health.json, and dupes.json in baselineDir when present | Sends the staged diff to Fallow or uses --changed-since for branch scope; emits dead-code, duplication, complexity, and dependency metrics when Fallow reports them. | | lanes.depcruise() / depcruise | config, default .dependency-cruiser.cjs; source, default . | source, contract | none | Runs Dependency Cruiser with the project config. | | lanes.designTokens() / design-tokens | baselinePath, default gates/baselines/design-tokens.json; roots, ignore, kinds | source, ui | entries of { file, kind, value, count } | Fails on a raw color, spacing, radius, font size or shadow with no baseline slot; a moved line is neutral and a removed one fails until the baseline shrinks. | | lanes.osv() / osv | baselinePath, default osv-baseline.json | dependency | osv-baseline.json | Runs OSV-Scanner, normalizes findings by source, package, version, ecosystem, and advisory id, and fails on findings absent from the reviewed baseline. | | lanes.gitleaks() / gitleaks | baselinePath or its baseline alias; optional config | always, except the docs-only override | optional supplied JSON path | Runs gitleaks detect --source . --redact --verbose. | | lanes.cspell() / cspell | baselinePath, default cspell-baseline.txt; optional tracked paths | every category | cspell-baseline.txt | Runs CSpell through a stdin file list and fails only on normalized issue lines absent from the text baseline. | | lanes.syncpack() / syncpack | none | dependency | none | Runs syncpack lint. | | lanes.testPresence() / test-presence | sourceRoots, default ["src"]; exclusionsPath, default gates/test-presence-exclusions.json | source, test | none | Requires meaningful source files to have a nearby test, be imported by a test, or have a reviewed exclusion with a useful reason. | | lanes.reactDoctor() / react-doctor | command, default react-doctor; scanCommand, default react-scan | ui | none | Passes q9gate's resolved base to React Doctor when known, including during --full; without a base, React Doctor uses its normal full-scan behavior. Also verifies the React Scan runtime, lite instrumentation, and Vite plugin surfaces. | | lanes.shellcheck() / shellcheck | none | shell | none | Checks changed *.sh files, or every tracked shell file for a full gate. | | lanes.actionlint() / actionlint | none | workflow | none | Checks changed workflow files, or all workflows for a full gate. | | lanes.tofu() / tofu | none | infra | none | Runs alone: tofu fmt -check -recursive, tofu validate for each infra/stacks/* directory, TFLint per stack, and trivy config infra. | | lanes.contractDrift() / contract-drift | required generate command; optional diff paths | contract | none | Runs alone, detects generated changes, reports the scoped diff, and restores every path changed by the generator. It refuses to run when the tree already has unstaged or untracked changes because those changes cannot be restored safely. | | lanes.convexCodegenDrift() / convex-codegen-drift | none | contract | none | Applies the same restore-safe drift check to convex codegen and fails with an install hint when Convex is absent. | | lanes.envContract() / env-contract | required schema module and sources globs | env | none | Loads the schema's exported keys() or uses a static fallback, then compares it with Wrangler vars, dotenv keys, and OpenTofu outputs. | | lanes.bundleSize() / bundle-size | required budgets map; values are bytes or strings such as "250 kB" | source, ui, dependency | none | Measures raw and gzip bytes under each target's dist, build, lib, or .output directory and fails over budget. | | lanes.versionDrift() / version-drift | none | dependency | none | Reads pnpm workspace manifests only, compares dependency ranges with the root catalog, and reports duplicate majors. | | lanes.migrationSafety() / migration-safety | required migration dir | sql | none | Rejects DROP, ALTER ... TYPE, and new NOT NULL constraints unless the previous line starts with -- expand-contract:. | | lanes.hygiene() / hygiene | commitScriptPath, default scripts/gates/commit.sh; configPath, default gate.config.ts | always | none | Rejects missing root script aliases, no-op and placeholder scripts, passWithNoTests, live dev/deploy/release commands, and mutating gate commands. | | lanes.i18n() / i18n | catalogGlob, sourceLocale, allowlistPath | changed catalogs or source files; always in --full | none | Checks message parity, ICU arguments, Arabic plural categories, and untranslated strings. | | lanes.custom() / configured id | required id, title, triggers, and run; optional exclusive | supplied category list or trigger function | none | Runs a shell command string or a typed LaneRunner as a project escape hatch. | | | | | | | | f26eaf9 | | Factory and lane id | Options | Trigger categories | Baseline | Behavior | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | lanes.typecheck() / typecheck | command, args; defaults to pnpm run typecheck | source, test, dependency, contract | none | Runs alone. | | lanes.lint() / lint | config, typeAware; type-aware mode defaults on when oxlint-tsgolint resolves | source, ui | none | Runs Oxlint on matching changed files, or . for a full gate. | | lanes.format() / format | config | source, docs, gateDefinition, env, workflow, shell | none | Runs oxfmt --check on matching changed files, or . for a full gate. The docs-only planner rule still skips it. | | lanes.test() / test | command, args; defaults to pnpm run test | source, test, contract | none | Runs alone. | | lanes.build() / build | command, args; defaults to pnpm run build | source, test, dependency, contract | none | Runs alone. | | lanes.fallow() / fallow | baselineDir, default gates/baselines/fallow | source | dead-code.json, health.json, and dupes.json in baselineDir when present | Sends the staged diff to Fallow or uses --changed-since for branch scope; emits dead-code, duplication, complexity, and dependency metrics when Fallow reports them. | | lanes.depcruise() / depcruise | config, default .dependency-cruiser.cjs; source, default . | source, contract | none | Runs Dependency Cruiser with the project config. | | lanes.designTokens() / design-tokens | baselinePath, default gates/baselines/design-tokens.json; roots, ignore, kinds | source, ui | entries of { file, kind, value, count } | Fails on a raw color, spacing, radius, font size or shadow with no baseline slot; a moved line is neutral and a removed one fails until the baseline shrinks. | | lanes.osv() / osv | baselinePath, default osv-baseline.json | dependency | osv-baseline.json | Runs OSV-Scanner, normalizes findings by source, package, version, ecosystem, and advisory id, and fails on findings absent from the reviewed baseline. | | lanes.gitleaks() / gitleaks | mode (dir default or git), logOpts (git only), baselinePath/baseline, config | always, except the docs-only override | optional supplied JSON path | Runs gitleaks detect --source . --redact --verbose by default; git mode passes history options. | | lanes.cspell() / cspell | baselinePath, default cspell-baseline.txt; optional tracked paths | every category | cspell-baseline.txt | Runs CSpell through a stdin file list and fails only on normalized issue lines absent from the text baseline. | | lanes.syncpack() / syncpack | optional args, replacing the default ["lint"] | dependency | none | Runs syncpack lint by default, or the supplied arguments. | | lanes.testPresence() / test-presence | sourceRoots, default ["src"]; exclusionsPath, default gates/test-presence-exclusions.json | source, test | none | Requires meaningful source files to have a nearby test, be imported by a test, or have a reviewed exclusion with a useful reason. | | lanes.reactDoctor() / react-doctor | command, default react-doctor; scanCommand, default react-scan | ui | none | Passes q9gate's resolved base to React Doctor when known, including during --full; without a base, React Doctor uses its normal full-scan behavior. Also verifies the React Scan runtime, lite instrumentation, and Vite plugin surfaces. | | lanes.shellcheck() / shellcheck | none | shell | none | Checks changed *.sh files, or every tracked shell file for a full gate. | | lanes.actionlint() / actionlint | none | workflow | none | Checks changed workflow files, or all workflows for a full gate. | | lanes.tofu() / tofu | none | infra | none | Runs alone: tofu fmt -check -recursive, tofu validate for each infra/stacks/* directory, TFLint per stack, and trivy config infra. | | lanes.contractDrift() / contract-drift | required generate command; optional diff paths | contract | none | Runs alone, detects generated changes, reports the scoped diff, and restores every path changed by the generator. It refuses to run when the tree already has unstaged or untracked changes because those changes cannot be restored safely. | | lanes.convexCodegenDrift() / convex-codegen-drift | none | contract | none | Applies the same restore-safe drift check to convex codegen and fails with an install hint when Convex is absent. | | lanes.envContract() / env-contract | required schema module and sources globs | env | none | Loads the schema's exported keys() or uses a static fallback, then compares it with Wrangler vars, dotenv keys, and OpenTofu outputs. | | lanes.bundleSize() / bundle-size | required budgets map; values are bytes or strings such as "250 kB" | source, ui, dependency | none | Measures raw and gzip bytes under each target's dist, build, lib, or .output directory and fails over budget. | | lanes.versionDrift() / version-drift | none | dependency | none | Reads pnpm workspace manifests only, compares dependency ranges with the root catalog, and reports duplicate majors. | | lanes.migrationSafety() / migration-safety | required migration dir | sql | none | Rejects DROP, ALTER ... TYPE, and new NOT NULL constraints unless the previous line starts with -- expand-contract:. | | lanes.hygiene() / hygiene | commitScriptPath, default scripts/gates/commit.sh; configPath, default gate.config.ts | always | none | Rejects missing root script aliases, no-op and placeholder scripts, passWithNoTests, live dev/deploy/release commands, and mutating gate commands. | | lanes.i18n() / i18n | catalogGlob, sourceLocale, allowlistPath | changed catalogs or source files; always in --full | none | Checks message parity, ICU arguments, Arabic plural categories, and untranslated strings. | | lanes.custom() / configured id | required id, title, triggers, and run; optional exclusive, doctorTools | supplied category list or trigger function | none | Runs a shell command string or a typed LaneRunner as a project escape hatch. |

Configure the env schema path in classifiers.env; otherwise a .ts schema change is only a source change and does not select env-contract. Configure a migration directory pattern in classifiers.sql when it differs from the default **/migrations/**/*.sql.

The i18n lane reads Lingui .po catalogs by default. Defaults match the template: apps/web/src/locales/*/messages.po, source locale en, and gates/i18n-allowlist.json. To check nested JSON catalogs, set format: "json" and configure catalogGlob to match their locale directories, for example:

i18n({
  format: "json",
  catalogGlob: "apps/portal/src/i18n/messages/*/*.json",
  sourceLocale: "en-US",
});

JSON string leaves become dot-separated message IDs. Multiple matching JSON files for one locale are combined; duplicate flattened keys fail the lane. Each non-source locale must have the same message IDs as the source locale; ICU argument names and types must match, and Arabic plural messages must include the CLDR cardinal categories zero, one, two, few, many, and other. gates/i18n-allowlist.json may contain reviewed { "locale", "id", "context?", "reason" } entries for intentional empty or source-identical strings. Exceptions do not skip catalog parity or ICU checks, and unused entries fail as stale.

Baselines

JSON ratchets use project-owned data shaped as follows:

{
  "count": 2,
  "entries": [],
  "acceptedAt": "2026-08-23T00:00:00.000Z",
  "message": "Reviewed debt"
}

OSV and tool-owned Fallow files keep their native entry shapes. CSpell uses one normalized issue per line and stores acceptance messages as # accepted ... comments. Native tool formats that cannot hold q9gate metadata use an adjacent .q9gate-acceptance.json file. accept-baseline is the package writer for approval metadata; it refuses lanes without a declared baseline.

The Semgrep lane accepts an optional baselinePath containing { "entries": [{ "file", "rule", "fingerprint" }] }. Each fingerprint includes the canonical rule id and repo-relative file path plus Semgrep's fingerprint (or a normalized source snippet when Semgrep omits one); line numbers alone are never used. New findings fail, accepted findings pass, and fixed entries can be removed from the baseline. Configure baselinePath to enable q9gate accept-baseline semgrep --message "why"; parse failures are shown as per-file warnings without failing the lane.

The design-token lane reads raw values (hex, functional and named colors, lengths, shadows) from CSS (including stylesheets inside template literals), Tailwind arbitrary values (text-[#123456], p-[13px]), inline styles and React Native style objects. A value inside a var() call is a token and never counts. The baseline key is file, kind and value, so a moved line stays neutral, and a violation that moves to another file takes a slot freed by the old one. A one-off exception needs a token-ratchet-ignore: <reason> comment on the line or the line above. List theme and token files, and files that cannot use CSS variables such as email templates, under ignore. q9gate accept-baseline design-tokens rewrites the baseline from the code and refuses when it would grow.

The pure helpers evaluateBaselineCount() and evaluateBaselineEntries() implement count and entry ratchets for custom lanes.

Report schema v1

gateReportSchema is a Zod runtime schema. validateGateReport(input) returns a typed report or throws, while isGateReport(input) is a type guard. Summary counts must equal the lane statuses.

{
  "schemaVersion": 1,
  "repo": "q9stack",
  "ref": "abc123",
  "scope": "branch",
  "base": "origin/main",
  "startedAt": "2026-08-23T00:00:00.000Z",
  "durationMs": 1250,
  "concurrency": 4,
  "lanes": [
    {
      "id": "fallow",
      "status": "passed",
      "reason": "12 source files changed",
      "durationMs": 320,
      "metrics": {
        "deadCode": 3,
        "dupes": 1,
        "complexityOverBaseline": 0
      },
      "baseline": { "before": 14, "after": 14 },
      "findings": [
        {
          "file": "packages/core/src/old.ts",
          "line": 1,
          "rule": "dead-code",
          "message": "Unused export"
        }
      ]
    }
  ],
  "summary": { "passed": 1, "failed": 0, "skipped": 0 }
}

Counting lanes emit stable metric names for dead code, duplicates, complexity, dependency issues, vulnerabilities, spelling, missing tests, env drift, bundle bytes, version drift, migration safety, infrastructure stacks, skipped optional tools, and checked files.

Library API

The root export includes defineGate, the lanes factory object, all named lane factories and option types, gate config and execution types, the report schema and types, classification and planning helpers, baseline ratchets, env-contract diffing, and migration scanning. Adapters for Git, processes, the filesystem, and terminal output remain internal.