pageship 0.3.0 → 0.4.1

package/dist/skills/pageship-docs/references/html-validate-rules.mjs

@@ -0,0 +1,326 @@
+// Pageship's html-validate rules, loaded by html-validate.json beside this file.
+// Run: npx --yes html-validate@11.17.0 --config <this folder>/html-validate.json <file>
+
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// `npx` installs html-validate where this file can't import it by name, so take its rule class
+// from the copy that is running, found through the command's path.
+async function loadHtmlValidate() {
+  const command = process.argv[1] ? realpathSync(process.argv[1]) : "";
+  if (/[/\\]html-validate[/\\]bin[/\\]html-validate\.m?js$/u.test(command)) {
+    return import(pathToFileURL(join(dirname(command), "../dist/esm/index.js")).href);
+  }
+  return import("html-validate");
+}
+
+const { Rule } = await loadHtmlValidate();
+
+const fileRules = new URL("./file.md", import.meta.url);
+
+/** The script and stylesheet tags the file rules give, with their exact attributes. */
+const trustedTags = [
+  ...readFileSync(fileRules, "utf8").matchAll(/^```html\n([\s\S]*?)^```/gmu),
+].flatMap(([, block]) =>
+  [...block.matchAll(/<(script|link)\b([^>]*)>/gu)].map(([, name, attributes]) => {
+    const values = new Map(
+      [...attributes.matchAll(/([\w-]+)="([^"]*)"/gu)].map(([, key, value]) => [key, value]),
+    );
+    return {
+      url: values.get(name === "script" ? "src" : "href"),
+      integrity: values.get("integrity"),
+      crossorigin: values.get("crossorigin"),
+    };
+  }),
+);
+
+const hasScheme = /^[a-z][a-z\d+.-]*:/iu;
+
+/** Hosted font CSS differs by browser, so it can't carry `integrity`. */
+const hostedFonts = /^https:\/\/fonts\.googleapis\.com\/css2?\?/u;
+
+const attributeValue = (element, name) => {
+  const value = element.getAttributeValue(name);
+  return typeof value === "string" ? value : null;
+};
+
+const linkTypes = (element) =>
+  (attributeValue(element, "rel") ?? "").toLowerCase().split(/\s+/u).filter(Boolean);
+
+/** The location of `text.slice(begin, end)`, for `text` that starts at `location`. */
+function locate(location, text, begin, end) {
+  const before = text.slice(0, begin);
+  const newline = before.lastIndexOf("\n");
+  return {
+    filename: location.filename,
+    offset: location.offset + begin,
+    line: location.line + before.split("\n").length - 1,
+    column: newline === -1 ? location.column + begin : begin - newline,
+    size: end - begin,
+  };
+}
+
+/** Spaces in place of each match, so offsets into the text stay the same. */
+const blank = (text, pattern) => text.replace(pattern, (match) => " ".repeat(match.length));
+const cssComments = /\/\*[\s\S]*?\*\//gu;
+const cssStrings = /"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/gu;
+
+/**
+ * The markup inside each `<svg>`, which html-validate leaves unparsed, and the location in the
+ * file of an offset into that markup.
+ */
+function* svgContents(document, source) {
+  // Blanking comments keeps commented-out markup from counting.
+  const data = blank(source.data, /<!--[\s\S]*?-->/gu);
+  for (const element of document.querySelectorAll("svg")) {
+    // An svg tag, read past any ">" inside its quoted attribute values.
+    const tags = /<(\/?)svg\b(?:[^>"']|"[^"]*"|'[^']*')*?(\/?)>/giu;
+    tags.lastIndex = Math.max(0, element.location.offset - source.offset - 1);
+    const opening = tags.exec(data);
+    if (!opening) continue;
+    const start = opening.index + opening[0].length;
+    // The svg's own closing tag, past any svg nested inside it.
+    let depth = 1;
+    let end = -1;
+    for (let tag = tags.exec(data); tag; tag = tags.exec(data)) {
+      // A self-closing <svg/> opens nothing.
+      if (tag[2]) continue;
+      depth += tag[1] ? -1 : 1;
+      if (depth === 0) {
+        end = tag.index;
+        break;
+      }
+    }
+    if (end === -1) continue;
+    const at = (begin, length) =>
+      locate(source, source.data, start + begin, start + begin + length);
+    yield { element, markup: data.slice(start, end), at };
+  }
+}
+
+/** The CSS of every `<style>` element and `style` attribute, SVG's included, with where it starts. */
+function* stylesheets(document, source) {
+  for (const element of document.querySelectorAll("style")) {
+    const text = element.childNodes[0];
+    if (text) yield { element, css: element.textContent, location: text.location };
+  }
+  for (const element of document.querySelectorAll("[style]")) {
+    const attribute = element.getAttribute("style");
+    if (typeof attribute?.value === "string") {
+      yield { element, css: attribute.value, location: attribute.valueLocation };
+    }
+  }
+  for (const { element, markup, at } of svgContents(document, source)) {
+    const css = /<style\b[^>]*>([\s\S]*?)<\/style\s*>|\sstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/giu;
+    for (const match of markup.matchAll(css)) {
+      const text = match[1] ?? match[2] ?? match[3];
+      const begin = match.index + match[0].indexOf(text, match[0].indexOf(match[1] ? ">" : "="));
+      yield { element, css: text, location: at(begin, text.length) };
+    }
+  }
+}
+
+class TrustedLibraries extends Rule {
+  documentation() {
+    return {
+      description:
+        "Load scripts and stylesheets only with a tag copied from the file rules (references/file.md): the same URL, `integrity` and `crossorigin`. A hosted Google Fonts stylesheet needs no `integrity`.",
+    };
+  }
+
+  setup() {
+    this.on("dom:ready", ({ document, source }) => {
+      for (const element of document.querySelectorAll("script[src]")) {
+        this.check(element, attributeValue(element, "src"));
+      }
+      for (const element of document.querySelectorAll("link")) {
+        const types = linkTypes(element);
+        const preloads = (attributeValue(element, "as") ?? "").toLowerCase();
+        const stylesheet =
+          types.includes("stylesheet") || (types.includes("preload") && preloads === "style");
+        const script =
+          types.includes("modulepreload") || (types.includes("preload") && preloads === "script");
+        if (stylesheet || script) {
+          this.check(element, attributeValue(element, "href"), { stylesheet });
+        }
+      }
+      for (const { element, css, location } of stylesheets(document, source)) {
+        const code = blank(css, cssComments);
+        for (const match of code.matchAll(/@import\s+(?:url\(\s*)?["']?([^"')\s;]+)/giu)) {
+          const url = match[1];
+          // A path beside the file is pageship/no-relative-paths' problem.
+          if (hostedFonts.test(url) || !hasScheme.test(url)) continue;
+          this.report(
+            element,
+            `The @import of ${url} is not a stylesheet the file rules give: load only the tags they give`,
+            locate(location, css, match.index, match.index + match[0].length),
+          );
+        }
+      }
+      for (const element of document.querySelectorAll("script")) {
+        if (element.hasAttribute("src")) continue;
+        const imported = /\bimport\b[^;]*?["'](https?:\/\/[^"']+)/u.exec(element.textContent)?.[1];
+        if (imported) {
+          this.report(
+            element,
+            `The module import of ${imported} can't be checked by integrity: load the library with a <script src> tag from the file rules`,
+          );
+        }
+      }
+    });
+  }
+
+  check(element, url, { stylesheet = false } = {}) {
+    if (url === null || (stylesheet && hostedFonts.test(url))) return;
+    const trusted = trustedTags.find((tag) => tag.url === url);
+    if (!trusted) {
+      this.report(element, `${url} is not a tag in the file rules: load only the tags they give`);
+      return;
+    }
+    for (const name of ["integrity", "crossorigin"]) {
+      if (attributeValue(element, name) !== trusted[name]) {
+        this.report(element, `${url} needs ${name}="${trusted[name]}", as the file rules give it`);
+      }
+    }
+  }
+}
+
+/** Attributes that load a resource, by the elements that carry them. */
+const loadingAttributes = {
+  script: ["src"],
+  img: ["src", "srcset"],
+  source: ["src", "srcset"],
+  video: ["src", "poster"],
+  audio: ["src"],
+  track: ["src"],
+  iframe: ["src"],
+  embed: ["src"],
+  object: ["data"],
+  input: ["src"],
+  link: ["href"],
+};
+/** The same inside an `<svg>`, read from its markup. */
+const svgLoads =
+  /<(?:image|use|feimage|script)\b[^>]*?\s(?:xlink:)?(?:href|src)\s*=\s*(?:"([^"]*)"|'([^']*)')/giu;
+/** The specifier of each static or dynamic module import in a script. */
+const imports = /\bimport\s*(?:\(\s*|[\w$*{}\s,]+?\s*from\s*)?["']([^"']+)["']/gu;
+
+const allowedUrl = /^(?:https:\/\/|data:|#)/iu;
+
+/** The URL of each candidate in a `srcset`, where a `data:` URL may hold commas of its own. */
+function srcsetUrls(srcset) {
+  const urls = [];
+  let rest = srcset;
+  for (;;) {
+    rest = rest.replace(/^[\s,]+/u, "");
+    if (!rest) return urls;
+    const url = /^\S+/u.exec(rest)[0];
+    rest = rest.slice(url.length);
+    if (url.endsWith(",")) {
+      urls.push(url.replace(/,+$/u, ""));
+    } else {
+      urls.push(url);
+      // Skip the descriptor, such as "2x" or "640w", up to the next candidate.
+      rest = rest.replace(/^[^,]*/u, "");
+    }
+  }
+}
+
+class NoRelativePaths extends Rule {
+  documentation() {
+    return {
+      description:
+        "A published file is the only file Pageship serves, so nothing loads from beside it. Use an `https://` or `data:` URL, or a `#fragment`.",
+    };
+  }
+
+  setup() {
+    this.on("dom:ready", ({ document, source }) => {
+      for (const [name, attributes] of Object.entries(loadingAttributes)) {
+        for (const element of document.querySelectorAll(name)) {
+          for (const attribute of attributes) {
+            const value = attributeValue(element, attribute);
+            if (value === null) continue;
+            const urls = attribute === "srcset" ? srcsetUrls(value) : [value.trim()];
+            for (const url of urls) this.check(element, url, element.location);
+          }
+        }
+      }
+      for (const { element, markup, at } of svgContents(document, source)) {
+        for (const match of markup.matchAll(svgLoads)) {
+          this.check(element, (match[1] ?? match[2]).trim(), at(match.index, match[0].length));
+        }
+      }
+      for (const element of document.querySelectorAll("script")) {
+        const text = element.childNodes[0];
+        if (element.hasAttribute("src") || !text) continue;
+        for (const match of element.textContent.matchAll(imports)) {
+          // An import from a URL is pageship/trusted-libraries' problem.
+          if (hasScheme.test(match[1])) continue;
+          const location = locate(
+            text.location,
+            element.textContent,
+            match.index,
+            match.index + match[0].length,
+          );
+          this.check(element, match[1], location);
+        }
+      }
+      for (const { element, css, location } of stylesheets(document, source)) {
+        const code = blank(css, cssComments);
+        for (const match of code.matchAll(/url\(\s*["']?([^"')]*)|@import\s+["']([^"']*)/giu)) {
+          const url = (match[1] ?? match[2]).trim();
+          this.check(
+            element,
+            url,
+            locate(location, css, match.index, match.index + match[0].length),
+          );
+        }
+      }
+    });
+  }
+
+  check(element, url, location) {
+    if (allowedUrl.test(url)) return;
+    this.report(
+      element,
+      `"${url}" loads from beside the file, which isn't published with it: use an https:// or data: URL`,
+      location,
+    );
+  }
+}
+
+const viewportHeight = /(?<![\w.-])-?(?:\d+\.?\d*|\.\d+)(?:vh|svh|lvh|dvh)\b/giu;
+
+class NoViewportHeight extends Rule {
+  documentation() {
+    return {
+      description:
+        "Size parts by their content, `rem` or `%`, not by the window's height: `vh`, `svh`, `lvh` and `dvh` are not allowed.",
+    };
+  }
+
+  setup() {
+    this.on("dom:ready", ({ document, source }) => {
+      for (const { element, css, location } of stylesheets(document, source)) {
+        for (const match of blank(blank(css, cssComments), cssStrings).matchAll(viewportHeight)) {
+          this.report(
+            element,
+            `${match[0]} sizes by the window's height: size by the content, rem or % instead`,
+            locate(location, css, match.index, match.index + match[0].length),
+          );
+        }
+      }
+    });
+  }
+}
+
+export default {
+  name: "pageship",
+  rules: {
+    "pageship/trusted-libraries": TrustedLibraries,
+    "pageship/no-relative-paths": NoRelativePaths,
+    "pageship/no-viewport-height": NoViewportHeight,
+  },
+};

package/dist/skills/pageship-docs/references/html-validate.json

@@ -0,0 +1,13 @@
+{
+  "plugins": ["./html-validate-rules.mjs"],
+  "extends": ["html-validate:recommended", "html-validate:document", "html-validate:prettier"],
+  "rules": {
+    "no-inline-style": "off",
+    "prefer-native-element": ["error", { "exclude": ["region"] }],
+    "require-sri": ["error", { "exclude": ["https://fonts.googleapis.com/"] }],
+    "heading-level": ["error", { "allowMultipleH1": false }],
+    "pageship/trusted-libraries": "error",
+    "pageship/no-relative-paths": "error",
+    "pageship/no-viewport-height": "error"
+  }
+}