c3b-lint 0.0.15 → 0.0.17

package/README.md

@@ -1,20 +1,14 @@
 # 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; a warning, not an error), stylesheet order (`reset`, `tokens`, `main`, …, page file last),
@@ -22,14 +16,20 @@ markdown that a tool can check, with one command and one config to install. It r
    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.
 
@@ -74,7 +74,8 @@ A project's own settings go in its `package.json`, under `"c3b-lint"`:
 "c3b-lint": {
     "ignore": ["src/experiment/**"],
     "globals": ["THREE", "gsap", "ScrollTrigger"],
-    "singularDirectories": ["mannequin-films"]
+    "singularDirectories": ["mannequin-films"],
+    "ignoreLength": ["src/index.html"]
 }
 ```
 
@@ -83,6 +84,8 @@ A project's own settings go in its `package.json`, under `"c3b-lint"`:
 - `globals` — the names a page's CDN `<script>` tags define (`THREE`, `gsap`, `Lenis`, …). ESLint lints each file on
   its own and never reads the HTML, so without them every use is "not defined". Read-only, `src/` scripts only.
 - `singularDirectories` — plural-looking directory names that are proper names (a client's brand).
+- `ignoreLength` — globs exempt from the 500-line limit and nothing else: the HTML, token, structure, ESLint and
+  Stylelint checks still run on them. For a file that can't be split, like a desktop app's one renderer page.
 
 The ESLint and Stylelint configs read these too, so WebStorm reports what the CLI does.
 
@@ -97,6 +100,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

@@ -9,7 +9,7 @@ import { checkCssTokens } from './check/css-tokens.js';
 import { checkHtml } from './check/html.js';
 import { checkStructure } from './check/structure.js';
 import { installHook } from './check/hook.js';
-import { ignoredPaths } from './config/project-settings.js';
+import { ignoredPaths, readSettings } from './config/project-settings.js';
 
 // Printed first so it's obvious which installed version is running.
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -114,39 +114,30 @@ 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));
+    const exempt = ignoredPaths(readSettings().ignoreLength);
+    const files = globSync('src/**/*.{css,html}').map(toPosix).filter((file) => !file.includes('/vendor/') && !ignored.has(file) && !exempt.has(file));
     for (const file of files.sort()) {
         // inline <svg> is vector art, not hand-written markup: its lines are not counted
         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 +156,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 +175,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 +216,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/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/config/eslint.config.js

@@ -130,8 +130,12 @@ export const librarySrc = {
     }
 };
 
+// the "ignoreLength" files: everything but max-lines still applies (ESLint refuses an empty files list)
+const lengthExempt = settings.ignoreLength.length ? [{ files: settings.ignoreLength, rules: { 'max-lines': 'off' } }] : [];
+
 export default [
     { ignores: ['node_modules/**', 'dist/**', 'c10g/**', 'src/**/vendor/**', '**/*.min.js', ...settings.ignore] },
     browser,
-    node
+    node,
+    ...lengthExempt
 ];

package/config/project-settings.js

@@ -7,7 +7,8 @@ import { resolve, sep } from 'path';
 //   "c3b-lint": {
 //       "ignore": ["src/experiment/**"],        globs no check looks at: ESLint, Stylelint and c3b-lint's own
 //       "globals": ["THREE", "gsap"],           names the pages' CDN <script> tags define, read-only in src/ scripts
-//       "singularDirectories": ["mannequin-films"]   plural-looking directory names that are proper names
+//       "singularDirectories": ["mannequin-films"],  plural-looking directory names that are proper names
+//       "ignoreLength": ["src/index.html"]      globs exempt from the 500-line limit only; every other check still runs
 //   }
 //
 // The ESLint and Stylelint configs read it too, so the editor reports what the CLI does.
@@ -22,17 +23,17 @@ export function readSettings() {
     return {
         ignore: settings.ignore ?? [],
         globals: settings.globals ?? [],
-        singularDirectories: settings.singularDirectories ?? []
+        singularDirectories: settings.singularDirectories ?? [],
+        ignoreLength: settings.ignoreLength ?? []
     };
 }
 
-// Every file and directory the "ignore" globs match, as posix paths from the project root, for the checks
-// c3b-lint runs itself (ESLint and Stylelint are handed the globs directly)
-export function ignoredPaths() {
-    const { ignore } = readSettings();
-    if (ignore.length === 0) {
+// Every file and directory the "ignore" globs (or the globs given) match, as posix paths from the project
+// root, for the checks c3b-lint runs itself (ESLint and Stylelint are handed the globs directly)
+export function ignoredPaths(globs = readSettings().ignore) {
+    if (globs.length === 0) {
         return new Set();
     }
 
-    return new Set(globSync(ignore).map((path) => path.split(sep).join('/')));
+    return new Set(globSync(globs).map((path) => path.split(sep).join('/')));
 }

package/package.json

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