@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/generators.js

@@ -3,11 +3,35 @@ import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { DoxloopError, UsageError } from './errors.js';
 import { GENERATOR_API_VERSION, } from './generator-api.js';
+export const GENERATOR_TIERS = {
+    full: {
+        label: 'Full',
+        description: 'Navigation, components, and diagrams are validated and documented; preview and strict build are exercised in CI.',
+    },
+    supported: {
+        label: 'Supported',
+        description: 'Nested navigation is validated where the configuration is readable and reported as unverified otherwise; authoring syntax is documented.',
+    },
+    basic: {
+        label: 'Basic',
+        description: 'Scaffold, preview, and file checks work; navigation checks are limited to what the scaffold owns.',
+    },
+};
+export const GENERATOR_TOOLCHAINS = {
+    node: { label: 'Node.js 20.12+', detail: 'Node.js with npm, pnpm, or yarn on the PATH.' },
+    python: { label: 'Python 3.9+', detail: 'python3 with the venv and pip modules; Doxloop creates .doxloop/venv on first preview.' },
+    hugo: { label: 'Hugo', detail: 'The hugo binary on the PATH (extended edition recommended).' },
+    ruby: { label: 'Ruby + Bundler', detail: 'ruby and bundle on the PATH; Doxloop installs gems under .doxloop/bundle on first preview.' },
+};
 export const GENERATOR_CATALOG = [
     {
         id: 'doxbrix',
         displayName: 'Doxbrix',
         skillName: 'doxloop-doxbrix',
+        buildCommand: 'doxloop export --out build',
+        outputDir: 'build',
+        tier: 'full',
+        toolchain: [],
     },
     {
         id: 'docusaurus',
@@ -16,6 +40,8 @@ export const GENERATOR_CATALOG = [
         skillName: 'doxloop-docusaurus',
         buildCommand: 'npm run build',
         outputDir: 'build',
+        tier: 'full',
+        toolchain: ['node'],
     },
     {
         id: 'mkdocs',
@@ -24,6 +50,8 @@ export const GENERATOR_CATALOG = [
         skillName: 'doxloop-mkdocs',
         buildCommand: 'mkdocs build --strict',
         outputDir: 'site',
+        tier: 'full',
+        toolchain: ['python'],
     },
     {
         id: 'sphinx',
@@ -32,6 +60,8 @@ export const GENERATOR_CATALOG = [
         skillName: 'doxloop-sphinx',
         buildCommand: 'sphinx-build -W -b html docs _build/html',
         outputDir: '_build/html',
+        tier: 'supported',
+        toolchain: ['python'],
     },
     {
         id: 'hugo',
@@ -40,6 +70,8 @@ export const GENERATOR_CATALOG = [
         skillName: 'doxloop-hugo',
         buildCommand: 'hugo --minify',
         outputDir: 'public',
+        tier: 'supported',
+        toolchain: ['hugo'],
     },
     {
         id: 'vitepress',
@@ -48,6 +80,8 @@ export const GENERATOR_CATALOG = [
         skillName: 'doxloop-vitepress',
         buildCommand: 'npm run docs:build',
         outputDir: 'docs/.vitepress/dist',
+        tier: 'supported',
+        toolchain: ['node'],
     },
     {
         id: 'markdoc',
@@ -56,6 +90,8 @@ export const GENERATOR_CATALOG = [
         skillName: 'doxloop-markdoc',
         buildCommand: 'npm run build',
         outputDir: 'dist',
+        tier: 'basic',
+        toolchain: ['node'],
     },
     {
         id: 'nextra',
@@ -64,6 +100,8 @@ export const GENERATOR_CATALOG = [
         skillName: 'doxloop-nextra',
         buildCommand: 'npm run build',
         outputDir: 'out',
+        tier: 'basic',
+        toolchain: ['node'],
     },
     {
         id: 'starlight',
@@ -72,6 +110,8 @@ export const GENERATOR_CATALOG = [
         skillName: 'doxloop-starlight',
         buildCommand: 'npm run build',
         outputDir: 'dist',
+        tier: 'supported',
+        toolchain: ['node'],
     },
     {
         id: 'jekyll',
@@ -80,6 +120,8 @@ export const GENERATOR_CATALOG = [
         skillName: 'doxloop-jekyll',
         buildCommand: 'bundle exec jekyll build --strict_front_matter',
         outputDir: '_site',
+        tier: 'basic',
+        toolchain: ['ruby'],
     },
     {
         id: 'static',
@@ -88,6 +130,8 @@ export const GENERATOR_CATALOG = [
         skillName: 'doxloop-static',
         buildCommand: 'npm run build',
         outputDir: 'site',
+        tier: 'basic',
+        toolchain: ['node'],
     },
 ];
 export function generatorCatalogEntry(id) {
@@ -156,6 +200,9 @@ export async function installedGeneratorEntries(root) {
         installed: entry.id === 'doxbrix' ||
             (entry.packageName !== undefined &&
                 resolveGeneratorPackage(root, entry.packageName) !== undefined),
+        tierLabel: GENERATOR_TIERS[entry.tier].label,
+        tierDescription: GENERATOR_TIERS[entry.tier].description,
+        toolchainLabels: entry.toolchain.map((id) => GENERATOR_TOOLCHAINS[id].label),
     })));
 }
 function validateAdapter(value, expectedId, packageName) {
@@ -175,6 +222,9 @@ function validateAdapter(value, expectedId, packageName) {
         !adapter.authoring ||
         typeof adapter.authoring.skillName !== 'string' ||
         typeof adapter.authoring.skillDirectory !== 'string' ||
+        (adapter.planning !== undefined &&
+            (!Array.isArray(adapter.planning.navigationFiles) ||
+                !adapter.planning.navigationFiles.every((file) => typeof file === 'string'))) ||
         !adapter.project ||
         !Array.isArray(adapter.project.pageExtensions) ||
         !Array.isArray(adapter.project.gitignore) ||
@@ -188,7 +238,10 @@ function validateAdapter(value, expectedId, packageName) {
         typeof adapter.validate !== 'function' ||
         (adapter.resolveLocalAsset !== undefined &&
             typeof adapter.resolveLocalAsset !== 'function') ||
-        (adapter.readPage !== undefined && typeof adapter.readPage !== 'function')) {
+        (adapter.readPage !== undefined && typeof adapter.readPage !== 'function') ||
+        (adapter.writeNavigation !== undefined &&
+            typeof adapter.writeNavigation !== 'function') ||
+        (adapter.renderPage !== undefined && typeof adapter.renderPage !== 'function')) {
         throw incompatible(packageName, 'does not satisfy the generator adapter contract');
     }
     return adapter;

package/dist/git-delivery.d.ts

@@ -0,0 +1,17 @@
+export interface GitDeliveryResult {
+    schemaVersion: 1;
+    proposalId: string;
+    branch: string;
+    baseBranch: string;
+    commit: string;
+    createdAt: string;
+    compareUrl?: string;
+    pullRequestCommand?: string;
+    pushedAt?: string;
+    pullRequestUrl?: string;
+}
+/** Push a previously prepared branch and optionally ask GitHub CLI to open its pull request. */
+export declare function publishProposalBranch(root: string, proposalId: string, createPullRequest: boolean): Promise<GitDeliveryResult>;
+/** Materialize a reviewed proposal on an isolated local Git branch. */
+export declare function createProposalBranch(root: string, proposalId: string, requestedBranch?: string): Promise<GitDeliveryResult>;
+//# sourceMappingURL=git-delivery.d.ts.map

package/dist/git-delivery.js

@@ -0,0 +1,123 @@
+import { execFile } from 'node:child_process';
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { DoxloopError } from './errors.js';
+import { ensureGitignoreEntries, pathExists } from './fs.js';
+import { readSyncRun, runWorkspace } from './sync-runs.js';
+const execute = promisify(execFile);
+/** Push a previously prepared branch and optionally ask GitHub CLI to open its pull request. */
+export async function publishProposalBranch(root, proposalId, createPullRequest) {
+    const path = join(root, '.doxloop', 'deliveries', `${proposalId}.json`);
+    if (!(await pathExists(path)))
+        throw new DoxloopError('Prepare the proposal branch before publishing it.');
+    let delivery;
+    try {
+        delivery = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        throw new DoxloopError('The saved proposal delivery record is unreadable.');
+    }
+    if (delivery.schemaVersion !== 1 || delivery.proposalId !== proposalId || !delivery.branch || !delivery.commit)
+        throw new DoxloopError('The saved proposal delivery record is invalid.');
+    const current = (await git(root, ['rev-parse', delivery.branch])).trim();
+    if (current !== delivery.commit)
+        throw new DoxloopError('The prepared delivery branch changed after review. Prepare a new branch before publishing.');
+    if (!(await optionalGit(root, ['remote', 'get-url', 'origin'])))
+        throw new DoxloopError('Add a Git remote named origin before publishing this branch.');
+    await git(root, ['push', '--set-upstream', 'origin', delivery.branch]);
+    let pullRequestUrl = delivery.pullRequestUrl;
+    if (createPullRequest && !pullRequestUrl) {
+        try {
+            pullRequestUrl = (await execute('gh', ['pr', 'create', '--fill', '--base', delivery.baseBranch, '--head', delivery.branch], { cwd: root, maxBuffer: 2_000_000 })).stdout.trim();
+        }
+        catch (error) {
+            throw new DoxloopError(`The branch was pushed, but GitHub CLI could not create the pull request: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    delivery = { ...delivery, pushedAt: new Date().toISOString(), ...(pullRequestUrl ? { pullRequestUrl } : {}) };
+    await writeFile(path, `${JSON.stringify(delivery, null, 2)}\n`, 'utf8');
+    return delivery;
+}
+/** Materialize a reviewed proposal on an isolated local Git branch. */
+export async function createProposalBranch(root, proposalId, requestedBranch) {
+    const run = await readSyncRun(root, proposalId);
+    if (!['awaiting-review', 'partially-applied'].includes(run.status))
+        throw new DoxloopError('Only a reviewable proposal can be prepared as a Git branch.');
+    if (!(await pathExists(join(root, '.git'))))
+        throw new DoxloopError('Pull-request delivery requires the documentation project to be a Git repository.');
+    const branch = requestedBranch?.trim() || `doxloop/${proposalId}`;
+    await git(root, ['check-ref-format', '--branch', branch]);
+    const baseBranch = (await git(root, ['branch', '--show-current'])).trim() || 'HEAD';
+    const parent = await mkdtemp(join(tmpdir(), 'doxloop-delivery-'));
+    const worktree = join(parent, 'worktree');
+    try {
+        await git(root, ['worktree', 'add', '--detach', worktree, 'HEAD']);
+        await git(worktree, ['checkout', '-b', branch]);
+        for (const change of run.changes) {
+            const target = contained(worktree, change.path);
+            if (change.kind === 'deleted')
+                await rm(target, { force: true, recursive: true });
+            else {
+                const source = contained(runWorkspace(root, proposalId), change.path);
+                await mkdir(dirname(target), { recursive: true });
+                await cp(source, target, { recursive: true });
+            }
+        }
+        await git(worktree, ['add', '--all']);
+        const status = await git(worktree, ['status', '--porcelain']);
+        if (!status.trim())
+            throw new DoxloopError('The proposal does not produce a Git change against the current documentation branch.');
+        await git(worktree, ['-c', 'user.name=Doxloop', '-c', 'user.email=doxloop@local', 'commit', '-m', `docs: apply ${proposalId}`]);
+        const commit = (await git(worktree, ['rev-parse', 'HEAD'])).trim();
+        const remote = await optionalGit(root, ['remote', 'get-url', 'origin']);
+        const compareUrl = remote ? githubCompareUrl(remote.trim(), baseBranch, branch) : undefined;
+        const result = {
+            schemaVersion: 1,
+            proposalId,
+            branch,
+            baseBranch,
+            commit,
+            createdAt: new Date().toISOString(),
+            ...(compareUrl ? { compareUrl } : {}),
+        };
+        await ensureGitignoreEntries(root, ['.doxloop/deliveries/']);
+        const directory = join(root, '.doxloop', 'deliveries');
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await writeFile(join(directory, `${proposalId}.json`), `${JSON.stringify(result, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        return result;
+    }
+    finally {
+        await optionalGit(root, ['worktree', 'remove', '--force', worktree]);
+        await rm(parent, { recursive: true, force: true });
+    }
+}
+async function git(cwd, args) {
+    try {
+        return (await execute('git', args, { cwd, maxBuffer: 2_000_000 })).stdout;
+    }
+    catch (error) {
+        throw new DoxloopError(error instanceof Error ? error.message : String(error));
+    }
+}
+async function optionalGit(cwd, args) {
+    try {
+        return (await execute('git', args, { cwd, maxBuffer: 2_000_000 })).stdout;
+    }
+    catch {
+        return undefined;
+    }
+}
+function contained(root, candidate) {
+    const path = resolve(root, candidate);
+    const rel = relative(resolve(root), path);
+    if (rel === '..' || rel.startsWith(`..${sep}`))
+        throw new DoxloopError(`Proposal path leaves the Git worktree: ${candidate}`);
+    return path;
+}
+function githubCompareUrl(remote, base, branch) {
+    const match = /github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?$/.exec(remote);
+    return match ? `https://github.com/${match[1]}/${match[2]}/compare/${encodeURIComponent(base)}...${encodeURIComponent(branch)}?expand=1` : undefined;
+}
+//# sourceMappingURL=git-delivery.js.map

package/dist/globs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Match a project-relative POSIX path against a glob pattern.
+ *
+ * Supported syntax is deliberately small: `*` inside one segment, `**` across
+ * segments, and `?` for one character. A pattern without a slash matches the
+ * file name at any depth, which is what people expect from `.gitignore` and
+ * keeps `pnpm-lock.yaml` or `*.test.ts` working without a leading `**\/`.
+ */
+export declare function matchesGlob(path: string, pattern: string): boolean;
+export declare function matchesAnyGlob(path: string, patterns: readonly string[]): boolean;
+/**
+ * Decide whether a changed source path is worth documenting attention.
+ * `ignore` always wins so a broad `watch` entry stays easy to narrow.
+ */
+export declare function isWatchedPath(path: string, watch: readonly string[], ignore: readonly string[]): boolean;
+//# sourceMappingURL=globs.d.ts.map

package/dist/globs.js

@@ -0,0 +1,65 @@
+const SEGMENT = '[^/]';
+/**
+ * Match a project-relative POSIX path against a glob pattern.
+ *
+ * Supported syntax is deliberately small: `*` inside one segment, `**` across
+ * segments, and `?` for one character. A pattern without a slash matches the
+ * file name at any depth, which is what people expect from `.gitignore` and
+ * keeps `pnpm-lock.yaml` or `*.test.ts` working without a leading `**\/`.
+ */
+export function matchesGlob(path, pattern) {
+    const normalizedPath = normalize(path);
+    const normalizedPattern = normalize(pattern);
+    if (normalizedPattern === '')
+        return false;
+    const effective = normalizedPattern.includes('/')
+        ? normalizedPattern
+        : `**/${normalizedPattern}`;
+    return globRegExp(effective).test(normalizedPath);
+}
+export function matchesAnyGlob(path, patterns) {
+    return patterns.some((pattern) => matchesGlob(path, pattern));
+}
+/**
+ * Decide whether a changed source path is worth documenting attention.
+ * `ignore` always wins so a broad `watch` entry stays easy to narrow.
+ */
+export function isWatchedPath(path, watch, ignore) {
+    if (matchesAnyGlob(path, ignore))
+        return false;
+    if (watch.length === 0)
+        return true;
+    return matchesAnyGlob(path, watch);
+}
+function normalize(value) {
+    return value.trim().split('\\').join('/').replace(/^\.\//, '').replace(/\/+$/, '');
+}
+function globRegExp(pattern) {
+    let source = '^';
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        if (character === '*') {
+            const doubled = pattern[index + 1] === '*';
+            if (doubled) {
+                // `a/**/b` must also match `a/b`, so the separator is part of the group.
+                if (pattern[index + 2] === '/') {
+                    source += `(?:${SEGMENT}+/)*`;
+                    index += 2;
+                    continue;
+                }
+                source += '.*';
+                index += 1;
+                continue;
+            }
+            source += `${SEGMENT}*`;
+            continue;
+        }
+        if (character === '?') {
+            source += SEGMENT;
+            continue;
+        }
+        source += character.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`${source}$`);
+}
+//# sourceMappingURL=globs.js.map

package/dist/glossary.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A glossary page generated from the documentation brief's terminology map,
+ * so the terms a team curates in Settings become a reader-facing page without
+ * an agent run. The page carries a marker so regenerating it never overwrites
+ * a glossary a person wrote by hand.
+ */
+export declare const GLOSSARY_MARKER = "doxloop:glossary";
+export interface GlossaryTerm {
+    term: string;
+    definition: string;
+}
+export interface GlossaryState {
+    /** Terms from the project brief, merged with the current plan's terminology. */
+    terms: GlossaryTerm[];
+    /** Project-relative path of the glossary page when one exists. */
+    page?: string;
+    /** True when the existing page was generated by Doxloop and can be regenerated. */
+    generated: boolean;
+    /** How many terms came from the current documentation plan rather than the brief. */
+    fromPlan: number;
+}
+export declare function readGlossary(root: string): Promise<GlossaryState>;
+export declare function generateGlossaryPage(root: string, raw: unknown): Promise<GlossaryState>;
+export declare function readerDefinition(definition: string): string;
+export declare function renderGlossary(terms: GlossaryTerm[], format: 'markdown' | 'rst' | 'html', productTitle: string): string;
+//# sourceMappingURL=glossary.d.ts.map

package/dist/glossary.js

@@ -0,0 +1,179 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { applyDirectEdit } from './direct-edit.js';
+import { DoxloopError } from './errors.js';
+import { EVIDENCE_MAP_FILE, readEvidenceMap, writeEvidenceMap } from './evidence.js';
+import { pathExists, readJson, resolveContainedDirectory } from './fs.js';
+import { loadGeneratorAdapter } from './generators.js';
+import { appendDoxbrixNavigationPage } from './navigation.js';
+import { loadProject, pageExtensions, relativePath, siteConfigPath } from './project.js';
+/**
+ * A glossary page generated from the documentation brief's terminology map,
+ * so the terms a team curates in Settings become a reader-facing page without
+ * an agent run. The page carries a marker so regenerating it never overwrites
+ * a glossary a person wrote by hand.
+ */
+export const GLOSSARY_MARKER = 'doxloop:glossary';
+export async function readGlossary(root) {
+    const project = await loadProject(root);
+    const brief = termsFromRecord(project.documentation.terminology);
+    const known = new Set(brief.map((entry) => entry.term.toLowerCase()));
+    const planned = (await planTerminology(root)).filter((entry) => !known.has(entry.term.toLowerCase()));
+    const location = await glossaryLocation(root, project);
+    const exists = await pathExists(location.absolute);
+    const generated = exists ? (await readFile(location.absolute, 'utf8')).includes(GLOSSARY_MARKER) : false;
+    return {
+        terms: [...brief, ...planned].sort(byTerm),
+        ...(exists ? { page: location.path } : {}),
+        generated,
+        fromPlan: planned.length,
+    };
+}
+export async function generateGlossaryPage(root, raw) {
+    const body = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+    const project = await loadProject(root);
+    const state = await readGlossary(root);
+    const terms = Array.isArray(body.terms) ? parseTerms(body.terms) : state.terms;
+    if (terms.length === 0)
+        throw new DoxloopError('Add at least one term under Settings → Audience and voice before generating a glossary.', 2);
+    const location = await glossaryLocation(root, project);
+    if (state.page && !state.generated && body.replace !== true) {
+        throw new DoxloopError(`${state.page} already exists and was not generated by Doxloop. Choose "Replace" to overwrite it.`);
+    }
+    const adapter = project.generator === 'doxbrix' ? undefined : await loadGeneratorAdapter(root, project);
+    const content = renderGlossary(terms, location.format, project.title);
+    const navigationFile = project.generator === 'doxbrix'
+        ? relativePath(root, await siteConfigPath(root, project))
+        : adapter?.planning?.navigationFiles[0];
+    const files = [location.path, EVIDENCE_MAP_FILE, ...(navigationFile ? [navigationFile] : [])];
+    await applyDirectEdit(root, {
+        kind: 'glossary',
+        requestText: `Generated the glossary from ${terms.length} term${terms.length === 1 ? '' : 's'}`,
+        files,
+        pagesChanged: 1,
+        apply: async () => {
+            await writeFile(location.absolute, content, 'utf8');
+            if (project.generator === 'doxbrix') {
+                await appendDoxbrixNavigationPage(root, project, { file: 'glossary', title: 'Glossary', icon: 'book', section: 'Reference' });
+            }
+            else if (adapter?.writeNavigation) {
+                await adapter.writeNavigation({
+                    root,
+                    contentRoot: location.contentRoot,
+                    project,
+                    action: 'add',
+                    page: { path: location.contentRelative, title: 'Glossary', section: 'Reference' },
+                });
+            }
+            const evidence = (await readEvidenceMap(root)) ?? { schemaVersion: 1, pages: {} };
+            evidence.pages[location.path] = {
+                sources: [],
+                confidence: 'inferred',
+                claims: terms.map((entry) => `${entry.term}: ${entry.definition}`),
+            };
+            await writeEvidenceMap(root, evidence);
+        },
+    });
+    return readGlossary(root);
+}
+/**
+ * Plan terminology doubles as a writer style sheet ("use this capitalization",
+ * "use X instead of Y"). Readers need only the defining part, so style clauses
+ * are dropped, and an entry that is nothing but a style note is left out.
+ */
+const STYLE_CLAUSE = /^(use|prefer|avoid|do not|don't|never|always|write|spell|capitali[sz]e|keep)\b|\bcapitali[sz]ation\b|\binstead of\b/i;
+export function readerDefinition(definition) {
+    const clauses = definition.trim().split(/;\s+|(?<=\.)\s+/).map((clause) => clause.trim()).filter(Boolean);
+    const kept = clauses.filter((clause) => !STYLE_CLAUSE.test(clause));
+    if (kept.length === 0)
+        return '';
+    const text = kept.join(' ').replace(/[;,]\s*$/, '');
+    return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+/** "app state" reads as a heading when capitalised; code-like terms ("onChange", "x.y") keep their exact spelling. */
+function headingTerm(term) {
+    return /^[a-z][a-z -]*$/.test(term) ? term[0].toUpperCase() + term.slice(1) : term;
+}
+export function renderGlossary(terms, format, productTitle) {
+    const sorted = [...terms]
+        .map((entry) => ({ term: entry.term, definition: readerDefinition(entry.definition) }))
+        .filter((entry) => entry.definition)
+        .sort(byTerm);
+    const description = `Definitions of the terms used across the ${productTitle} documentation.`;
+    if (format === 'rst') {
+        const entries = sorted.map((entry) => `   ${entry.term}\n      ${entry.definition.replace(/\n+/g, ' ')}`).join('\n\n');
+        return `.. ${GLOSSARY_MARKER}\n\nGlossary\n========\n\n${description}\n\n.. glossary::\n   :sorted:\n\n${entries}\n`;
+    }
+    if (format === 'html') {
+        const items = sorted.map((entry) => `      <dt id="${slug(entry.term)}">${escapeHtml(entry.term)}</dt>\n      <dd>${escapeHtml(entry.definition)}</dd>`).join('\n');
+        return `<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="utf-8">\n    <title>Glossary</title>\n    <meta name="description" content="${escapeHtml(description)}">\n    <!-- ${GLOSSARY_MARKER} -->\n  </head>\n  <body>\n    <main>\n      <h1>Glossary</h1>\n      <p>${escapeHtml(description)}</p>\n      <dl>\n${items}\n      </dl>\n    </main>\n  </body>\n</html>\n`;
+    }
+    const sections = sorted.map((entry) => `## ${headingTerm(entry.term)}\n\n${entry.definition.trim()}\n`).join('\n');
+    return `---\ntitle: "Glossary"\ndescription: ${JSON.stringify(description)}\nicon: book\n---\n\n<!-- ${GLOSSARY_MARKER} -->\n\n${description} Each entry gives the meaning used throughout these pages.\n\n${sections}`;
+}
+async function glossaryLocation(root, project) {
+    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Documentation content directory', {
+        allowRoot: project.generator === 'doxbrix',
+    });
+    const adapter = project.generator === 'doxbrix' ? undefined : await loadGeneratorAdapter(root, project);
+    const format = adapter?.project.contentFormat ?? 'markdown';
+    const extensions = [...(await pageExtensions(root, project))];
+    const extension = project.generator === 'doxbrix'
+        ? '.mdx'
+        : format === 'rst'
+            ? '.rst'
+            : format === 'html'
+                ? '.html'
+                : extensions.find((entry) => entry === '.md') ?? extensions[0] ?? '.md';
+    const contentRelative = `glossary${extension}`;
+    const absolute = join(contentRoot, contentRelative);
+    return { absolute, path: relativePath(root, absolute), contentRelative, contentRoot, format };
+}
+async function planTerminology(root) {
+    const path = join(root, '.doxloop', 'documentation-plan.json');
+    if (!(await pathExists(path)))
+        return [];
+    try {
+        const plan = await readJson(path);
+        return termsFromRecord(plan.terminology);
+    }
+    catch {
+        return [];
+    }
+}
+function termsFromRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return [];
+    return Object.entries(value)
+        .filter((entry) => typeof entry[1] === 'string' && entry[0].trim() !== '' && entry[1].trim() !== '')
+        .map(([term, definition]) => ({ term: term.trim(), definition: definition.trim() }));
+}
+function parseTerms(raw) {
+    const seen = new Set();
+    const terms = [];
+    for (const entry of raw) {
+        const item = entry && typeof entry === 'object' ? entry : {};
+        const term = typeof item.term === 'string' ? item.term.trim() : '';
+        const definition = typeof item.definition === 'string' ? item.definition.trim() : '';
+        if (!term || !definition)
+            continue;
+        if (term.length > 80 || definition.length > 1000)
+            throw new DoxloopError(`"${term.slice(0, 40)}" is too long for a glossary entry.`, 2);
+        const key = term.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        terms.push({ term, definition });
+    }
+    return terms;
+}
+function byTerm(left, right) {
+    return left.term.localeCompare(right.term, undefined, { sensitivity: 'base' });
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '') || 'term';
+}
+function escapeHtml(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+}
+//# sourceMappingURL=glossary.js.map