c3b-lint 0.0.18 → 0.0.21

package/README.md

@@ -21,7 +21,9 @@ markdown that a tool can check, with one command and one config to install. It r
    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.
+5. The **500-line limit** on `src/**/*.{css,html}` (ESLint reports the JS); inline `<svg>` art is not counted, nor is
+   a [colab-partial](https://codeberg.org/colab47/colab-partial) region whose partial is in `src/partial/` (one line
+   each: the partial is counted on its own).
 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
@@ -85,7 +87,8 @@ A project's own settings go in its `package.json`, under `"c3b-lint"`:
   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.
+  Stylelint checks still run on them. For a file that can't be split. A page made long by the partials it carries
+  needs none: their regions count as one line each.
 
 The ESLint and Stylelint configs read these too, so WebStorm reports what the CLI does.
 
@@ -104,6 +107,14 @@ Findings print in sections, in the order they run — `--- c3b-lint ---` (checks
 `--- 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.
 
+With `C3B_LINT_REPORT=<path>` in the environment, every finding of the run is also written to that file as JSON,
+passed or failed: `{ version, errors, warnings, findings }`, each finding
+`{ check, file, line, column, severity, rule, message, fixable }` — `check` is `structure`, `html`, `tokens`,
+`editorconfig`, `lengths`, `eslint` or `stylelint`, `file` is relative to the project root, `rule` and `fixable`
+come from ESLint and Stylelint (null and false for c3b-lint's own checks). It's for a program reading the run —
+colab-desktop's Output summary. An environment variable rather than a flag: a caller that sets it for every project
+can't know which c3b-lint each one pins, and an older version ignores it where it would refuse a flag.
+
 ## Not covered
 
 Rules that need judgement stay with review: whether two selectors are structurally disjoint, flex vs grid, whether

package/c3b-lint.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, globSync, readFileSync, writeFileSync } from 'fs';
-import { dirname, join, resolve, sep } from 'path';
+import { dirname, join, relative, resolve, sep } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { ESLint } from 'eslint';
 import stylelint from 'stylelint';
@@ -83,6 +83,12 @@ for (const arg of args) {
 
 const fix = args.includes('--fix');
 const init = args.includes('--init');
+// Where to also write every finding as JSON, for a program reading the run (colab-desktop's Output
+// summary). An environment variable rather than a flag: a caller that sets it for every project can't
+// know which c3b-lint each one pins, and an older version ignores it where it would refuse a flag.
+const REPORT_FILE = process.env.C3B_LINT_REPORT;
+// ESLint's and Stylelint's findings, in the report's shape, as they come in
+const toolFindings = [];
 
 const toPosix = (p) => p.split(sep).join('/');
 
@@ -125,14 +131,21 @@ function checkEditorconfig(report) {
     }
 }
 
+// A colab-partial region: the opening marker's line, the copy, the closing marker's line naming the same partial
+const PARTIAL_REGION = /^[ \t]*<!-- partial ([\w./-]+) -->[ \t]*\r?\n[\s\S]*?^[ \t]*<!-- \/partial \1 -->/gm;
+
 // general.md: no hand-written file past 500 lines. ESLint reports JS; this covers CSS and HTML.
 function checkFileLengths(report) {
     const ignored = ignoredPaths();
     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/>');
+        // inline <svg> is vector art, not hand-written markup: its lines are not counted. Nor is a partial's
+        // copy (colab-partial writes it from src/partial/, which is counted on its own): one line, as long as
+        // that partial is there, so markers can't hide markup written nowhere else
+        const content = readFileSync(file, 'utf8')
+                .replace(/<svg[\s\S]*?<\/svg>/g, '<svg/>')
+                .replace(PARTIAL_REGION, (region, name) => (existsSync(join('src', 'partial', name)) ? `<!-- partial ${ name } -->` : region));
         const lines = content.split('\n').length - (content.endsWith('\n') ? 1 : 0);
         if (lines > MAX_LINES) {
             report.error(file, `is ${ lines } lines (limit ${ MAX_LINES }) — split it by responsibility`);
@@ -155,6 +168,16 @@ async function runEslint() {
     if (fix) {
         await ESLint.outputFixes(results);
     }
+    results.forEach((result) => result.messages.forEach((message) => toolFindings.push({
+        check: 'eslint',
+        file: toPosix(relative(process.cwd(), result.filePath)),
+        line: message.line ?? null,
+        column: message.column ?? null,
+        severity: message.severity === 2 ? 'error' : 'warning',
+        rule: message.ruleId ?? null,
+        message: message.message,
+        fixable: Boolean(message.fix)
+    })));
     const formatter = await eslint.loadFormatter('stylish');
     printSection('eslint', await formatter.format(results));
 
@@ -176,10 +199,35 @@ async function runStylelint() {
         formatter: 'string'
     });
     printSection('stylelint', result.report ?? result.output);
+    result.results.forEach((file) => file.warnings.forEach((warning) => toolFindings.push({
+        check: 'stylelint',
+        file: toPosix(relative(process.cwd(), file.source)),
+        line: warning.line ?? null,
+        column: warning.column ?? null,
+        severity: warning.severity === 'error' ? 'error' : 'warning',
+        rule: warning.rule ?? null,
+        // Stylelint ends each message with its rule in brackets; the report has the rule apart
+        message: warning.text.replace(/\s*\([^()]+\)$/, ''),
+        fixable: false
+    })));
 
     return result.results.reduce((sum, file) => sum + file.warnings.filter((w) => w.severity === 'error').length, 0);
 }
 
+// --- the JSON report --------------------------------------------------------
+
+// Every finding of the run, whether it failed or not: { version, errors, warnings, findings }, the
+// files relative to the project root. Written whole, once the checks are done.
+function writeReport(path, findings) {
+    const count = (severity) => findings.filter((finding) => finding.severity === severity).length;
+    const body = { version, errors: count('error'), warnings: count('warning'), findings };
+    try {
+        writeFileSync(resolve(path), `${ JSON.stringify(body, null, 2) }\n`);
+    } catch (error) {
+        fail(`could not write the report to ${ path }: ${ error.message }`);
+    }
+}
+
 // --- run ------------------------------------------------------------------
 
 // The checks run in a fixed order: c3b-lint's own, then ESLint, then Stylelint. Each tool's findings
@@ -213,11 +261,11 @@ async function main() {
     };
 
     const report = createReport();
-    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));
+    await timed('structure', () => checkStructure(report.as('structure')));
+    await timed('html', () => checkHtml(report.as('html')));
+    await timed('tokens', () => checkCssTokens(report.as('tokens')));
+    await timed('editorconfig', () => checkEditorconfig(report.as('editorconfig')));
+    await timed('lengths', () => checkFileLengths(report.as('lengths')));
     printSection(name, report.format());
     let errors = report.errors;
     errors += await timed('eslint', () => runEslint());
@@ -225,6 +273,9 @@ async function main() {
 
     console.log(`\n${ timings.join('\n') }`);
     console.log(`  ${ 'total'.padEnd(13) }${ Math.round(performance.now() - started) }ms`);
+    if (REPORT_FILE) {
+        writeReport(REPORT_FILE, [...report.findings(), ...toolFindings]);
+    }
     if (errors > 0) {
         fail(`${ errors } error(s)`);
     }

package/check/report.js

@@ -2,31 +2,56 @@ 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.
+// counter so main() knows how many errors were found. Each finding also keeps the check it came
+// from (as(check) hands a check its own reporter), for the JSON report (C3B_LINT_REPORT).
 export function createReport() {
     const byFile = new Map();
     let errors = 0;
     let warnings = 0;
 
     // Checks pass "file" or "file:line"
-    function add(where, level, message) {
+    function add(where, level, message, check) {
         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 });
+        byFile.get(file).push({ line, level, message, check });
+    }
+
+    function error(where, message, check = null) {
+        add(where, 'error', message, check);
+        errors++;
+    }
+
+    function warn(where, message, check = null) {
+        add(where, 'warning', message, check);
+        warnings++;
     }
 
     return {
-        error(where, message) {
-            add(where, 'error', message);
-            errors++;
+        error,
+        warn,
+        // the reporter one check is handed: the same report, its findings marked as that check's
+        as(check) {
+            return {
+                error: (where, message) => error(where, message, check),
+                warn: (where, message) => warn(where, message, check)
+            };
         },
-        warn(where, message) {
-            add(where, 'warning', message);
-            warnings++;
+        // every finding, for the JSON report: { check, file, line, column, severity, rule, message, fixable }
+        findings() {
+            return [...byFile.entries()].flatMap(([file, found]) => found.map((finding) => ({
+                check: finding.check,
+                file,
+                line: finding.line ? Number(finding.line) : null,
+                column: null,
+                severity: finding.level,
+                rule: null,
+                message: finding.message,
+                fixable: false
+            })));
         },
         // The whole report as one string, empty when nothing was found
         format() {

package/package.json

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