@riebeckite/plugin-permalink 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { type ContentLocationInput, type PostFrontmatter } from "@riebeckite/core";
+export type PermalinkIdStrategy = "frontmatter" | "hash" | "frontmatter-or-hash";
+export type PermalinkPathMode = "flat" | "preserve" | "append";
+export type RedirectStatus = 301 | 302 | 307 | 308;
+type ResolverContent = Pick<ContentLocationInput, "slug" | "path"> & {
+    frontmatter: PostFrontmatter;
+};
+export type PermalinkOptions = {
+    frontmatter?: string;
+    id?: {
+        strategy?: PermalinkIdStrategy;
+        length?: number;
+    };
+    path?: {
+        mode?: PermalinkPathMode;
+        prefix?: string;
+        trailingSlash?: boolean;
+    };
+    index?: {
+        collapse?: boolean;
+    };
+    override?: {
+        frontmatter?: string;
+    };
+    redirects?: {
+        frontmatter?: string;
+        status?: RedirectStatus;
+    };
+    resolveId?: (content: ResolverContent) => string;
+    resolvePath?: (input: {
+        content: ResolverContent;
+        id: string;
+    }) => string;
+};
+export declare function permalink(options?: PermalinkOptions): import("@riebeckite/core").RiebeckitePlugin<unknown>;
+export declare const permalinkPlugin: typeof permalink;
+export {};

package/dist/index.js

@@ -0,0 +1,254 @@
+// index.ts
+import { createHash } from "node:crypto";
+import {
+  definePlugin
+} from "@riebeckite/core";
+import { parse } from "yaml";
+function permalink(options = {}) {
+  const resolved = resolveOptions(options);
+  return definePlugin({
+    name: "permalink",
+    resolveContentLocations: ({ entries }) => {
+      const contents = entries.map((entry) => ({
+        ...entry,
+        frontmatter: parseFrontmatter(entry)
+      }));
+      const locations = contents.map(
+        (content) => resolveLocation(content, options, resolved)
+      );
+      assertNoCollisions(locations, contents);
+      return locations;
+    }
+  });
+}
+var permalinkPlugin = permalink;
+function resolveLocation(content, options, resolved) {
+  const override = readOptionalString(
+    content.frontmatter,
+    resolved.overrideField
+  );
+  const explicitId = readOptionalString(
+    content.frontmatter,
+    resolved.frontmatter
+  );
+  const id = override ? explicitId === null ? null : validateId(explicitId, content.path) : options.resolveId ? validateId(options.resolveId(content), content.path) : resolveId(content, resolved);
+  const permalink2 = override ? normalizePath(override, resolved.trailingSlash) : normalizePath(
+    options.resolvePath ? options.resolvePath({ content, id: id ?? "" }) : composePath(content, id ?? "", resolved),
+    resolved.trailingSlash
+  );
+  const redirectValues = content.frontmatter[resolved.redirectsField];
+  const redirects = readRedirects(redirectValues, content.path).map((path) => ({
+    path: normalizePath(path, resolved.trailingSlash),
+    status: resolved.redirectStatus
+  }));
+  return {
+    slug: content.slug,
+    permalink: permalink2,
+    redirects,
+    metadata: id ? {
+      id,
+      idSource: idSource(content, options, resolved, override !== null)
+    } : void 0
+  };
+}
+function idSource(content, options, resolved, hasOverride) {
+  if (hasOverride) return "frontmatter";
+  if (options.resolveId) return "custom";
+  if (resolved.strategy === "hash" || resolved.strategy === "frontmatter-or-hash" && !hasFrontmatterId(content.frontmatter, resolved.frontmatter)) {
+    return "derived";
+  }
+  return "frontmatter";
+}
+function resolveId(content, options) {
+  const value = readOptionalString(content.frontmatter, options.frontmatter);
+  if (options.strategy === "frontmatter") {
+    if (!value) {
+      throw new Error(
+        `Permalink ID is required in frontmatter field "${options.frontmatter}": ${content.path}`
+      );
+    }
+    return validateId(value, content.path);
+  }
+  if (options.strategy === "frontmatter-or-hash" && value) {
+    return validateId(value, content.path);
+  }
+  return createPathId(content.path, options.hashLength);
+}
+function composePath(content, id, options) {
+  if (options.mode === "flat") return joinPath(options.prefix, id);
+  const segments = content.slug.split("/");
+  const fileName = segments.pop() ?? content.slug;
+  if (options.mode === "preserve") {
+    const directories = fileName === "index" && !options.collapseIndex ? [...segments, fileName] : segments;
+    return joinPath(options.prefix, ...directories, id);
+  }
+  const appendSegments = fileName === "index" && options.collapseIndex ? segments : [...segments, fileName];
+  return joinPath(options.prefix, ...appendSegments, id);
+}
+function createPathId(path, length) {
+  const normalized = path.replaceAll("\\", "/").replace(/^\/+/, "").normalize("NFC");
+  return createHash("sha256").update(normalized, "utf8").digest("base64url").slice(0, length);
+}
+function parseFrontmatter(entry) {
+  const match = entry.markdown.match(
+    /^(?:\uFEFF)?---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/
+  );
+  if (!match) return {};
+  const value = parse(match[1] ?? "");
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid frontmatter object: ${entry.path}`);
+  }
+  return value;
+}
+function resolveOptions(options) {
+  const frontmatter = options.frontmatter ?? "id";
+  const strategy = options.id?.strategy ?? "frontmatter-or-hash";
+  const hashLength = options.id?.length ?? 12;
+  if (!Number.isInteger(hashLength) || hashLength < 6 || hashLength > 43) {
+    throw new Error(
+      "Permalink hash ID length must be an integer from 6 through 43."
+    );
+  }
+  const mode = options.path?.mode ?? "flat";
+  if (!["flat", "preserve", "append"].includes(mode)) {
+    throw new Error(`Invalid permalink path mode: ${mode}`);
+  }
+  const redirectStatus = options.redirects?.status ?? 308;
+  if (![301, 302, 307, 308].includes(redirectStatus)) {
+    throw new Error(`Invalid permalink redirect status: ${redirectStatus}`);
+  }
+  return {
+    frontmatter: validateFieldName(frontmatter, "ID"),
+    strategy,
+    hashLength,
+    mode,
+    prefix: normalizePrefix(options.path?.prefix ?? "/n"),
+    trailingSlash: options.path?.trailingSlash ?? false,
+    collapseIndex: options.index?.collapse ?? true,
+    overrideField: validateFieldName(
+      options.override?.frontmatter ?? "permalink",
+      "override"
+    ),
+    redirectsField: validateFieldName(
+      options.redirects?.frontmatter ?? "redirect_from",
+      "redirect"
+    ),
+    redirectStatus
+  };
+}
+function assertNoCollisions(locations, contents) {
+  const bySlug = new Map(contents.map((content) => [content.slug, content]));
+  const ids = /* @__PURE__ */ new Map();
+  const paths = /* @__PURE__ */ new Map();
+  for (const location of locations) {
+    const id = location.metadata?.id;
+    if (id) assertUnique(ids, id, location, bySlug, "Permalink ID collision");
+    assertPathUnique(paths, location.permalink, location, "canonical", bySlug);
+    for (const redirect of location.redirects ?? []) {
+      assertPathUnique(paths, redirect.path, location, "redirect", bySlug);
+    }
+  }
+}
+function assertUnique(values, key, next, contents, heading) {
+  const previous = values.get(key);
+  if (previous)
+    throw collisionError(heading, key, previous, next, contents, "ID", "ID");
+  values.set(key, next);
+}
+function assertPathUnique(values, key, next, kind, contents) {
+  const previous = values.get(key);
+  if (previous)
+    throw collisionError(
+      "Permalink URL collision",
+      key,
+      previous.location,
+      next,
+      contents,
+      previous.kind,
+      kind
+    );
+  values.set(key, { location: next, kind });
+}
+function collisionError(heading, key, first, second, contents, firstKind, secondKind) {
+  return new Error(
+    `${heading}: ${key}
+
+- ${contents.get(first.slug)?.path ?? first.slug} (${firstKind})
+- ${contents.get(second.slug)?.path ?? second.slug} (${secondKind})`
+  );
+}
+function readOptionalString(frontmatter, field) {
+  const value = frontmatter[field];
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "string")
+    throw new Error(`Permalink frontmatter field "${field}" must be a string.`);
+  return value.trim() || null;
+}
+function readRedirects(value, path) {
+  if (value === void 0 || value === null) return [];
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string"))
+    return value;
+  throw new Error(
+    `Permalink redirect field must be a string or string array: ${path}`
+  );
+}
+function hasFrontmatterId(frontmatter, field) {
+  return typeof frontmatter[field] === "string" && frontmatter[field].trim().length > 0;
+}
+function validateId(value, path) {
+  const id = value.trim();
+  const decoded = hasMalformedPercentEncoding(id) ? null : decodeURIComponent(id);
+  if (!id || !decoded || decoded === "." || decoded === ".." || /[\\/#?]/.test(decoded) || /\s/.test(decoded)) {
+    throw new Error(
+      `Invalid permalink ID "${value}" in ${path}. IDs must be a non-empty single path segment.`
+    );
+  }
+  return id;
+}
+function normalizePrefix(value) {
+  if (!value.trim() || value.trim() === "/") return "";
+  return normalizePath(value, false);
+}
+function normalizePath(value, trailingSlash) {
+  const raw = value.trim();
+  if (raw.length === 0 || !raw.startsWith("/") || raw.includes("?") || raw.includes("#") || raw.includes("\\") || raw.includes("//")) {
+    throw new Error(
+      `Invalid permalink path: "${value}". It must be a site-local absolute path.`
+    );
+  }
+  const segments = raw.split("/").filter(Boolean).map((segment) => {
+    if (segment === "." || segment === ".." || hasMalformedPercentEncoding(segment)) {
+      throw new Error(`Invalid permalink path: "${value}".`);
+    }
+    return encodeURIComponent(decodeURIComponent(segment));
+  });
+  const path = `/${segments.join("/")}`;
+  if (path === "/") return "/";
+  return trailingSlash ? `${path}/` : path;
+}
+function joinPath(prefix, ...segments) {
+  return [
+    prefix,
+    ...segments.map(
+      (segment) => encodeURIComponent(decodeURIComponent(segment))
+    )
+  ].filter(Boolean).join("/").replace(/^([^/])/, "/$1");
+}
+function hasMalformedPercentEncoding(value) {
+  try {
+    decodeURIComponent(value);
+    return false;
+  } catch {
+    return true;
+  }
+}
+function validateFieldName(value, label) {
+  if (!value.trim() || /[.[\]]/.test(value))
+    throw new Error(`Permalink ${label} frontmatter field must be top-level.`);
+  return value;
+}
+export {
+  permalink,
+  permalinkPlugin
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@riebeckite/plugin-permalink",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "yaml": "^2.9.0",
+    "@riebeckite/core": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README_ja.md",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rerurate514/riebeckite.git",
+    "directory": "packages/plugins/permalink"
+  },
+  "homepage": "https://github.com/Rerurate514/riebeckite#readme",
+  "bugs": {
+    "url": "https://github.com/Rerurate514/riebeckite/issues"
+  },
+  "description": "Stable, configurable content permalinks for Riebeckite.",
+  "keywords": [
+    "riebeckite",
+    "plugin",
+    "permalinks",
+    "redirects"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "node ../../../scripts/build_package.mjs"
+  }
+}