@mintlify/prebuild 1.0.951 → 1.0.953

package/dist/index.d.ts

@@ -4,3 +4,5 @@ export * from './utils.js';
 export * from './prebuild/index.js';
 export { getFaviconsConfig } from './prebuild/generateFavicons.js';
 export * from './prebuild/update/rss/index.js';
+export { resolveRefs, resolveFileRefs, RefNotFoundError, CircularRefError, PathTraversalError, RefInvalidJsonError, } from './prebuild/resolveRefs.js';
+export type { ResolveRefsResult } from './prebuild/resolveRefs.js';

package/dist/index.js

@@ -4,3 +4,4 @@ export * from './utils.js';
 export * from './prebuild/index.js';
 export { getFaviconsConfig } from './prebuild/generateFavicons.js';
 export * from './prebuild/update/rss/index.js';
+export { resolveRefs, resolveFileRefs, RefNotFoundError, CircularRefError, PathTraversalError, RefInvalidJsonError, } from './prebuild/resolveRefs.js';

package/dist/prebuild/__tests__/resolveRefs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/prebuild/__tests__/resolveRefs.test.js

@@ -0,0 +1,163 @@
+import { mkdtemp, writeFile, mkdir, rm } from 'fs/promises';
+import { readFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import path from 'path';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { resolveRefs, RefNotFoundError, CircularRefError, PathTraversalError, RefInvalidJsonError, } from '../resolveRefs.js';
+describe('resolveRefs', () => {
+    let tempDir;
+    let reader;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(path.join(tmpdir(), 'resolve-refs-'));
+        reader = (relPath) => readFile(path.join(tempDir, relPath), 'utf-8');
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    const writeJson = async (relativePath, value) => {
+        await writeFile(path.join(tempDir, relativePath), JSON.stringify(value));
+    };
+    it('passes through values with no refs unchanged', async () => {
+        const input = { name: 'My Docs', navigation: [{ group: 'Guide', pages: ['intro'] }] };
+        const { resolved, referencedFiles } = await resolveRefs(input, reader);
+        expect(resolved).toEqual(input);
+        expect(referencedFiles).toEqual([]);
+    });
+    it('resolves a basic single $ref', async () => {
+        await writeJson('nav.json', ['intro', 'quickstart']);
+        const input = { name: 'Docs', pages: { $ref: './nav.json' } };
+        const { resolved, referencedFiles } = await resolveRefs(input, reader);
+        expect(resolved).toEqual({ name: 'Docs', pages: ['intro', 'quickstart'] });
+        expect(referencedFiles).toEqual(['nav.json']);
+    });
+    it('resolves nested refs (A → B → C)', async () => {
+        await mkdir(path.join(tempDir, 'nav'));
+        await writeJson('nav/tabs.json', { items: { $ref: './items.json' } });
+        await writeJson('nav/items.json', ['page1', 'page2']);
+        const input = { tabs: { $ref: './nav/tabs.json' } };
+        const { resolved, referencedFiles } = await resolveRefs(input, reader);
+        expect(resolved).toEqual({ tabs: { items: ['page1', 'page2'] } });
+        expect(referencedFiles).toContain(path.join('nav', 'tabs.json'));
+        expect(referencedFiles).toContain(path.join('nav', 'items.json'));
+    });
+    it('resolves $ref inside array elements', async () => {
+        await writeJson('group1.json', { group: 'API', pages: ['api/get', 'api/post'] });
+        await writeJson('group2.json', { group: 'Guides', pages: ['guide/start'] });
+        const input = { navigation: [{ $ref: './group1.json' }, { $ref: './group2.json' }] };
+        const { resolved } = await resolveRefs(input, reader);
+        expect(resolved).toEqual({
+            navigation: [
+                { group: 'API', pages: ['api/get', 'api/post'] },
+                { group: 'Guides', pages: ['guide/start'] },
+            ],
+        });
+    });
+    it('handles mixed refs and inline values', async () => {
+        await writeJson('api-nav.json', ['api/list', 'api/create']);
+        const input = {
+            name: 'Docs',
+            navigation: [
+                { group: 'Getting Started', pages: ['intro'] },
+                { group: 'API', pages: { $ref: './api-nav.json' } },
+            ],
+        };
+        const { resolved } = await resolveRefs(input, reader);
+        expect(resolved).toEqual({
+            name: 'Docs',
+            navigation: [
+                { group: 'Getting Started', pages: ['intro'] },
+                { group: 'API', pages: ['api/list', 'api/create'] },
+            ],
+        });
+    });
+    it('merges sibling keys on top of $ref when resolved value is an object', async () => {
+        await writeJson('group.json', {
+            group: 'Authentication',
+            pages: ['api/login', 'api/logout'],
+        });
+        const input = {
+            navigation: [
+                {
+                    $ref: './group.json',
+                    icon: 'lock',
+                    tag: 'Beta',
+                },
+            ],
+        };
+        const { resolved } = await resolveRefs(input, reader);
+        expect(resolved).toEqual({
+            navigation: [
+                {
+                    group: 'Authentication',
+                    pages: ['api/login', 'api/logout'],
+                    icon: 'lock',
+                    tag: 'Beta',
+                },
+            ],
+        });
+    });
+    it('sibling keys override matching keys from $ref', async () => {
+        await writeJson('group.json', {
+            group: 'Auth',
+            pages: ['api/login', 'api/logout'],
+            icon: 'key',
+        });
+        const input = {
+            navigation: [
+                {
+                    $ref: './group.json',
+                    icon: 'lock',
+                },
+            ],
+        };
+        const { resolved } = await resolveRefs(input, reader);
+        expect(resolved).toEqual({
+            navigation: [
+                {
+                    group: 'Auth',
+                    pages: ['api/login', 'api/logout'],
+                    icon: 'lock',
+                },
+            ],
+        });
+    });
+    it('detects circular references (A → B → A)', async () => {
+        await writeJson('a.json', { next: { $ref: './b.json' } });
+        await writeJson('b.json', { next: { $ref: './a.json' } });
+        const input = { data: { $ref: './a.json' } };
+        await expect(resolveRefs(input, reader)).rejects.toThrow(CircularRefError);
+        await expect(resolveRefs(input, reader)).rejects.toThrow(/Circular reference detected/);
+    });
+    it('throws RefNotFoundError for missing files', async () => {
+        const input = { data: { $ref: './nonexistent.json' } };
+        await expect(resolveRefs(input, reader)).rejects.toThrow(RefNotFoundError);
+        await expect(resolveRefs(input, reader)).rejects.toThrow(/does not exist/);
+    });
+    it('throws RefInvalidJsonError for invalid JSON in referenced file', async () => {
+        await writeFile(path.join(tempDir, 'bad.json'), '{ invalid json }');
+        const input = { data: { $ref: './bad.json' } };
+        await expect(resolveRefs(input, reader)).rejects.toThrow(RefInvalidJsonError);
+        await expect(resolveRefs(input, reader)).rejects.toThrow(/contains invalid JSON/);
+    });
+    it('throws PathTraversalError for paths outside content root', async () => {
+        const input = { data: { $ref: '../../etc/passwd' } };
+        await expect(resolveRefs(input, reader)).rejects.toThrow(PathTraversalError);
+        await expect(resolveRefs(input, reader)).rejects.toThrow(/outside the project directory/);
+    });
+    it('allows diamond dependencies (same file referenced from two places)', async () => {
+        await writeJson('shared.json', { shared: true });
+        const input = {
+            a: { $ref: './shared.json' },
+            b: { $ref: './shared.json' },
+        };
+        const { resolved, referencedFiles } = await resolveRefs(input, reader);
+        expect(resolved).toEqual({ a: { shared: true }, b: { shared: true } });
+        expect(referencedFiles.filter((f) => f.endsWith('shared.json'))).toHaveLength(2);
+    });
+    it('ignores sibling keys when the referenced value is not an object', async () => {
+        await writeJson('pages.json', ['intro', 'quickstart']);
+        const input = { $ref: './pages.json', extra: 'value' };
+        const { resolved } = await resolveRefs(input, reader);
+        expect(resolved).toEqual(['intro', 'quickstart']);
+    });
+});

package/dist/prebuild/resolveRefs.d.ts

@@ -0,0 +1,18 @@
+export declare class RefNotFoundError extends Error {
+    constructor(refPath: string, referencedFrom: string);
+}
+export declare class CircularRefError extends Error {
+    constructor(chain: string[]);
+}
+export declare class PathTraversalError extends Error {
+    constructor(refPath: string);
+}
+export declare class RefInvalidJsonError extends Error {
+    constructor(refPath: string, details: string);
+}
+export interface ResolveRefsResult {
+    resolved: unknown;
+    referencedFiles: string[];
+}
+export declare function resolveRefs(value: unknown, readFile: (relativePath: string) => Promise<string>): Promise<ResolveRefsResult>;
+export declare function resolveFileRefs(value: unknown, contentDirectory: string): Promise<ResolveRefsResult>;

package/dist/prebuild/resolveRefs.js

@@ -0,0 +1,95 @@
+import { readFile } from 'fs/promises';
+import path from 'path';
+export class RefNotFoundError extends Error {
+    constructor(refPath, referencedFrom) {
+        super(`Referenced config file '${refPath}' does not exist (referenced from ${referencedFrom})`);
+        this.name = 'RefNotFoundError';
+    }
+}
+export class CircularRefError extends Error {
+    constructor(chain) {
+        super(`Circular reference detected: ${chain.join(' → ')}`);
+        this.name = 'CircularRefError';
+    }
+}
+export class PathTraversalError extends Error {
+    constructor(refPath) {
+        super(`Referenced config file '${refPath}' is outside the project directory`);
+        this.name = 'PathTraversalError';
+    }
+}
+export class RefInvalidJsonError extends Error {
+    constructor(refPath, details) {
+        super(`Referenced config file '${refPath}' contains invalid JSON: ${details}`);
+        this.name = 'RefInvalidJsonError';
+    }
+}
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function getRefPath(value) {
+    if (!isJsonObject(value) || typeof value.$ref !== 'string')
+        return undefined;
+    return value.$ref;
+}
+function resolveRefPath(refPath, fromFile) {
+    if (fromFile)
+        return path.normalize(path.join(path.dirname(fromFile), refPath));
+    return path.normalize(refPath);
+}
+async function loadRefFile(refPath, fullPath, readFile, fromFile) {
+    let content;
+    try {
+        content = await readFile(fullPath);
+    }
+    catch {
+        throw new RefNotFoundError(refPath, fromFile ?? 'project root');
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (e) {
+        throw new RefInvalidJsonError(refPath, e instanceof Error ? e.message : String(e));
+    }
+}
+export async function resolveRefs(value, readFile) {
+    const referencedFiles = [];
+    async function resolve(value, visited, fromFile) {
+        const refPath = getRefPath(value);
+        if (refPath != null) {
+            const fullPath = resolveRefPath(refPath, fromFile);
+            if (fullPath.startsWith('..'))
+                throw new PathTraversalError(refPath);
+            if (visited.has(fullPath))
+                throw new CircularRefError([...visited, fullPath]);
+            const parsed = await loadRefFile(refPath, fullPath, readFile, fromFile);
+            referencedFiles.push(fullPath);
+            const resolvedRef = await resolve(parsed, new Set([...visited, fullPath]), fullPath);
+            if (isJsonObject(resolvedRef)) {
+                const siblings = Object.entries(value).filter(([key]) => key !== '$ref');
+                const result = { ...resolvedRef };
+                for (const [key, val] of siblings) {
+                    result[key] = await resolve(val, visited, fromFile);
+                }
+                return result;
+            }
+            return resolvedRef;
+        }
+        if (Array.isArray(value)) {
+            return Promise.all(value.map((item) => resolve(item, visited, fromFile)));
+        }
+        if (isJsonObject(value)) {
+            const result = {};
+            for (const [key, val] of Object.entries(value)) {
+                result[key] = await resolve(val, visited, fromFile);
+            }
+            return result;
+        }
+        return value;
+    }
+    const resolved = await resolve(value, new Set());
+    return { resolved, referencedFiles };
+}
+export async function resolveFileRefs(value, contentDirectory) {
+    return resolveRefs(value, (relativePath) => readFile(path.join(contentDirectory, relativePath), 'utf-8'));
+}

package/dist/prebuild/update/ConfigUpdater.d.ts

@@ -3,7 +3,7 @@ export declare class ConfigUpdater<T> {
     private type;
     constructor(type: ConfigType);
     getConfigType(): "mint" | "docs";
-    getConfig(configPath: string, strict?: boolean, onError?: (message: string) => void): Promise<T>;
+    getConfig(configPath: string, strict?: boolean, contentDirectoryPath?: string, onError?: (message: string) => void): Promise<T>;
     validateConfigJsonString: (configContents: string, strict?: boolean, onError?: (message: string) => void) => Promise<{
         data: T;
         warnings: import("zod").ZodIssue[];
@@ -15,6 +15,7 @@ export declare class ConfigUpdater<T> {
         success: true;
         error?: never;
     }>;
+    private validateConfigObj;
     private readConfigFile;
     writeConfigFile: (config: T, targetDir?: string) => Promise<void>;
     private parseConfigJson;

package/dist/prebuild/update/ConfigUpdater.js

@@ -3,11 +3,15 @@ import Chalk from 'chalk';
 import { promises as _promises } from 'fs';
 import { outputFile } from 'fs-extra';
 import { join } from 'path';
+import { resolveFileRefs } from '../resolveRefs.js';
 const { readFile } = _promises;
 export class ConfigUpdater {
     constructor(type) {
         this.validateConfigJsonString = async (configContents, strict, onError) => {
             const configObj = this.parseConfigJson(configContents, onError);
+            return this.validateConfigObj(configObj, strict, onError);
+        };
+        this.validateConfigObj = async (configObj, strict, onError) => {
             const validationResults = this.type === 'mint' ? validateMintConfig(configObj) : validateDocsConfig(configObj);
             if (!validationResults.success) {
                 const errorMsg = `🚨 Invalid ${this.type}.json:`;
@@ -94,10 +98,25 @@ export class ConfigUpdater {
     getConfigType() {
         return this.type;
     }
-    async getConfig(configPath, strict, onError) {
+    async getConfig(configPath, strict, contentDirectoryPath, onError) {
         const configContents = await this.readConfigFile(configPath);
-        const validationResults = await this.validateConfigJsonString(configContents, strict, onError);
-        return validationResults.data;
+        const configObj = this.parseConfigJson(configContents, onError);
+        let resolvedObj = configObj;
+        if (contentDirectoryPath) {
+            try {
+                const { resolved } = await resolveFileRefs(configObj, contentDirectoryPath);
+                resolvedObj = resolved;
+            }
+            catch (e) {
+                const msg = `Error resolving $ref in ${this.type}.json: ${e instanceof Error ? e.message : String(e)}`;
+                if (onError) {
+                    onError(msg);
+                }
+                throw Error(msg);
+            }
+        }
+        const { data: config } = await this.validateConfigObj(resolvedObj, strict, onError);
+        return config;
     }
 }
 export const MintConfigUpdater = new ConfigUpdater('mint');

package/dist/prebuild/update/docsConfig/index.js

@@ -10,7 +10,7 @@ export async function updateDocsConfigFile({ contentDirectoryPath, openApiFiles,
         throw Error(NOT_CORRECT_PATH_ERROR);
     }
     if (docsConfig == null && configPath) {
-        docsConfig = await DocsConfigUpdater.getConfig(configPath, strict);
+        docsConfig = await DocsConfigUpdater.getConfig(configPath, strict, contentDirectoryPath);
     }
     if (docsConfig == null) {
         throw Error(NOT_CORRECT_PATH_ERROR);

package/dist/prebuild/update/mintConfig/index.js

@@ -6,7 +6,7 @@ export async function updateMintConfigFile(contentDirectoryPath, openApiFiles, l
     if (configPath == null) {
         return null;
     }
-    const mintConfig = await MintConfigUpdater.getConfig(configPath, strict);
+    const mintConfig = await MintConfigUpdater.getConfig(configPath, strict, contentDirectoryPath);
     const { mintConfig: newMintConfig, pagesAcc, openApiFiles: newOpenApiFiles, } = await generateOpenApiAnchorsOrTabs(mintConfig, openApiFiles, undefined, localSchema);
     await MintConfigUpdater.writeConfigFile(newMintConfig);
     return {