@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/quality-examples.js

@@ -0,0 +1,233 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { chmod, cp, mkdir, mkdtemp, readFile, readdir, realpath, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join, relative, resolve } from 'node:path';
+import { pathExists } from './fs.js';
+import { QUALITY_CODES } from './quality-contract.js';
+import { loadOpenApiSource } from './openapi.js';
+import { loadProject, sourceKind } from './project.js';
+export const EXAMPLES_FILE = join('.doxloop', 'examples.json');
+export async function verifyExamples(root, enabled) {
+    const path = join(root, EXAMPLES_FILE);
+    if (!(await pathExists(path)))
+        return [{ code: QUALITY_CODES.exampleSourceVerified, category: 'examples', status: 'skipped', message: 'No executable-example manifest is configured; examples remain source-verified.' }];
+    if (!enabled)
+        return [{ code: QUALITY_CODES.exampleSourceVerified, category: 'examples', status: 'skipped', message: `Executable examples are opt-in. Set examples.enabled in .doxloop/quality.json to run ${EXAMPLES_FILE}.` }];
+    const manifest = JSON.parse(await readFile(path, 'utf8'));
+    if (!validManifest(manifest))
+        return [{ code: QUALITY_CODES.exampleFailed, category: 'examples', status: 'fail', message: `${EXAMPLES_FILE} has an unsupported format.` }];
+    const checks = [];
+    for (const example of manifest.examples) {
+        if (example.runtime === 'source-verified' || example.runtime === 'shell-source-verified') {
+            checks.push({ code: QUALITY_CODES.exampleSourceVerified, category: 'examples', status: 'skipped', message: `${example.id} is explicitly source-verified rather than executed.`, file: example.file });
+            continue;
+        }
+        checks.push(example.runtime === 'python' ? await executePythonExample(root, example) : example.runtime === 'openapi-request' ? await verifyOpenApiRequest(root, example) : await executeNodeExample(root, example));
+    }
+    return checks.length > 0 ? checks : [{ code: QUALITY_CODES.exampleSourceVerified, category: 'examples', status: 'skipped', message: 'The executable-example manifest contains no examples.' }];
+}
+async function verifyOpenApiRequest(root, example) {
+    const source = contained(contained(root, example.workingDirectory), example.file);
+    if (!(await pathExists(source)))
+        return failure(example, 'The declared HTTP example file does not exist.');
+    const content = await readFile(source, 'utf8');
+    const request = /^\s*(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s+(\/\S*)/im.exec(content);
+    if (!request)
+        return failure(example, 'HTTP examples must contain a METHOD /path request line.');
+    const expectedStatus = /^\s*#\s*expect-status:\s*([1-5]\d\d)\s*$/im.exec(content)?.[1];
+    const operationId = `${request[1].toUpperCase()} ${request[2].split('?')[0]}`;
+    const project = await loadProject(root);
+    for (const binding of project.sources.filter((item) => sourceKind(item) === 'openapi')) {
+        try {
+            const loaded = await loadOpenApiSource(root, binding);
+            const operation = loaded.snapshot.operations[operationId];
+            if (!operation)
+                continue;
+            const pathItem = objectRecord(objectRecord(loaded.document.paths)[request[2].split('?')[0]]);
+            const rawOperation = objectRecord(pathItem[request[1].toLowerCase()]);
+            const responses = objectRecord(rawOperation.responses);
+            if (expectedStatus && !Object.hasOwn(responses, expectedStatus))
+                return failure(example, `${operationId} does not declare expected HTTP ${expectedStatus}.`);
+            return { code: QUALITY_CODES.examplePassed, category: 'examples', status: 'pass', message: `${example.id} matches ${operationId}${expectedStatus ? ` and HTTP ${expectedStatus}` : ''} in ${binding.name}.`, file: example.file };
+        }
+        catch { /* Continue to another configured OpenAPI source. */ }
+    }
+    return failure(example, `${operationId} was not found in a configured OpenAPI source.`);
+}
+function objectRecord(value) { return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; }
+async function executePythonExample(root, example) {
+    const image = process.env.DOXLOOP_PYTHON_SANDBOX_IMAGE;
+    if (!image || !/^[a-zA-Z0-9][a-zA-Z0-9./:_-]*@sha256:[a-f0-9]{64}$/.test(image)) {
+        return { code: QUALITY_CODES.exampleSourceVerified, category: 'examples', status: 'skipped', file: example.file, message: `${example.id} was not executed. Python requires a locally installed, digest-pinned container image in DOXLOOP_PYTHON_SANDBOX_IMAGE; host Python is never used as a sandbox.` };
+    }
+    const workingRoot = contained(root, example.workingDirectory);
+    const source = contained(workingRoot, example.file);
+    if (!(await pathExists(source)))
+        return failure(example, 'The declared Python example file does not exist.');
+    const content = await readFile(source, 'utf8');
+    if (containsCredential(content))
+        return failure(example, 'Execution was refused because the example appears to contain a real credential.');
+    if (containsProductionTarget(content))
+        return failure(example, 'Execution was refused because the example names a non-example network destination.');
+    if (/\b(?:ctypes|os\.system|subprocess|pty|multiprocessing)\b/.test(content))
+        return failure(example, 'Python examples may not start subprocesses or load native process APIs.');
+    const parent = await mkdtemp(join(tmpdir(), 'doxloop-python-example-'));
+    const container = `doxloop-example-${randomUUID()}`;
+    try {
+        const sandbox = join(parent, 'workspace');
+        await mkdir(sandbox);
+        const script = join(sandbox, basename(source));
+        await cp(source, script);
+        for (const fixture of example.fixtures) {
+            const fixtureSource = contained(workingRoot, fixture);
+            if (!(await pathExists(fixtureSource)))
+                return failure(example, `Fixture does not exist: ${fixture}`);
+            const unsafe = await unsafeFixture(fixtureSource);
+            if (unsafe)
+                return failure(example, `Fixture ${fixture} ${unsafe}.`);
+            await cp(fixtureSource, join(sandbox, basename(fixtureSource)), { recursive: true });
+        }
+        await readableFixtures(sandbox);
+        const result = await run('docker', [
+            'run', '--rm', '--pull=never', '--name', container,
+            '--network=none', '--read-only', '--cap-drop=ALL', '--security-opt=no-new-privileges',
+            '--pids-limit=32', '--memory=256m', '--cpus=1', '--user=65534:65534',
+            '--tmpfs', '/tmp:rw,noexec,nosuid,size=16m',
+            '--mount', `type=bind,src=${sandbox},dst=/workspace,readonly`,
+            '--workdir=/workspace', '--env=HOME=/tmp', '--entrypoint=python3', image,
+            '-I', `/workspace/${basename(source)}`,
+        ], sandbox, 20_000);
+        const matches = result.code === example.expected.exitCode &&
+            (example.expected.stdoutIncludes === undefined || result.stdout.includes(example.expected.stdoutIncludes)) &&
+            (example.expected.stderrIncludes === undefined || result.stderr.includes(example.expected.stderrIncludes));
+        return matches
+            ? { code: QUALITY_CODES.examplePassed, category: 'examples', status: 'pass', message: `${example.id} produced the declared result in a container with no network, a read-only filesystem, and only the declared example fixtures mounted.`, file: example.file }
+            : failure(example, `Expected exit ${example.expected.exitCode}; received ${result.code}.`, `stdout: ${clip(result.stdout)}\nstderr: ${clip(result.stderr)}`);
+    }
+    catch (error) {
+        return failure(example, error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        await run('docker', ['rm', '-f', container], parent, 5_000).catch(() => undefined);
+        await rm(parent, { recursive: true, force: true });
+    }
+}
+async function readableFixtures(path) {
+    const info = await stat(path);
+    await chmod(path, info.isDirectory() ? 0o755 : 0o644);
+    if (info.isDirectory())
+        for (const name of await readdir(path))
+            await readableFixtures(join(path, name));
+}
+async function executeNodeExample(root, example) {
+    const workingRoot = contained(root, example.workingDirectory);
+    const source = contained(workingRoot, example.file);
+    if (!(await pathExists(source)))
+        return failure(example, 'The declared example file does not exist.');
+    const content = await readFile(source, 'utf8');
+    if (containsCredential(content))
+        return failure(example, 'Execution was refused because the example appears to contain a real credential.');
+    if (containsProductionTarget(content))
+        return failure(example, 'Execution was refused because the example names a non-example network destination.');
+    if (example.network !== 'denied')
+        return failure(example, 'Executable examples must declare network: "denied".');
+    const parent = await mkdtemp(join(tmpdir(), 'doxloop-example-'));
+    try {
+        const sandbox = join(parent, 'workspace');
+        await mkdir(sandbox);
+        const script = join(sandbox, basename(source));
+        await cp(source, script);
+        for (const fixture of example.fixtures) {
+            const fixtureSource = contained(workingRoot, fixture);
+            if (!(await pathExists(fixtureSource)))
+                return failure(example, `Fixture does not exist: ${fixture}`);
+            const unsafe = await unsafeFixture(fixtureSource);
+            if (unsafe)
+                return failure(example, `Fixture ${fixture} ${unsafe}.`);
+            await cp(fixtureSource, join(sandbox, basename(fixtureSource)), { recursive: true });
+        }
+        const actualSandbox = await realpath(sandbox);
+        const actualScript = await realpath(script);
+        const result = await run(process.execPath, [
+            '--experimental-permission',
+            `--allow-fs-read=${actualSandbox}`,
+            `--allow-fs-write=${actualSandbox}`,
+            actualScript,
+        ], actualSandbox, 20_000);
+        const matches = result.code === example.expected.exitCode &&
+            (example.expected.stdoutIncludes === undefined || result.stdout.includes(example.expected.stdoutIncludes)) &&
+            (example.expected.stderrIncludes === undefined || result.stderr.includes(example.expected.stderrIncludes));
+        return matches
+            ? { code: QUALITY_CODES.examplePassed, category: 'examples', status: 'pass', message: `${example.id} produced the declared result in an isolated, network-denied Node process.`, file: example.file }
+            : failure(example, `Expected exit ${example.expected.exitCode}; received ${result.code}.`, `stdout: ${clip(result.stdout)}\nstderr: ${clip(result.stderr)}`);
+    }
+    catch (error) {
+        return failure(example, error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        await rm(parent, { recursive: true, force: true });
+    }
+}
+function run(command, args, cwd, timeout) {
+    return new Promise((resolveRun, reject) => {
+        const child = spawn(command, args, { cwd, env: { PATH: process.env.PATH ?? '' }, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timeout);
+        child.stdout.on('data', (chunk) => { if (stdout.length < 64_000)
+            stdout += chunk; });
+        child.stderr.on('data', (chunk) => { if (stderr.length < 64_000)
+            stderr += chunk; });
+        child.once('error', (error) => { clearTimeout(timer); reject(error); });
+        child.once('exit', (code) => { clearTimeout(timer); resolveRun({ code: timedOut ? 124 : (code ?? 1), stdout, stderr }); });
+    });
+}
+function contained(root, candidate) {
+    const path = resolve(root, candidate);
+    const rel = relative(resolve(root), path);
+    if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || rel.startsWith('../') || rel.startsWith('..\\'))
+        throw new Error(`Example path leaves the project: ${candidate}`);
+    return path;
+}
+function validManifest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const manifest = value;
+    return manifest.schemaVersion === 1 && Array.isArray(manifest.examples) && manifest.examples.every((example) => !!example && typeof example === 'object' && typeof example.id === 'string' && ['node', 'python', 'openapi-request', 'shell-source-verified', 'source-verified'].includes(example.runtime) && typeof example.file === 'string' && typeof example.workingDirectory === 'string' && Array.isArray(example.fixtures) && example.fixtures.every((item) => typeof item === 'string') && example.network === 'denied' && !!example.expected && Number.isInteger(example.expected.exitCode));
+}
+function containsCredential(value) { return /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|\bAKIA[0-9A-Z]{16}\b|\bgh[pousr]_[A-Za-z0-9]{36,}\b/.test(value); }
+function containsProductionTarget(value) {
+    return [...value.matchAll(/https?:\/\/([^/:\s"'`]+)/gi)].some((match) => {
+        const host = match[1]?.toLowerCase() ?? '';
+        return host !== 'localhost' && host !== '127.0.0.1' && host !== '::1' && host !== 'example.com' && !host.endsWith('.example');
+    });
+}
+async function unsafeFixture(path) {
+    const info = await stat(path);
+    if (info.isDirectory()) {
+        for (const entry of await readdir(path)) {
+            const unsafe = await unsafeFixture(join(path, entry));
+            if (unsafe)
+                return unsafe;
+        }
+        return undefined;
+    }
+    if (info.size > 1_000_000)
+        return 'exceeds the 1 MB fixture safety limit';
+    try {
+        const content = await readFile(path, 'utf8');
+        if (content.includes('\0'))
+            return undefined;
+        if (containsCredential(content))
+            return 'appears to contain a real credential';
+        if (containsProductionTarget(content))
+            return 'names a non-example network destination';
+    }
+    catch { /* Binary fixtures are copied but never interpreted. */ }
+    return undefined;
+}
+function failure(example, message, detail) { return { code: QUALITY_CODES.exampleFailed, category: 'examples', status: 'fail', message: `${example.id}: ${message}`, file: example.file, ...(detail ? { detail } : {}) }; }
+function clip(value) { return value.trim().slice(0, 1_000); }
+//# sourceMappingURL=quality-examples.js.map

package/dist/quality-gates.d.ts

@@ -0,0 +1,16 @@
+import type { QualityReport } from './types.js';
+export declare const QUALITY_REPORT_DIRECTORY: string;
+export declare const LATEST_QUALITY_REPORT: string;
+export interface RunQualityOptions {
+    offline?: boolean;
+    rendered?: boolean;
+    examples?: boolean;
+    fix?: boolean;
+    updateVisuals?: boolean;
+    approveBaseline?: boolean;
+}
+export declare function runQuality(root: string, options?: RunQualityOptions): Promise<QualityReport>;
+export declare function readLatestQualityReport(root: string): Promise<QualityReport | undefined>;
+export declare function qualityInputHash(root: string): Promise<string>;
+export declare function formatQualityReport(report: QualityReport): string;
+//# sourceMappingURL=quality-gates.d.ts.map

package/dist/quality-gates.js

@@ -0,0 +1,192 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { assertPublicContract } from './contract-validation.js';
+import { loadGeneratorAdapter } from './generators.js';
+import { pathExists } from './fs.js';
+import { loadPages, loadProject, relativePath } from './project.js';
+import { reverifyClaims } from './quality-claims.js';
+import { loadQualityConfig } from './quality-config.js';
+import { QUALITY_CODES, QUALITY_CONTRACT_VERSION } from './quality-contract.js';
+import { verifyExamples } from './quality-examples.js';
+import { lintDocumentation, fixDocumentation } from './quality-lint.js';
+import { checkExternalLinks } from './quality-links.js';
+import { checkRenderedQuality } from './quality-rendered.js';
+import { lintSchemas } from './quality-schema.js';
+import { validateProject } from './validation.js';
+import { buildDoxbrixStaticSite } from './doxbrix-build.js';
+export const QUALITY_REPORT_DIRECTORY = join('.doxloop', 'quality-reports');
+export const LATEST_QUALITY_REPORT = join(QUALITY_REPORT_DIRECTORY, 'latest.json');
+export async function runQuality(root, options = {}) {
+    const project = await loadProject(root);
+    const config = await loadQualityConfig(root);
+    if (options.rendered !== undefined)
+        config.rendered = { ...config.rendered, enabled: options.rendered };
+    if (options.examples !== undefined)
+        config.examples = { ...config.examples, enabled: options.examples };
+    if (options.offline !== undefined)
+        config.links = { ...config.links, mode: options.offline ? 'offline' : 'online' };
+    if (options.fix)
+        await fixDocumentation(root, project);
+    const validation = await validateProject(root);
+    const checks = validation.issues.map((issue) => ({ code: `validation.${issue.code}`, category: 'validation', status: issue.severity === 'error' ? 'fail' : 'warning', message: issue.message, ...(issue.file ? { file: issue.file } : {}) }));
+    if (validation.issues.length === 0)
+        checks.push({ code: QUALITY_CODES.validation, category: 'validation', status: 'pass', message: `${validation.pages.length} documentation pages passed deterministic validation.` });
+    checks.push(await strictBuild(root, project));
+    const [links, examples, schemas, lint, claims] = await Promise.all([
+        checkExternalLinks(root, project, config, options.offline === undefined ? {} : { offline: options.offline }),
+        verifyExamples(root, config.examples?.enabled === true),
+        lintSchemas(root, project),
+        lintDocumentation(root, project, config),
+        reverifyClaims(root, project, config.readerVerification?.enabled === true),
+    ]);
+    checks.push(...links, ...examples, ...schemas, ...lint, ...claims.checks);
+    const rendered = await checkRenderedQuality(root, project, config, options.updateVisuals === true);
+    checks.push(...rendered.checks);
+    applySuppressions(checks, config);
+    await applyRatchet(root, checks, config, options.approveBaseline === true);
+    const counts = {
+        passed: checks.filter((check) => check.status === 'pass').length,
+        warnings: checks.filter((check) => check.status === 'warning').length,
+        failed: checks.filter((check) => check.status === 'fail').length,
+        skipped: checks.filter((check) => check.status === 'skipped').length,
+    };
+    const generatedAt = new Date().toISOString();
+    const inputHash = await qualityInputHash(root);
+    const reportName = `quality-${generatedAt.replace(/[:.]/g, '-')}.json`;
+    const report = {
+        schemaVersion: 1,
+        contractVersion: QUALITY_CONTRACT_VERSION,
+        generatedAt,
+        inputHash,
+        project: project.title,
+        generator: project.generator,
+        status: counts.failed > 0 ? 'fail' : counts.warnings > 0 ? 'warning' : 'pass',
+        checks,
+        counts,
+        artifacts: {
+            report: join(QUALITY_REPORT_DIRECTORY, reportName),
+            ...(rendered.accessibility ? { accessibility: rendered.accessibility } : {}),
+            ...(rendered.visuals ? { visuals: rendered.visuals } : {}),
+        },
+        options: { offline: config.links?.mode === 'offline', rendered: config.rendered?.enabled === true, examples: config.examples?.enabled === true },
+    };
+    const directory = join(root, QUALITY_REPORT_DIRECTORY);
+    await mkdir(directory, { recursive: true });
+    await assertPublicContract('quality-report-v1', report);
+    const serialized = `${JSON.stringify(report, null, 2)}\n`;
+    await Promise.all([writeFile(join(directory, reportName), serialized, 'utf8'), writeFile(join(root, LATEST_QUALITY_REPORT), serialized, 'utf8')]);
+    return report;
+}
+async function applyRatchet(root, checks, config, approve) {
+    const setting = config.ratchet;
+    if (!setting?.enabled && !approve)
+        return;
+    const baselinePath = join(root, setting?.baselineFile ?? '.doxloop/quality-baseline.json');
+    const current = checks.filter((check) => check.status === 'warning' || check.status === 'fail').map(issueIdentity);
+    if (approve) {
+        await mkdir(dirname(baselinePath), { recursive: true });
+        await writeFile(baselinePath, `${JSON.stringify({ schemaVersion: 1, issues: current.sort() }, null, 2)}\n`, 'utf8');
+        return;
+    }
+    if (!(await pathExists(baselinePath))) {
+        checks.push({ code: QUALITY_CODES.ratchetBaselineMissing, category: 'validation', status: 'warning', message: 'Quality ratcheting is enabled but no approved baseline exists.', detail: `Run doxloop quality --approve-quality-baseline after reviewing current issues.` });
+        return;
+    }
+    let known = new Set();
+    try {
+        const value = JSON.parse(await readFile(baselinePath, 'utf8'));
+        if (value.schemaVersion === 1 && Array.isArray(value.issues))
+            known = new Set(value.issues.filter((item) => typeof item === 'string'));
+    }
+    catch { /* Malformed baselines fail open as a visible warning below. */ }
+    if (known.size === 0 && current.length > 0)
+        checks.push({ code: QUALITY_CODES.ratchetBaselineInvalid, category: 'validation', status: 'warning', message: 'The quality baseline is empty or invalid; current issues were not suppressed.' });
+    for (const check of checks) {
+        if ((check.status === 'warning' || check.status === 'fail') && known.has(issueIdentity(check))) {
+            check.detail = [check.detail, 'Present in the approved quality baseline; kept visible for ratcheting.'].filter(Boolean).join('\n');
+            check.status = 'skipped';
+        }
+    }
+}
+function applySuppressions(checks, config) {
+    const now = Date.now();
+    for (const check of checks) {
+        const suppression = config.suppressions?.find((item) => item.code === check.code && (!item.file || item.file === check.file) && (!item.expires || Date.parse(item.expires) > now));
+        if (!suppression || (check.status !== 'warning' && check.status !== 'fail'))
+            continue;
+        check.status = 'skipped';
+        check.detail = [check.detail, `Suppressed: ${suppression.reason}${suppression.expires ? ` (expires ${suppression.expires})` : ''}`].filter(Boolean).join('\n');
+    }
+}
+function issueIdentity(check) { return `${check.code}\0${check.file ?? ''}\0${check.message}`; }
+export async function readLatestQualityReport(root) {
+    const path = join(root, LATEST_QUALITY_REPORT);
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        return value.schemaVersion === 1 && value.contractVersion === QUALITY_CONTRACT_VERSION && Array.isArray(value.checks) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function qualityInputHash(root) {
+    const project = await loadProject(root);
+    const files = await loadPages(root, project);
+    const candidates = [join(root, '.doxloop', 'project.json'), join(root, '.doxloop', 'quality.json'), join(root, '.doxloop', 'examples.json'), join(root, '.doxloop', 'evidence-map.json'), ...files];
+    const hash = createHash('sha256');
+    for (const path of candidates.sort()) {
+        if (!(await pathExists(path)))
+            continue;
+        hash.update(relativePath(root, path));
+        hash.update('\0');
+        hash.update(await readFile(path));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+export function formatQualityReport(report) {
+    const icon = report.status === 'pass' ? '✓' : report.status === 'warning' ? '!' : '✗';
+    const lines = [`${icon} Release quality: ${report.status}`, `${report.counts.failed} failed · ${report.counts.warnings} warnings · ${report.counts.passed} passed · ${report.counts.skipped} skipped`];
+    for (const category of [...new Set(report.checks.map((check) => check.category))]) {
+        lines.push('', category[0].toUpperCase() + category.slice(1));
+        for (const check of report.checks.filter((item) => item.category === category && item.status !== 'pass'))
+            lines.push(`  ${check.status === 'fail' ? '✗' : check.status === 'warning' ? '!' : '–'} ${check.code}${check.file ? ` · ${check.file}` : ''}\n    ${check.message}${check.detail ? `\n    ${check.detail}` : ''}`);
+    }
+    lines.push('', `Report: ${report.artifacts.report}`);
+    return lines.join('\n');
+}
+async function strictBuild(root, project) {
+    if (project.generator === 'doxbrix') {
+        try {
+            const result = await buildDoxbrixStaticSite({ root });
+            return { code: QUALITY_CODES.buildPassed, category: 'build', status: 'pass', message: `Doxbrix static build passed (${result.pages} pages).` };
+        }
+        catch (error) {
+            return { code: QUALITY_CODES.buildFailed, category: 'build', status: 'fail', message: 'Doxbrix static build failed.', detail: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    const adapter = await loadGeneratorAdapter(root, project);
+    const result = await runShell(adapter.build.command, root);
+    return result.code === 0
+        ? { code: QUALITY_CODES.buildPassed, category: 'build', status: 'pass', message: `${adapter.displayName} strict build passed.` }
+        : { code: QUALITY_CODES.buildFailed, category: 'build', status: 'fail', message: `${adapter.displayName} strict build failed with exit code ${result.code}.`, detail: clip(`${result.stdout}\n${result.stderr}`) };
+}
+function runShell(command, cwd) {
+    return new Promise((resolveRun, reject) => {
+        const child = spawn(command, { cwd, env: process.env, shell: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => { if (stdout.length < 128_000)
+            stdout += chunk; });
+        child.stderr.on('data', (chunk) => { if (stderr.length < 128_000)
+            stderr += chunk; });
+        child.once('error', reject);
+        child.once('exit', (code) => resolveRun({ code: code ?? 1, stdout, stderr }));
+    });
+}
+function clip(value) { return value.trim().slice(-4_000); }
+//# sourceMappingURL=quality-gates.js.map

package/dist/quality-links.d.ts

@@ -0,0 +1,7 @@
+import type { DoxloopProject, QualityCheck, QualityConfig } from './types.js';
+export declare function checkExternalLinks(root: string, project: DoxloopProject, config: QualityConfig, options?: {
+    offline?: boolean;
+    fetch?: typeof globalThis.fetch;
+    resolveHostname?: (hostname: string) => Promise<string[]>;
+}): Promise<QualityCheck[]>;
+//# sourceMappingURL=quality-links.d.ts.map

package/dist/quality-links.js

@@ -0,0 +1,149 @@
+import { contentLinks } from './content-links.js';
+import { lookup } from 'node:dns/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { isIP } from 'node:net';
+import { join } from 'node:path';
+import { isPrivateAddress } from './capture.js';
+import { pathExists } from './fs.js';
+import { loadPages, relativePath } from './project.js';
+import { QUALITY_CODES } from './quality-contract.js';
+const CACHE_FILE = join('.doxloop', 'cache', 'external-links.json');
+const MAX_REDIRECTS = 5;
+export async function checkExternalLinks(root, project, config, options = {}) {
+    const references = await externalReferences(root, project);
+    if (references.size === 0)
+        return [{ code: QUALITY_CODES.linkOk, category: 'links', status: 'pass', message: 'No literal external links were found in Markdown, HTML attributes, or reStructuredText. Dynamic links and cross-reference roles require the native generator check.' }];
+    const cache = await readCache(root);
+    const checks = [];
+    const links = config.links ?? {};
+    const offline = options.offline ?? links.mode === 'offline';
+    const maxAge = (links.cacheHours ?? 24) * 3_600_000;
+    for (const [url, files] of references) {
+        const file = [...files].sort().join(', ');
+        if (ignored(url, links.ignore ?? []) || !allowed(url, links.allowHosts ?? [])) {
+            checks.push({ code: QUALITY_CODES.linkSkipped, category: 'links', status: 'skipped', message: `External link is excluded by policy: ${url}`, file });
+            continue;
+        }
+        const cached = cache.links[url];
+        const fresh = cached && Date.now() - Date.parse(cached.checkedAt) <= maxAge;
+        if (offline) {
+            checks.push(cached
+                ? resultForStatus(url, file, cached.status, `Cached result from ${cached.checkedAt}.`)
+                : { code: QUALITY_CODES.linkSkipped, category: 'links', status: 'skipped', message: `External link was not checked in offline mode: ${url}`, file, detail: 'Run without --offline to populate the cache.' });
+            continue;
+        }
+        if (fresh) {
+            checks.push(resultForStatus(url, file, cached.status, `Cached result from ${cached.checkedAt}.`));
+            continue;
+        }
+        try {
+            const result = await fetchLink(url, {
+                fetch: options.fetch ?? globalThis.fetch,
+                resolveHostname: options.resolveHostname ?? resolvePublicHostname,
+                timeoutMs: links.timeoutMs ?? 8_000,
+                retries: links.retries ?? 2,
+            });
+            cache.links[url] = { checkedAt: new Date().toISOString(), status: result.status, finalUrl: result.url };
+            checks.push(resultForStatus(url, file, result.status));
+        }
+        catch (error) {
+            checks.push({ code: QUALITY_CODES.linkUnavailable, category: 'links', status: 'warning', message: `External link could not be confirmed: ${url}`, file, detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    if (!offline)
+        await writeCache(root, cache);
+    return checks;
+}
+async function externalReferences(root, project) {
+    const output = new Map();
+    for (const path of await loadPages(root, project)) {
+        const raw = await readFile(path, 'utf8');
+        for (const rawUrl of contentLinks(raw)) {
+            if (!/^https?:\/\//i.test(rawUrl))
+                continue;
+            let url;
+            try {
+                url = new URL(rawUrl);
+            }
+            catch {
+                continue;
+            }
+            url.hash = '';
+            const key = url.toString();
+            const files = output.get(key) ?? new Set();
+            files.add(relativePath(root, path));
+            output.set(key, files);
+        }
+    }
+    return output;
+}
+async function fetchLink(url, options) {
+    let lastError;
+    for (let attempt = 0; attempt <= options.retries; attempt += 1) {
+        try {
+            return await fetchLinkOnce(url, options);
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === options.retries)
+                break;
+        }
+    }
+    throw lastError;
+}
+async function fetchLinkOnce(raw, options) {
+    let current = new URL(raw);
+    for (let count = 0; count <= MAX_REDIRECTS; count += 1) {
+        if (!['http:', 'https:'].includes(current.protocol) || current.username || current.password)
+            throw new Error('Only credential-free HTTP and HTTPS links are allowed.');
+        const addresses = await options.resolveHostname(current.hostname);
+        if (addresses.length === 0 || addresses.some(isPrivateAddress))
+            throw new Error(`Private or unresolved host blocked: ${current.hostname}`);
+        const response = await options.fetch(current, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(options.timeoutMs), headers: { 'user-agent': 'Doxloop-Link-Checker/1' } });
+        if (response.status >= 300 && response.status < 400) {
+            if (count === MAX_REDIRECTS)
+                throw new Error('Redirect limit exceeded.');
+            const location = response.headers.get('location');
+            if (!location)
+                return { status: response.status, url: current.toString() };
+            current = new URL(location, current);
+            continue;
+        }
+        if (response.status === 405) {
+            const get = await options.fetch(current, { method: 'GET', redirect: 'manual', signal: AbortSignal.timeout(options.timeoutMs), headers: { range: 'bytes=0-0', 'user-agent': 'Doxloop-Link-Checker/1' } });
+            return { status: get.status, url: current.toString() };
+        }
+        if (response.status >= 500 || response.status === 408 || response.status === 429)
+            throw new Error(`Temporary HTTP ${response.status}.`);
+        return { status: response.status, url: current.toString() };
+    }
+    throw new Error('Redirect limit exceeded.');
+}
+function resultForStatus(url, file, status, detail) {
+    if (status >= 200 && status < 400)
+        return { code: QUALITY_CODES.linkOk, category: 'links', status: 'pass', message: `External link responded with HTTP ${status}: ${url}`, file, ...(detail ? { detail } : {}) };
+    if (status === 401 || status === 403)
+        return { code: QUALITY_CODES.linkUnavailable, category: 'links', status: 'warning', message: `External link requires authentication (HTTP ${status}): ${url}`, file, ...(detail ? { detail } : {}) };
+    return { code: QUALITY_CODES.linkBroken, category: 'links', status: 'fail', message: `External link responded with HTTP ${status}: ${url}`, file, ...(detail ? { detail } : {}) };
+}
+function allowed(raw, hosts) { return hosts.length === 0 || hosts.includes(new URL(raw).hostname); }
+function ignored(raw, patterns) { return patterns.some((pattern) => raw === pattern || raw.startsWith(pattern)); }
+async function resolvePublicHostname(hostname) { return isIP(hostname) ? [hostname] : (await lookup(hostname, { all: true, verbatim: true })).map((item) => item.address); }
+async function readCache(root) {
+    const path = join(root, CACHE_FILE);
+    if (!(await pathExists(path)))
+        return { schemaVersion: 1, links: {} };
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        return value.schemaVersion === 1 && value.links && typeof value.links === 'object' ? value : { schemaVersion: 1, links: {} };
+    }
+    catch {
+        return { schemaVersion: 1, links: {} };
+    }
+}
+async function writeCache(root, cache) {
+    const path = join(root, CACHE_FILE);
+    await mkdir(join(root, '.doxloop', 'cache'), { recursive: true });
+    await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`, 'utf8');
+}
+//# sourceMappingURL=quality-links.js.map

package/dist/quality-lint.d.ts

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