@mannisto/astro-metadata 1.0.1 → 2.0.0-alpha.1

package/src/lib/checks.js

@@ -0,0 +1,193 @@
+// Plain JavaScript: the integration runs in Node, which does not strip types in node_modules.
+// The dev toolbar app uses the same functions, so the build and the toolbar give the same results.
+
+import { ASSET_RULES, RULES, SITE_RULES } from "./rules.js"
+
+export { findLink, parseHead } from "./head.js"
+export { LIMITS } from "./rules.js"
+
+const ORDER = ["error", "warning", "info"]
+
+const LEVELS = ["error", "warning", "info"]
+
+/**
+ * Returns true for a rule that the `rules.ignore` option does not turn off.
+ *
+ * @param {{ id: string }} rule
+ * @param {import("./checks").CheckOptions} options
+ * @returns {boolean}
+ */
+function isOn(rule, options) {
+  return !options.ignore?.includes(rule.id)
+}
+
+/**
+ * Checks the custom rules of the `rules.custom` option.
+ *
+ * @param {import("./checks").CustomRule[] | undefined} custom
+ * @throws {Error} For a rule without an id, a message, a valid level or a check function,
+ * and for an id that another rule already has.
+ */
+export function validateCustomRules(custom) {
+  const ids = new Set(
+    [...RULES, ...ASSET_RULES, ...SITE_RULES].map((rule) => {
+      return rule.id
+    })
+  )
+  for (const rule of custom ?? []) {
+    const name = rule?.id ? `The custom rule "${rule.id}"` : "A custom rule"
+    if (!rule?.id || typeof rule.id !== "string") throw new Error(`${name} has no \`id\`.`)
+    if (ids.has(rule.id)) throw new Error(`${name} has the id of another rule.`)
+    if (!LEVELS.includes(rule.level)) {
+      throw new Error(`${name} needs a \`level\`: "error", "warning" or "info".`)
+    }
+    if (typeof rule.message !== "string" && typeof rule.message !== "function") {
+      throw new Error(`${name} has no \`message\`.`)
+    }
+    if (typeof rule.check !== "function") throw new Error(`${name} has no \`check\` function.`)
+    ids.add(rule.id)
+  }
+}
+
+/**
+ * Changes a custom rule into a rule of the same form as the rules in `rules.js`.
+ *
+ * @param {import("./checks").CustomRule} rule
+ * @returns {import("./rules").Rule}
+ */
+function toRule(rule) {
+  return {
+    id: rule.id,
+    field: rule.field ?? "custom",
+    level: rule.level,
+    indexed: rule.indexed,
+    check(head) {
+      try {
+        if (!rule.check(head)) return undefined
+        return typeof rule.message === "function" ? rule.message(head) : rule.message
+      } catch (error) {
+        // An error in a custom rule shows as its problem, and the other rules still run
+        return `The custom rule \`${rule.id}\` failed: ${error instanceof Error ? error.message : error}`
+      }
+    },
+  }
+}
+
+/**
+ * Returns the checks with the errors first, then the warnings, then the information.
+ *
+ * @param {import("./checks").Check[]} checks
+ * @returns {import("./checks").Check[]}
+ */
+export function sortChecks(checks) {
+  return checks.sort((a, b) => {
+    return ORDER.indexOf(a.level) - ORDER.indexOf(b.level)
+  })
+}
+
+/**
+ * Returns true for a page with `noindex`. Such a page gets no search and sharing checks.
+ *
+ * @param {import("./head").HeadData} head
+ * @returns {boolean}
+ */
+export function isNoindex(head) {
+  return /noindex/i.test(head.meta.robots ?? "")
+}
+
+/**
+ * Returns a path without the slash at the end, e.g. "/blog" for "/blog/". The root stays "/".
+ *
+ * @param {string} path
+ * @returns {string}
+ */
+function trimSlash(path) {
+  return path.length > 1 ? path.replace(/\/+$/, "") : path
+}
+
+/**
+ * Returns true for a page path that matches a pattern of the `ignore` option.
+ * In a pattern, `*` matches one part of the path and `**` matches any number of parts.
+ *
+ * @example isIgnored("/drafts/hello/", ["/drafts/**"]) // true
+ *
+ * @param {string} path - The path of the page without the base, e.g. "/drafts/hello/".
+ * @param {string[] | undefined} patterns - e.g. ["/404", "/drafts/**"].
+ * @returns {boolean}
+ */
+export function isIgnored(path, patterns) {
+  return (patterns ?? []).some((pattern) => {
+    const source = trimSlash(pattern)
+      .split(/(\*\*|\*)/)
+      .map((part) => {
+        if (part === "**") return ".*"
+        if (part === "*") return "[^/]*"
+        return part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")
+      })
+      .join("")
+    return new RegExp(`^${source}$`).test(trimSlash(path))
+  })
+}
+
+/**
+ * Checks the head of a page with the rules in `rules.js`.
+ *
+ * @param {import("./head").HeadData} head - The metadata from `parseHead`.
+ * @param {import("./checks").CheckOptions} [options]
+ * @returns {import("./checks").Check[]} The problems, errors first.
+ */
+export function checkHead(head, options = {}) {
+  const noindex = isNoindex(head)
+
+  /** @type {import("./checks").Check[]} */
+  const checks = []
+  const custom = (options.custom ?? []).map(toRule)
+  for (const rule of [...RULES, ...custom]) {
+    if ((noindex && rule.indexed) || !isOn(rule, options)) continue
+
+    const message = rule.check(head)
+    if (message) checks.push({ id: rule.id, field: rule.field, level: rule.level, message })
+  }
+  return sortChecks(checks)
+}
+
+/**
+ * Checks the loaded files of a page: the `og:image` and the favicons.
+ *
+ * @param {import("./head").HeadData} head
+ * @param {import("./rules").PageAssets} assets
+ * @param {import("./checks").CheckOptions} [options]
+ * @returns {import("./checks").Check[]}
+ */
+export function checkAssets(head, assets, options = {}) {
+  /** @type {import("./checks").Check[]} */
+  const checks = []
+  for (const rule of ASSET_RULES) {
+    if (!isOn(rule, options)) continue
+
+    const message = rule.check(head, assets)
+    if (message) checks.push({ id: rule.id, field: rule.field, level: rule.level, message })
+  }
+  return sortChecks(checks)
+}
+
+/**
+ * Compares the pages of the site, e.g. two pages with the same title.
+ *
+ * @param {import("./rules").SitePage[]} pages
+ * @param {import("./checks").CheckOptions} [options]
+ * @returns {Map<string, import("./checks").Check[]>} The problems of each page path.
+ */
+export function checkSite(pages, options = {}) {
+  /** @type {Map<string, import("./checks").Check[]>} */
+  const result = new Map()
+  for (const rule of SITE_RULES) {
+    if (!isOn(rule, options)) continue
+
+    for (const problem of rule.check(pages)) {
+      const check = { id: rule.id, field: rule.field, level: rule.level, message: problem.message }
+      result.set(problem.path, [...(result.get(problem.path) ?? []), check])
+    }
+  }
+  return result
+}

package/src/lib/config.ts

@@ -0,0 +1,111 @@
+import type { FaviconInfo } from "./favicon.ts"
+import type { ManifestConfig } from "./manifest.ts"
+
+/**
+ * A text value: one string for all locales, or one string for each locale.
+ *
+ * @example "Acme Studio"
+ * @example { en: "Acme Studio", fi: "Acme Studio Suomi" }
+ */
+export type Localized = string | Record<string, string>
+
+/**
+ * An image for the social cards. Use an image of 1200 × 630 px.
+ */
+export type MetadataImage = {
+  /** The path or URL of the image, e.g. "/og.jpg". */
+  url: string
+  /** A description of the image. */
+  alt?: string
+  width?: number
+  height?: number
+}
+
+/**
+ * The color of the browser interface: one color, or one color for each color mode.
+ */
+export type ThemeColor = string | { light: string; dark: string }
+
+/**
+ * A feed of the site: RSS, Atom or JSON.
+ */
+export type Feed = {
+  /** The path of the feed, e.g. "/rss.xml". */
+  href: string
+  title?: Localized
+  /** Defaults to "rss". */
+  type?: "rss" | "atom" | "json"
+}
+
+/**
+ * The site values in the `metadata()` integration. The props of `<Metadata>` override them.
+ */
+export type MetadataConfig = {
+  /** The name of the site: the title of a page without a title, and `og:site_name`. */
+  siteName?: Localized
+  /** The title template, e.g. "%s | My Site". */
+  titleTemplate?: Localized
+  /** The description of a page without a description. */
+  description?: Localized
+  /** The social image of a page without an image. */
+  image?: Omit<MetadataImage, "alt"> & { alt?: Localized }
+  twitter?: {
+    /** The card type for pages with an image. Defaults to "summary_large_image". */
+    card?: "summary" | "summary_large_image"
+    /** The Twitter (X) handle of the site, e.g. "@mysite". */
+    site?: string
+  }
+  /** The color of the browser interface, e.g. the address bar on Android. */
+  themeColor?: ThemeColor
+  /** The feeds of the site. */
+  feeds?: Feed[]
+  robots?: {
+    /** Set to false to keep all pages out of search results, e.g. on a staging site. */
+    index?: boolean
+    /** Set to false to tell search engines not to follow the links. */
+    follow?: boolean
+    /** Other directives for all pages, e.g. "max-image-preview:large". */
+    extra?: string
+  }
+  /** The web app manifest: an object to generate it, or the path of your own manifest. */
+  manifest?: ManifestConfig | string
+}
+
+/**
+ * The data that the integration gives to the components at build time.
+ */
+export type RuntimeConfig = MetadataConfig & {
+  /** The generated favicon files. */
+  favicon?: FaviconInfo
+  /** The `trailingSlash` setting of the Astro config. */
+  trailingSlash?: "always" | "never" | "ignore"
+  /** The `build.format` setting of the Astro config. */
+  buildFormat?: "directory" | "file" | "preserve"
+  /** The `base` of the Astro config. */
+  base?: string
+  /** The `site` of the Astro config. The dev toolbar app loads its files from the dev server. */
+  site?: string
+}
+
+// The integration replaces this name with the config, with Vite's `define`
+declare const __ASTRO_METADATA__: RuntimeConfig | undefined
+
+/**
+ * Returns the config of the integration, or an empty config without the integration.
+ */
+export function getConfig(): RuntimeConfig {
+  return typeof __ASTRO_METADATA__ === "undefined" ? {} : __ASTRO_METADATA__
+}
+
+/**
+ * Returns the value of a text for a locale. A missing locale uses the first value.
+ *
+ * @param value - A string or an object with one string for each locale.
+ * @param locale - The current locale, e.g. "fi".
+ * @returns The text, or undefined without a value.
+ */
+export function localize(value: Localized | undefined, locale?: string): string | undefined {
+  if (value === undefined || typeof value === "string") return value
+  if (locale && Object.hasOwn(value, locale)) return value[locale]
+  return Object.values(value)[0]
+}

package/src/lib/favicon-files.d.ts

@@ -0,0 +1,29 @@
+/** A favicon file in the `files` option. The format comes from the extension. */
+export type FaviconFile = {
+  /** The URL of the file, e.g. "/favicon-96.png". Must end in .ico, .png or .svg. */
+  path: string
+  /** The size in px. Required for a PNG file. */
+  size?: number
+  /** The sizes of the images in an ICO file. Defaults to [16, 32]. */
+  sizes?: number[]
+}
+
+/** A favicon file after the checks, with its format and its use. */
+export type ResolvedFaviconFile = {
+  path: string
+  type: "ico" | "png" | "svg"
+  /**
+   * "icon": an icon link tag. "apple": the Apple link tag.
+   * "manifest": the web app manifest (PNG files of 192 px or larger).
+   */
+  use: "icon" | "apple" | "manifest"
+  /** The sizes in px, smallest first. Empty for an SVG file. */
+  sizes: number[]
+}
+
+export declare function defaultFaviconFiles(svg: boolean): FaviconFile[]
+
+export declare function resolveFaviconFiles(
+  files: FaviconFile[],
+  svg: boolean
+): ResolvedFaviconFile[]

package/src/lib/favicon-files.js

@@ -0,0 +1,103 @@
+// Plain JavaScript: the integration runs in Node, which does not strip types in node_modules.
+
+// A PNG file of this size or larger goes into the web app manifest. Smaller PNG files get an
+// icon link tag. 192 px is the smallest icon that browsers use to install a web app.
+const MANIFEST_SIZE = 192
+
+/**
+ * The default files. An SVG source also gives `favicon.svg`.
+ *
+ * @param {boolean} svg - True for an SVG source.
+ * @returns {import("./favicon-files").FaviconFile[]}
+ */
+export function defaultFaviconFiles(svg) {
+  return [
+    { path: "/favicon.ico", sizes: [16, 32] },
+    ...(svg ? [{ path: "/favicon.svg" }] : []),
+    { path: "/favicon-16.png", size: 16 },
+    { path: "/favicon-32.png", size: 32 },
+    { path: "/apple-touch-icon.png", size: 180 },
+    { path: "/favicon-192.png", size: 192 },
+    { path: "/favicon-512.png", size: 512 },
+  ]
+}
+
+/**
+ * Returns true for a whole number from 1 to a maximum.
+ *
+ * @param {unknown} value
+ * @param {number} max
+ * @returns {boolean}
+ */
+function isSize(value, max) {
+  return Number.isInteger(value) && Number(value) >= 1 && Number(value) <= max
+}
+
+/**
+ * Checks the favicon files and finds the use of each file from its name, format and size:
+ * - `.ico` and `.svg` files get an icon link tag.
+ * - `apple-touch-icon.png` gets the Apple link tag and the background color.
+ * - Other `.png` files smaller than 192 px get an icon link tag.
+ * - Other `.png` files of 192 px or larger go into the web app manifest.
+ *
+ * @param {import("./favicon-files").FaviconFile[]} files - The `files` option, or the defaults.
+ * @param {boolean} svg - True for an SVG source.
+ * @returns {import("./favicon-files").ResolvedFaviconFile[]}
+ * @throws {Error} For a file that the package can not generate.
+ */
+export function resolveFaviconFiles(files, svg) {
+  const paths = new Set()
+
+  return files.map((file) => {
+    const { path } = file
+    if (typeof path !== "string" || !path.startsWith("/")) {
+      throw new Error(`The favicon path "${path}" must start with "/".`)
+    }
+    if (paths.has(path)) {
+      throw new Error(`The favicon path "${path}" is in the list two times.`)
+    }
+    paths.add(path)
+
+    const type = path.split(".").pop()?.toLowerCase()
+    const name = path.split("/").pop() ?? ""
+
+    if (type === "svg") {
+      if (!svg) throw new Error(`"${path}" needs an SVG source.`)
+      if (file.size !== undefined || file.sizes !== undefined) {
+        throw new Error(`"${path}" is an SVG file, so it has no size.`)
+      }
+      return { path, type, use: "icon", sizes: [] }
+    }
+
+    if (type === "ico") {
+      if (file.size !== undefined && file.sizes !== undefined) {
+        throw new Error(`"${path}" has "size" and "sizes". Use one.`)
+      }
+      const sizes = file.sizes ?? (file.size !== undefined ? [file.size] : [16, 32])
+      const valid = sizes.every((size) => {
+        return isSize(size, 256)
+      })
+      if (sizes.length === 0 || !valid) {
+        throw new Error(`The sizes of "${path}" must be whole numbers from 1 to 256.`)
+      }
+      const sorted = [...sizes].sort((a, b) => {
+        return a - b
+      })
+      return { path, type, use: "icon", sizes: sorted }
+    }
+
+    if (type === "png") {
+      if (file.sizes !== undefined) {
+        throw new Error(`"${path}" is a PNG file: use "size", not "sizes".`)
+      }
+      if (!isSize(file.size, 4096)) {
+        throw new Error(`"${path}" needs a "size" from 1 to 4096.`)
+      }
+      let use = file.size >= MANIFEST_SIZE ? "manifest" : "icon"
+      if (name.startsWith("apple-touch-icon")) use = "apple"
+      return { path, type, use, sizes: [file.size] }
+    }
+
+    throw new Error(`"${path}" must be an .ico, .png or .svg file.`)
+  })
+}

package/src/lib/favicon-image.ts

@@ -0,0 +1,124 @@
+import fs from "node:fs/promises"
+import { createRequire } from "node:module"
+import type Sharp from "sharp"
+
+import { getConfig } from "./config.ts"
+import type { FaviconInfo } from "./favicon.ts"
+
+// The Apple icon shows the logo on the background color, with space around it.
+// The logo fills 80 % of the icon.
+const APPLE_CONTENT = 0.8
+
+/**
+ * Loads sharp from the path that the integration found. The build writes this code into
+ * the dist folder of the project, and with pnpm the project can not see the dependencies
+ * of this package from there.
+ */
+function loadSharp(favicon: FaviconInfo): typeof Sharp {
+  return createRequire(import.meta.url)(favicon.sharp)
+}
+
+/**
+ * Renders a square PNG of the source with transparent space around it.
+ * An SVG source is rasterized at a density that gives a sharp result at the size.
+ */
+async function renderPng(favicon: FaviconInfo, size: number): Promise<Buffer> {
+  const sharp = loadSharp(favicon)
+  const source = await fs.readFile(favicon.source)
+  const meta = await sharp(source).metadata()
+  const smallest = Math.min(meta.width ?? size, meta.height ?? size)
+  const density = favicon.svg ? Math.min(2400, Math.ceil((72 * size) / smallest)) : undefined
+
+  return sharp(source, density ? { density } : {})
+    .resize(size, size, { fit: "contain", background: { r: 0, g: 0, b: 0, alpha: 0 } })
+    .png()
+    .toBuffer()
+}
+
+/**
+ * Renders a square icon with a background color and padding around the logo.
+ */
+async function renderPadded(favicon: FaviconInfo, size: number, content: number): Promise<Buffer> {
+  const inner = Math.round(size * content)
+  const logo = await renderPng(favicon, inner)
+  const offset = Math.floor((size - inner) / 2)
+  const sharp = loadSharp(favicon)
+
+  return sharp({
+    create: { width: size, height: size, channels: 4, background: favicon.background },
+  })
+    .composite([{ input: logo, left: offset, top: offset }])
+    .png()
+    .toBuffer()
+}
+
+/**
+ * Puts PNG images into an ICO container: a 6-byte header, a 16-byte entry
+ * for each image, and then the PNG data of each image.
+ */
+function toIco(images: { size: number; png: Buffer }[]): Buffer {
+  const header = Buffer.alloc(6)
+  header.writeUInt16LE(0, 0)
+  header.writeUInt16LE(1, 2)
+  header.writeUInt16LE(images.length, 4)
+
+  let offset = 6 + 16 * images.length
+  const entries = images.map((image) => {
+    const entry = Buffer.alloc(16)
+    entry.writeUInt8(image.size >= 256 ? 0 : image.size, 0)
+    entry.writeUInt8(image.size >= 256 ? 0 : image.size, 1)
+    entry.writeUInt8(0, 2)
+    entry.writeUInt8(0, 3)
+    entry.writeUInt16LE(1, 4)
+    entry.writeUInt16LE(32, 6)
+    entry.writeUInt32LE(image.png.length, 8)
+    entry.writeUInt32LE(offset, 12)
+    offset += image.png.length
+    return entry
+  })
+
+  return Buffer.concat([
+    header,
+    ...entries,
+    ...images.map((image) => {
+      return image.png
+    }),
+  ])
+}
+
+/**
+ * Renders a generated favicon file as a response.
+ *
+ * @param path - The path of the file, e.g. "/apple-touch-icon.png".
+ * @returns The response with the file, or a 404 for a file that is not in the favicon config.
+ */
+export async function renderFavicon(path: string): Promise<Response> {
+  const favicon = getConfig().favicon
+  const file = favicon?.files.find((entry) => {
+    return entry.path === path
+  })
+  if (!favicon || !file) return new Response(null, { status: 404 })
+
+  if (file.type === "svg") {
+    const svg = await fs.readFile(favicon.source)
+    return new Response(svg, { headers: { "Content-Type": "image/svg+xml" } })
+  }
+
+  if (file.type === "ico") {
+    const images = await Promise.all(
+      file.sizes.map(async (size) => {
+        return { size, png: await renderPng(favicon, size) }
+      })
+    )
+    return new Response(new Uint8Array(toIco(images)), {
+      headers: { "Content-Type": "image/x-icon" },
+    })
+  }
+
+  const size = file.sizes[0]
+  const png =
+    file.use === "apple"
+      ? await renderPadded(favicon, size, APPLE_CONTENT)
+      : await renderPng(favicon, size)
+  return new Response(new Uint8Array(png), { headers: { "Content-Type": "image/png" } })
+}