c3b-lint 0.0.11 → 0.0.13

package/README.md

@@ -20,7 +20,7 @@ markdown that a tool can check, with one command and one config to install. It r
    stylesheets (webfonts are self-hosted), 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,
+   (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/`
@@ -66,6 +66,26 @@ Then in `package.json`:
 `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.
 
+## Project settings
+
+A project's own settings go in its `package.json`, under `"c3b-lint"`:
+
+```json
+"c3b-lint": {
+    "ignore": ["src/experiment/**"],
+    "globals": ["THREE", "gsap", "ScrollTrigger"],
+    "singularDirectories": ["mannequin-films"]
+}
+```
+
+- `ignore` — globs, from the project root, that no check looks at: ESLint, Stylelint and every check c3b-lint runs
+  itself (HTML, structure, tokens, file lengths). For code that is not the site's own, like standalone experiments.
+- `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).
+
+The ESLint and Stylelint configs read these too, so WebStorm reports what the CLI does.
+
 ## Usage
 
 ```

package/c3b-lint.js

@@ -9,6 +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';
 
 // Printed first so it's obvious which installed version is running.
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -133,7 +134,8 @@ function checkEditorconfig() {
 // general.md: no hand-written file past 500 lines. ESLint reports JS; this covers CSS and HTML.
 function checkFileLengths() {
     let errors = 0;
-    const files = globSync('src/**/*.{css,html}').filter((file) => !toPosix(file).includes('/vendor/'));
+    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()) {
         // 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/>');

package/check/css-tokens.js

@@ -1,6 +1,7 @@
 import { globSync, readFileSync } from 'fs';
 import { sep } from 'path';
 import postcss from 'postcss';
+import { ignoredPaths } from '../config/project-settings.js';
 
 // Token hygiene, from frontend.md's CSS Tokens section:
 // - a literal that duplicates a token's value is a bug: use the token
@@ -52,7 +53,8 @@ function readTokens() {
 }
 
 export function checkCssTokens(report) {
-    const files = globSync('src/**/*.css').map(toPosix).filter((f) => !f.includes('/vendor/')).sort();
+    const ignored = ignoredPaths();
+    const files = globSync('src/**/*.css').map(toPosix).filter((f) => !f.includes('/vendor/') && !ignored.has(f)).sort();
     if (!files.includes(TOKENS)) {
         return;
     }

package/check/html.js

@@ -1,6 +1,7 @@
 import { globSync, readFileSync } from 'fs';
 import { basename, sep } from 'path';
 import { parse } from 'parse5';
+import { ignoredPaths } from '../config/project-settings.js';
 
 // The HTML rules from frontend.md that a parser can check, on every page under src/ (partials are
 // fragments and are skipped). c10g checks the served page in a browser; this runs in milliseconds
@@ -25,6 +26,19 @@ const toPosix = (p) => p.split(sep).join('/');
 const attr = (el, name) => el.attrs?.find((a) => a.name === name)?.value;
 const line = (el) => el.sourceCodeLocation?.startLine ?? 0;
 const isElement = (node) => Boolean(node.tagName);
+const isBarbaContainer = (node) => isElement(node) && attr(node, 'data-barba') === 'container';
+
+// Inside Barba's page container: replaced on every navigation, so its links resolve against the URL
+// of the page they came with
+function inBarbaContainer(el) {
+    for (let node = el.parentNode; node; node = node.parentNode) {
+        if (isBarbaContainer(node)) {
+            return true;
+        }
+    }
+
+    return false;
+}
 
 // Every element in document order
 function* elements(node) {
@@ -43,8 +57,9 @@ const find = (root, name) => [...elements(root)].find((el) => el.tagName === nam
 const children = (el) => (el.childNodes ?? []).filter(isElement);
 
 export function checkHtml(report) {
+    const ignored = ignoredPaths();
     const files = globSync('src/**/*.html').map(toPosix)
-            .filter((f) => !f.startsWith('src/partial/') && !f.includes('/vendor/')).sort();
+            .filter((f) => !f.startsWith('src/partial/') && !f.includes('/vendor/') && !ignored.has(f)).sort();
     for (const file of files) {
         checkPage(report, file, readFileSync(file, 'utf8'));
     }
@@ -152,6 +167,10 @@ function checkPage(report, file, source) {
         report.error(h1s[1] ? at(h1s[1]) : file, `one <h1> per page (found ${ h1s.length })`);
     }
     const ids = new Map();
+    // A Barba site keeps everything outside its container (header, menu) for the whole visit while the URL
+    // changes under it, so a relative link there would resolve against whichever page is showing: those
+    // links stay root-relative
+    const barba = all.some((el) => attr(el, 'data-barba') === 'wrapper');
     for (const el of all) {
         for (const { name, value } of el.attrs ?? []) {
             if (/^on[a-z]+$/.test(name)) {
@@ -160,7 +179,8 @@ function checkPage(report, file, source) {
             if (name === 'style' && !/^\s*(--[a-z0-9-]+\s*:[^;]+;?\s*)+$/.test(value)) {
                 report.error(at(el), 'no style="" attributes, except to set a JS-driven custom property');
             }
-            if ((name === 'href' || name === 'src') && /^\/(?!\/)/.test(value)) {
+            const persistentLink = barba && el.name === 'a' && name === 'href' && !inBarbaContainer(el);
+            if ((name === 'href' || name === 'src') && /^\/(?!\/)/.test(value) && !persistentLink) {
                 report.error(at(el), `root-relative path ${ value } — use a relative path`);
             }
             if (name === 'id') {

package/check/structure.js

@@ -1,5 +1,6 @@
-import { existsSync, globSync, readdirSync, readFileSync, statSync } from 'fs';
+import { existsSync, globSync, readdirSync, statSync } from 'fs';
 import { basename, dirname, sep } from 'path';
+import { ignoredPaths, readSettings } from '../config/project-settings.js';
 
 // The project-structure rules from general.md and frontend.md: singular directory names, kebab-case
 // asset names, and where CSS, JS and fonts live under src/. Pure filesystem walks.
@@ -15,34 +16,26 @@ const CSS_HOMES_EXTRA = [/^src\/experiment\//];
 
 const toPosix = (p) => p.split(sep).join('/');
 
-// A project names the plural-looking directories that are proper names (a client's brand, an
-// experiment's title) in package.json: "c3b-lint": { "singularDirectories": ["mannequin-films"] }
-function readAllowedDirectories() {
-    try {
-        const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
-
-        return new Set(pkg['c3b-lint']?.singularDirectories ?? []);
-    } catch (error) {
-        return new Set();
-    }
-}
-
 export function checkStructure(report) {
-    checkDirectoryNames(report, '.', readAllowedDirectories());
-    checkAssetNames(report);
-    checkFileHomes(report);
+    // A project names the plural-looking directories that are proper names (a client's brand, an
+    // experiment's title) in package.json: "c3b-lint": { "singularDirectories": ["mannequin-films"] }
+    const allowed = new Set(readSettings().singularDirectories);
+    const ignored = ignoredPaths();
+    checkDirectoryNames(report, '.', allowed, ignored);
+    checkAssetNames(report, ignored);
+    checkFileHomes(report, ignored);
 }
 
 // Every directory, root included, is singular: component/ not components/. "assets" is in the
 // exception list only because it is a common name for a dir that should be asset/ — it is reported
 // separately below, with the rename.
-function checkDirectoryNames(report, dir, allowed) {
+function checkDirectoryNames(report, dir, allowed, ignored) {
     for (const entry of readdirSync(dir)) {
         if (SKIP_DIRS.has(entry) || entry.startsWith('.') || allowed.has(entry)) {
             continue;
         }
         const path = dir === '.' ? entry : `${ dir }/${ entry }`;
-        if (!statSync(path).isDirectory()) {
+        if (ignored.has(path) || !statSync(path).isDirectory()) {
             continue;
         }
         if (entry === 'assets' || entry === 'images' || entry === 'scripts' || entry === 'styles') {
@@ -50,17 +43,17 @@ function checkDirectoryNames(report, dir, allowed) {
         } else if (/[a-z]s$/.test(entry) && !/ss$/.test(entry) && !SINGULAR_ENDING_IN_S.has(entry)) {
             report.error(path + '/', `directories are singular — rename to ${ entry.slice(0, -1) }/ (a proper name goes in package.json "c3b-lint".singularDirectories)`);
         }
-        checkDirectoryNames(report, path, allowed);
+        checkDirectoryNames(report, path, allowed, ignored);
     }
 }
 
 // Asset files are lowercase kebab-case: booking-empty-state.svg, never LUNABLACK_2026-0138.webp
-function checkAssetNames(report) {
+function checkAssetNames(report, ignored) {
     if (!existsSync('src/asset')) {
         return;
     }
     for (const file of globSync('src/asset/**/*').map(toPosix).sort()) {
-        if (statSync(file).isDirectory()) {
+        if (ignored.has(file) || statSync(file).isDirectory()) {
             continue;
         }
         const name = basename(file);
@@ -74,14 +67,14 @@ function checkAssetNames(report) {
 
 // CSS lives in src/style/ (reset, tokens, main, components) with pages in style/page/ and animations
 // in style/animation/; JS in src/script/ (WebGL helpers in src/gl/); fonts in src/asset/font/.
-function checkFileHomes(report) {
+function checkFileHomes(report, ignored) {
     // src/ is a web root when it holds pages; a library that keeps its modules in src/ (c10g) is not
     // bound to the site layout
     if (!existsSync('src') || globSync('src/**/*.html').length === 0) {
         return;
     }
     for (const file of globSync('src/**/*.{css,js,woff,woff2,ttf,otf}').map(toPosix).sort()) {
-        if (file.includes('/vendor/') || /\.min\.js$/.test(file)) {
+        if (ignored.has(file) || file.includes('/vendor/') || /\.min\.js$/.test(file)) {
             continue;
         }
         if (/^\d/.test(basename(file))) {

package/config/eslint.config.js

@@ -1,5 +1,6 @@
 import js from '@eslint/js';
 import globals from 'globals';
+import { readSettings } from './project-settings.js';
 
 // The JavaScript rules from frontend.md and node-cli.md that a linter can check. Formatting
 // (indent, quotes, spacing) is not here: .editorconfig and the IDE own that.
@@ -9,6 +10,9 @@ import globals from 'globals';
 // - everything else (bin files, script/, test/, config): ES modules on Node
 
 const MAX_LINES = 500;
+const settings = readSettings();
+// the project's CDN globals (package.json "c3b-lint".globals), read-only like the browser's own
+const cdnGlobals = Object.fromEntries(settings.globals.map((name) => [name, 'readonly']));
 
 const shared = {
     // general.md: no source file past 500 lines
@@ -61,7 +65,7 @@ export const browser = {
     languageOptions: {
         ecmaVersion: 2024,
         sourceType: 'script',
-        globals: { ...globals.browser, HTMLCanvasElement: 'readonly', App: 'writable', ColabClient: 'readonly' }
+        globals: { ...globals.browser, HTMLCanvasElement: 'readonly', App: 'writable', ColabClient: 'readonly', ...cdnGlobals }
     },
     rules: {
         ...js.configs.recommended.rules,
@@ -127,7 +131,7 @@ export const librarySrc = {
 };
 
 export default [
-    { ignores: ['node_modules/**', 'dist/**', 'c10g/**', 'src/**/vendor/**', '**/*.min.js'] },
+    { ignores: ['node_modules/**', 'dist/**', 'c10g/**', 'src/**/vendor/**', '**/*.min.js', ...settings.ignore] },
     browser,
     node
 ];

package/config/project-settings.js

@@ -0,0 +1,38 @@
+import { globSync, readFileSync } from 'fs';
+import { resolve, sep } from 'path';
+
+// A project's own c3b-lint settings, read from the "c3b-lint" key of its package.json (the project being
+// linted, so the current directory — the CLI and WebStorm both run from the project root):
+//
+//   "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
+//   }
+//
+// The ESLint and Stylelint configs read it too, so the editor reports what the CLI does.
+export function readSettings() {
+    let settings = {};
+    try {
+        settings = JSON.parse(readFileSync(resolve('package.json'), 'utf8'))['c3b-lint'] ?? {};
+    } catch (error) {
+        // no package.json, or not JSON: the CLI reports the first, and the defaults apply
+    }
+
+    return {
+        ignore: settings.ignore ?? [],
+        globals: settings.globals ?? [],
+        singularDirectories: settings.singularDirectories ?? []
+    };
+}
+
+// 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) {
+        return new Set();
+    }
+
+    return new Set(globSync(ignore).map((path) => path.split(sep).join('/')));
+}

package/config/stylelint.config.js

@@ -1,4 +1,5 @@
 import recommended from 'stylelint-config-recommended';
+import { readSettings } from './project-settings.js';
 
 // The CSS rules from frontend.md that a linter can check. Formatting is left to .editorconfig
 // and the IDE, and judgement calls (when a literal should become a token, whether a selector
@@ -12,6 +13,8 @@ const KEBAB = '^[a-z][a-z0-9]*(-[a-z0-9]+)*$';
 const CLASS = '^(is-[a-z0-9]+(-[a-z0-9]+)*|[a-z][a-z0-9]*(-[a-z0-9]+)*(--[a-z0-9]+(-[a-z0-9]+)*)?)$';
 
 export default {
+    // the project's package.json "c3b-lint".ignore
+    ignoreFiles: readSettings().ignore,
     rules: {
         ...recommended.rules,
         // a judgement call in frontend.md (structurally disjoint selectors), too noisy as a hard rule

package/package.json

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