gt 2.14.17 → 2.14.18

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # gtx-cli
 
+## 2.14.18
+
+### Patch Changes
+
+- [#1243](https://github.com/generaltranslation/gt/pull/1243) [`a0e19f6`](https://github.com/generaltranslation/gt/commit/a0e19f64a17d1a439d2352a6bc3ca7390c4ed401) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Handling Mintlify $ref
+
 ## 2.14.17
 
 ### Patch Changes

package/dist/api/downloadFileBatch.js

@@ -8,6 +8,7 @@ import { mergeJson } from '../formats/json/mergeJson.js';
 import { extractJson } from '../formats/json/extractJson.js';
 import mergeYaml from '../formats/yaml/mergeYaml.js';
 import { extractYaml } from '../formats/yaml/extractYaml.js';
+import { resolveMintlifyRefs, shouldResolveRefs, } from '../utils/resolveMintlifyRefs.js';
 import { readLockfile, writeLockfile, findOrCreateEntry, } from '../fs/config/downloadedVersions.js';
 import { recordDownloaded, recordRemerged } from '../state/recentDownloads.js';
 import { recordWarning } from '../state/translateWarnings.js';
@@ -30,7 +31,19 @@ function mergeWithSource(translatedContent, locale, inputPath, options) {
     if (!sourceContent)
         return translatedContent;
     if (jsonSchema) {
-        return mergeJson(sourceContent, inputPath, options.options, [{ translatedContent, targetLocale: locale }], options.defaultLocale, options.locales)[0];
+        // Resolve $ref before merging if configured
+        let resolvedSourceContent = sourceContent;
+        if (shouldResolveRefs(inputPath, options.options)) {
+            try {
+                const json = JSON.parse(sourceContent);
+                const { resolved } = resolveMintlifyRefs(json, inputPath);
+                resolvedSourceContent = JSON.stringify(resolved, null, 2);
+            }
+            catch {
+                // Fall through with original content
+            }
+        }
+        return mergeJson(resolvedSourceContent, inputPath, options.options, [{ translatedContent, targetLocale: locale }], options.defaultLocale, options.locales)[0];
     }
     else {
         return mergeYaml(sourceContent, inputPath, options.options, [{ translatedContent, targetLocale: locale }], options.defaultLocale)[0];
@@ -103,7 +116,18 @@ export async function downloadFileBatch(fileTracker, files, options, forceDownlo
                     // For schema-based files, re-merge with current source in case
                     // non-translatable fields changed (skip the API download, not the merge)
                     try {
-                        const existingContent = fs.readFileSync(outputPath, 'utf8');
+                        let existingContent = fs.readFileSync(outputPath, 'utf8');
+                        // Resolve $ref before extraction if configured
+                        if (shouldResolveRefs(outputPath, options.options)) {
+                            try {
+                                const json = JSON.parse(existingContent);
+                                const { resolved } = resolveMintlifyRefs(json, outputPath);
+                                existingContent = JSON.stringify(resolved, null, 2);
+                            }
+                            catch {
+                                // Fall through with original content
+                            }
+                        }
                         const jsonExtracted = options.options?.jsonSchema
                             ? extractJson(existingContent, inputPath, options.options, locale, options.defaultLocale)
                             : null;

package/dist/cli/base.js

@@ -33,6 +33,7 @@ import { detectFramework } from '../setup/detectFramework.js';
 import { getFrameworkDisplayName, getReactFrameworkLibrary, } from '../setup/frameworkUtils.js';
 import { INLINE_LIBRARIES } from '../types/libraries.js';
 import { handleEnqueue } from './commands/enqueue.js';
+import { splitMintlifyLanguageRefs } from '../utils/splitMintlifyLanguageRefs.js';
 export class BaseCLI {
     library;
     additionalModules;
@@ -198,6 +199,8 @@ export class BaseCLI {
         if (include.size > 0) {
             await postProcessTranslations(settings, include);
         }
+        // Split Mintlify language entries into $ref files to keep docs.json small
+        await splitMintlifyLanguageRefs(settings);
         // Mirror assets after translations are downloaded and locale dirs are populated
         await mirrorAssetsToLocales(settings);
         clearDownloaded();

package/dist/cli/commands/upload.js

@@ -2,12 +2,12 @@ import { noSupportedFormatError, noDefaultLocaleError, } from '../../console/ind
 import { exitSync, logErrorAndExit } from '../../console/logging.js';
 import { logger } from '../../console/logger.js';
 import { getRelative, readFile } from '../../fs/findFilepath.js';
-import path from 'node:path';
 import { SUPPORTED_FILE_EXTENSIONS } from '../../formats/files/supportedFiles.js';
 import sanitizeFileContent from '../../utils/sanitizeFileContent.js';
 import { parseJson } from '../../formats/json/parseJson.js';
 import { extractJson } from '../../formats/json/extractJson.js';
-import { validateJsonSchema, detectMintlifyUnsupportedFields, } from '../../formats/json/utils.js';
+import { validateJsonSchema } from '../../formats/json/utils.js';
+import { resolveMintlifyRefs, shouldResolveRefs, } from '../../utils/resolveMintlifyRefs.js';
 import { runUploadFilesWorkflow } from '../../workflows/upload.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { createFileMapping } from '../../formats/files/fileMapping.js';
@@ -38,17 +38,19 @@ export async function upload(filePaths, placeholderPaths, transformPaths, dataFo
         }
         const jsonFiles = filePaths.json.map((filePath) => {
             const content = readFile(filePath);
-            // Detect unsupported fields in Mintlify docs.json
-            if (settings.framework === 'mintlify' &&
-                path.basename(filePath) === 'docs.json') {
+            // Resolve $ref before parsing if configured
+            let contentForParsing = content;
+            if (shouldResolveRefs(filePath, additionalOptions)) {
                 try {
-                    detectMintlifyUnsupportedFields(JSON.parse(content), filePath);
+                    const json = JSON.parse(content);
+                    const { resolved } = resolveMintlifyRefs(json, filePath);
+                    contentForParsing = JSON.stringify(resolved, null, 2);
                 }
                 catch {
                     // JSON parse errors are handled below by parseJson
                 }
             }
-            const parsedJson = parseJson(content, filePath, additionalOptions, settings.defaultLocale);
+            const parsedJson = parseJson(contentForParsing, filePath, additionalOptions, settings.defaultLocale);
             const relativePath = getRelative(filePath);
             const jsonSchema = validateJsonSchema(additionalOptions, filePath);
             if (jsonSchema?.composite) {

package/dist/formats/files/aggregateFiles.js

@@ -3,8 +3,8 @@ import { recordWarning } from '../../state/translateWarnings.js';
 import { getRelative, readFile } from '../../fs/findFilepath.js';
 import { SUPPORTED_FILE_EXTENSIONS } from './supportedFiles.js';
 import { parseJson } from '../json/parseJson.js';
-import { detectMintlifyUnsupportedFields } from '../json/utils.js';
-import path from 'node:path';
+import { resolveMintlifyRefs, shouldResolveRefs, } from '../../utils/resolveMintlifyRefs.js';
+import { storeRefMap } from '../../state/mintlifyRefMap.js';
 import parseYaml from '../yaml/parseYaml.js';
 import { validateYamlSchema } from '../yaml/utils.js';
 import { flattenJson } from '../json/flattenJson.js';
@@ -75,17 +75,20 @@ export async function aggregateFiles(settings) {
                     return null;
                 }
             }
-            // Detect unsupported fields in Mintlify docs.json
-            if (settings.framework === 'mintlify' &&
-                path.basename(filePath) === 'docs.json') {
+            // Resolve $ref before parsing if configured
+            let contentForParsing = content;
+            if (shouldResolveRefs(filePath, settings.options)) {
                 try {
-                    detectMintlifyUnsupportedFields(JSON.parse(content), filePath);
+                    const json = JSON.parse(content);
+                    const { resolved, refMap } = resolveMintlifyRefs(json, filePath);
+                    storeRefMap(refMap);
+                    contentForParsing = JSON.stringify(resolved, null, 2);
                 }
                 catch {
                     // JSON parse errors are handled below by parseJson
                 }
             }
-            const parsedJson = parseJson(content, filePath, settings.options || {}, settings.defaultLocale);
+            const parsedJson = parseJson(contentForParsing, filePath, settings.options || {}, settings.defaultLocale);
             // Detect companion metadata file
             let keyedMetadata;
             let parsedContent;

package/dist/generated/version.d.ts

@@ -1 +1 @@
-export declare const PACKAGE_VERSION = "2.14.17";
+export declare const PACKAGE_VERSION = "2.14.18";

package/dist/generated/version.js

@@ -1,2 +1,2 @@
 // This file is auto-generated. Do not edit manually.
-export const PACKAGE_VERSION = '2.14.17';
+export const PACKAGE_VERSION = '2.14.18';

package/dist/state/mintlifyRefMap.d.ts

@@ -0,0 +1,4 @@
+import type { RefMap } from '../utils/resolveMintlifyRefs.js';
+export declare function storeRefMap(refMap: RefMap): void;
+export declare function getStoredRefMap(): RefMap | null;
+export declare function clearStoredRefMap(): void;

package/dist/state/mintlifyRefMap.js

@@ -0,0 +1,12 @@
+let storedRefMap = new Map();
+export function storeRefMap(refMap) {
+    for (const [key, value] of refMap.entries()) {
+        storedRefMap.set(key, value);
+    }
+}
+export function getStoredRefMap() {
+    return storedRefMap.size > 0 ? storedRefMap : null;
+}
+export function clearStoredRefMap() {
+    storedRefMap = new Map();
+}

package/dist/utils/resolveMintlifyRefs.d.ts

@@ -0,0 +1,28 @@
+export type RefMapEntry = {
+    sourceFile: string;
+    refPath: string;
+    containingDir: string;
+    originalContent: unknown;
+};
+export type RefMap = Map<string, RefMapEntry>;
+export type ResolvedRefs = {
+    resolved: unknown;
+    refMap: RefMap;
+};
+/**
+ * Resolve all Mintlify $ref references in a parsed JSON object.
+ *
+ * Returns the fully-expanded JSON and a refMap that tracks which subtrees
+ * came from which files (used later to split translated output back into
+ * the same file topology).
+ */
+export declare function resolveMintlifyRefs(json: unknown, filePath: string): ResolvedRefs;
+/**
+ * Check if a file should have $ref resolution applied based on the settings.
+ * Returns true if the file has mintlify options configured AND matches a
+ * composite jsonSchema entry.
+ */
+export declare function shouldResolveRefs(filePath: string, options?: {
+    mintlify?: any;
+    jsonSchema?: Record<string, any>;
+}): boolean;

package/dist/utils/resolveMintlifyRefs.js

@@ -0,0 +1,117 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../console/logger.js';
+import chalk from 'chalk';
+import micromatch from 'micromatch';
+/**
+ * Resolve all Mintlify $ref references in a parsed JSON object.
+ *
+ * Returns the fully-expanded JSON and a refMap that tracks which subtrees
+ * came from which files (used later to split translated output back into
+ * the same file topology).
+ */
+export function resolveMintlifyRefs(json, filePath) {
+    const refMap = new Map();
+    const resolved = resolveNode(json, path.dirname(path.resolve(filePath)), '', new Set(), refMap);
+    return { resolved, refMap };
+}
+function resolveNode(node, baseDir, pointer, visiting, refMap) {
+    if (node === null || typeof node !== 'object')
+        return node;
+    if (Array.isArray(node)) {
+        return node.map((item, i) => resolveNode(item, baseDir, `${pointer}/${i}`, visiting, refMap));
+    }
+    const obj = node;
+    if (typeof obj['$ref'] === 'string') {
+        return resolveRef(obj, baseDir, pointer, visiting, refMap);
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        result[key] = resolveNode(value, baseDir, `${pointer}/${key}`, visiting, refMap);
+    }
+    return result;
+}
+function resolveRef(obj, baseDir, pointer, visiting, refMap) {
+    const refPath = obj['$ref'];
+    if (!isRelativePath(refPath)) {
+        logger.warn(chalk.yellow(`Skipping non-relative $ref at ${pointer || '/'}: ${refPath}`));
+        const { $ref: _, ...rest } = obj;
+        return rest;
+    }
+    const resolvedFilePath = path.resolve(baseDir, refPath);
+    if (visiting.has(resolvedFilePath)) {
+        logger.warn(chalk.yellow(`Circular $ref detected at ${pointer || '/'}: ${refPath}`));
+        const { $ref: _, ...rest } = obj;
+        return rest;
+    }
+    if (!fs.existsSync(resolvedFilePath)) {
+        logger.warn(chalk.yellow(`$ref file not found at ${pointer || '/'}: ${refPath} (resolved to ${resolvedFilePath})`));
+        const { $ref: _, ...rest } = obj;
+        return rest;
+    }
+    let fileContent;
+    try {
+        fileContent = fs.readFileSync(resolvedFilePath, 'utf-8');
+    }
+    catch {
+        logger.warn(chalk.yellow(`Failed to read $ref file: ${resolvedFilePath}`));
+        const { $ref: _, ...rest } = obj;
+        return rest;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fileContent);
+    }
+    catch {
+        logger.warn(chalk.yellow(`$ref file is not valid JSON: ${resolvedFilePath}`));
+        const { $ref: _, ...rest } = obj;
+        return rest;
+    }
+    // Record provenance before recursive resolution
+    refMap.set(pointer, {
+        sourceFile: resolvedFilePath,
+        refPath,
+        containingDir: baseDir,
+        originalContent: parsed,
+    });
+    // Recursively resolve nested $ref in the referenced file
+    const refFileDir = path.dirname(resolvedFilePath);
+    const nextVisiting = new Set(visiting);
+    nextVisiting.add(resolvedFilePath);
+    const resolvedContent = resolveNode(parsed, refFileDir, pointer, nextVisiting, refMap);
+    // Apply Mintlify merge rules
+    const { $ref: _, ...siblings } = obj;
+    if (resolvedContent !== null &&
+        typeof resolvedContent === 'object' &&
+        !Array.isArray(resolvedContent)) {
+        // Object: merge siblings on top (siblings take precedence)
+        return { ...resolvedContent, ...siblings };
+    }
+    // Non-object (array, string, number, etc.): replace entirely, drop siblings
+    return resolvedContent;
+}
+/**
+ * Check if a file should have $ref resolution applied based on the settings.
+ * Returns true if the file has mintlify options configured AND matches a
+ * composite jsonSchema entry.
+ */
+export function shouldResolveRefs(filePath, options) {
+    if (!options?.mintlify)
+        return false;
+    if (!options.jsonSchema)
+        return false;
+    const relative = path.relative(process.cwd(), filePath);
+    for (const [glob, schema] of Object.entries(options.jsonSchema)) {
+        if (schema?.composite && micromatch.isMatch(relative, glob)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isRelativePath(refPath) {
+    if (path.isAbsolute(refPath))
+        return false;
+    if (/^[a-z]+:\/\//i.test(refPath))
+        return false;
+    return true;
+}

package/dist/utils/splitMintlifyLanguageRefs.d.ts

@@ -0,0 +1,13 @@
+import { Settings } from '../types/index.js';
+/**
+ * Post-processing step for Mintlify docs.json.
+ *
+ * After mergeJson writes a fully-inlined docs.json, this function restores
+ * the original $ref structure:
+ *
+ * - Default locale: restores original $ref paths
+ * - Non-default locales: prefixes ref paths with {locale}/, writes translated
+ *   content to the prefixed paths
+ * - Top-level refs (navigation, navbar): restored in docs.json
+ */
+export declare function splitMintlifyLanguageRefs(settings: Settings): Promise<void>;

package/dist/utils/splitMintlifyLanguageRefs.js

@@ -0,0 +1,190 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../console/logger.js';
+import { shouldResolveRefs } from './resolveMintlifyRefs.js';
+import { getStoredRefMap, clearStoredRefMap } from '../state/mintlifyRefMap.js';
+/**
+ * Post-processing step for Mintlify docs.json.
+ *
+ * After mergeJson writes a fully-inlined docs.json, this function restores
+ * the original $ref structure:
+ *
+ * - Default locale: restores original $ref paths
+ * - Non-default locales: prefixes ref paths with {locale}/, writes translated
+ *   content to the prefixed paths
+ * - Top-level refs (navigation, navbar): restored in docs.json
+ */
+export async function splitMintlifyLanguageRefs(settings) {
+    const isMintlify = settings.framework === 'mintlify' || !!settings.options?.mintlify;
+    if (!isMintlify)
+        return;
+    const refMap = getStoredRefMap();
+    if (!refMap || refMap.size === 0)
+        return;
+    try {
+        const resolvedJsonPaths = settings.files?.resolvedPaths?.json;
+        if (!resolvedJsonPaths)
+            return;
+        const docsJsonPath = resolvedJsonPaths.find((p) => shouldResolveRefs(p, settings.options));
+        if (!docsJsonPath)
+            return;
+        if (!fs.existsSync(docsJsonPath))
+            return;
+        let docsJson;
+        try {
+            docsJson = JSON.parse(fs.readFileSync(docsJsonPath, 'utf-8'));
+        }
+        catch {
+            return;
+        }
+        const defaultLocale = settings.defaultLocale;
+        const navRefEntry = refMap.get('/navigation');
+        const navContent = navRefEntry
+            ? getAtPointer(docsJson, '/navigation')
+            : docsJson?.navigation;
+        const languages = navContent?.languages;
+        if (!Array.isArray(languages) || languages.length <= 1) {
+            restoreTopLevelRefs(docsJson, refMap, docsJsonPath);
+            return;
+        }
+        const defaultIndex = languages.findIndex((e) => e?.language === defaultLocale);
+        if (defaultIndex < 0) {
+            restoreTopLevelRefs(docsJson, refMap, docsJsonPath);
+            return;
+        }
+        const navDir = navRefEntry
+            ? path.dirname(navRefEntry.sourceFile)
+            : path.dirname(docsJsonPath);
+        const defaultPointerPrefix = `/navigation/languages/${defaultIndex}`;
+        const internalRefs = collectInternalRefs(refMap, defaultPointerPrefix);
+        if (internalRefs.length > 0) {
+            const defaultEntry = languages[defaultIndex];
+            for (const ref of internalRefs) {
+                setAtPointer(defaultEntry, ref.relativePointer, {
+                    $ref: ref.refPath,
+                });
+            }
+            for (const entry of languages) {
+                if (!entry || entry.language === defaultLocale)
+                    continue;
+                const locale = entry.language;
+                if (!locale)
+                    continue;
+                for (const ref of internalRefs) {
+                    const subtree = getAtPointer(entry, ref.relativePointer);
+                    if (subtree === undefined)
+                        continue;
+                    const originalAbsPath = path.resolve(ref.resolvedDir, ref.refPath);
+                    const relToNavDir = path.relative(navDir, originalAbsPath);
+                    const localeRelPath = path.join(locale, relToNavDir);
+                    const outputPath = path.resolve(navDir, localeRelPath);
+                    writeJsonFile(outputPath, subtree);
+                    // All refs inside the locale's files use original paths — the locale
+                    // directory mirrors the source structure, so relative resolution works.
+                    // The locale prefix only appears in the parent navigation.json entry.
+                    setAtPointer(entry, ref.relativePointer, { $ref: ref.refPath });
+                }
+            }
+            logger.info(`Restored $ref structure for source locale navigation`);
+        }
+        const navFileName = navRefEntry
+            ? path.basename(navRefEntry.sourceFile)
+            : 'navigation.json';
+        for (let i = 0; i < languages.length; i++) {
+            const entry = languages[i];
+            if (!entry || entry.language === defaultLocale)
+                continue;
+            const locale = entry.language;
+            if (!locale)
+                continue;
+            const { language, ...contentWithoutLanguage } = entry;
+            const entryFileName = `${locale}/${navFileName}`;
+            const entryFilePath = path.resolve(navDir, entryFileName);
+            writeJsonFile(entryFilePath, contentWithoutLanguage);
+            languages[i] = { language: locale, $ref: `./${entryFileName}` };
+        }
+        logger.info(`Split locale navigation entries into ref files`);
+        restoreTopLevelRefs(docsJson, refMap, docsJsonPath);
+    }
+    finally {
+        clearStoredRefMap();
+    }
+}
+/**
+ * Restore top-level $ref pointers in docs.json.
+ * Writes each resolved subtree to its original source file and replaces
+ * the subtree in docs.json with the $ref pointer.
+ */
+function restoreTopLevelRefs(docsJson, refMap, docsJsonPath) {
+    let changed = false;
+    // Sort deepest-first so nested refs are written before their parent
+    // replaces the ancestor subtree with a $ref pointer
+    const entries = [...refMap.entries()]
+        .filter(([pointer]) => !pointer.match(/^\/navigation\/languages\/\d+/))
+        .sort(([a], [b]) => b.length - a.length);
+    for (const [pointer, entry] of entries) {
+        const subtree = getAtPointer(docsJson, pointer);
+        if (subtree === undefined)
+            continue;
+        writeJsonFile(entry.sourceFile, subtree);
+        setAtPointer(docsJson, pointer, { $ref: entry.refPath });
+        changed = true;
+    }
+    if (changed) {
+        fs.writeFileSync(docsJsonPath, JSON.stringify(docsJson, null, 2), 'utf-8');
+    }
+}
+/**
+ * Collect refMap entries that describe a language entry's internal $ref chain.
+ * Sorted deepest-first so nested content is extracted before parents.
+ */
+function collectInternalRefs(refMap, entryPointerPrefix) {
+    const refs = [];
+    for (const [pointer, entry] of refMap.entries()) {
+        if (!pointer.startsWith(entryPointerPrefix + '/'))
+            continue;
+        refs.push({
+            relativePointer: pointer.slice(entryPointerPrefix.length),
+            refPath: entry.refPath,
+            // The directory from which this $ref path should be resolved
+            resolvedDir: entry.containingDir,
+        });
+    }
+    refs.sort((a, b) => b.relativePointer.length - a.relativePointer.length);
+    return refs;
+}
+function writeJsonFile(filePath, data) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+function getAtPointer(obj, pointer) {
+    if (!pointer || pointer === '/')
+        return obj;
+    const parts = pointer.split('/').filter(Boolean);
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        const index = /^\d+$/.test(part) ? parseInt(part) : part;
+        current = current[index];
+    }
+    return current;
+}
+function setAtPointer(obj, pointer, value) {
+    if (!pointer || pointer === '/')
+        return;
+    const parts = pointer.split('/').filter(Boolean);
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const index = /^\d+$/.test(parts[i]) ? parseInt(parts[i]) : parts[i];
+        if (current[index] === undefined)
+            return;
+        current = current[index];
+    }
+    const lastPart = parts[parts.length - 1];
+    const lastIndex = /^\d+$/.test(lastPart) ? parseInt(lastPart) : lastPart;
+    current[lastIndex] = value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gt",
-  "version": "2.14.17",
+  "version": "2.14.18",
   "main": "dist/index.js",
   "bin": "dist/main.js",
   "files": [
@@ -110,9 +110,9 @@
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
     "yaml": "^2.8.0",
-    "@generaltranslation/python-extractor": "0.2.10",
     "generaltranslation": "8.2.5",
-    "gt-remark": "1.0.7"
+    "gt-remark": "1.0.7",
+    "@generaltranslation/python-extractor": "0.2.10"
   },
   "devDependencies": {
     "@babel/types": "^7.28.4",