c3b-lint 0.0.1 → 0.0.2

package/README.md

@@ -10,8 +10,21 @@ markdown that a tool can check, with one command and one config to install. It r
    `!important`, max 3 compound selectors, kebab-case ids/classes with `is-*` states and `--` variants, `:root` only
    in `tokens.css` (and `reset.css`), token names `--{category}-{role}`, `rem` font sizes, `em` letter-spacing,
    never `dvh`, no styling off `data-*` (warning).
-3. The **500-line limit** on `src/**/*.{css,html}` (ESLint reports the JS).
-4. That the project's **`.editorconfig`** is the shared one — it carries the JetBrains `ij_*` code-style keys, so
+3. **Token hygiene** across all the CSS, which no per-file linter can do: a literal that duplicates a token's value
+   (`#2b4b6f` where `--color-primary` is that), a literal colour, font-family or spacing value used in two or more
+   rules (that is a token by definition), and a token nothing uses (CSS `var()`, or JS/HTML by name).
+4. **HTML** on every page under `src/` (partials are skipped): doctype, `lang`, charset, viewport without
+   `user-scalable=no`, the required head set (title, description, absolute canonical, `og:*` with an absolute
+   `og:image`, `twitter:card`, one SVG favicon; a `noindex` page is excused the canonical and social tags), stylesheet order (`reset`, `tokens`, `main`, …, page file last),
+   the skip-link rule (`<a id="skip-link" href="#main">` first in `<body>` when there is a header or nav, absent
+   otherwise, `<main id="main">`), one `<h1>`, `alt` on every image, no inline handlers, no `<style>` or `style=""`
+   (except a JS-driven custom property), relative paths only, kebab-case ids and classes, no duplicate ids,
+   `integrity` on CDN scripts.
+5. **Project structure**: singular directory names, lowercase kebab-case asset names (and no camera exports), CSS
+   only in `src/style/` + `style/page/` + `style/animation/`, JS only in `src/script/`, fonts only in
+   `src/asset/font/` as woff2, file names starting with a letter.
+6. The **500-line limit** on `src/**/*.{css,html}` (ESLint reports the JS).
+7. That the project's **`.editorconfig`** is the shared one — it carries the JetBrains `ij_*` code-style keys, so
    WebStorm and IntelliJ format the same way without committing `.idea/`.
 
 Formatting itself (indent, quotes, spacing) is not linted: the `.editorconfig` and the IDE own it.
@@ -23,27 +36,33 @@ npm install --save-dev c3b-lint
 npx c3b-lint --init
 ```
 
-`--init` writes three files at the project root, all to commit:
+`--init` writes four files at the project root, all to commit:
 
 - `.editorconfig` — the shared one (a copy; editors need a real file).
 - `eslint.config.js` and `stylelint.config.js` — one line each, re-exporting this package's configs, so WebStorm
   shows the same errors inline as the CLI reports. Bumping `c3b-lint` changes the rules everywhere.
+- `.githooks/pre-commit`, and `git config core.hooksPath .githooks` — the lint runs before every commit, so a
+  commit that fails it never lands, whoever makes it. The hook lives in the repo, so after a clone one `--init`
+  (or `npx c3b-lint --init` in `postinstall`) wires it up. If `node_modules` is missing it says so and lets the
+  commit through; the test gate catches it later.
 
 Then in `package.json`:
 
 ```json
+"postinstall": "c3b-lint --init",
 "lint": "c3b-lint",
 "pretest": "colab-partial --check && c3b-lint"
 ```
 
-so a lint error fails `npm test` and anything that runs it (`predeploy`).
+`postinstall` keeps the four files current and wires the hook on every clone with no extra step (`--init` only
+writes, it never fails an install); `pretest` makes a lint error fail `npm test` and anything that runs it.
 
 ## Usage
 
 ```
 c3b-lint            # lint; exits 1 on any error
-c3b-lint --fix      # apply the fixes ESLint and Stylelint consider safe (var -> const, braces, …)
-c3b-lint --init     # (re)write .editorconfig, eslint.config.js, stylelint.config.js
+c3b-lint --fix      # apply the fixes ESLint and Stylelint consider safe (var -> const, braces, …); reformat in the IDE after
+c3b-lint --init     # (re)write .editorconfig, eslint.config.js, stylelint.config.js, the pre-commit hook
 c3b-lint --help
 ```
 
@@ -51,7 +70,9 @@ The version is printed first, so you can tell which install is running.
 
 ## Not covered
 
-Rules that need judgement stay with review: when a literal should become a token, whether two selectors are
-structurally disjoint, flex vs grid, where a page style belongs. `no-descending-specificity` is off for the same
-reason. Java projects use [colab-checkstyle](https://codeberg.org/colab47/colab-checkstyle) and the same
+Rules that need judgement stay with review: whether two selectors are structurally disjoint, flex vs grid, whether
+a one-off literal should be a token anyway, where a component style belongs. `no-descending-specificity` is off for
+the same reason. The checks that need a browser (console errors, broken links and images, accessibility, overflow)
+stay in [c10g](https://codeberg.org/colab47/c10g); its SEO and duplicate-id suites now overlap with the HTML check
+here. Java projects use [colab-checkstyle](https://codeberg.org/colab47/colab-checkstyle) and the same
 `.editorconfig`.

package/c3b-lint.js

@@ -176,9 +176,13 @@ async function runStylelint() {
 // --- run ------------------------------------------------------------------
 
 async function main() {
+    // --init only writes: it runs from postinstall, where a lint failure must not fail npm install
     if (init) {
         writeBaseline();
         installHook((what) => console.log(`  write   ${ what }`));
+        console.log('Baseline written. Run c3b-lint to lint.');
+
+        return;
     }
 
     const report = createReport();

package/check/css-tokens.js

@@ -75,11 +75,16 @@ export function checkCssTokens(report) {
             if (file === TOKENS || decl.parent.type === 'atrule' && decl.parent.name === 'font-face') {
                 return;
             }
-            const where = { file, line: decl.source.start.line, rule: decl.parent };
+            // the steps of one @keyframes are one rule: the same colour in 20%, 40% and 60% is one animation
+            const keyframes = decl.parent.parent?.type === 'atrule' && decl.parent.parent.name === 'keyframes';
+            const where = { file, line: decl.source.start.line, rule: keyframes ? decl.parent.parent : decl.parent };
             const value = decl.value.replace(/url\([^)]*\)/g, '');
 
+            // A colour or font literal duplicates a token wherever it appears; a length only does on a
+            // spacing property (a 24px icon is not --spacing-lg, a 16px font size is not --spacing-md)
             const exact = normalise(value);
-            if (byValue.has(exact) && !decl.prop.startsWith('--')) {
+            const lengthLike = /^-?\d/.test(exact);
+            if (byValue.has(exact) && !decl.prop.startsWith('--') && (!lengthLike || SPACING_PROPERTIES.test(decl.prop))) {
                 report.error(`${ file }:${ where.line }`, `${ decl.value } duplicates ${ byValue.get(exact) } — use var(${ byValue.get(exact) })`);
             }
 

package/check/html.js

@@ -81,7 +81,13 @@ function checkPage(report, file, source) {
     if (!headEls.some((el) => el.name === 'title')) {
         report.error(file, 'missing <title>');
     }
+    // an internal tool (noindex) is never shared or indexed, so the social and canonical tags are
+    // not required there; the description and favicon still are
+    const noindex = headEls.some((el) => el.name === 'meta' && attr(el, 'name') === 'robots' && /noindex/.test(attr(el, 'content') ?? ''));
     for (const [label, matches] of REQUIRED_META) {
+        if (noindex && /canonical|og:|twitter:/.test(label)) {
+            continue;
+        }
         if (!headEls.some(matches)) {
             report.error(file, `missing ${ label }`);
         }

package/config/eslint.config.js

@@ -15,10 +15,14 @@ const shared = {
     'max-lines': ['error', { max: MAX_LINES, skipBlankLines: false, skipComments: false }],
     // frontend.md: brackets on every if; const by default, let when reassigned, never var; blank line before return
     'curly': ['error', 'all'],
+    // and the block's body on its own line: `if (x) {y();}` is what curly's fix produces on its own
+    'brace-style': ['error', '1tbs', { allowSingleLine: false }],
     'no-var': 'error',
     'prefer-const': 'error',
     'eqeqeq': ['error', 'always'],
     'padding-line-between-statements': ['error', { blankLine: 'always', prev: '*', next: 'return' }],
+    // an unused catch binding is fine: `catch (error) { // reason }` is how we say the failure is expected
+    'no-unused-vars': ['error', { caughtErrors: 'none' }],
 };
 
 export const browser = {
@@ -26,7 +30,7 @@ export const browser = {
     languageOptions: {
         ecmaVersion: 2024,
         sourceType: 'script',
-        globals: { ...globals.browser, App: 'writable' },
+        globals: { ...globals.browser, App: 'writable', ColabClient: 'readonly' },
     },
     rules: {
         ...js.configs.recommended.rules,

package/config/stylelint.config.js

@@ -47,6 +47,12 @@ export default {
             files: ['src/style/tokens.css', 'src/style/reset.css'],
             rules: { 'selector-disallowed-list': null },
         },
+        {
+            // a theme switch (:root[data-theme="light"] { --color-bg: … }) is the one place styling
+            // hangs off a data attribute: JS sets it, and only tokens change
+            files: ['src/style/tokens.css'],
+            rules: { 'selector-attribute-name-disallowed-list': null },
+        },
         {
             files: ['src/style/tokens.css'],
             rules: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c3b-lint",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Lints a co:lab project against the rules a tool can check: ESLint, Stylelint, the 500-line limit and the shared .editorconfig; --init writes the config files.",
   "license": "GPL-3.0",
   "type": "module",