@uniweb/projections 0.1.1

package/src/search/generate.js

@@ -0,0 +1,154 @@
+/**
+ * Generate search index from site content
+ *
+ * Creates a JSON search index file that can be loaded at runtime
+ * for client-side search functionality.
+ */
+
+// The leaf subpath, not the bare `@uniweb/core` entry: the package root pulls
+// in `@uniweb/semantic-parser`, which would put this package's environment
+// contract at the mercy of a transitive dependency. `locale-config` has
+// zero imports of its own.
+import { resolveDefaultLocale } from '@uniweb/core/locale-config'
+import { extractSearchContent } from './extract.js'
+
+/**
+ * Generate search index for a site
+ * @param {Object} siteContent - Parsed site-content.json
+ * @param {Object} options - Generation options
+ * @param {string} [options.locale] - Locale code for this index
+ * @param {Object} [options.extract] - Options passed to extractSearchContent
+ * @param {Object} [options.search] - Search configuration from site.yml
+ * @returns {Object} Search index object
+ */
+export function generateSearchIndex(siteContent, options = {}) {
+  const {
+    locale = siteContent.config?.activeLocale || resolveDefaultLocale(siteContent.config),
+    extract: extractOptions = {},
+    search: searchConfig = {}
+  } = options
+
+  // Merge search config with extract options
+  const mergedExtractOptions = {
+    ...extractOptions,
+    excludeRoutes: searchConfig.exclude?.routes || extractOptions.excludeRoutes || [],
+    excludeComponents: searchConfig.exclude?.components || extractOptions.excludeComponents || []
+  }
+
+  // Check what to include from config
+  if (searchConfig.include) {
+    mergedExtractOptions.pages = searchConfig.include.pages !== false
+    mergedExtractOptions.sections = searchConfig.include.sections !== false
+    mergedExtractOptions.headings = searchConfig.include.headings !== false
+    mergedExtractOptions.paragraphs = searchConfig.include.paragraphs !== false
+    mergedExtractOptions.links = searchConfig.include.links !== false
+    mergedExtractOptions.lists = searchConfig.include.lists !== false
+  }
+
+  // Extract searchable content
+  const entries = extractSearchContent(siteContent, mergedExtractOptions)
+
+  // Build the index.
+  //
+  // Deliberately no `generated` timestamp. A clock in a derived artifact
+  // cannot be content-addressed: every publish produces different bytes, so a
+  // content-addressed asset store never recognizes an unchanged index and
+  // re-uploads it forever. It also breaks byte-parity between publishers,
+  // which is the property this package exists to guarantee. Nothing read the
+  // field. If a freshness signal is ever needed it belongs in delivery
+  // metadata, not in the artifact.
+  const index = {
+    version: '1.0',
+    locale,
+    count: entries.length,
+    entries
+  }
+
+  return index
+}
+
+/**
+ * Merge a pages index with collection indexes into the single-file form.
+ *
+ * Two layouts exist because two consumers want different things, and neither
+ * is wrong:
+ *
+ * - **Split** (`_search/{locale}/pages.json` + `{name}.json`) suits a *server*
+ *   that loads only the parts a query needs.
+ * - **Merged** (`search-index.json`) suits a *browser* that needs all of it —
+ *   one request rather than N+1, and no manifest to discover the parts from.
+ *
+ * The bug was never that both exist; it was that a lane emitted only one of
+ * them while a consumer of the other was pointed at it. Emitting both from the
+ * same entries costs a serialization, keeps the client working on every lane
+ * with no configuration, and means a host declaring search never has to
+ * describe *where the index lives* — only whether it serves queries.
+ *
+ * @param {Object} pagesIndex - Result of {@link generateSearchIndex}
+ * @param {Object[]} [collectionIndexes] - Results of `generateCollectionIndex`
+ * @returns {Object} One index carrying every entry
+ */
+export function mergeSearchIndexes(pagesIndex, collectionIndexes = []) {
+  const entries = [
+    ...(pagesIndex?.entries || []),
+    ...collectionIndexes.flatMap(index => index?.entries || [])
+  ]
+
+  return {
+    version: pagesIndex?.version || '1.0',
+    locale: pagesIndex?.locale,
+    count: entries.length,
+    entries
+  }
+}
+
+/**
+ * Check if search is enabled for a site
+ * @param {Object} siteContent - Parsed site-content.json
+ * @returns {boolean}
+ */
+export function isSearchEnabled(siteContent) {
+  // Search is enabled by default unless explicitly disabled
+  return siteContent.config?.search?.enabled !== false
+}
+
+/**
+ * Get search configuration from site content
+ * @param {Object} siteContent - Parsed site-content.json
+ * @returns {Object} Search configuration
+ */
+export function getSearchConfig(siteContent) {
+  const config = siteContent.config?.search || {}
+
+  return {
+    enabled: config.enabled !== false,
+    include: {
+      pages: config.include?.pages !== false,
+      sections: config.include?.sections !== false,
+      headings: config.include?.headings !== false,
+      paragraphs: config.include?.paragraphs !== false,
+      links: config.include?.links !== false,
+      lists: config.include?.lists !== false
+    },
+    exclude: {
+      routes: config.exclude?.routes || [],
+      components: config.exclude?.components || []
+    }
+  }
+}
+
+/**
+ * Get the search index filename for a locale
+ * @param {string} locale - Locale code
+ * @param {string} defaultLocale - Default locale code
+ * @returns {string} Filename
+ */
+export function getSearchIndexFilename(locale, defaultLocale) {
+  // Default locale uses root filename, others use locale prefix path
+  if (locale === defaultLocale) {
+    return 'search-index.json'
+  }
+  return `${locale}/search-index.json`
+}
+
+export default generateSearchIndex

package/src/search/index.js

@@ -0,0 +1,46 @@
+/**
+ * Search Index Generation Module
+ *
+ * Generates search indexes for Uniweb sites — a projection of the site's
+ * authored content, in the same family as the agent index and the per-page
+ * markdown. The generated indexes can be loaded at runtime for client-side
+ * search.
+ *
+ * Moved here from `@uniweb/build` so that **one implementation serves every
+ * publisher**. The code was always portable (no imports beyond a
+ * zero-dependency locale helper); what made sharing unsafe was the package it
+ * lived in, whose identity pulls Vite and Node APIs — which is why a second
+ * copy of this logic was hand-maintained elsewhere and drifted from it.
+ * `@uniweb/build` re-exports this module, so existing call sites are unchanged.
+ *
+ * @module @uniweb/projections/search
+ *
+ * @example
+ * import { generateSearchIndex, isSearchEnabled } from '@uniweb/projections/search'
+ *
+ * // Check if search is enabled
+ * if (isSearchEnabled(siteContent)) {
+ *   // Generate index for current locale
+ *   const index = generateSearchIndex(siteContent, {
+ *     locale: 'en'
+ *   })
+ *
+ *   // Write to file
+ *   writeFileSync('dist/search-index.json', JSON.stringify(index))
+ * }
+ */
+
+export {
+  extractSearchContent,
+  extractSearchContent as default
+} from './extract.js'
+
+export {
+  generateSearchIndex,
+  mergeSearchIndexes,
+  isSearchEnabled,
+  getSearchConfig,
+  getSearchIndexFilename
+} from './generate.js'
+
+export { generateCollectionIndex } from './collections.js'

package/src/site-index.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview The discovery projection: an annotated index of the site.
+ *
+ * Answers the question an agent cannot answer by guessing — "does this page
+ * exist, and where?" — and answers it with meaning attached, so the agent can
+ * pick a page rather than fetch several to find out.
+ *
+ * Follows the external `llms.txt` convention: H1 title, blockquote summary,
+ * `##` groups of annotated links. Link targets are the `.md` projections, so
+ * following an entry is one hop rather than a fetch-then-strip.
+ */
+
+import { groupPagesForIndex, buildPageUrl } from './pages.js'
+import { resolvePageDescription } from './description.js'
+
+/** Heading for pages that sit under no container. */
+const ROOT_GROUP_TITLE = 'Pages'
+
+/**
+ * Render the agent index for one locale of a site.
+ *
+ * @param {Object} siteContent - Parsed site-content.json (one locale)
+ * @param {Object} [options]
+ * @param {string} [options.baseUrl] - Site origin; links are root-relative without it
+ * @param {string} [options.basePath] - Subdirectory deploy prefix
+ * @param {string} [options.locale] - Locale being rendered
+ * @param {string} [options.defaultLocale] - Locale served at the root
+ * @param {string[]} [options.exclude] - Additional excluded route prefixes
+ * @param {string} [options.title] - Override the site title
+ * @param {string} [options.description] - Override the site summary
+ * @param {string} [options.rootGroupTitle] - Heading for ungrouped pages
+ * @param {number} [options.maxDescriptionChars=200]
+ * @returns {string} The index document
+ */
+export function renderSiteIndex(siteContent, options = {}) {
+  const config = siteContent?.config || {}
+  const {
+    baseUrl = config.seo?.baseUrl || '',
+    basePath = '',
+    locale = config.activeLocale,
+    defaultLocale,
+    exclude = [],
+    title = config.title || config.name || 'Site',
+    description = config.description || '',
+    rootGroupTitle = ROOT_GROUP_TITLE,
+    maxDescriptionChars = 200,
+  } = options
+
+  const urlOptions = {
+    baseUrl,
+    basePath,
+    locale,
+    defaultLocale,
+    routeTranslations: config.i18n?.routeTranslations,
+  }
+
+  const lines = [`# ${title}`]
+
+  if (description) {
+    lines.push('', ...blockquote(description))
+  }
+
+  const groups = groupPagesForIndex(siteContent?.pages, { exclude })
+
+  for (const group of groups) {
+    const entries = group.pages
+      .map(page => renderEntry(page, urlOptions, maxDescriptionChars))
+      .filter(Boolean)
+    if (!entries.length) continue
+
+    lines.push('', `## ${group.heading || rootGroupTitle}`, '', ...entries)
+  }
+
+  return `${lines.join('\n')}\n`
+}
+
+/**
+ * One `- [Title](url): description` entry.
+ *
+ * @param {Object} page
+ * @param {Object} urlOptions
+ * @param {number} maxChars
+ * @returns {string}
+ */
+function renderEntry(page, urlOptions, maxChars) {
+  const title = page.title || page.label || page.route
+  if (!title) return ''
+
+  const url = buildPageUrl(page.route, urlOptions)
+  const description = resolvePageDescription(page, { maxChars })
+
+  return description
+    ? `- [${title}](${url}): ${description}`
+    : `- [${title}](${url})`
+}
+
+/**
+ * Wrap a summary as a markdown blockquote, one line per source line.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function blockquote(text) {
+  return text
+    .trim()
+    .split('\n')
+    .map(line => `> ${line}`.trimEnd())
+}