@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/prompts.js

@@ -1,4 +1,5 @@
 import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
 import { styleText } from 'node:util';
 import { booleanFlag } from './args.js';
 import { DoxloopError } from './errors.js';
@@ -38,6 +39,7 @@ class LineReader {
     pending;
     canceled = false;
     prompt;
+    cancel;
     constructor(io) {
         this.prompt = createInterface({ input: io.input, output: io.output });
         this.prompt.on('line', (line) => {
@@ -50,7 +52,7 @@ class LineReader {
                 this.queue.push(line);
             }
         });
-        const cancel = () => {
+        this.cancel = () => {
             this.canceled = true;
             if (this.pending) {
                 const waiting = this.pending;
@@ -58,8 +60,8 @@ class LineReader {
                 waiting.reject(promptCanceled());
             }
         };
-        this.prompt.on('SIGINT', cancel);
-        this.prompt.on('close', cancel);
+        this.prompt.on('SIGINT', this.cancel);
+        this.prompt.on('close', this.cancel);
     }
     next(io, query) {
         io.output.write(query);
@@ -73,7 +75,10 @@ class LineReader {
         });
     }
     close() {
-        this.prompt.removeAllListeners('close');
+        // Keep readline's own `close` listeners intact. They detach its input and
+        // keypress handlers; removing all listeners here leaves an old interface
+        // echoing every subsequent prompt, so typed characters appear repeatedly.
+        this.prompt.removeListener('close', this.cancel);
         this.prompt.close();
     }
 }
@@ -108,6 +113,30 @@ export async function promptText(options) {
         reader.close();
     }
 }
+/**
+ * Read one line without echoing it, for passwords. The readline interface
+ * writes its echo to a sink, so a terminal shows nothing while typing; piped
+ * input is read as a plain line.
+ */
+export async function promptSecret(options) {
+    const io = options.io ?? defaultIo();
+    io.output.write(`${color(io, 'cyan', '◆')} ${options.message} ${color(io, 'dim', '(typing is hidden)')}\n`);
+    io.output.write(`${color(io, 'dim', '│')}  `);
+    const sink = new Writable({ write(_chunk, _encoding, callback) { callback(); } });
+    const reader = createInterface({ input: io.input, output: sink, terminal: io.input.isTTY === true });
+    try {
+        const line = await new Promise((resolve, reject) => {
+            reader.once('line', resolve);
+            reader.once('SIGINT', () => reject(promptCanceled()));
+            reader.once('close', () => reject(promptCanceled()));
+        });
+        io.output.write('\n');
+        return line;
+    }
+    finally {
+        reader.close();
+    }
+}
 export async function promptConfirm(options) {
     const io = options.io ?? defaultIo();
     const fallback = options.initial ?? true;

package/dist/proposal-replay.d.ts

@@ -0,0 +1,32 @@
+import type { ValidationIssue } from './types.js';
+export interface ReplayResult {
+    /** Where the copy the checks ran on was left (removed unless `keep`). */
+    workspace: string;
+    /** Validation errors before any repair; what the run itself would have shown. */
+    before: {
+        errors: number;
+        warnings: number;
+        issues: ValidationIssue[];
+    };
+    /** Doxloop's repairs, in order. */
+    repairs: string[];
+    /** Screenshot defects the tolerant check recorded. */
+    screenshotDefects: string[];
+    /** Validation after every repair; what the accept check sees. */
+    after: {
+        errors: number;
+        warnings: number;
+        issues: ValidationIssue[];
+    };
+}
+export interface ReplayOptions {
+    /** Leave the working copy in place for inspection. */
+    keep?: boolean;
+    log?: (line: string) => void;
+}
+/**
+ * Run the post-authoring pipeline over a copy of `<run-dir>/workspace` using
+ * the run's approved plan. The original run folder is never modified.
+ */
+export declare function replayRun(runDirectory: string, options?: ReplayOptions): Promise<ReplayResult>;
+//# sourceMappingURL=proposal-replay.d.ts.map

package/dist/proposal-replay.js

@@ -0,0 +1,99 @@
+/**
+ * Replay the end-of-run checks over a recorded run workspace.
+ *
+ * Every "the run succeeded but the proposal is blocked" failure came from the
+ * interaction of steps that each had unit tests: reuse of planning captures,
+ * the screenshot validator, the retake, the tolerant downgrade, the post-pass
+ * and the accept check. They were only ever exercised together on a real
+ * half-hour run. A replay runs exactly that pipeline over a copy of a run's
+ * workspace in seconds, so a change to any gate is verified against real
+ * manifests and pages before the next run — and a run folder that failed
+ * becomes a permanent regression fixture.
+ */
+import { cp, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { applyAuthoringPostPass, removeSupersededStarterPages } from './authoring-postpass.js';
+import { normalizeCaptureManifest } from './batch-artifacts.js';
+import { DoxloopError } from './errors.js';
+import { pathExists } from './fs.js';
+import { loadProject } from './project.js';
+import { SCREENSHOT_MANIFEST_FILE, adoptCapturedImages, collapseDuplicateCaptures, embedMissingCaptures, validateScreenshotManifest, } from './screenshot-workflow.js';
+import { formatValidation, validateProject } from './validation.js';
+/**
+ * Run the post-authoring pipeline over a copy of `<run-dir>/workspace` using
+ * the run's approved plan. The original run folder is never modified.
+ */
+export async function replayRun(runDirectory, options = {}) {
+    const log = options.log ?? (() => { });
+    const source = resolve(runDirectory);
+    const workspaceSource = join(source, 'workspace');
+    if (!(await pathExists(workspaceSource)))
+        throw new DoxloopError(`${runDirectory} has no workspace folder to replay.`);
+    let plan;
+    try {
+        plan = JSON.parse(await readFile(join(source, 'approved-plan.json'), 'utf8'));
+    }
+    catch {
+        throw new DoxloopError(`${runDirectory} has no readable approved-plan.json; only plan-first runs can be replayed.`);
+    }
+    const workspace = await mkdtemp(join(tmpdir(), 'doxloop-replay-'));
+    await cp(workspaceSource, workspace, { recursive: true });
+    const repairs = [];
+    const say = (line) => { repairs.push(line); log(line); };
+    try {
+        const project = await loadProject(workspace);
+        const before = await validateProject(workspace);
+        log(`Before repairs: ${before.errors} error${before.errors === 1 ? '' : 's'}, ${before.warnings} warning${before.warnings === 1 ? '' : 's'}.`);
+        // 1. Screenshots: the same order as the end of a generation run.
+        const normalized = await normalizeCaptureManifest(workspace, SCREENSHOT_MANIFEST_FILE);
+        for (const step of normalized.verified)
+            say(`manifest: ${step} verified on disk.`);
+        for (const reset of normalized.reset)
+            say(`manifest: ${reset.step} reset to planned (${reset.reason}).`);
+        const adopted = await adoptCapturedImages(workspace, project.generator, plan);
+        if (adopted.length > 0)
+            say(`captures: adopted ${adopted.length} unrecorded image${adopted.length === 1 ? '' : 's'}.`);
+        const dropped = await collapseDuplicateCaptures(workspace, plan);
+        if (dropped.length > 0)
+            say(`captures: quarantined ${dropped.length} duplicate${dropped.length === 1 ? '' : 's'}.`);
+        const placed = await embedMissingCaptures(workspace, plan);
+        if (placed.length > 0)
+            say(`captures: embedded ${placed.length} unplaced image${placed.length === 1 ? '' : 's'}.`);
+        const screenshots = await validateScreenshotManifest(workspace, plan, plan.execution?.screenshots ?? 'auto', { tolerateDefects: true });
+        for (const defect of screenshots.defects)
+            say(`screenshot defect: ${defect}`);
+        // 2. The deterministic repairs the accept path relies on.
+        const report = await applyAuthoringPostPass({ workspace, project, plan, pages: plan.pages, unlinkUnresolved: true, pruneEmptySpaces: true });
+        for (const line of report.repairs)
+            say(`post-pass: ${line}`);
+        for (const line of report.problems)
+            say(`post-pass note: ${line}`);
+        const middle = await validateProject(workspace);
+        const starters = await removeSupersededStarterPages(workspace, middle.issues);
+        if (starters.length > 0) {
+            for (const file of starters)
+                say(`starter: removed ${file}.`);
+            const again = await applyAuthoringPostPass({ workspace, project, plan, pages: plan.pages, unlinkUnresolved: true, pruneEmptySpaces: true });
+            for (const line of again.repairs)
+                say(`post-pass: ${line}`);
+        }
+        // 3. What "Accept all" checks.
+        const after = await validateProject(workspace);
+        log(`After repairs: ${after.errors} error${after.errors === 1 ? '' : 's'}, ${after.warnings} warning${after.warnings === 1 ? '' : 's'}.`);
+        if (after.errors > 0)
+            log(formatValidation({ ...after, issues: after.issues.filter((issue) => issue.severity === 'error') }));
+        return {
+            workspace,
+            before: { errors: before.errors, warnings: before.warnings, issues: before.issues },
+            repairs,
+            screenshotDefects: screenshots.defects,
+            after: { errors: after.errors, warnings: after.warnings, issues: after.issues },
+        };
+    }
+    finally {
+        if (!options.keep)
+            await rm(workspace, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=proposal-replay.js.map

package/dist/quality-claims.d.ts

@@ -0,0 +1,8 @@
+import type { DoxloopProject, QualityCheck, ReaderVerificationMetadata } from './types.js';
+export declare const VERIFICATION_METADATA_FILE: string;
+export declare function readVerificationMetadata(root: string): Promise<ReaderVerificationMetadata | undefined>;
+export declare function reverifyClaims(root: string, project: DoxloopProject, publishMetadata: boolean): Promise<{
+    checks: QualityCheck[];
+    metadata: ReaderVerificationMetadata;
+}>;
+//# sourceMappingURL=quality-claims.d.ts.map

package/dist/quality-claims.js

@@ -0,0 +1,168 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { computeDrift } from './drift.js';
+import { readEvidenceMap } from './evidence.js';
+import { QUALITY_CODES } from './quality-contract.js';
+import { readSyncState } from './sync.js';
+import { pathExists } from './fs.js';
+import { loadOpenApiSource } from './openapi.js';
+import { sourceKind } from './project.js';
+export const VERIFICATION_METADATA_FILE = join('.doxloop', 'verification-metadata.json');
+export async function readVerificationMetadata(root) {
+    const path = join(root, VERIFICATION_METADATA_FILE);
+    if (!(await pathExists(path)))
+        return undefined;
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        return value.schemaVersion === 1 && value.pages && typeof value.pages === 'object' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function reverifyClaims(root, project, publishMetadata) {
+    const [map, drift, sync] = await Promise.all([readEvidenceMap(root), computeDrift(root, project), readSyncState(root)]);
+    const checks = [];
+    const metadata = { schemaVersion: 1, generatedAt: new Date().toISOString(), pages: {} };
+    if (!map) {
+        checks.push({ code: QUALITY_CODES.claimNeedsHuman, category: 'claims', status: 'warning', message: 'No evidence map exists, so reader-facing claims cannot be reverified.' });
+        return { checks, metadata };
+    }
+    const stale = new Set(drift.pages.map((page) => page.page));
+    for (const [page, evidence] of Object.entries(map.pages)) {
+        const pageIsStale = stale.has(page) || drift.status === 'unknown';
+        const hasRevision = evidence.sources.length > 0 && evidence.sources.every((source) => !!evidence.verifiedAt?.[source.source]);
+        const fallback = defaultState(evidence.confidence, pageIsStale, hasRevision);
+        const currentEvidence = await claimEvidenceText(root, project, evidence.sources);
+        const claimStates = (evidence.claims ?? []).map((claim) => {
+            const recorded = evidence.claimVerification?.[claim];
+            return semanticClaimState(claim, currentEvidence, pageIsStale, recorded, fallback);
+        });
+        const state = worstState(claimStates.length > 0 ? claimStates : [fallback]);
+        const revisions = Object.fromEntries(evidence.sources.flatMap((source) => {
+            const revision = evidence.verifiedAt?.[source.source];
+            return revision ? [[source.source, revision]] : [];
+        }));
+        const dates = Object.values(evidence.verifiedOn ?? {}).filter(Boolean).sort();
+        const verifiedOn = dates.at(0);
+        metadata.pages[page] = {
+            state,
+            confidence: evidence.confidence ?? 'needs-human',
+            ...(verifiedOn ? { verifiedOn } : {}),
+            revisions,
+            locale: project.documentation.locale,
+        };
+        for (const [index, claim] of (evidence.claims ?? []).entries())
+            checks.push(checkForState(page, claim, claimStates[index] ?? state));
+        if ((evidence.claims ?? []).length === 0)
+            checks.push(checkForState(page, 'Page evidence has no claim-level entries.', state));
+    }
+    if (publishMetadata) {
+        await mkdir(join(root, '.doxloop'), { recursive: true });
+        await writeFile(join(root, VERIFICATION_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+    }
+    return { checks, metadata };
+}
+async function claimEvidenceText(root, project, entries) {
+    const chunks = [];
+    const byName = new Map(project.sources.map((source) => [source.name, source]));
+    for (const entry of entries) {
+        const source = byName.get(entry.source);
+        if (!source)
+            continue;
+        // The crawled pages of an existing documentation site are what is being
+        // rewritten, not proof: a claim they alone support stays at the page's
+        // recorded confidence instead of being verified against itself.
+        if (sourceKind(source) === 'docs-site')
+            continue;
+        if (sourceKind(source) === 'openapi') {
+            try {
+                const loaded = await loadOpenApiSource(root, source);
+                for (const identifier of entry.operations ?? []) {
+                    const operation = loaded.snapshot.operations[identifier];
+                    if (operation)
+                        chunks.push(identifier, operation.full);
+                    const operationMatch = /^(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s+(\/\S+)$/i.exec(identifier);
+                    if (operationMatch) {
+                        const paths = objectRecord(loaded.document.paths);
+                        const pathItem = objectRecord(paths[operationMatch[2]]);
+                        const raw = pathItem[operationMatch[1].toLowerCase()];
+                        if (raw)
+                            chunks.push(identifier, JSON.stringify(raw));
+                    }
+                    const schema = loaded.snapshot.schemas[identifier.replace(/^schema:/, '')];
+                    if (schema)
+                        chunks.push(identifier, schema);
+                }
+                if (!(entry.operations?.length))
+                    chunks.push(JSON.stringify(loaded.document).slice(0, 250_000));
+            }
+            catch { /* Unavailable evidence remains a needs-human result. */ }
+            continue;
+        }
+        const sourceRoot = resolve(root, source.path);
+        for (const candidate of entry.paths ?? []) {
+            if (/[*?[\]]/.test(candidate))
+                continue;
+            const path = resolve(sourceRoot, candidate);
+            const rel = relative(sourceRoot, path);
+            if (rel === '..' || rel.startsWith('../') || rel.startsWith('..\\') || !(await pathExists(path)))
+                continue;
+            try {
+                chunks.push((await readFile(path, 'utf8')).slice(0, 250_000));
+            }
+            catch { /* Binary or unreadable evidence is ignored. */ }
+        }
+    }
+    return chunks.join('\n').toLowerCase();
+}
+function objectRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function semanticClaimState(claim, evidence, stale, recorded, fallback) {
+    if (recorded === 'contradicted')
+        return 'contradicted';
+    if (!evidence)
+        return stale ? 'needs-human' : (recorded ?? fallback);
+    const facts = extractFacts(claim);
+    if (facts.length === 0)
+        return stale ? 'needs-human' : (recorded ?? fallback);
+    const present = facts.filter((fact) => evidence.includes(fact.value.toLowerCase()));
+    if (present.length === facts.length)
+        return 'verified';
+    const missing = facts.filter((fact) => !present.includes(fact));
+    const categories = new Set(missing.map((fact) => fact.kind));
+    const evidenceFacts = extractFacts(evidence);
+    const comparable = evidenceFacts.filter((fact) => categories.has(fact.kind));
+    if (comparable.length > 0)
+        return 'contradicted';
+    return 'needs-human';
+}
+function extractFacts(value) {
+    const facts = [];
+    const patterns = [
+        ['http-status', /\b[1-5]\d\d\b/g],
+        ['http-operation', /\b(?:GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s+\/[A-Za-z0-9_{}./:-]+/gi],
+        ['cli-option', /--[a-z0-9][a-z0-9-]*/gi],
+        ['environment', /\b[A-Z][A-Z0-9]*_[A-Z0-9_]+\b/g],
+        ['version', /\bv?\d+\.\d+(?:\.\d+)?\b/gi],
+    ];
+    for (const [kind, pattern] of patterns)
+        for (const match of value.matchAll(pattern))
+            facts.push({ kind, value: match[0] });
+    return [...new Map(facts.map((fact) => [`${fact.kind}:${fact.value.toLowerCase()}`, fact])).values()];
+}
+function defaultState(confidence, stale, hasRevision) {
+    if (stale || confidence === 'needs-human' || confidence === undefined)
+        return 'needs-human';
+    return confidence === 'verified' && !hasRevision ? 'inferred' : confidence;
+}
+function worstState(states) {
+    const order = ['verified', 'inferred', 'needs-human', 'contradicted'];
+    return states.reduce((worst, state) => order.indexOf(state) > order.indexOf(worst) ? state : worst, 'verified');
+}
+function checkForState(file, claim, state) {
+    const code = state === 'verified' ? QUALITY_CODES.claimVerified : state === 'inferred' ? QUALITY_CODES.claimInferred : state === 'contradicted' ? QUALITY_CODES.claimContradicted : QUALITY_CODES.claimNeedsHuman;
+    return { code, category: 'claims', status: state === 'verified' ? 'pass' : state === 'contradicted' ? 'fail' : 'warning', message: `${state}: ${claim}`, file };
+}
+//# sourceMappingURL=quality-claims.js.map

package/dist/quality-config.d.ts

@@ -0,0 +1,5 @@
+import type { QualityConfig } from './types.js';
+export declare const QUALITY_CONFIG_FILE: string;
+export declare const DEFAULT_QUALITY_CONFIG: QualityConfig;
+export declare function loadQualityConfig(root: string): Promise<QualityConfig>;
+//# sourceMappingURL=quality-config.d.ts.map

package/dist/quality-config.js

@@ -0,0 +1,84 @@
+import { join } from 'node:path';
+import { pathExists, readJson } from './fs.js';
+import { DoxloopError } from './errors.js';
+export const QUALITY_CONFIG_FILE = join('.doxloop', 'quality.json');
+export const DEFAULT_QUALITY_CONFIG = {
+    schemaVersion: 1,
+    links: { mode: 'online', allowHosts: [], ignore: [], timeoutMs: 8_000, retries: 2, cacheHours: 24 },
+    examples: { enabled: false },
+    rendered: {
+        enabled: false,
+        routes: ['/'],
+        viewports: [
+            { name: 'desktop', width: 1440, height: 900 },
+            { name: 'mobile', width: 390, height: 844 },
+        ],
+        themes: ['light', 'dark'],
+        maximumDiffRatio: 0.001,
+    },
+    lint: { maximumTitleLength: 72, maximumNavigationLabelLength: 42 },
+    readerVerification: { enabled: false },
+    suppressions: [],
+    ratchet: { enabled: false, baselineFile: '.doxloop/quality-baseline.json' },
+};
+export async function loadQualityConfig(root) {
+    const path = join(root, QUALITY_CONFIG_FILE);
+    if (!(await pathExists(path)))
+        return structuredClone(DEFAULT_QUALITY_CONFIG);
+    const input = await readJson(path);
+    if (!isQualityConfig(input))
+        throw new DoxloopError(`${QUALITY_CONFIG_FILE} has an unsupported format.`);
+    return {
+        schemaVersion: 1,
+        links: { ...DEFAULT_QUALITY_CONFIG.links, ...input.links },
+        examples: { ...DEFAULT_QUALITY_CONFIG.examples, ...input.examples },
+        rendered: { ...DEFAULT_QUALITY_CONFIG.rendered, ...input.rendered },
+        lint: { ...DEFAULT_QUALITY_CONFIG.lint, ...input.lint },
+        readerVerification: { ...DEFAULT_QUALITY_CONFIG.readerVerification, ...input.readerVerification },
+        suppressions: input.suppressions ?? [],
+        ratchet: { ...DEFAULT_QUALITY_CONFIG.ratchet, ...input.ratchet },
+    };
+}
+function isQualityConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const config = value;
+    if (config.schemaVersion !== 1)
+        return false;
+    if (config.links) {
+        if (!object(config.links))
+            return false;
+        if (config.links.mode !== undefined && !['online', 'offline'].includes(config.links.mode))
+            return false;
+        if (!textList(config.links.allowHosts) || !textList(config.links.ignore))
+            return false;
+        if (!bounded(config.links.timeoutMs, 500, 60_000) || !bounded(config.links.retries, 0, 5) || !bounded(config.links.cacheHours, 1, 720))
+            return false;
+    }
+    if (config.examples && (!object(config.examples) || !optionalBoolean(config.examples.enabled)))
+        return false;
+    if (config.readerVerification && (!object(config.readerVerification) || !optionalBoolean(config.readerVerification.enabled)))
+        return false;
+    if (config.suppressions !== undefined && (!Array.isArray(config.suppressions) || !config.suppressions.every((item) => object(item) && typeof item.code === 'string' && item.code.trim() !== '' && typeof item.reason === 'string' && item.reason.trim() !== '' && (item.file === undefined || typeof item.file === 'string') && (item.expires === undefined || typeof item.expires === 'string' && !Number.isNaN(Date.parse(item.expires))))))
+        return false;
+    if (config.ratchet && (!object(config.ratchet) || !optionalBoolean(config.ratchet.enabled) || (config.ratchet.baselineFile !== undefined && typeof config.ratchet.baselineFile !== 'string')))
+        return false;
+    if (config.rendered) {
+        if (!object(config.rendered) || !optionalBoolean(config.rendered.enabled) || !textList(config.rendered.routes))
+            return false;
+        if (config.rendered.viewports !== undefined && (!Array.isArray(config.rendered.viewports) || !config.rendered.viewports.every((item) => object(item) && typeof item.name === 'string' && bounded(item.width, 320, 3840) && bounded(item.height, 320, 2160))))
+            return false;
+        if (config.rendered.themes !== undefined && (!Array.isArray(config.rendered.themes) || !config.rendered.themes.every((item) => item === 'light' || item === 'dark')))
+            return false;
+        if (config.rendered.maximumDiffRatio !== undefined && (typeof config.rendered.maximumDiffRatio !== 'number' || config.rendered.maximumDiffRatio < 0 || config.rendered.maximumDiffRatio > 1))
+            return false;
+    }
+    if (config.lint && (!object(config.lint) || !bounded(config.lint.maximumTitleLength, 20, 200) || !bounded(config.lint.maximumNavigationLabelLength, 10, 120)))
+        return false;
+    return true;
+}
+function object(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
+function textList(value) { return value === undefined || (Array.isArray(value) && value.every((item) => typeof item === 'string' && item.trim() !== '')); }
+function bounded(value, minimum, maximum) { return value === undefined || (Number.isInteger(value) && Number(value) >= minimum && Number(value) <= maximum); }
+function optionalBoolean(value) { return value === undefined || typeof value === 'boolean'; }
+//# sourceMappingURL=quality-config.js.map

package/dist/quality-contract.d.ts

@@ -0,0 +1,37 @@
+import type { QualityCheckCategory } from './types.js';
+export declare const QUALITY_CONTRACT_VERSION: "1.0.0";
+/**
+ * Public issue codes are append-only within contract v1. Text may change, but
+ * automation can safely baseline, suppress, and ratchet these identifiers.
+ */
+export declare const QUALITY_CODES: {
+    readonly validation: "quality.validation";
+    readonly buildPassed: "quality.build.passed";
+    readonly buildFailed: "quality.build.failed";
+    readonly linkOk: "quality.link.ok";
+    readonly linkBroken: "quality.link.broken";
+    readonly linkUnavailable: "quality.link.unavailable";
+    readonly linkSkipped: "quality.link.skipped";
+    readonly examplePassed: "quality.example.passed";
+    readonly exampleFailed: "quality.example.failed";
+    readonly exampleSourceVerified: "quality.example.source-verified";
+    readonly schemaPassed: "quality.schema.passed";
+    readonly schemaIssue: "quality.schema.issue";
+    readonly accessibilityPassed: "quality.accessibility.passed";
+    readonly accessibilityIssue: "quality.accessibility.issue";
+    readonly accessibilityManual: "quality.accessibility.manual-review";
+    readonly visualMatched: "quality.visual.matched";
+    readonly visualChanged: "quality.visual.changed";
+    readonly visualCreated: "quality.visual.created";
+    readonly visualSkipped: "quality.visual.skipped";
+    readonly lintIssue: "quality.lint.issue";
+    readonly lintPassed: "quality.lint.passed";
+    readonly claimVerified: "quality.claim.verified";
+    readonly claimInferred: "quality.claim.inferred";
+    readonly claimContradicted: "quality.claim.contradicted";
+    readonly claimNeedsHuman: "quality.claim.needs-human";
+    readonly ratchetBaselineMissing: "quality.ratchet.baseline-missing";
+    readonly ratchetBaselineInvalid: "quality.ratchet.baseline-invalid";
+};
+export declare const QUALITY_CATEGORIES: readonly QualityCheckCategory[];
+//# sourceMappingURL=quality-contract.d.ts.map

package/dist/quality-contract.js

@@ -0,0 +1,46 @@
+export const QUALITY_CONTRACT_VERSION = '1.0.0';
+/**
+ * Public issue codes are append-only within contract v1. Text may change, but
+ * automation can safely baseline, suppress, and ratchet these identifiers.
+ */
+export const QUALITY_CODES = {
+    validation: 'quality.validation',
+    buildPassed: 'quality.build.passed',
+    buildFailed: 'quality.build.failed',
+    linkOk: 'quality.link.ok',
+    linkBroken: 'quality.link.broken',
+    linkUnavailable: 'quality.link.unavailable',
+    linkSkipped: 'quality.link.skipped',
+    examplePassed: 'quality.example.passed',
+    exampleFailed: 'quality.example.failed',
+    exampleSourceVerified: 'quality.example.source-verified',
+    schemaPassed: 'quality.schema.passed',
+    schemaIssue: 'quality.schema.issue',
+    accessibilityPassed: 'quality.accessibility.passed',
+    accessibilityIssue: 'quality.accessibility.issue',
+    accessibilityManual: 'quality.accessibility.manual-review',
+    visualMatched: 'quality.visual.matched',
+    visualChanged: 'quality.visual.changed',
+    visualCreated: 'quality.visual.created',
+    visualSkipped: 'quality.visual.skipped',
+    lintIssue: 'quality.lint.issue',
+    lintPassed: 'quality.lint.passed',
+    claimVerified: 'quality.claim.verified',
+    claimInferred: 'quality.claim.inferred',
+    claimContradicted: 'quality.claim.contradicted',
+    claimNeedsHuman: 'quality.claim.needs-human',
+    ratchetBaselineMissing: 'quality.ratchet.baseline-missing',
+    ratchetBaselineInvalid: 'quality.ratchet.baseline-invalid',
+};
+export const QUALITY_CATEGORIES = [
+    'validation',
+    'build',
+    'links',
+    'examples',
+    'schemas',
+    'accessibility',
+    'visual',
+    'lint',
+    'claims',
+];
+//# sourceMappingURL=quality-contract.js.map

package/dist/quality-examples.d.ts

@@ -0,0 +1,4 @@
+import type { QualityCheck } from './types.js';
+export declare const EXAMPLES_FILE: string;
+export declare function verifyExamples(root: string, enabled: boolean): Promise<QualityCheck[]>;
+//# sourceMappingURL=quality-examples.d.ts.map