c3b-lint 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# c3b-lint
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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:
+
+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.
+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
+   `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.
+
+## Setup
+
+```
+npm install --save-dev c3b-lint
+npx c3b-lint --init
+```
+
+`--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"
+```
+
+`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, …); reformat in the IDE after
+c3b-lint --init     # (re)write .editorconfig, eslint.config.js, stylelint.config.js, the pre-commit hook
+c3b-lint --help
+```
+
+The version is printed first, so you can tell which install is running.
+
+## Not covered
+
+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

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { existsSync, globSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join, resolve, sep } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { ESLint } from 'eslint';
+import stylelint from 'stylelint';
+import { createReport } from './check/report.js';
+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';
+
+// Printed first so it's obvious which installed version is running.
+const HERE = dirname(fileURLToPath(import.meta.url));
+const { name, version } = JSON.parse(readFileSync(join(HERE, 'package.json'), 'utf8'));
+console.log(`${ name } version: ${ version }`);
+
+// Lints a co:lab project against the rules in the llm-instructions markdown that a tool can check:
+// ESLint on every .js file, Stylelint on src/**/*.css, token hygiene across the CSS, the HTML rules,
+// the project structure, the 500-line limit on CSS and HTML (ESLint covers JS), and that the
+// project's .editorconfig is the shared one. The ESLint/Stylelint configs ship in config/; --init
+// writes one-line re-exports of them at the project root (what WebStorm reads to show the same
+// results inline) and installs the pre-commit hook.
+
+const CONFIG_DIR = join(HERE, 'config');
+const EDITORCONFIG = resolve('.editorconfig');
+
+// The project's own config file when it has one (the one-liner --init writes, or an extended copy for
+// a project that needs an exception), so the CLI and WebStorm always agree; this package's otherwise.
+const configFor = (file) => (existsSync(resolve(file)) ? resolve(file) : join(CONFIG_DIR, file));
+const MAX_LINES = 500;
+
+// Files --init writes at the project root. The .editorconfig is a copy (it has to be a real
+// file for editors to read it); the two lint configs re-export this package's, so a bump of
+// c3b-lint changes the rules everywhere without touching projects.
+const BASELINE = {
+    '.editorconfig': readFileSync(join(CONFIG_DIR, 'editorconfig'), 'utf8'),
+    'eslint.config.js': "export { default } from 'c3b-lint/config/eslint.config.js';\n",
+    'stylelint.config.js': "export { default } from 'c3b-lint/config/stylelint.config.js';\n",
+};
+
+const FLAGS = {
+    '--fix': 'apply the ESLint and Stylelint fixes that are safe to apply automatically',
+    '--init': 'write .editorconfig, eslint.config.js, stylelint.config.js and the pre-commit hook',
+    '--help': 'print this help',
+};
+
+function usage() {
+    console.log(`Usage: ${ name } [flags]\n\nLints .js, src/**/*.css and src/**/*.html, token use, project structure, file lengths and .editorconfig; exits 1 on any error.\n\nFlags:`);
+    for (const [flag, description] of Object.entries(FLAGS)) {
+        console.log(`  ${ flag.padEnd(16) }${ description }`);
+    }
+}
+
+function fail(message) {
+    console.error(`${ name }: ${ message }`);
+    process.exit(1);
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+    usage();
+    process.exit(0);
+}
+for (const arg of args) {
+    if (!(arg in FLAGS)) {
+        console.error(`${ name }: unknown option ${ arg }\n`);
+        usage();
+        process.exit(1);
+    }
+}
+
+const fix = args.includes('--fix');
+const init = args.includes('--init');
+
+const toPosix = (p) => p.split(sep).join('/');
+
+if (!existsSync(resolve('package.json'))) {
+    fail('package.json not found — run from the project root');
+}
+
+// --- --init ---------------------------------------------------------------
+
+function writeBaseline() {
+    for (const [file, content] of Object.entries(BASELINE)) {
+        const path = resolve(file);
+        if (existsSync(path) && readFileSync(path, 'utf8') === content) {
+            continue;
+        }
+        console.log(`  write   ${ file }`);
+        writeFileSync(path, content);
+    }
+}
+
+// --- the checks -----------------------------------------------------------
+
+// Each check returns the number of errors it found, after printing them.
+
+function checkEditorconfig() {
+    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;
+    }
+
+    return 0;
+}
+
+// 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/'));
+    for (const file of files.sort()) {
+        const content = readFileSync(file, 'utf8');
+        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++;
+        }
+    }
+
+    return errors;
+}
+
+async function runEslint() {
+    const eslint = new ESLint({ cwd: process.cwd(), overrideConfigFile: configFor('eslint.config.js'), fix });
+    let results;
+    try {
+        results = await eslint.lintFiles(['.']);
+    } catch (error) {
+        // a project with no .js at all (a pure HTML/CSS site) is not an error
+        if (/No files matching|All files matched by '\.' are ignored/.test(error.message)) {
+            return 0;
+        }
+        throw error;
+    }
+    if (fix) {
+        await ESLint.outputFixes(results);
+    }
+    const formatter = await eslint.loadFormatter('stylish');
+    const output = await formatter.format(results);
+    if (output.trim()) {
+        console.log(output);
+    }
+
+    return results.reduce((sum, result) => sum + result.errorCount, 0);
+}
+
+async function runStylelint() {
+    if (globSync('src/**/*.css').length === 0) {
+        return 0;
+    }
+    // Passed as an object with the project as base dir, so the overrides' globs match project files
+    // (a configFile's globs only ever match under that file's own directory)
+    const { default: config } = await import(pathToFileURL(configFor('stylelint.config.js')).href);
+    const result = await stylelint.lint({
+        files: 'src/**/*.css',
+        config,
+        configBasedir: process.cwd(),
+        fix,
+        formatter: 'string',
+    });
+    const output = result.report ?? result.output;
+    if (output.trim()) {
+        console.log(output);
+    }
+
+    return result.results.reduce((sum, file) => sum + file.warnings.filter((w) => w.severity === 'error').length, 0);
+}
+
+// --- 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();
+    checkStructure(report);
+    checkHtml(report);
+    checkCssTokens(report);
+    const errors = checkEditorconfig() + checkFileLengths() + report.errors + await runEslint() + await runStylelint();
+    if (errors > 0) {
+        fail(`${ errors } error(s)`);
+    }
+    console.log('No lint errors.');
+}
+
+main().catch((error) => fail(error.message));

package/check/css-tokens.js

@@ -0,0 +1,139 @@
+import { globSync, readFileSync } from 'fs';
+import { sep } from 'path';
+import postcss from 'postcss';
+
+// Token hygiene, from frontend.md's CSS Tokens section:
+// - a literal that duplicates a token's value is a bug: use the token
+// - a literal colour, font or spacing value that appears in two or more rules is a token by definition
+// - a token with no uses is deleted
+// Stylelint has no rule for any of these, because they need the whole project, not one file.
+
+const TOKENS = 'src/style/tokens.css';
+const SPACING_PROPERTIES = /^(margin|padding|gap|row-gap|column-gap)(-[a-z]+)?$/;
+const COLOUR = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?)\([^)]*\)/gi;
+
+const toPosix = (p) => p.split(sep).join('/');
+
+// Hex colours compare as lowercase six/eight digit; everything else as lowercase with single spaces.
+function normalise(value) {
+    const v = value.trim().toLowerCase().replace(/\s+/g, ' ').replace(/\s*,\s*/g, ', ');
+    const short = v.match(/^#([0-9a-f])([0-9a-f])([0-9a-f])([0-9a-f])?$/);
+    if (short) {
+        return '#' + short.slice(1, 5).filter(Boolean).map((c) => c + c).join('');
+    }
+
+    return v;
+}
+
+function parse(file) {
+    try {
+        return postcss.parse(readFileSync(file, 'utf8'), { from: file });
+    } catch (error) {
+        return null; // Stylelint reports the syntax error
+    }
+}
+
+function readTokens() {
+    const tokens = new Map();
+    const root = parse(TOKENS);
+    if (!root) {
+        return tokens;
+    }
+    root.walkDecls(/^--/, (decl) => {
+        tokens.set(decl.prop, normalise(decl.value));
+    });
+
+    return tokens;
+}
+
+export function checkCssTokens(report) {
+    const files = globSync('src/**/*.css').map(toPosix).filter((f) => !f.includes('/vendor/')).sort();
+    if (!files.includes(TOKENS)) {
+        return;
+    }
+    const tokens = readTokens();
+    const byValue = new Map([...tokens].map(([name, value]) => [value, name]));
+
+    // literal -> [{ file, line }] across every rule it appears in (one entry per rule)
+    const colours = new Map();
+    const fonts = new Map();
+    const spacing = new Map();
+    const used = new Set();
+    const noteUse = (text) => {
+        for (const match of text.matchAll(/--[a-z0-9-]+/g)) {
+            used.add(match[0]);
+        }
+    };
+
+    for (const file of files) {
+        const root = parse(file);
+        if (!root) {
+            continue;
+        }
+        root.walkDecls((decl) => {
+            noteUse(decl.value);
+            if (file === TOKENS || decl.parent.type === 'atrule' && decl.parent.name === 'font-face') {
+                return;
+            }
+            // 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);
+            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) })`);
+            }
+
+            for (const match of value.matchAll(COLOUR)) {
+                const colour = normalise(match[0]);
+                if (byValue.has(colour) && exact !== colour) {
+                    report.error(`${ file }:${ where.line }`, `${ match[0] } duplicates ${ byValue.get(colour) } — use var(${ byValue.get(colour) })`);
+                } else if (!byValue.has(colour)) {
+                    add(colours, colour, where);
+                }
+            }
+            if (decl.prop === 'font-family' && !/var\(/.test(value)) {
+                add(fonts, exact, where);
+            }
+            if (SPACING_PROPERTIES.test(decl.prop) && !/var\(|calc\(|%|auto|^0$/.test(value)) {
+                add(spacing, exact, where);
+            }
+        });
+    }
+
+    for (const file of globSync('src/**/*.{js,html}').map(toPosix)) {
+        noteUse(readFileSync(file, 'utf8'));
+    }
+
+    for (const [name] of tokens) {
+        if (!used.has(name)) {
+            report.error(TOKENS, `${ name } is never used — delete it`);
+        }
+    }
+    reportRepeats(report, colours, 'colour');
+    reportRepeats(report, fonts, 'font-family');
+    reportRepeats(report, spacing, 'spacing value');
+}
+
+// One entry per rule: the same literal twice in one rule (a border shorthand and a shadow) is one use.
+function add(map, key, where) {
+    const list = map.get(key) ?? [];
+    if (!list.some((entry) => entry.rule === where.rule)) {
+        list.push(where);
+        map.set(key, list);
+    }
+}
+
+function reportRepeats(report, map, kind) {
+    for (const [literal, uses] of map) {
+        if (uses.length < 2) {
+            continue;
+        }
+        const places = uses.map((use) => `${ use.file }:${ use.line }`).join(', ');
+        report.error(uses[0].file, `${ kind } ${ literal } is used in ${ uses.length } rules (${ places }) — make it a token in ${ TOKENS }`);
+    }
+}

package/check/hook.js

@@ -0,0 +1,39 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'fs';
+import { execFileSync } from 'child_process';
+
+// A pre-commit hook, so a commit that fails the lint never lands — designers commit straight to the
+// repos, and nobody runs npm test before every commit. The hook lives in the repo (.githooks/) and is
+// wired with core.hooksPath, so it works with no extra tool and survives a fresh clone after one
+// --init. If the package isn't installed (no npm install yet), it says so and lets the commit through
+// rather than blocking someone who hasn't set up: the test gate still catches it later.
+const HOOK = `#!/bin/sh
+# Written by c3b-lint --init. Runs the lint before every commit; see https://codeberg.org/colab47/c3b-lint
+if [ -x node_modules/.bin/c3b-lint ]; then
+    node_modules/.bin/c3b-lint || exit 1
+else
+    echo "c3b-lint is not installed (run npm install) — commit not linted"
+fi
+`;
+
+export function installHook(log) {
+    const path = '.githooks/pre-commit';
+    if (!existsSync(path) || readFileSync(path, 'utf8') !== HOOK) {
+        mkdirSync('.githooks', { recursive: true });
+        writeFileSync(path, HOOK);
+        log(path);
+    }
+    chmodSync(path, 0o755);
+
+    if (existsSync('.git')) {
+        try {
+            const current = execFileSync('git', ['config', '--get', 'core.hooksPath'], { encoding: 'utf8', stdio: 'pipe' }).trim();
+            if (current === '.githooks') {
+                return;
+            }
+        } catch (error) {
+            // not set yet
+        }
+        execFileSync('git', ['config', 'core.hooksPath', '.githooks'], { stdio: 'pipe' });
+        log('git config core.hooksPath .githooks');
+    }
+}

package/check/html.js

@@ -0,0 +1,183 @@
+import { globSync, readFileSync } from 'fs';
+import { basename, sep } from 'path';
+import { parse } from 'parse5';
+
+// 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
+// before any browser starts, and covers what a browser can't see, like link order and skip links.
+
+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]+)*)?)$/;
+const STYLE_ORDER = ['reset.css', 'tokens.css', 'main.css'];
+const REQUIRED_META = [
+    ['meta[name=description]', (el) => el.name === 'meta' && attr(el, 'name') === 'description'],
+    ['link[rel=canonical]', (el) => el.name === 'link' && attr(el, 'rel') === 'canonical'],
+    ['og:title', (el) => el.name === 'meta' && attr(el, 'property') === 'og:title'],
+    ['og:description', (el) => el.name === 'meta' && attr(el, 'property') === 'og:description'],
+    ['og:type', (el) => el.name === 'meta' && attr(el, 'property') === 'og:type'],
+    ['og:url', (el) => el.name === 'meta' && attr(el, 'property') === 'og:url'],
+    ['og:image', (el) => el.name === 'meta' && attr(el, 'property') === 'og:image'],
+    ['twitter:card', (el) => el.name === 'meta' && attr(el, 'name') === 'twitter:card'],
+    ['favicon link[rel=icon]', (el) => el.name === 'link' && attr(el, 'rel') === 'icon'],
+];
+
+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);
+
+// Every element in document order
+function* elements(node) {
+    for (const child of node.childNodes ?? []) {
+        if (isElement(child)) {
+            yield child;
+            yield* elements(child);
+        }
+        if (child.content) {
+            yield* elements(child.content);
+        }
+    }
+}
+
+const find = (root, name) => [...elements(root)].find((el) => el.tagName === name);
+const children = (el) => (el.childNodes ?? []).filter(isElement);
+
+export function checkHtml(report) {
+    const files = globSync('src/**/*.html').map(toPosix)
+        .filter((f) => !f.startsWith('src/partial/') && !f.includes('/vendor/')).sort();
+    for (const file of files) {
+        checkPage(report, file, readFileSync(file, 'utf8'));
+    }
+}
+
+function checkPage(report, file, source) {
+    const document = parse(source, { sourceCodeLocationInfo: true });
+    const all = [...elements(document)].map((el) => ({ ...el, name: el.tagName }));
+    const at = (el) => `${ file }:${ line(el) }`;
+
+    // --- document basics
+    if (!/^\s*<!doctype html>/i.test(source)) {
+        report.error(file, 'missing <!DOCTYPE html>');
+    }
+    const html = find(document, 'html');
+    if (html && !attr(html, 'lang')) {
+        report.error(at(html), '<html> needs a lang attribute');
+    }
+    const head = find(document, 'head');
+    const body = find(document, 'body');
+    if (!head || !body) {
+        return;
+    }
+    const headEls = children(head).map((el) => ({ ...el, name: el.tagName }));
+    if (!headEls.some((el) => el.name === 'meta' && attr(el, 'charset'))) {
+        report.error(file, 'missing <meta charset>');
+    }
+    const viewport = headEls.find((el) => el.name === 'meta' && attr(el, 'name') === 'viewport');
+    if (!viewport) {
+        report.error(file, 'missing viewport meta');
+    } else if (/user-scalable\s*=\s*no|maximum-scale/i.test(attr(viewport, 'content') ?? '')) {
+        report.error(at(viewport), 'viewport must not set user-scalable=no or maximum-scale');
+    }
+    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 }`);
+        }
+    }
+    const ogImage = headEls.find((el) => el.name === 'meta' && attr(el, 'property') === 'og:image');
+    if (ogImage && !/^https?:\/\//.test(attr(ogImage, 'content') ?? '')) {
+        report.error(at(ogImage), 'og:image must be an absolute URL (social platforms ignore relative paths)');
+    }
+    const canonical = headEls.find((el) => el.name === 'link' && attr(el, 'rel') === 'canonical');
+    if (canonical && !/^https?:\/\//.test(attr(canonical, 'href') ?? '')) {
+        report.error(at(canonical), 'canonical must be an absolute URL');
+    }
+    const favicons = headEls.filter((el) => el.name === 'link' && attr(el, 'rel') === 'icon');
+    if (favicons.length > 1) {
+        report.error(at(favicons[1]), 'one favicon <link>, an SVG');
+    } else if (favicons.length === 1 && !/\.svg$/.test(attr(favicons[0], 'href') ?? '')) {
+        report.error(at(favicons[0]), 'the favicon is an SVG');
+    }
+    if (headEls.some((el) => el.name === 'style')) {
+        report.error(file, 'no <style> blocks — styles live in src/style/');
+    }
+
+    // --- stylesheet link order: reset, tokens, main, components, page file last
+    const sheets = headEls.filter((el) => el.name === 'link' && attr(el, 'rel') === 'stylesheet')
+        .map((el) => ({ el, href: attr(el, 'href') ?? '' }));
+    const names = sheets.map((s) => basename(s.href.split('?')[0]));
+    const expectedStart = STYLE_ORDER.filter((n) => names.includes(n));
+    if (names.slice(0, expectedStart.length).join() !== expectedStart.join()) {
+        report.error(at(sheets[0].el), `stylesheets start with ${ STYLE_ORDER.join(', ') } in that order`);
+    }
+    const pageIndex = sheets.findIndex((s) => /\/page\//.test(s.href));
+    if (pageIndex !== -1 && pageIndex !== sheets.length - 1) {
+        report.error(at(sheets[pageIndex].el), 'the page stylesheet is linked last');
+    }
+
+    // --- skip link and main
+    const hasChrome = all.some((el) => el.name === 'header' || el.name === 'nav');
+    const first = children(body)[0];
+    const skipLink = first && first.tagName === 'a' && attr(first, 'id') === 'skip-link';
+    const main = all.find((el) => el.name === 'main');
+    if (hasChrome) {
+        if (!skipLink || attr(first, 'href') !== '#main') {
+            report.error(file, 'a page with a header or nav starts <body> with <a id="skip-link" href="#main">');
+        }
+        if (!main || attr(main, 'id') !== 'main') {
+            report.error(file, '<main> carries id="main" for the skip link');
+        }
+    } else if (skipLink) {
+        report.error(at(first), 'a page with no header or nav has no skip link');
+    }
+
+    // --- headings, images, scripts, paths, inline handlers and styles, names
+    const h1s = all.filter((el) => el.name === 'h1');
+    if (h1s.length !== 1) {
+        report.error(h1s[1] ? at(h1s[1]) : file, `one <h1> per page (found ${ h1s.length })`);
+    }
+    const ids = new Map();
+    for (const el of all) {
+        for (const { name, value } of el.attrs ?? []) {
+            if (/^on[a-z]+$/.test(name)) {
+                report.error(at(el), `no inline handlers (${ name }) — JS lives in src/script/`);
+            }
+            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)) {
+                report.error(at(el), `root-relative path ${ value } — use a relative path`);
+            }
+            if (name === 'id') {
+                if (!KEBAB.test(value)) {
+                    report.error(at(el), `id "${ value }" is not kebab-case`);
+                }
+                if (ids.has(value)) {
+                    report.error(at(el), `duplicate id "${ value }" (first at line ${ ids.get(value) })`);
+                }
+                ids.set(value, line(el));
+            }
+            if (name === 'class') {
+                for (const cls of value.split(/\s+/).filter(Boolean)) {
+                    if (!CLASS.test(cls)) {
+                        report.error(at(el), `class "${ cls }" is not kebab-case (state classes are is-*, variants use --)`);
+                    }
+                }
+            }
+        }
+        if (el.name === 'img' && attr(el, 'alt') === undefined) {
+            report.error(at(el), '<img> needs alt text (alt="" if decorative)');
+        }
+        if (el.name === 'script' && /^https?:\/\//.test(attr(el, 'src') ?? '') && !attr(el, 'integrity')) {
+            report.error(at(el), 'CDN scripts carry integrity and crossorigin="anonymous"');
+        }
+    }
+}

package/check/report.js

@@ -0,0 +1,23 @@
+// 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.
+export function createReport() {
+    let errors = 0;
+    let warnings = 0;
+
+    return {
+        error(file, message) {
+            console.log(`  error   ${ file }: ${ message }`);
+            errors++;
+        },
+        warn(file, message) {
+            console.log(`  warn    ${ file }: ${ message }`);
+            warnings++;
+        },
+        get errors() {
+            return errors;
+        },
+        get warnings() {
+            return warnings;
+        },
+    };
+}

package/check/structure.js

@@ -0,0 +1,86 @@
+import { existsSync, globSync, readdirSync, statSync } from 'fs';
+import { basename, dirname, sep } from 'path';
+
+// 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.
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'c10g', '.llm-rules', '.idea', 'vendor', 'target', 'build']);
+// Words that end in s but are not plurals, or that are plural by convention outside our control
+const SINGULAR_ENDING_IN_S = new Set(['css', 'js', 'canvas', 'status', 'news', 'gl', 'lens', 'bus', 'analysis', 'ios', 'macos', 'assets']);
+const ASSET_NAME = /^[a-z0-9]+(-[a-z0-9]+)*(\.[a-z0-9]+)+$/;
+const CSS_HOMES = [/^src\/style\/[a-z0-9-]+\.css$/, /^src\/style\/page\/[a-z][a-z0-9-]*\.css$/, /^src\/style\/animation\/[a-z][a-z0-9-]*\.css$/];
+const JS_HOMES = [/^src\/script\/([a-z0-9-]+\/)*[a-z][a-z0-9-]*\.js$/, /^src\/gl\//];
+
+const toPosix = (p) => p.split(sep).join('/');
+
+export function checkStructure(report) {
+    checkDirectoryNames(report, '.');
+    checkAssetNames(report);
+    checkFileHomes(report);
+}
+
+// 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) {
+    for (const entry of readdirSync(dir)) {
+        if (SKIP_DIRS.has(entry) || entry.startsWith('.')) {
+            continue;
+        }
+        const path = dir === '.' ? entry : `${ dir }/${ entry }`;
+        if (!statSync(path).isDirectory()) {
+            continue;
+        }
+        if (entry === 'assets' || entry === 'images' || entry === 'scripts' || entry === 'styles') {
+            report.error(path + '/', `directories are singular — rename to ${ entry.slice(0, -1) }/`);
+        } 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) }/ (or add it to the exceptions in c3b-lint if it is not a plural)`);
+        }
+        checkDirectoryNames(report, path);
+    }
+}
+
+// Asset files are lowercase kebab-case: booking-empty-state.svg, never LUNABLACK_2026-0138.webp
+function checkAssetNames(report) {
+    if (!existsSync('src/asset')) {
+        return;
+    }
+    for (const file of globSync('src/asset/**/*').map(toPosix).sort()) {
+        if (statSync(file).isDirectory()) {
+            continue;
+        }
+        const name = basename(file);
+        if (!ASSET_NAME.test(name)) {
+            report.error(file, 'asset names are lowercase kebab-case (letters, digits, hyphens)');
+        } else if (/^(img|dsc|dcim|screenshot|untitled)[-0-9]/.test(name)) {
+            report.error(file, 'name the asset after what it shows, not the camera export');
+        }
+    }
+}
+
+// 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) {
+    if (!existsSync('src')) {
+        return;
+    }
+    for (const file of globSync('src/**/*.{css,js,woff,woff2,ttf,otf}').map(toPosix).sort()) {
+        if (file.includes('/vendor/') || /\.min\.js$/.test(file)) {
+            continue;
+        }
+        if (/^\d/.test(basename(file))) {
+            report.error(file, 'file names start with a letter, never a digit');
+        }
+        if (file.endsWith('.css') && !CSS_HOMES.some((home) => home.test(file))) {
+            report.error(file, 'CSS lives in src/style/ (shared), src/style/page/ (one per page) or src/style/animation/');
+        } else if (file.endsWith('.js') && !JS_HOMES.some((home) => home.test(file))) {
+            report.error(file, 'JS lives in src/script/');
+        } else if (/\.(woff2?|ttf|otf)$/.test(file)) {
+            if (dirname(file) !== 'src/asset/font') {
+                report.error(file, 'fonts live in src/asset/font/');
+            } else if (!file.endsWith('.woff2')) {
+                report.error(file, 'fonts are self-hosted as woff2 only');
+            }
+        }
+    }
+}

package/config/editorconfig

@@ -0,0 +1,65 @@
+# co:lab editor settings, written by c3b-lint --init and checked by every c3b-lint run.
+# The ij_* keys are JetBrains code-style settings (WebStorm / IntelliJ read them from here),
+# so the formatter is shared without committing .idea/.
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+max_line_length = 120
+ij_continuation_indent_size = 8
+ij_visual_guides = 120
+ij_wrap_on_typing = false
+
+[*.{js,mjs,cjs}]
+ij_javascript_use_double_quotes = false
+ij_javascript_force_quote_style = true
+ij_javascript_force_semicolon_style = true
+ij_javascript_use_semicolon_after_statement = true
+ij_javascript_if_brace_force = always
+ij_javascript_for_brace_force = always
+ij_javascript_while_brace_force = always
+ij_javascript_do_while_brace_force = always
+ij_javascript_spaces_within_object_literal_braces = true
+ij_javascript_spaces_within_imports = true
+ij_javascript_spaces_within_interpolation_expressions = true
+ij_javascript_align_multiline_parameters = false
+ij_javascript_align_multiline_chained_methods = false
+ij_javascript_blank_lines_after_imports = 1
+ij_javascript_keep_blank_lines_in_code = 1
+
+[*.java]
+ij_java_if_brace_force = always
+ij_java_for_brace_force = always
+ij_java_while_brace_force = always
+ij_java_dowhile_brace_force = always
+ij_java_align_multiline_parameters = false
+ij_java_align_group_field_declarations = false
+ij_java_align_consecutive_variable_declarations = false
+ij_java_align_consecutive_assignments = false
+ij_java_class_count_to_use_import_on_demand = 999
+ij_java_names_count_to_use_import_on_demand = 999
+ij_java_method_call_chain_wrap = normal
+ij_java_blank_lines_after_imports = 1
+ij_java_keep_blank_lines_in_code = 1
+ij_java_keep_blank_lines_in_declarations = 1
+ij_java_blank_lines_around_method = 1
+ij_java_blank_lines_around_field = 0
+ij_java_generate_final_locals = true
+ij_java_generate_final_parameters = true
+
+[*.{css,html}]
+ij_html_quote_style = double
+ij_css_enforce_quotes_on_format = true
+ij_css_use_double_quotes = true
+
+[*.md]
+max_line_length = 120
+trim_trailing_whitespace = false
+
+[*.{json,yml,yaml}]
+indent_size = 2

package/config/eslint.config.js

@@ -0,0 +1,84 @@
+import js from '@eslint/js';
+import globals from 'globals';
+
+// 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.
+//
+// Two shapes of file in every co:lab project:
+// - src/**: classic browser scripts, one global scope, wrapped in an IIFE, no console.log
+// - everything else (bin files, script/, test/, config): ES modules on Node
+
+const MAX_LINES = 500;
+
+const shared = {
+    // general.md: no source file past 500 lines
+    '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 = {
+    files: ['src/**/*.js'],
+    languageOptions: {
+        ecmaVersion: 2024,
+        sourceType: 'script',
+        globals: { ...globals.browser, App: 'writable', ColabClient: 'readonly' },
+    },
+    rules: {
+        ...js.configs.recommended.rules,
+        ...shared,
+        // frontend.md: no console.log/debug in src/; warn only for feature fallbacks
+        'no-console': ['error', { allow: ['warn', 'error'] }],
+        'no-restricted-syntax': [
+            'error',
+            {
+                selector: 'Program > VariableDeclaration',
+                message: 'Classic scripts share one global scope: wrap the file in an IIFE and attach its API to window.App.',
+            },
+            {
+                selector: 'Program > FunctionDeclaration',
+                message: 'Classic scripts share one global scope: wrap the file in an IIFE and attach its API to window.App.',
+            },
+        ],
+        'no-restricted-properties': [
+            'warn',
+            {
+                object: 'document',
+                property: 'getElementsByClassName',
+                message: 'Use getElementById for the landmark, then querySelectorAll scoped off it.',
+            },
+        ],
+        'no-restricted-globals': [
+            'warn',
+            { name: 'setInterval', message: 'Use IntersectionObserver or requestAnimationFrame, not polling.' },
+        ],
+    },
+};
+
+export const node = {
+    files: ['**/*.js'],
+    ignores: ['src/**'],
+    languageOptions: {
+        ecmaVersion: 2024,
+        sourceType: 'module',
+        globals: globals.node,
+    },
+    rules: {
+        ...js.configs.recommended.rules,
+        ...shared,
+    },
+};
+
+export default [
+    { ignores: ['node_modules/**', 'dist/**', 'c10g/**', 'src/**/vendor/**', '**/*.min.js'] },
+    browser,
+    node,
+];

package/config/stylelint.config.js

@@ -0,0 +1,65 @@
+import recommended from 'stylelint-config-recommended';
+
+// 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
+// is structurally disjoint) are left to review.
+//
+// stylelint-config-recommended's rules are spread in rather than `extends`-ed: c3b-lint passes this
+// config to Stylelint as an object, so there is nothing to resolve from the project's node_modules.
+
+const KEBAB = '^[a-z][a-z0-9]*(-[a-z0-9]+)*$';
+// a kebab-case class, an is-* state class, or a kebab-case class with one -- variant
+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 {
+    rules: {
+        ...recommended.rules,
+        // a judgement call in frontend.md (structurally disjoint selectors), too noisy as a hard rule
+        'no-descending-specificity': null,
+        // frontend.md: no !important; max 3 compound selectors per rule
+        'declaration-no-important': true,
+        'selector-max-compound-selectors': 3,
+        // kebab-case ids and classes, is-* for state, -- for a variant of a shared class
+        'selector-id-pattern': [KEBAB, { message: 'ids are kebab-case' }],
+        'selector-class-pattern': [CLASS, {
+            resolveNestedSelectors: true,
+            message: 'classes are kebab-case; state classes are is-*; a variant of a shared class uses --',
+        }],
+        // custom properties are kebab-case everywhere; the stricter token shape applies in tokens.css below
+        'custom-property-pattern': ['^[a-z0-9]+(-[a-z0-9]+)*$', { message: 'custom properties are kebab-case' }],
+        // tokens are defined once, in tokens.css; reset.css may touch :root for box-sizing and text-size-adjust
+        'selector-disallowed-list': [['/^:root/'], { message: ':root declarations belong in tokens.css' }],
+        // units: font sizes in rem (clamp() may mix in vw), letter-spacing in em, never dvh
+        'unit-disallowed-list': [['dvh'], { message: 'dvh follows the phone toolbar; use vh, or svh for bottom-anchored content' }],
+        'declaration-property-unit-allowed-list': {
+            'font-size': ['rem', 'vw', '%'],
+            'letter-spacing': ['em'],
+        },
+        // frontend.md: don't style off data attributes; they exist for JS
+        'selector-attribute-name-disallowed-list': [['/^data-/'], {
+            severity: 'warning',
+            message: 'data-* attributes are for JS; style with an id, class or structural selector',
+        }],
+    },
+    // Override globs are relative to the project root: c3b-lint sets configBasedir to it.
+    overrides: [
+        {
+            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: {
+                'custom-property-pattern': ['^[a-z][a-z0-9]*-[a-z0-9]+(-[a-z0-9]+)*$', {
+                    message: 'tokens are --{category}-{role}[-{variant}]: --color-text-muted, not --fg',
+                }],
+            },
+        },
+    ],
+};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "c3b-lint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "bin": {
+    "c3b-lint": "c3b-lint.js"
+  },
+  "files": [
+    "c3b-lint.js",
+    "check",
+    "config"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/colab47/c3b-lint.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "test": "node c3b-lint.js && node --test test/*.test.js",
+    "deploy": "npm run test && npm publish"
+  },
+  "dependencies": {
+    "@eslint/js": "9",
+    "eslint": "9",
+    "globals": "16",
+    "parse5": "7",
+    "postcss": "8",
+    "stylelint": "16",
+    "stylelint-config-recommended": "17"
+  }
+}