c3b-lint 0.0.10 → 0.0.12

package/README.md

@@ -5,7 +5,8 @@ markdown that a tool can check, with one command and one config to install. It r
 
 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.
+   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,
@@ -65,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
@@ -43,8 +44,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'));
     }

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
@@ -46,12 +50,22 @@ const shared = {
     'eol-last': 'error'
 };
 
+// node-cli.md: a replacement that comes from data (a name, a URL, a hash) goes in as a function — a
+// string replacement expands `$&`, `$'` and `$1`, so a value with a `$` in it rewrites the output.
+// A literal second argument is fine; anything else (an identifier, a template with expressions, a
+// call) must be wrapped: `text.replace(re, () => value)`.
+const dataReplacement = {
+    selector: 'CallExpression[callee.property.name=/^replace(All)?$/][arguments.length=2]'
+            + ':not([arguments.1.type=/^(ArrowFunctionExpression|FunctionExpression|Literal)$/])',
+    message: 'A replacement from data expands $& and $1: pass a function, text.replace(re, () => value).'
+};
+
 export const browser = {
     files: ['src/**/*.js'],
     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,
@@ -60,6 +74,7 @@ export const browser = {
         'no-console': ['error', { allow: ['warn', 'error'] }],
         'no-restricted-syntax': [
             'error',
+            dataReplacement,
             {
                 selector: 'Program > VariableDeclaration',
                 message: 'Classic scripts share one global scope: wrap the file in an IIFE and attach its API to window.App.'
@@ -94,7 +109,8 @@ export const node = {
     },
     rules: {
         ...js.configs.recommended.rules,
-        ...shared
+        ...shared,
+        'no-restricted-syntax': ['error', dataReplacement]
     }
 };
 
@@ -108,14 +124,14 @@ export const librarySrc = {
     rules: {
         ...node.rules,
         'no-console': 'off',
-        'no-restricted-syntax': 'off',
+        'no-restricted-syntax': ['error', dataReplacement],
         'no-restricted-properties': 'off',
         'no-restricted-globals': 'off'
     }
 };
 
 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.10",
+  "version": "0.0.12",
   "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",
@@ -27,12 +27,12 @@
     "deploy": "npm run test && npm publish"
   },
   "dependencies": {
-    "@eslint/js": "9",
-    "eslint": "9",
-    "globals": "16",
-    "parse5": "7",
-    "postcss": "8",
-    "stylelint": "16",
-    "stylelint-config-recommended": "17"
+    "@eslint/js": "9.39.5",
+    "eslint": "9.39.5",
+    "globals": "16.5.0",
+    "parse5": "7.3.0",
+    "postcss": "8.5.29",
+    "stylelint": "16.26.1",
+    "stylelint-config-recommended": "17.0.0"
   }
 }