@webority/repo-checks

Repository checks for Webority React web portals and React Native apps. One command reads every app package.json in the git repository and reports what the house rules say it must not have, must have, and how it must be pinned and installed.

It also counts raw measures, raw colours, root font sizes and palette reads in every tracked style, markup and script file of the repository (bootstrap-ui.md → Tokens).

Use

pnpm add -D --save-exact @webority/repo-checks
pnpm exec webority-repo-checks              # every app in the repository
pnpm exec webority-repo-checks apps/portal  # one app folder

An app is a package.json whose dependencies hold react-native (mobile) or react-dom (web). A react-dom folder that also has react-native-web is a react-native-web demo: it gets the pnpm and Biome checks, not the portal rules. Biome and @webority/biome-config are read from the package.json beside the biome.json in effect (a nested config with "root": false defers to the one above), so a sub-folder linted by the root config does not repeat them. A workspace:, file: or link: reference is local and never counts as a lockstep version. A package with agentation in its dependencies is a build tool, not an app. It and anything else (tooling roots, libraries) get only the lockfile check.

Every app also gets the Node checks: engines.node (from the app's package.json, else the one beside its pnpm-lock.yaml) must be >=24.15 <25, and the nearest .nvmrc must hold 24. A mobile app with an android/ folder gets the Android checks, and a web app's src/ the import checks. The missing-export:<file> check runs the Biome installed beside the app or in a folder above it, so it needs @biomejs/biome installed; without one it reports nothing, and the required:@biomejs/biome finding fails the app.

Comment lines (//, /*, *) and .test. or .spec. files are not read by the import checks.

Token rules: counted per file

The four rules read every tracked .scss, .css, .cshtml, .jsx and .tsx file, and each .js or .ts file that imports react-native. They skip a path with a node_modules, dist, generated, vendor, __tests__ or __mocks__ segment, an email template project folder (<Product>.Email or <Product>.Emails: email clients read no CSS variables, so inline pixels and colours are required there; a plain Email folder of admin screens stays checked), a path containing wwwroot/lib/, a .generated. name, a .min.css name, a .test. or .spec. script, and any path the repo lists under generated[].paths in .webority/map.json (a trailing / names a folder; * matches within one segment). List a compiled stylesheet there: it bundles the shared theme, so its library rules are not the product's code, and the rules still read the SCSS it is built from.

raw-measure counts a non-zero px, rem or em literal, or a bare number for a weight or a leading, in padding, margin, gap, inset, a corner, font size, font weight or line height: one finding per declaration or style key. A zero, a keyword (auto, bold, normal), a token (var(--wui-space-md)), a percentage or another unit, and a custom property or Sass variable declaration are not counted.

raw-colour counts a hex, an rgb(), rgba(), hsl() or hsla() with numeric arguments, or a CSS named colour, in a colour property or style key (including a fallback inside var(--color-x, #fff)). transparent, currentColor, a meaning read, a custom property or Sass variable declaration, and text inside a url() or a quoted string are not counted.

root-font-size counts every font-size or font declaration in a rule whose selector is html or :root (with or without an attribute, class or pseudo-class), whatever its value.

palette-read counts each var(--wui-<step>) and each phone palette. read, plus each var(--bs-<colour>), var(--bs-<colour>-rgb) and Sass $<colour> for Bootstrap's eight theme colours: one finding per read, and a declaration is not a read.

missing-canvas-key and repeated-canvas-key read every script module that imports react-native, @webority/mobile-ui or @webority/ui-react. The attribute is testID in a module that imports react-native or @webority/mobile-ui, and data-canvas in any other. A spread on the item counts as keyed, and a repeat adds one finding per tag after the first.

src/assets/styles/_home.scss:12: color: var(--wui-primary);
  (read the meaning: var(--color-primary))

New rules start as warnings

lint, rn-mainactivity-oncreate-bundle, spa-host-immutable-assets and oversize print as warnings and do not fail until REPO_CHECKS_ENFORCE names them: REPO_CHECKS_ENFORCE=lint,rn-mainactivity-oncreate-bundle, or all. A release removes a rule from the warning list when no repository has a hit. --json carries the warnings under warnings.

Existing findings: a baseline that only shrinks

A repository adopting the checks records what it has today, once:

pnpm exec webority-repo-checks --baseline-init

That writes .webority/baselines/repo-checks-baseline.json, creating the folder: the dependency findings as "<app folder> | <id>", and the code rules counted per file:

{
    "version": 2,
    "findings": ["apps/portal | banned:@webority/ui-elements", "samples/react-sandbox | required:@webority/web-core"],
    "counts": { "palette-read:packages/theme/scss/wui/_buttons.scss": 3, "raw-measure:src/assets/styles/_home.scss": 14 }
}

From then on a finding in the baseline is reported as known and does not fail; any other finding fails (exit 1). A count may only fall: a file above its recorded count fails and prints its lines, and a file missing from the baseline is at 0, so a new or renamed file starts at 0. After fixing old findings or lowering counts, --baseline-shrink drops the fixed findings and lowers each count to its current value, deleting one that reaches 0; it never adds or raises one.

--baseline-accept <folder> --reason <text> records debt the owner has accepted: every current finding and count under that folder is added, and a count is raised to its current value, never lowered. Use it only for debt the owner has accepted, and give a reason that names the decision; the reason is kept in accepted in the baseline file, and --baseline-shrink keeps that entry.

--baseline-adopt <rule,...> records today's findings and counts for rules the baseline has never recorded, such as a rule a new release adds. It refuses a rule the baseline already records, so it never raises an existing entry, and names how many findings and counts it adopted per rule.

--baseline-init runs once: it refuses an existing file and folder arguments. When the file is the earlier shape (no version), delete it and run --baseline-init once from the git root, then review the diff before committing.

--json prints { root, new, known, stale } for tools; a count above its record appears in new with its lines.

The shared pre-commit hook

Every repository runs the pre-commit hook this package ships. Adopt it once, from the git root:

pnpm exec webority-repo-checks --sync-hook

That writes .husky/pre-commit, creating .husky when it is missing, with LF line endings. A multi-app repository installs it once, at the root. husky stays the installer, through the prepare script. Remove lint-staged (pnpm remove lint-staged, and delete its config key): the shared hook runs Biome itself. Put repo-only steps in .husky/pre-commit.local; the shared hook runs that file after Biome, and --sync-hook never touches it.

hook:drift keeps the root copy equal to the shipped one.

Versioning

Published from the webority-ui monorepo in lockstep with the other @webority/* packages. Pin an exact version; a new rule arrives when you bump it.