@no-k/hermes 0.1.0 → 0.3.0

package/templates/lint/fsd/fsd.ts

@@ -0,0 +1,180 @@
+import path from "node:path";
+import { DEFAULT_FSD_LAYERS, type FsdOptions } from "./options";
+
+// This module knows only paths and FSD policy. It does not depend on ESLint, ASTs or filesystem reads.
+export const toPosixPath = (value: string): string =>
+  value.replaceAll("\\", "/").replace(/^[a-z]:/, (drive) => drive.toUpperCase());
+
+export const resolvePath = (base: string, value: string): string => {
+  const windows = /^[a-z]:[/\\]/i.test(base) || /^[a-z]:[/\\]/i.test(value);
+  return toPosixPath((windows ? path.win32 : path.posix).resolve(toPosixPath(base), toPosixPath(value)));
+};
+
+const isWithin = (parent: string, child: string): boolean =>
+  child === parent || child.startsWith(parent.endsWith("/") ? parent : parent + "/");
+const sourceExtension = /(?:\.d)?\.[cm]?[jt]sx?$/;
+const withoutExtension = (name: string): string => name.replace(sourceExtension, "");
+const isFile = (name: string): boolean => /\.[^/]+$/.test(name);
+
+type Root = { path: string; aliases: [string, string][] };
+export type FsdLocation = {
+  root: string;
+  layer: string;
+  parts: string[];
+  slice?: string;
+  scope: string[];
+  segmentless: boolean;
+};
+export type FsdViolation = {
+  messageId: "invalidDirection" | "crossSliceSameLayer" | "usePublicApi" | "missingSlice" | "missingSegment";
+  data: Record<string, string>;
+};
+
+const normalizeAliases = (...groups: Record<string, string>[]): [string, string][] => {
+  const aliases = new Map<string, string>();
+  for (const group of groups) {
+    for (const [key, target] of Object.entries(group)) {
+      const prefix = key.replace(/\/\*$/, "").replace(/\/$/, "");
+      const destination = target.replace(/\/\*$/, "");
+      if (!prefix || prefix.includes("*") || destination.includes("*")) {
+        throw new Error("FSD aliases must be exact prefixes, optionally ending in /*.");
+      }
+      aliases.set(prefix, destination);
+    }
+  }
+  return [...aliases].sort(([a], [b]) => b.length - a.length);
+};
+
+export function createFsdPolicy(cwd: string, options: FsdOptions = {}) {
+  const layers = options.layers ?? DEFAULT_FSD_LAYERS;
+  const ranks = new Map(layers.map((layer, index) => [layer, index]));
+  const segmentlessLayers = options.segmentlessLayers ?? ["app", "shared"];
+  const publicApiFiles = options.publicApiFiles ?? ["index"];
+  const sharedModuleSegments = options.sharedModuleSegments ?? ["ui", "lib"];
+  const roots: Root[] = (options.roots ?? ["src"])
+    .map((root) => {
+      const definition = typeof root === "string" ? { path: root } : root;
+      return {
+        path: resolvePath(cwd, definition.path),
+        aliases: normalizeAliases({ "@": ".", "~": "." }, options.aliases ?? {}, definition.aliases ?? {}),
+      };
+    })
+    .sort((a, b) => b.path.length - a.path.length);
+  if (new Set(roots.map((root) => root.path)).size !== roots.length) {
+    throw new Error("FSD roots must resolve to different directories.");
+  }
+  const ignored = (options.ignore ?? []).map((prefix) => {
+    const normalized = toPosixPath(prefix).replace(/^\.\//, "").replace(/\/$/, "");
+    if (!normalized || normalized.startsWith("/") || normalized.includes("*") || normalized.split("/").includes("..")) {
+      throw new Error("FSD ignore paths must be root-relative file/directory prefixes without globs or '..'.");
+    }
+    return normalized;
+  });
+  const isPublicFile = (name: string): boolean => publicApiFiles.includes(withoutExtension(name));
+
+  function locate(filename: string): FsdLocation | undefined {
+    const absolute = resolvePath(cwd, filename);
+    const root = roots.find((candidate) => isWithin(candidate.path, absolute));
+    if (!root) return undefined;
+    const relative = absolute.slice(root.path.length).replace(/^\//, "");
+    if (ignored.some((prefix) => isWithin(prefix, relative))) return undefined;
+    const parts = relative.split("/").filter(Boolean);
+    const layer = parts[0];
+    if (!layer || !ranks.has(layer)) return undefined;
+    const segmentless = segmentlessLayers.includes(layer);
+    const scope = parts.slice(0, 2);
+    // Shared UI/lib modules may each have an index, avoiding one large segment barrel.
+    if (
+      layer === "shared" &&
+      sharedModuleSegments.includes(parts[1] ?? "") &&
+      parts[2] &&
+      !isFile(parts[2]) &&
+      !isPublicFile(parts[2])
+    ) {
+      scope.push(parts[2]);
+    }
+    return { root: root.path, layer, parts, slice: segmentless ? undefined : parts[1], scope, segmentless };
+  }
+
+  function resolveImport(source: string, importer: FsdLocation, filename: string): FsdLocation | undefined {
+    if (source.startsWith(".")) return locate(resolvePath(resolvePath(filename, ".."), source));
+    if (path.posix.isAbsolute(source) || path.win32.isAbsolute(source)) return locate(source);
+    const root = roots.find((candidate) => candidate.path === importer.root);
+    if (!root) return undefined;
+    for (const [alias, target] of root.aliases) {
+      if (source === alias || source.startsWith(alias + "/")) {
+        return locate(resolvePath(resolvePath(root.path, target), source.slice(alias.length).replace(/^\//, "")));
+      }
+    }
+    // Bare specifiers are npm packages unless explicitly mapped by the consumer.
+    return undefined;
+  }
+
+  const sameSlice = (from: FsdLocation, to: FsdLocation): boolean =>
+    from.root === to.root && from.layer === to.layer && from.slice !== undefined && from.slice === to.slice;
+  const sameScope = (from: FsdLocation, to: FsdLocation): boolean =>
+    from.root === to.root && from.scope.join("/") === to.scope.join("/");
+  const entityCrossApi = (from: FsdLocation, to: FsdLocation): boolean =>
+    (options.allowEntityCrossImports ?? true) &&
+    from.root === to.root &&
+    from.layer === "entities" &&
+    to.layer === "entities" &&
+    from.slice !== to.slice &&
+    to.parts.length === 4 &&
+    to.parts[2] === "@x" &&
+    withoutExtension(to.parts[3] ?? "") === from.slice;
+
+  function checkLayers(from: FsdLocation, to: FsdLocation): FsdViolation | undefined {
+    if ((ranks.get(to.layer) ?? -1) > (ranks.get(from.layer) ?? -1)) {
+      return { messageId: "invalidDirection", data: { fromLayer: from.layer, toLayer: to.layer } };
+    }
+    if (
+      from.layer === to.layer &&
+      !sameSlice(from, to) &&
+      !(from.segmentless && from.root === to.root) &&
+      !entityCrossApi(from, to) &&
+      !options.allowCrossSliceSameLayer &&
+      !(options.allowCrossSliceLayers ?? []).includes(from.layer)
+    ) {
+      return {
+        messageId: "crossSliceSameLayer",
+        data: {
+          fromLayer: from.layer,
+          fromSlice: from.slice ?? from.scope[1] ?? "",
+          toLayer: to.layer,
+          toSlice: to.slice ?? to.scope[1] ?? "",
+        },
+      };
+    }
+    return undefined;
+  }
+
+  function checkPublicApi(from: FsdLocation, to: FsdLocation): FsdViolation | undefined {
+    if (sameScope(from, to) || entityCrossApi(from, to)) return undefined;
+    const remainder = to.parts.slice(to.scope.length);
+    const publicScope = to.scope.length >= 2 && !isFile(to.scope[to.scope.length - 1] ?? "");
+    if (publicScope && (remainder.length === 0 || (remainder.length === 1 && isPublicFile(remainder[0] ?? "")))) {
+      return undefined;
+    }
+    return { messageId: "usePublicApi", data: { layer: to.layer, publicName: to.scope.slice(1).join("/") } };
+  }
+
+  function checkStructure(location: FsdLocation): FsdViolation | undefined {
+    if ((options.ignoreLayers ?? []).includes(location.layer)) return undefined;
+    const { parts, layer, segmentless } = location;
+    const filename = parts[parts.length - 1] ?? "";
+    if (segmentless) {
+      if (parts.length >= 3 || (parts.length === 2 && isPublicFile(filename))) return undefined;
+      return { messageId: "missingSegment", data: { layer, slice: "" } };
+    }
+    if (parts.length < 3) {
+      return { messageId: "missingSlice", data: { layer } };
+    }
+    if (parts.length === 3 && !isPublicFile(filename)) {
+      return { messageId: "missingSegment", data: { layer, slice: parts[1] ?? "" } };
+    }
+    return undefined;
+  }
+
+  return { locate, resolveImport, checkLayers, checkPublicApi, checkStructure };
+}

package/templates/lint/fsd/import-listener.ts

@@ -0,0 +1,41 @@
+import type { Rule } from "eslint";
+import { type FsdViolation, createFsdPolicy } from "./fsd";
+import type { FsdOptions } from "./options";
+
+type SourceNode = {
+  value?: unknown;
+  literal?: SourceNode;
+  source?: SourceNode;
+  argument?: SourceNode;
+};
+
+export function createImportListener(
+  context: Rule.RuleContext,
+  check: "checkLayers" | "checkPublicApi",
+): Rule.RuleListener {
+  const filename = context.filename;
+  if (!filename || filename.startsWith("<")) return {};
+  const policy = createFsdPolicy(context.cwd, context.options[0] as FsdOptions | undefined);
+  const from = policy.locate(filename);
+  if (!from) return {};
+  const visit = (node: Rule.Node): void => {
+    const candidate = node as unknown as SourceNode;
+    let source = candidate.source;
+    if (!source) {
+      const argument = candidate.argument;
+      source = argument?.literal ?? argument;
+    }
+    if (typeof source?.value !== "string") return;
+    const to = policy.resolveImport(source.value, from, filename);
+    if (!to) return;
+    const violation: FsdViolation | undefined = policy[check](from, to);
+    if (violation) context.report({ node: source as Rule.Node, ...violation });
+  };
+  return {
+    ImportDeclaration: visit,
+    ExportNamedDeclaration: visit,
+    ExportAllDeclaration: visit,
+    ImportExpression: visit,
+    TSImportType: visit,
+  };
+}

package/templates/lint/fsd/index.ts

@@ -0,0 +1,32 @@
+// Hermes copies this plugin into the consumer project. Edit these files to customize its policy.
+import type { Linter } from "eslint";
+import { type FsdOptions, HERMES_OPTIONS } from "./options";
+import fsdLayerImports from "./rules/fsd-layer-imports";
+import fsdPublicApi from "./rules/fsd-public-api";
+import fsdSliceSegments from "./rules/fsd-slice-segments";
+
+export type { FsdOptions, FsdRoot } from "./options";
+
+const plugin = {
+  meta: { name: "hermes-fsd" },
+  rules: {
+    "fsd-layer-imports": fsdLayerImports,
+    "fsd-public-api": fsdPublicApi,
+    "fsd-slice-segments": fsdSliceSegments,
+  },
+  configs: {} as { recommended: Linter.Config; hermes: Linter.Config },
+};
+
+export function createConfig(options: FsdOptions = {}, namespace = "fsd"): Linter.Config {
+  return {
+    name: "hermes-fsd/" + namespace,
+    files: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
+    plugins: { [namespace]: plugin },
+    rules: Object.fromEntries(Object.keys(plugin.rules).map((rule) => [namespace + "/" + rule, ["error", options]])),
+  };
+}
+
+plugin.configs.recommended = createConfig();
+plugin.configs.hermes = createConfig(HERMES_OPTIONS, "hermes");
+
+export default plugin;

package/templates/lint/fsd/options.ts

@@ -0,0 +1,74 @@
+export type FsdRoot = {
+  path: string;
+  /** Alias targets are relative to this FSD root, not the process cwd. */
+  aliases?: Record<string, string>;
+};
+
+export type FsdOptions = {
+  roots?: (string | FsdRoot)[];
+  aliases?: Record<string, string>;
+  /** Lowest to highest. Deprecated "processes" is opt-in. */
+  layers?: string[];
+  segmentlessLayers?: string[];
+  allowCrossSliceLayers?: string[];
+  allowCrossSliceSameLayer?: boolean;
+  allowEntityCrossImports?: boolean;
+  /** Root-relative file/directory prefixes, not globs. Applies to both ends of an import. */
+  ignore?: string[];
+  /** Only affects the structure rule. */
+  ignoreLayers?: string[];
+  /** Public entrypoint basenames, without extensions. */
+  publicApiFiles?: string[];
+  /** Shared segments whose child modules may expose their own public API. */
+  sharedModuleSegments?: string[];
+};
+
+export const DEFAULT_FSD_LAYERS = ["shared", "entities", "features", "widgets", "pages", "app"];
+
+export const HERMES_OPTIONS: FsdOptions = {
+  layers: ["shared", "entities", "features", "widgets", "pages", "processes", "app"],
+  allowCrossSliceLayers: ["widgets", "pages", "processes", "app"],
+  ignoreLayers: ["shared", "app"],
+};
+
+const names = {
+  type: "array",
+  items: { type: "string", pattern: "^[^/\\\\.*]+$" },
+  uniqueItems: true,
+};
+const aliases = {
+  type: "object",
+  additionalProperties: { type: "string", minLength: 1 },
+};
+
+export const optionSchema = {
+  type: "object",
+  properties: {
+    roots: {
+      type: "array",
+      minItems: 1,
+      items: {
+        anyOf: [
+          { type: "string", minLength: 1 },
+          {
+            type: "object",
+            properties: { path: { type: "string", minLength: 1 }, aliases },
+            required: ["path"],
+            additionalProperties: false,
+          },
+        ],
+      },
+    },
+    aliases,
+    layers: { ...names, minItems: 1 },
+    segmentlessLayers: names,
+    allowCrossSliceLayers: names,
+    allowCrossSliceSameLayer: { type: "boolean" },
+    allowEntityCrossImports: { type: "boolean" },
+    ignore: { type: "array", items: { type: "string", minLength: 1 }, uniqueItems: true },
+    ignoreLayers: names,
+    publicApiFiles: { ...names, minItems: 1 },
+    sharedModuleSegments: names,
+  },
+  additionalProperties: false,
+} as const;

package/templates/lint/fsd/rules/fsd-layer-imports.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "eslint";
+import { createImportListener } from "../import-listener";
+import { optionSchema } from "../options";
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Enforce FSD layer direction and slice isolation",
+      url: "https://github.com/no-k/hermes/tree/main/packages/lib/lint/fsd#fsd-layer-imports",
+    },
+    schema: [optionSchema],
+    messages: {
+      invalidDirection: "FSD layer '{{fromLayer}}' cannot import upper layer '{{toLayer}}'.",
+      crossSliceSameLayer:
+        "FSD same-layer imports must stay inside the same slice. '{{fromLayer}}/{{fromSlice}}' cannot import '{{toLayer}}/{{toSlice}}'.",
+    },
+  },
+  create: (context) => createImportListener(context, "checkLayers"),
+};
+
+export default rule;

package/templates/lint/fsd/rules/fsd-public-api.ts

@@ -0,0 +1,20 @@
+import type { Rule } from "eslint";
+import { createImportListener } from "../import-listener";
+import { optionSchema } from "../options";
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Enforce public API imports across FSD scopes",
+      url: "https://github.com/no-k/hermes/tree/main/packages/lib/lint/fsd#fsd-public-api",
+    },
+    schema: [optionSchema],
+    messages: {
+      usePublicApi: "FSD cross-scope import must use the public API of '{{layer}}/{{publicName}}'.",
+    },
+  },
+  create: (context) => createImportListener(context, "checkPublicApi"),
+};
+
+export default rule;

package/templates/lint/fsd/rules/fsd-slice-segments.ts

@@ -0,0 +1,33 @@
+import type { Rule } from "eslint";
+import { createFsdPolicy } from "../fsd";
+import { type FsdOptions, optionSchema } from "../options";
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Enforce FSD slice/segment structure, including segment-only App and Shared",
+      url: "https://github.com/no-k/hermes/tree/main/packages/lib/lint/fsd#fsd-slice-segments",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingSlice: "FSD layer '{{layer}}' must contain slice directories before implementation files.",
+      missingSegment:
+        "FSD implementation in '{{layer}}/{{slice}}' must live in a segment or be an allowed public API entrypoint.",
+    },
+  },
+  create(context) {
+    if (!context.filename || context.filename.startsWith("<")) return {};
+    const policy = createFsdPolicy(context.cwd, context.options[0] as FsdOptions | undefined);
+    const location = policy.locate(context.filename);
+    if (!location) return {};
+    return {
+      Program(node) {
+        const violation = policy.checkStructure(location);
+        if (violation) context.report({ node, ...violation });
+      },
+    };
+  },
+};
+
+export default rule;

package/bin/hermes.mjs

@@ -1,159 +0,0 @@
-#!/usr/bin/env node
-import { lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { parseArgs } from "node:util";
-import { validateCatalog } from "../lib/catalog.mjs";
-
-const packageDirectory = fileURLToPath(new URL("../", import.meta.url));
-const manifest = JSON.parse(readFileSync(path.join(packageDirectory, "package.json"), "utf8"));
-const help = [
-  "Hermes " + manifest.version + " — copy TypeScript utilities into your project",
-  "",
-  "Usage:",
-  "  hermes list",
-  "  hermes add <item...> --dir <directory> [--dry-run] [--overwrite]",
-  "",
-  "Options:",
-  "  -d, --dir       Destination for utility folders and LICENSE (required for add)",
-  "  --dry-run       Show the planned files without writing",
-  "  --overwrite     Replace existing files whose contents differ",
-  "  -h, --help      Show help",
-  "  -v, --version   Show version",
-  "",
-  "Example:",
-  "  npx @no-k/hermes add array-chunk --dir src/lib/hermes",
-  "",
-  "External npm dependencies are reported; they are not installed automatically.",
-].join("\n");
-
-function stat(file) {
-  try {
-    return lstatSync(file);
-  } catch (error) {
-    if (error.code === "ENOENT") return undefined;
-    throw error;
-  }
-}
-
-function destinationStat(directory, relative) {
-  let current = directory;
-  const segments = relative.split("/");
-  for (let index = -1; index < segments.length; index += 1) {
-    if (index >= 0) current = path.join(current, segments[index]);
-    const info = stat(current);
-    if (info?.isSymbolicLink()) throw new Error("Refusing to write through a symbolic link: " + current);
-    if (index < segments.length - 1 && info && !info.isDirectory()) {
-      throw new Error("Expected a directory: " + current);
-    }
-    if (index === segments.length - 1) {
-      if (info && !info.isFile()) throw new Error("Expected a regular file: " + current);
-      return info;
-    }
-  }
-}
-
-function sourceContent(relative) {
-  const directory = realpathSync(path.join(packageDirectory, "templates"));
-  const file = realpathSync(path.join(directory, relative));
-  const fromRoot = path.relative(directory, file);
-  if (path.isAbsolute(fromRoot) || fromRoot === ".." || fromRoot.startsWith(".." + path.sep)) {
-    throw new Error("Source template escapes its directory: " + relative);
-  }
-  return readFileSync(file, "utf8");
-}
-
-function add(items, options) {
-  if (!options.dir?.trim()) throw new Error("Specify a destination with --dir <directory>.");
-  const directory = path.resolve(options.dir);
-  const files = new Map();
-  for (const item of items) {
-    for (const file of item.files) {
-      if (!files.has(file)) files.set(file, sourceContent(file));
-    }
-  }
-  files.set("LICENSE", readFileSync(path.join(packageDirectory, "LICENSE"), "utf8"));
-  const plan = [...files]
-    .sort(([a], [b]) => a.localeCompare(b))
-    .map(([file, content]) => {
-      const destination = path.join(directory, file);
-      const existing = destinationStat(directory, file);
-      const same = existing && readFileSync(destination, "utf8") === content;
-      return { file, content, destination, action: same ? "keep" : existing ? "replace" : "create" };
-    });
-  const conflicts = plan.filter((file) => file.action === "replace");
-  if (conflicts.length && !options.overwrite) {
-    throw new Error(
-      "Existing files differ; no files were written:\n" +
-        conflicts.map((file) => "  " + file.destination).join("\n") +
-        "\nReview the changes, then use --overwrite if you want to replace them.",
-    );
-  }
-  for (const file of plan) {
-    if (!options["dry-run"] && file.action !== "keep") {
-      mkdirSync(path.dirname(file.destination), { recursive: true });
-      writeFileSync(file.destination, file.content, { flag: file.action === "create" ? "wx" : "w" });
-    }
-    console.log((options["dry-run"] ? "[dry-run] " : "") + file.action + " " + file.destination);
-  }
-  const dependencies = [...new Set(items.flatMap((item) => item.dependencies))].sort();
-  const devDependencies = [...new Set(items.flatMap((item) => item.devDependencies ?? []))].sort();
-  if (dependencies.length || devDependencies.length) {
-    console.log("\nThese utilities need npm packages. Install them in your consuming project:");
-    if (dependencies.length)
-      console.log("  npm install " + dependencies.map((value) => JSON.stringify(value)).join(" "));
-    if (devDependencies.length) {
-      console.log("  npm install --save-dev " + devDependencies.map((value) => JSON.stringify(value)).join(" "));
-    }
-  }
-  for (const item of items) {
-    if (item.runtime === "node") console.log("\n" + item.name + ": requires Node.js (imports a Node.js builtin).");
-    if (item.runtime === "dom") console.log("\n" + item.name + ": requires DOM APIs and DOM TypeScript types.");
-  }
-  console.log("\n" + (options["dry-run"] ? "Planned" : "Added") + " " + items.map((item) => item.name).join(", "));
-}
-
-function main() {
-  const { values, positionals } = parseArgs({
-    options: {
-      dir: { type: "string", short: "d" },
-      "dry-run": { type: "boolean" },
-      overwrite: { type: "boolean" },
-      help: { type: "boolean", short: "h" },
-      version: { type: "boolean", short: "v" },
-    },
-    allowPositionals: true,
-  });
-  if (values.help || (!positionals.length && !values.version)) {
-    console.log(help);
-    return;
-  }
-  if (values.version) {
-    console.log(manifest.version);
-    return;
-  }
-  const [command, ...names] = positionals;
-  if (!["list", "add"].includes(command)) throw new Error("Unknown command: " + command + ". Use --help.");
-  const catalog = validateCatalog(JSON.parse(readFileSync(path.join(packageDirectory, "catalog.json"), "utf8")));
-  if (catalog.version !== manifest.version)
-    throw new Error("The catalog version does not match the package. Rebuild the CLI.");
-  if (command === "list") {
-    if (names.length || values.dir || values.overwrite || values["dry-run"]) throw new Error("Usage: hermes list");
-    for (const item of catalog.items) console.log(item.name + "\t" + item.description);
-    return;
-  }
-  if (!names.length) throw new Error("Specify at least one item. Use 'hermes list' to see available items.");
-  const items = [...new Set(names)].map((name) => {
-    const item = catalog.items.find((candidate) => candidate.name === name);
-    if (!item) throw new Error("Unknown item: " + name + ". Use 'hermes list' to see available items.");
-    return item;
-  });
-  add(items, values);
-}
-
-try {
-  main();
-} catch (error) {
-  console.error("Hermes: " + error.message);
-  process.exitCode = 1;
-}

package/lib/catalog.mjs

@@ -1,51 +0,0 @@
-const itemNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-
-export function isSourcePath(value) {
-  return (
-    typeof value === "string" &&
-    value.endsWith(".ts") &&
-    !value.includes("\\") &&
-    !value.includes("\0") &&
-    !value.includes(":") &&
-    value.split("/").every((part) => part && part !== "." && part !== "..") &&
-    !/\.(test|spec|stories|config|d)\.ts$/.test(value)
-  );
-}
-
-export function validateCatalog(catalog) {
-  if (
-    catalog?.schemaVersion !== 1 ||
-    typeof catalog.version !== "string" ||
-    !Array.isArray(catalog.items) ||
-    catalog.items.length === 0
-  ) {
-    throw new Error("Invalid Hermes catalog.");
-  }
-  const names = new Set();
-  for (const item of catalog.items) {
-    if (
-      !item ||
-      typeof item.name !== "string" ||
-      !itemNamePattern.test(item.name) ||
-      names.has(item.name) ||
-      typeof item.description !== "string" ||
-      !Array.isArray(item.files) ||
-      item.files.length === 0 ||
-      !item.files.every(isSourcePath) ||
-      new Set(item.files).size !== item.files.length ||
-      (item.runtime !== undefined && !["node", "dom"].includes(item.runtime))
-    ) {
-      throw new Error("Invalid or duplicate Hermes item: " + item?.name);
-    }
-    for (const values of [item.dependencies, item.devDependencies ?? []]) {
-      if (
-        !Array.isArray(values) ||
-        !values.every((value) => typeof value === "string" && /^[^\s]+@[^\s]+$/.test(value))
-      ) {
-        throw new Error("Invalid dependencies for " + item.name);
-      }
-    }
-    names.add(item.name);
-  }
-  return catalog;
-}