@uniweb/build 0.3.2 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -50,8 +50,8 @@
     "sharp": "^0.33.2"
   },
   "optionalDependencies": {
-    "@uniweb/content-reader": "1.0.8",
-    "@uniweb/runtime": "0.4.3"
+    "@uniweb/content-reader": "1.1.1",
+    "@uniweb/runtime": "0.5.0"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -60,7 +60,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.2.5"
+    "@uniweb/core": "0.3.1"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/collections.js

@@ -9,6 +9,7 @@ import { readFile, writeFile, readdir, mkdir } from 'fs/promises'
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { computeHash } from './hash.js'
+import { loadFreeformCollectionItem } from './freeform.js'
 
 export const COLLECTIONS_DIR = 'collections'
 
@@ -198,13 +199,16 @@ function addUnit(units, source, field, context) {
  * Merge translations into collection data and write locale-specific files
  * @param {string} siteRoot - Site root directory
  * @param {Object} options - Options
+ * @param {boolean} [options.freeformEnabled=true] - Enable free-form translation support
  * @returns {Promise<Object>} Map of locale to output paths
  */
 export async function buildLocalizedCollections(siteRoot, options = {}) {
   const {
     locales = [],
     outputDir = join(siteRoot, 'dist'),
-    collectionsLocalesDir = join(siteRoot, 'locales', COLLECTIONS_DIR)
+    collectionsLocalesDir = join(siteRoot, 'locales', COLLECTIONS_DIR),
+    localesDir = join(siteRoot, 'locales'),
+    freeformEnabled = true
   } = options
 
   const dataDir = join(siteRoot, 'public', 'data')
@@ -240,6 +244,10 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
       }
     }
 
+    // Check if free-form translations exist for this locale
+    const freeformDir = join(localesDir, 'freeform', locale)
+    const hasFreeform = freeformEnabled && existsSync(freeformDir)
+
     // Create locale data directory
     const localeDataDir = join(outputDir, locale, 'data')
     await mkdir(localeDataDir, { recursive: true })
@@ -262,9 +270,15 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
           continue
         }
 
-        // Translate each item
-        const translatedItems = items.map(item =>
-          translateItem(item, collectionName, translations)
+        // Translate each item (with free-form support)
+        const translatedItems = await Promise.all(
+          items.map(item =>
+            translateItemAsync(item, collectionName, translations, {
+              locale,
+              localesDir,
+              freeformEnabled: hasFreeform
+            })
+          )
         )
 
         const destPath = join(localeDataDir, file)
@@ -280,13 +294,69 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
 }
 
 /**
- * Apply translations to a collection item
+ * Apply translations to a collection item (async, with free-form support)
+ *
+ * Resolution order:
+ * 1. Check for free-form translation (complete or partial replacement)
+ * 2. Fall back to hash-based translation
+ *
+ * @param {Object} item - Collection item
+ * @param {string} collectionName - Name of the collection
+ * @param {Object} translations - Hash-based translations
+ * @param {Object} options - Options
+ * @returns {Promise<Object>} Translated item
  */
-function translateItem(item, collectionName, translations) {
+async function translateItemAsync(item, collectionName, translations, options = {}) {
+  const { locale, localesDir, freeformEnabled } = options
   const translated = { ...item }
   const slug = item.slug || 'unknown'
   const context = { collection: collectionName, item: slug }
 
+  // Check for free-form translation first
+  if (freeformEnabled && locale && localesDir) {
+    const freeform = await loadFreeformCollectionItem(item, collectionName, locale, localesDir)
+
+    if (freeform) {
+      // Merge free-form data (supports partial: frontmatter only, body only, or both)
+      if (freeform.frontmatter) {
+        // Merge frontmatter fields from free-form
+        Object.assign(translated, freeform.frontmatter)
+      }
+      if (freeform.content) {
+        // Replace content entirely with free-form content
+        translated.content = freeform.content
+        // Skip hash-based content translation since we have free-form
+        return translateItemFields(translated, context, translations)
+      }
+    }
+  }
+
+  // Fall back to hash-based translation (or continue after partial free-form)
+  return translateItemSync(translated, collectionName, translations)
+}
+
+/**
+ * Apply translations to a collection item (sync, hash-based only)
+ */
+function translateItemSync(item, collectionName, translations) {
+  const translated = { ...item }
+  const slug = item.slug || 'unknown'
+  const context = { collection: collectionName, item: slug }
+
+  // Translate all fields including content
+  return translateItemFields(translated, context, translations, true)
+}
+
+/**
+ * Translate item fields (frontmatter and optionally content)
+ *
+ * @param {Object} translated - Item being translated
+ * @param {Object} context - Translation context
+ * @param {Object} translations - Hash-based translations
+ * @param {boolean} includeContent - Whether to translate ProseMirror content
+ * @returns {Object} Translated item
+ */
+function translateItemFields(translated, context, translations, includeContent = false) {
   // Translate frontmatter fields
   const translatableFields = ['title', 'description', 'excerpt', 'summary', 'subtitle']
 
@@ -320,8 +390,8 @@ function translateItem(item, collectionName, translations) {
     })
   }
 
-  // Translate ProseMirror content
-  if (translated.content?.type === 'doc') {
+  // Translate ProseMirror content (only if requested)
+  if (includeContent && translated.content?.type === 'doc') {
     translated.content = translateProseMirrorDoc(
       translated.content,
       context,
@@ -332,6 +402,14 @@ function translateItem(item, collectionName, translations) {
   return translated
 }
 
+/**
+ * Apply translations to a collection item (legacy sync function)
+ * @deprecated Use translateItemAsync for free-form support
+ */
+function translateItem(item, collectionName, translations) {
+  return translateItemSync(item, collectionName, translations)
+}
+
 /**
  * Translate a ProseMirror document
  */

package/src/i18n/freeform-manifest.js

@@ -0,0 +1,307 @@
+/**
+ * Free-form Translation Manifest Management
+ *
+ * Tracks source content hashes for free-form translations to detect
+ * when source content changes (staleness). The manifest lives at:
+ *   locales/freeform/{locale}/.manifest.json
+ *
+ * Manifest format:
+ * {
+ *   "pages/about/hero.md": { "hash": "a1b2c3d4", "recorded": "2025-01-28" },
+ *   "page-ids/installation/intro.md": { "hash": "b2c3d4e5", "recorded": "2025-01-25" },
+ *   "collections/articles/getting-started.md": { "hash": "c3d4e5f6", "recorded": "2025-01-27" }
+ * }
+ */
+
+import { readFile, writeFile, mkdir } from 'fs/promises'
+import { existsSync } from 'fs'
+import { join, dirname } from 'path'
+import { createHash } from 'crypto'
+
+const MANIFEST_FILENAME = '.manifest.json'
+
+/**
+ * Compute a hash of a ProseMirror document for staleness detection
+ *
+ * Extracts text content and computes a hash that changes when
+ * the content changes (ignoring formatting-only changes).
+ *
+ * @param {Object} doc - ProseMirror document
+ * @returns {string} 8-character hex hash
+ */
+export function computeSourceHash(doc) {
+  if (!doc) return ''
+
+  // Extract all text content from the document
+  const textContent = extractTextFromDoc(doc)
+
+  // Hash the normalized text
+  return createHash('sha256')
+    .update(textContent)
+    .digest('hex')
+    .slice(0, 8)
+}
+
+/**
+ * Recursively extract text from a ProseMirror document
+ * @param {Object} node - ProseMirror node
+ * @returns {string} Concatenated text content
+ */
+function extractTextFromDoc(node) {
+  if (!node) return ''
+
+  if (node.type === 'text') {
+    return node.text || ''
+  }
+
+  if (!node.content || !Array.isArray(node.content)) {
+    return ''
+  }
+
+  return node.content.map(extractTextFromDoc).join(' ')
+}
+
+/**
+ * Get the manifest path for a locale
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @returns {string} Path to manifest file
+ */
+function getManifestPath(localeDir) {
+  return join(localeDir, MANIFEST_FILENAME)
+}
+
+/**
+ * Load the manifest for a locale
+ *
+ * @param {string} localeDir - Path to locale's freeform directory (locales/freeform/{locale})
+ * @returns {Promise<Object>} Manifest object (empty if not found)
+ */
+export async function loadManifest(localeDir) {
+  const manifestPath = getManifestPath(localeDir)
+
+  if (!existsSync(manifestPath)) {
+    return {}
+  }
+
+  try {
+    const content = await readFile(manifestPath, 'utf-8')
+    return JSON.parse(content)
+  } catch (err) {
+    console.warn(`[i18n] Failed to load manifest ${manifestPath}: ${err.message}`)
+    return {}
+  }
+}
+
+/**
+ * Save the manifest for a locale
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {Object} manifest - Manifest object to save
+ */
+export async function saveManifest(localeDir, manifest) {
+  const manifestPath = getManifestPath(localeDir)
+
+  // Ensure directory exists
+  if (!existsSync(localeDir)) {
+    await mkdir(localeDir, { recursive: true })
+  }
+
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2))
+}
+
+/**
+ * Record a source hash in the manifest
+ *
+ * Called when a new free-form translation is created to record
+ * the hash of the source content at that time.
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string} relativePath - Path relative to locale dir (e.g., 'pages/about/hero.md')
+ * @param {string} sourceHash - Hash of the source content
+ * @returns {Promise<void>}
+ */
+export async function recordHash(localeDir, relativePath, sourceHash) {
+  const manifest = await loadManifest(localeDir)
+
+  manifest[relativePath] = {
+    hash: sourceHash,
+    recorded: new Date().toISOString().split('T')[0] // YYYY-MM-DD
+  }
+
+  await saveManifest(localeDir, manifest)
+}
+
+/**
+ * Check if a translation is stale (source content changed)
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string} relativePath - Path relative to locale dir
+ * @param {string} currentSourceHash - Current hash of source content
+ * @returns {Promise<Object>} { isStale, recordedHash, recordedDate, currentHash }
+ */
+export async function checkStaleness(localeDir, relativePath, currentSourceHash) {
+  const manifest = await loadManifest(localeDir)
+  const entry = manifest[relativePath]
+
+  if (!entry) {
+    // No recorded hash - translation was never registered
+    return {
+      isStale: false, // Not stale, just unregistered
+      isNew: true,
+      recordedHash: null,
+      recordedDate: null,
+      currentHash: currentSourceHash
+    }
+  }
+
+  const isStale = entry.hash !== currentSourceHash
+
+  return {
+    isStale,
+    isNew: false,
+    recordedHash: entry.hash,
+    recordedDate: entry.recorded,
+    currentHash: currentSourceHash
+  }
+}
+
+/**
+ * Update the hash for a translation (after translator reviews changes)
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string} relativePath - Path relative to locale dir
+ * @param {string} newHash - New hash to record
+ * @returns {Promise<void>}
+ */
+export async function updateHash(localeDir, relativePath, newHash) {
+  return recordHash(localeDir, relativePath, newHash)
+}
+
+/**
+ * Remove entries from the manifest
+ *
+ * Used when translations are deleted.
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string[]} paths - Paths to remove
+ * @returns {Promise<number>} Number of entries removed
+ */
+export async function removeManifestEntries(localeDir, paths) {
+  const manifest = await loadManifest(localeDir)
+  let removed = 0
+
+  for (const path of paths) {
+    if (manifest[path]) {
+      delete manifest[path]
+      removed++
+    }
+  }
+
+  if (removed > 0) {
+    await saveManifest(localeDir, manifest)
+  }
+
+  return removed
+}
+
+/**
+ * Rename entries in the manifest
+ *
+ * Used when translations are moved/renamed.
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string[]} oldPaths - Old paths
+ * @param {string[]} newPaths - New paths (same order as oldPaths)
+ * @returns {Promise<number>} Number of entries renamed
+ */
+export async function renameManifestEntries(localeDir, oldPaths, newPaths) {
+  if (oldPaths.length !== newPaths.length) {
+    throw new Error('oldPaths and newPaths must have the same length')
+  }
+
+  const manifest = await loadManifest(localeDir)
+  let renamed = 0
+
+  for (let i = 0; i < oldPaths.length; i++) {
+    const oldPath = oldPaths[i]
+    const newPath = newPaths[i]
+
+    if (manifest[oldPath]) {
+      manifest[newPath] = manifest[oldPath]
+      delete manifest[oldPath]
+      renamed++
+    }
+  }
+
+  if (renamed > 0) {
+    await saveManifest(localeDir, manifest)
+  }
+
+  return renamed
+}
+
+/**
+ * Get all stale translations for a locale
+ *
+ * Compares manifest hashes against current source content.
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {Object} sourceHashes - Map of relativePath → currentHash
+ * @returns {Promise<Object[]>} Array of { path, recordedHash, recordedDate, currentHash }
+ */
+export async function getStaleTranslations(localeDir, sourceHashes) {
+  const manifest = await loadManifest(localeDir)
+  const stale = []
+
+  for (const [path, entry] of Object.entries(manifest)) {
+    const currentHash = sourceHashes[path]
+
+    // If we have a current hash and it differs, it's stale
+    if (currentHash && currentHash !== entry.hash) {
+      stale.push({
+        path,
+        recordedHash: entry.hash,
+        recordedDate: entry.recorded,
+        currentHash
+      })
+    }
+  }
+
+  return stale
+}
+
+/**
+ * Get orphaned translations (translations without source)
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {Set<string>} validPaths - Set of valid translation paths that have source content
+ * @returns {Promise<Object[]>} Array of { path, recordedHash, recordedDate }
+ */
+export async function getOrphanedTranslations(localeDir, validPaths) {
+  const manifest = await loadManifest(localeDir)
+  const orphaned = []
+
+  for (const [path, entry] of Object.entries(manifest)) {
+    if (!validPaths.has(path)) {
+      orphaned.push({
+        path,
+        recordedHash: entry.hash,
+        recordedDate: entry.recorded
+      })
+    }
+  }
+
+  return orphaned
+}
+
+/**
+ * Get unregistered translations (translations without manifest entry)
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string[]} translationPaths - All translation file paths found
+ * @returns {Promise<string[]>} Paths that exist as files but not in manifest
+ */
+export async function getUnregisteredTranslations(localeDir, translationPaths) {
+  const manifest = await loadManifest(localeDir)
+  return translationPaths.filter(path => !manifest[path])
+}