@hagicode/hagilight 0.2.5 → 0.3.1

package/Footer.astro

@@ -1,5 +1,6 @@
 ---
 import Copyright from './Copyright.astro';
+import { resolveRssFooterLinks } from './rss-footer-context.mjs';
 import { resolveSiteLinks, type SiteLinksOptions } from './site-links.ts';
 
 interface Props {
@@ -9,7 +10,8 @@ interface Props {
 
 const { locale: propLocale, links } = Astro.props;
 const locale = propLocale ?? Astro.currentLocale ?? 'en-US';
-const resolvedLinks = resolveSiteLinks(locale, links);
+const footerLinks = resolveRssFooterLinks(Astro.locals, locale, links);
+const resolvedLinks = resolveSiteLinks(locale, footerLinks);
 ---
 
 <footer class="hagilight-footer">

package/integration.mjs

@@ -0,0 +1,191 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, extname, isAbsolute, resolve, win32 } from 'node:path';
+import { resolveRssLocales } from './rss-locales.mjs';
+
+export const HAGILIGHT_RSS_OWNER = Symbol.for('@hagicode/hagilight/rss-owner');
+const VIRTUAL_RSS_CONFIG = 'virtual:hagilight/rss-config';
+const VIRTUAL_RSS_CONFIG_RESOLVED = `\0${VIRTUAL_RSS_CONFIG}`;
+const RSS_OWNER_REGISTRY = Symbol.for('@hagicode/hagilight/rss-owner-registry');
+const PAGE_SOURCE_EXTENSIONS = new Set(['.astro', '.html', '.js', '.jsx', '.md', '.mdx', '.ts', '.tsx']);
+const registeredRssOwners = globalThis[RSS_OWNER_REGISTRY] ?? new Map();
+globalThis[RSS_OWNER_REGISTRY] = registeredRssOwners;
+
+export function registerStarlightRssOwner(enabled) {
+  const token = Symbol('starlight-rss-owner');
+  registeredRssOwners.set(token, { package: 'starlight', enabled });
+  return () => registeredRssOwners.delete(token);
+}
+
+function resolveOptions(options) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('Hagilight RSS integration options must be an object.');
+  }
+  const locales = resolveRssLocales(options.locales, { requireNonEmpty: true });
+  if (typeof options.getFeed !== 'string' || !options.getFeed.trim()) {
+    throw new TypeError('Hagilight RSS getFeed must be a non-empty module path such as "./src/rss-feed.mjs".');
+  }
+  return { locales, getFeed: options.getFeed.trim() };
+}
+
+function resolveSite(site) {
+  let parsed;
+  try {
+    parsed = new URL(site);
+  } catch {
+    throw new Error('Hagilight RSS requires an absolute Astro site URL. Set `site` in astro.config.mjs.');
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password) {
+    throw new Error('Hagilight RSS requires an absolute HTTP(S) Astro site URL.');
+  }
+  return parsed.href;
+}
+
+function resolveFeedModule(root, reference) {
+  if (reference.startsWith('file:') || isAbsolute(reference) || win32.isAbsolute(reference)) {
+    throw new TypeError('Hagilight RSS getFeed must be a path relative to the Astro project root.');
+  }
+  const rootPath = fileURLToPath(root);
+  const modulePath = resolve(rootPath, reference);
+  if (!existsSync(modulePath) || !statSync(modulePath).isFile()) {
+    throw new Error(`Hagilight RSS getFeed module "${reference}" was not found relative to the Astro project root.`);
+  }
+  return modulePath;
+}
+
+function routeCollisions(config, locales) {
+  const expectedFiles = new Set(['rss.xml', 'rss.en.xml', ...locales.map(({ filename }) => `rss.${filename}.xml`)]);
+  const pageRoot = resolve(fileURLToPath(config.srcDir), 'pages');
+  const publicRoot = fileURLToPath(config.publicDir);
+  const collisions = [];
+
+  function findPageCollisions(directory) {
+    if (!existsSync(directory)) return;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const entryPath = resolve(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'rss.xml' || /^rss\..+\.xml$/u.test(entry.name)) {
+          for (const child of readdirSync(entryPath, { withFileTypes: true })) {
+            if (child.isFile()
+              && child.name.startsWith('index.')
+              && PAGE_SOURCE_EXTENSIONS.has(extname(child.name))) {
+              collisions.push(resolve(entryPath, child.name));
+            }
+          }
+        }
+        findPageCollisions(entryPath);
+      } else if (entry.isFile()) {
+        const extension = extname(entry.name);
+        if (!PAGE_SOURCE_EXTENSIONS.has(extension)) continue;
+        const sourceName = entry.name.slice(0, -extension.length);
+        if (expectedFiles.has(sourceName) || /^rss\..+\.xml$/u.test(sourceName)) {
+          collisions.push(entryPath);
+        }
+      }
+    }
+  }
+  findPageCollisions(pageRoot);
+
+  for (const filename of expectedFiles) {
+    const publicFile = resolve(publicRoot, filename);
+    if (existsSync(publicFile) && statSync(publicFile).isFile()) collisions.push(publicFile);
+  }
+
+  if (collisions.length > 0) {
+    throw new Error(`Hagilight RSS route conflicts with consumer-owned file(s): ${collisions.join(', ')}. Remove the conflicting route or do not enable hagilightRss().`);
+  }
+}
+
+function findStarlightRss(config) {
+  const registeredOwners = [...registeredRssOwners.values()];
+  const owners = registeredOwners.length > 0
+    ? registeredOwners
+    : (config.integrations ?? [])
+    .map((integration) => integration?.[HAGILIGHT_RSS_OWNER])
+    .filter((owner) => owner?.package === 'starlight');
+  registeredRssOwners.clear();
+  return owners;
+}
+
+function createVirtualPlugin({ modulePath, site, baseUrl, locales, defaultFeedUrl, localeFeedUrls }) {
+  return {
+    name: '@hagicode/hagilight:rss',
+    resolveId(id) {
+      return id === VIRTUAL_RSS_CONFIG ? VIRTUAL_RSS_CONFIG_RESOLVED : null;
+    },
+    load(id) {
+      if (id !== VIRTUAL_RSS_CONFIG_RESOLVED) return null;
+      return [
+        `import * as siteFeedModule from ${JSON.stringify(modulePath)};`,
+        'const config = {',
+        `  site: ${JSON.stringify(site)},`,
+        `  baseUrl: ${JSON.stringify(baseUrl)},`,
+        `  locales: ${JSON.stringify(locales)},`,
+        '  getFeed: siteFeedModule.default,',
+        `  footer: ${JSON.stringify({ defaultFeedUrl, localeFeedUrls, locales })},`,
+        '};',
+        'export default config;',
+      ].join('\n');
+    },
+  };
+}
+
+export function hagilightRss(input) {
+  const options = resolveOptions(input);
+
+  return {
+    name: '@hagicode/hagilight:rss',
+    [HAGILIGHT_RSS_OWNER]: { package: 'core', enabled: true },
+    hooks: {
+      'astro:config:setup'({ config, injectRoute, addMiddleware, updateConfig }) {
+        const starlightOwners = findStarlightRss(config);
+        const activeStarlightOwners = starlightOwners.filter((owner) => owner.enabled);
+        if (activeStarlightOwners.length > 1) {
+          throw new Error('Hagilight RSS cannot determine a sole route owner because multiple Starlight RSS integrations are enabled.');
+        }
+        if (activeStarlightOwners.length > 0) return;
+        if (starlightOwners.length > 0) {
+          throw new Error('Hagilight RSS cannot establish route ownership: Starlight RSS is explicitly disabled while hagilightRss() requests feed generation. Enable Starlight RSS or remove hagilightRss().');
+        }
+
+        const site = resolveSite(config.site);
+        const modulePath = resolveFeedModule(config.root, options.getFeed);
+        routeCollisions(config, options.locales);
+        const baseSegments = `${config.base || '/'}`
+          .split('/')
+          .filter(Boolean);
+        const baseUrl = baseSegments.length > 0 ? `/${baseSegments.join('/')}/` : '/';
+        const baseLocation = new URL(baseUrl, site);
+        const defaultFeedUrl = new URL('rss.xml', baseLocation).href;
+        const localeFeedUrls = Object.fromEntries(options.locales
+          .filter(({ filename }) => filename !== 'en')
+          .map(({ lang, filename }) => [lang, new URL(`rss.${filename}.xml`, baseLocation).href]));
+        const rssIntegrationPath = dirname(fileURLToPath(import.meta.url));
+        const plugin = createVirtualPlugin({
+          modulePath,
+          site,
+          baseUrl,
+          locales: options.locales,
+          defaultFeedUrl,
+          localeFeedUrls,
+        });
+
+        injectRoute({
+          pattern: '/rss.xml',
+          entrypoint: resolve(rssIntegrationPath, './rss.xml.ts'),
+          prerender: true,
+        });
+        injectRoute({
+          pattern: '/rss.[language].xml',
+          entrypoint: resolve(rssIntegrationPath, './rss.[language].xml.ts'),
+          prerender: true,
+        });
+        addMiddleware({
+          entrypoint: resolve(rssIntegrationPath, './rss-middleware.mjs'),
+          order: 'pre',
+        });
+        updateConfig({ vite: { plugins: [plugin] } });
+      },
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "type": "module",
   "description": "Shared Astro components for HagiCode sites",
   "repository": {
@@ -23,7 +23,9 @@
     "./GoogleAnalytics": "./GoogleAnalytics.astro",
     "./Analytics51LA": "./Analytics51LA.astro",
     "./SEOHead": "./SEOHead.astro",
+    "./integration": "./integration.mjs",
     "./seo-utils": "./seo-utils.mjs",
+    "./rss-locales": "./rss-locales.mjs",
     "./rss": "./rss-renderer.mjs",
     "./seo-schema": {
       "types": "./seo-schema.d.ts",

package/rss-footer-context.mjs

@@ -0,0 +1,51 @@
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeLanguageTag(value) {
+  if (typeof value !== 'string' || !value.trim()) return undefined;
+  const input = value.trim().replaceAll('_', '-');
+  const alias = input.toLowerCase();
+  if (['zh', 'zh-cn', 'zh-hans', 'root'].includes(alias)) return 'zh-CN';
+  if (['zh-hant', 'zh-tw', 'zh-hk'].includes(alias)) return 'zh-Hant';
+  try {
+    return Intl.getCanonicalLocales(input)[0];
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveRssFooterLinks(locals, locale, links = {}) {
+  if (!isRecord(locals) || !Object.hasOwn(locals, 'hagilightRss')) return links;
+  const rss = locals.hagilightRss;
+  if (!isRecord(rss)
+    || typeof rss.defaultFeedUrl !== 'string'
+    || !rss.defaultFeedUrl
+    || !isRecord(rss.localeFeedUrls)
+    || !Array.isArray(rss.locales)
+    || rss.locales.some((entry) => !isRecord(entry)
+      || typeof entry.lang !== 'string'
+      || typeof entry.filename !== 'string')) {
+    throw new TypeError('Hagilight RSS Footer context is malformed.');
+  }
+
+  const normalizedLocale = normalizeLanguageTag(locale);
+  const configuredLocale = rss.locales.find((entry) =>
+    isRecord(entry)
+      && entry.filename !== 'en'
+      && normalizeLanguageTag(entry.lang) === normalizedLocale);
+  const localeFeedUrl = configuredLocale
+    ? rss.localeFeedUrls[configuredLocale.lang]
+    : undefined;
+  if (configuredLocale && (typeof localeFeedUrl !== 'string' || !localeFeedUrl)) {
+    throw new TypeError(`Hagilight RSS Footer context has no URL for "${configuredLocale.lang}".`);
+  }
+
+  return {
+    ...links,
+    rssFeedUrl: links.rssFeedUrl ?? rss.defaultFeedUrl,
+    ...(typeof localeFeedUrl === 'string' && localeFeedUrl
+      ? { rssLocaleFeedUrl: links.rssLocaleFeedUrl ?? localeFeedUrl }
+      : {}),
+  };
+}

package/rss-locales.mjs

@@ -0,0 +1,40 @@
+const LANGUAGE_TAG_PATTERN = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u;
+
+export function resolveRssLocales(locales, { requireNonEmpty = false } = {}) {
+  if (locales !== undefined && (!locales || typeof locales !== 'object' || Array.isArray(locales))) {
+    throw new TypeError('Hagilight RSS locales must be an object.');
+  }
+  if (requireNonEmpty && (locales === undefined || Object.keys(locales).length === 0)) {
+    throw new TypeError('Hagilight RSS locales must contain at least one locale.');
+  }
+
+  const configuredLocales = locales === undefined
+    ? [['root', { lang: 'en' }]]
+    : Object.entries(locales);
+  if (configuredLocales.length === 0) {
+    if (requireNonEmpty) throw new TypeError('Hagilight RSS locales must contain at least one locale.');
+    configuredLocales.push(['root', { lang: 'en' }]);
+  }
+
+  const usedFilenames = new Set();
+  return configuredLocales.map(([route, config]) => {
+    const lang = typeof config === 'string' ? config : config?.lang ?? (route === 'root' ? undefined : route);
+    if (typeof lang !== 'string' || !LANGUAGE_TAG_PATTERN.test(lang)) {
+      throw new TypeError(`Hagilight RSS locale "${route}" must have a valid language tag.`);
+    }
+    let normalizedLang;
+    try {
+      [normalizedLang] = Intl.getCanonicalLocales(lang);
+    } catch {
+      throw new TypeError(`Hagilight RSS locale "${route}" has an invalid language tag "${lang}".`);
+    }
+
+    const filename = /^en(?:-us)?$/iu.test(normalizedLang) ? 'en' : normalizedLang;
+    const collisionKey = filename.toLowerCase();
+    if (usedFilenames.has(collisionKey)) {
+      throw new Error(`Hagilight RSS locales collide on the "${filename}" feed filename.`);
+    }
+    usedFilenames.add(collisionKey);
+    return { route, lang: normalizedLang, filename };
+  });
+}

package/rss-middleware.mjs

@@ -0,0 +1,6 @@
+import rssConfig from 'virtual:hagilight/rss-config';
+
+export const onRequest = (context, next) => {
+  context.locals.hagilightRss = rssConfig.footer;
+  return next();
+};

package/rss-runtime.mjs

@@ -0,0 +1,45 @@
+import { generateRssFeed } from './rss-renderer.mjs';
+
+const EMPTY_ENGLISH_FEED = {
+  title: 'Hagilight RSS Feed',
+  description: 'English-language feed for this site.',
+  items: [],
+};
+
+export async function renderRssFeed(config, filename) {
+  const locale = config.locales.find((entry) => entry.filename === filename);
+  if (!locale && filename !== 'en') {
+    throw new Error(`Hagilight RSS has no configured locale for "${filename}".`);
+  }
+
+  let feed;
+  if (!locale) {
+    feed = EMPTY_ENGLISH_FEED;
+  } else {
+    if (typeof config.getFeed !== 'function') {
+      throw new TypeError('Hagilight RSS getFeed module must default-export a callback function.');
+    }
+    feed = await config.getFeed({ route: locale.route, lang: locale.lang });
+    if (!feed || typeof feed !== 'object' || Array.isArray(feed)) {
+      throw new TypeError(`Hagilight RSS getFeed callback for "${locale.lang}" must return an object.`);
+    }
+    if (typeof feed.title !== 'string' || !feed.title.trim()) {
+      throw new TypeError(`Hagilight RSS getFeed callback for "${locale.lang}" must return a non-empty title.`);
+    }
+    if (typeof feed.description !== 'string' || !feed.description.trim()) {
+      throw new TypeError(`Hagilight RSS getFeed callback for "${locale.lang}" must return a non-empty description.`);
+    }
+    if (!Array.isArray(feed.items)) {
+      throw new TypeError(`Hagilight RSS getFeed callback for "${locale.lang}" must return an items array.`);
+    }
+  }
+
+  return generateRssFeed({
+    site: config.site,
+    baseUrl: config.baseUrl,
+    language: locale?.lang ?? 'en',
+    title: feed.title,
+    description: feed.description,
+    items: feed.items,
+  });
+}

package/rss.[language].xml.ts

@@ -0,0 +1,10 @@
+import type { APIRoute, GetStaticPaths } from 'astro';
+import rssConfig from 'virtual:hagilight/rss-config';
+import { renderRssFeed } from './rss-runtime.mjs';
+
+export const getStaticPaths: GetStaticPaths = () => [...new Set([
+  'en',
+  ...rssConfig.locales.map(({ filename }) => filename),
+])].map((language) => ({ params: { language } }));
+
+export const GET: APIRoute = ({ params }) => renderRssFeed(rssConfig, params.language);

package/rss.xml.ts

@@ -0,0 +1,5 @@
+import type { APIRoute } from 'astro';
+import rssConfig from 'virtual:hagilight/rss-config';
+import { renderRssFeed } from './rss-runtime.mjs';
+
+export const GET: APIRoute = () => renderRssFeed(rssConfig, 'en');