@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/mintlify-import.d.ts

@@ -0,0 +1,75 @@
+export interface MintlifySource {
+    path?: string;
+    repository?: string;
+    branch?: string;
+    subdirectory?: string;
+}
+export interface MintlifyInspection {
+    id: string;
+    title: string;
+    source: {
+        path?: string;
+        repository?: string;
+        branch?: string;
+        head?: string;
+        subdirectory?: string;
+    };
+    pageCount: number;
+    assetCount: number;
+    pages: string[];
+    spaces: string[];
+    redirects: Array<{
+        from: string;
+        to: string;
+    }>;
+    unmapped: string[];
+    warnings: string[];
+    suggestedDestination: string;
+}
+/** A reviewed conversion is a frozen snapshot, including assets, not a second conversion on submit. */
+export declare class MintlifyImports {
+    private prepared;
+    private preparing;
+    private converting;
+    inspect(input: MintlifySource, cwd: string): Promise<MintlifyInspection>;
+    convert(id: string, destination: string, allowWarnings?: boolean): Promise<{
+        conversion: {
+            importedAt: string;
+            destination: string;
+            id: string;
+            title: string;
+            source: {
+                path?: string;
+                repository?: string;
+                branch?: string;
+                head?: string;
+                subdirectory?: string;
+            };
+            pageCount: number;
+            assetCount: number;
+            pages: string[];
+            spaces: string[];
+            redirects: Array<{
+                from: string;
+                to: string;
+            }>;
+            unmapped: string[];
+            warnings: string[];
+            suggestedDestination: string;
+        };
+        root: string;
+        title: string;
+        generator: import("./types.js").GeneratorName;
+        contentDir: string;
+        pageCount: number;
+        skills: Array<{
+            path: string;
+            action: "installed" | "updated" | "unchanged";
+        }>;
+        warnings: string[];
+    }>;
+    private convertPrepared;
+    discard(id: string): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=mintlify-import.d.ts.map

package/dist/mintlify-import.js

@@ -0,0 +1,190 @@
+import { randomUUID } from 'node:crypto';
+import { cp, mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { convertSourceTree, materializeMintlifyOpenApiNavigation } from '../vendor/doxbrix-import/dist/importer.js';
+import { collectSourceAssets, collectSourceFiles, copySourceAssets, writeConvertResult } from '../vendor/doxbrix-import/dist/docs/import.js';
+import { listFilesRecursive } from '../vendor/doxbrix-import/dist/docs/project.js';
+import { withPageExtension } from '../vendor/doxbrix-import/dist/docs/manifest.js';
+import { DoxloopError } from './errors.js';
+import { mintlifyMarker } from './mintlify-detect.js';
+import { pathExists, resolveContainedDirectory } from './fs.js';
+import { fetchRemoteOpenApi } from './openapi.js';
+import { REDIRECTS_FILE } from './page-operations.js';
+import { importExistingDocumentation } from './project-import.js';
+import { listRemoteBranches, materializeRemoteSource, parseGitHubRepository } from './remote-source.js';
+const EXPIRY_MS = 30 * 60 * 1000;
+/** A reviewed conversion is a frozen snapshot, including assets, not a second conversion on submit. */
+export class MintlifyImports {
+    prepared = new Map();
+    preparing = false;
+    converting = new Set();
+    async inspect(input, cwd) {
+        if (this.preparing)
+            throw new DoxloopError('Another Mintlify inspection is running. Wait for it to finish.');
+        this.preparing = true;
+        let temporary;
+        try {
+            for (const [id, item] of this.prepared)
+                if (item.expires < Date.now())
+                    await this.discard(id);
+            if (this.prepared.size >= 3)
+                throw new DoxloopError('Finish or cancel an existing Mintlify import before inspecting another project.');
+            temporary = await mkdtemp(join(tmpdir(), 'doxloop-mintlify-'));
+            let root;
+            let source;
+            if (input.repository) {
+                const repository = `https://github.com/${parseGitHubRepository(input.repository)}.git`;
+                const branch = input.branch || (await listRemoteBranches({ provider: 'git', repository, branch: 'HEAD' }))[0]?.name;
+                if (!branch)
+                    throw new DoxloopError('The repository has no readable branches.');
+                const remote = { provider: 'git', repository, branch };
+                const snapshot = await materializeRemoteSource(join(temporary, 'project'), { name: 'mintlify', remote });
+                root = await realpath(snapshot.path);
+                source = { repository, branch, head: snapshot.head };
+            }
+            else {
+                if (!input.path?.trim())
+                    throw new DoxloopError('Choose a local Mintlify folder or enter a GitHub repository.');
+                root = await realpath(resolve(cwd, input.path));
+                if (root === homedir() || dirname(root) === root)
+                    throw new DoxloopError('Choose the documentation repository, not your home folder or filesystem root.');
+                source = { path: root };
+            }
+            const originalRoot = root;
+            if (input.subdirectory)
+                root = await resolveContainedDirectory(root, input.subdirectory, 'Mintlify documentation directory');
+            else if (!(await mintlifyMarker(root))) {
+                // Reuse the CLI's traversal rules (including its symlink and tooling exclusions).
+                const candidates = [];
+                for (const path of listFilesRecursive(root)) {
+                    if (!/(^|\/)(docs|mint)\.json$/.test(path))
+                        continue;
+                    const candidate = dirname(join(root, path));
+                    if (await mintlifyMarker(candidate) && !candidates.includes(candidate))
+                        candidates.push(candidate);
+                }
+                if (candidates.length !== 1)
+                    throw new DoxloopError(candidates.length
+                        ? `Several Mintlify sites were found. Choose a documentation subfolder: ${candidates.map((path) => relative(root, path)).join(', ')}`
+                        : 'No Mintlify docs.json or mint.json with navigation was found. Choose the documentation folder.');
+                root = candidates[0];
+            }
+            if (!(await mintlifyMarker(root)))
+                throw new DoxloopError('The selected folder is not a Mintlify documentation project.');
+            const subdirectory = relative(originalRoot, root).replace(/\\/g, '/');
+            if (subdirectory)
+                source.subdirectory = subdirectory;
+            const isProjectFile = (path) => !path.split(/[\\/]/).some((part) => ['.doxloop', '.codex'].includes(part));
+            const files = collectSourceFiles(root).filter((file) => isProjectFile(file.path));
+            const converted = convertSourceTree(files);
+            if (converted.dialect !== 'mintlify')
+                throw new DoxloopError('The Doxbrix converter did not recognize this project as Mintlify.');
+            const expanded = await materializeMintlifyOpenApiNavigation({ result: converted, files, loadRemote: async (url) => (await fetchRemoteOpenApi(url)).content });
+            const result = expanded.result;
+            if (!result.pages.length)
+                throw new DoxloopError('The selected Mintlify project contains no convertible pages.');
+            const paths = result.pages.map((page) => withPageExtension(page.path));
+            if (new Set(paths.map((path) => path.toLowerCase())).size !== paths.length)
+                throw new DoxloopError('Several converted pages have the same output path. Resolve those collisions before importing.');
+            const warnings = [...expanded.warnings];
+            const convertedIds = new Set(paths.map((path) => path.replace(/\.(md|mdx)$/i, '')));
+            const missingPages = new Set();
+            const inspectNavigation = (nodes) => {
+                for (const node of nodes) {
+                    if (node.type === 'group')
+                        inspectNavigation(node.items);
+                    else if (node.type === 'page' && !convertedIds.has(node.file))
+                        missingPages.add(node.file);
+                }
+            };
+            for (const space of result.manifest.spaces)
+                inspectNavigation(space.nav);
+            if (missingPages.size)
+                warnings.push(`Navigation references ${missingPages.size} page(s) absent from the converted output: ${[...missingPages].join(', ')}. The converter excludes repository instruction files such as AGENTS.md; these pages need review before deployment.`);
+            const collected = new Set(files.map((file) => file.path));
+            const omitted = listFilesRecursive(root).filter((path) => /\.(mdx?|markdown)$/i.test(path) && !collected.has(path));
+            if (omitted.length)
+                warnings.push(`${omitted.length} source page(s) exceeded the converter's file limits or could not be read: ${omitted.slice(0, 10).join(', ')}`);
+            const output = join(temporary, 'converted');
+            writeConvertResult(output, result);
+            const assets = collectSourceAssets(root).filter(isProjectFile);
+            const assetCount = copySourceAssets(root, output, assets);
+            if (assetCount !== assets.length)
+                throw new DoxloopError('Some documentation assets could not be copied. Check source file access and try again.');
+            // The CLI returns redirects separately. Preserve them in the native manifest as well as the report.
+            if (result.redirects.length)
+                await writeFile(join(output, 'docs.json'), JSON.stringify({ ...result.manifest, redirects: result.redirects }, null, 2) + '\n');
+            const id = randomUUID();
+            const title = result.manifest.name || basename(root);
+            const folder = `${(source.repository ? parseGitHubRepository(source.repository).split('/')[1] : basename(root)) || 'documentation'}-doxbrix`;
+            const report = { id, title, source, pageCount: paths.length, assetCount, pages: paths.slice(0, 25), spaces: result.manifest.spaces.map((space) => space.name), redirects: result.redirects, unmapped: result.unmapped, warnings, suggestedDestination: join(source.path ? dirname(originalRoot) : cwd, folder) };
+            this.prepared.set(id, { temporary, output, sourceRoot: originalRoot, expires: Date.now() + EXPIRY_MS, report });
+            return report;
+        }
+        catch (error) {
+            if (temporary)
+                await rm(temporary, { recursive: true, force: true });
+            throw error;
+        }
+        finally {
+            this.preparing = false;
+        }
+    }
+    async convert(id, destination, allowWarnings = false) {
+        if (this.converting.has(id))
+            throw new DoxloopError('This conversion is already running.');
+        this.converting.add(id);
+        try {
+            return await this.convertPrepared(id, destination, allowWarnings);
+        }
+        finally {
+            this.converting.delete(id);
+        }
+    }
+    async convertPrepared(id, destination, allowWarnings) {
+        const item = this.prepared.get(id);
+        if (!item || item.expires < Date.now())
+            throw new DoxloopError('This conversion preview expired. Inspect the Mintlify project again.');
+        if (!allowWarnings && (item.report.unmapped.length || item.report.warnings.length))
+            throw new DoxloopError('Review the conversion warnings and acknowledge them before importing.');
+        if (!destination.trim())
+            throw new DoxloopError('Choose a new folder for the Doxbrix project.');
+        const requested = resolve(destination);
+        // Resolve the parent to catch aliases through symlinks; never place output in the source tree.
+        const parent = await realpath(dirname(requested));
+        const root = join(parent, basename(requested));
+        const rel = relative(item.sourceRoot, root);
+        if (!rel || (rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel)))
+            throw new DoxloopError('Choose a destination outside the original Mintlify project.');
+        if (await pathExists(root))
+            throw new DoxloopError('The destination already exists. Choose a new project folder.');
+        // Claim a new directory exclusively. A failure may clean up only the directory we created.
+        await mkdir(root);
+        this.prepared.delete(id);
+        try {
+            await cp(item.output, root, { recursive: true, force: false, errorOnExist: true });
+            const imported = await importExistingDocumentation({ directory: root, generator: 'doxbrix', contentDir: '', title: item.report.title });
+            if (item.report.redirects.length)
+                await writeFile(join(root, REDIRECTS_FILE), JSON.stringify(Object.fromEntries(item.report.redirects.map(({ from, to }) => [from, to])), null, 2) + '\n');
+            const report = { ...item.report, importedAt: new Date().toISOString(), destination: root };
+            await writeFile(join(root, '.doxloop', 'mintlify-import.json'), JSON.stringify(report, null, 2) + '\n');
+            return { ...imported, conversion: report };
+        }
+        catch (error) {
+            await rm(root, { recursive: true, force: true });
+            throw error;
+        }
+        finally {
+            await rm(item.temporary, { recursive: true, force: true });
+        }
+    }
+    async discard(id) {
+        const item = this.prepared.get(id);
+        this.prepared.delete(id);
+        if (item)
+            await rm(item.temporary, { recursive: true, force: true });
+    }
+    async close() { await Promise.all([...this.prepared.keys()].map((id) => this.discard(id))); }
+}
+//# sourceMappingURL=mintlify-import.js.map

package/dist/navigation.d.ts

@@ -0,0 +1,98 @@
+import type { DoxloopProject } from './types.js';
+/**
+ * The navigation editor's model. It is the Doxbrix node shape for every
+ * generator: page and group nodes are what MkDocs and the other tree-capable
+ * adapters map to, and label, divider, link, and API nodes only appear for
+ * Doxbrix. Page nodes carry the project-relative `path` so the editor can join
+ * them to the page list; the path is derived and never written back.
+ */
+export type NavigationNode = {
+    type: 'page';
+    file: string;
+    path?: string;
+    title?: string;
+    pageTitle?: string;
+    icon?: string;
+    hidden?: boolean;
+} | {
+    type: 'group';
+    label: string;
+    icon?: string;
+    hidden?: boolean;
+    items: NavigationNode[];
+} | {
+    type: 'label';
+    text: string;
+} | {
+    type: 'divider';
+} | {
+    type: 'link';
+    title: string;
+    href: string;
+    icon?: string;
+} | {
+    type: 'api';
+    title: string;
+    spec: string;
+    icon?: string;
+};
+export interface NavigationSpace {
+    name: string;
+    version?: string;
+    icon?: string;
+    nav: NavigationNode[];
+}
+export interface NavigationSupport {
+    icons: boolean;
+    hidden: boolean;
+    labels: boolean;
+    links: boolean;
+    dividers: boolean;
+    spaces: boolean;
+}
+export interface NavigationTree {
+    generator: string;
+    /** False when the generator keeps its navigation in code Doxloop cannot rewrite. */
+    editable: boolean;
+    reason?: string;
+    /** Project-relative file the navigation lives in. */
+    configFile: string;
+    fingerprint: string;
+    /** Whether every page must stay in navigation, which is the Doxbrix rule. */
+    requiresEveryPage: boolean;
+    /** Node types the generator can represent beyond pages and groups. */
+    supports: NavigationSupport;
+    spaces: NavigationSpace[];
+    /** Pages that exist on disk but are not referenced by the navigation. */
+    orphans: Array<{
+        file: string;
+        path: string;
+        title: string;
+    }>;
+    /** Icon names the Doxbrix reader can draw. */
+    icons: string[];
+}
+export declare const DOXBRIX_NAV_ICONS: string[];
+export declare function readNavigation(root: string): Promise<NavigationTree>;
+export interface NavigationWrite {
+    fingerprint: string;
+    spaces: Array<{
+        name: string;
+        version?: string;
+        nav: unknown;
+    }>;
+}
+export declare function writeNavigation(root: string, raw: unknown): Promise<NavigationTree>;
+/**
+ * Add one page to the Doxbrix navigation, used by generated content such as
+ * the glossary. The page joins the named group when it exists, otherwise the
+ * end of the first space. Other generators go through the adapter's
+ * `writeNavigation` hook.
+ */
+export declare function appendDoxbrixNavigationPage(root: string, project: DoxloopProject, page: {
+    file: string;
+    title: string;
+    icon?: string;
+    section?: string;
+}): Promise<void>;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/navigation.js

@@ -0,0 +1,310 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { applyDirectEdit } from './direct-edit.js';
+import { DoxloopError } from './errors.js';
+import { resolveContainedDirectory } from './fs.js';
+import { loadGeneratorAdapter } from './generators.js';
+import { loadPages, loadProject, loadSiteConfig, pageId, readPage, relativePath, siteConfigPath, } from './project.js';
+export const DOXBRIX_NAV_ICONS = [
+    'book', 'file', 'home', 'rocket', 'bolt', 'zap', 'terminal', 'code', 'braces', 'plug', 'settings',
+    'wrench', 'key', 'database', 'server', 'cloud', 'package', 'workflow', 'users', 'compass', 'globe',
+    'list', 'link', 'github', 'clock', 'history', 'search', 'sparkle',
+];
+const MAX_LABEL = 120;
+const NO_SUPPORT = { icons: false, hidden: false, labels: false, links: false, dividers: false, spaces: false };
+export async function readNavigation(root) {
+    const project = await loadProject(root);
+    const contentRoot = await contentDirectory(root, project);
+    const files = await loadPages(root, project);
+    const known = new Map();
+    for (const absolute of files) {
+        const page = await readPage(absolute);
+        const path = relativePath(root, absolute);
+        const entry = { path, title: page.title || labelFromFile(path) };
+        known.set(pageId(contentRoot, absolute), entry);
+        known.set(relativePath(contentRoot, absolute), entry);
+    }
+    if (project.generator === 'doxbrix') {
+        const configPath = await siteConfigPath(root, project);
+        const site = await loadSiteConfig(root, project);
+        const raw = await readFile(configPath, 'utf8');
+        const referenced = new Set();
+        const defaultVersion = (site.versions?.find((entry) => entry.default || entry.isDefault) ?? site.versions?.[0])?.version;
+        const spaces = site.spaces.map((space) => ({
+            name: space.name,
+            ...((space.version ?? defaultVersion) ? { version: (space.version ?? defaultVersion) } : {}),
+            ...(space.icon ? { icon: space.icon } : {}),
+            nav: decorate(space.nav, known, referenced),
+        }));
+        return {
+            generator: 'doxbrix',
+            editable: true,
+            configFile: relativePath(root, configPath),
+            fingerprint: fingerprint(raw),
+            requiresEveryPage: true,
+            supports: { icons: true, hidden: true, labels: true, links: true, dividers: true, spaces: true },
+            spaces,
+            orphans: orphans(files, root, known, referenced, (absolute) => pageId(contentRoot, absolute)),
+            icons: DOXBRIX_NAV_ICONS,
+        };
+    }
+    const adapter = await loadGeneratorAdapter(root, project);
+    const configFile = adapter.planning?.navigationFiles[0] ?? '';
+    const base = { generator: project.generator, configFile, requiresEveryPage: false, supports: NO_SUPPORT, icons: [] };
+    if (!adapter.readNavigationTree || !adapter.writeNavigationTree) {
+        return {
+            ...base,
+            editable: false,
+            reason: configFile
+                ? `${adapter.displayName} keeps its navigation in ${configFile}. Doxloop cannot rewrite that file safely, so edit it directly or ask the agent to change the navigation.`
+                : `${adapter.displayName} derives its navigation from the file system, so there is nothing to reorder here.`,
+            fingerprint: '',
+            spaces: [],
+            orphans: [],
+        };
+    }
+    const tree = await adapter.readNavigationTree({ root, contentRoot, project });
+    const referenced = new Set();
+    const nav = decorate(fromGeneratorTree(tree.nodes), known, referenced);
+    const configText = configFile ? await readFile(join(root, configFile), 'utf8').catch(() => '') : '';
+    return {
+        ...base,
+        editable: true,
+        fingerprint: fingerprint(configText || JSON.stringify(tree)),
+        spaces: [{ name: project.title, nav }],
+        orphans: orphans(files, root, known, referenced, (absolute) => relativePath(contentRoot, absolute)),
+    };
+}
+export async function writeNavigation(root, raw) {
+    const input = parseWrite(raw);
+    const current = await readNavigation(root);
+    if (!current.editable)
+        throw new DoxloopError(current.reason ?? 'This navigation cannot be edited from Doxloop.', 2);
+    if (input.fingerprint !== current.fingerprint) {
+        throw new DoxloopError('The navigation changed on disk since it was loaded. Reload the navigation and apply your changes again.');
+    }
+    const project = await loadProject(root);
+    const contentRoot = await contentDirectory(root, project);
+    const files = await loadPages(root, project);
+    const knownFiles = new Set(files.map((absolute) => (project.generator === 'doxbrix' ? pageId(contentRoot, absolute) : relativePath(contentRoot, absolute))));
+    const spaces = input.spaces.map((space, index) => ({
+        name: requireLabel(space.name, `Space ${index + 1} name`),
+        ...(space.version ? { version: space.version } : {}),
+        nav: sanitizeNodes(space.nav, knownFiles, new Set(), current.supports, `space "${space.name}"`),
+    }));
+    if (spaces.length === 0)
+        throw new DoxloopError('Navigation needs at least one space.', 2);
+    if (!current.supports.spaces && spaces.length > 1)
+        throw new DoxloopError(`${project.generator} navigation is a single tree.`, 2);
+    await applyDirectEdit(root, {
+        kind: 'navigation',
+        requestText: 'Reorganized the navigation',
+        files: current.configFile ? [current.configFile] : [],
+        apply: async () => {
+            if ((await readNavigation(root)).fingerprint !== input.fingerprint)
+                throw new DoxloopError('Navigation changed before saving. Reload and try again.');
+            if (project.generator === 'doxbrix') {
+                await writeDoxbrixNavigation(root, project, spaces);
+                return;
+            }
+            const adapter = await loadGeneratorAdapter(root, project);
+            await adapter.writeNavigationTree({ root, contentRoot, project, tree: { nodes: toGeneratorTree(spaces[0].nav) } });
+        },
+    });
+    return readNavigation(root);
+}
+/**
+ * Add one page to the Doxbrix navigation, used by generated content such as
+ * the glossary. The page joins the named group when it exists, otherwise the
+ * end of the first space. Other generators go through the adapter's
+ * `writeNavigation` hook.
+ */
+export async function appendDoxbrixNavigationPage(root, project, page) {
+    const configPath = await siteConfigPath(root, project);
+    const site = await loadSiteConfig(root, project);
+    const space = site.spaces[0];
+    if (!space)
+        throw new DoxloopError('docs.json has no space to add the page to.');
+    const existing = new Set();
+    const walk = (nodes) => {
+        for (const node of nodes) {
+            if (node.type === 'page')
+                existing.add(node.file);
+            else if (node.type === 'group')
+                walk(node.items);
+        }
+    };
+    for (const entry of site.spaces)
+        walk(entry.nav);
+    if (existing.has(page.file))
+        return;
+    const node = { type: 'page', file: page.file, title: page.title, ...(page.icon ? { icon: page.icon } : {}) };
+    const group = page.section
+        ? space.nav.find((entry) => entry.type === 'group' && entry.label === page.section)
+        : undefined;
+    if (group)
+        group.items.push(node);
+    else
+        space.nav.push(node);
+    await writeFile(configPath, `${JSON.stringify(site, null, 2)}\n`, 'utf8');
+}
+async function writeDoxbrixNavigation(root, project, spaces) {
+    const configPath = await siteConfigPath(root, project);
+    const site = await loadSiteConfig(root, project);
+    const defaultVersion = (site.versions?.find((entry) => entry.default || entry.isDefault) ?? site.versions?.[0])?.version;
+    const existing = new Map(site.spaces.map((space) => [JSON.stringify([space.version ?? defaultVersion, space.name]), space]));
+    const next = spaces.map((space, index) => {
+        if (space.version && site.versions?.length && !site.versions.some((entry) => entry.version === space.version))
+            throw new DoxloopError(`Unknown documentation version "${space.version}".`);
+        const previous = existing.get(JSON.stringify([space.version ?? defaultVersion, space.name])) ?? site.spaces[index];
+        return { ...(previous ?? {}), ...(space.version ? { version: space.version } : {}), name: space.name, nav: space.nav };
+    });
+    await writeFile(configPath, `${JSON.stringify({ ...site, spaces: next }, null, 2)}\n`, 'utf8');
+}
+function parseWrite(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new DoxloopError('A navigation write needs spaces and a fingerprint.', 2);
+    const body = raw;
+    if (typeof body.fingerprint !== 'string')
+        throw new DoxloopError('A navigation write needs the fingerprint it was loaded with.', 2);
+    if (!Array.isArray(body.spaces))
+        throw new DoxloopError('A navigation write needs a spaces array.', 2);
+    return {
+        fingerprint: body.fingerprint,
+        spaces: body.spaces.map((space) => {
+            const entry = (space && typeof space === 'object' ? space : {});
+            if (entry.version !== undefined && (typeof entry.version !== 'string' || !entry.version.trim()))
+                throw new DoxloopError('Space version must be a non-empty string.');
+            return { name: typeof entry.name === 'string' ? entry.name : '', ...(typeof entry.version === 'string' ? { version: entry.version } : {}), nav: entry.nav };
+        }),
+    };
+}
+function sanitizeNodes(raw, knownFiles, seen, supports, location) {
+    if (!Array.isArray(raw))
+        throw new DoxloopError(`${location} needs a list of navigation items.`, 2);
+    return raw.map((item, index) => {
+        const node = (item && typeof item === 'object' ? item : {});
+        const where = `${location} item ${index + 1}`;
+        const icon = supports.icons ? optionalIcon(node.icon, where) : undefined;
+        const hidden = supports.hidden && node.hidden === true;
+        switch (node.type) {
+            case 'page': {
+                const file = typeof node.file === 'string' ? node.file.trim().replace(/^\.?\//, '') : '';
+                if (!file || !knownFiles.has(file))
+                    throw new DoxloopError(`${where} points at "${file || '?'}", which is not a page in this project.`, 2);
+                if (seen.has(file))
+                    throw new DoxloopError(`"${file}" appears more than once in the navigation.`, 2);
+                seen.add(file);
+                const title = optionalLabel(node.title, `${where} title`);
+                return { type: 'page', file, ...(title ? { title } : {}), ...(icon ? { icon } : {}), ...(hidden ? { hidden } : {}) };
+            }
+            case 'group': {
+                const label = requireLabel(node.label, `${where} group label`);
+                return {
+                    type: 'group',
+                    label,
+                    ...(icon ? { icon } : {}),
+                    ...(hidden ? { hidden } : {}),
+                    items: sanitizeNodes(node.items ?? [], knownFiles, seen, supports, `group "${label}"`),
+                };
+            }
+            case 'label':
+                if (!supports.labels)
+                    throw new DoxloopError(`${where}: this generator has no section labels.`, 2);
+                return { type: 'label', text: requireLabel(node.text, `${where} label text`) };
+            case 'divider':
+                if (!supports.dividers)
+                    throw new DoxloopError(`${where}: this generator has no dividers.`, 2);
+                return { type: 'divider' };
+            case 'link': {
+                if (!supports.links)
+                    throw new DoxloopError(`${where}: this generator has no navigation links.`, 2);
+                const href = typeof node.href === 'string' ? node.href.trim() : '';
+                if (!/^(?:https:\/\/|\/(?!\/))/i.test(href))
+                    throw new DoxloopError(`${where} link needs an HTTPS or root-relative address.`, 2);
+                return { type: 'link', title: requireLabel(node.title, `${where} link title`), href, ...(icon ? { icon } : {}) };
+            }
+            case 'api': {
+                if (!supports.links)
+                    throw new DoxloopError(`${where}: this generator has no API entries.`, 2);
+                const spec = typeof node.spec === 'string' ? node.spec.trim() : '';
+                if (!spec)
+                    throw new DoxloopError(`${where} API entry needs a specification path.`, 2);
+                return { type: 'api', title: requireLabel(node.title, `${where} API title`), spec, ...(icon ? { icon } : {}) };
+            }
+            default:
+                throw new DoxloopError(`${where} has an unsupported type.`, 2);
+        }
+    });
+}
+function requireLabel(value, label) {
+    const text = optionalLabel(value, label);
+    if (!text)
+        throw new DoxloopError(`${label} is required.`, 2);
+    return text;
+}
+function optionalLabel(value, label) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (typeof value !== 'string')
+        throw new DoxloopError(`${label} must be text.`, 2);
+    const text = value.trim().replace(/\s+/g, ' ');
+    if (text.length > MAX_LABEL)
+        throw new DoxloopError(`${label} must be ${MAX_LABEL} characters or fewer.`, 2);
+    return text || undefined;
+}
+function optionalIcon(value, where) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (typeof value !== 'string' || !/^[a-z][a-z0-9-]{0,39}$/.test(value))
+        throw new DoxloopError(`${where} icon must be an icon name.`, 2);
+    return value;
+}
+function decorate(nodes, known, referenced) {
+    return nodes.map((node) => {
+        if (node.type === 'page') {
+            const file = node.file.replace(/^\.?\//, '');
+            const page = known.get(file);
+            if (page)
+                referenced.add(page.path);
+            return { ...node, file, ...(page ? { path: page.path, pageTitle: page.title } : {}) };
+        }
+        if (node.type === 'group')
+            return { ...node, items: decorate(node.items ?? [], known, referenced) };
+        return node;
+    });
+}
+function orphans(files, root, known, referenced, fileOf) {
+    return files
+        .map((absolute) => ({ file: fileOf(absolute), path: relativePath(root, absolute) }))
+        .filter((entry) => !referenced.has(entry.path))
+        .map((entry) => ({ ...entry, title: known.get(entry.file)?.title ?? labelFromFile(entry.path) }));
+}
+function fromGeneratorTree(nodes) {
+    return nodes.map((node) => (node.type === 'group'
+        ? { type: 'group', label: node.label, items: fromGeneratorTree(node.items) }
+        : { type: 'page', file: node.file, ...(node.title ? { title: node.title } : {}) }));
+}
+function toGeneratorTree(nodes) {
+    const output = [];
+    for (const node of nodes) {
+        if (node.type === 'page')
+            output.push({ type: 'page', file: node.file, ...(node.title ? { title: node.title } : {}) });
+        else if (node.type === 'group')
+            output.push({ type: 'group', label: node.label, items: toGeneratorTree(node.items) });
+    }
+    return output;
+}
+function fingerprint(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+async function contentDirectory(root, project) {
+    return resolveContainedDirectory(root, project.contentDir, 'Documentation content directory', {
+        allowRoot: project.generator === 'doxbrix',
+    });
+}
+function labelFromFile(path) {
+    return path.split('/').at(-1).replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ').replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+//# sourceMappingURL=navigation.js.map