c3b-lint 0.0.14 → 0.0.16

package/README.md

@@ -1,35 +1,35 @@
 # c3b-lint
 
 Lints a co:lab project against the rules in the [llm-instructions](https://codeberg.org/colab47/llm-instructions)
-markdown that a tool can check, with one command and one config to install. It runs:
+markdown that a tool can check, with one command and one config to install. It runs, in this order:
 
-1. **ESLint** on every `.js` file — classic browser scripts under `src/` (IIFE required, no top-level declarations,
-   no `console.log`), ES modules everywhere else — with `eslint:recommended` plus the rules from `frontend.md`:
-   braces on every `if`, `const`/`let` never `var`, `===`, a blank line before `return`, 500 lines max, and a
-   `replace()`/`replaceAll()` whose replacement comes from data must pass a function (a string one expands `$&`).
-2. **Stylelint** on `src/**/*.css` with `stylelint-config-recommended` plus the rules from `frontend.md`: no
-   `!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. **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
+1. **Project structure**: singular directory names, lowercase kebab-case asset names (and no camera exports), and,
+   when `src/` holds pages, CSS only in `src/style/` + `style/page/` + `style/animation/`, JS only in `src/script/`
+   (an experiment under `src/experiment/<name>/` keeps its own beside its `index.html`), fonts only in
+   `src/asset/font/` as woff2, file names starting with a letter. A directory whose plural-looking name is a proper
+   name (a client's brand) is listed in `package.json` under `"c3b-lint": { "singularDirectories": [...] }`.
+2. **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), no external
-   stylesheets (webfonts are self-hosted), stylesheet order (`reset`, `tokens`, `main`, …, page file last),
+   stylesheets (webfonts are self-hosted; a warning, not an error), 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, landing on `<main id="main">` — or on the id `<main>` already has), one `<h1>`, `alt` on every image, no inline handlers, no `<style>` or `style=""`
    (except a JS-driven custom property), relative paths only (a Barba site's links outside its container — header, menu — stay root-relative), 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), and,
-   when `src/` holds pages, CSS only in `src/style/` + `style/page/` + `style/animation/`, JS only in `src/script/`
-   (an experiment under `src/experiment/<name>/` keeps its own beside its `index.html`), fonts only in
-   `src/asset/font/` as woff2, file names starting with a letter. A directory whose plural-looking name is a proper
-   name (a client's brand) is listed in `package.json` under `"c3b-lint": { "singularDirectories": [...] }`.
-6. The **500-line limit** on `src/**/*.{css,html}` (ESLint reports the JS); inline `<svg>` art is not counted.
-7. 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. 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/`.
+5. The **500-line limit** on `src/**/*.{css,html}` (ESLint reports the JS); inline `<svg>` art is not counted.
+6. **ESLint** on every `.js` file — classic browser scripts under `src/` (IIFE required, no top-level declarations,
+   no `console.log`), ES modules everywhere else — with `eslint:recommended` plus the rules from `frontend.md`:
+   braces on every `if`, `const`/`let` never `var`, `===`, a blank line before `return`, 500 lines max, and a
+   `replace()`/`replaceAll()` whose replacement comes from data must pass a function (a string one expands `$&`).
+7. **Stylelint** on `src/**/*.css` with `stylelint-config-recommended` plus the rules from `frontend.md`: no
+   `!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).
 
 Formatting itself (indent, quotes, spacing) is not linted: the `.editorconfig` and the IDE own it.
 
@@ -97,6 +97,10 @@ c3b-lint --help
 
 The version is printed first, so you can tell which install is running.
 
+Findings print in sections, in the order they run — `--- c3b-lint ---` (checks 1–5), `--- eslint ---`,
+`--- stylelint ---` — each grouped under the file's absolute path the way ESLint prints, with a `✖ N problems` total.
+A section with no findings is not printed. The timings follow, then the error count.
+
 ## Not covered
 
 Rules that need judgement stay with review: whether two selectors are structurally disjoint, flex vs grid, whether

package/c3b-lint.js

@@ -114,26 +114,19 @@ function writeBaseline() {
 
 // --- the checks -----------------------------------------------------------
 
-// Each check returns the number of errors it found, after printing them.
+// c3b-lint's own checks add their findings to the shared report; ESLint and Stylelint print their
+// own and return the number of errors they found.
 
-function checkEditorconfig() {
+function checkEditorconfig(report) {
     if (!existsSync(EDITORCONFIG)) {
-        console.log(`  error   .editorconfig is missing — run "${ name } --init"`);
-
-        return 1;
-    }
-    if (readFileSync(EDITORCONFIG, 'utf8') !== BASELINE['.editorconfig']) {
-        console.log(`  error   .editorconfig differs from the shared one — run "${ name } --init"`);
-
-        return 1;
+        report.error('.editorconfig', `is missing — run "${ name } --init"`);
+    } else if (readFileSync(EDITORCONFIG, 'utf8') !== BASELINE['.editorconfig']) {
+        report.error('.editorconfig', `differs from the shared one — run "${ name } --init"`);
     }
-
-    return 0;
 }
 
 // general.md: no hand-written file past 500 lines. ESLint reports JS; this covers CSS and HTML.
-function checkFileLengths() {
-    let errors = 0;
+function checkFileLengths(report) {
     const ignored = ignoredPaths();
     const files = globSync('src/**/*.{css,html}').map(toPosix).filter((file) => !file.includes('/vendor/') && !ignored.has(file));
     for (const file of files.sort()) {
@@ -141,12 +134,9 @@ function checkFileLengths() {
         const content = readFileSync(file, 'utf8').replace(/<svg[\s\S]*?<\/svg>/g, '<svg/>');
         const lines = content.split('\n').length - (content.endsWith('\n') ? 1 : 0);
         if (lines > MAX_LINES) {
-            console.log(`  error   ${ toPosix(file) } is ${ lines } lines (limit ${ MAX_LINES }) — split it by responsibility`);
-            errors++;
+            report.error(file, `is ${ lines } lines (limit ${ MAX_LINES }) — split it by responsibility`);
         }
     }
-
-    return errors;
 }
 
 async function runEslint() {
@@ -165,10 +155,7 @@ async function runEslint() {
         await ESLint.outputFixes(results);
     }
     const formatter = await eslint.loadFormatter('stylish');
-    const output = await formatter.format(results);
-    if (output.trim()) {
-        console.log(output);
-    }
+    printSection('eslint', await formatter.format(results));
 
     return results.reduce((sum, result) => sum + result.errorCount, 0);
 }
@@ -187,16 +174,22 @@ async function runStylelint() {
         fix,
         formatter: 'string'
     });
-    const output = result.report ?? result.output;
-    if (output.trim()) {
-        console.log(output);
-    }
+    printSection('stylelint', result.report ?? result.output);
 
     return result.results.reduce((sum, file) => sum + file.warnings.filter((w) => w.severity === 'error').length, 0);
 }
 
 // --- run ------------------------------------------------------------------
 
+// The checks run in a fixed order: c3b-lint's own, then ESLint, then Stylelint. Each tool's findings
+// print under its name, so it's clear where one ends and the next begins.
+function printSection(title, output) {
+    if (output.trim()) {
+        console.log(`\n--- ${ title } ---`);
+        console.log(output.trimEnd());
+    }
+}
+
 async function main() {
     // --init only writes: it runs from postinstall, where a lint failure must not fail npm install
     if (init) {
@@ -222,13 +215,14 @@ async function main() {
     await timed('structure', () => checkStructure(report));
     await timed('html', () => checkHtml(report));
     await timed('tokens', () => checkCssTokens(report));
+    await timed('editorconfig', () => checkEditorconfig(report));
+    await timed('lengths', () => checkFileLengths(report));
+    printSection(name, report.format());
     let errors = report.errors;
-    errors += await timed('editorconfig', () => checkEditorconfig());
-    errors += await timed('lengths', () => checkFileLengths());
     errors += await timed('eslint', () => runEslint());
     errors += await timed('stylelint', () => runStylelint());
 
-    console.log(timings.join('\n'));
+    console.log(`\n${ timings.join('\n') }`);
     console.log(`  ${ 'total'.padEnd(13) }${ Math.round(performance.now() - started) }ms`);
     if (errors > 0) {
         fail(`${ errors } error(s)`);

package/check/html.js

@@ -128,9 +128,11 @@ function checkPage(report, file, source) {
     // --- stylesheet link order: reset, tokens, main, components, page file last
     const allSheets = headEls.filter((el) => el.name === 'link' && attr(el, 'rel') === 'stylesheet')
             .map((el) => ({ el, href: attr(el, 'href') ?? '' }));
-    // frontend.md: webfonts are self-hosted woff2 in src/asset/font/; no stylesheet comes from another origin
+    // frontend.md: webfonts are self-hosted woff2 in src/asset/font/; no stylesheet comes from another origin.
+    // A warning, not an error: a licensed font can come with a stylesheet that has to load from the foundry
+    // (Monotype's tracking CSS), and a font still waiting on its licence shouldn't block every commit.
     for (const sheet of allSheets.filter((s) => /^(https?:)?\/\//.test(s.href))) {
-        report.error(at(sheet.el), `external stylesheet ${ sheet.href } — self-host it (fonts as woff2 in src/asset/font/)`);
+        report.warn(at(sheet.el), `external stylesheet ${ sheet.href } — self-host it (fonts as woff2 in src/asset/font/)`);
     }
     const sheets = allSheets.filter((s) => !/^(https?:)?\/\//.test(s.href));
     const names = sheets.map((s) => basename(s.href.split('?')[0]));

package/check/report.js

@@ -1,18 +1,54 @@
-// One line per finding, the way every co:lab tool prints: a padded level, then the file and
-// message. Returns a counter so each check can hand back how many errors it printed.
+import { resolve } from 'path';
+
+// Findings are collected, then printed grouped under each file's absolute path the way ESLint's
+// stylish formatter prints, so the c3b-lint and ESLint sections of a run read the same. Returns a
+// counter so main() knows how many errors were found.
 export function createReport() {
+    const byFile = new Map();
     let errors = 0;
     let warnings = 0;
 
+    // Checks pass "file" or "file:line"
+    function add(where, level, message) {
+        const match = where.match(/^(.*):(\d+)$/);
+        const file = match ? match[1] : where;
+        const line = match ? match[2] : '';
+        if (!byFile.has(file)) {
+            byFile.set(file, []);
+        }
+        byFile.get(file).push({ line, level, message });
+    }
+
     return {
-        error(file, message) {
-            console.log(`  error   ${ file }: ${ message }`);
+        error(where, message) {
+            add(where, 'error', message);
             errors++;
         },
-        warn(file, message) {
-            console.log(`  warn    ${ file }: ${ message }`);
+        warn(where, message) {
+            add(where, 'warning', message);
             warnings++;
         },
+        // The whole report as one string, empty when nothing was found
+        format() {
+            let output = '';
+            for (const file of [...byFile.keys()].sort()) {
+                const findings = byFile.get(file).sort((a, b) => Number(a.line) - Number(b.line));
+                const lineWidth = Math.max(...findings.map((finding) => finding.line.length));
+                const levelWidth = Math.max(...findings.map((finding) => finding.level.length));
+                // resolve() drops a directory's trailing slash; it is kept so a directory reads as one
+                output += `\n${ resolve(file) }${ file.endsWith('/') ? '/' : '' }\n`;
+                for (const { line, level, message } of findings) {
+                    output += `  ${ line.padStart(lineWidth) }  ${ level.padEnd(levelWidth) }  ${ message }\n`;
+                }
+            }
+            if (byFile.size > 0) {
+                const total = errors + warnings;
+                const plural = (count, word) => `${ count } ${ word }${ count === 1 ? '' : 's' }`;
+                output += `\n✖ ${ plural(total, 'problem') } (${ plural(errors, 'error') }, ${ plural(warnings, 'warning') })\n`;
+            }
+
+            return output;
+        },
         get errors() {
             return errors;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c3b-lint",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "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",