@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/quality-lint.js

@@ -0,0 +1,124 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadPages, loadSiteConfig, readPage, relativePath } from './project.js';
+import { QUALITY_CODES } from './quality-contract.js';
+const MISSPELLINGS = {
+    accomodate: 'accommodate',
+    occured: 'occurred',
+    recieve: 'receive',
+    seperate: 'separate',
+    teh: 'the',
+    untill: 'until',
+};
+export async function lintDocumentation(root, project, config) {
+    const checks = [];
+    const paragraphs = new Map();
+    const maximumTitle = config.lint?.maximumTitleLength ?? 72;
+    for (const path of await loadPages(root, project)) {
+        const file = relativePath(root, path);
+        const page = await readPage(path);
+        if (page.title.length > maximumTitle)
+            checks.push(lint(file, `Title is ${page.title.length} characters; the configured maximum is ${maximumTitle}.`));
+        const prose = page.body.replace(/```[\s\S]*?```/g, '').replace(/<[^>]+>/g, ' ');
+        for (const [misspelling, replacement] of Object.entries(MISSPELLINGS)) {
+            if (new RegExp(`\\b${misspelling}\\b`, 'i').test(prose))
+                checks.push(lint(file, `Possible spelling error: use "${replacement}" instead of "${misspelling}".`, true));
+        }
+        for (const [term, preferred] of Object.entries(project.documentation.terminology)) {
+            if (term.toLowerCase() === preferred.toLowerCase() || preferred.length > 60)
+                continue;
+            if (new RegExp(`\\b${escapeRegExp(term)}\\b`, 'i').test(prose) && !new RegExp(escapeRegExp(preferred), 'i').test(prose))
+                checks.push(lint(file, `Terminology guidance prefers "${preferred}" where "${term}" is used.`));
+        }
+        const sentences = prose.split(/[.!?]+(?:\s|$)/).map((item) => item.trim()).filter((item) => item.split(/\s+/).length >= 4);
+        const long = sentences.filter((item) => item.split(/\s+/).length > 35);
+        if (long.length > Math.max(1, sentences.length / 4))
+            checks.push(lint(file, `${long.length} sentences exceed 35 words; shorten them for easier scanning.`));
+        for (const paragraph of prose.split(/\n\s*\n/).map(normalizeParagraph).filter((item) => item.length >= 100)) {
+            const files = paragraphs.get(paragraph) ?? [];
+            files.push(file);
+            paragraphs.set(paragraph, files);
+        }
+    }
+    for (const files of paragraphs.values())
+        if (new Set(files).size > 1)
+            checks.push(lint([...new Set(files)].join(', '), 'Substantial duplicate prose appears across multiple pages.'));
+    if (project.generator === 'doxbrix') {
+        const site = await loadSiteConfig(root, project);
+        const maximum = config.lint?.maximumNavigationLabelLength ?? 42;
+        for (const label of navigationLabels(site.spaces.flatMap((space) => space.nav)))
+            if (label.length > maximum)
+                checks.push(lint(join(project.contentDir, 'docs.json'), `Navigation label "${label}" is ${label.length} characters; the configured maximum is ${maximum}.`));
+    }
+    return checks.length > 0 ? checks : [{ code: QUALITY_CODES.lintPassed, category: 'lint', status: 'pass', message: 'Documentation linting found no terminology, duplication, spelling, readability, title, or navigation-label issues.' }];
+}
+export async function fixDocumentation(root, project) {
+    const changed = [];
+    for (const path of await loadPages(root, project)) {
+        const original = await readFile(path, 'utf8');
+        let next = normalizeLocalLinks(original.replace(/[ \t]+$/gm, ''));
+        next = addFenceLanguages(next);
+        next = repairSingleHeadingJumps(next);
+        if (!next.endsWith('\n'))
+            next += '\n';
+        if (next !== original) {
+            await writeFile(path, next, 'utf8');
+            changed.push(relativePath(root, path));
+        }
+    }
+    return { changed };
+}
+function addFenceLanguages(value) {
+    const lines = value.split('\n');
+    let insideFence = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const fence = /^```(.*)$/.exec(lines[index] ?? '');
+        if (!fence)
+            continue;
+        if (!insideFence && fence[1]?.trim() === '') {
+            const sample = lines[index + 1]?.trim() ?? '';
+            const language = /^\s*(?:\{|\[)/.test(sample) ? 'json' : /^(?:npm|pnpm|yarn|npx|curl|git|doxloop)\b/.test(sample) ? 'bash' : /^(?:const|let|var|import|export|function)\b/.test(sample) ? 'javascript' : '';
+            if (language)
+                lines[index] = `\`\`\`${language}`;
+        }
+        insideFence = !insideFence;
+    }
+    return lines.join('\n');
+}
+function repairSingleHeadingJumps(value) {
+    let previous = 0;
+    let insideFence = false;
+    return value.split('\n').map((line) => {
+        if (/^```/.test(line)) {
+            insideFence = !insideFence;
+            return line;
+        }
+        if (insideFence)
+            return line;
+        const match = /^(#{1,6})(\s+\S.*)$/.exec(line);
+        if (!match)
+            return line;
+        let level = match[1].length;
+        if (previous > 0 && level > previous + 1)
+            level = previous + 1;
+        previous = level;
+        return `${'#'.repeat(level)}${match[2]}`;
+    }).join('\n');
+}
+function normalizeLocalLinks(value) {
+    let insideFence = false;
+    return value.split('\n').map((line) => {
+        if (/^```/.test(line)) {
+            insideFence = !insideFence;
+            return line;
+        }
+        if (insideFence)
+            return line;
+        return line.replace(/\]\(\.\/([^)]*)\)/g, ']($1)').replace(/\]\(([^)]*\\[^)]*)\)/g, (_all, target) => `](${target.replace(/\\/g, '/')})`);
+    }).join('\n');
+}
+function navigationLabels(nodes) { return nodes.flatMap((node) => node.type === 'group' ? [node.label, ...navigationLabels(node.items)] : node.type === 'label' ? [node.text] : node.type === 'page' && node.title ? [node.title] : node.type === 'link' || node.type === 'api' ? [node.title] : []); }
+function lint(file, message, fixable = false) { return { code: QUALITY_CODES.lintIssue, category: 'lint', status: 'warning', message, file, ...(fixable ? { fixable: true } : {}) }; }
+function normalizeParagraph(value) { return value.toLowerCase().replace(/\s+/g, ' ').trim(); }
+function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+//# sourceMappingURL=quality-lint.js.map

package/dist/quality-rendered.d.ts

@@ -0,0 +1,11 @@
+import type { DoxloopProject, QualityCheck, QualityConfig } from './types.js';
+export declare function checkRenderedQuality(root: string, project: DoxloopProject, config: QualityConfig, updateVisuals: boolean): Promise<{
+    checks: QualityCheck[];
+    accessibility?: string;
+    visuals?: string;
+}>;
+export declare function compareScreenshots(baselinePath: string, currentPath: string, diffPath: string): Promise<{
+    ratio: number;
+    diff: string;
+}>;
+//# sourceMappingURL=quality-rendered.d.ts.map

package/dist/quality-rendered.js

@@ -0,0 +1,222 @@
+import { createHash } from 'node:crypto';
+import { cp, mkdir, readFile, readdir } from 'node:fs/promises';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import axe from 'axe-core';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+import { ensurePlaywright } from './capture.js';
+import { renderMarkdown } from './doxbrix-markdown.js';
+import { pathExists } from './fs.js';
+import { loadGeneratorAdapter } from './generators.js';
+import { loadPages, loadSiteConfig, pageId, readPage } from './project.js';
+import { doxbrixDocument } from './preview.js';
+import { QUALITY_CODES } from './quality-contract.js';
+export async function checkRenderedQuality(root, project, config, updateVisuals) {
+    if (!config.rendered?.enabled)
+        return { checks: [
+                { code: QUALITY_CODES.accessibilityManual, category: 'accessibility', status: 'skipped', message: 'Rendered checks are opt-in. Enable rendered.enabled in .doxloop/quality.json.' },
+                { code: QUALITY_CODES.visualSkipped, category: 'visual', status: 'skipped', message: 'Visual regression checks are disabled.' },
+            ] };
+    const pages = await renderedPages(root, project, config.rendered.routes ?? ['/']);
+    if (pages.length === 0)
+        return { checks: [{ code: QUALITY_CODES.accessibilityIssue, category: 'accessibility', status: 'fail', message: 'No representative rendered pages were found.' }, { code: QUALITY_CODES.visualSkipped, category: 'visual', status: 'skipped', message: 'No rendered pages are available for visual comparison.' }] };
+    const outputRoot = join(root, '.doxloop', 'quality-artifacts');
+    const currentRoot = join(outputRoot, 'visuals', project.generator);
+    const baselineRoot = join(root, '.doxloop', 'visual-baselines', project.generator);
+    await mkdir(currentRoot, { recursive: true });
+    const checks = [];
+    let playwright;
+    try {
+        playwright = await ensurePlaywright();
+    }
+    catch (error) {
+        return { checks: [
+                { code: QUALITY_CODES.accessibilityManual, category: 'accessibility', status: 'warning', message: 'Rendered accessibility automation is unavailable; manual review is required.', detail: error instanceof Error ? error.message : String(error) },
+                { code: QUALITY_CODES.visualSkipped, category: 'visual', status: 'warning', message: 'Visual screenshots could not be captured in this environment.' },
+            ] };
+    }
+    const browser = await playwright.chromium.launch({ headless: true });
+    try {
+        for (const rendered of pages) {
+            for (const theme of config.rendered.themes ?? ['light', 'dark'])
+                for (const viewport of config.rendered.viewports ?? []) {
+                    const context = await browser.newContext({ viewport: { width: viewport.width, height: viewport.height }, colorScheme: theme, reducedMotion: 'reduce' });
+                    try {
+                        const page = await context.newPage();
+                        await page.route('**/*', (route) => route.abort('blockedbyclient'));
+                        await page.setContent(rendered.html, { waitUntil: 'load' });
+                        await page.evaluate((selectedTheme) => {
+                            document.documentElement.dataset.colorTheme = selectedTheme;
+                            document.querySelectorAll('[data-color-theme]').forEach((element) => { element.dataset.colorTheme = selectedTheme; });
+                        }, theme);
+                        const slug = routeSlug(rendered.route);
+                        const directory = join(currentRoot, theme, slug);
+                        const screenshot = join(directory, `${viewport.name}.png`);
+                        await mkdir(directory, { recursive: true });
+                        await page.screenshot({ path: screenshot, fullPage: true, animations: 'disabled' });
+                        await page.addScriptTag({ content: axe.source });
+                        const axeIssues = await page.evaluate(async () => {
+                            const runner = globalThis.axe;
+                            return runner ? (await runner.run()).violations.map((violation) => `${violation.id}: ${violation.help}${violation.nodes.length ? ` — ${violation.nodes.slice(0, 3).flatMap((node) => node.target).join(', ')}` : ''}`) : ['Axe could not be loaded into the rendered page.'];
+                        });
+                        const issues = [...await page.evaluate(ACCESSIBILITY_SCRIPT), ...await keyboardIssues(page), ...axeIssues];
+                        for (const issue of issues)
+                            checks.push({ code: QUALITY_CODES.accessibilityIssue, category: 'accessibility', status: 'fail', message: issue, file: rendered.route });
+                        if (issues.length === 0)
+                            checks.push({ code: QUALITY_CODES.accessibilityPassed, category: 'accessibility', status: 'pass', message: `${rendered.route} passed automated landmark, name, heading, image, overflow, and focus checks at ${viewport.name}.`, file: rendered.route });
+                        const baseline = join(baselineRoot, theme, slug, `${viewport.name}.png`);
+                        if (updateVisuals) {
+                            await mkdir(dirname(baseline), { recursive: true });
+                            await cp(screenshot, baseline);
+                            checks.push({ code: QUALITY_CODES.visualCreated, category: 'visual', status: 'pass', message: `Updated ${project.generator}/${theme}/${slug}/${viewport.name} visual baseline.`, file: rendered.route });
+                        }
+                        else if (!(await pathExists(baseline)))
+                            checks.push({ code: QUALITY_CODES.visualChanged, category: 'visual', status: 'warning', message: `No approved visual baseline exists for ${rendered.route} at ${viewport.name}.`, file: rendered.route, detail: 'Run doxloop quality --rendered --update-visuals after intentional review.' });
+                        else {
+                            const comparison = await compareScreenshots(baseline, screenshot, join(directory, `${viewport.name}.diff.png`));
+                            const maximum = config.rendered.maximumDiffRatio ?? 0.001;
+                            if (comparison.ratio <= maximum)
+                                checks.push({ code: QUALITY_CODES.visualMatched, category: 'visual', status: 'pass', message: `${rendered.route} matches the approved ${theme} ${viewport.name} visual baseline (${(comparison.ratio * 100).toFixed(3)}% changed).`, file: rendered.route });
+                            else
+                                checks.push({ code: QUALITY_CODES.visualChanged, category: 'visual', status: 'fail', message: `${rendered.route} differs from the approved ${theme} ${viewport.name} baseline by ${(comparison.ratio * 100).toFixed(3)}%.`, file: rendered.route, detail: `Current: ${relative(root, screenshot)}\nDiff: ${relative(root, comparison.diff)}` });
+                        }
+                    }
+                    finally {
+                        await context.close();
+                    }
+                }
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    checks.push({ code: QUALITY_CODES.accessibilityManual, category: 'accessibility', status: 'warning', message: 'Automation cannot prove WCAG conformance. Manually review keyboard order, visible focus, contrast, zoom, screen-reader output, and reflow before release.' });
+    return { checks, accessibility: relative(root, outputRoot), visuals: relative(root, currentRoot) };
+}
+async function renderedPages(root, project, routes) {
+    if (project.generator === 'doxbrix') {
+        const [site, files] = await Promise.all([loadSiteConfig(root, project), loadPages(root, project)]);
+        const contentRoot = resolve(root, project.contentDir);
+        const css = await readFile(resolve(fileURLToPath(new URL('..', import.meta.url)), 'assets', 'doxbrix-preview.css'), 'utf8');
+        const byRoute = new Map(files.map((path) => [`/${pageId(contentRoot, path)}`, path]));
+        if (files[0])
+            byRoute.set('/', files[0]);
+        return Promise.all(routes.flatMap((route) => byRoute.get(route) ? [{ route, path: byRoute.get(route) }] : []).map(async ({ route, path }) => {
+            const page = await readPage(path);
+            return { route, html: doxbrixDocument({ site, title: page.title, ...(page.description ? { description: page.description } : {}), current: pageId(contentRoot, path), rendered: renderMarkdown(page.body) }).replace('<link rel="stylesheet" href="/__doxloop/doxbrix.css">', `<style>${css}</style>`) };
+        }));
+    }
+    const adapter = await loadGeneratorAdapter(root, project);
+    const output = resolve(root, adapter.build.outputDir);
+    if (!(await pathExists(output)))
+        return [];
+    const html = await listHtml(output);
+    const byRoute = new Map(html.map((path) => [htmlRoute(output, path), path]));
+    return Promise.all(routes.flatMap((route) => {
+        const normalized = normalizeRoute(route);
+        const path = byRoute.get(normalized);
+        return path ? [{ route: normalized, path }] : [];
+    }).map(async ({ route, path }) => ({ route, html: await inlineLocalAssets(await readFile(path, 'utf8'), path, output) })));
+}
+async function listHtml(root) {
+    const output = [];
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            output.push(...await listHtml(path));
+        else if (extname(path) === '.html')
+            output.push(path);
+    }
+    return output.sort();
+}
+function routeSlug(route) { return route.replace(/^\/+|\/+$/g, '').replace(/[^a-z0-9]+/gi, '-') || 'index'; }
+function normalizeRoute(route) { const value = `/${route.replace(/^\/+|\/+$/g, '')}`; return value === '/' ? value : `${value}/`; }
+function htmlRoute(output, path) {
+    const value = relative(output, path).replace(/\\/g, '/').replace(/(?:^|\/)index\.html$/, '').replace(/\.html$/, '/');
+    return normalizeRoute(value);
+}
+async function inlineLocalAssets(html, htmlPath, outputRoot) {
+    let result = html;
+    const styles = [...html.matchAll(/<link\b[^>]*\brel=["']stylesheet["'][^>]*\bhref=["']([^"']+)["'][^>]*>/gi)];
+    for (const match of styles) {
+        const asset = await localAsset(match[1], htmlPath, outputRoot);
+        if (asset)
+            result = result.replace(match[0], `<style data-doxloop-inline="${escapeAttribute(match[1])}">${(await readFile(asset, 'utf8')).replace(/<\/style/gi, '<\\/style')}</style>`);
+    }
+    const scripts = [...result.matchAll(/<script\b([^>]*)\bsrc=["']([^"']+)["']([^>]*)><\/script>/gi)];
+    for (const match of scripts) {
+        const asset = await localAsset(match[2], htmlPath, outputRoot);
+        if (asset)
+            result = result.replace(match[0], `<script${match[1] ?? ''}${match[3] ?? ''}>${(await readFile(asset, 'utf8')).replace(/<\/script/gi, '<\\/script')}</script>`);
+    }
+    return result;
+}
+async function localAsset(reference, htmlPath, outputRoot) {
+    if (/^(?:[a-z]+:|\/\/|data:)/i.test(reference))
+        return undefined;
+    const clean = reference.split(/[?#]/, 1)[0];
+    const path = resolve(clean.startsWith('/') ? outputRoot : dirname(htmlPath), clean.replace(/^\/+/, ''));
+    const rel = relative(outputRoot, path);
+    return rel !== '..' && !rel.startsWith('../') && !rel.startsWith('..\\') && await pathExists(path) ? path : undefined;
+}
+function escapeAttribute(value) { return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;'); }
+async function digest(path) { return createHash('sha256').update(await readFile(path)).digest('hex'); }
+export async function compareScreenshots(baselinePath, currentPath, diffPath) {
+    if (await digest(baselinePath) === await digest(currentPath))
+        return { ratio: 0, diff: diffPath };
+    const [baseline, current] = await Promise.all([readFile(baselinePath).then((value) => PNG.sync.read(value)), readFile(currentPath).then((value) => PNG.sync.read(value))]);
+    if (baseline.width !== current.width || baseline.height !== current.height)
+        return { ratio: 1, diff: currentPath };
+    const diff = new PNG({ width: current.width, height: current.height });
+    const changed = pixelmatch(baseline.data, current.data, diff.data, current.width, current.height, { threshold: 0.1, includeAA: false });
+    await writePng(diffPath, diff);
+    return { ratio: changed / Math.max(current.width * current.height, 1), diff: diffPath };
+}
+async function writePng(path, png) {
+    const { writeFile } = await import('node:fs/promises');
+    await writeFile(path, PNG.sync.write(png));
+}
+async function keyboardIssues(page) {
+    const count = await page.evaluate(() => document.querySelectorAll('a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])').length);
+    if (count === 0)
+        return [];
+    const seen = new Set();
+    for (let index = 0; index < Math.min(count + 1, 80); index += 1) {
+        await page.keyboard.press('Tab');
+        const name = await page.evaluate(() => {
+            const active = document.activeElement;
+            if (!active || active === document.body)
+                return '';
+            return active.getAttribute('aria-label') ?? active.getAttribute('href') ?? active.id ?? active.textContent?.trim().slice(0, 80) ?? active.tagName;
+        });
+        if (name)
+            seen.add(name);
+    }
+    return seen.size < Math.min(count, 2) ? ['Keyboard traversal did not reach the expected interactive controls.'] : [];
+}
+const ACCESSIBILITY_SCRIPT = String.raw `(() => {
+  const issues = [];
+  if (!document.documentElement.lang) issues.push('The rendered document needs a language declaration.');
+  if (!document.querySelector('main, [role="main"]')) issues.push('The rendered document needs a main landmark.');
+  if (!document.querySelector('h1')) issues.push('The rendered document needs an h1.');
+  document.querySelectorAll('img').forEach((image) => { if (!image.hasAttribute('alt')) issues.push('Every rendered image needs an alt attribute.'); });
+  document.querySelectorAll('button, a[href], input, select, textarea').forEach((control) => {
+    const name = control.getAttribute('aria-label') || control.getAttribute('title') || control.textContent?.trim() || control.getAttribute('placeholder');
+    if (!name) issues.push('Every interactive control needs an accessible name.');
+    if (control.getAttribute('tabindex') && Number(control.getAttribute('tabindex')) > 0) issues.push('Positive tabindex values create an unpredictable keyboard order.');
+  });
+  let previous = 0;
+  document.querySelectorAll('h1,h2,h3,h4,h5,h6').forEach((heading) => { const level = Number(heading.tagName.slice(1)); if (previous && level > previous + 1) issues.push('Rendered heading levels must not skip ranks.'); previous = level; });
+  if (document.documentElement.scrollWidth > window.innerWidth + 2) issues.push('The rendered page overflows horizontally at this viewport.');
+  const focusTarget = document.querySelector('a[href], button, input, select, textarea');
+  if (focusTarget) {
+    focusTarget.focus();
+    const focus = getComputedStyle(focusTarget);
+    if (focus.outlineStyle === 'none' && focus.boxShadow === 'none') issues.push('The first keyboard control has no detectable focus indicator.');
+  }
+  document.documentElement.style.zoom = '2';
+  if (document.documentElement.scrollWidth > window.innerWidth * 2 + 2) issues.push('The rendered page does not reflow cleanly at 200% zoom.');
+  return Array.from(new Set(issues));
+})()`;
+//# sourceMappingURL=quality-rendered.js.map

package/dist/quality-schema.d.ts

@@ -0,0 +1,3 @@
+import type { DoxloopProject, QualityCheck } from './types.js';
+export declare function lintSchemas(root: string, project: DoxloopProject): Promise<QualityCheck[]>;
+//# sourceMappingURL=quality-schema.d.ts.map

package/dist/quality-schema.js

@@ -0,0 +1,71 @@
+import { loadOpenApiSource } from './openapi.js';
+import { QUALITY_CODES } from './quality-contract.js';
+const METHODS = ['get', 'put', 'post', 'delete', 'patch', 'options', 'head', 'trace'];
+export async function lintSchemas(root, project) {
+    const sources = project.sources.filter((source) => source.kind === 'openapi');
+    if (sources.length === 0)
+        return [{ code: QUALITY_CODES.schemaPassed, category: 'schemas', status: 'pass', message: 'No connector-native schemas require linting.' }];
+    const checks = [];
+    for (const source of sources) {
+        try {
+            const loaded = await loadOpenApiSource(root, source);
+            const document = loaded.document;
+            const operationIds = new Map();
+            const rootSecurity = Array.isArray(document.security) && document.security.length > 0;
+            for (const [path, rawItem] of Object.entries(record(document.paths))) {
+                const item = record(rawItem);
+                for (const method of METHODS) {
+                    if (!record(item[method]) || Object.keys(record(item[method])).length === 0)
+                        continue;
+                    const operation = record(item[method]);
+                    const location = `${method.toUpperCase()} ${path}`;
+                    const operationId = text(operation.operationId);
+                    if (!operationId)
+                        checks.push(issue(source.path, `${location} should declare operationId.`, 'warning'));
+                    else if (operationIds.has(operationId))
+                        checks.push(issue(source.path, `${location} duplicates operationId "${operationId}" from ${operationIds.get(operationId)}.`, 'fail'));
+                    else
+                        operationIds.set(operationId, location);
+                    if (!text(operation.summary) && !text(operation.description))
+                        checks.push(issue(source.path, `${location} needs a summary or description for reader-facing API documentation.`, 'warning'));
+                    if (Object.keys(record(operation.responses)).length === 0)
+                        checks.push(issue(source.path, `${location} must declare at least one response.`, 'fail'));
+                    if (!rootSecurity && operation.security === undefined)
+                        checks.push(issue(source.path, `${location} does not declare an explicit security policy.`, 'warning'));
+                    for (const reference of references(operation)) {
+                        if (!reference.startsWith('#/'))
+                            checks.push(issue(source.path, `${location} uses unsupported external schema reference ${reference}.`, 'warning'));
+                        else if (resolvePointer(document, reference) === undefined)
+                            checks.push(issue(source.path, `${location} references missing schema ${reference}.`, 'fail'));
+                    }
+                }
+            }
+            if (!checks.some((check) => check.file === source.path))
+                checks.push({ code: QUALITY_CODES.schemaPassed, category: 'schemas', status: 'pass', message: `${source.name} passed OpenAPI structural linting.`, file: source.path });
+        }
+        catch (error) {
+            checks.push(issue(source.path, error instanceof Error ? error.message : String(error), 'fail'));
+        }
+    }
+    return checks;
+}
+function issue(file, message, status) { return { code: QUALITY_CODES.schemaIssue, category: 'schemas', status, message, file }; }
+function record(value) { return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; }
+function text(value) { return typeof value === 'string' && value.trim() ? value.trim() : undefined; }
+function references(value) {
+    if (Array.isArray(value))
+        return value.flatMap(references);
+    if (!value || typeof value !== 'object')
+        return [];
+    return Object.entries(value).flatMap(([key, item]) => key === '$ref' && typeof item === 'string' ? [item] : references(item));
+}
+function resolvePointer(document, pointer) {
+    let value = document;
+    for (const segment of pointer.slice(2).split('/').map((item) => item.replace(/~1/g, '/').replace(/~0/g, '~'))) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        value = value[segment];
+    }
+    return value;
+}
+//# sourceMappingURL=quality-schema.js.map

package/dist/release-notes.d.ts

@@ -0,0 +1,44 @@
+import type { DoxloopProject, ReleaseInventory, SourceBinding } from './types.js';
+/**
+ * Deterministic inputs for a release-notes plan: the commits and changed files
+ * between two Git refs of every Git-backed source, plus the section of the
+ * product's own changelog that names the release. The planner and writer get
+ * this inventory verbatim, so the page is grounded in the actual commit range
+ * rather than in what the agent remembers about the product.
+ */
+export declare const MAX_RELEASE_COMMITS = 200;
+export declare const MAX_RELEASE_FILES = 300;
+export interface SourceRefs {
+    source: string;
+    /** Newest first. */
+    tags: string[];
+    branches: string[];
+    head: string;
+    /** The refs a "latest release" request would use, when two tags exist. */
+    suggested?: {
+        from: string;
+        to: string;
+        version: string;
+    };
+}
+export interface ReleaseTemplateInput {
+    version: string;
+    from: string;
+    to: string;
+    /** Restrict the inventory to these sources; empty means every Git-backed directory source. */
+    sources?: string[];
+}
+/** Directory sources whose checkout is a Git repository. */
+export declare function gitBackedSources(root: string, project: DoxloopProject): Promise<SourceBinding[]>;
+export declare function listSourceRefs(root: string, sourceName: string): Promise<SourceRefs>;
+export declare function collectReleaseInventory(root: string, project: DoxloopProject, input: ReleaseTemplateInput): Promise<ReleaseInventory>;
+/** The changelog section that names the version, or the top of the file when no section matches. */
+export declare function changelogExcerpt(sourceRoot: string, version: string): Promise<{
+    path: string;
+    excerpt: string;
+} | undefined>;
+export declare function extractVersionSection(text: string, version: string): string;
+/** The inventory as the planner and writer read it. */
+export declare function formatReleaseInventory(inventory: ReleaseInventory): string;
+export declare function releaseNotesPagePath(version: string): string;
+//# sourceMappingURL=release-notes.d.ts.map