@duckmind/dm-linux-x64 0.63.9 → 0.64.2

package/extensions/dm-lens/clients/dispatch/runners/helm-render.js

@@ -0,0 +1,601 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { logLatency } from "../../latency-logger.js";
+import { PathKeyedMap } from "../../path-keyed-map.js";
+import { normalizeMapKey } from "../../path-utils.js";
+import { loadDmLensProjectConfig } from "../../project-lens-config.js";
+import {
+  getProjectTrustState,
+  projectTrustDenialReason
+} from "../../project-trust.js";
+import { safeSpawnAsync } from "../../safe-spawn.js";
+import {
+  killedForOutputCap,
+  truncatedByOutputCap
+} from "../../spawn-output-cap.js";
+import { isTrivyEnabled, resolveSeverityFloor } from "../../trivy-client.js";
+import { findNearestDirWithMarker } from "../../workspace-topology.js";
+import { PRIORITY } from "../priorities.js";
+import { describeUnavailability } from "./utils/availability-policy.js";
+import {
+  createAvailabilityChecker,
+  resolveAvailableOrInstall
+} from "./utils/runner-helpers.js";
+const helm = createAvailabilityChecker("helm", ".exe");
+const trivy = createAvailabilityChecker("trivy", ".exe");
+const inFlightByChartRoot = new PathKeyedMap(normalizeMapKey);
+const RENDER_TIMEOUT_MS = 30000;
+const TRIVY_TIMEOUT_MS = 45000;
+const MAX_RENDERED_FILES = 400;
+const MAX_REPORT_BYTES = 8 * 1024 * 1024;
+const MAX_RENDER_OUTPUT_BYTES = 8 * 1024 * 1024;
+const SKIPPED = {
+  status: "skipped",
+  diagnostics: [],
+  semantic: "none"
+};
+function isWithin(root, candidate) {
+  const relative = path.relative(normalizeMapKey(root), normalizeMapKey(candidate));
+  return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+export function isHelmRenderEnabled(workspaceRoot) {
+  try {
+    const config = loadDmLensProjectConfig(workspaceRoot);
+    const helmConfig = config.raw?.helm;
+    return helmConfig?.renderValidation?.enabled === true;
+  } catch {
+    return false;
+  }
+}
+export function resolveTemplateSource(sourceRef, chartRoot, realChartRoot) {
+  const segments = sourceRef.split(/[\\/]+/).filter((segment) => segment && segment !== ".");
+  if (segments.length < 2)
+    return null;
+  const candidate = path.resolve(chartRoot, ...segments.slice(1));
+  if (!isWithin(chartRoot, candidate))
+    return null;
+  try {
+    if (!fs.lstatSync(candidate).isFile())
+      return null;
+    const root = realChartRoot ?? fs.realpathSync(chartRoot);
+    if (!isWithin(root, fs.realpathSync(candidate)))
+      return null;
+  } catch {
+    return null;
+  }
+  return candidate;
+}
+function canonicalChartRoot(chartRoot) {
+  try {
+    return fs.realpathSync(chartRoot);
+  } catch {
+    return chartRoot;
+  }
+}
+function chartYaml(chartRoot) {
+  return path.join(chartRoot, "Chart.yaml");
+}
+const HELM_INSTALL_HINT = "https://helm.sh/docs/intro/install/";
+const TRIVY_INSTALL_HINT = "https://trivy.dev/latest/getting-started/installation/";
+const SOURCE_ANNOTATION = /^#\s*Source:\s*(\S+)\s*$/m;
+const TEMPLATE_EXTENSION = /\.(?:ya?ml|tpl)$/i;
+export function extractTemplateRef(line) {
+  for (const token of line.split(/[\s(),<>"']+/)) {
+    const parts = token.split(":");
+    const ref = parts[0];
+    if (!ref.includes("/"))
+      continue;
+    if (!TEMPLATE_EXTENSION.test(ref))
+      continue;
+    const lineNumber = /^\d+$/.test(parts[1] ?? "") ? Number(parts[1]) : undefined;
+    return { ref, line: lineNumber };
+  }
+  return null;
+}
+export function mapRenderedToSource(options) {
+  const { chartRoot, realChartRoot } = options;
+  const annotation = SOURCE_ANNOTATION.exec(options.renderedContent);
+  if (annotation) {
+    const resolved = resolveTemplateSource(annotation[1], chartRoot, realChartRoot);
+    if (resolved)
+      return { filePath: resolved, mapped: true };
+  }
+  const relative = path.relative(options.outputDir, options.renderedPath);
+  if (relative && !relative.startsWith("..")) {
+    const resolved = resolveTemplateSource(relative, chartRoot, realChartRoot);
+    if (resolved)
+      return { filePath: resolved, mapped: true };
+  }
+  return { filePath: chartYaml(chartRoot), mapped: false };
+}
+export function parseHelmTemplateFailure(raw, chartRoot) {
+  const diagnostics = [];
+  const text = raw.trim();
+  const realRoot = canonicalChartRoot(chartRoot);
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("Error:"))
+      continue;
+    const location = extractTemplateRef(trimmed);
+    const resolved = location ? resolveTemplateSource(location.ref, chartRoot, realRoot) : null;
+    const chartName = path.basename(chartRoot);
+    diagnostics.push({
+      id: `helm-render-error-${diagnostics.length + 1}`,
+      message: resolved ? trimmed : `${trimmed} (helm template failed for chart ${chartName})`,
+      filePath: resolved ?? chartYaml(chartRoot),
+      line: resolved ? location?.line ?? 1 : 1,
+      column: 1,
+      severity: "error",
+      semantic: "blocking",
+      tool: "helm-render",
+      rule: "render-failed",
+      fixable: false
+    });
+  }
+  if (diagnostics.length === 0) {
+    diagnostics.push({
+      id: "helm-render-error-1",
+      message: `helm template failed: ${(text || "no output").slice(0, 400)}`,
+      filePath: chartYaml(chartRoot),
+      line: 1,
+      column: 1,
+      severity: "error",
+      semantic: "blocking",
+      tool: "helm-render",
+      rule: "render-failed",
+      fixable: false
+    });
+  }
+  return diagnostics;
+}
+export function checkManifestShape(options) {
+  const diagnostics = [];
+  const documents = options.renderedContent.split(/^---\s*$/m);
+  documents.forEach((document, index) => {
+    const meaningful = document.split(/\r?\n/).filter((line) => line.trim() && !line.trim().startsWith("#"));
+    if (meaningful.length === 0)
+      return;
+    const missing = [];
+    if (!/^apiVersion:\s*\S/m.test(document))
+      missing.push("apiVersion");
+    if (!/^kind:\s*\S/m.test(document))
+      missing.push("kind");
+    if (missing.length === 0)
+      return;
+    const where = options.sourceMapped ? `rendered ${options.renderedRelativePath}` : `rendered ${options.renderedRelativePath} (source template could not be resolved)`;
+    diagnostics.push({
+      id: `helm-render-shape-${options.renderedRelativePath}-${index}`,
+      message: `Rendered document ${index + 1} is missing ${missing.join(" and ")} — it is not a Kubernetes object (${where}).`,
+      filePath: options.sourcePath,
+      line: 1,
+      column: 1,
+      severity: "warning",
+      semantic: "warning",
+      tool: "helm-render",
+      rule: "manifest-shape",
+      fixable: false
+    });
+  });
+  return diagnostics;
+}
+export function parseRenderedTrivyOutput(raw, locate) {
+  if (!raw.trim()) {
+    return { understood: false, diagnostics: [], problem: "empty report" };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {
+      understood: false,
+      diagnostics: [],
+      problem: "report was not valid JSON"
+    };
+  }
+  const results = parsed?.Results;
+  if (!Array.isArray(results)) {
+    return {
+      understood: false,
+      diagnostics: [],
+      problem: "report carried no Results array"
+    };
+  }
+  const diagnostics = [];
+  for (const entry of results) {
+    if (!entry || typeof entry !== "object")
+      continue;
+    const target = entry.Target;
+    const rows = entry.Misconfigurations;
+    if (!Array.isArray(rows))
+      continue;
+    const located = locate(typeof target === "string" ? target : "");
+    for (const row of rows) {
+      if (!row || typeof row !== "object")
+        continue;
+      const misconfig = row;
+      const id = typeof misconfig.ID === "string" ? misconfig.ID : undefined;
+      if (!id)
+        continue;
+      const cause = misconfig.CauseMetadata ?? {};
+      const renderedLine = typeof cause.StartLine === "number" && cause.StartLine > 0 ? cause.StartLine : undefined;
+      const severity = typeof misconfig.Severity === "string" ? misconfig.Severity.toUpperCase() : "UNKNOWN";
+      const title = typeof misconfig.Title === "string" && misconfig.Title ? misconfig.Title : id;
+      const resolution = typeof misconfig.Resolution === "string" && misconfig.Resolution ? ` ${misconfig.Resolution}` : "";
+      const at = renderedLine ? `${located.detail}:${renderedLine}` : located.detail;
+      diagnostics.push({
+        id: `helm-render-${id}-${diagnostics.length + 1}`,
+        message: `[${id}] ${title} (${severity}) in ${at}.${resolution}`.trim(),
+        filePath: located.filePath,
+        line: 1,
+        column: 1,
+        severity: severity === "CRITICAL" ? "error" : "warning",
+        semantic: severity === "CRITICAL" ? "blocking" : "warning",
+        defectClass: "safety",
+        tool: "helm-render",
+        rule: id,
+        fixable: false
+      });
+    }
+  }
+  return { understood: true, diagnostics };
+}
+function helmUnavailableResult(cwd) {
+  const verdict = helm.getVerdict(cwd);
+  return {
+    status: "failed",
+    diagnostics: [],
+    semantic: "warning",
+    failureKind: "unavailable",
+    failureMessage: describeUnavailability({
+      tool: "helm",
+      installHint: HELM_INSTALL_HINT,
+      outcome: verdict.outcome,
+      cause: verdict.cause,
+      elapsedMs: verdict.elapsedMs,
+      retryAfterMs: verdict.retryAtMs ? Math.max(0, verdict.retryAtMs - Date.now()) : undefined
+    }).slice(0, 300)
+  };
+}
+function failedResult(kind, message) {
+  return {
+    status: "failed",
+    diagnostics: [],
+    semantic: "warning",
+    failureKind: kind,
+    failureMessage: message.slice(0, 200)
+  };
+}
+const OUR_RENDER_FLAGS = ["--output-dir"];
+export function rejectedOurInvocation(output) {
+  if (!output)
+    return null;
+  const complaint = /unknown flag|unknown shorthand flag|flag provided but not defined|unknown command|unrecognized (?:flag|option)/i.test(output);
+  if (!complaint)
+    return null;
+  for (const flag of OUR_RENDER_FLAGS) {
+    if (output.includes(flag))
+      return flag;
+  }
+  return null;
+}
+function spawnFailureKind(result) {
+  const typed = result.spawnFailure?.kind;
+  if (typed === "tool-not-found")
+    return "unavailable";
+  if (typed === "timeout" || result.failure === "timeout")
+    return "timeout";
+  if (typed === "killed" || result.failure === "aborted")
+    return "aborted";
+  if (result.failure)
+    return "server_error";
+  return null;
+}
+function collectRenderedFiles(root) {
+  const files = [];
+  const stack = [root];
+  let truncated = false;
+  while (stack.length > 0 && !truncated) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && /\.ya?ml$/i.test(entry.name)) {
+        if (files.length >= MAX_RENDERED_FILES) {
+          truncated = true;
+          break;
+        }
+        files.push(full);
+      }
+    }
+  }
+  return {
+    files: files.sort((left, right) => left.localeCompare(right)),
+    truncated
+  };
+}
+function summarize(diagnostics) {
+  let semantic = "none";
+  if (diagnostics.some((item) => item.severity === "error")) {
+    semantic = "blocking";
+  } else if (diagnostics.length > 0) {
+    semantic = "warning";
+  }
+  return { status: "succeeded", diagnostics, semantic };
+}
+function readRenderedTree(outputDir, chartRoot) {
+  const manifests = [];
+  const walk = collectRenderedFiles(outputDir);
+  const realChartRoot = canonicalChartRoot(chartRoot);
+  let unreadable = 0;
+  for (const renderedPath of walk.files) {
+    let content;
+    try {
+      content = fs.readFileSync(renderedPath, "utf-8");
+    } catch {
+      unreadable += 1;
+      continue;
+    }
+    const mapping = mapRenderedToSource({
+      renderedContent: content,
+      renderedPath,
+      outputDir,
+      chartRoot,
+      realChartRoot
+    });
+    manifests.push({
+      renderedPath,
+      relativePath: path.relative(outputDir, renderedPath),
+      content,
+      sourcePath: mapping.filePath,
+      sourceMapped: mapping.mapped
+    });
+  }
+  return { manifests, truncated: walk.truncated, unreadable };
+}
+function coverageGap(chartRoot, rule, message) {
+  return {
+    id: `helm-render-${rule}`,
+    message,
+    filePath: chartYaml(chartRoot),
+    line: 1,
+    column: 1,
+    severity: "info",
+    semantic: "warning",
+    tool: "helm-render",
+    rule,
+    fixable: false
+  };
+}
+export async function runIacPass(options) {
+  const { chartRoot, cwd, outputDir } = options;
+  const trivyCmd = await resolveAvailableOrInstall(trivy, "trivy", cwd);
+  if (!trivyCmd) {
+    const verdict = trivy.getVerdict(cwd);
+    return [
+      coverageGap(chartRoot, "iac-pass-unavailable", `Rendered-manifest IaC checks did not run: ${describeUnavailability({
+        tool: "trivy",
+        installHint: TRIVY_INSTALL_HINT,
+        outcome: verdict.outcome,
+        cause: verdict.cause,
+        elapsedMs: verdict.elapsedMs
+      })}`)
+    ];
+  }
+  const scan = await safeSpawnAsync(trivyCmd, [
+    "config",
+    "--quiet",
+    "--format",
+    "json",
+    "--severity",
+    resolveSeverityFloor(cwd).join(","),
+    outputDir
+  ], {
+    cwd,
+    timeout: TRIVY_TIMEOUT_MS,
+    deadlineAt: Date.now() + TRIVY_TIMEOUT_MS,
+    resourceLabel: "helm-render-trivy",
+    maxOutputBytes: MAX_REPORT_BYTES
+  });
+  if (truncatedByOutputCap(scan)) {
+    return [
+      coverageGap(chartRoot, "iac-report-unreadable", `Rendered-manifest IaC checks did not run: the trivy report exceeded ${MAX_REPORT_BYTES} bytes and was truncated before parsing.`)
+    ];
+  }
+  const scanFailure = spawnFailureKind(scan);
+  if (scanFailure || scan.status !== 0) {
+    const why = scanFailure ?? `exit ${scan.status}`;
+    const detail = (scan.stderr || scan.error?.message || "no output").slice(0, 200);
+    return [
+      coverageGap(chartRoot, "iac-pass-failed", `Rendered-manifest IaC checks failed to complete (${why}): ${detail}`)
+    ];
+  }
+  const sourceByRendered = new PathKeyedMap(normalizeMapKey);
+  for (const manifest of options.manifests) {
+    sourceByRendered.set(manifest.renderedPath, {
+      filePath: manifest.sourcePath,
+      detail: manifest.relativePath
+    });
+  }
+  const report = parseRenderedTrivyOutput(scan.stdout || "", (target) => {
+    const hit = sourceByRendered.get(path.resolve(outputDir, target));
+    return hit ?? {
+      filePath: chartYaml(chartRoot),
+      detail: target || "rendered manifest"
+    };
+  });
+  if (!report.understood) {
+    return [
+      coverageGap(chartRoot, "iac-report-unreadable", `Rendered-manifest IaC checks produced no readable result (${report.problem}), so the manifests are UNSCANNED rather than clean.`)
+    ];
+  }
+  return report.diagnostics;
+}
+function logRenderPass(filePath, chartRoot, startedAt, metadata) {
+  logLatency({
+    type: "phase",
+    phase: "helm_render_pass",
+    filePath,
+    durationMs: Date.now() - startedAt,
+    metadata: { chartRoot, ...metadata }
+  });
+}
+export function discardScratchDir(outputDir, filePath, remove = (target) => fs.rmSync(target, { recursive: true, force: true })) {
+  try {
+    remove(outputDir);
+  } catch (error) {
+    logLatency({
+      type: "phase",
+      phase: "helm_render_scratch_leak",
+      filePath,
+      durationMs: 0,
+      metadata: {
+        outputDir,
+        error: error instanceof Error ? error.message : String(error)
+      }
+    });
+  }
+}
+async function renderAndValidate(chartRoot, cwd, filePath) {
+  const startedAt = Date.now();
+  const helmCmd = await resolveAvailableOrInstall(helm, "helm", cwd);
+  if (!helmCmd)
+    return helmUnavailableResult(cwd);
+  const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), "dm-lens-helm-render-"));
+  try {
+    const render = await safeSpawnAsync(helmCmd, ["template", "dm-lens-render", chartRoot, "--output-dir", outputDir], {
+      cwd,
+      timeout: RENDER_TIMEOUT_MS,
+      deadlineAt: Date.now() + RENDER_TIMEOUT_MS,
+      resourceLabel: "helm-render",
+      maxOutputBytes: MAX_RENDER_OUTPUT_BYTES
+    });
+    const renderOutput = [render.stdout, render.stderr].filter(Boolean).join(`
+`);
+    const renderCapped = truncatedByOutputCap(render);
+    if (killedForOutputCap(render)) {
+      logRenderPass(filePath, chartRoot, startedAt, {
+        outcome: "render-truncated",
+        diagnostics: 1
+      });
+      return summarize([
+        coverageGap(chartRoot, "render-truncated", `helm template produced more than ${MAX_RENDER_OUTPUT_BYTES} bytes and was stopped mid-render, so the rendered manifests are UNCHECKED rather than clean.`)
+      ]);
+    }
+    const startupFailure = spawnFailureKind(render);
+    if (startupFailure) {
+      logRenderPass(filePath, chartRoot, startedAt, {
+        outcome: "runner-failed",
+        failureKind: startupFailure
+      });
+      return failedResult(startupFailure, render.error?.message || `helm template ${startupFailure}`);
+    }
+    if (render.status !== 0) {
+      const ourFlag = rejectedOurInvocation(renderOutput);
+      if (ourFlag) {
+        logRenderPass(filePath, chartRoot, startedAt, {
+          outcome: "runner-failed",
+          failureKind: "invocation_rejected",
+          flag: ourFlag
+        });
+        return failedResult("invocation_rejected", `helm rejected dm-lens's own invocation (${ourFlag}); this is a helm/dm-lens compatibility problem, not a chart defect: ${renderOutput.trim().slice(0, 160)}`);
+      }
+      const diagnostics = parseHelmTemplateFailure(renderOutput, chartRoot);
+      if (renderCapped) {
+        diagnostics.push(coverageGap(chartRoot, "render-truncated", "helm template output was truncated, so this failure report may be incomplete."));
+      }
+      logRenderPass(filePath, chartRoot, startedAt, {
+        outcome: "render-failed",
+        diagnostics: diagnostics.length
+      });
+      return summarize(diagnostics);
+    }
+    const tree = readRenderedTree(outputDir, chartRoot);
+    const diagnostics = [];
+    for (const manifest of tree.manifests) {
+      diagnostics.push(...checkManifestShape({
+        renderedContent: manifest.content,
+        renderedRelativePath: manifest.relativePath,
+        sourcePath: manifest.sourcePath,
+        sourceMapped: manifest.sourceMapped
+      }));
+    }
+    if (renderCapped) {
+      diagnostics.push(coverageGap(chartRoot, "render-output-truncated", `helm template printed more than ${MAX_RENDER_OUTPUT_BYTES} bytes and its stdout was truncated. The rendered manifests were still validated from disk; only helm's own progress output was lost.`));
+    }
+    if (tree.truncated) {
+      diagnostics.push(coverageGap(chartRoot, "render-truncated", `This chart rendered more than ${MAX_RENDERED_FILES} manifests; only the first ${MAX_RENDERED_FILES} were validated, so the rest are UNCHECKED rather than clean.`));
+    }
+    if (tree.unreadable > 0) {
+      diagnostics.push(coverageGap(chartRoot, "rendered-file-unreadable", `${tree.unreadable} rendered manifest(s) could not be read back from the scratch directory and are UNCHECKED rather than clean.`));
+    }
+    if (tree.manifests.length === 0) {
+      diagnostics.push(coverageGap(chartRoot, "render-empty", "helm template succeeded but produced no manifests to validate, so this chart is UNVALIDATED rather than clean. Check whether the chart's values disable every template."));
+    }
+    const iacRequested = isTrivyEnabled(cwd);
+    if (iacRequested) {
+      diagnostics.push(...await runIacPass({
+        chartRoot,
+        cwd,
+        outputDir,
+        manifests: tree.manifests
+      }));
+    }
+    logRenderPass(filePath, chartRoot, startedAt, {
+      outcome: "rendered",
+      manifests: tree.manifests.length,
+      truncated: tree.truncated,
+      unreadable: tree.unreadable,
+      iacRequested,
+      diagnostics: diagnostics.length
+    });
+    return summarize(diagnostics);
+  } finally {
+    discardScratchDir(outputDir, filePath);
+  }
+}
+const helmRenderRunner = {
+  id: "helm-render",
+  appliesTo: ["yaml", "helm-template"],
+  priority: PRIORITY.GENERAL_ANALYSIS,
+  skipTestFiles: false,
+  timeoutMs: RENDER_TIMEOUT_MS + TRIVY_TIMEOUT_MS + 1e4,
+  async run(ctx) {
+    const cwd = ctx.cwd || process.cwd();
+    const workspaceRoot = path.resolve(ctx.projectRoot ?? cwd);
+    if (!isHelmRenderEnabled(workspaceRoot))
+      return SKIPPED;
+    const startDir = path.dirname(path.resolve(ctx.filePath));
+    const discovered = findNearestDirWithMarker(startDir, "chartYamlPath");
+    if (!discovered)
+      return SKIPPED;
+    const chartRoot = path.resolve(discovered);
+    if (!isWithin(workspaceRoot, chartRoot))
+      return SKIPPED;
+    if (getProjectTrustState() === "untrusted") {
+      logRenderPass(ctx.filePath, chartRoot, Date.now(), {
+        outcome: "refused-untrusted"
+      });
+      return summarize([
+        coverageGap(chartRoot, "render-untrusted", `Helm rendered-manifest validation did not run: ${projectTrustDenialReason() ?? "project trust denied"}. Rendering executes this chart's own templates, so it needs host trust in addition to the \`helm.renderValidation.enabled\` switch — and that switch is a tracked file a cloned repository can set for itself.`)
+      ]);
+    }
+    const existing = inFlightByChartRoot.get(chartRoot);
+    if (existing)
+      return existing;
+    const promise = renderAndValidate(chartRoot, cwd, ctx.filePath).finally(() => {
+      if (inFlightByChartRoot.get(chartRoot) === promise)
+        inFlightByChartRoot.delete(chartRoot);
+    });
+    inFlightByChartRoot.set(chartRoot, promise);
+    return promise;
+  }
+};
+export default helmRenderRunner;

package/extensions/dm-lens/clients/dispatch/runners/htmlhint.js

@@ -0,0 +1,97 @@
+import * as path from "node:path";
+import { safeSpawnAsync } from "../../safe-spawn.js";
+import { getLinterPolicyForCwd } from "../../tool-policy.js";
+import { PRIORITY } from "../priorities.js";
+import {
+  createAvailabilityChecker,
+  resolveToolCommandWithInstallFallback
+} from "./utils/runner-helpers.js";
+import { parseToolRun } from "./utils/tool-failure.js";
+import { finishParsedRun } from "./utils/tool-failure.js";
+const htmlhint = createAvailabilityChecker("htmlhint");
+const HTMLHINT_RULES = {
+  "tag-pair": true,
+  "attr-no-duplication": true,
+  "tagname-lowercase": true,
+  "doctype-first": false,
+  "spec-char-escape": true,
+  "id-unique": true
+};
+function parseHtmlhintOutput(raw, filePath) {
+  const diagnostics = [];
+  const lineRe = /^.+?:(\d+):(\d+): (.+?) \[(error|warning)\/([^\]]+)\]/;
+  for (const line of raw.split(`
+`)) {
+    const match = line.match(lineRe);
+    if (!match)
+      continue;
+    const lineNum = parseInt(match[1], 10);
+    const col = parseInt(match[2], 10);
+    const message = match[3].trim();
+    const level = match[4];
+    const rule = match[5].trim();
+    const severity = level === "error" ? "error" : "warning";
+    diagnostics.push({
+      id: `htmlhint-${rule}-${lineNum}`,
+      message,
+      filePath,
+      line: lineNum,
+      column: col,
+      severity,
+      semantic: severity === "error" ? "blocking" : "warning",
+      tool: "htmlhint",
+      rule,
+      fixable: false
+    });
+  }
+  return diagnostics;
+}
+const htmlhintRunner = {
+  id: "htmlhint",
+  appliesTo: ["html"],
+  priority: PRIORITY.GENERAL_ANALYSIS,
+  skipTestFiles: false,
+  async run(ctx) {
+    const cwd = ctx.cwd || process.cwd();
+    const policy = getLinterPolicyForCwd(ctx.filePath, cwd);
+    if (policy && !policy.preferredRunners.includes("htmlhint")) {
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    let cmd = null;
+    if (await htmlhint.isAvailableAsync(cwd)) {
+      cmd = htmlhint.getCommand(cwd);
+    } else {
+      cmd = await resolveToolCommandWithInstallFallback(cwd, "htmlhint");
+    }
+    if (!cmd) {
+      return { status: "skipped", diagnostics: [], semantic: "none" };
+    }
+    const rulesArg = Object.entries(HTMLHINT_RULES).flatMap(([rule, enabled]) => enabled === true ? [rule] : []).join(",");
+    const result = await safeSpawnAsync(cmd, [
+      "--rules",
+      rulesArg,
+      "--format",
+      "unix",
+      path.resolve(cwd, ctx.filePath)
+    ], { cwd });
+    const output = result.stdout || result.stderr || "";
+    const run = parseToolRun("htmlhint", { result, output }, (out) => parseHtmlhintOutput(out, ctx.filePath));
+    if (run.skipped)
+      return run.skipped;
+    const diagnostics = run.diagnostics;
+    return finishParsedRun({
+      tool: "htmlhint",
+      ctx,
+      result,
+      diagnostics,
+      classify: (diagnostics) => {
+        const hasErrors = diagnostics.some((d) => d.severity === "error");
+        return {
+          status: "failed",
+          semantic: hasErrors ? "blocking" : "warning"
+        };
+      }
+    });
+  }
+};
+export default htmlhintRunner;