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

package/scripts/lib/new-note.js

@@ -0,0 +1,172 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const yaml = require("js-yaml");
+
+const { resolveInside } = require("./safe-path");
+const {
+  parseCollectionConfig,
+  parsePageConfig,
+  validateCollectionProfileConfig,
+  validatePageProfileConfig
+} = require("./content-config");
+const { getProfileAdapter } = require("./collection-pipeline/registry");
+const { parseFrontMatterYaml } = require("./front-matter");
+const { deepFreeze } = require("../schema/schema-utils");
+
+class NewNoteError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "NewNoteError";
+    Object.assign(this, details);
+  }
+}
+
+class NewNoteConflictError extends NewNoteError {
+  constructor(target) {
+    super(`Stellar new note 拒绝覆盖已有文件：${target}`, { target });
+    this.name = "NewNoteConflictError";
+  }
+}
+
+function formatDate(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) throw new NewNoteError("generatedAt 必须是合法日期");
+  const pad = number => String(number).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+function safeSegment(value, label) {
+  const segment = typeof value === "string" ? value.trim() : "";
+  if (segment.length === 0) throw new NewNoteError(`${label} 必须是非空字符串`);
+  const hasControl = Array.from(segment).some(character => character.charCodeAt(0) < 32);
+  if (segment === "." || segment === ".." || /[<>:"/\\|?*]/.test(segment) || hasControl) {
+    throw new NewNoteError(`${label} 不能包含路径或文件系统保留字符`);
+  }
+  return segment;
+}
+
+function normalizeTags(value) {
+  const values = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+  const tags = [];
+  const seen = new Set();
+  for (const item of values) {
+    const tag = typeof item === "string" ? item.trim() : "";
+    if (tag.length === 0 || seen.has(tag)) continue;
+    if (Array.from(tag).some(character => character.charCodeAt(0) < 32)) {
+      throw new NewNoteError("--tags 不能包含换行或空字符");
+    }
+    seen.add(tag);
+    tags.push(tag);
+  }
+  return Object.freeze(tags);
+}
+
+function notebookConfigFile(sourceDir, notebook) {
+  const candidates = ["yml", "yaml"].map(extension => (
+    path.join(sourceDir, "_data", "notebooks", `${notebook}.${extension}`)
+  ));
+  return candidates.find(file => fs.existsSync(file)) || candidates[0];
+}
+
+function renderFrontMatter({ title, tags, generatedAt }) {
+  const lines = [
+    "---",
+    `date: ${formatDate(generatedAt)}`,
+    `title: ${JSON.stringify(title)}`
+  ];
+  if (tags.length > 0) {
+    lines.push("tags:", ...tags.map(tag => `  - ${JSON.stringify(tag)}`));
+  }
+  lines.push("---", "", "");
+  return lines.join("\n");
+}
+
+function buildNewNotePlan(options = {}) {
+  const baseDir = path.resolve(options.baseDir || process.cwd());
+  const sourceDir = path.resolve(options.sourceDir || path.join(baseDir, "source"));
+  const notebook = safeSegment(options.notebook, "--notebook");
+  const title = safeSegment(options.title, "--title");
+  const tags = normalizeTags(options.tags);
+  const configFile = notebookConfigFile(sourceDir, notebook);
+  if (!fs.existsSync(configFile) || !fs.statSync(configFile).isFile()) {
+    throw new NewNoteError(`未知 Notebook：${notebook}；缺少 ${path.relative(baseDir, configFile)}`);
+  }
+  let rawCollection;
+  try {
+    rawCollection = yaml.load(fs.readFileSync(configFile, "utf8"), { filename: configFile }) || {};
+  } catch (error) {
+    throw new NewNoteError(`${configFile}: Notebook YAML 无效（${error.message}）`);
+  }
+  const collectionSource = path.relative(baseDir, configFile).replace(/\\/g, "/");
+  validateCollectionProfileConfig(
+    parseCollectionConfig(rawCollection, collectionSource),
+    collectionSource,
+    "notebook",
+    getProfileAdapter("notebook").config
+  );
+
+  const target = path.posix.join("source", "notebooks", notebook, `${title}.md`);
+  const output = resolveInside(baseDir, target, `stellar new note: ${target}`);
+  const content = renderFrontMatter({ title, tags, generatedAt: options.generatedAt ?? new Date() });
+  validatePageProfileConfig(
+    parsePageConfig(parseFrontMatterYaml(content, target) || {}, target),
+    target,
+    "notebook",
+    getProfileAdapter("notebook").config
+  );
+  if (fs.existsSync(output.absolute)) throw new NewNoteConflictError(target);
+  return deepFreeze({
+    notebook,
+    title,
+    tags,
+    baseDir,
+    target,
+    outputPath: output.absolute,
+    content
+  });
+}
+
+function writeNewNotePlan(plan) {
+  const output = resolveInside(plan.baseDir, plan.target, `write: ${plan.target}`);
+  if (output.absolute !== path.resolve(plan.outputPath)) {
+    throw new NewNoteError(`${plan.target}: outputPath 与计划根目录不一致`);
+  }
+  if (fs.existsSync(plan.outputPath)) throw new NewNoteConflictError(plan.target);
+  const createdDirectories = [];
+  let directory = path.dirname(plan.outputPath);
+  while (!fs.existsSync(directory)) {
+    createdDirectories.push(directory);
+    directory = path.dirname(directory);
+  }
+  try {
+    fs.mkdirSync(path.dirname(plan.outputPath), { recursive: true });
+    fs.writeFileSync(plan.outputPath, plan.content, { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if (fs.existsSync(plan.outputPath)) fs.unlinkSync(plan.outputPath);
+    for (const created of createdDirectories) {
+      if (fs.existsSync(created) && fs.readdirSync(created).length === 0) fs.rmdirSync(created);
+    }
+    if (error instanceof NewNoteError) throw error;
+    throw new NewNoteError(`Stellar new note 写入失败，已回滚本次创建的文件（${error.message}）`);
+  }
+  return plan;
+}
+
+function formatNewNotePlan(plan, options = {}) {
+  return [
+    options.dryRun ? "Stellar new note dry-run" : "Stellar new note plan",
+    `  notebook ${plan.notebook}`,
+    `  create ${plan.target}`
+  ].join("\n");
+}
+
+module.exports = {
+  NewNoteConflictError,
+  NewNoteError,
+  buildNewNotePlan,
+  formatNewNotePlan,
+  normalizeTags,
+  writeNewNotePlan
+};

package/scripts/lib/page-view-model-registry.js

@@ -0,0 +1,103 @@
+"use strict";
+
+const profileInputs = new Map();
+const profileBases = new Map();
+const relatedItems = new Map();
+const pageConfigs = new Map();
+
+function keysForPage(page) {
+  return [page?.source, page?.path, page?._id]
+    .filter(value => typeof value === "string" && value.length > 0);
+}
+
+function resetPageViewModelRegistry() {
+  profileInputs.clear();
+  profileBases.clear();
+  relatedItems.clear();
+  pageConfigs.clear();
+}
+
+function setValue(store, page, value) {
+  for (const key of keysForPage(page)) store.set(key, value);
+}
+
+function getValue(store, page) {
+  for (const key of keysForPage(page)) {
+    if (store.has(key)) return store.get(key);
+  }
+  return null;
+}
+
+function setPageConfig(page, config) {
+  setValue(pageConfigs, page, config);
+}
+
+function getPageConfig(page) {
+  return getValue(pageConfigs, page);
+}
+
+function profileStore(stores, profile) {
+  if (!stores.has(profile)) stores.set(profile, new Map());
+  return stores.get(profile);
+}
+
+function setProfileViewModelInput(profile, page, input) {
+  setValue(profileStore(profileInputs, profile), page, input);
+}
+
+function getProfileViewModelInput(profile, page) {
+  return getValue(profileStore(profileInputs, profile), page);
+}
+
+function setProfileViewModelBase(profile, page, base) {
+  setValue(profileStore(profileBases, profile), page, base);
+}
+
+function getProfileViewModelBase(profile, page) {
+  return getValue(profileStore(profileBases, profile), page);
+}
+
+function getPostViewModelInput(page) {
+  return getProfileViewModelInput("post", page);
+}
+
+function getTopicViewModelInput(page) {
+  return getProfileViewModelInput("topic", page);
+}
+
+function getTopicViewModelBase(page) {
+  return getProfileViewModelBase("topic", page);
+}
+
+function getNotebookViewModelInput(page) {
+  return getProfileViewModelInput("notebook", page);
+}
+
+function getNotebookViewModelBase(page) {
+  return getProfileViewModelBase("notebook", page);
+}
+
+function setRelatedItems(page, items) {
+  setValue(relatedItems, page, Object.freeze(items.slice()));
+}
+
+function getRelatedItems(page) {
+  return getValue(relatedItems, page) || [];
+}
+
+module.exports = {
+  getProfileViewModelBase,
+  getProfileViewModelInput,
+  getPageConfig,
+  getNotebookViewModelBase,
+  getNotebookViewModelInput,
+  getPostViewModelInput,
+  getRelatedItems,
+  getTopicViewModelBase,
+  getTopicViewModelInput,
+  resetPageViewModelRegistry,
+  setPageConfig,
+  setProfileViewModelBase,
+  setProfileViewModelInput,
+  setRelatedItems
+};

package/scripts/lib/regions.js

@@ -0,0 +1,132 @@
+"use strict";
+
+const { resolveRegionWidgets } = require("./widget-registry");
+
+const REGION_IDS = Object.freeze(["topbar", "leftbar", "rightbar"]);
+
+function clone(value) {
+  if (Array.isArray(value)) return value.map(clone);
+  if (value == null || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, clone(child)]));
+}
+
+function freeze(value) {
+  if (value == null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.values(value).forEach(freeze);
+  return Object.freeze(value);
+}
+
+function regionLayer(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+
+function cascadeRegion(layers, region) {
+  let widgets = [];
+  for (const layer of layers) {
+    const current = regionLayer(layer?.[region]);
+    if (!current) continue;
+    if (Array.isArray(current.widgets)) widgets = current.widgets.map(clone);
+  }
+  return widgets;
+}
+
+function mergeBrand(base, override, sources = null) {
+  if (override == null) return clone(base);
+  if (override === false) return false;
+  if (regionLayer(override) == null) return clone(base);
+  const requestedSource = typeof override.source === "string" ? override.source : null;
+  const sourceBrand = requestedSource && sources && Object.prototype.hasOwnProperty.call(sources, requestedSource)
+    ? sources[requestedSource]
+    : undefined;
+  const result = sourceBrand !== undefined
+    ? (regionLayer(sourceBrand) == null ? {} : clone(sourceBrand))
+    : (regionLayer(base) == null ? {} : clone(base));
+  for (const [key, value] of Object.entries(override)) {
+    if (key === "image" && regionLayer(value)) {
+      result.image = { ...(regionLayer(result.image) ? result.image : {}), ...clone(value) };
+    } else {
+      result[key] = clone(value);
+    }
+  }
+  return result;
+}
+
+function resolveRegion(layers, region, options = {}) {
+  const result = {
+    enabled: region !== "topbar",
+    widgets: []
+  };
+  if (["topbar", "leftbar"].includes(region)) {
+    result.brand = false;
+    result.menu = [];
+  }
+  if (region === "leftbar") result.footer = { actions: [] };
+  for (const layer of layers) {
+    const current = regionLayer(layer?.[region]);
+    if (!current) continue;
+    if (typeof current.enabled === "boolean") result.enabled = current.enabled;
+    if (["topbar", "leftbar"].includes(region) && current.brand !== undefined) {
+      result.brand = mergeBrand(result.brand, current.brand, region === "leftbar" ? options.brandSources : null);
+    }
+    if (["topbar", "leftbar"].includes(region) && Array.isArray(current.menu)) {
+      result.menu = current.menu.map(clone);
+    }
+    if (region === "leftbar" && Array.isArray(current.footer?.actions)) {
+      result.footer.actions = current.footer.actions.map(clone);
+    }
+    if (Array.isArray(current.widgets)) result.widgets = current.widgets.map(clone);
+  }
+  return result;
+}
+
+function resolveLeftbar(layers, options = {}) {
+  return resolveRegion(layers, "leftbar", options);
+}
+
+function cascadeRegions(layers, options = {}) {
+  const regions = {};
+  for (const region of REGION_IDS) {
+    regions[region] = resolveRegion(layers, region, options);
+  }
+  return freeze(regions);
+}
+
+function resolveRegions(options = {}) {
+  const layers = Array.isArray(options.layers) ? options.layers : [];
+  const resolvedRegions = {};
+  const warnings = [];
+  for (const region of REGION_IDS) {
+    const state = resolveRegion(layers, region, options);
+    const widgets = state.enabled ? state.widgets : [];
+    const resolved = resolveRegionWidgets(widgets, options.catalog || {}, {
+      region,
+      profile: options.profile,
+      contentOnly: region === "leftbar"
+    });
+    resolvedRegions[region] = {
+      widgets: resolved.instances,
+      enabled: state.enabled,
+      ...(["topbar", "leftbar"].includes(region) ? {
+        brand: clone(state.brand),
+        menu: clone(state.menu)
+      } : {}),
+      ...(region === "leftbar" ? {
+        defaultState: options.defaultState || "expanded",
+        footer: clone(state.footer)
+      } : {})
+    };
+    warnings.push(...resolved.warnings);
+  }
+  return freeze({ ...resolvedRegions, warnings });
+}
+
+module.exports = {
+  REGION_IDS,
+  cascadeRegion,
+  cascadeRegions,
+  mergeBrand,
+  resolveLeftbar,
+  resolveRegion,
+  resolveRegions
+};

package/scripts/lib/runtime-data.js

@@ -0,0 +1,23 @@
+/* global hexo */
+"use strict";
+
+function ensureRuntimeData(ctx) {
+  ctx.stellar ||= {};
+  ctx.stellar.data ||= {};
+  return ctx.stellar.data;
+}
+
+function runtimeDataAt(ctx, path) {
+  const parts = typeof path === "string" && path.length > 0 ? path.split(".") : [];
+  let value = ctx.stellar?.data;
+  for (const part of parts) {
+    if (value == null || !Object.prototype.hasOwnProperty.call(value, part)) return undefined;
+    value = value[part];
+  }
+  return value;
+}
+
+module.exports = {
+  ensureRuntimeData,
+  runtimeDataAt
+};

package/scripts/lib/safe-path.js

@@ -0,0 +1,44 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+function safeRelativePath(value, source) {
+  if (typeof value !== "string" || value.length === 0) throw new TypeError(`${source}: 路径必须是非空相对路径`);
+  const unixPath = value.replace(/\\/g, "/");
+  const normalized = path.posix.normalize(unixPath);
+  const hasDriveRoot = /^[A-Za-z]:/.test(unixPath);
+  if (path.isAbsolute(value) || path.posix.isAbsolute(unixPath) || hasDriveRoot || unixPath.split("/").includes("..") || /^\.\/?$/.test(normalized)) {
+    throw new TypeError(`${source}: 路径不能逃逸根目录（${value}）`);
+  }
+  return normalized;
+}
+
+function resolveInside(root, relative, source) {
+  const safe = safeRelativePath(relative, source);
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, safe);
+  if (resolved !== resolvedRoot && !resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new TypeError(`${source}: 路径不能逃逸根目录（${relative}）`);
+  }
+  const physicalRoot = fs.realpathSync(resolvedRoot);
+  let ancestor = resolved;
+  while (!fs.existsSync(ancestor)) {
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor) break;
+    ancestor = parent;
+  }
+  const physicalAncestor = fs.realpathSync(ancestor);
+  if (physicalAncestor !== physicalRoot && !physicalAncestor.startsWith(`${physicalRoot}${path.sep}`)) {
+    throw new TypeError(`${source}: 路径经过根目录外的符号链接（${relative}）`);
+  }
+  if (fs.existsSync(resolved)) {
+    const physicalResolved = fs.realpathSync(resolved);
+    if (physicalResolved !== physicalRoot && !physicalResolved.startsWith(`${physicalRoot}${path.sep}`)) {
+      throw new TypeError(`${source}: 路径经过根目录外的符号链接（${relative}）`);
+    }
+  }
+  return { relative: safe, absolute: resolved };
+}
+
+module.exports = { resolveInside, safeRelativePath };

package/scripts/lib/search-domain.js

@@ -0,0 +1,59 @@
+"use strict";
+
+const COLLECTION_PROFILES = new Set(["wiki", "notebook", "topic"]);
+
+function collectionDomain(profile, id) {
+  if (typeof profile !== "string" || profile.length === 0) return null;
+  if (typeof id !== "string" || id.length === 0) return null;
+  return `${profile}:${id}`;
+}
+
+function indexDomains(page, config) {
+  const domains = [];
+  if (page?.layout === "post") domains.push("blog");
+  const collection = config?.collection;
+  const domain = COLLECTION_PROFILES.has(collection?.profile)
+    ? collectionDomain(collection.profile, collection.id)
+    : null;
+  if (domain && !domains.includes(domain)) domains.push(domain);
+  return domains;
+}
+
+function scopeAllows(indexScope, contentType) {
+  return indexScope === "all" || indexScope === contentType;
+}
+
+function collectionScope(collection, indexScope) {
+  const profile = collection?.profile;
+  if (!COLLECTION_PROFILES.has(profile)) return null;
+  const domain = collectionDomain(profile, collection?.id);
+  if (!domain) return null;
+  const contentType = profile === "topic" ? "post" : "page";
+  if (!scopeAllows(indexScope, contentType)) return null;
+  const label = collection?.identity?.name || collection?.name || collection.id;
+  const options = profile === "topic" && scopeAllows(indexScope, "post")
+    ? ["blog", domain]
+    : [domain];
+  return { current: domain, label, options };
+}
+
+function resolveSearchScope(input = {}) {
+  const indexScope = ["all", "post", "page"].includes(input.indexScope)
+    ? input.indexScope
+    : "all";
+  const collection = input.viewModel?.collection || input.collection || null;
+  const scoped = collectionScope(collection, indexScope);
+  if (scoped) return scoped;
+  if (collection?.profile === "post" || input.blogAggregate === true) {
+    if (!scopeAllows(indexScope, "post")) return null;
+    return { current: "blog", label: null, options: ["blog"] };
+  }
+  return null;
+}
+
+module.exports = {
+  collectionDomain,
+  indexDomains,
+  resolveSearchScope,
+  scopeAllows
+};

package/scripts/lib/seo.js

@@ -23,25 +23,25 @@ function firstContentImage(content) {
 }
 
 /**
- * 构建文章图片数组（顺序：cover → banner → photos → 正文首图 → 默认封面）。
+ * 构建文章图片数组（顺序：cover → banner.image → photos → 正文首图 → 默认封面）。
  * @param {Object} opts
- * @param {string} opts.cover
- * @param {string} opts.banner
+ * @param {string} opts.cardCover
+ * @param {string} opts.bannerImage
  * @param {Array} opts.photos
  * @param {string} opts.content
- * @param {string} opts.defaultCover 主题默认封面（theme.default.cover）
+ * @param {string} opts.defaultCover 主题默认封面（fallbacks.cover）
  * @returns {Array<string>}
  */
 function postImages(opts) {
-  const cover = opts.cover || '';
-  const banner = opts.banner || '';
+  const cardCover = opts.cardCover || '';
+  const bannerImage = opts.bannerImage || '';
   const photos = Array.isArray(opts.photos) ? opts.photos.slice() : [];
   const defaultCover = opts.defaultCover || '';
   const images = photos;
-  if (cover) {
-    images.unshift(cover);
-  } else if (banner) {
-    images.unshift(banner);
+  if (cardCover) {
+    images.unshift(cardCover);
+  } else if (bannerImage) {
+    images.unshift(bannerImage);
   }
   if (images.length === 0) {
     const first = firstContentImage(opts.content);

package/scripts/lib/service-provider.js

@@ -0,0 +1,12 @@
+/* global hexo */
+
+"use strict";
+
+function resolveServiceProvider(service) {
+  const provider = service?.provider;
+  if (provider == null) return null;
+  if (typeof service !== "object" || Array.isArray(service)) return null;
+  return Object.prototype.hasOwnProperty.call(service, provider) ? service[provider] : null;
+}
+
+module.exports = { resolveServiceProvider };

package/scripts/lib/settings.js

@@ -0,0 +1,16 @@
+"use strict";
+
+const TOKEN_PATTERN = /\{(?:hexo|theme)\.[a-z]+\}/g;
+
+function replaceSettingsTokens(value, tokens) {
+  const source = typeof value === "string" ? value : "";
+  return source.replace(TOKEN_PATTERN, token => Object.prototype.hasOwnProperty.call(tokens, token) ? String(tokens[token]) : token);
+}
+
+function routeIdentity(value) {
+  let route = String(value || "").trim().replace(/^\/+|\/+$/g, "");
+  route = route.replace(/\/index\.html$/i, "");
+  return route || "<root>";
+}
+
+module.exports = { replaceSettingsTokens, routeIdentity };