specra 0.2.6 → 0.2.7

package/dist/mdx-cache.js

@@ -6,6 +6,7 @@
  * invalidated automatically when files change.
  */
 import { getVersions, getAllDocs, getDocBySlug } from './mdx';
+import { clearProductCaches } from './config.server';
 import { watch } from 'fs';
 import { join } from 'path';
 import { PerfTimer, logCacheOperation } from './dev-utils';
@@ -36,6 +37,11 @@ function initializeWatchers() {
                 return;
             // Invalidate relevant caches when MDX or JSON files change
             if (filename.endsWith('.mdx') || filename.endsWith('.json')) {
+                // Clear product caches when _product_.json changes
+                if (filename.endsWith('_product_.json')) {
+                    clearProductCaches();
+                    console.log(`[MDX Cache] Product cache invalidated: ${filename}`);
+                }
                 // Extract version from path
                 const parts = filename.split(/[/\\]/);
                 const version = parts[0];
@@ -52,6 +58,7 @@ function initializeWatchers() {
                 // Clear versions cache if directory structure changed
                 if (eventType === 'rename') {
                     versionsCache.data = null;
+                    clearProductCaches();
                 }
                 console.log(`[MDX Cache] Invalidated cache for: ${filename}`);
             }
@@ -69,11 +76,28 @@ function isCacheValid(timestamp) {
     return Date.now() - timestamp < CACHE_TTL;
 }
 /**
- * Cached version of getVersions()
+ * Cached version of getVersions().
+ * When product is provided, uses a separate cache key per product.
  */
-export function getCachedVersions() {
+const productVersionsCache = new Map();
+export function getCachedVersions(product) {
     // Initialize watchers on first use
     initializeWatchers();
+    // For product-scoped versions, use a separate cache
+    if (product && product !== "_default_") {
+        const cached = productVersionsCache.get(product);
+        if (cached && isCacheValid(cached.timestamp)) {
+            logCacheOperation('hit', `versions:${product}`);
+            return cached.data;
+        }
+        logCacheOperation('miss', `versions:${product}`);
+        const timer = new PerfTimer(`getVersions(${product})`);
+        const versions = getVersions(product);
+        timer.end();
+        productVersionsCache.set(product, { data: versions, timestamp: Date.now() });
+        return versions;
+    }
+    // Default product — original cache
     if (versionsCache.data && isCacheValid(versionsCache.timestamp)) {
         logCacheOperation('hit', 'versions');
         return versionsCache.data;
@@ -89,10 +113,11 @@ export function getCachedVersions() {
 /**
  * Cached version of getAllDocs()
  */
-export async function getCachedAllDocs(version = 'v1.0.0', locale) {
+export async function getCachedAllDocs(version = 'v1.0.0', locale, product) {
     // Initialize watchers on first use
     initializeWatchers();
-    const cacheKey = locale ? `${version}:${locale}` : version;
+    const productKey = (product && product !== "_default_") ? product : "_default_";
+    const cacheKey = locale ? `${productKey}:${version}:${locale}` : `${productKey}:${version}`;
     const cached = allDocsCache.get(cacheKey);
     if (cached && isCacheValid(cached.timestamp)) {
         logCacheOperation('hit', `getAllDocs:${cacheKey}`);
@@ -100,7 +125,7 @@ export async function getCachedAllDocs(version = 'v1.0.0', locale) {
     }
     logCacheOperation('miss', `getAllDocs:${cacheKey}`);
     const timer = new PerfTimer(`getAllDocs(${cacheKey})`);
-    const docs = await getAllDocs(version, locale);
+    const docs = await getAllDocs(version, locale, product);
     timer.end();
     allDocsCache.set(cacheKey, {
         data: docs,
@@ -111,10 +136,11 @@ export async function getCachedAllDocs(version = 'v1.0.0', locale) {
 /**
  * Cached version of getDocBySlug()
  */
-export async function getCachedDocBySlug(slug, version = 'v1.0.0') {
+export async function getCachedDocBySlug(slug, version = 'v1.0.0', product) {
     // Initialize watchers on first use
     initializeWatchers();
-    const cacheKey = `${version}:${slug}`;
+    const productKey = (product && product !== "_default_") ? product : "_default_";
+    const cacheKey = `${productKey}:${version}:${slug}`;
     const cached = docBySlugCache.get(cacheKey);
     if (cached && isCacheValid(cached.timestamp)) {
         logCacheOperation('hit', `getDocBySlug:${cacheKey}`);
@@ -122,7 +148,7 @@ export async function getCachedDocBySlug(slug, version = 'v1.0.0') {
     }
     logCacheOperation('miss', `getDocBySlug:${cacheKey}`);
     const timer = new PerfTimer(`getDocBySlug(${slug})`);
-    const doc = await getDocBySlug(slug, version);
+    const doc = await getDocBySlug(slug, version, undefined, product);
     timer.end();
     docBySlugCache.set(cacheKey, {
         data: doc,
@@ -136,8 +162,10 @@ export async function getCachedDocBySlug(slug, version = 'v1.0.0') {
  */
 export function clearAllCaches() {
     versionsCache.data = null;
+    productVersionsCache.clear();
     allDocsCache.clear();
     docBySlugCache.clear();
+    clearProductCaches();
     console.log('[MDX Cache] All caches cleared');
 }
 /**

package/dist/mdx.d.ts

@@ -58,10 +58,15 @@ export interface TocItem {
     title: string;
     level: number;
 }
-export declare function getVersions(): string[];
+export declare function getVersions(product?: string): string[];
+/**
+ * Get versions scoped to a specific product.
+ * Convenience wrapper around getVersions() for product-aware code.
+ */
+export declare function getProductVersions(product: string): string[];
 export declare function getI18nConfig(): I18nConfig | null;
-export declare function getDocBySlug(slug: string, version?: string, locale?: string): Promise<Doc | null>;
-export declare function getAllDocs(version?: string, locale?: string): Doc[];
+export declare function getDocBySlug(slug: string, version?: string, locale?: string, product?: string): Promise<Doc | null>;
+export declare function getAllDocs(version?: string, locale?: string, product?: string): Doc[];
 export declare function getAdjacentDocs(currentSlug: string, allDocs: Doc[]): {
     previous?: Doc;
     next?: Doc;

package/dist/mdx.js

@@ -16,6 +16,17 @@ import { sortSidebarItems, sortSidebarGroups, buildSidebarStructure } from "./si
 import { sanitizePath, validatePathWithinDirectory, validateMDXSecurity } from "./mdx-security";
 import { getConfig } from "./config";
 const DOCS_DIR = path.join(process.cwd(), "docs");
+/**
+ * Resolve the docs directory for a given version and optional product.
+ * - Default product or omitted: docs/{version}/
+ * - Named product: docs/{product}/{version}/
+ */
+function resolveDocsPath(version, product) {
+    if (product && product !== "_default_") {
+        return path.join(DOCS_DIR, product, version);
+    }
+    return path.join(DOCS_DIR, version);
+}
 /**
  * Map of lowercased HTML tag names to PascalCase component names.
  * When rehype processes MDX, it lowercases all custom tags.
@@ -981,15 +992,35 @@ function calculateReadingTime(content) {
     const minutes = Math.ceil(words / 200);
     return { minutes, words };
 }
-export function getVersions() {
+export function getVersions(product) {
     try {
-        const versions = fs.readdirSync(DOCS_DIR);
-        return versions.filter((v) => fs.statSync(path.join(DOCS_DIR, v)).isDirectory());
+        const baseDir = (product && product !== "_default_")
+            ? path.join(DOCS_DIR, product)
+            : DOCS_DIR;
+        const entries = fs.readdirSync(baseDir);
+        return entries.filter((v) => {
+            if (!fs.statSync(path.join(baseDir, v)).isDirectory())
+                return false;
+            // In the default product's base dir, skip product directories (those with _product_.json)
+            if (!product || product === "_default_") {
+                const hasProductJson = fs.existsSync(path.join(baseDir, v, "_product_.json"));
+                if (hasProductJson)
+                    return false;
+            }
+            return true;
+        });
     }
     catch (error) {
         return ["v1.0.0"];
     }
 }
+/**
+ * Get versions scoped to a specific product.
+ * Convenience wrapper around getVersions() for product-aware code.
+ */
+export function getProductVersions(product) {
+    return getVersions(product);
+}
 /**
  * Recursively find all MDX files in a directory
  */
@@ -1094,7 +1125,7 @@ export function getI18nConfig() {
     }
     return i18n;
 }
-export async function getDocBySlug(slug, version = "v1.0.0", locale) {
+export async function getDocBySlug(slug, version = "v1.0.0", locale, product) {
     try {
         // Security: Sanitize and validate slug
         const sanitizedVersion = sanitizePath(version);
@@ -1117,8 +1148,8 @@ export async function getDocBySlug(slug, version = "v1.0.0", locale) {
         // Try finding the file in this order:
         // 1. Localized extension: slug.locale.mdx (e.g. guide.fr.mdx)
         // 2. Default file: slug.mdx (only if using default locale and configured to fallback or strictly default)
-        // Construct potential paths
-        const basePath = path.join(DOCS_DIR, sanitizedVersion);
+        // Construct potential paths — product-aware
+        const basePath = resolveDocsPath(sanitizedVersion, product);
         let result = null;
         // 1. Try localized file extension
         if (targetLocale) {
@@ -1156,9 +1187,9 @@ export async function getDocBySlug(slug, version = "v1.0.0", locale) {
         return null;
     }
 }
-export function getAllDocs(version = "v1.0.0", locale) {
+export function getAllDocs(version = "v1.0.0", locale, product) {
     try {
-        const versionDir = path.join(DOCS_DIR, version);
+        const versionDir = resolveDocsPath(version, product);
         if (!fs.existsSync(versionDir)) {
             return [];
         }
@@ -1166,7 +1197,7 @@ export function getAllDocs(version = "v1.0.0", locale) {
         const i18nConfig = getI18nConfig();
         const targetLocale = locale || i18nConfig?.defaultLocale || 'en';
         const mdxFiles = findMdxFiles(versionDir);
-        const categoryConfigs = getAllCategoryConfigs(version);
+        const categoryConfigs = getAllCategoryConfigs(version, product);
         const docs = mdxFiles.map((file) => {
             // file contains path relative to version dir, e.g. "getting-started/intro.mdx" or "intro.fr.mdx"
             let originalFilePath = file.replace(/\.mdx$/, "");

package/dist/redirects.d.ts

@@ -3,7 +3,8 @@ export interface RedirectMapping {
     to: string;
 }
 /**
- * Build redirect mappings from all docs' redirect_from frontmatter
+ * Build redirect mappings from all docs' redirect_from frontmatter.
+ * In multi-product mode, generates product-aware redirect URLs.
  */
 export declare function buildRedirectMappings(): Promise<RedirectMapping[]>;
 /**

package/dist/redirects.js

@@ -1,19 +1,45 @@
 import { getAllDocs, getVersions } from "./mdx";
+import { getProducts } from "./config.server";
 /**
- * Build redirect mappings from all docs' redirect_from frontmatter
+ * Build redirect mappings from all docs' redirect_from frontmatter.
+ * In multi-product mode, generates product-aware redirect URLs.
  */
 export async function buildRedirectMappings() {
-    const versions = getVersions();
     const redirects = [];
-    for (const version of versions) {
-        const docs = await getAllDocs(version);
-        for (const doc of docs) {
-            if (doc.meta.redirect_from && Array.isArray(doc.meta.redirect_from)) {
-                for (const oldPath of doc.meta.redirect_from) {
-                    redirects.push({
-                        from: oldPath,
-                        to: `/docs/${version}/${doc.slug}`,
-                    });
+    const products = getProducts();
+    if (products.length === 0) {
+        // Single-product mode — current behavior
+        const versions = getVersions();
+        for (const version of versions) {
+            const docs = await getAllDocs(version);
+            for (const doc of docs) {
+                if (doc.meta.redirect_from && Array.isArray(doc.meta.redirect_from)) {
+                    for (const oldPath of doc.meta.redirect_from) {
+                        redirects.push({
+                            from: oldPath,
+                            to: `/docs/${version}/${doc.slug}`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    else {
+        // Multi-product mode
+        for (const product of products) {
+            const versions = getVersions(product.isDefault ? undefined : product.slug);
+            const urlPrefix = product.isDefault ? "/docs" : `/docs/${product.slug}`;
+            for (const version of versions) {
+                const docs = await getAllDocs(version, undefined, product.isDefault ? undefined : product.slug);
+                for (const doc of docs) {
+                    if (doc.meta.redirect_from && Array.isArray(doc.meta.redirect_from)) {
+                        for (const oldPath of doc.meta.redirect_from) {
+                            redirects.push({
+                                from: oldPath,
+                                to: `${urlPrefix}/${version}/${doc.slug}`,
+                            });
+                        }
+                    }
                 }
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specra",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "A modern documentation library for SvelteKit with built-in versioning, API reference generation, full-text search, and MDX support",
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",