@schalkneethling/miyagi-core 4.4.4 → 4.5.1

package/api/index.js

@@ -12,6 +12,11 @@ import {
   toSchemaValidationResult,
   validateSchemas,
 } from "../lib/validator/schemas.js";
+import {
+  validateAllHtml as validateAllHtmlImpl,
+  validateComponentHtml as validateComponentHtmlImpl,
+} from "../lib/validator/html.js";
+import { generateMarkdownReport } from "../lib/validator/html-report.js";
 
 /**
  * @param {object} obj
@@ -307,6 +312,54 @@ function getComponentsObject(component) {
  * @param {Map<string, Array<object>>} params.errorMap
  * @returns {Array<object>}
  */
+/**
+ * @param {object} [options]
+ * @param {object} [options.htmlValidateConfig]
+ * @returns {Promise<object>}
+ */
+export const validateHtml = async (options = {}) => {
+  global.app = await init("api");
+  const results = await validateAllHtmlImpl(options);
+  const report = generateMarkdownReport(results);
+  return {
+    success: results.summary.failed === 0,
+    data: { results, report },
+  };
+};
+
+/**
+ * @param {object} obj
+ * @param {string|null} obj.component
+ * @param {object} [obj.htmlValidateConfig]
+ * @returns {Promise<object>}
+ */
+export const validateHtmlComponent = async (
+  { component, ...options } = { component: null },
+) => {
+  if (!component)
+    return {
+      success: false,
+      message:
+        'Please pass a component to `validateHtmlComponent` ({ component: "name" }).',
+    };
+
+  global.app = await init("api");
+
+  const componentObject = getComponentsObject(component);
+
+  if (!componentObject)
+    return {
+      success: false,
+      message: `Component "${component}" does not exist.`,
+    };
+
+  const result = await validateComponentHtmlImpl(componentObject, options);
+  return {
+    success: result.variations.every((v) => v.valid),
+    data: result,
+  };
+};
+
 function getLintComponentErrorsInRouteOrder({ components, errorMap }) {
   return components
     .map((route) => {

package/lib/cli/index.js

@@ -2,8 +2,10 @@ import lintImport from "./lint.js";
 import componentImport from "./component.js";
 import drupalAssetsImport from "./drupal-assets.js";
 import doctorImport from "./doctor.js";
+import validateHtmlImport from "./validate-html.js";
 
 export const lint = lintImport;
 export const component = componentImport;
 export const drupalAssets = drupalAssetsImport;
 export const doctor = doctorImport;
+export const validateHtml = validateHtmlImport;

package/lib/cli/run.js

@@ -9,6 +9,7 @@ import {
   component as createComponentViaCli,
   drupalAssets,
   doctor,
+  validateHtml as validateHtmlCli,
 } from "./index.js";
 import { EXIT_CODES, MiyagiError } from "../errors.js";
 
@@ -220,6 +221,11 @@ async function runDrupalAssetsCommand(args) {
  * @param {object} args
  * @returns {Promise<object>}
  */
+async function runValidateHtmlCommand(args) {
+  applyCliEnv(args);
+  return await validateHtmlCli(args);
+}
+
 async function runDoctorCommand(args) {
   applyCliEnv(args);
   return await doctor(args);
@@ -268,6 +274,7 @@ export async function runCli(argv = process.argv) {
       new: runComponentCommand,
       mocks: runMocksCommand,
       lint: runLintCommand,
+      validateHtml: runValidateHtmlCommand,
       drupalAssets: runDrupalAssetsCommand,
       doctor: runDoctorCommand,
     },

package/lib/cli/validate-html.js

@@ -0,0 +1,110 @@
+import path from "path";
+import { writeFile } from "node:fs/promises";
+import init from "./app.js";
+import getConfig from "../config.js";
+import log from "../logger.js";
+import { t } from "../i18n/index.js";
+import { EXIT_CODES } from "../errors.js";
+import {
+  validateAllHtml,
+  validateComponentHtml,
+  validateHtmlFiles,
+} from "../validator/html.js";
+import { generateMarkdownReport } from "../validator/html-report.js";
+
+/**
+ * @param {object} args
+ * @returns {Promise<object>}
+ */
+export default async function validateHtml(args) {
+  process.env.NODE_ENV = "development";
+
+  const filesGlob = args.files;
+
+  if (filesGlob) {
+    // Files mode — validate pre-existing HTML files
+    const config = await getConfig(args);
+    global.config = config;
+    const results = await validateHtmlFiles(filesGlob);
+    return await writeReport(results, args, config);
+  }
+
+  // Render mode — render components and validate
+  const componentArg = args.component;
+  const config = await getConfig(args);
+  global.app = await init(config);
+
+  let results;
+
+  if (componentArg) {
+    const component = global.state.routes.find(
+      ({ alias }) =>
+        alias === path.relative(config.components.folder, componentArg),
+    );
+
+    if (!component) {
+      const message = t("htmlValidation.componentNotFound").replace("{{component}}", componentArg);
+      log("error", message);
+      return {
+        success: false,
+        code: EXIT_CODES.CLI_USAGE_ERROR,
+        shouldExit: true,
+        message,
+      };
+    }
+
+    const result = await validateComponentHtml(component);
+    results = {
+      components: [result],
+      summary: {
+        total: 1,
+        passed: result.variations.every((v) => v.valid) ? 1 : 0,
+        failed: result.variations.some((v) => !v.valid) ? 1 : 0,
+        errors: result.variations.reduce(
+          (sum, v) =>
+            sum + v.messages.filter((m) => m.severity === 2).length,
+          0,
+        ),
+        warnings: result.variations.reduce(
+          (sum, v) =>
+            sum + v.messages.filter((m) => m.severity !== 2).length,
+          0,
+        ),
+      },
+    };
+  } else {
+    results = await validateAllHtml();
+  }
+
+  return await writeReport(results, args, config);
+}
+
+/**
+ * @param {object} results
+ * @param {object} args
+ * @param {object} config
+ * @returns {Promise<object>}
+ */
+async function writeReport(results, args, config) {
+  const report = generateMarkdownReport(results);
+  const outputPath = args.output ?? config.htmlValidation?.output ?? "html-validation-report.md";
+
+  try {
+    await writeFile(outputPath, report, "utf-8");
+    log(
+      "info",
+      t("htmlValidation.reportWritten").replace("{{path}}", outputPath),
+    );
+  } catch (error) {
+    log("error", t("htmlValidation.reportWriteFailed").replace("{{error}}", error.message));
+  }
+
+  return {
+    success: results.summary.failed === 0,
+    code:
+      results.summary.failed === 0
+        ? EXIT_CODES.SUCCESS
+        : EXIT_CODES.VALIDATION_ERROR,
+    shouldExit: true,
+  };
+}

package/lib/default-config.js

@@ -49,6 +49,18 @@ export default {
     lint: {
       logLevel: "error",
     },
+    htmlValidation: {
+      output: "html-validation-report.md",
+      htmlValidateConfig: {
+        extends: ["html-validate:recommended"],
+        rules: {
+          "doctype-style": "off",
+          "input-missing-label": "error",
+          "missing-doctype": "off",
+          "no-missing-references": "off",
+        },
+      },
+    },
     extensions: [],
     files: {
       css: {

package/lib/i18n/en.js

@@ -31,6 +31,29 @@ export default {
       done: "Finished creating component {{component}}.",
     },
   },
+  htmlValidation: {
+    all: {
+      start: "Validating rendered HTML for all components\u2026",
+      valid: "All rendered HTML is valid!",
+      invalid: {
+        one: "1 component has HTML validation errors!",
+        other: "{{amount}} components have HTML validation errors!",
+      },
+    },
+    component: {
+      start: "Validating rendered HTML for {{component}}\u2026",
+      valid: "Rendered HTML is valid!",
+      renderFailed:
+        "Could not render {{component}} variation {{variation}}.",
+    },
+    files: {
+      start: "Validating HTML files matching {{pattern}}\u2026",
+      noFilesFound: "No files found matching {{pattern}}.",
+    },
+    componentNotFound: "The component {{component}} does not seem to exist.",
+    reportWriteFailed: "Failed to write report: {{error}}.",
+    reportWritten: "HTML validation report written to {{path}}.",
+  },
   linter: {
     all: {
       start: "Validating schema files and mock data for all components…",

package/lib/init/args.js

@@ -101,6 +101,28 @@ export default function createCli(handlers, argv = process.argv) {
         }),
       commandHandler(handlers.lint),
     )
+    .command(
+      "validate-html [component]",
+      "Validates rendered HTML of components and generates a Markdown report",
+      (builder) =>
+        builder
+          .positional("component", {
+            description: "Optional component path to validate (render mode)",
+            type: "string",
+          })
+          .option("files", {
+            alias: "f",
+            description:
+              "Glob pattern pointing to HTML files to validate (e.g. build/miyagi/component-*.html)",
+            type: "string",
+          })
+          .option("output", {
+            alias: "o",
+            description: "Path for the Markdown report file",
+            type: "string",
+          }),
+      commandHandler(handlers.validateHtml),
+    )
     .command(
       "drupal-assets",
       "Resolves Drupal *.libraries.yml dependencies and updates component $assets in mock files",

package/lib/validator/html-report.js

@@ -0,0 +1,85 @@
+/**
+ * Generate a Markdown report from HTML validation results.
+ * @param {object} results - output from validateAllHtml, validateComponentHtml, or validateHtmlFiles
+ * @param {Array<object>} results.components
+ * @param {object} results.summary
+ * @returns {string} Markdown-formatted report
+ */
+export function generateMarkdownReport(results) {
+  const { components, summary } = results;
+  const lines = [];
+
+  lines.push("# HTML Validation Report");
+  lines.push("");
+  lines.push(`**Date:** ${new Date().toISOString().split("T")[0]}`);
+  lines.push(
+    `**Total components:** ${summary.total} | **Passed:** ${summary.passed} | **Failed:** ${summary.failed}`,
+  );
+  lines.push(
+    `**Errors:** ${summary.errors} | **Warnings:** ${summary.warnings}`,
+  );
+  lines.push("");
+
+  // Summary table
+  lines.push("## Summary");
+  lines.push("");
+  lines.push("| Component | Status | Errors | Warnings |");
+  lines.push("|-----------|--------|--------|----------|");
+
+  for (const comp of components) {
+    const hasErrors = comp.variations.some((v) => !v.valid);
+    const status = hasErrors ? "FAIL" : "PASS";
+    let errors = 0;
+    let warnings = 0;
+
+    for (const variation of comp.variations) {
+      for (const msg of variation.messages) {
+        if (msg.severity === 2) {
+          errors++;
+        } else {
+          warnings++;
+        }
+      }
+    }
+
+    lines.push(`| ${comp.component} | ${status} | ${errors} | ${warnings} |`);
+  }
+
+  // Failed component details
+  const failedComponents = components.filter((comp) =>
+    comp.variations.some((v) => !v.valid),
+  );
+
+  if (failedComponents.length > 0) {
+    lines.push("");
+    lines.push("## Failed Components");
+
+    for (const comp of failedComponents) {
+      lines.push("");
+      lines.push(`### ${comp.component}`);
+
+      const failedVariations = comp.variations.filter((v) => !v.valid);
+
+      for (const variation of failedVariations) {
+        lines.push("");
+        lines.push(`#### ${variation.name}`);
+        lines.push("");
+        lines.push("| Line | Col | Severity | Rule | Message |");
+        lines.push("|------|-----|----------|------|---------|");
+
+        for (const msg of variation.messages) {
+          const severity = msg.severity === 2 ? "error" : "warning";
+          const escapedMessage = msg.message
+            .replace(/\\/g, "\\\\")
+            .replace(/\|/g, "\\|");
+          lines.push(
+            `| ${msg.line} | ${msg.column} | ${severity} | ${msg.ruleId} | ${escapedMessage} |`,
+          );
+        }
+      }
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}

package/lib/validator/html.js

@@ -0,0 +1,389 @@
+import { readFile } from "node:fs/promises";
+import { globSync } from "node:fs";
+import path from "path";
+import { HtmlValidate } from "html-validate";
+import { getComponentData } from "../mocks/index.js";
+import { t } from "../i18n/index.js";
+import log from "../logger.js";
+
+/**
+ * @param {string} templatePath
+ * @param {object} data
+ * @returns {Promise<string>}
+ */
+function renderTemplate(templatePath, data) {
+  return new Promise((resolve, reject) => {
+    global.app.render(templatePath, data, (error, result) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve(result);
+      }
+    });
+  });
+}
+
+/**
+ * @param {object} htmlValidateConfig
+ * @returns {HtmlValidate}
+ */
+function createValidator(htmlValidateConfig) {
+  return new HtmlValidate(htmlValidateConfig);
+}
+
+/**
+ * @param {Array<object>} componentResults
+ * @returns {object}
+ */
+function buildSummary(componentResults) {
+  let errors = 0;
+  let warnings = 0;
+  let passed = 0;
+  let failed = 0;
+
+  for (const comp of componentResults) {
+    const hasErrors = comp.variations.some((v) => !v.valid);
+    if (hasErrors) {
+      failed++;
+    } else {
+      passed++;
+    }
+    for (const variation of comp.variations) {
+      for (const msg of variation.messages) {
+        if (msg.severity === 2) {
+          errors++;
+        } else {
+          warnings++;
+        }
+      }
+    }
+  }
+
+  return {
+    total: componentResults.length,
+    passed,
+    failed,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Validate rendered HTML for all components.
+ * @param {object} [options]
+ * @param {object} [options.htmlValidateConfig]
+ * @returns {Promise<{components: Array<object>, summary: object}>}
+ */
+export async function validateAllHtml(options = {}) {
+  const config =
+    options.htmlValidateConfig ?? global.config.htmlValidation?.htmlValidateConfig;
+  const validator = createValidator(config);
+  const components = global.state.routes.filter(
+    (route) => route.type === "components" && route.paths.tpl,
+  );
+
+  log(
+    "info",
+    t("htmlValidation.all.start"),
+  );
+
+  const componentResults = await Promise.all(
+    components.map((component) =>
+      validateSingleComponent(component, validator),
+    ),
+  );
+
+  const summary = buildSummary(componentResults);
+
+  if (summary.failed === 0) {
+    log("success", t("htmlValidation.all.valid"));
+  } else {
+    const msg =
+      summary.failed === 1
+        ? t("htmlValidation.all.invalid.one")
+        : t("htmlValidation.all.invalid.other").replace(
+            "{{amount}}",
+            summary.failed,
+          );
+    log("error", msg);
+  }
+
+  return { components: componentResults, summary };
+}
+
+/**
+ * Validate rendered HTML for a single component (all variations).
+ * @param {object} component - route object from global.state.routes
+ * @param {object} [options]
+ * @param {object} [options.htmlValidateConfig]
+ * @returns {Promise<{component: string, variations: Array<object>}>}
+ */
+export async function validateComponentHtml(component, options = {}) {
+  const config =
+    options.htmlValidateConfig ?? global.config.htmlValidation?.htmlValidateConfig;
+  const validator = createValidator(config);
+
+  log(
+    "info",
+    t("htmlValidation.component.start").replace(
+      "{{component}}",
+      component.paths.dir.short,
+    ),
+  );
+
+  const result = await validateSingleComponent(component, validator);
+
+  const allValid = result.variations.every((v) => v.valid);
+  if (allValid) {
+    log("success", t("htmlValidation.component.valid"));
+  }
+
+  return result;
+}
+
+/**
+ * @param {object} component
+ * @param {HtmlValidate} validator
+ * @returns {Promise<{component: string, variations: Array<object>}>}
+ */
+async function validateSingleComponent(component, validator) {
+  const data = await getComponentData(component);
+  const variations = [];
+
+  if (data && data.length > 0) {
+    for (const entry of data) {
+      try {
+        const html = await renderTemplate(
+          component.paths.tpl.full,
+          entry.resolved ?? {},
+        );
+        const report = await validator.validateString(html);
+        const messages = report.results.flatMap((r) =>
+          r.messages.map((msg) => ({
+            severity: msg.severity,
+            message: msg.message,
+            ruleId: msg.ruleId,
+            line: msg.line,
+            column: msg.column,
+          })),
+        );
+
+        variations.push({
+          name: entry.name,
+          valid: report.valid,
+          messages,
+        });
+      } catch (error) {
+        log(
+          "warn",
+          t("htmlValidation.component.renderFailed")
+            .replace("{{component}}", component.paths.dir.short)
+            .replace("{{variation}}", entry.name),
+        );
+        variations.push({
+          name: entry.name,
+          valid: false,
+          messages: [
+            {
+              severity: 2,
+              message: `Render error: ${error.message || error}`,
+              ruleId: "render-error",
+              line: 0,
+              column: 0,
+            },
+          ],
+        });
+      }
+    }
+  } else {
+    // No mock data — render with empty object for default variation
+    try {
+      const html = await renderTemplate(component.paths.tpl.full, {});
+      const report = await validator.validateString(html);
+      const messages = report.results.flatMap((r) =>
+        r.messages.map((msg) => ({
+          severity: msg.severity,
+          message: msg.message,
+          ruleId: msg.ruleId,
+          line: msg.line,
+          column: msg.column,
+        })),
+      );
+
+      variations.push({
+        name: "default",
+        valid: report.valid,
+        messages,
+      });
+    } catch (error) {
+      variations.push({
+        name: "default",
+        valid: false,
+        messages: [
+          {
+            severity: 2,
+            message: `Render error: ${error.message || error}`,
+            ruleId: "render-error",
+            line: 0,
+            column: 0,
+          },
+        ],
+      });
+    }
+  }
+
+  return {
+    component: component.paths.dir.short,
+    variations,
+  };
+}
+
+/**
+ * Parse component and variation name from a build output filename.
+ * Expected pattern: component-<path>-variation-<name>.html
+ * @param {string} filePath
+ * @returns {{ component: string, variation: string }}
+ */
+function parseFileName(filePath) {
+  const basename = path.basename(filePath, ".html");
+
+  const variationMatch = basename.match(/^component-(.+)-variation-(.+)$/);
+  if (variationMatch) {
+    const componentPart = variationMatch[1].replace(/-/g, "/");
+    return {
+      component: componentPart,
+      variation: variationMatch[2],
+    };
+  }
+
+  // Fallback: use full basename as component name
+  return {
+    component: basename,
+    variation: "default",
+  };
+}
+
+/**
+ * Validate pre-existing HTML files matching a glob pattern.
+ * Files are validated as full HTML documents.
+ * @param {string} globPattern
+ * @param {object} [options]
+ * @param {object} [options.htmlValidateConfig]
+ * @returns {Promise<{components: Array<object>, summary: object}>}
+ */
+export async function validateHtmlFiles(globPattern, options = {}) {
+  const baseConfig =
+    options.htmlValidateConfig ?? global.config?.htmlValidation?.htmlValidateConfig;
+
+  // For file mode, use full-document validation (don't disable doctype rules)
+  const fileConfig = {
+    ...baseConfig,
+    rules: {
+      ...(baseConfig?.rules ?? {}),
+      "doctype-style": undefined,
+      "missing-doctype": undefined,
+    },
+  };
+
+  // Remove undefined keys so they fall back to the preset defaults
+  for (const [key, value] of Object.entries(fileConfig.rules)) {
+    if (value === undefined) {
+      delete fileConfig.rules[key];
+    }
+  }
+
+  const validator = createValidator(fileConfig);
+
+  log(
+    "info",
+    t("htmlValidation.files.start").replace("{{pattern}}", globPattern),
+  );
+
+  const files = globSync(globPattern);
+
+  if (files.length === 0) {
+    log(
+      "warn",
+      t("htmlValidation.files.noFilesFound").replace(
+        "{{pattern}}",
+        globPattern,
+      ),
+    );
+    return { components: [], summary: buildSummary([]) };
+  }
+
+  // Group files by component
+  const componentMap = new Map();
+
+  for (const filePath of files) {
+    const { component, variation } = parseFileName(filePath);
+    if (!componentMap.has(component)) {
+      componentMap.set(component, []);
+    }
+    componentMap.get(component).push({ filePath, variation });
+  }
+
+  const componentResults = [];
+
+  for (const [componentName, fileEntries] of componentMap) {
+    const variations = [];
+
+    for (const { filePath, variation } of fileEntries) {
+      try {
+        const html = await readFile(filePath, "utf-8");
+        const report = await validator.validateString(html);
+        const messages = report.results.flatMap((r) =>
+          r.messages.map((msg) => ({
+            severity: msg.severity,
+            message: msg.message,
+            ruleId: msg.ruleId,
+            line: msg.line,
+            column: msg.column,
+          })),
+        );
+
+        variations.push({
+          name: variation,
+          valid: report.valid,
+          messages,
+        });
+      } catch (error) {
+        variations.push({
+          name: variation,
+          valid: false,
+          messages: [
+            {
+              severity: 2,
+              message: `File read error: ${error.message || error}`,
+              ruleId: "file-error",
+              line: 0,
+              column: 0,
+            },
+          ],
+        });
+      }
+    }
+
+    componentResults.push({
+      component: componentName,
+      variations,
+    });
+  }
+
+  const summary = buildSummary(componentResults);
+
+  if (summary.failed === 0) {
+    log("success", t("htmlValidation.all.valid"));
+  } else {
+    const msg =
+      summary.failed === 1
+        ? t("htmlValidation.all.invalid.one")
+        : t("htmlValidation.all.invalid.other").replace(
+            "{{amount}}",
+            summary.failed,
+          );
+    log("error", msg);
+  }
+
+  return { components: componentResults, summary };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schalkneethling/miyagi-core",
-  "version": "4.4.4",
+  "version": "4.5.1",
   "description": "miyagi is a component development tool for JavaScript template engines.",
   "main": "index.js",
   "author": "Schalk Neethling <schalkneethling@duck.com>, Michael Großklaus <mail@mgrossklaus.de> (https://www.mgrossklaus.de)",
@@ -43,6 +43,7 @@
     "deepmerge": "^4.3.1",
     "directory-tree": "^3.5.2",
     "express": "^5.1.0",
+    "html-validate": "^10.11.2",
     "js-yaml": "^4.1.0",
     "marked": "^17.0.2",
     "twing": "7.3.1",