gt 2.14.18 → 2.14.19

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # gtx-cli
 
+## 2.14.19
+
+### Patch Changes
+
+- [#1244](https://github.com/generaltranslation/gt/pull/1244) [`c4c8b9c`](https://github.com/generaltranslation/gt/commit/c4c8b9c0429ce10d98ebdfaabc1213bd85a572bf) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Updating Mintlify $ref handling
+
+- Updated dependencies [[`8b75420`](https://github.com/generaltranslation/gt/commit/8b7542091233fb2c87284a365cc9ab8ce70371d3)]:
+  - generaltranslation@8.2.6
+  - @generaltranslation/python-extractor@0.2.11
+
 ## 2.14.18
 
 ### Patch Changes

package/dist/config/optionPresets.js

@@ -4,11 +4,13 @@ export function generatePreset(preset, type) {
             case 'mintlify':
                 // https://mintlify.com/docs/navigation
                 return {
+                    resolveRefs: true,
                     composite: {
                         '$.navigation.languages': {
                             type: 'array',
                             key: '$.language',
                             experimentalSort: 'localesAlphabetical',
+                            splitEntries: true,
                             include: [
                                 '$..group',
                                 '$..tab',
@@ -40,6 +42,36 @@ export function generatePreset(preset, type) {
                         },
                     },
                 };
+            case 'mintlify-hide-default':
+                // Mintlify with hideDefaultLocale — paths don't have locale prefix in source
+                return {
+                    resolveRefs: true,
+                    composite: {
+                        '$.navigation.languages': {
+                            type: 'array',
+                            key: '$.language',
+                            experimentalSort: 'localesAlphabetical',
+                            splitEntries: true,
+                            include: [
+                                '$..group',
+                                '$..tab',
+                                '$..item',
+                                '$..anchor',
+                                '$..dropdown',
+                            ],
+                            transform: {
+                                '$..pages[*]': {
+                                    match: '^/?(.*)$',
+                                    replace: '{locale}/$1',
+                                },
+                                '$..root': {
+                                    match: '^/?(.*)$',
+                                    replace: '{locale}/$1',
+                                },
+                            },
+                        },
+                    },
+                };
             case 'openapi':
                 return {
                     include: ['$..summary', '$..description'],

package/dist/generated/version.d.ts

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

package/dist/generated/version.js

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

package/dist/types/index.d.ts

@@ -252,8 +252,9 @@ export type StructuralTransform = {
     destinationPointer: string;
 };
 export type JsonSchema = {
-    preset?: 'mintlify' | 'openapi';
+    preset?: 'mintlify' | 'mintlify-hide-default' | 'openapi';
     structuralTransform?: StructuralTransform[];
+    resolveRefs?: boolean;
     include?: string[];
     composite?: {
         [sourceObjectPath: string]: SourceObjectOptions;
@@ -271,6 +272,7 @@ export type SourceObjectOptions = {
     localeProperty?: string;
     transform?: TransformOptions;
     experimentalSort?: 'locales' | 'localesAlphabetical';
+    splitEntries?: boolean;
 };
 export type TransformOptions = {
     [transformPath: string]: TransformOption;

package/dist/utils/resolveMintlifyRefs.d.ts

@@ -19,10 +19,8 @@ export type ResolvedRefs = {
 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.
+ * Returns true if the file matches a jsonSchema entry with resolveRefs: true.
  */
 export declare function shouldResolveRefs(filePath: string, options?: {
-    mintlify?: any;
     jsonSchema?: Record<string, any>;
 }): boolean;

package/dist/utils/resolveMintlifyRefs.js

@@ -92,17 +92,14 @@ function resolveRef(obj, baseDir, pointer, visiting, refMap) {
 }
 /**
  * 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.
+ * Returns true if the file matches a jsonSchema entry with resolveRefs: true.
  */
 export function shouldResolveRefs(filePath, options) {
-    if (!options?.mintlify)
-        return false;
-    if (!options.jsonSchema)
+    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)) {
+        if (schema?.resolveRefs && micromatch.isMatch(relative, glob)) {
             return true;
         }
     }

package/dist/utils/splitMintlifyLanguageRefs.d.ts

@@ -1,13 +1,13 @@
 import { Settings } from '../types/index.js';
 /**
- * Post-processing step for Mintlify docs.json.
+ * Post-processing step for composite JSON files with splitEntries enabled.
  *
- * After mergeJson writes a fully-inlined docs.json, this function restores
- * the original $ref structure:
+ * After mergeJson writes a fully-inlined composite file, this function:
+ * 1. Restores the original $ref structure (if the source used $ref / resolveRefs)
+ * 2. Extracts non-default keyed entries into their own ref files
+ *    to keep the source file compact
  *
- * - 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
+ * Driven entirely by the jsonSchema config — reads the composite path,
+ * key field, and splitEntries flag from the schema.
  */
 export declare function splitMintlifyLanguageRefs(settings: Settings): Promise<void>;

package/dist/utils/splitMintlifyLanguageRefs.js

@@ -1,74 +1,151 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { logger } from '../console/logger.js';
-import { shouldResolveRefs } from './resolveMintlifyRefs.js';
+import { validateJsonSchema } from '../formats/json/utils.js';
 import { getStoredRefMap, clearStoredRefMap } from '../state/mintlifyRefMap.js';
+import { JSONPath } from 'jsonpath-plus';
+import { getLocaleProperties } from 'generaltranslation';
 /**
- * Post-processing step for Mintlify docs.json.
+ * Post-processing step for composite JSON files with splitEntries enabled.
  *
- * After mergeJson writes a fully-inlined docs.json, this function restores
- * the original $ref structure:
+ * After mergeJson writes a fully-inlined composite file, this function:
+ * 1. Restores the original $ref structure (if the source used $ref / resolveRefs)
+ * 2. Extracts non-default keyed entries into their own ref files
+ *    to keep the source file compact
  *
- * - 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
+ * Driven entirely by the jsonSchema config — reads the composite path,
+ * key field, and splitEntries flag from the schema.
  */
 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)
+        // Find a JSON file that has splitEntries enabled or resolveRefs
+        const targetFile = findTargetFile(resolvedJsonPaths, settings);
+        if (!targetFile)
             return;
-        if (!fs.existsSync(docsJsonPath))
+        const { filePath: compositeFilePath, splitConfig } = targetFile;
+        if (!fs.existsSync(compositeFilePath))
             return;
-        let docsJson;
+        let fileJson;
         try {
-            docsJson = JSON.parse(fs.readFileSync(docsJsonPath, 'utf-8'));
+            fileJson = JSON.parse(fs.readFileSync(compositeFilePath, '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 docsDir = path.dirname(compositeFilePath);
+        // If splitEntries is configured, process it
+        if (splitConfig) {
+            processSplitEntries(fileJson, compositeFilePath, docsDir, splitConfig, settings, refMap);
         }
-        const defaultIndex = languages.findIndex((e) => e?.language === defaultLocale);
-        if (defaultIndex < 0) {
-            restoreTopLevelRefs(docsJson, refMap, docsJsonPath);
-            return;
+        // Restore top-level refs if any exist
+        if (refMap && refMap.size > 0) {
+            restoreTopLevelRefs(fileJson, refMap, splitConfig);
+        }
+        // Always write the composite file back — splitEntries modified the
+        // languages array, and restoreTopLevelRefs may not have written it
+        // (e.g., when all refs are inside language entries, not top-level)
+        fs.writeFileSync(compositeFilePath, JSON.stringify(fileJson, null, 2), 'utf-8');
+    }
+    finally {
+        clearStoredRefMap();
+    }
+}
+/**
+ * Find the target file and extract split configuration from the schema.
+ */
+function findTargetFile(resolvedPaths, settings) {
+    if (!settings.options?.jsonSchema)
+        return null;
+    for (const filePath of resolvedPaths) {
+        const schema = validateJsonSchema(settings.options, filePath);
+        if (!schema)
+            continue;
+        const hasSplitEntries = schema.composite
+            ? Object.entries(schema.composite).some(([, opts]) => opts.splitEntries)
+            : false;
+        const hasResolveRefs = schema.resolveRefs;
+        if (!hasSplitEntries && !hasResolveRefs)
+            continue;
+        // Extract split config if available
+        let splitConfig = null;
+        if (schema.composite) {
+            for (const [compositePath, opts] of Object.entries(schema.composite)) {
+                if (opts.splitEntries && opts.type === 'array' && opts.key) {
+                    splitConfig = {
+                        compositePath,
+                        jsonPointer: jsonPathToPointer(compositePath),
+                        keyField: opts.key,
+                        keyJsonPath: opts.key,
+                        sourceObjectOptions: opts,
+                    };
+                    break;
+                }
+            }
         }
-        const navDir = navRefEntry
-            ? path.dirname(navRefEntry.sourceFile)
-            : path.dirname(docsJsonPath);
-        const defaultPointerPrefix = `/navigation/languages/${defaultIndex}`;
+        return { filePath, schema, splitConfig };
+    }
+    return null;
+}
+/**
+ * Process splitEntries: extract non-default keyed entries into ref files.
+ */
+function processSplitEntries(fileJson, compositeFilePath, docsDir, splitConfig, settings, refMap) {
+    const { jsonPointer, keyJsonPath } = splitConfig;
+    // Find the composite array — may be behind a $ref
+    const parentPointer = jsonPointer.split('/').slice(0, -1).join('/') || '';
+    const arrayKey = jsonPointer.split('/').pop() || '';
+    const navRefEntry = refMap?.get(parentPointer || undefined);
+    // Get the array from the file
+    const arrayContainer = parentPointer
+        ? getAtPointer(fileJson, parentPointer)
+        : fileJson;
+    if (!arrayContainer)
+        return;
+    const entries = arrayContainer[arrayKey];
+    if (!Array.isArray(entries) || entries.length <= 1)
+        return;
+    // Determine the default key value (the source entry)
+    const defaultKeyValue = getDefaultKeyValue(settings.defaultLocale, splitConfig.sourceObjectOptions);
+    const defaultIndex = entries.findIndex((e) => {
+        if (!e || typeof e !== 'object')
+            return false;
+        const values = JSONPath({
+            json: e,
+            path: keyJsonPath,
+            resultType: 'value',
+            flatten: true,
+            wrap: true,
+        });
+        return values?.[0] === defaultKeyValue;
+    });
+    if (defaultIndex < 0)
+        return;
+    // Determine where the composite array actually lives on disk
+    const navDir = navRefEntry ? path.dirname(navRefEntry.sourceFile) : docsDir;
+    // Restore $ref structure if the source used $ref
+    if (refMap && refMap.size > 0) {
+        const defaultPointerPrefix = `${jsonPointer}/${defaultIndex}`;
         const internalRefs = collectInternalRefs(refMap, defaultPointerPrefix);
         if (internalRefs.length > 0) {
-            const defaultEntry = languages[defaultIndex];
+            const defaultEntry = entries[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)
+            for (const entry of entries) {
+                const entryKeyValues = JSONPath({
+                    json: entry,
+                    path: keyJsonPath,
+                    resultType: 'value',
+                    flatten: true,
+                    wrap: true,
+                });
+                if (entryKeyValues?.[0] === defaultKeyValue)
                     continue;
                 for (const ref of internalRefs) {
                     const subtree = getAtPointer(entry, ref.relativePointer);
@@ -76,66 +153,87 @@ export async function splitMintlifyLanguageRefs(settings) {
                         continue;
                     const originalAbsPath = path.resolve(ref.resolvedDir, ref.refPath);
                     const relToNavDir = path.relative(navDir, originalAbsPath);
-                    const localeRelPath = path.join(locale, relToNavDir);
+                    const keyValue = entryKeyValues?.[0] || 'unknown';
+                    const localeRelPath = path.join(keyValue, 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(`Restored $ref structure for default entry`);
         }
-        logger.info(`Split locale navigation entries into ref files`);
-        restoreTopLevelRefs(docsJson, refMap, docsJsonPath);
     }
-    finally {
-        clearStoredRefMap();
+    // Extract each non-default entry into its own ref file
+    const navFileName = navRefEntry
+        ? path.basename(navRefEntry.sourceFile)
+        : path.basename(compositeFilePath);
+    // Get the actual property name from the key JSONPath (e.g., "$.language" → "language")
+    const keyPropertyName = keyJsonPath.replace(/^\$\.?/, '');
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const keyValues = JSONPath({
+            json: entry,
+            path: keyJsonPath,
+            resultType: 'value',
+            flatten: true,
+            wrap: true,
+        });
+        const keyValue = keyValues?.[0];
+        if (!keyValue || keyValue === defaultKeyValue)
+            continue;
+        const { [keyPropertyName]: _, ...contentWithoutKey } = entry;
+        const entryFileName = `${keyValue}/${navFileName}`;
+        const entryFilePath = path.resolve(navDir, entryFileName);
+        writeJsonFile(entryFilePath, contentWithoutKey);
+        entries[i] = { [keyPropertyName]: keyValue, $ref: `./${entryFileName}` };
     }
+    logger.info(`Split keyed entries into ref files`);
+}
+/**
+ * Get the identifying key value for the default locale.
+ */
+function getDefaultKeyValue(defaultLocale, sourceObjectOptions) {
+    const localeProperty = sourceObjectOptions.localeProperty || 'code';
+    const localeProperties = getLocaleProperties(defaultLocale);
+    return (localeProperties[localeProperty] ||
+        localeProperties.code ||
+        defaultLocale);
 }
 /**
- * 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.
+ * Convert a JSONPath like "$.navigation.languages" to a JSON pointer like "/navigation/languages".
  */
-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
+function jsonPathToPointer(jsonPath) {
+    return jsonPath
+        .replace(/^\$\.?/, '')
+        .split('.')
+        .filter(Boolean)
+        .map((segment) => `/${segment}`)
+        .join('');
+}
+/**
+ * Restore top-level $ref pointers in the composite file.
+ * Sorted deepest-first so nested refs are written before parents.
+ */
+function restoreTopLevelRefs(fileJson, refMap, splitConfig) {
+    // Build a regex to exclude entries inside the composite array
+    const arrayPointerPattern = splitConfig
+        ? new RegExp(`^${splitConfig.jsonPointer.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/\\d+`)
+        : null;
     const entries = [...refMap.entries()]
-        .filter(([pointer]) => !pointer.match(/^\/navigation\/languages\/\d+/))
+        .filter(([pointer]) => !arrayPointerPattern || !arrayPointerPattern.test(pointer))
         .sort(([a], [b]) => b.length - a.length);
     for (const [pointer, entry] of entries) {
-        const subtree = getAtPointer(docsJson, pointer);
+        const subtree = getAtPointer(fileJson, 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');
+        setAtPointer(fileJson, pointer, { $ref: entry.refPath });
     }
 }
 /**
- * Collect refMap entries that describe a language entry's internal $ref chain.
+ * Collect refMap entries that describe an entry's internal $ref chain.
  * Sorted deepest-first so nested content is extracted before parents.
  */
 function collectInternalRefs(refMap, entryPointerPrefix) {
@@ -146,7 +244,6 @@ function collectInternalRefs(refMap, entryPointerPrefix) {
         refs.push({
             relativePointer: pointer.slice(entryPointerPrefix.length),
             refPath: entry.refPath,
-            // The directory from which this $ref path should be resolved
             resolvedDir: entry.containingDir,
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gt",
-  "version": "2.14.18",
+  "version": "2.14.19",
   "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": "8.2.5",
-    "gt-remark": "1.0.7",
-    "@generaltranslation/python-extractor": "0.2.10"
+    "@generaltranslation/python-extractor": "0.2.11",
+    "generaltranslation": "8.2.6",
+    "gt-remark": "1.0.7"
   },
   "devDependencies": {
     "@babel/types": "^7.28.4",