zemdomu 1.1.5 → 1.3.0

package/README.md

@@ -1,8 +1,8 @@
-# ZemDomu Core
+# ZemDomu
 
 Semantic HTML linting engine for clean, accessible and SEO-friendly markup. This package provides the shared core logic used by the ZemDomu VS Code extension and upcoming GitHub Action.
 
-## 🧠 What is ZemDomu Core?
+## 🧠 What is ZemDomu?
 
 **ZemDomu** is a semantic-first linter that helps developers write better HTML and JSX by catching accessibility and structural issues. It parses `.html`, `.jsx` and `.tsx` files and exposes a simple `lint()` function that returns semantic violations.
 
@@ -18,16 +18,20 @@ yarn add zemdomu
 
 - ✅ Lint semantic issues in HTML, JSX and TSX
 - 📦 Works in Node.js, CI or any JS runtime
-- ⚙️ Extensible rule system
+- ⚙️ Extensible rule system with simple custom rules
+- 🔀 Cross-component analysis for React/JSX projects
+- 🚀 Command line interface with `--custom` and `--cross`
+- ⚠️ Configurable rule severity (`error`, `warning`, `off`)
+- 📈 Performance diagnostics for profiling lint runs
 - 📚 Shared by the extension and GitHub Action
 - 🧪 Simple API: `lint(content, options)`
 
 ## ⚙️ Usage Example
 
 ```ts
-import { lint } from 'zemdomu';
+import { lint } from "zemdomu";
 
-const html = '<img>';
+const html = "<img>";
 const results = lint(html, { rules: { requireAltText: true } });
 
 console.log(results);
@@ -41,7 +45,7 @@ console.log(results);
 // ]
 
 // Custom rules can be supplied via the `customRules` option
-// const myRule = { name: 'demo', checkHtml: () => [] };
+// const myRule = { name: 'demo', test: node => false, message: 'demo' };
 // lint(html, { customRules: [myRule] });
 ```
 
@@ -52,21 +56,30 @@ console.log(results);
 **Parameters**
 
 - `content` — HTML, JSX or TSX string input
-- `options.rules` — toggles for built-in rules
+- `options.rules` — severity settings for built-in rules
 - `options.customRules` — array of additional rules
+- `options.filePath` — optional source file path
+- `options.perf` — attach a `PerformanceRecorder` instance
 
 **Example `LinterOptions`**
 
 ```ts
 interface LinterOptions {
-  rules: {
-    requireAltText: boolean;
-    // ...more rules to come
-  };
+  rules?: Record<string, 'error' | 'warning' | 'off'>;
   customRules?: Rule[];
+  filePath?: string;
+  perf?: PerformanceRecorder;
 }
 ```
 
+Example enabling one rule as a warning:
+
+```ts
+const results = lint(html, {
+  rules: { requireAltText: 'warning', uniqueIds: 'error' }
+});
+```
+
 **Example `LintResult`**
 
 ```ts
@@ -78,9 +91,112 @@ interface LintResult {
 }
 ```
 
+## 🛠 CLI Usage
+
+Run the linter from the command line by installing the package globally or using
+`npx`. Provide one or more glob patterns to specify the files to lint. Patterns
+may be separated by spaces, commas or newlines:
+
+```bash
+npx zemdomu "src/**/*.{html,jsx,tsx}" --custom my-rule.js
+npx zemdomu "src/**/*.html,src/**/*.jsx"
+```
+
+Use `--custom` (or `-c`) to provide a path to a JavaScript or TypeScript module
+exporting a custom rule or array of rules. Use `--cross` to enable cross
+component analysis.
+
+### Cross-Component Analysis
+
+When analysing JSX projects you can track `<h1>` usage or similar patterns
+across component boundaries. Instantiate `ProjectLinter` with the
+`crossComponentAnalysis` option or pass `--cross` to the CLI. Use
+`crossComponentDepth` (or `--cross-depth`) to limit how deep component trees are
+traversed during analysis:
+
+```ts
+import { ProjectLinter } from 'zemdomu';
+const linter = new ProjectLinter({ crossComponentAnalysis: true, crossComponentDepth: 2 });
+await linter.lintFile('App.jsx');
+```
+
+```bash
+npx zemdomu "src/**/*.{jsx,tsx}" --cross --cross-depth 2
+```
+
+### Performance Diagnostics
+
+Attach a `PerformanceDiagnostics` recorder to gather timing information for each
+file and rule:
+
+```ts
+import { lint, PerformanceDiagnostics } from 'zemdomu';
+const perf = new PerformanceDiagnostics();
+lint(code, { perf });
+console.log(perf.getAsJSON());
+```
+
+## 📝 Writing Custom Rules
+
+Custom rules are simple objects implementing the `Rule` interface. At minimum
+provide a `name`, a `test` function that returns `true` when a node violates the
+rule and a `message` describing the problem:
+
+```ts
+interface Rule {
+  name: string;
+  test(node: any): boolean;
+  message: string;
+}
+```
+
+```js
+// my-rule.js
+module.exports = {
+  name: 'noFooDiv',
+  test: node => node.type === 'element' && node.tagName === 'foo',
+  message: '<foo> is not allowed'
+};
+```
+
+Use it programmatically:
+
+```ts
+import { lint } from 'zemdomu';
+const results = lint('<foo></foo>', { customRules: [require('./my-rule')] });
+```
+
+### Helper Utilities
+
+For more advanced rules you may need direct access to the parsed HTML or JSX
+AST. ZemDomu exposes a few helpers to make this easier:
+
+```ts
+import {
+  parseHtml,
+  visitHtml,
+  getAttr,
+  getJsxAttr,
+  getTag,
+  ElementNode,
+  HtmlVisitor,
+} from 'zemdomu';
+```
+
+`parseHtml` returns the root `ElementNode`. The `visitHtml` function performs a
+simple depth‑first traversal using an `HtmlVisitor` with optional `enter` and
+`exit` callbacks. Utility functions like `getAttr` and `getJsxAttr` help reading
+attributes, while `getTag` resolves JSX element names.
+
+Or via the CLI:
+
+```bash
+npx zemdomu file.html --custom my-rule.js
+```
+
 ## 🔗 Related Tools
 
-- [ZemDomu VS Code Extension](../ZemDomu-Extension)
+- [ZemDomu VS Code Extension](https://marketplace.visualstudio.com/items?itemName=ZachariasErydBerlin.zemdomu)
 - ZemDomu GitHub Action (coming soon)
 
 ## 🛠 Development

package/out/linter.js

@@ -1,164 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.lint = lint;
-const simpleHtmlParser_1 = require("./simpleHtmlParser");
-const parser_1 = require("@babel/parser");
-const traverse_1 = __importDefault(require("@babel/traverse"));
-const requireAltText_1 = __importDefault(require("./rules/requireAltText"));
-const requireSectionHeading_1 = __importDefault(require("./rules/requireSectionHeading"));
-const enforceHeadingOrder_1 = __importDefault(require("./rules/enforceHeadingOrder"));
-const singleH1_1 = __importDefault(require("./rules/singleH1"));
-const requireLabelForFormControls_1 = __importDefault(require("./rules/requireLabelForFormControls"));
-const enforceListNesting_1 = __importDefault(require("./rules/enforceListNesting"));
-const requireLinkText_1 = __importDefault(require("./rules/requireLinkText"));
-const requireTableCaption_1 = __importDefault(require("./rules/requireTableCaption"));
-const preventEmptyInlineTags_1 = __importDefault(require("./rules/preventEmptyInlineTags"));
-const requireHrefOnAnchors_1 = __importDefault(require("./rules/requireHrefOnAnchors"));
-const requireButtonText_1 = __importDefault(require("./rules/requireButtonText"));
-const requireIframeTitle_1 = __importDefault(require("./rules/requireIframeTitle"));
-const requireHtmlLang_1 = __importDefault(require("./rules/requireHtmlLang"));
-const requireImageInputAlt_1 = __importDefault(require("./rules/requireImageInputAlt"));
-const requireNavLinks_1 = __importDefault(require("./rules/requireNavLinks"));
-const uniqueIds_1 = __importDefault(require("./rules/uniqueIds"));
-const noTabindexGreaterThanZero_1 = __importDefault(require("./rules/noTabindexGreaterThanZero"));
-const builtInRules = {
-    requireSectionHeading: requireSectionHeading_1.default,
-    enforceHeadingOrder: enforceHeadingOrder_1.default,
-    singleH1: singleH1_1.default,
-    requireAltText: requireAltText_1.default,
-    requireLabelForFormControls: requireLabelForFormControls_1.default,
-    enforceListNesting: enforceListNesting_1.default,
-    requireLinkText: requireLinkText_1.default,
-    requireTableCaption: requireTableCaption_1.default,
-    preventEmptyInlineTags: preventEmptyInlineTags_1.default,
-    requireHrefOnAnchors: requireHrefOnAnchors_1.default,
-    requireButtonText: requireButtonText_1.default,
-    requireIframeTitle: requireIframeTitle_1.default,
-    requireHtmlLang: requireHtmlLang_1.default,
-    requireImageInputAlt: requireImageInputAlt_1.default,
-    requireNavLinks: requireNavLinks_1.default,
-    uniqueIds: uniqueIds_1.default,
-    noTabindexGreaterThanZero: noTabindexGreaterThanZero_1.default,
-};
-const defaultOptions = {
-    rules: {
-        requireSectionHeading: true,
-        enforceHeadingOrder: true,
-        singleH1: true,
-        requireAltText: true,
-        requireLabelForFormControls: true,
-        enforceListNesting: true,
-        requireLinkText: true,
-        requireTableCaption: true,
-        preventEmptyInlineTags: true,
-        requireHrefOnAnchors: true,
-        requireButtonText: true,
-        requireIframeTitle: true,
-        requireHtmlLang: true,
-        requireImageInputAlt: true,
-        requireNavLinks: true,
-        uniqueIds: true,
-        noTabindexGreaterThanZero: true,
-    },
-    customRules: [],
-};
-/**
- * Lint HTML/JSX/TSX content.
- */
-function lint(content, options = defaultOptions) {
-    var _a;
-    const opts = {
-        rules: { ...defaultOptions.rules, ...(options.rules || {}) },
-        customRules: (_a = options.customRules) !== null && _a !== void 0 ? _a : defaultOptions.customRules,
-    };
-    const results = [];
-    const activeRules = [];
-    for (const name in opts.rules) {
-        const enabled = opts.rules[name];
-        if (enabled && builtInRules[name]) {
-            activeRules.push(builtInRules[name]());
-        }
-    }
-    if (opts.customRules)
-        activeRules.push(...opts.customRules);
-    activeRules.forEach(r => r.init && r.init());
-    let ast = null;
-    try {
-        ast = (0, parser_1.parse)(content, {
-            sourceType: 'module',
-            plugins: ['typescript', 'jsx'],
-        });
-    }
-    catch {
-        ast = null;
-    }
-    if (ast) {
-        (0, traverse_1.default)(ast, {
-            JSXElement: {
-                enter(path) {
-                    var _a;
-                    for (const rule of activeRules) {
-                        if (rule.enterJsx) {
-                            try {
-                                results.push(...rule.enterJsx(path));
-                            }
-                            catch (e) {
-                                console.error(`[ZemDomu] Error in rule ${rule.name} (${(_a = opts.filePath) !== null && _a !== void 0 ? _a : 'unknown'}):`, e);
-                            }
-                        }
-                    }
-                },
-                exit(path) {
-                    var _a;
-                    for (const rule of activeRules) {
-                        if (rule.exitJsx) {
-                            try {
-                                results.push(...rule.exitJsx(path));
-                            }
-                            catch (e) {
-                                console.error(`[ZemDomu] Error in rule ${rule.name} (${(_a = opts.filePath) !== null && _a !== void 0 ? _a : 'unknown'}):`, e);
-                            }
-                        }
-                    }
-                },
-            },
-        });
-        activeRules.forEach(r => r.end && results.push(...r.end()));
-        return results;
-    }
-    const root = (0, simpleHtmlParser_1.parse)(content);
-    const walk = (node) => {
-        var _a, _b;
-        for (const rule of activeRules) {
-            if (rule.enterHtml) {
-                try {
-                    results.push(...rule.enterHtml(node));
-                }
-                catch (e) {
-                    console.error(`[ZemDomu] Error in rule ${rule.name} (${(_a = opts.filePath) !== null && _a !== void 0 ? _a : 'unknown'}):`, e);
-                }
-            }
-        }
-        if (node.children) {
-            for (const child of node.children) {
-                walk(child);
-            }
-        }
-        for (const rule of activeRules) {
-            if (rule.exitHtml) {
-                try {
-                    results.push(...rule.exitHtml(node));
-                }
-                catch (e) {
-                    console.error(`[ZemDomu] Error in rule ${rule.name} (${(_b = opts.filePath) !== null && _b !== void 0 ? _b : 'unknown'}):`, e);
-                }
-            }
-        }
-    };
-    walk(root);
-    activeRules.forEach(r => r.end && results.push(...r.end()));
-    return results;
-}

package/out/src/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const glob_1 = __importDefault(require("glob"));
+const path_1 = __importDefault(require("path"));
+const project_linter_1 = require("./project-linter");
+function parsePatterns(inputs) {
+    const result = [];
+    for (const input of inputs) {
+        const splits = input
+            .split(/\r?\n/)
+            .flatMap((p) => p.split(/[ ,]+/))
+            .filter(Boolean);
+        result.push(...splits);
+    }
+    return result;
+}
+async function run() {
+    var _a;
+    const args = process.argv.slice(2);
+    const rawPatterns = [];
+    const customRules = [];
+    let cross = false;
+    let depth;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--custom' || arg === '-c') {
+            const file = args[++i];
+            if (!file)
+                throw new Error('Missing file for --custom');
+            const resolved = path_1.default.resolve(file);
+            const customDir = path_1.default.resolve('custom-rules');
+            const relative = path_1.default.relative(customDir, resolved);
+            if (relative.startsWith('..') || path_1.default.isAbsolute(relative)) {
+                throw new Error('Custom rule file must be inside ./custom-rules');
+            }
+            const mod = require(resolved);
+            const rules = (_a = mod.default) !== null && _a !== void 0 ? _a : mod;
+            if (Array.isArray(rules))
+                customRules.push(...rules);
+            else
+                customRules.push(rules);
+        }
+        else if (arg === '--cross') {
+            cross = true;
+        }
+        else if (arg === '--cross-depth') {
+            const val = args[++i];
+            if (!val)
+                throw new Error('Missing value for --cross-depth');
+            depth = parseInt(val, 10);
+            if (isNaN(depth))
+                throw new Error('Invalid number for --cross-depth');
+            cross = true;
+        }
+        else {
+            rawPatterns.push(arg);
+        }
+    }
+    const patterns = parsePatterns(rawPatterns);
+    if (patterns.length === 0) {
+        patterns.push('**/*.{html,jsx,tsx}');
+    }
+    const files = new Set();
+    for (const pattern of patterns) {
+        const matches = glob_1.default.sync(pattern, { nodir: true });
+        for (const m of matches)
+            files.add(m);
+    }
+    const linter = new project_linter_1.ProjectLinter({ customRules, crossComponentAnalysis: cross, crossComponentDepth: depth });
+    const results = await linter.lintFiles(Array.from(files));
+    let hasIssues = false;
+    for (const [file, issues] of results.entries()) {
+        for (const issue of issues) {
+            console.error(`${file}:${issue.line + 1}:${issue.column + 1} ${issue.rule}: ${issue.message}`);
+            hasIssues = true;
+        }
+    }
+    if (hasIssues)
+        process.exit(1);
+}
+run().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});