@translation-cms/sync 1.2.9 → 1.2.12

package/dist/core/api-internals/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/core/api-internals/sync.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAgB,MAAM,YAAY,CAAC;AAYlE;;;GAGG;AACH,wBAAsB,UAAU,CAC5B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,YAAY,EACxB,IAAI,GAAE,iBAA2C,GAClD,OAAO,CAAC,IAAI,CAAC,CA+Hf"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/core/api-internals/sync.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAgB,MAAM,YAAY,CAAC;AAYlE;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC5B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,YAAY,EACxB,IAAI,GAAE,iBAA2C,GAClD,OAAO,CAAC,IAAI,CAAC,CAwIf"}

package/dist/core/api-internals/sync.js

@@ -4,10 +4,18 @@
 import { loadSyncCache, saveSyncCache, isSyncNeeded, computeDiff, writeReport, serializeNamespaces, formatPreviewRoutes, } from '../cache.js';
 import { resolveReportPath } from './helpers.js';
 /**
- * Push translation keys to the CMS for syncing.
- * Optionally supports dry-run mode and report generation.
+ * Push discovered translation keys to the CMS sync endpoint.
+ *
+ * Three possible outcomes:
+ *  1. **Dry-run** (`opts.dryRun`) — prints a diff against the last cache and
+ *     optionally writes a report, but never POSTs to the CMS.
+ *  2. **No changes** — skips the POST when the serialized keys are identical
+ *     to the last cache and `--force` was not passed.
+ *  3. **Sync** — POSTs the full namespace map; on success saves the new cache
+ *     and optionally writes a report.
  */
 export async function postToSync(config, namespaces, opts = { root: process.cwd() }) {
+    // Flatten NamespaceMap → plain serializable object for the API payload and cache
     const { serialized, totalKeys } = serializeNamespaces(namespaces);
     const namespaceCount = Object.keys(serialized).length;
     console.log(`Found ${totalKeys} key(s) across ${namespaceCount} namespace(s): ${Object.keys(serialized).join(', ')}`);
@@ -15,6 +23,7 @@ export async function postToSync(config, namespaces, opts = { root: process.cwd(
         console.log('Nothing to sync.');
         return;
     }
+    // Load the baseline from the last successful sync to diff against
     const cached = loadSyncCache(opts.root);
     // ---- Dry-run: print diff and return without posting --------------------
     if (opts.dryRun) {
@@ -48,14 +57,18 @@ export async function postToSync(config, namespaces, opts = { root: process.cwd(
         return;
     }
     // ---- Skip if no changes ------------------------------------------------
+    // isSyncNeeded compares serialized keys against the cache — if identical,
+    // there's nothing new for the CMS to process.
     if (!opts.force && !isSyncNeeded(serialized, cached)) {
         console.log('No changes detected — skipping sync. Use --force to override.');
         if (opts.reportPath) {
+            // Write a report even when skipping so CI artefacts stay up-to-date
             writeReport(resolveReportPath(opts.root, opts.reportPath), serialized);
         }
         return;
     }
     // ---- Post to CMS -------------------------------------------------------
+    // Strip trailing slash to avoid double slashes in the URL
     const url = `${config.cmsUrl.replace(/\/$/, '')}/api/sync/${config.projectId}`;
     console.log(`Posting to ${url}...`);
     const response = await fetch(url, {
@@ -70,6 +83,7 @@ export async function postToSync(config, namespaces, opts = { root: process.cwd(
     const isJson = contentType.includes('application/json');
     if (!response.ok) {
         console.error(`Sync failed: ${response.status} ${response.statusText}`);
+        // HTML response usually means the endpoint doesn't exist (wrong URL / not deployed)
         if (!isJson) {
             console.error(`The CMS returned HTML instead of JSON. Is the sync endpoint available at ${url}?`);
         }
@@ -78,6 +92,7 @@ export async function postToSync(config, namespaces, opts = { root: process.cwd(
         }
         process.exit(1);
     }
+    // A 2xx with an HTML body is also invalid — guard against misconfigured proxies
     if (!isJson) {
         console.error(`The CMS returned HTML instead of JSON. Is the sync endpoint available at ${url}?`);
         process.exit(1);
@@ -86,6 +101,7 @@ export async function postToSync(config, namespaces, opts = { root: process.cwd(
     console.log(`Synced: ${data.created} created, ${data.updated ?? 0} routes updated, ${data.existing} existing`);
     if (data.message)
         console.log(data.message);
+    // Persist the new baseline so subsequent runs can detect changes correctly
     saveSyncCache(opts.root, serialized);
     if (opts.reportPath) {
         const diff = computeDiff(serialized, cached);

package/dist/core/api-internals/sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/core/api-internals/sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/core/api-internals/sync.ts"],"names":[],"mappings":"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"}

package/dist/core/cache-internals/format.d.ts

@@ -1,4 +1,20 @@
 import type { PreviewRoute } from '../scanner.js';
+/**
+ * Format a single PreviewRoute for human-readable output.
+ *
+ * Plain string routes are returned as-is.
+ * Object routes (with params) are rendered as `/path (key=value, …)`.
+ *
+ * @example
+ * formatPreviewRoute('/dashboard')                          // → "/dashboard"
+ * formatPreviewRoute({ route: '/blog/[slug]', params: { slug: 'hello' } })
+ *                                                           // → "/blog/[slug] (slug=hello)"
+ */
 export declare function formatPreviewRoute(route: PreviewRoute): string;
+/**
+ * Format an array of PreviewRoutes as a comma-separated string.
+ * Returns `"no route"` for keys that have no associated preview routes
+ * (e.g. keys inside dialogs or overlays).
+ */
 export declare function formatPreviewRoutes(routes: PreviewRoute[]): string;
 //# sourceMappingURL=format.d.ts.map

package/dist/core/cache-internals/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/core/cache-internals/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQ9D;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAGlE"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/core/cache-internals/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAS9D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAGlE"}

package/dist/core/cache-internals/format.js

@@ -1,6 +1,18 @@
+/**
+ * Format a single PreviewRoute for human-readable output.
+ *
+ * Plain string routes are returned as-is.
+ * Object routes (with params) are rendered as `/path (key=value, …)`.
+ *
+ * @example
+ * formatPreviewRoute('/dashboard')                          // → "/dashboard"
+ * formatPreviewRoute({ route: '/blog/[slug]', params: { slug: 'hello' } })
+ *                                                           // → "/blog/[slug] (slug=hello)"
+ */
 export function formatPreviewRoute(route) {
     if (typeof route === 'string')
         return route;
+    // Append param list only when params are present
     const params = route.params
         ? ` (${Object.entries(route.params)
             .map(([k, v]) => `${k}=${v}`)
@@ -8,6 +20,11 @@ export function formatPreviewRoute(route) {
         : '';
     return `${route.route}${params}`;
 }
+/**
+ * Format an array of PreviewRoutes as a comma-separated string.
+ * Returns `"no route"` for keys that have no associated preview routes
+ * (e.g. keys inside dialogs or overlays).
+ */
 export function formatPreviewRoutes(routes) {
     if (routes.length === 0)
         return 'no route';

package/dist/core/cache-internals/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../src/core/cache-internals/format.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,kBAAkB,CAAC,KAAmB;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM;QACvB,CAAC,CAAC,KAAK,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;aAC5B,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;aAC5B,IAAI,CAAC,IAAI,CAAC,GAAG;QACpB,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,GAAG,KAAK,CAAC,KAAK,GAAG,MAAM,EAAE,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAsB;IACtD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IAC3C,OAAO,MAAM,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC"}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../src/core/cache-internals/format.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAmB;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,iDAAiD;IACjD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM;QACvB,CAAC,CAAC,KAAK,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;aAC5B,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;aAC5B,IAAI,CAAC,IAAI,CAAC,GAAG;QACpB,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,GAAG,KAAK,CAAC,KAAK,GAAG,MAAM,EAAE,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAsB;IACtD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IAC3C,OAAO,MAAM,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC"}

package/dist/core/cache-internals/params.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../../src/core/cache-internals/params.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA+CpD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,MAAM,EAAE,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAexC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAU3E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC/C,IAAI,CAUN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC9C,kBAAkB,EAAE,MAAM,GAC3B,IAAI,CAkCN"}
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../../src/core/cache-internals/params.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA2CpD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,MAAM,EAAE,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAexC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAU3E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC/C,IAAI,CAUN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC9C,kBAAkB,EAAE,MAAM,GAC3B,IAAI,CAoCN"}

package/dist/core/cache-internals/params.js

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { randomUUID } from 'crypto';
 /**
  * Extract dynamic parameter names from a route string.
  * E.g. "/[locale]/blog/[slug]" → ["locale", "slug"]
@@ -9,35 +10,34 @@ function extractParamNames(route) {
     return matches.map(m => m.slice(1, -1));
 }
 /**
- * Generate a sensible default value for a param name.
+ * Generate a sensible default value for any dynamic route param name.
  *
- * Rules:
- * - locale/lang → "en"
- * - id/ID-containing names → "123"
- * - slug/username/code → "demo" or descriptive
- * - others → "demo"
+ * Matches by suffix/pattern so it works generically — e.g. `productId`,
+ * `orderId`, `articleSlug`, `teamName` — without hardcoding every variant.
+ *
+ * Fallback: converts the param name from camelCase to kebab-case, which is
+ * both human-readable and a valid value for slug-style params.
+ * e.g. `articleSlug` → `"article-slug"`, `teamName` → `"team-name"`
  */
 function generateDefaultParamValue(paramName) {
     const lower = paramName.toLowerCase();
-    if (lower === 'locale' || lower === 'lang' || lower === 'language') {
-        return 'en';
-    }
-    if (lower.includes('id') ||
-        lower === 'postid' ||
-        lower === 'productid' ||
-        lower === 'userid') {
-        return '123';
-    }
-    if (lower === 'slug') {
-        return 'demo';
-    }
-    if (lower === 'username') {
-        return 'demo-user';
-    }
-    if (lower === 'email') {
+    // Any param ending in "id" (userId, productId, orderId, …) → UUID
+    if (lower.endsWith('id'))
+        return randomUUID();
+    // Email addresses
+    if (lower.includes('email'))
         return 'demo@example.com';
-    }
-    return 'demo';
+    // Dates (createdDate, startDate, …)
+    if (lower.includes('date'))
+        return '2024-01-01';
+    // Pagination and numeric indices (page, pageNum, stepIndex, …)
+    if (lower === 'page' || lower.endsWith('num') || lower.endsWith('index') || lower.endsWith('page'))
+        return '1';
+    // Version strings (version, apiVersion, ver, …)
+    if (lower.includes('version') || lower === 'ver')
+        return 'v1';
+    // Fallback: kebab-case the param name so the value is always meaningful
+    return paramName.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '');
 }
 /**
  * Generate route params from detected routes.

package/dist/core/cache-internals/params.js.map

@@ -1 +1 @@
-{"version":3,"file":"params.js","sourceRoot":"","sources":["../../../src/core/cache-internals/params.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../../src/core/cache-internals/params.ts"],"names":[],"mappings":"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"}

package/dist/core/cache-internals/pull.d.ts

@@ -1,5 +1,17 @@
+/** Filename of the pull timestamp marker written inside the output directory. */
 export declare const PULL_META_FILE = ".last-pulled";
+/** Default TTL before a pull is considered stale and a re-fetch is triggered. */
 export declare const DEFAULT_PULL_TTL_MS: number;
+/**
+ * Read the timestamp of the last successful pull from the marker file.
+ * Returns the time as a Unix timestamp (ms), or null when the file is absent
+ * or contains an unparseable date.
+ */
 export declare function getLastPulledTime(outputDir: string): number | null;
+/**
+ * Write the current time as an ISO 8601 string to the marker file.
+ * Creates the output directory if it doesn't exist yet.
+ * Called after a successful pull to reset the TTL clock.
+ */
 export declare function saveLastPulledTime(outputDir: string): void;
 //# sourceMappingURL=pull.d.ts.map

package/dist/core/cache-internals/pull.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../../src/core/cache-internals/pull.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,cAAc,iBAAiB,CAAC;AAC7C,eAAO,MAAM,mBAAmB,QAAgB,CAAC;AAEjD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASlE;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAO1D"}
+{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../../src/core/cache-internals/pull.ts"],"names":[],"mappings":"AAGA,iFAAiF;AACjF,eAAO,MAAM,cAAc,iBAAiB,CAAC;AAE7C,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,QAAgB,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUlE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAO1D"}

package/dist/core/cache-internals/pull.js

@@ -1,19 +1,32 @@
 import fs from 'fs';
 import path from 'path';
+/** Filename of the pull timestamp marker written inside the output directory. */
 export const PULL_META_FILE = '.last-pulled';
+/** Default TTL before a pull is considered stale and a re-fetch is triggered. */
 export const DEFAULT_PULL_TTL_MS = 5 * 60 * 1000; // 5 minutes
+/**
+ * Read the timestamp of the last successful pull from the marker file.
+ * Returns the time as a Unix timestamp (ms), or null when the file is absent
+ * or contains an unparseable date.
+ */
 export function getLastPulledTime(outputDir) {
     const p = path.join(outputDir, PULL_META_FILE);
     if (!fs.existsSync(p))
         return null;
     try {
         const ts = new Date(fs.readFileSync(p, 'utf-8').trim()).getTime();
+        // isNaN guard handles a corrupted or empty file
         return isNaN(ts) ? null : ts;
     }
     catch {
         return null;
     }
 }
+/**
+ * Write the current time as an ISO 8601 string to the marker file.
+ * Creates the output directory if it doesn't exist yet.
+ * Called after a successful pull to reset the TTL clock.
+ */
 export function saveLastPulledTime(outputDir) {
     fs.mkdirSync(outputDir, { recursive: true });
     fs.writeFileSync(path.join(outputDir, PULL_META_FILE), new Date().toISOString(), 'utf-8');

package/dist/core/cache-internals/pull.js.map

@@ -1 +1 @@
-{"version":3,"file":"pull.js","sourceRoot":"","sources":["../../../src/core/cache-internals/pull.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAC;AAC7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;AAE9D,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IAC/C,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IAC/C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QAClE,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAChD,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,EAAE,CAAC,aAAa,CACZ,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EACpC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EACxB,OAAO,CACV,CAAC;AACN,CAAC"}
+{"version":3,"file":"pull.js","sourceRoot":"","sources":["../../../src/core/cache-internals/pull.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,iFAAiF;AACjF,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAC;AAE7C,iFAAiF;AACjF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;AAE9D;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IAC/C,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IAC/C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACD,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QAClE,gDAAgD;QAChD,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAChD,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,EAAE,CAAC,aAAa,CACZ,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EACpC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EACxB,OAAO,CACV,CAAC;AACN,CAAC"}

package/dist/core/cache-internals/sync.d.ts

@@ -1,6 +1,29 @@
 import type { SerializedNamespaces, SyncDiff } from './types.js';
+/**
+ * Load the serialized namespace map from the last successful sync.
+ * Returns null when no cache exists yet or when the file is unreadable.
+ */
 export declare function loadSyncCache(root: string): SerializedNamespaces | null;
+/**
+ * Persist the serialized namespace map as the new sync baseline.
+ * Subsequent runs diff against this to detect changes.
+ */
 export declare function saveSyncCache(root: string, data: SerializedNamespaces): void;
+/**
+ * Returns true when the current scan differs from the cached baseline,
+ * meaning the CMS needs to be updated.
+ * Always returns true when there is no cache yet (first run).
+ */
 export declare function isSyncNeeded(current: SerializedNamespaces, cached: SerializedNamespaces | null): boolean;
+/**
+ * Compute a three-way diff between the current scan and the cached baseline:
+ *
+ *  - `added`         keys present in current but not in cache
+ *  - `removed`       keys present in cache but no longer in current
+ *  - `routesChanged` keys present in both but with different preview routes
+ *  - `unchanged`     count of keys that are identical in both
+ *
+ * Preview routes are compared order-independently by sorting before joining.
+ */
 export declare function computeDiff(current: SerializedNamespaces, cached: SerializedNamespaces | null): SyncDiff;
 //# sourceMappingURL=sync.d.ts.map

package/dist/core/cache-internals/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/core/cache-internals/sync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIjE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAQvE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAM5E;AAED,wBAAgB,YAAY,CACxB,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,oBAAoB,GAAG,IAAI,GACpC,OAAO,CAGT;AAED,wBAAgB,WAAW,CACvB,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,oBAAoB,GAAG,IAAI,GACpC,QAAQ,CA6CV"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/core/cache-internals/sync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKjE;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAQvE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAM5E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CACxB,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,oBAAoB,GAAG,IAAI,GACpC,OAAO,CAIT;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACvB,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,oBAAoB,GAAG,IAAI,GACpC,QAAQ,CAgDV"}

package/dist/core/cache-internals/sync.js

@@ -1,6 +1,11 @@
 import fs from 'fs';
 import path from 'path';
+/** Filename of the sync baseline cache written at the project root. */
 const CACHE_FILE = '.cms-sync-cache.json';
+/**
+ * Load the serialized namespace map from the last successful sync.
+ * Returns null when no cache exists yet or when the file is unreadable.
+ */
 export function loadSyncCache(root) {
     const p = path.join(root, CACHE_FILE);
     if (!fs.existsSync(p))
@@ -12,19 +17,40 @@ export function loadSyncCache(root) {
         return null;
     }
 }
+/**
+ * Persist the serialized namespace map as the new sync baseline.
+ * Subsequent runs diff against this to detect changes.
+ */
 export function saveSyncCache(root, data) {
     fs.writeFileSync(path.join(root, CACHE_FILE), JSON.stringify(data, null, 2), 'utf-8');
 }
+/**
+ * Returns true when the current scan differs from the cached baseline,
+ * meaning the CMS needs to be updated.
+ * Always returns true when there is no cache yet (first run).
+ */
 export function isSyncNeeded(current, cached) {
     if (!cached)
         return true;
+    // Stringify comparison is sufficient — order is stable because serializeNamespaces sorts keys
     return JSON.stringify(current) !== JSON.stringify(cached);
 }
+/**
+ * Compute a three-way diff between the current scan and the cached baseline:
+ *
+ *  - `added`         keys present in current but not in cache
+ *  - `removed`       keys present in cache but no longer in current
+ *  - `routesChanged` keys present in both but with different preview routes
+ *  - `unchanged`     count of keys that are identical in both
+ *
+ * Preview routes are compared order-independently by sorting before joining.
+ */
 export function computeDiff(current, cached) {
     const added = [];
     const removed = [];
     const routesChanged = [];
     let unchanged = 0;
+    // Forward pass: find added keys and route changes
     for (const [ns, keys] of Object.entries(current)) {
         for (const { key, previewRoutes } of keys) {
             const cachedEntry = cached?.[ns]?.find(k => k.key === key);
@@ -32,6 +58,7 @@ export function computeDiff(current, cached) {
                 added.push({ namespace: ns, key, routes: previewRoutes });
             }
             else {
+                // Sort both sides so route order doesn't cause false positives
                 const before = [...cachedEntry.previewRoutes]
                     .map(routeToString)
                     .sort()
@@ -54,6 +81,7 @@ export function computeDiff(current, cached) {
             }
         }
     }
+    // Reverse pass: find keys that exist in cache but are gone from current
     if (cached) {
         for (const [ns, keys] of Object.entries(cached)) {
             for (const { key } of keys) {
@@ -65,6 +93,11 @@ export function computeDiff(current, cached) {
     }
     return { added, removed, routesChanged, unchanged };
 }
+/**
+ * Normalise a PreviewRoute to a string for stable comparison.
+ * String routes are returned as-is; object routes are JSON-stringified.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function routeToString(r) {
     return typeof r === 'string' ? r : JSON.stringify(r);
 }

package/dist/core/cache-internals/sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/core/cache-internals/sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/core/cache-internals/sync.ts"],"names":[],"mappings":"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"}

package/dist/core/cache-internals/types.d.ts

@@ -1,8 +1,21 @@
 import type { PreviewRoute } from '../scanner.js';
+/**
+ * The serialized form of a NamespaceMap written to the sync cache and sent to
+ * the CMS API. Each namespace maps to an ordered array of key entries so the
+ * structure is JSON-serializable without Maps.
+ */
 export type SerializedNamespaces = Record<string, Array<{
     key: string;
     previewRoutes: PreviewRoute[];
 }>>;
+/**
+ * Result of diffing the current scan against the cached baseline.
+ *
+ *  - `added`         keys new since the last sync
+ *  - `removed`       keys that no longer exist in the source
+ *  - `routesChanged` keys whose set of preview routes has changed
+ *  - `unchanged`     count of keys identical in both snapshots
+ */
 export interface SyncDiff {
     added: Array<{
         namespace: string;
@@ -21,6 +34,13 @@ export interface SyncDiff {
     }>;
     unchanged: number;
 }
+/**
+ * Shape of the `.cms-sync-cache-meta.json` file that stores auto-generated
+ * route params between sync runs.
+ *
+ *  - `generated`   route → param map produced by the last sync
+ *  - `timestamp`   ISO 8601 string of when the cache was last written
+ */
 export interface CachedRouteParams {
     generated: Record<string, Record<string, string>>;
     timestamp: string;

package/dist/core/cache-internals/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/cache-internals/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,MAAM,oBAAoB,GAAG,MAAM,CACrC,MAAM,EACN,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CACxD,CAAC;AAEF,MAAM,WAAW,QAAQ;IACrB,KAAK,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC,CAAC;IACzE,OAAO,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,aAAa,EAAE,KAAK,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,YAAY,EAAE,CAAC;QACvB,KAAK,EAAE,YAAY,EAAE,CAAC;KACzB,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAC9B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,SAAS,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/cache-internals/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CACrC,MAAM,EACN,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CACxD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACrB,KAAK,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC,CAAC;IACzE,OAAO,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,aAAa,EAAE,KAAK,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,YAAY,EAAE,CAAC;QACvB,KAAK,EAAE,YAAY,EAAE,CAAC;KACzB,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAC9B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,SAAS,EAAE,MAAM,CAAC;CACrB"}

package/dist/core/scanner-internals/ast.d.ts

@@ -3,20 +3,38 @@
  */
 import type { AstNode } from './types.js';
 /**
- * Walk an AST tree depth-first, calling visit() for each node.
+ * Walk an AST node depth-first, calling visit() for every node encountered.
+ *
+ * Handles three cases:
+ *  - Arrays     → recurse into each element
+ *  - AST nodes  → call visit(), then recurse into all object-valued properties
+ *  - Primitives → stop (nothing to traverse)
  */
 export declare function walk(node: unknown, visit: (node: AstNode) => void): void;
 /**
- * Parse source code using Babel with appropriate plugins based on file extension.
+ * Parse source code into a Babel AST with the appropriate plugins for the
+ * file extension.
+ *
+ *  - `.ts`              → typescript
+ *  - `.tsx`, `.jsx`, `.js` → typescript (if .tsx) + jsx
+ *
+ * `errorRecovery: true` lets the parser continue past syntax errors so a
+ * single broken file doesn't abort the entire scan.
  */
 export declare function parseSource(filePath: string, source: string): unknown;
 /**
- * Returns the string value of a StringLiteral or no-expression TemplateLiteral node.
+ * Extract the static string value from a `StringLiteral` or a `TemplateLiteral`
+ * that contains no expressions (i.e. `` `plain string` ``).
+ * Returns null for dynamic expressions or any other node type.
  */
 export declare function stringValue(node: unknown): string | null;
 /**
- * Extracts namespace string(s) from a useTranslation/getTranslation argument.
- * Handles both single strings and arrays of strings.
+ * Extract namespace string(s) from the first argument of a
+ * `useTranslation()` / `getTranslation()` call.
+ *
+ * Handles:
+ *  - Single string:  `useTranslation('sidebar')`          → `['sidebar']`
+ *  - Array of strings: `useTranslation(['common', 'nav'])` → `['common', 'nav']`
  */
 export declare function namespacesFromArg(node: unknown): string[];
 //# sourceMappingURL=ast.d.ts.map

package/dist/core/scanner-internals/ast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../../src/core/scanner-internals/ast.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;GAEG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAWxE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAUrE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgBxD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAWzD"}
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../../src/core/scanner-internals/ast.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAYxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAUrE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAiBxD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAWzD"}

package/dist/core/scanner-internals/ast.js

@@ -4,7 +4,12 @@
 import { parse } from '@babel/parser';
 import path from 'path';
 /**
- * Walk an AST tree depth-first, calling visit() for each node.
+ * Walk an AST node depth-first, calling visit() for every node encountered.
+ *
+ * Handles three cases:
+ *  - Arrays     → recurse into each element
+ *  - AST nodes  → call visit(), then recurse into all object-valued properties
+ *  - Primitives → stop (nothing to traverse)
  */
 export function walk(node, visit) {
     if (!node || typeof node !== 'object')
@@ -15,6 +20,7 @@ export function walk(node, visit) {
         return;
     }
     const n = node;
+    // Visit before recursing so parents are seen before their children
     if (typeof n.type === 'string')
         visit(n);
     for (const value of Object.values(n)) {
@@ -23,7 +29,14 @@ export function walk(node, visit) {
     }
 }
 /**
- * Parse source code using Babel with appropriate plugins based on file extension.
+ * Parse source code into a Babel AST with the appropriate plugins for the
+ * file extension.
+ *
+ *  - `.ts`              → typescript
+ *  - `.tsx`, `.jsx`, `.js` → typescript (if .tsx) + jsx
+ *
+ * `errorRecovery: true` lets the parser continue past syntax errors so a
+ * single broken file doesn't abort the entire scan.
  */
 export function parseSource(filePath, source) {
     const ext = path.extname(filePath);
@@ -39,7 +52,9 @@ export function parseSource(filePath, source) {
     });
 }
 /**
- * Returns the string value of a StringLiteral or no-expression TemplateLiteral node.
+ * Extract the static string value from a `StringLiteral` or a `TemplateLiteral`
+ * that contains no expressions (i.e. `` `plain string` ``).
+ * Returns null for dynamic expressions or any other node type.
  */
 export function stringValue(node) {
     if (!node || typeof node !== 'object')
@@ -50,6 +65,7 @@ export function stringValue(node) {
     if (n.type === 'TemplateLiteral') {
         const exprs = n.expressions;
         const quasis = n.quasis;
+        // Only static template literals (no ${…} expressions) can be resolved
         if (exprs.length === 0 && quasis.length === 1) {
             const quasi = quasis[0];
             if (quasi?.value) {
@@ -60,8 +76,12 @@ export function stringValue(node) {
     return null;
 }
 /**
- * Extracts namespace string(s) from a useTranslation/getTranslation argument.
- * Handles both single strings and arrays of strings.
+ * Extract namespace string(s) from the first argument of a
+ * `useTranslation()` / `getTranslation()` call.
+ *
+ * Handles:
+ *  - Single string:  `useTranslation('sidebar')`          → `['sidebar']`
+ *  - Array of strings: `useTranslation(['common', 'nav'])` → `['common', 'nav']`
  */
 export function namespacesFromArg(node) {
     const single = stringValue(node);