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

package/scripts/lib/content-config.js

@@ -0,0 +1,157 @@
+/* global hexo */
+"use strict";
+
+const {
+  ConfigSchemaError,
+  formatIssue,
+  isPlainObject,
+  parseConfigSchema
+} = require("./config-schema");
+const {
+  COLLECTION_CONFIG_SCHEMA,
+  FRONT_MATTER_CONFIG_SCHEMA
+} = require("../schema/content-config-schema");
+
+const CONTENT_MODEL_FIELDS = Object.freeze({
+  article: Object.freeze(["style", "paragraphIndent", "author", "aiLabel"]),
+  banner: Object.freeze(["enabled", "image", "avatar", "headline", "tagline"]),
+  brand: Object.freeze(["image", "name", "tagline", "href"]),
+  brandImage: Object.freeze(["src", "variant"]),
+  comments: Object.freeze(["enabled", "title", "id", "provider", "options"]),
+  footer: Object.freeze(["references", "license", "share", "showTags"]),
+  navigation: Object.freeze(["menu", "breadcrumb"]),
+  regionIds: Object.freeze(["topbar", "leftbar", "rightbar"]),
+  region: Object.freeze(["enabled", "brand", "menu", "footer", "widgets"]),
+  source: Object.freeze(["repository", "branch"]),
+  visibility: Object.freeze(["listed", "searchable"])
+});
+
+class ContentConfigError extends Error {
+  constructor(issues) {
+    super(`Stellar v2 内容配置校验失败：\n${issues.map(issue => `- ${typeof issue === "string" ? issue : formatIssue(issue)}`).join("\n")}`);
+    this.name = "ContentConfigError";
+    this.issues = issues;
+  }
+}
+
+function contentError(error) {
+  if (!(error instanceof ConfigSchemaError)) throw error;
+  throw new ContentConfigError(error.issues);
+}
+
+function parseCollectionConfig(config, source = "<collection>", options = {}) {
+  try {
+    return parseConfigSchema(COLLECTION_CONFIG_SCHEMA, config, {
+      ...options,
+      source,
+      isFatalIssue(currentIssue) {
+        return currentIssue.path === "name" || options.isFatalIssue?.(currentIssue);
+      }
+    });
+  } catch (error) {
+    return contentError(error);
+  }
+}
+
+function parsePageConfig(config, source = "<page>", options = {}) {
+  try {
+    return parseConfigSchema(FRONT_MATTER_CONFIG_SCHEMA, config, {
+      ...options,
+      source,
+      isFatalIssue(currentIssue) {
+        return /^collection\.(?:profile|id)$/.test(currentIssue.path) || options.isFatalIssue?.(currentIssue);
+      }
+    });
+  } catch (error) {
+    return contentError(error);
+  }
+}
+
+function validateObjectInput(config, source) {
+  if (isPlainObject(config)) return config;
+  const issue = Object.freeze({
+    code: "invalid_type",
+    source,
+    path: "root",
+    actualType: Array.isArray(config) ? "array" : config === null ? "null" : typeof config,
+    expected: "object",
+    migration: "configuration/v2"
+  });
+  throw new ContentConfigError([issue]);
+}
+
+function validateThemeConfig(config, source = "<theme>") {
+  return validateObjectInput(config, source);
+}
+
+function hasOwn(value, key) {
+  return value != null && Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function unsupportedProfileField(source, path, profile) {
+  return Object.freeze({
+    code: "invalid_value",
+    source,
+    path,
+    actualType: "declared field",
+    expected: `field supported by the ${profile} profile`,
+    migration: "content-schema/profile-capabilities"
+  });
+}
+
+function validateCollectionProfileConfig(config, source, profile, capabilities) {
+  const policy = capabilities?.collection;
+  if (!policy) throw new ContentConfigError([unsupportedProfileField(source, "root", profile)]);
+  const issues = [];
+  if (hasOwn(config, "hero") && policy.hero !== true) {
+    issues.push(unsupportedProfileField(source, "hero", profile));
+  }
+  if (hasOwn(config?.route, "start") && policy.routeStart !== true) {
+    issues.push(unsupportedProfileField(source, "route.start", profile));
+  }
+  if (hasOwn(config?.navigation, "tree") && policy.navigationTree !== true) {
+    issues.push(unsupportedProfileField(source, "navigation.tree", profile));
+  }
+  const listingFields = new Set(policy.listing || []);
+  for (const field of Object.keys(config?.listing || {})) {
+    if (!listingFields.has(field)) {
+      issues.push(unsupportedProfileField(source, `listing.${field.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`)}`, profile));
+    }
+  }
+  if (issues.length > 0) throw new ContentConfigError(issues);
+  return config;
+}
+
+function validatePageProfileConfig(config, source, profile, capabilities) {
+  if (hasOwn(config?.listing, "priority") && capabilities?.page?.listingPriority !== true) {
+    throw new ContentConfigError([unsupportedProfileField(source, "listing.priority", profile)]);
+  }
+  return config;
+}
+
+function getCollectionId(page, profile) {
+  if (page?.collection?.profile !== profile) return null;
+  return page.collection.id;
+}
+
+function isListed(content) {
+  return content?.visibility?.listed !== false;
+}
+
+function isSearchable(content) {
+  return content?.visibility?.searchable !== false;
+}
+
+module.exports = {
+  CONTENT_MODEL_FIELDS,
+  ContentConfigError,
+  getCollectionId,
+  isPlainObject,
+  isListed,
+  isSearchable,
+  parseCollectionConfig,
+  parsePageConfig,
+  validateCollectionProfileConfig,
+  validatePageProfileConfig,
+  validateThemeConfig
+};

package/scripts/lib/content-defaults.js

@@ -0,0 +1,56 @@
+/* global hexo */
+"use strict";
+
+const {
+  ConfigSchemaError,
+  isPlainObject,
+  valueType
+} = require("./config-schema");
+
+function requireContentConfig(stellarConfig, source = "_config.stellar.yml") {
+  const article = stellarConfig?.article;
+  const notebook = stellarConfig?.profiles?.notebook;
+  if (isPlainObject(article) && isPlainObject(notebook)) {
+    return { article, notebook };
+  }
+  const path = isPlainObject(article) ? "stellarConfig.profiles.notebook" : "stellarConfig.article";
+  const actual = isPlainObject(article) ? notebook : article;
+  throw new ConfigSchemaError([Object.freeze({
+    code: "invalid_type",
+    source,
+    path,
+    actualType: valueType(actual),
+    expected: "normalized content defaults object",
+    migration: null
+  })]);
+}
+
+function articlePresentationDefaults(content) {
+  return {
+    style: content.article.style,
+    paragraphIndent: content.article.paragraphIndent
+  };
+}
+
+function articleFooterDefaults(content) {
+  return {
+    references: [],
+    license: content.article.footer.license,
+    share: content.article.footer.share,
+    showTags: content.article.footer.showTags
+  };
+}
+
+function collectionFooterDefaults(content) {
+  return {
+    ...articleFooterDefaults(content),
+    share: []
+  };
+}
+
+module.exports = {
+  articleFooterDefaults,
+  articlePresentationDefaults,
+  collectionFooterDefaults,
+  requireContentConfig
+};

package/scripts/lib/content-membership.js

@@ -0,0 +1,233 @@
+"use strict";
+
+const { deepFreeze } = require("../schema/schema-utils");
+const { normalize_path: normalizePathKey } = require("./path_utils");
+
+const PROFILE_DIRECTORY = Object.freeze({
+  wiki: "wiki",
+  topic: "topic",
+  notebook: "notebooks"
+});
+
+function normalizePath(value) {
+  if (typeof value !== "string") return "";
+  let result = value.replace(/\\/g, "/").replace(/^source\//, "").replace(/^\/+/, "");
+  result = result.replace(/\.md$/i, "");
+  result = normalizePathKey(result).replace(/^\/+|\/+$/g, "");
+  return result;
+}
+
+function sourcePagePath(source) {
+  const normalized = normalizePath(source);
+  return normalizePath(normalized.replace(/^_posts\//, ""));
+}
+
+function flattenTree(tree) {
+  if (Array.isArray(tree)) return tree.filter(item => typeof item === "string");
+  if (tree == null || typeof tree !== "object") return [];
+  return Object.values(tree).flatMap(items => (
+    Array.isArray(items) ? items.filter(item => typeof item === "string") : []
+  ));
+}
+
+function addIndex(index, signal, key) {
+  const normalized = normalizePath(signal);
+  if (!normalized) return;
+  if (!index.has(normalized)) index.set(normalized, new Set());
+  index.get(normalized).add(key);
+}
+
+function parseCollectionKey(key) {
+  const matched = String(key).match(/^(wiki|topic|notebooks)\/(.+)$/);
+  if (!matched) return null;
+  return {
+    profile: matched[1] === "notebooks" ? "notebook" : matched[1],
+    id: matched[2]
+  };
+}
+
+function createCollectionRegistry(collectionConfigs) {
+  const records = [];
+  const byKey = new Map();
+  const wikiMembers = new Map();
+  const topicStarts = new Map();
+  for (const [sourceKey, config] of collectionConfigs || []) {
+    const identity = parseCollectionKey(sourceKey);
+    if (!identity) continue;
+    const key = `${identity.profile}:${identity.id}`;
+    const record = deepFreeze({ ...identity, key, sourceKey, config });
+    records.push(record);
+    byKey.set(key, record);
+    if (identity.profile === "wiki") {
+      const base = normalizePath(config.route?.path || `wiki/${identity.id}`);
+      for (const member of flattenTree(config.navigation?.tree)) {
+        addIndex(wikiMembers, `${base}/${member}`, key);
+      }
+    } else if (identity.profile === "topic" && typeof config.route?.start === "string") {
+      addIndex(topicStarts, config.route.start, key);
+    }
+  }
+  return {
+    records: Object.freeze(records),
+    byKey,
+    wikiMembers,
+    topicStarts
+  };
+}
+
+function namespaceFor(kind, source) {
+  const normalized = normalizePath(source);
+  if (kind === "pages") {
+    const wiki = normalized.match(/^wiki\/([^/]+)(?:\/|$)/);
+    if (wiki) return { profile: "wiki", id: wiki[1], key: `wiki:${wiki[1]}` };
+    const notebook = normalized.match(/^notebooks\/([^/]+)(?:\/|$)/);
+    if (notebook) return { profile: "notebook", id: notebook[1], key: `notebook:${notebook[1]}` };
+  }
+  if (kind === "posts") {
+    const topic = normalized.match(/^_posts\/topics?\/([^/]+)(?:\/|$)/);
+    if (topic) return { profile: "topic", id: topic[1], key: `topic:${topic[1]}` };
+  }
+  return null;
+}
+
+function pageSignals(source, pagePath, config) {
+  const normalizedSource = normalizePath(source);
+  const withoutPosts = normalizedSource.replace(/^_posts\//, "");
+  const signals = new Set([
+    normalizedSource,
+    withoutPosts,
+    sourcePagePath(source),
+    normalizePath(pagePath),
+    normalizePath(config?.permalink),
+    normalizePath(withoutPosts.split("/").at(-1))
+  ].filter(Boolean));
+  return signals;
+}
+
+function collectCandidateKeys({ kind, source, pagePath, config, registry }, includeNamespace) {
+  const keys = new Set();
+  const namespace = namespaceFor(kind, source);
+  if (includeNamespace && namespace && registry.byKey.has(namespace.key)) keys.add(namespace.key);
+  const index = kind === "posts" ? registry.topicStarts : registry.wikiMembers;
+  for (const signal of pageSignals(source, pagePath, config)) {
+    for (const key of index.get(signal) || []) keys.add(key);
+  }
+  return Object.freeze([...keys].sort());
+}
+
+function candidateKeys(input) {
+  return collectCandidateKeys(input, true);
+}
+
+function membershipIssue(code, source, actual, candidates, fix) {
+  const list = candidates.length > 0 ? candidates.join(", ") : "<none>";
+  return Object.freeze({
+    code,
+    source,
+    path: "collection",
+    actualType: actual,
+    expected: `one registered Collection; candidates=${list}; fix=${fix}`,
+    migration: "content-schema/membership"
+  });
+}
+
+function resolveContentMembership(input) {
+  const kind = input.kind;
+  const source = input.source || "<page>";
+  const config = input.config || {};
+  const registry = input.registry;
+  const candidates = candidateKeys({ ...input, registry });
+  const relationshipCandidates = collectCandidateKeys({ ...input, registry }, false);
+  const namespace = namespaceFor(kind, source);
+  const hardCandidates = new Set(relationshipCandidates);
+  if (namespace?.profile !== "wiki" && registry.byKey.has(namespace?.key)) hardCandidates.add(namespace.key);
+  const conflictingCandidates = Object.freeze([...hardCandidates].sort());
+  const explicit = config.collection == null
+    ? null
+    : `${config.collection.profile}:${config.collection.id}`;
+  const allowedProfiles = kind === "posts" ? new Set(["topic"]) : new Set(["wiki", "notebook"]);
+
+  if (explicit) {
+    const profile = config.collection.profile;
+    if (!allowedProfiles.has(profile) || !registry.byKey.has(explicit)) {
+      return deepFreeze({
+        config: null,
+        candidates,
+        inferred: false,
+        issues: [membershipIssue(
+          "collection_not_found",
+          source,
+          `collection:${explicit}`,
+          candidates,
+          "use a profile/id registered in source/_data and valid for this content source"
+        )]
+      });
+    }
+    if (conflictingCandidates.length > 0 && !conflictingCandidates.includes(explicit)) {
+      return deepFreeze({
+        config: null,
+        candidates,
+        inferred: false,
+        issues: [membershipIssue(
+          "collection_conflict",
+          source,
+          `collection:${explicit}`,
+          conflictingCandidates,
+          "change collection.profile/id to the inferred member or move the source file"
+        )]
+      });
+    }
+    return deepFreeze({ config, candidates, inferred: false, issues: [] });
+  }
+
+  if (candidates.length === 1) {
+    const record = registry.byKey.get(candidates[0]);
+    return deepFreeze({
+      config: {
+        ...config,
+        collection: { profile: record.profile, id: record.id }
+      },
+      candidates,
+      inferred: true,
+      issues: []
+    });
+  }
+  if (candidates.length > 1) {
+    return deepFreeze({
+      config: null,
+      candidates,
+      inferred: false,
+      issues: [membershipIssue(
+        "collection_ambiguous",
+        source,
+        "collection:missing",
+        candidates,
+        "add collection.profile and collection.id to this page"
+      )]
+    });
+  }
+
+  if (namespace) {
+    return deepFreeze({
+      config: null,
+      candidates,
+      inferred: false,
+      issues: [membershipIssue(
+        "collection_not_found",
+        source,
+        "collection:missing",
+        candidates,
+        `create source/_data/${PROFILE_DIRECTORY[namespace.profile]}/${namespace.id}.yml or add a valid collection.profile/id`
+      )]
+    });
+  }
+  return deepFreeze({ config, candidates, inferred: false, issues: [] });
+}
+
+module.exports = {
+  candidateKeys,
+  createCollectionRegistry,
+  normalizePath,
+  resolveContentMembership,
+  sourcePagePath
+};

package/scripts/lib/contribution-contract.js

@@ -0,0 +1,165 @@
+/* global hexo */
+
+"use strict";
+
+const CONTRIBUTION_KINDS = new Set(["extension", "feature", "component"]);
+const ENTRY_TYPES = new Set(["browser-module", "template"]);
+const ACTIVATION_TYPES = new Set(["always", "selector", "server"]);
+const DEFINITION_FIELDS = new Set([
+  "id",
+  "kind",
+  "entry",
+  "resources",
+  "activation",
+  "schema",
+  "i18n",
+  "docs",
+  "tests",
+  "defaultsOwner",
+  "project"
+]);
+
+function deepFreeze(value) {
+  if (value == null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.values(value).forEach(deepFreeze);
+  return Object.freeze(value);
+}
+
+function plainObject(value, label) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`[stellar contributions] ${label} must be an object`);
+  }
+  return value;
+}
+
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`[stellar contributions] ${label} must be a non-empty string`);
+  }
+}
+
+function stringList(value, label, options = {}) {
+  if (!Array.isArray(value) || (!options.allowEmpty && value.length === 0)) {
+    throw new TypeError(`[stellar contributions] ${label} must be ${options.allowEmpty ? "an" : "a non-empty"} array`);
+  }
+  const seen = new Set();
+  value.forEach((item, index) => {
+    nonEmptyString(item, `${label}[${index}]`);
+    if (seen.has(item)) throw new TypeError(`[stellar contributions] duplicate ${label} value ${item}`);
+    seen.add(item);
+  });
+}
+
+function validateEntry(entry, label) {
+  plainObject(entry, label);
+  const allowed = new Set(["type", "path", "adapter"]);
+  const unknown = Object.keys(entry).find(key => !allowed.has(key));
+  if (unknown) throw new TypeError(`[stellar contributions] ${label} has unknown field ${unknown}`);
+  if (!ENTRY_TYPES.has(entry.type)) throw new TypeError(`[stellar contributions] ${label}.type is invalid`);
+  nonEmptyString(entry.path, `${label}.path`);
+  if (entry.type === "browser-module" && (!entry.path.startsWith("/js/runtime/") || !entry.path.endsWith(".js"))) {
+    throw new TypeError(`[stellar contributions] ${label}.path must be a local runtime .js path`);
+  }
+  if (entry.type === "template" && !entry.path.startsWith("layout/")) {
+    throw new TypeError(`[stellar contributions] ${label}.path must be a layout path`);
+  }
+  if (entry.adapter !== undefined && entry.adapter !== "feature") {
+    throw new TypeError(`[stellar contributions] ${label}.adapter is invalid`);
+  }
+}
+
+function validateActivation(activation, label) {
+  plainObject(activation, label);
+  const allowed = new Set(["type", "value"]);
+  const unknown = Object.keys(activation).find(key => !allowed.has(key));
+  if (unknown) throw new TypeError(`[stellar contributions] ${label} has unknown field ${unknown}`);
+  if (!ACTIVATION_TYPES.has(activation.type)) throw new TypeError(`[stellar contributions] ${label}.type is invalid`);
+  if (activation.type === "always") {
+    if (activation.value !== undefined) throw new TypeError(`[stellar contributions] ${label}.value is not allowed for always`);
+    return;
+  }
+  nonEmptyString(activation.value, `${label}.value`);
+}
+
+function validateI18n(i18n, label) {
+  if (i18n === null) return;
+  plainObject(i18n, label);
+  const unknown = Object.keys(i18n).find(key => !["namespace", "keys"].includes(key));
+  if (unknown) throw new TypeError(`[stellar contributions] ${label} has unknown field ${unknown}`);
+  nonEmptyString(i18n.namespace, `${label}.namespace`);
+  stringList(i18n.keys, `${label}.keys`);
+}
+
+function validateDocs(docs, label) {
+  plainObject(docs, label);
+  const unknown = Object.keys(docs).find(key => !["category", "path"].includes(key));
+  if (unknown) throw new TypeError(`[stellar contributions] ${label} has unknown field ${unknown}`);
+  nonEmptyString(docs.category, `${label}.category`);
+  nonEmptyString(docs.path, `${label}.path`);
+}
+
+function validateContributionDefinitions(definitions) {
+  if (!Array.isArray(definitions) || definitions.length === 0) {
+    throw new TypeError("[stellar contributions] registry must be a non-empty array");
+  }
+  const ids = new Set();
+  const resourceOwners = new Map();
+  const schemaOwners = new Map();
+
+  definitions.forEach((definition, index) => {
+    const label = `definitions[${index}]`;
+    plainObject(definition, label);
+    const unknown = Object.keys(definition).find(key => !DEFINITION_FIELDS.has(key));
+    if (unknown) throw new TypeError(`[stellar contributions] ${label} has unknown field ${unknown}`);
+    const missing = [...DEFINITION_FIELDS].find(key => !Object.prototype.hasOwnProperty.call(definition, key));
+    if (missing) throw new TypeError(`[stellar contributions] ${label} is missing field ${missing}`);
+    if (typeof definition.id !== "string" || !/^[a-z][a-z0-9-]*$/.test(definition.id)) {
+      throw new TypeError(`[stellar contributions] ${label}.id is invalid`);
+    }
+    if (ids.has(definition.id)) throw new TypeError(`[stellar contributions] duplicate contribution id ${definition.id}`);
+    ids.add(definition.id);
+    if (!CONTRIBUTION_KINDS.has(definition.kind)) throw new TypeError(`[stellar contributions] ${label}.kind is invalid`);
+    validateEntry(definition.entry, `${label}.entry`);
+    stringList(definition.resources, `${label}.resources`);
+    validateActivation(definition.activation, `${label}.activation`);
+    if (definition.schema !== null) nonEmptyString(definition.schema, `${label}.schema`);
+    validateI18n(definition.i18n, `${label}.i18n`);
+    validateDocs(definition.docs, `${label}.docs`);
+    stringList(definition.tests, `${label}.tests`);
+    if (definition.defaultsOwner !== null) nonEmptyString(definition.defaultsOwner, `${label}.defaultsOwner`);
+    if ((definition.schema === null) !== (definition.defaultsOwner === null)) {
+      throw new TypeError(`[stellar contributions] ${definition.id} schema and defaultsOwner must both be null or strings`);
+    }
+    if (definition.project !== null && typeof definition.project !== "function") {
+      throw new TypeError(`[stellar contributions] ${label}.project must be a function or null`);
+    }
+    if (definition.project !== null && definition.entry.type !== "browser-module") {
+      throw new TypeError(`[stellar contributions] ${definition.id} projected contribution must use a browser-module entry`);
+    }
+
+    definition.resources.forEach(resource => {
+      if (resourceOwners.has(resource)) {
+        throw new TypeError(`[stellar contributions] resource ${resource} is owned by both ${resourceOwners.get(resource)} and ${definition.id}`);
+      }
+      resourceOwners.set(resource, definition.id);
+    });
+    if (definition.schema !== null) {
+      const owner = schemaOwners.get(definition.schema);
+      if (owner && owner !== definition.defaultsOwner) {
+        throw new TypeError(`[stellar contributions] schema ${definition.schema} has conflicting defaults owners ${owner} and ${definition.defaultsOwner}`);
+      }
+      schemaOwners.set(definition.schema, definition.defaultsOwner);
+    }
+  });
+  return definitions;
+}
+
+function defineContributions(definitions) {
+  validateContributionDefinitions(definitions);
+  return deepFreeze(definitions.slice());
+}
+
+module.exports = {
+  defineContributions,
+  validateContributionDefinitions
+};