@rocket/js 0.0.0 → 0.1.1

package/src/publicAssets.js

@@ -0,0 +1,336 @@
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { URLPattern } from 'urlpattern-polyfill';
+import { paginatedArchivePaths } from './page-pagination.js';
+import { normalizeDocumentPath, standaloneDemoPaths } from './standalone-demo-url.js';
+import { needsDefaultSocialPreviewImage, publicSocialPreviewPages } from './socialPreviewImages.js';
+
+export const PUBLIC_ASSETS_DIR = 'public';
+
+/**
+ * @typedef {{
+ *   file: string;
+ *   relativePath: string;
+ *   publicPath: string;
+ * }} PublicAsset
+ */
+
+/**
+ * @param {string} [projectRoot]
+ * @returns {PublicAsset[]}
+ */
+export function discoverPublicAssets(projectRoot = process.cwd()) {
+  const publicDir = path.join(projectRoot, PUBLIC_ASSETS_DIR);
+  if (!existsSync(publicDir)) {
+    return [];
+  }
+  const publicDirStats = lstatSync(publicDir);
+  if (publicDirStats.isSymbolicLink()) {
+    throw new Error(
+      `Public Assets directory ${PUBLIC_ASSETS_DIR} is a symbolic link. ` +
+        `Public Assets must be regular files.`,
+    );
+  }
+  if (!publicDirStats.isDirectory()) {
+    throw new Error(`Public Assets directory ${PUBLIC_ASSETS_DIR} must be a directory.`);
+  }
+
+  /** @type {PublicAsset[]} */
+  const assets = [];
+  collectPublicAssets({ publicDir, directory: publicDir, relativeDirectory: '', assets });
+  return assets.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+
+/**
+ * @param {{
+ *   projectRoot: string;
+ *   outDir: string;
+ * }} options
+ */
+export function assertPublicAssetsOutputDir({ projectRoot, outDir }) {
+  const publicDir = path.resolve(projectRoot, PUBLIC_ASSETS_DIR);
+  const resolvedOutDir = path.resolve(outDir);
+  if (resolvedOutDir === publicDir || resolvedOutDir.startsWith(`${publicDir}${path.sep}`)) {
+    throw new Error(
+      `Invalid build output directory ${outDir}. ` +
+        `The ${PUBLIC_ASSETS_DIR} directory is reserved for Public Assets.`,
+    );
+  }
+}
+
+/**
+ * @param {{
+ *   publicDir: string;
+ *   directory: string;
+ *   relativeDirectory: string;
+ *   assets: PublicAsset[];
+ * }} options
+ */
+function collectPublicAssets({ publicDir, directory, relativeDirectory, assets }) {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const relativePath = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+    const file = path.join(publicDir, ...relativePath.split('/'));
+
+    if (entry.isSymbolicLink()) {
+      throw new Error(
+        `Public Asset ${PUBLIC_ASSETS_DIR}/${relativePath} is a symbolic link. ` +
+          `Public Assets must be regular files.`,
+      );
+    }
+
+    if (isExcludedDotPath(relativePath)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      collectPublicAssets({
+        publicDir,
+        directory: file,
+        relativeDirectory: relativePath,
+        assets,
+      });
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      throw new Error(
+        `Public Asset ${PUBLIC_ASSETS_DIR}/${relativePath} is not a regular file. ` +
+          `Public Assets must be regular files.`,
+      );
+    }
+
+    assets.push({
+      file,
+      relativePath,
+      publicPath: `/${relativePath}`,
+    });
+  }
+}
+
+/**
+ * @param {string} relativePath
+ */
+function isExcludedDotPath(relativePath) {
+  if (relativePath === '.well-known' || relativePath.startsWith('.well-known/')) {
+    return false;
+  }
+  return relativePath.split('/').some(segment => segment.startsWith('.'));
+}
+
+/**
+ * @param {{
+ *   publicAssets: PublicAsset[];
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ *   generatedPages: import('@rocket/js/types.js').PageRegistry;
+ *   config: import('@rocket/js/types.js').ResolvedRocketConfig;
+ *   emitRedirectFallbacks?: boolean;
+ * }} options
+ */
+export function validatePublicAssetCollisions({
+  publicAssets,
+  pages,
+  generatedPages,
+  config,
+  emitRedirectFallbacks = true,
+}) {
+  assertNoDuplicatePublicAssetPaths(publicAssets);
+
+  const generatedClaims = generatedOutputClaims({
+    pages,
+    generatedPages,
+    config,
+    emitRedirectFallbacks,
+  });
+
+  for (const asset of publicAssets) {
+    for (const requestPath of publicAssetRequestPaths(asset)) {
+      const pageCollision = matchingPage(requestPath, pages);
+      if (pageCollision) {
+        throw new Error(
+          `Public Asset ${PUBLIC_ASSETS_DIR}/${asset.relativePath} collides with configured ` +
+            `Page ${pageCollision.page.file} at ${pageCollision.routePath}.`,
+        );
+      }
+
+      const generatedCollision =
+        generatedClaims.get(requestPath) ||
+        generatedClaims.get(normalizeDirectoryRequestPath(requestPath));
+      if (generatedCollision) {
+        throw new Error(
+          `Public Asset ${PUBLIC_ASSETS_DIR}/${asset.relativePath} collides with ` +
+            `${generatedCollision} at ${requestPath}.`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * @param {string} requestPath
+ */
+function normalizeDirectoryRequestPath(requestPath) {
+  return requestPath.endsWith('/') ? requestPath : `${path.dirname(requestPath)}/`;
+}
+
+/**
+ * @param {PublicAsset[]} publicAssets
+ */
+function assertNoDuplicatePublicAssetPaths(publicAssets) {
+  const claimedPaths = new Map();
+  for (const asset of publicAssets) {
+    for (const requestPath of publicAssetRequestPaths(asset)) {
+      const existing = claimedPaths.get(requestPath);
+      if (existing) {
+        throw new Error(
+          `Public Asset ${PUBLIC_ASSETS_DIR}/${asset.relativePath} collides with Public Asset ` +
+            `${PUBLIC_ASSETS_DIR}/${existing.relativePath} at ${requestPath}.`,
+        );
+      }
+      claimedPaths.set(requestPath, asset);
+    }
+  }
+}
+
+/**
+ * @param {{
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ *   generatedPages: import('@rocket/js/types.js').PageRegistry;
+ *   config: import('@rocket/js/types.js').ResolvedRocketConfig;
+ *   emitRedirectFallbacks: boolean;
+ * }} options
+ * @returns {Map<string, string>}
+ */
+function generatedOutputClaims({ pages, generatedPages, config, emitRedirectFallbacks }) {
+  const claims = new Map();
+
+  for (const [pagePath, page] of generatedPages) {
+    for (const demoPath of standaloneDemoPaths(pagePath, page)) {
+      claims.set(normalizeDocumentPath(demoPath), `Standalone Demo URL ${demoPath}`);
+    }
+    for (const archivePath of paginatedArchivePaths({ pages, page, pagePath })) {
+      claims.set(normalizeDocumentPath(archivePath), `generated archive Page ${archivePath}`);
+    }
+  }
+
+  for (const [pagePath, page] of publicSocialPreviewPages(pages)) {
+    if (
+      needsDefaultSocialPreviewImage({
+        pagePath,
+        page,
+        siteHeadMetadata: config.siteHeadMetadata,
+      })
+    ) {
+      claims.set('/_rocket/social-preview/', `Default Social Preview Image for Page ${pagePath}`);
+    }
+  }
+
+  for (const redirect of config.urlLifecycle?.redirects || []) {
+    claims.set(redirect.source, `Redirect source ${redirect.source}`);
+    if (emitRedirectFallbacks && !isFileOutputPath(redirect.source)) {
+      claims.set(normalizeDocumentPath(redirect.source), `Redirect fallback ${redirect.source}`);
+    }
+  }
+
+  if (config.siteDiscoverability?.sitemap === true) {
+    claims.set('/sitemap.xml', 'generated Sitemap');
+  }
+  if (config.siteDiscoverability?.robots === true) {
+    claims.set('/robots.txt', 'generated Robots File');
+  }
+  if (config.adapter?.name === 'netlify' && config.urlLifecycle?.redirects?.length) {
+    claims.set('/_redirects', 'Netlify Redirect output');
+  }
+
+  return claims;
+}
+
+/**
+ * @param {string} requestPath
+ * @param {import('@rocket/js/types.js').PageRegistry} pages
+ */
+function matchingPage(requestPath, pages) {
+  for (const [routePath, page] of pages) {
+    const pattern = new URLPattern({ pathname: routePath });
+    if (pattern.exec(requestPath, 'http://localhost')) {
+      return { routePath, page };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * @param {PublicAsset} asset
+ * @returns {string[]}
+ */
+export function publicAssetRequestPaths(asset) {
+  const requestPaths = new Set([asset.publicPath]);
+  if (isIndexHtmlPath(asset.relativePath)) {
+    const documentPath = indexHtmlDocumentPath(asset.relativePath);
+    requestPaths.add(documentPath);
+    if (documentPath !== '/') {
+      requestPaths.add(documentPath.slice(0, -1));
+    }
+  }
+  return Array.from(requestPaths);
+}
+
+/**
+ * @param {string} relativePath
+ */
+function isIndexHtmlPath(relativePath) {
+  return relativePath === 'index.html' || relativePath.endsWith('/index.html');
+}
+
+/**
+ * @param {string} relativePath
+ */
+function indexHtmlDocumentPath(relativePath) {
+  if (relativePath === 'index.html') {
+    return '/';
+  }
+  return normalizeDocumentPath(`/${relativePath.slice(0, -'/index.html'.length)}`);
+}
+
+/**
+ * @param {{
+ *   publicAssets: PublicAsset[];
+ *   outDir: string;
+ * }} options
+ */
+export function copyPublicAssets({ publicAssets, outDir }) {
+  for (const asset of publicAssets) {
+    const destination = path.join(outDir, ...asset.relativePath.split('/'));
+    if (existsSync(destination)) {
+      throw new Error(
+        `Public Asset ${PUBLIC_ASSETS_DIR}/${asset.relativePath} collides with generated ` +
+          `output ${asset.publicPath}.`,
+      );
+    }
+    mkdirSync(path.dirname(destination), { recursive: true });
+    copyFileSync(asset.file, destination);
+  }
+}
+
+/**
+ * @param {PublicAsset[]} publicAssets
+ * @param {string} requestPath
+ * @returns {PublicAsset | undefined}
+ */
+export function findPublicAsset(publicAssets, requestPath) {
+  return publicAssets.find(asset => publicAssetRequestPaths(asset).includes(requestPath));
+}
+
+/**
+ * @param {PublicAsset} asset
+ */
+export function readPublicAsset(asset) {
+  return readFileSync(asset.file);
+}
+
+/**
+ * @param {string} pagePath
+ * @returns {boolean}
+ */
+function isFileOutputPath(pagePath) {
+  return path.extname(pagePath) !== '';
+}

package/src/requestDemoMetadata.js

@@ -0,0 +1,97 @@
+/** Runs on: import-hook */
+
+/**
+ * @typedef {{
+ *   url: string;
+ *   label?: string;
+ *   height?: number;
+ * }} RequestDemoMetadata
+ */
+
+/**
+ * @param {string | null | undefined} meta
+ * @returns {RequestDemoMetadata}
+ */
+export function parseRequestDemoMetadata(meta) {
+  const attributes = parseFenceAttributes(stripRequestDemoMarker(meta || ''));
+  const url = attributes.get('url');
+
+  if (url === undefined) {
+    throw new Error('Invalid Request Demo metadata: `url` is required.');
+  }
+  validateRequestDemoUrl(url);
+
+  const height = attributes.has('height')
+    ? parseRequestDemoHeight(attributes.get('height'))
+    : undefined;
+  const label = attributes.get('label') || undefined;
+
+  return {
+    url,
+    ...(label ? { label } : {}),
+    ...(height !== undefined ? { height } : {}),
+  };
+}
+
+/**
+ * @param {string} meta
+ */
+function stripRequestDemoMarker(meta) {
+  return meta
+    .trim()
+    .replace(/^request-demo\b/, '')
+    .trim();
+}
+
+/**
+ * @param {string} source
+ */
+function parseFenceAttributes(source) {
+  /** @type {Map<string, string | undefined>} */
+  const attributes = new Map();
+  const matcher = /([^\s=]+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s]*)))?/g;
+
+  for (const match of source.matchAll(matcher)) {
+    attributes.set(match[1], match[2] ?? match[3] ?? match[4]);
+  }
+
+  return attributes;
+}
+
+/**
+ * @param {string} url
+ */
+function validateRequestDemoUrl(url) {
+  if (isExternalUrl(url)) {
+    throw new Error(
+      'Invalid Request Demo metadata: `url` must be a same-site path starting with `/`.',
+    );
+  }
+  if (!url.startsWith('/')) {
+    throw new Error(
+      'Invalid Request Demo metadata: `url` must be a site-root path starting with `/`.',
+    );
+  }
+  if (url.includes('#')) {
+    throw new Error('Invalid Request Demo metadata: `url` must not include a hash.');
+  }
+}
+
+/**
+ * @param {string} url
+ */
+function isExternalUrl(url) {
+  return url.startsWith('//') || /^[a-zA-Z][a-zA-Z\d.+-]*:/.test(url);
+}
+
+/**
+ * @param {string | undefined} height
+ */
+function parseRequestDemoHeight(height) {
+  if (!height || !/^[1-9]\d*$/.test(height)) {
+    throw new Error(
+      'Invalid Request Demo metadata: `height` must be a positive integer pixel value.',
+    );
+  }
+  return Number(height);
+}

package/src/resolve.js

@@ -0,0 +1,15 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * @param {string} url
+ * @param {ImportMeta} meta
+ * @returns {string} Absolute path to the file, relative to the output directory
+ */
+export function resolve(url, meta) {
+  // get current directory
+  const outputFilePath = process.cwd();
+  const resolvedPath = meta.resolve(url);
+  const rel = path.relative(outputFilePath, fileURLToPath(resolvedPath));
+  return (process.env.ENVIRONMENT === 'BUILD' ? '/../' : '/') + rel.split(path.sep).join('/');
+}

package/src/siteDiscoverability.js

@@ -0,0 +1,184 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import {
+  hasPagePagination,
+  paginatedArchivePath,
+  paginatedArchivePaths,
+} from './page-pagination.js';
+
+/**
+ * @param {{
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ *   outDir: string;
+ *   config: import('@rocket/js/types.js').ResolvedRocketConfig;
+ * }} options
+ */
+export function writeSiteDiscoverabilityOutputs({ pages, outDir, config }) {
+  const shouldWriteSitemap = config.siteDiscoverability?.sitemap === true;
+  const shouldWriteRobots = config.siteDiscoverability?.robots === true;
+  if (!shouldWriteSitemap && !shouldWriteRobots) {
+    return;
+  }
+
+  const siteOrigin = requireSiteOrigin(
+    config.siteOrigin,
+    shouldWriteSitemap ? 'Sitemap' : 'Robots File',
+  );
+  mkdirSync(outDir, { recursive: true });
+  if (shouldWriteSitemap) {
+    writeFileSync(path.join(outDir, 'sitemap.xml'), createSitemap({ pages, siteOrigin }));
+  }
+  if (shouldWriteRobots) {
+    writeFileSync(path.join(outDir, 'robots.txt'), createRobotsFile({ pages, siteOrigin }));
+  }
+}
+
+/**
+ * @param {{
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ *   siteOrigin: string;
+ * }} options
+ */
+export function createSitemap({ pages, siteOrigin }) {
+  const locations = sitemapPageLocations({ pages, siteOrigin });
+  const urls = locations
+    .map(location => ['  <url>', `    <loc>${escapeXml(location)}</loc>`, '  </url>'].join('\n'))
+    .join('\n');
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    urls,
+    '</urlset>',
+    '',
+  ].join('\n');
+}
+
+/**
+ * @param {{
+ *   pages?: import('@rocket/js/types.js').PageRegistry;
+ *   siteOrigin: string;
+ * }} options
+ */
+export function createRobotsFile({ pages = new Map(), siteOrigin }) {
+  const sitemapUrl = new URL('/sitemap.xml', `${siteOrigin}/`).href;
+  const disallowDirectives = robotsDisallowPaths({ pages })
+    .map(pagePath => `Disallow: ${pagePath}`)
+    .sort();
+
+  if (disallowDirectives.length === 0) {
+    return `Sitemap: ${sitemapUrl}\n`;
+  }
+
+  return ['User-agent: *', ...disallowDirectives, '', `Sitemap: ${sitemapUrl}`, ''].join('\n');
+}
+
+/**
+ * @param {{
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ *   siteOrigin: string;
+ * }} options
+ */
+function sitemapPageLocations({ pages, siteOrigin }) {
+  return Array.from(pages.entries())
+    .filter(([pagePath, page]) => {
+      return !hasPathParameter(pagePath) && page.module.config.discoverability?.sitemap !== false;
+    })
+    .flatMap(([pagePath, page]) => discoverabilityPagePaths({ pages, pagePath, page }))
+    .map(pagePath => absolutePageUrl(siteOrigin, pagePath))
+    .sort();
+}
+
+/**
+ * @param {{
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ * }} options
+ */
+function robotsDisallowPaths({ pages }) {
+  return Array.from(pages.entries())
+    .filter(([, page]) => page.module.config.discoverability?.robots === 'disallow')
+    .flatMap(([pagePath, page]) => discoverabilityPagePaths({ pages, pagePath, page }));
+}
+
+/**
+ * @param {{
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ *   pagePath: string;
+ *   page: import('@rocket/js/types.js').Page;
+ * }} options
+ */
+function discoverabilityPagePaths({ pages, pagePath, page }) {
+  if (!hasPagePagination(page)) {
+    return [pagePath];
+  }
+  return [paginatedArchivePath(pagePath, 1), ...paginatedArchivePaths({ pages, page, pagePath })];
+}
+
+/**
+ * @param {string | undefined} siteOrigin
+ * @param {'Sitemap' | 'Robots File'} outputName
+ */
+function requireSiteOrigin(siteOrigin, outputName) {
+  if (typeof siteOrigin !== 'string' || siteOrigin.trim() === '') {
+    throw new Error(
+      `Site Discoverability ${outputName} requires a Site Origin. ` +
+        `Add siteOrigin: 'https://example.com' to rocket-config.js.`,
+    );
+  }
+  return normalizeSiteOrigin(siteOrigin);
+}
+
+/**
+ * @param {string} siteOrigin
+ */
+function normalizeSiteOrigin(siteOrigin) {
+  let url;
+  try {
+    url = new URL(siteOrigin);
+  } catch {
+    throw invalidSiteOriginError(siteOrigin);
+  }
+
+  if (url.origin === 'null' || url.pathname !== '/' || url.search || url.hash) {
+    throw invalidSiteOriginError(siteOrigin);
+  }
+  return url.origin;
+}
+
+/**
+ * @param {string} siteOrigin
+ */
+function invalidSiteOriginError(siteOrigin) {
+  return new Error(
+    `Invalid Site Origin ${JSON.stringify(siteOrigin)}. ` +
+      `Use an absolute origin such as 'https://example.com'.`,
+  );
+}
+
+/**
+ * @param {string} siteOrigin
+ * @param {string} pagePath
+ */
+function absolutePageUrl(siteOrigin, pagePath) {
+  const pathname = pagePath.startsWith('/') ? pagePath : `/${pagePath}`;
+  return new URL(pathname, `${siteOrigin}/`).href;
+}
+
+/**
+ * @param {string} pagePath
+ */
+function hasPathParameter(pagePath) {
+  return /(^|\/):[^/]+/.test(pagePath);
+}
+
+/**
+ * @param {string} value
+ */
+function escapeXml(value) {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}

package/src/siteHeadMetadata.js

@@ -0,0 +1,69 @@
+/**
+ * @param {{
+ *   config: import('@rocket/js/types.js').SiteHeadMetadataConfig;
+ *   pageMetadata: import('@rocket/js/types.js').PageMetadata;
+ *   pageSiteHeadMetadata?: import('@rocket/js/types.js').PageSiteHeadMetadataConfig;
+ *   defaultSocialPreviewImage?: string;
+ *   pathname: string;
+ *   siteOrigin: string;
+ * }} options
+ * @returns {import('@rocket/js/types.js').SiteHeadMetadata}
+ */
+export function createSiteHeadMetadata({
+  config,
+  pageMetadata,
+  pageSiteHeadMetadata,
+  defaultSocialPreviewImage,
+  pathname,
+  siteOrigin,
+}) {
+  const socialPreviewImage = pageSiteHeadMetadata?.socialPreview?.image
+    ? resolveSocialPreviewImage(pageSiteHeadMetadata.socialPreview.image, pathname, siteOrigin)
+    : defaultSocialPreviewImage;
+  return {
+    siteName: config.siteName,
+    defaultDescription: config.defaultDescription,
+    language: config.language,
+    ...(config.icons ? { icons: config.icons } : {}),
+    ...(config.themeColor ? { themeColor: config.themeColor } : {}),
+    ...(pageSiteHeadMetadata?.indexing ? { indexing: pageSiteHeadMetadata.indexing } : {}),
+    ...(socialPreviewImage ? { socialPreview: { image: socialPreviewImage } } : {}),
+    title: pathname === '/' ? config.siteName : `${pageMetadata.title} | ${config.siteName}`,
+    description: pageMetadata.description || config.defaultDescription,
+    canonicalUrl: new URL(pathname, `${siteOrigin}/`).href,
+  };
+}
+
+/**
+ * @param {string} image
+ * @param {string} pathname
+ * @param {string} siteOrigin
+ */
+function resolveSocialPreviewImage(image, pathname, siteOrigin) {
+  if (isAbsoluteHttpUrl(image)) {
+    return image;
+  }
+  if (image.startsWith('/')) {
+    return new URL(image, `${siteOrigin}/`).href;
+  }
+  return new URL(image, new URL(pageDocumentPath(pathname), `${siteOrigin}/`)).href;
+}
+
+/**
+ * @param {string} value
+ */
+function isAbsoluteHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} pathname
+ */
+function pageDocumentPath(pathname) {
+  return pathname.endsWith('/') ? pathname : `${pathname}/`;
+}