hexo-theme-stellar 1.44.0 → 2.0.0-rc.2

package/scripts/lib/doctor.js

@@ -0,0 +1,296 @@
+/* global hexo */
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const yaml = require("js-yaml");
+
+const { ConfigSchemaError, deepFreeze, parseStellarConfig } = require("./config-schema");
+const {
+  ContentConfigError,
+  parseCollectionConfig,
+  parsePageConfig,
+  validateCollectionProfileConfig,
+  validatePageProfileConfig
+} = require("./content-config");
+const { getProfileAdapter } = require("./collection-pipeline/registry");
+const {
+  createCollectionRegistry,
+  resolveContentMembership,
+  sourcePagePath
+} = require("./content-membership");
+const { FrontMatterParseError, parseFrontMatterYaml } = require("./front-matter");
+const { resolveRegions } = require("./regions");
+
+function issue(code, source, fieldPath, actualType, expected, migration) {
+  return Object.freeze({ code, source, path: fieldPath, actualType, expected, migration });
+}
+
+function relative(baseDir, file) {
+  return path.relative(baseDir, file).replace(/\\/g, "/") || ".";
+}
+
+function major(version) {
+  const match = String(version || "").match(/^(?:v)?(\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+function yamlValue(file, source, issues) {
+  try {
+    return yaml.load(fs.readFileSync(file, "utf8"), { filename: source }) || {};
+  } catch (error) {
+    issues.push(issue("invalid_yaml", source, "root", "invalid YAML", "valid YAML document", "configuration/v2"));
+    return null;
+  }
+}
+
+function frontMatterValue(file, source, issues) {
+  const content = fs.readFileSync(file, "utf8");
+  try {
+    return parseFrontMatterYaml(content, source);
+  } catch (error) {
+    if (!(error instanceof FrontMatterParseError)) throw error;
+    const actualType = error.kind === "unterminated" ? "unterminated front matter" : "invalid YAML";
+    issues.push(issue("invalid_yaml", source, "root", actualType, "valid YAML front matter", "content-schema/front-matter"));
+    return null;
+  }
+}
+
+function filesBelow(root, predicate) {
+  if (!fs.existsSync(root)) return [];
+  const result = [];
+  const visit = directory => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(file);
+      else if (entry.isFile() && predicate(file)) result.push(file);
+    }
+  };
+  visit(root);
+  return result;
+}
+
+function collectSchemaIssues(callback, issues) {
+  try {
+    return callback();
+  } catch (error) {
+    if (!(error instanceof ConfigSchemaError) && !(error instanceof ContentConfigError)) throw error;
+    issues.push(...error.issues);
+    return null;
+  }
+}
+
+function widgetCatalog(baseDir) {
+  const themeFile = path.resolve(__dirname, "../../_data/widgets.yml");
+  const siteFile = path.join(baseDir, "source/_data/widgets.yml");
+  const theme = yaml.load(fs.readFileSync(themeFile, "utf8"), { filename: themeFile }) || {};
+  if (!fs.existsSync(siteFile)) return theme;
+  const site = yaml.load(fs.readFileSync(siteFile, "utf8"), { filename: siteFile }) || {};
+  const result = { ...theme };
+  for (const [id, descriptor] of Object.entries(site)) {
+    if (descriptor == null || descriptor.length === 0) delete result[id];
+    else result[id] = { ...(result[id] || {}), ...descriptor };
+  }
+  return result;
+}
+
+function placementWarnings(options) {
+  const resolved = resolveRegions({
+    profile: options.profile,
+    defaultState: options.defaultState,
+    catalog: options.catalog,
+    layers: options.layers
+  });
+  return resolved.warnings.map(warning => Object.freeze({
+    code: warning.code,
+    severity: "warning",
+    source: options.source,
+    path: `layout=${options.profile}; region=${warning.region}`,
+    widget: warning.widget,
+    layout: warning.layout,
+    region: warning.region,
+    supported: warning.supported
+  }));
+}
+
+function runDoctor(options = {}) {
+  const baseDir = path.resolve(options.baseDir || process.cwd());
+  const nodeVersion = String(options.nodeVersion || process.versions.node);
+  const hexoVersion = String(options.hexoVersion || "");
+  const issues = [];
+  const warnings = [];
+  const catalog = widgetCatalog(baseDir);
+
+  if (major(nodeVersion) == null || major(nodeVersion) < 22) {
+    issues.push(issue("unsupported_version", "environment", "node", `string:${nodeVersion || "unknown"}`, "Node.js >= 22", "start/requirements"));
+  }
+  if (major(hexoVersion) == null || major(hexoVersion) < 8) {
+    issues.push(issue("unsupported_version", "environment", "hexo", `string:${hexoVersion || "unknown"}`, "Hexo >= 8", "start/requirements"));
+  }
+
+  const siteConfigPath = path.join(baseDir, "_config.yml");
+  let siteConfig = {};
+  if (!fs.existsSync(siteConfigPath)) {
+    issues.push(issue("missing_file", "_config.yml", "root", "missing", "Hexo site config", "start/install"));
+  } else {
+    siteConfig = yamlValue(siteConfigPath, "_config.yml", issues) || {};
+    if (siteConfig.theme !== "stellar") {
+      issues.push(issue("invalid_value", "_config.yml", "theme", typeof siteConfig.theme, "stellar", "start/install"));
+    }
+  }
+
+  const stellarConfigPath = path.join(baseDir, "_config.stellar.yml");
+  let stellarConfig = null;
+  if (fs.existsSync(stellarConfigPath)) {
+    const value = yamlValue(stellarConfigPath, "_config.stellar.yml", issues);
+    if (value != null) stellarConfig = collectSchemaIssues(() => parseStellarConfig({
+      source: "_config.stellar.yml",
+      themeConfig: value,
+      siteConfig
+    }), issues);
+  } else {
+    stellarConfig = collectSchemaIssues(() => parseStellarConfig({
+      source: "Stellar Schema defaults",
+      themeConfig: {},
+      siteConfig
+    }), issues);
+  }
+
+  if (stellarConfig) {
+    for (const [profile, profileConfig] of Object.entries(stellarConfig.profiles)) {
+      warnings.push(...placementWarnings({
+        profile,
+        source: fs.existsSync(stellarConfigPath) ? "_config.stellar.yml" : "Stellar Schema defaults",
+        catalog,
+        defaultState: stellarConfig.leftbar.defaultState,
+        layers: [stellarConfig, profileConfig]
+      }));
+    }
+  }
+
+  const collectionConfigs = new Map();
+  for (const collectionRoot of ["wiki", "topic", "notebooks"]) {
+    const directory = path.join(baseDir, "source", "_data", collectionRoot);
+    for (const file of filesBelow(directory, item => /\.ya?ml$/i.test(item))) {
+      const source = relative(baseDir, file);
+      const value = yamlValue(file, source, issues);
+      if (value != null) {
+        const contentProfile = collectionRoot === "notebooks" ? "notebook" : collectionRoot;
+        const parsed = collectSchemaIssues(() => {
+          const config = parseCollectionConfig(value, source);
+          return validateCollectionProfileConfig(config, source, contentProfile, getProfileAdapter(contentProfile).config);
+        }, issues);
+        if (parsed != null) {
+          const key = relative(path.join(baseDir, "source", "_data"), file).replace(/\.ya?ml$/i, "");
+          collectionConfigs.set(key, parsed);
+          const profile = collectionRoot === "notebooks" ? "note" : collectionRoot;
+          if (stellarConfig) warnings.push(...placementWarnings({
+            profile,
+            source,
+            catalog,
+            defaultState: stellarConfig.leftbar.defaultState,
+            layers: [
+              stellarConfig,
+              stellarConfig.profiles[profile],
+              parsed
+            ]
+          }));
+        }
+      }
+    }
+  }
+
+  const membershipRegistry = createCollectionRegistry(collectionConfigs);
+  const sourceRoot = path.join(baseDir, "source");
+  for (const file of filesBelow(sourceRoot, item => item.endsWith(".md"))) {
+    const source = relative(baseDir, file);
+    const value = frontMatterValue(file, source, issues);
+    if (value != null) {
+      const parsed = collectSchemaIssues(() => parsePageConfig(value, source), issues);
+      if (parsed == null) continue;
+      const resolved = resolveContentMembership({
+        kind: source.startsWith("source/_posts/") ? "posts" : "pages",
+        source,
+        pagePath: parsed.permalink || sourcePagePath(source),
+        config: parsed,
+        registry: membershipRegistry
+      });
+      issues.push(...resolved.issues);
+      const finalConfig = resolved.config || parsed;
+      const profile = finalConfig.collection?.profile
+        || (source.startsWith("source/_posts/") ? "post" : (parsed.layout || "page"));
+      const contentProfile = finalConfig.collection?.profile
+        || (source.startsWith("source/_posts/") ? "post" : "page");
+      collectSchemaIssues(() => validatePageProfileConfig(
+        finalConfig,
+        source,
+        contentProfile,
+        contentProfile === "page" ? null : getProfileAdapter(contentProfile).config
+      ), issues);
+      const collectionKey = finalConfig.collection
+        ? `${finalConfig.collection.profile === "notebook" ? "notebooks" : finalConfig.collection.profile}/${finalConfig.collection.id}`
+        : null;
+      const collection = collectionKey ? collectionConfigs.get(collectionKey) : null;
+      if (stellarConfig) warnings.push(...placementWarnings({
+        profile,
+        source,
+        catalog,
+        defaultState: stellarConfig.leftbar.defaultState,
+        layers: [
+          stellarConfig,
+          stellarConfig.profiles[profile],
+          collection,
+          finalConfig
+        ]
+      }));
+    }
+  }
+
+  return deepFreeze({
+    ok: issues.length === 0,
+    environment: {
+      node: nodeVersion,
+      hexo: hexoVersion,
+      baseDir
+    },
+    checked: {
+      themeConfig: fs.existsSync(stellarConfigPath),
+      collections: filesBelow(path.join(baseDir, "source", "_data"), item => /\/(wiki|topic|notebooks)\/.*\.ya?ml$/i.test(item)).length,
+      pages: filesBelow(sourceRoot, item => item.endsWith(".md")).length
+    },
+    issues: issues.map(item => Object.freeze({ ...item })),
+    warnings
+  });
+}
+
+function formatDoctorText(result) {
+  const lines = [
+    `Stellar doctor: ${result.ok ? "PASS" : "FAIL"}`,
+    `Node.js: ${result.environment.node}`,
+    `Hexo: ${result.environment.hexo}`,
+    `Checked: ${result.checked.themeConfig ? "theme config" : "Schema defaults"}, ${result.checked.collections} collection file(s), ${result.checked.pages} Markdown file(s)`
+  ];
+  if (result.issues.length > 0) {
+    lines.push(`Issues (${result.issues.length}):`);
+    for (const item of result.issues) {
+      lines.push(`- ${item.source}: ${item.path}; actual=${item.actualType}; expected=${item.expected}; migration=${item.migration}`);
+    }
+  }
+  if (result.warnings.length > 0) {
+    lines.push(`Warnings (${result.warnings.length}):`);
+    for (const item of result.warnings) {
+      lines.push(`- ${item.source}: Widget ${item.widget} (layout=${item.layout}) does not support ${item.region}; supported=${item.supported.join(",") || "none"}; skipped`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function formatDoctorJson(result) {
+  return JSON.stringify(result, null, 2);
+}
+
+module.exports = {
+  formatDoctorJson,
+  formatDoctorText,
+  runDoctor
+};

package/scripts/lib/front-matter.js

@@ -0,0 +1,29 @@
+/* global hexo */
+"use strict";
+
+const yaml = require("js-yaml");
+
+class FrontMatterParseError extends Error {
+  constructor(kind, source, message) {
+    super(`${source}: ${message}`);
+    this.name = "FrontMatterParseError";
+    this.kind = kind;
+    this.source = source;
+  }
+}
+
+function parseFrontMatterYaml(content, source) {
+  if (!/^\uFEFF?---\r?\n/.test(content)) return null;
+  const match = content.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) throw new FrontMatterParseError("unterminated", source, "Front Matter 缺少结束分隔符");
+  try {
+    return yaml.load(match[1], { filename: source }) || {};
+  } catch (error) {
+    throw new FrontMatterParseError("invalid_yaml", source, `Front Matter YAML 无效（${error.message}）`);
+  }
+}
+
+module.exports = {
+  FrontMatterParseError,
+  parseFrontMatterYaml
+};

package/scripts/lib/hero-effect-registry.js

@@ -0,0 +1,262 @@
+"use strict";
+
+const INTERNAL = require("./internal-constants");
+const OPTION_TYPES = new Set([
+  "boolean",
+  "enum",
+  "hex_color",
+  "hex_color_array",
+  "nullable_positive_number",
+  "nullable_string",
+  "number",
+  "number_array"
+]);
+
+function deepFreeze(value) {
+  if (value == null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.values(value).forEach(deepFreeze);
+  return Object.freeze(value);
+}
+
+function optionMatches(rule, value) {
+  if (rule.type === "boolean") return typeof value === "boolean";
+  if (rule.type === "number") return typeof value === "number" && Number.isFinite(value);
+  if (rule.type === "nullable_positive_number") {
+    return value === null || (typeof value === "number" && Number.isFinite(value) && value > 0);
+  }
+  if (rule.type === "nullable_string") return value === null || (typeof value === "string" && value.trim().length > 0);
+  if (rule.type === "number_array") {
+    return Array.isArray(value) && value.every(item => typeof item === "number" && Number.isFinite(item));
+  }
+  if (rule.type === "enum") return typeof value === "string" && rule.values.includes(value);
+  if (rule.type === "hex_color") return typeof value === "string" && /^#?[a-f\d]{6}$/i.test(value);
+  if (rule.type === "hex_color_array") {
+    return Array.isArray(value)
+      && value.length >= 1
+      && value.length <= 8
+      && value.every(item => typeof item === "string" && /^#?[a-f\d]{6}$/i.test(item));
+  }
+  return false;
+}
+
+function defineHeroEffects(definitions) {
+  const ids = new Set();
+  for (const definition of definitions) {
+    if (typeof definition.id !== "string" || !/^[a-z][a-z0-9-]*$/.test(definition.id)) {
+      throw new TypeError("[stellar hero effects] id is invalid");
+    }
+    if (ids.has(definition.id)) throw new TypeError(`[stellar hero effects] duplicate id ${definition.id}`);
+    ids.add(definition.id);
+    if (typeof definition.label !== "string" || definition.label.length === 0) {
+      throw new TypeError(`[stellar hero effects] ${definition.id} label is invalid`);
+    }
+    if (typeof definition.module !== "string" || !definition.module.startsWith("/js/runtime/hero-effects/") || !definition.module.endsWith(".js")) {
+      throw new TypeError(`[stellar hero effects] ${definition.id} module is invalid`);
+    }
+    if (definition.options == null || typeof definition.options !== "object" || Array.isArray(definition.options)) {
+      throw new TypeError(`[stellar hero effects] ${definition.id} options are invalid`);
+    }
+    if (definition.defaults == null || typeof definition.defaults !== "object" || Array.isArray(definition.defaults)) {
+      throw new TypeError(`[stellar hero effects] ${definition.id} defaults are invalid`);
+    }
+    for (const [key, rule] of Object.entries(definition.options)) {
+      if (!rule || !OPTION_TYPES.has(rule.type)) {
+        throw new TypeError(`[stellar hero effects] ${definition.id}.${key} option rule is invalid`);
+      }
+      if (rule.type === "enum" && (!Array.isArray(rule.values) || rule.values.length === 0)) {
+        throw new TypeError(`[stellar hero effects] ${definition.id}.${key} enum is empty`);
+      }
+      if (!Object.prototype.hasOwnProperty.call(definition.defaults, key) || !optionMatches(rule, definition.defaults[key])) {
+        throw new TypeError(`[stellar hero effects] ${definition.id}.${key} default is invalid`);
+      }
+    }
+    const unknownDefault = Object.keys(definition.defaults).find(key => !definition.options[key]);
+    if (unknownDefault) throw new TypeError(`[stellar hero effects] ${definition.id}.${unknownDefault} default is not declared`);
+    if (typeof definition.presentation !== "function") {
+      throw new TypeError(`[stellar hero effects] ${definition.id} presentation is invalid`);
+    }
+  }
+  return deepFreeze(definitions.slice());
+}
+
+const LIGHT_RAYS_ORIGINS = Object.freeze([
+  "top-left",
+  "top-center",
+  "top-right",
+  "left",
+  "right",
+  "bottom-left",
+  "bottom-center",
+  "bottom-right"
+]);
+
+const DEFINITIONS = defineHeroEffects([
+  {
+    id: "galaxy",
+    label: "Galaxy",
+    module: INTERNAL.assets.heroEffects.galaxy,
+    options: {
+      focal: { type: "number_array" },
+      rotation: { type: "number_array" },
+      starSpeed: { type: "number" },
+      density: { type: "number" },
+      hueShift: { type: "number" },
+      disableAnimation: { type: "boolean" },
+      speed: { type: "number" },
+      mouseInteraction: { type: "boolean" },
+      glowIntensity: { type: "number" },
+      saturation: { type: "number" },
+      mouseRepulsion: { type: "boolean" },
+      repulsionStrength: { type: "number" },
+      twinkleIntensity: { type: "number" },
+      rotationSpeed: { type: "number" },
+      autoCenterRepulsion: { type: "number" },
+      transparent: { type: "boolean" }
+    },
+    defaults: {
+      focal: [0.5, 0.5],
+      rotation: [1, 0],
+      starSpeed: 2,
+      density: 2,
+      hueShift: 140,
+      disableAnimation: false,
+      speed: 0.5,
+      mouseInteraction: true,
+      glowIntensity: 0.2,
+      saturation: 0.1,
+      mouseRepulsion: true,
+      twinkleIntensity: 0.1,
+      rotationSpeed: 0.1,
+      repulsionStrength: 0.1,
+      autoCenterRepulsion: 0,
+      transparent: true
+    },
+    presentation() {
+      return { background: "#000000" };
+    }
+  },
+  {
+    id: "light-rays",
+    label: "Light Rays",
+    module: INTERNAL.assets.heroEffects.lightRays,
+    options: {
+      raysOrigin: { type: "enum", values: LIGHT_RAYS_ORIGINS },
+      raysColor: { type: "hex_color" },
+      raysSpeed: { type: "number" },
+      lightSpread: { type: "number" },
+      rayLength: { type: "number" },
+      pulsating: { type: "boolean" },
+      fadeDistance: { type: "number" },
+      saturation: { type: "number" },
+      followMouse: { type: "boolean" },
+      mouseInfluence: { type: "number" },
+      noiseAmount: { type: "number" },
+      distortion: { type: "number" },
+      lightMode: { type: "boolean" }
+    },
+    defaults: {
+      raysOrigin: "top-center",
+      raysColor: "#ffffff",
+      raysSpeed: 1,
+      lightSpread: 0.5,
+      rayLength: 3,
+      pulsating: false,
+      fadeDistance: 1,
+      saturation: 1,
+      followMouse: true,
+      mouseInfluence: 0.1,
+      noiseAmount: 0,
+      distortion: 0,
+      lightMode: false
+    },
+    presentation(options) {
+      return { background: options?.lightMode === true ? "#ffffff" : "#000000" };
+    }
+  },
+  {
+    id: "ferrofluid",
+    label: "Ferrofluid",
+    module: INTERNAL.assets.heroEffects.ferrofluid,
+    options: {
+      colors: { type: "hex_color_array" },
+      backgroundColor: { type: "hex_color" },
+      speed: { type: "number" },
+      scale: { type: "number" },
+      turbulence: { type: "number" },
+      fluidity: { type: "number" },
+      rimWidth: { type: "number" },
+      sharpness: { type: "number" },
+      shimmer: { type: "number" },
+      glow: { type: "number" },
+      flowDirection: { type: "enum", values: ["up", "down", "left", "right"] },
+      opacity: { type: "number" },
+      mouseInteraction: { type: "boolean" },
+      mouseStrength: { type: "number" },
+      mouseRadius: { type: "number" },
+      mouseDampening: { type: "number" },
+      paused: { type: "boolean" },
+      dpr: { type: "nullable_positive_number" },
+      mixBlendMode: { type: "nullable_string" }
+    },
+    defaults: {
+      colors: ["#ffffff", "#ffffff", "#ffffff"],
+      backgroundColor: "#03010A",
+      speed: 0.5,
+      scale: 1.6,
+      turbulence: 1,
+      fluidity: 0.1,
+      rimWidth: 0.2,
+      sharpness: 2.5,
+      shimmer: 1.5,
+      glow: 2,
+      flowDirection: "down",
+      opacity: 1,
+      mouseInteraction: true,
+      mouseStrength: 1,
+      mouseRadius: 0.35,
+      mouseDampening: 0.15,
+      paused: false,
+      dpr: null,
+      mixBlendMode: null
+    },
+    presentation(options) {
+      const color = typeof options?.backgroundColor === "string" ? options.backgroundColor : "#03010A";
+      return { background: color.startsWith("#") ? color : `#${color}` };
+    }
+  }
+]);
+
+const BY_ID = new Map(DEFINITIONS.map(definition => [definition.id, definition]));
+const HERO_EFFECT_IDS = Object.freeze(DEFINITIONS.map(definition => definition.id));
+
+function getHeroEffectDefinition(id) {
+  return BY_ID.get(id) || null;
+}
+
+function heroEffectDefinitions() {
+  return DEFINITIONS.slice();
+}
+
+function heroEffectRuntimeConfig() {
+  return Object.fromEntries(DEFINITIONS.map(definition => [definition.id, {
+    module: definition.module,
+    defaults: definition.defaults
+  }]));
+}
+
+function projectHeroEffect(effect) {
+  const definition = getHeroEffectDefinition(effect?.type);
+  if (!definition) return effect;
+  return {
+    ...effect,
+    presentation: definition.presentation(effect.options || {})
+  };
+}
+
+module.exports = {
+  HERO_EFFECT_IDS,
+  getHeroEffectDefinition,
+  heroEffectDefinitions,
+  heroEffectRuntimeConfig,
+  projectHeroEffect
+};