zemdomu 1.3.17 → 1.3.19

package/README.md

@@ -1,15 +1,35 @@
 # ZemDomu Core
 
-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 the GitHub Action.
+> The semantic rules engine behind ZemDomu.
 
-## What it is
+ZemDomu Core is the shared engine that powers the ZemDomu ecosystem. It parses
+HTML, JSX, TSX, and Vue templates and returns semantic issues that affect
+structure, accessibility, and search visibility.
 
-ZemDomu is a semantic-first linter that helps developers write better HTML and
-JSX by catching accessibility and structural issues. It parses `.html`, `.jsx`,
-`.tsx`, and `.vue` files and exposes a simple `lint()` function that returns
-semantic violations.
+Most linters check syntax. ZemDomu checks meaning.
+
+## What It Is
+
+ZemDomu Core is a semantic-first linting engine for modern frontend codebases.
+It helps developers catch issues like missing landmarks, confusing heading
+structure, unlabeled controls, weak semantic relationships, and cross-component
+composition problems before those issues become late-stage audit findings.
+
+This package provides the shared logic used by:
+
+- the ZemDomu CLI
+- the ZemDomu VS Code Extension
+- the ZemDomu GitHub Action
+
+## Why ZemDomu
+
+Compared with generic linters and scanner-only workflows, ZemDomu is designed
+to keep semantic analysis practical in real component codebases.
+
+- Cross-component analysis catches issues that only appear when components are composed.
+- One shared rules engine powers editor, CLI, and CI behavior consistently.
+- Diagnostics focus on semantic HTML, accessible naming, and document structure.
+- Custom-rule support lets teams extend checks without rebuilding a lint stack.
 
 ## Features
 
@@ -20,7 +40,6 @@ semantic violations.
 - 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)`.
 
 ## Installation
@@ -44,14 +63,10 @@ console.log(results);
 //   {
 //     line: 0,
 //     column: 0,
-//     message: '<img> tag missing alt attribute',
-//     rule: 'requireAltText'
+//     message: "<img> tag missing alt attribute",
+//     rule: "requireAltText"
 //   }
 // ]
-
-// Custom rules can be supplied via the `customRules` option
-// const myRule = { name: 'demo', test: node => false, message: 'demo' };
-// lint(html, { customRules: [myRule] });
 ```
 
 ## API
@@ -64,6 +79,7 @@ console.log(results);
 - `options.rules`: severity settings for built-in rules.
 - `options.customRules`: array of additional rules.
 - `options.filePath`: optional source file path.
+- `options.forceHtml`: treat input as HTML.
 - `options.perf`: attach a `PerformanceRecorder` instance.
 
 ### Example `LinterOptions`
@@ -78,7 +94,7 @@ interface LinterOptions {
 }
 ```
 
-Example enabling one rule as a warning:
+Example enabling rule severities:
 
 ```ts
 const results = lint(html, {
@@ -97,11 +113,11 @@ interface LintResult {
 }
 ```
 
-## CLI usage
+## CLI Usage
 
-Run the linter from the command line by installing the package globally or
+Run the linter from the command line by installing the package globally or by
 using `npx`. Provide one or more glob patterns to specify the files to lint.
-Patterns may be separated by spaces, commas, or newlines:
+Patterns may be separated by spaces, commas, or newlines.
 
 ```bash
 npx zemdomu "src/**/*.{html,jsx,tsx,vue}" --custom my-rule.js
@@ -110,27 +126,30 @@ 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. For safety, the CLI only accepts
-files inside a `./custom-rules` directory (relative to your current working
-directory). You can repeat `--custom` to load multiple rule files. Use `--cross`
-to enable cross component analysis.
+files inside a `./custom-rules` directory relative to your current working
+directory. You can repeat `--custom` to load multiple rule files.
+
+Use `--cross` to enable cross-component analysis.
 
 Use `--perf` to emit a JSON timing report to stdout, and `--perf-slowest` to
 also print the slowest file and phase.
 
-### Cross-component analysis
+## Cross-Component Analysis
 
-When analyzing JSX or Vue projects you can track `<h1>` usage or similar
-patterns across component boundaries. Instantiate `ProjectLinter` with the
+When analyzing JSX or Vue projects you can track semantic issues 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:
+`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
+  crossComponentDepth: 2,
 });
+
 await linter.lintFile("App.jsx");
 ```
 
@@ -138,23 +157,24 @@ await linter.lintFile("App.jsx");
 npx zemdomu "src/**/*.{jsx,tsx,vue}" --cross --cross-depth 2
 ```
 
-### Performance diagnostics
+## Performance Diagnostics
 
-Attach a `PerformanceDiagnostics` recorder to gather timing information for
-each file and rule:
+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
+## 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:
+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 {
@@ -177,13 +197,14 @@ Use it programmatically:
 
 ```ts
 import { lint } from "zemdomu";
+
 const results = lint("<foo></foo>", { customRules: [require("./my-rule")] });
 ```
 
-### Helper utilities
+### 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:
+AST. ZemDomu exposes helpers for traversal and attribute inspection:
 
 ```ts
 import {
@@ -201,13 +222,6 @@ import {
 } 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. JSX helpers like `getJsxAttribute`, `getJsxAttributeState`, and
-`getJsxExpressionState` help interpret JSX attributes and expressions, while
-`getTag` resolves JSX element names.
-
 Or via the CLI:
 
 ```bash
@@ -217,9 +231,10 @@ npx zemdomu file.html --custom custom-rules/my-rule.js
 npx zemdomu "src/**/*.{html,jsx,tsx,vue}" --perf --perf-slowest
 ```
 
-There is a sample rule in `custom-rules/example-rule.js` you can copy and edit.
+There is a sample rule in `custom-rules/example-rule.js` that you can copy and
+edit.
 
-## Local development (monorepo)
+## Local Development
 
 From the core package:
 
@@ -231,15 +246,12 @@ npm run build
 
 ## Links
 
-Development happens in a private monorepo; this repository is the public mirror
-for issues and updates.
-
-- NPM package: https://www.npmjs.com/package/zemdomu
-- Public mirror: https://github.com/Zemdomu/ZemDomu-core
-- Issues and suggestions: https://github.com/Zemdomu/ZemDomu-core/issues
+- npm package: https://www.npmjs.com/package/zemdomu
+- Website: https://zemdomu.dev/
+- Issues and suggestions: https://github.com/ZemDomu/ZemDomu-core/issues
 - VS Code extension: https://marketplace.visualstudio.com/items?itemName=ZachariasErydBerlin.zemdomu
-- GitHub Action: https://github.com/Zemdomu/ZemDomu-action
+- GitHub Action: https://github.com/ZemDomu/ZemDomu-action
 
 ## License
 
-MIT (c) 2025 Zacharias Eryd Berlin
+MIT (c) 2025 Zacharias Eryd Berlin

package/out/linter.js

@@ -25,6 +25,9 @@ const requireNavLinks_1 = __importDefault(require("./rules/requireNavLinks"));
 const uniqueIds_1 = __importDefault(require("./rules/uniqueIds"));
 const noTabindexGreaterThanZero_1 = __importDefault(require("./rules/noTabindexGreaterThanZero"));
 const preventZemdomuPlaceholders_1 = __importDefault(require("./rules/preventZemdomuPlaceholders"));
+const requireDocumentTitle_1 = __importDefault(require("./rules/requireDocumentTitle"));
+const requireSingleMain_1 = __importDefault(require("./rules/requireSingleMain"));
+const ariaValidAttrValue_1 = __importDefault(require("./rules/ariaValidAttrValue"));
 const rule_codes_1 = require("./rule-codes");
 const builtInRules = {
     requireSectionHeading: requireSectionHeading_1.default,
@@ -45,6 +48,9 @@ const builtInRules = {
     uniqueIds: uniqueIds_1.default,
     noTabindexGreaterThanZero: noTabindexGreaterThanZero_1.default,
     preventZemdomuPlaceholders: preventZemdomuPlaceholders_1.default,
+    requireDocumentTitle: requireDocumentTitle_1.default,
+    requireSingleMain: requireSingleMain_1.default,
+    ariaValidAttrValue: ariaValidAttrValue_1.default,
 };
 const defaultOptions = {
     rules: {
@@ -66,6 +72,9 @@ const defaultOptions = {
         uniqueIds: "error",
         noTabindexGreaterThanZero: "warning",
         preventZemdomuPlaceholders: "warning",
+        requireDocumentTitle: "error",
+        requireSingleMain: "error",
+        ariaValidAttrValue: "error",
     },
     customRules: [],
 };

package/out/project-linter.js

@@ -46,6 +46,55 @@ const component_path_resolver_1 = require("./component-path-resolver");
 const collectLocalDeps_1 = require("./utils/collectLocalDeps");
 const vue_sfc_1 = require("./utils/vue-sfc");
 const rule_codes_1 = require("./rule-codes");
+const FRAMEWORK_HOST_DOCUMENT_RULES = [
+    "requireHtmlLang",
+    "requireDocumentTitle",
+    "requireSingleMain",
+];
+function isHtmlFile(filePath) {
+    return /\.(html|htm)$/i.test(filePath);
+}
+function getHtmlTagAttribute(tag, name) {
+    var _a, _b, _c;
+    const match = new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i").exec(tag);
+    return match ? (_c = (_b = (_a = match[1]) !== null && _a !== void 0 ? _a : match[2]) !== null && _b !== void 0 ? _b : match[3]) !== null && _c !== void 0 ? _c : "" : null;
+}
+function hasFrameworkMountPoint(content) {
+    return /<[a-z][\w:-]*\b(?=[^>]*\bid\s*=\s*["'](?:app|root|app-root|mount|__nuxt|__next|svelte)["'])[^>]*>/i.test(content);
+}
+function isFrameworkEntrySrc(src) {
+    const normalized = src.replace(/[?#].*$/, "").replace(/\\/g, "/");
+    return /(?:^|\/)(?:src\/)?(?:main|index|app)\.(?:[cm]?[jt]sx?|vue)$/i.test(normalized);
+}
+function hasFrameworkModuleEntry(content) {
+    const scriptRe = /<script\b[^>]*>/gi;
+    let match;
+    while ((match = scriptRe.exec(content))) {
+        const tag = match[0];
+        const type = getHtmlTagAttribute(tag, "type");
+        if (!type || type.toLowerCase() !== "module")
+            continue;
+        const src = getHtmlTagAttribute(tag, "src");
+        if (src && isFrameworkEntrySrc(src))
+            return true;
+    }
+    return /<script\b(?=[^>]*\btype\s*=\s*["']?module["']?)[^>]*>[\s\S]*?\b(?:createApp|createRoot|ReactDOM\.render|new\s+Vue)\s*\(/i.test(content);
+}
+function isFrameworkHostHtml(filePath, content) {
+    if (path_1.default.basename(filePath).toLowerCase() !== "index.html")
+        return false;
+    if (!hasFrameworkMountPoint(content))
+        return false;
+    return hasFrameworkModuleEntry(content);
+}
+function suppressRules(options, ruleNames) {
+    var _a;
+    const rules = { ...((_a = options.rules) !== null && _a !== void 0 ? _a : {}) };
+    for (const ruleName of ruleNames) {
+        rules[ruleName] = "off";
+    }
+    return { ...options, rules };
+}
 class ProjectLinter {
     constructor(options = {}) {
         var _a;
@@ -61,16 +110,21 @@ class ProjectLinter {
         if (!content) {
             content = await fs.readFile(filePath, "utf8");
         }
-        const isVue = path_1.default.extname(filePath).toLowerCase() === ".vue";
+        const ext = path_1.default.extname(filePath).toLowerCase();
+        const isVue = ext === ".vue";
+        const isHtml = isHtmlFile(filePath);
         let lintContent = content;
         if (isVue) {
             const template = (0, vue_sfc_1.extractVueTemplate)(content);
             lintContent = (0, vue_sfc_1.isHtmlVueTemplate)(template) ? template.content : "";
         }
+        const lintOptions = isHtml && isFrameworkHostHtml(filePath, content)
+            ? suppressRules(this.opts, FRAMEWORK_HOST_DOCUMENT_RULES)
+            : this.opts;
         const results = (0, linter_1.lint)(lintContent, {
-            ...this.opts,
+            ...lintOptions,
             filePath,
-            forceHtml: isVue || this.opts.forceHtml,
+            forceHtml: isHtml || isVue || this.opts.forceHtml,
         });
         const resolvedResults = results.map((result) => result.filePath ? result : { ...result, filePath });
         const byFile = new Map();

package/out/rule-codes.d.ts

@@ -17,6 +17,9 @@ declare const RULE_CODES: {
     readonly uniqueIds: "ZMD016";
     readonly noTabindexGreaterThanZero: "ZMD017";
     readonly preventZemdomuPlaceholders: "ZMD018";
+    readonly requireDocumentTitle: "ZMD019";
+    readonly requireSingleMain: "ZMD020";
+    readonly ariaValidAttrValue: "ZMD021";
 };
 export declare function getRuleCode(rule: string): string | undefined;
 export declare function applyRuleCode<T extends {

package/out/rule-codes.js

@@ -22,6 +22,9 @@ const RULE_CODES = {
     uniqueIds: "ZMD016",
     noTabindexGreaterThanZero: "ZMD017",
     preventZemdomuPlaceholders: "ZMD018",
+    requireDocumentTitle: "ZMD019",
+    requireSingleMain: "ZMD020",
+    ariaValidAttrValue: "ZMD021",
 };
 exports.RULE_CODES = RULE_CODES;
 function getRuleCode(rule) {

package/out/rules/ariaValidAttrValue.d.ts

@@ -0,0 +1,2 @@
+import { Rule } from "../linter";
+export default function ariaValidAttrValue(): Rule;

package/out/rules/ariaValidAttrValue.js

@@ -0,0 +1,230 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = ariaValidAttrValue;
+const t = __importStar(require("@babel/types"));
+const BOOLEAN_ATTRS = new Set([
+    "aria-hidden",
+    "aria-expanded",
+    "aria-selected",
+    "aria-disabled",
+    "aria-required",
+    "aria-modal",
+    "aria-multiline",
+    "aria-multiselectable",
+    "aria-readonly",
+    "aria-busy",
+    "aria-atomic",
+]);
+const TRISTATE_ATTRS = new Set(["aria-checked", "aria-pressed"]);
+const NUMERIC_ATTRS = new Set([
+    "aria-level",
+    "aria-valuemin",
+    "aria-valuemax",
+    "aria-valuenow",
+    "aria-colindex",
+    "aria-rowindex",
+    "aria-colcount",
+    "aria-rowcount",
+    "aria-setsize",
+    "aria-posinset",
+]);
+const IDREF_LIST_ATTRS = new Set([
+    "aria-labelledby",
+    "aria-describedby",
+    "aria-controls",
+    "aria-owns",
+    "aria-details",
+    "aria-errormessage",
+    "aria-flowto",
+]);
+const TOKEN_ATTRS = {
+    "aria-current": new Set([
+        "page",
+        "step",
+        "location",
+        "date",
+        "time",
+        "true",
+        "false",
+    ]),
+    "aria-live": new Set(["off", "polite", "assertive"]),
+    "aria-sort": new Set(["none", "ascending", "descending", "other"]),
+    "aria-orientation": new Set(["horizontal", "vertical"]),
+    "aria-haspopup": new Set([
+        "false",
+        "true",
+        "menu",
+        "listbox",
+        "tree",
+        "grid",
+        "dialog",
+    ]),
+    "aria-autocomplete": new Set(["inline", "list", "both", "none"]),
+    "aria-invalid": new Set(["false", "true", "grammar", "spelling"]),
+};
+const MULTI_TOKEN_ATTRS = {
+    "aria-relevant": new Set(["additions", "removals", "text", "all"]),
+};
+function normalize(value) {
+    return value.trim().toLowerCase();
+}
+function isNumeric(value) {
+    if (!value.trim())
+        return false;
+    return Number.isFinite(Number(value));
+}
+function isNonEmptyIdRefList(value) {
+    const tokens = value
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter(Boolean);
+    return tokens.length > 0;
+}
+function isSupportedAriaAttr(attr) {
+    return (BOOLEAN_ATTRS.has(attr) ||
+        TRISTATE_ATTRS.has(attr) ||
+        NUMERIC_ATTRS.has(attr) ||
+        IDREF_LIST_ATTRS.has(attr) ||
+        Object.prototype.hasOwnProperty.call(TOKEN_ATTRS, attr) ||
+        Object.prototype.hasOwnProperty.call(MULTI_TOKEN_ATTRS, attr));
+}
+function isValidAriaValue(attr, rawValue) {
+    const value = normalize(rawValue);
+    if (!isSupportedAriaAttr(attr))
+        return true;
+    if (!value)
+        return false;
+    if (BOOLEAN_ATTRS.has(attr)) {
+        return value === "true" || value === "false";
+    }
+    if (TRISTATE_ATTRS.has(attr)) {
+        return (value === "true" ||
+            value === "false" ||
+            value === "mixed" ||
+            value === "undefined");
+    }
+    if (NUMERIC_ATTRS.has(attr)) {
+        return isNumeric(value);
+    }
+    if (IDREF_LIST_ATTRS.has(attr)) {
+        return isNonEmptyIdRefList(rawValue);
+    }
+    const tokenSet = TOKEN_ATTRS[attr];
+    if (tokenSet) {
+        return tokenSet.has(value);
+    }
+    const multiTokenSet = MULTI_TOKEN_ATTRS[attr];
+    if (multiTokenSet) {
+        const tokens = value.split(/\s+/).filter(Boolean);
+        return tokens.length > 0 && tokens.every((token) => multiTokenSet.has(token));
+    }
+    return true;
+}
+function jsxStaticAriaValue(attr) {
+    if (!attr.value)
+        return { value: "", dynamic: false };
+    if (t.isStringLiteral(attr.value))
+        return { value: attr.value.value, dynamic: false };
+    if (!t.isJSXExpressionContainer(attr.value))
+        return { value: "", dynamic: true };
+    const expr = attr.value.expression;
+    if (t.isStringLiteral(expr))
+        return { value: expr.value, dynamic: false };
+    if (t.isBooleanLiteral(expr))
+        return { value: String(expr.value), dynamic: false };
+    if (t.isNumericLiteral(expr))
+        return { value: String(expr.value), dynamic: false };
+    if (t.isTemplateLiteral(expr) && expr.expressions.length === 0) {
+        const staticValue = expr.quasis.map((q) => { var _a; return (_a = q.value.cooked) !== null && _a !== void 0 ? _a : q.value.raw; }).join("");
+        return { value: staticValue, dynamic: false };
+    }
+    return { value: "", dynamic: true };
+}
+function invalidValueResult(attr, rawValue, line, column) {
+    return {
+        line,
+        column,
+        message: `ARIA attribute "${attr}" has invalid value "${rawValue}"`,
+        rule: "ariaValidAttrValue",
+    };
+}
+function ariaValidAttrValue() {
+    return {
+        name: "ariaValidAttrValue",
+        enterHtml(node) {
+            if (node.type !== "element")
+                return [];
+            const results = [];
+            for (const [rawName, rawValue] of Object.entries(node.attrs)) {
+                const name = rawName.toLowerCase();
+                if (name.startsWith(":aria-") || name.startsWith("v-bind:aria-"))
+                    continue;
+                if (!name.startsWith("aria-"))
+                    continue;
+                if (!isSupportedAriaAttr(name))
+                    continue;
+                const value = String(rawValue !== null && rawValue !== void 0 ? rawValue : "");
+                if (!isValidAriaValue(name, value)) {
+                    results.push(invalidValueResult(name, value, 0, 0));
+                }
+            }
+            return results;
+        },
+        enterJsx(path) {
+            var _a, _b, _c, _d, _e, _f, _g, _h;
+            const results = [];
+            const attrs = path.node.openingElement.attributes;
+            for (const attr of attrs) {
+                if (!t.isJSXAttribute(attr) || !t.isJSXIdentifier(attr.name))
+                    continue;
+                const name = attr.name.name.toLowerCase();
+                if (!name.startsWith("aria-"))
+                    continue;
+                if (!isSupportedAriaAttr(name))
+                    continue;
+                const { value, dynamic } = jsxStaticAriaValue(attr);
+                if (dynamic)
+                    continue;
+                if (!isValidAriaValue(name, value)) {
+                    const line = ((_d = (_b = (_a = attr.loc) === null || _a === void 0 ? void 0 : _a.start.line) !== null && _b !== void 0 ? _b : (_c = path.node.loc) === null || _c === void 0 ? void 0 : _c.start.line) !== null && _d !== void 0 ? _d : 1) - 1;
+                    const column = (_h = (_f = (_e = attr.loc) === null || _e === void 0 ? void 0 : _e.start.column) !== null && _f !== void 0 ? _f : (_g = path.node.loc) === null || _g === void 0 ? void 0 : _g.start.column) !== null && _h !== void 0 ? _h : 0;
+                    results.push(invalidValueResult(name, value, line, column));
+                }
+            }
+            return results;
+        },
+    };
+}