@avi2dg/checks 0.45.1 → 0.46.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.46.0
+
+Released 2026-10-19.
+
+### Features
+
+- **quality:** refuse CSS comments, non-ASCII selectors and stylesheets over 400 lines [#172](https://github.com/avi2d/checks/pull/172)
+
 ## 0.45.1
 
 Released 2026-10-19.

package/README.md

@@ -172,6 +172,7 @@ The table groups the gates by vector, the part of a repository each one judges.
 | quality | [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
 | quality | [`checks-effect-scope`](docs/gates/checks-effect-scope.md) | the working tree | a repository tracking `oxlint.config.ts` |
 | quality | [`checks-frontend-syntax`](docs/gates/checks-frontend-syntax.md) | the working tree | a repository tracking `frontend-syntax.json` |
+| quality | [`checks-css-size`](docs/gates/checks-css-size.md) | the working tree | a repository tracking `*.css` |
 | quality | [`checks-no-plain-js`](docs/gates/checks-no-plain-js.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | testing | [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | testing | [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |

package/dist/presets/stylelint.js

@@ -13,6 +13,12 @@ var SELECTOR_COMPLEXITY = {
   "selector-max-specificity": "0,3,2",
   "selector-max-compound-selectors": 3
 };
+var COMMENT_REFUSAL = {
+  "comment-word-disallowed-list": ["/^[\\s\\S]*$/"]
+};
+var LANGUAGE_FREE_SELECTORS = {
+  "selector-disallowed-list": ["/[^\\x00-\\x7F]/"]
+};
 var COLOUR_FUNCTIONS = ["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color"];
 var DESIGN_TOKENS = {
   "color-no-hex": true,
@@ -61,6 +67,8 @@ function defineConfig({ baseline, tokens, rules, overrides = [], ...rest }) {
   const merged = {
     ...CONVENTION_CHANGES,
     ...SELECTOR_COMPLEXITY,
+    ...COMMENT_REFUSAL,
+    ...LANGUAGE_FREE_SELECTORS,
     [BASELINE_RULE]: [true, { available }],
     ...tokenRules.rules,
     ...rules

package/docs/design.md

@@ -145,14 +145,18 @@ The violation it catches is a deleted workflow step, so it has to fail in the lo
 It parses workflows with `Bun.YAML`, which the `bun` shebang already provides, so it adds no dependency.
 It reads `on` as a string key, not as the YAML 1.1 boolean.
 
-## Size and repetition only fail on growth
+## TypeScript size and repetition only fail on growth
 
-The size limits are oxlint's own rules at `error`, not a script of the kit's.
+The TypeScript size limits are oxlint's own rules at `error`, not a script of the kit's.
 A script of the kit's own would restate how oxlint reads its config and compares sites, and each restatement adds cases oxlint itself does not have.
 A repository records its existing violations with `oxlint --suppress-all`, and `checks-suppressions-ratchet` refuses any count that rises.
 The cost is that a file or function already over its limit can grow without adding a site the count sees.
 Each repository works its counts down to zero.
 
+`checks-css-size` holds each stylesheet to the same 400 lines as an absolute budget, with no count to ratchet.
+oxlint does not read CSS, and no maintained stylelint rule or plugin limits lines per file, so the budget is a kit script.
+A stylesheet already over 400 lines fails until it is split, whatever the suppression counts hold.
+
 `checks-repetition` runs jscpd at both ends of the range with the head's `.jscpd.json`, so the same `path` and `ignore` globs pick the files at both ends.
 It compares each file's count of repeated lines, and does not use jscpd's `--baseline-from-ref`.
 That flag reports a repeated block as new once its text changes, so a change that shortens an existing repeated block would fail.

package/docs/gates/checks-advisories.md

@@ -101,12 +101,13 @@ A range that leaves `bun.lock` unchanged runs in under a second, and one that ch
 
 ## Running it on a schedule
 
-A range never fails on an advisory published after its package landed, so a scheduled `--all` run finds those:
+A range never fails on an advisory published after its package landed, so a scheduled `--all` run finds those.
+A repository schedules it at minute 17 of its tier's 30 minute night window, so repositories do not start together:
 
 ```yaml
 on:
   schedule:
-    - cron: "41 4 * * *"
+    - cron: "17 22 * * *"
   workflow_dispatch:
 jobs:
   advisories:

package/docs/gates/checks-css-size.md

@@ -0,0 +1,53 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-css-size
+
+`checks-css-size` is the gate that holds each tracked stylesheet to 400 lines, the kit's own `max-lines` for code files.
+
+## What it checks
+
+It fails on every `*.css` file in the working tree that holds more than 400 lines.
+It counts every line, blank lines and comments included, the way `max-lines` counts code with blank lines and comments kept.
+Each line names the file and its line count, and tells its writer to split the stylesheet into smaller files.
+
+## What it reads
+
+It reads the working tree.
+It scans the tracked and untracked files that `git ls-files --cached --others --exclude-standard` reports.
+Ignore rules leave out untracked files only, so an untracked `node_modules/` is out of reach while a tracked stylesheet under an ignored directory is still measured.
+A local run agrees with CI before `git add`.
+
+## Arguments
+
+```sh
+checks-css-size [<directory>]
+```
+
+It checks the directory it runs in, or the directory it is given.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every stylesheet holds 400 lines or fewer |
+| 1 | a stylesheet holds more than 400 lines |
+| 2 | git does not list the working tree, or a listed stylesheet cannot be read |
+
+## Sample output
+
+```
+css-size: 1 violation(s)
+  src/styles.css: 1901 lines, over the 400-line budget; split the stylesheet into smaller files
+```
+
+## When it runs
+
+`checks-lint` runs it when the repository tracks a `*.css` file.
+
+## Related topics
+
+- [checks-frontend-syntax](checks-frontend-syntax.md)
+- [checks-lint](checks-lint.md)
+- [checks-repetition](checks-repetition.md)

package/docs/gates/checks-flake.md

@@ -101,12 +101,13 @@ Only a schedule the repository writes runs it.
 
 ## Running it on a schedule
 
-A repository runs it on a schedule and keeps the record of a failed run as an artifact:
+A repository runs it on a schedule and keeps the record of a failed run as an artifact.
+A repository schedules it at minute 27 of its tier's 30 minute night window, so repositories do not start together:
 
 ```yaml
 on:
   schedule:
-    - cron: "17 5 * * *"
+    - cron: "27 22 * * *"
   workflow_dispatch:
 jobs:
   flake:

package/docs/gates/checks-frontend-syntax.md

@@ -39,6 +39,8 @@ A control that needs selection off sets it on its own selector, such as `.drag-h
 | G3 selector complexity | `selector-max-specificity` at `0,3,2` and `selector-max-compound-selectors` at 3 | on |
 | G4 design tokens | `color-no-hex`, `color-named: "never"`, `function-disallowed-list` over `rgb`, `rgba`, `hsl`, `hsla`, `hwb`, `lab`, `lch`, `oklab`, `oklch` and `color`, and `font-size` only as one `var(--…)` with no fallback, or `inherit` | off until `tokens` names the token files, and off in those files |
 | G5 Baseline target | `plugin/use-baseline` from `stylelint-plugin-use-baseline`, which judges each property, value, function, at-rule, selector and unit against the Baseline data, and passes a property inside an `@supports` block. It passes `@property` at every target, since a browser without `@property` treats the declaration as an unregistered custom property | on, at the target `baseline` sets |
+| G6 comments refused | `comment-word-disallowed-list` over `/^[\s\S]*$/`, which refuses every comment, including an empty `/* */` | on |
+| G7 language-free selectors | `selector-disallowed-list` over `/[^\x00-\x7F]/`, which refuses any selector holding a non-ASCII character, in attribute values, class names and ids alike | on |
 
 The builder changes three of the shared config's rules:
 
@@ -47,7 +49,9 @@ The builder changes three of the shared config's rules:
 - `property-no-vendor-prefix` keeps reporting without a fix, and passes `-webkit-user-select`, since its fix deletes the prefix Safari still needs.
 - In an `.html` or `.astro` file, `declaration-block-single-line-max-declarations` is off, since a `style` attribute is one line.
 
+The comment rule refuses every comment but a sourcemap `/*# */` one, which stylelint passes to keep the map.
 CSS repetition is not a family of this gate: a repository adds `"css"` to `format` in `.jscpd.json`, and [checks-repetition](checks-repetition.md) then fails when a stylesheet's repeated lines grow.
+A stylesheet's length is not a family of this gate either, and [checks-css-size](checks-css-size.md) fails one that holds more than 400 lines.
 
 ### What no comment turns off
 
@@ -169,6 +173,7 @@ A repository without that file never runs it and needs neither `stylelint.config
 - [checks-browser](checks-browser.md)
 - [checks-lint](checks-lint.md)
 - [checks-comment-gate](checks-comment-gate.md)
+- [checks-css-size](checks-css-size.md)
 - [checks-suppressions-ratchet](checks-suppressions-ratchet.md)
 - [checks-repetition](checks-repetition.md)
 - [Native settings](../configs/native-settings.md)

package/docs/gates/checks-lint.md

@@ -14,6 +14,7 @@ Gates requiring tracked TypeScript files begin running when the repository track
 `checks-advisories` begins running when the repository tracks `bun.lock`.
 `checks-frontend-syntax` begins running when the repository tracks `frontend-syntax.json` at its root.
 `checks-copy` begins running when the repository tracks `copy.json` at its root.
+`checks-css-size` begins running when the repository tracks a `*.css` file.
 All other gates run for every repository.
 
 ## What it reads
@@ -48,7 +49,7 @@ With two arguments, the base and head override range discovery.
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 18 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 19 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->

package/docs/gates/checks-release-pr.md

@@ -80,13 +80,14 @@ Run the workflow by hand with `gh workflow run daily-release` to refresh the rel
 ## Running it in CI
 
 A repository takes the daily release as `.github/workflows/daily-release.yml`.
+A repository schedules it at minute 7 of its tier's 30 minute night window, so repositories do not start together.
 The `pull-request` job runs on the schedule, and the `tag` job runs when a release commit lands on `main`, as [checks-release-tag](checks-release-tag.md) says:
 
 ```yaml
 name: daily-release
 on:
   schedule:
-    - cron: "29 3 * * *"
+    - cron: "7 22 * * *"
   workflow_dispatch:
   push:
     branches: [main]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.45.1",
+  "version": "0.46.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -63,6 +63,7 @@
     "src/docs/prose-matchers.ts",
     "src/quality/comments.ts",
     "src/quality/comment-gate.ts",
+    "src/quality/css-size.ts",
     "src/quality/frontend-syntax.ts",
     "src/quality/browser/",
     "src/complexity/suppressions-ratchet.ts",
@@ -157,6 +158,7 @@
     "checks-subsumed-tests": "src/testing/subsumed-tests.ts",
     "checks-ci-wiring": "src/delivery/ci-wiring.ts",
     "checks-comment-gate": "src/quality/comment-gate.ts",
+    "checks-css-size": "src/quality/css-size.ts",
     "checks-suppressions-ratchet": "src/complexity/suppressions-ratchet.ts",
     "checks-repetition": "src/complexity/repetition.ts",
     "checks-unused": "src/complexity/unused.ts",

package/src/core/gates.ts

@@ -40,6 +40,8 @@ const OXLINT_CONFIG: TrackedContent = { pathspecs: ["oxlint.config.ts"], content
 
 const FRONTEND_SYNTAX_DECLARATION: TrackedContent = { pathspecs: ["frontend-syntax.json"], content: "a frontend syntax declaration" };
 
+const STYLESHEET: TrackedContent = { pathspecs: ["*.css"], content: "a stylesheet" };
+
 const COPY_DECLARATION: TrackedContent = { pathspecs: ["copy.json"], content: "a copy declaration" };
 
 export const KIT_GATES = [
@@ -49,6 +51,7 @@ export const KIT_GATES = [
   { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-effect-scope", vector: "quality", file: "effect-scope.ts", reads: "tree", args: ["--check"], appliesTo: OXLINT_CONFIG },
   { bin: "checks-frontend-syntax", vector: "quality", file: "frontend-syntax.ts", reads: "tree", appliesTo: FRONTEND_SYNTAX_DECLARATION },
+  { bin: "checks-css-size", vector: "quality", file: "css-size.ts", reads: "tree", appliesTo: STYLESHEET },
   { bin: "checks-no-plain-js", vector: "quality", file: "no-plain-js.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-suppressions-ratchet", vector: "complexity", file: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },

package/src/core/main.ts

@@ -26,3 +26,17 @@ export function runMain<E extends { readonly message: string }>(
   );
   BunRuntime.runMain(program, { teardown: (exit, onExit) => onExit(statusOf(exit)) });
 }
+
+export function runTreeGate<Outcome extends { readonly violations: readonly unknown[] }>(
+  name: string,
+  check: (root: string) => Effect.Effect<Outcome, { readonly message: string }, BunServices.BunServices>,
+  format: (result: Outcome) => string,
+): void {
+  const gate = Effect.gen(function* () {
+    const root = process.argv[2] ?? process.cwd();
+    const result = yield* check(root);
+    yield* Console.log(format(result));
+    return result.violations.length === 0;
+  });
+  runMain(name, gate);
+}

package/src/quality/css-size.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env bun
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { workingTreeFiles } from "../core/git.ts";
+import { runTreeGate } from "../core/main.ts";
+import { SOURCE_LIMITS } from "./presets/oxlint.ts";
+
+export type Violation = {
+  readonly file: string;
+  readonly line: number | undefined;
+  readonly message: string;
+};
+
+const NAME = "css-size";
+
+const LIMIT = SOURCE_LIMITS["max-lines"];
+
+const STYLESHEET = /\.css$/;
+
+export function lineCount(source: string): number {
+  if (source === "") return 0;
+  const parts = source.split("\n");
+  return source.endsWith("\n") ? parts.length - 1 : parts.length;
+}
+
+export function violationsOf(entries: readonly { readonly file: string; readonly lines: number }[]): readonly Violation[] {
+  return entries
+    .filter(({ lines }) => lines > LIMIT)
+    .toSorted((a, b) => (a.file < b.file ? -1 : 1))
+    .map(({ file, lines }) => ({
+      file,
+      line: undefined,
+      message: `${lines} lines, over the ${LIMIT}-line budget; split the stylesheet into smaller files`,
+    }));
+}
+
+class CssSizeError extends Schema.TaggedError<CssSizeError>()("CssSizeError", {
+  message: Schema.String,
+}) {}
+
+export type Result = { readonly files: number; readonly violations: readonly Violation[] };
+
+const listJudged = Effect.fn("listJudged")(function* (root: string) {
+  const listed = yield* workingTreeFiles(root).pipe(
+    Effect.mapError((cause) => new CssSizeError({ message: cause.message })),
+  );
+  return listed.filter((file) => STYLESHEET.test(file)).toSorted();
+});
+
+const measure = Effect.fn("measure")(function* (root: string, file: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const source = yield* fs.readFileString(path.join(root, file)).pipe(
+    Effect.mapError((cause) => new CssSizeError({ message: `cannot read ${file}: ${String(cause)}` })),
+  );
+  return { file, lines: lineCount(source) };
+});
+
+export const run = Effect.fn("run")(function* (root: string) {
+  const judged = yield* listJudged(root);
+  const entries = yield* Effect.forEach(judged, (file) => measure(root, file), { concurrency: "unbounded" });
+  return { files: judged.length, violations: violationsOf(entries) } satisfies Result;
+});
+
+export function report({ files, violations }: Result): string {
+  if (violations.length === 0) return `${NAME}: no stylesheet over ${LIMIT} lines among ${files} CSS file(s)`;
+  return [`${NAME}: ${violations.length} violation(s)`, ...violations.map(({ file, message }) => `  ${file}: ${message}`)].join("\n");
+}
+
+if (import.meta.main) runTreeGate(NAME, run, report);

package/src/quality/no-plain-js.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
-import { Console, Effect, Schema } from "effect";
+import { Effect, Schema } from "effect";
 import { workingTreeFiles } from "../core/git.ts";
-import { runMain } from "../core/main.ts";
+import { runTreeGate } from "../core/main.ts";
 
 export type Violation = {
   readonly file: string;
@@ -61,11 +61,4 @@ export function report({ files, violations }: Result): string {
   return [`${NAME}: ${violations.length} violation(s)`, ...violations.map(({ file, message }) => `  ${file}: ${message}`)].join("\n");
 }
 
-const noPlainJs = Effect.gen(function* () {
-  const root = process.argv[2] ?? process.cwd();
-  const result = yield* run(root);
-  yield* Console.log(report(result));
-  return result.violations.length === 0;
-});
-
-if (import.meta.main) runMain(NAME, noPlainJs);
+if (import.meta.main) runTreeGate(NAME, run, report);

package/src/quality/presets/stylelint.ts

@@ -31,6 +31,16 @@ const SELECTOR_COMPLEXITY = {
   "selector-max-compound-selectors": 3,
 } as const satisfies Rules;
 
+// [\s\S] without anchors passes an empty /**/, so the anchors refuse every comment text there is.
+const COMMENT_REFUSAL = {
+  "comment-word-disallowed-list": ["/^[\\s\\S]*$/"],
+} as const satisfies Rules;
+
+// A non-ASCII class refuses every language at once, where naming scripts would chase each one.
+const LANGUAGE_FREE_SELECTORS = {
+  "selector-disallowed-list": ["/[^\\x00-\\x7F]/"],
+} as const satisfies Rules;
+
 const COLOUR_FUNCTIONS = ["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color"] as const;
 
 const DESIGN_TOKENS = {
@@ -84,6 +94,8 @@ export function defineConfig({ baseline, tokens, rules, overrides = [], ...rest
   const merged: Rules = {
     ...CONVENTION_CHANGES,
     ...SELECTOR_COMPLEXITY,
+    ...COMMENT_REFUSAL,
+    ...LANGUAGE_FREE_SELECTORS,
     [BASELINE_RULE]: [true, { available }],
     ...tokenRules.rules,
     ...rules,