@x12i/made-easy 0.0.0-stage → 0.1.0

package/dist/validate.js

@@ -0,0 +1,986 @@
+import { BUNDLE_FILES, HUMAN_ROLES, ruleSeverity, summarizeDiagnostics, sortDiagnostics, dedupeDiagnostics, } from './contracts/index.js';
+import { computeUsage, parseRef } from './analysis.js';
+import { PLACEHOLDER_PATTERN, extractInlineRefs } from './markdown-doc.js';
+import { allBlocks, blocksOf, entriesOf, fileDigest } from './model.js';
+import { isPlainObject, sha256Digest, canonicalJson } from './util.js';
+import { pointerFromPath } from './yamlfile.js';
+import { resolveRelative } from './source.js';
+export const SUPPORTED_THEMES = ['book@1.0.0'];
+/* --------------------------------- helpers -------------------------------- */
+export function isFilled(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return value.trim() !== '';
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (isPlainObject(value))
+        return Object.keys(value).length > 0;
+    return true;
+}
+/** Return pointers (relative to `root`) of locations that fail the dotted field path. */
+export function failingPointers(root, path, base = '') {
+    const walk = (node, segs, ptr) => {
+        if (!segs.length)
+            return isFilled(node) ? [] : [ptr];
+        const [seg, ...rest] = segs;
+        const isList = seg.endsWith('[]');
+        const key = isList ? seg.slice(0, -2) : seg;
+        const child = isPlainObject(node) ? node[key] : undefined;
+        const childPtr = `${ptr}/${key}`;
+        if (isList) {
+            if (!Array.isArray(child) || child.length === 0)
+                return [childPtr];
+            return child.flatMap((el, i) => walk(el, rest, `${childPtr}/${i}`));
+        }
+        return walk(child, rest, childPtr);
+    };
+    return walk(root, path.split('.'), base);
+}
+const SECRET_PATTERNS = [
+    ['private key', /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+    ['AWS access key ID', /\bAKIA[0-9A-Z]{16}\b/],
+    ['GitHub token', /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}\b|\bgithub_pat_[A-Za-z0-9_]{40,}\b/],
+    ['npm token', /\bnpm_[A-Za-z0-9]{30,}\b/],
+    ['API key', /\bsk-[A-Za-z0-9_-]{24,}\b/],
+    ['Slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/],
+    ['npm auth line', /_authToken\s*=\s*(?!\$\{)[^\s]{8,}/],
+    ['bearer token', /\bBearer\s+[A-Za-z0-9._~+/=-]{24,}/],
+];
+const TEXT_FILE = /\.(md|ya?ml|json|txt|csv|js|mjs|cjs|ts|sh|ps1|toml|env|ini|cfg|html?|css)$/i;
+const MEDIA_BY_EXT = {
+    png: ['image/png'],
+    jpg: ['image/jpeg'],
+    jpeg: ['image/jpeg'],
+    gif: ['image/gif'],
+    webp: ['image/webp'],
+    svg: ['image/svg+xml'],
+    pdf: ['application/pdf'],
+    csv: ['text/csv'],
+    json: ['application/json'],
+    txt: ['text/plain'],
+    md: ['text/markdown'],
+};
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/** Digest of an executable example: its definition plus every fixture file. */
+export function exampleDigest(model, props) {
+    const fixture = typeof props.fixture === 'string' ? props.fixture.replace(/\/$/, '') : '';
+    const fixtureFiles = fixture
+        ? model.files
+            .paths()
+            .filter((p) => p.startsWith(`${fixture}/`))
+            .map((p) => ({ path: p, digest: fileDigest(p, model.files.bytes(p)) }))
+        : [];
+    return sha256Digest(canonicalJson({
+        setup: props.setup ?? [],
+        run: props.run ?? [],
+        expected: props.expected ?? '',
+        runtime: props.runtime ?? '',
+        files: fixtureFiles,
+    }));
+}
+export function exampleBlocks(model) {
+    return allBlocks(model).filter(({ block }) => block.type === 'example' && block.props.executable !== false);
+}
+/* --------------------------------- validate ------------------------------- */
+export function validateModel(model, options) {
+    const { mode } = options;
+    const out = [...model.diagnostics];
+    const recipe = model.recipe;
+    const severityOf = (rule) => {
+        if (!recipe)
+            return mode === 'release' ? 'error' : 'warning';
+        let s = ruleSeverity(recipe, mode, rule);
+        // An explicit audience decides privacy findings; with none given the mode's default applies.
+        if (rule === 'privateReferences' && options.audience === 'public')
+            s = 'error';
+        else if (rule === 'privateReferences' && options.audience === 'private')
+            s = 'info';
+        return s;
+    };
+    const emit = (rule, d) => {
+        const s = severityOf(rule);
+        if (s !== 'off')
+            out.push({ ...d, severity: s });
+    };
+    const err = (d) => out.push({ ...d, severity: 'error' });
+    const lineIn = (file, pointer) => model.lines[file]?.(pointer);
+    const guide = model.guide;
+    /* ------------------------------ pins & profile ----------------------------- */
+    if (guide) {
+        if (!SUPPORTED_THEMES.includes(`${guide.theme.id}@${guide.theme.version}`)) {
+            err({
+                code: 'THEME_UNSUPPORTED',
+                path: BUNDLE_FILES.guide,
+                line: lineIn(BUNDLE_FILES.guide, '/theme'),
+                pointer: '/theme',
+                message: `Theme ${guide.theme.id}@${guide.theme.version} is not available. Available: ${SUPPORTED_THEMES.join(', ')}.`,
+            });
+        }
+        if (recipe && recipe.profile !== guide.subject.type) {
+            err({
+                code: 'SUBJECT_RECIPE_MISMATCH',
+                path: BUNDLE_FILES.guide,
+                line: lineIn(BUNDLE_FILES.guide, '/subject/type'),
+                pointer: '/subject/type',
+                message: `Subject type "${guide.subject.type}" does not match recipe ${recipe.id} (profile "${recipe.profile}").`,
+            });
+        }
+    }
+    /* --------------------------------- roles ---------------------------------- */
+    if (guide && recipe) {
+        const human = entriesOf(model, 'human');
+        let lastIndex = -1;
+        for (const def of recipe.roleDetails) {
+            const matches = human.filter((e) => e.role === def.role);
+            if (!matches.length) {
+                emit('missingBlocks', {
+                    code: 'ROLE_MISSING',
+                    path: BUNDLE_FILES.guide,
+                    line: lineIn(BUNDLE_FILES.guide, '/tracks/human'),
+                    pointer: '/tracks/human',
+                    message: `The human track needs a "${def.role}" entry (${def.title}).`,
+                });
+                continue;
+            }
+            if (matches.length > 1) {
+                err({
+                    code: 'ROLE_DUPLICATE',
+                    path: BUNDLE_FILES.guide,
+                    line: lineIn(BUNDLE_FILES.guide, matches[1].pointer),
+                    pointer: matches[1].pointer,
+                    message: `The "${def.role}" role appears ${matches.length} times; each required role appears once.`,
+                });
+            }
+            const idx = human.indexOf(matches[0]);
+            if (idx < lastIndex) {
+                err({
+                    code: 'ROLE_ORDER',
+                    path: BUNDLE_FILES.guide,
+                    line: lineIn(BUNDLE_FILES.guide, matches[0].pointer),
+                    pointer: matches[0].pointer,
+                    message: `Role "${def.role}" is out of order. Required order: ${HUMAN_ROLES.join(' → ')}.`,
+                });
+            }
+            lastIndex = Math.max(lastIndex, idx);
+        }
+        const lastRequired = Math.max(-1, ...human.map((e, i) => (e.role === 'appendix' ? -1 : i)));
+        human.forEach((e, i) => {
+            if (e.role === 'appendix' && i < lastRequired) {
+                err({
+                    code: 'ROLE_ORDER',
+                    path: BUNDLE_FILES.guide,
+                    line: lineIn(BUNDLE_FILES.guide, e.pointer),
+                    pointer: e.pointer,
+                    message: 'Appendix entries come after the six required roles.',
+                });
+            }
+        });
+        const operator = entriesOf(model, 'operator');
+        for (const role of recipe.profileDefinition.requiredOperatorRoles) {
+            if (!operator.some((e) => e.role === role)) {
+                emit('missingBlocks', {
+                    code: 'ROLE_MISSING',
+                    path: BUNDLE_FILES.guide,
+                    line: lineIn(BUNDLE_FILES.guide, '/tracks/operator'),
+                    pointer: '/tracks/operator',
+                    message: `The operator track needs a "${role}" entry for the ${recipe.profile} profile.`,
+                });
+            }
+        }
+    }
+    /* ----------------------------- recipe requirements -------------------------- */
+    if (recipe) {
+        for (const def of recipe.roleDetails) {
+            const entry = entriesOf(model, 'human').find((e) => e.role === def.role);
+            if (!entry)
+                continue;
+            const blocks = blocksOf(entry);
+            for (const req of def.requirements)
+                checkRequirement(req, def.role, entry, blocks, emit);
+            if (entry.words < def.minWords) {
+                emit('shortContent', {
+                    code: 'CONTENT_TOO_SHORT',
+                    path: entry.path,
+                    line: 1,
+                    message: `The "${def.role}" section has ${entry.words} words of prose; the ${recipe.preset} preset needs at least ${def.minWords}.`,
+                });
+            }
+        }
+    }
+    /* --------------------------------- data files ------------------------------ */
+    const brief = model.brief;
+    const checks = model.checks;
+    const sources = model.sources;
+    const checkIds = new Set((checks?.checks ?? []).map((c) => c.id));
+    const resultIds = new Set((checks?.results ?? []).map((r) => r.id));
+    const sourceIds = new Set((sources?.sources ?? []).map((s) => s.id));
+    const claimIds = new Set((sources?.claims ?? []).map((c) => c.id));
+    const assetIds = new Set((model.assets?.assets ?? []).map((a) => a.id));
+    const pauseIds = new Set((brief?.pauseRules ?? []).map((p) => p.id));
+    const inputIds = new Set((brief?.inputs ?? []).map((i) => i.id));
+    const entryById = new Map(model.entries.map((e) => [e.id, e]));
+    const blockById = new Map(allBlocks(model).map((b) => [b.block.id, b]));
+    const dupes = (file, base, ids, what) => {
+        const seen = new Set();
+        ids.forEach((id, i) => {
+            if (!id)
+                return;
+            if (seen.has(id)) {
+                err({
+                    code: 'ID_DUPLICATE',
+                    path: file,
+                    line: lineIn(file, `${base}/${i}/id`),
+                    pointer: `${base}/${i}/id`,
+                    message: `Duplicate ${what} id "${id}".`,
+                });
+            }
+            seen.add(id);
+        });
+    };
+    dupes(BUNDLE_FILES.brief, '/inputs', (brief?.inputs ?? []).map((x) => x.id), 'input');
+    dupes(BUNDLE_FILES.brief, '/pauseRules', (brief?.pauseRules ?? []).map((x) => x.id), 'pause rule');
+    dupes(BUNDLE_FILES.brief, '/reportBack', (brief?.reportBack ?? []).map((x) => x.id), 'report-back field');
+    dupes(BUNDLE_FILES.checks, '/checks', (checks?.checks ?? []).map((x) => x.id), 'check');
+    dupes(BUNDLE_FILES.checks, '/results', (checks?.results ?? []).map((x) => x.id), 'result');
+    dupes(BUNDLE_FILES.sources, '/sources', (sources?.sources ?? []).map((x) => x.id), 'source');
+    dupes(BUNDLE_FILES.sources, '/claims', (sources?.claims ?? []).map((x) => x.id), 'claim');
+    dupes(BUNDLE_FILES.assets, '/assets', (model.assets?.assets ?? []).map((x) => x.id), 'asset');
+    const unresolved = (file, pointer, what, id) => err({
+        code: 'REF_UNRESOLVED',
+        path: file,
+        line: lineIn(file, pointer),
+        pointer,
+        message: `${what} "${id}" does not exist.`,
+    });
+    // brief references
+    (brief?.acceptanceChecks ?? []).forEach((id, i) => {
+        if (!checkIds.has(id))
+            unresolved(BUNDLE_FILES.brief, `/acceptanceChecks/${i}`, 'Acceptance check', id);
+    });
+    (brief?.operatorReference?.entries ?? []).forEach((pin, i) => {
+        const entry = entryById.get(pin.id);
+        const base = `/operatorReference/entries/${i}`;
+        if (!entry || entry.track !== 'operator') {
+            emit('stalePins', {
+                code: 'PIN_UNRESOLVED',
+                path: BUNDLE_FILES.brief,
+                line: lineIn(BUNDLE_FILES.brief, base),
+                pointer: base,
+                message: `Pinned operator-reference entry "${pin.id}" does not exist.`,
+            });
+            return;
+        }
+        if (!pin.digest) {
+            emit('stalePins', {
+                code: 'PIN_MISSING',
+                path: BUNDLE_FILES.brief,
+                line: lineIn(BUNDLE_FILES.brief, base),
+                pointer: base,
+                message: `Entry "${pin.id}" is listed but has no digest. Run "made-easy pin" to record ${entry.digest}.`,
+            });
+        }
+        else if (pin.digest !== entry.digest) {
+            emit('stalePins', {
+                code: 'PIN_STALE',
+                path: BUNDLE_FILES.brief,
+                line: lineIn(BUNDLE_FILES.brief, `${base}/digest`),
+                pointer: `${base}/digest`,
+                message: `Operator-reference entry "${pin.id}" (${entry.path}) changed since it was pinned. Review it, then run "made-easy pin".`,
+                hint: `pinned ${pin.digest}; current ${entry.digest}`,
+            });
+        }
+    });
+    // results and evidence
+    const refExists = (ref) => {
+        const p = parseRef(ref);
+        if (!p)
+            return false;
+        switch (p.kind) {
+            case 'check': return checkIds.has(p.id);
+            case 'claim': return claimIds.has(p.id);
+            case 'source': return sourceIds.has(p.id);
+            case 'result': return resultIds.has(p.id);
+            case 'pause': return pauseIds.has(p.id);
+            case 'asset': return assetIds.has(p.id);
+            case 'input': return inputIds.has(p.id);
+            case 'block': return blockById.has(p.id);
+            case 'entry': {
+                const e = entryById.get(p.id);
+                return Boolean(e) && (!p.anchor || e.headings.some((h) => h.anchor === p.anchor));
+            }
+        }
+    };
+    (checks?.results ?? []).forEach((r, ri) => {
+        (r.checks ?? []).forEach((rc, ci) => {
+            if (!checkIds.has(rc.check))
+                unresolved(BUNDLE_FILES.checks, `/results/${ri}/checks/${ci}/check`, 'Check', rc.check);
+            (rc.evidence ?? []).forEach((ref, ei) => {
+                if (!refExists(ref))
+                    unresolved(BUNDLE_FILES.checks, `/results/${ri}/checks/${ci}/evidence/${ei}`, 'Evidence reference', ref);
+            });
+        });
+        // same checks, consistent verdict
+        const accept = brief?.acceptanceChecks ?? [];
+        const recorded = (r.checks ?? []).map((c) => c.check);
+        if (brief && (accept.some((c) => !recorded.includes(c)) || recorded.some((c) => !accept.includes(c)))) {
+            err({
+                code: 'RESULT_CHECK_MISMATCH',
+                path: BUNDLE_FILES.checks,
+                line: lineIn(BUNDLE_FILES.checks, `/results/${ri}/checks`),
+                pointer: `/results/${ri}/checks`,
+                message: `Result "${r.id}" must be recorded against exactly the acceptance checks in brief.yaml (${accept.join(', ') || 'none'}).`,
+            });
+        }
+        const outcomes = (r.checks ?? []).map((c) => c.outcome);
+        const bad = outcomes.some((o) => o === 'fail' || o === 'contradictory');
+        const missing = outcomes.some((o) => o === 'missing');
+        const expected = bad ? 'invalid' : missing ? 'partial' : 'usable';
+        if (outcomes.length && r.verdict !== expected) {
+            err({
+                code: 'RESULT_VERDICT_INCONSISTENT',
+                path: BUNDLE_FILES.checks,
+                line: lineIn(BUNDLE_FILES.checks, `/results/${ri}/verdict`),
+                pointer: `/results/${ri}/verdict`,
+                message: `Result "${r.id}" is marked ${r.verdict} but its check outcomes imply ${expected} (fail or contradictory → invalid; missing → partial; all pass → usable).`,
+            });
+        }
+        if (r.kind === 'usable' && r.verdict !== 'usable') {
+            err({
+                code: 'RESULT_VERDICT_INCONSISTENT',
+                path: BUNDLE_FILES.checks,
+                line: lineIn(BUNDLE_FILES.checks, `/results/${ri}/kind`),
+                pointer: `/results/${ri}/kind`,
+                message: `Result "${r.id}" is a usable example but its verdict is ${r.verdict}.`,
+            });
+        }
+        if (r.kind === 'flawed' && r.verdict === 'usable') {
+            err({
+                code: 'RESULT_VERDICT_INCONSISTENT',
+                path: BUNDLE_FILES.checks,
+                line: lineIn(BUNDLE_FILES.checks, `/results/${ri}/kind`),
+                pointer: `/results/${ri}/kind`,
+                message: `Result "${r.id}" is a flawed example but its verdict is usable.`,
+            });
+        }
+    });
+    (sources?.claims ?? []).forEach((c, i) => {
+        (c.evidence ?? []).forEach((e, ei) => {
+            if (!sourceIds.has(e.source))
+                unresolved(BUNDLE_FILES.sources, `/claims/${i}/evidence/${ei}/source`, 'Source', e.source);
+        });
+        if (c.status === 'unresolved') {
+            emit('unresolvedClaims', {
+                code: 'CLAIM_UNRESOLVED',
+                path: BUNDLE_FILES.sources,
+                line: lineIn(BUNDLE_FILES.sources, `/claims/${i}`),
+                pointer: `/claims/${i}`,
+                message: `Claim "${c.id}" is recorded as unresolved: ${c.text}`,
+            });
+        }
+        else if (!(c.evidence ?? []).length) {
+            emit('unresolvedClaims', {
+                code: 'CLAIM_NO_EVIDENCE',
+                path: BUNDLE_FILES.sources,
+                line: lineIn(BUNDLE_FILES.sources, `/claims/${i}`),
+                pointer: `/claims/${i}`,
+                message: `Claim "${c.id}" is marked supported but cites no evidence.`,
+            });
+        }
+    });
+    (sources?.checkEvidence ?? []).forEach((ce, i) => {
+        if (!checkIds.has(ce.check))
+            unresolved(BUNDLE_FILES.sources, `/checkEvidence/${i}/check`, 'Check', ce.check);
+        (ce.evidence ?? []).forEach((e, ei) => {
+            if (!sourceIds.has(e.source))
+                unresolved(BUNDLE_FILES.sources, `/checkEvidence/${i}/evidence/${ei}/source`, 'Source', e.source);
+        });
+    });
+    for (const id of brief?.acceptanceChecks ?? []) {
+        const mapped = (sources?.checkEvidence ?? []).find((c) => c.check === id && (c.evidence ?? []).length);
+        if (!mapped && checkIds.has(id)) {
+            emit('incompleteData', {
+                code: 'CHECK_NOT_COVERED',
+                path: BUNDLE_FILES.sources,
+                line: lineIn(BUNDLE_FILES.sources, '/checkEvidence') ?? 1,
+                pointer: '/checkEvidence',
+                message: `Acceptance check "${id}" is not mapped to evidence in sources.yaml (checkEvidence).`,
+            });
+        }
+    }
+    (sources?.sources ?? []).forEach((s, i) => {
+        if (s.synthetic) {
+            out.push({
+                code: 'SOURCE_SYNTHETIC',
+                severity: 'info',
+                path: BUNDLE_FILES.sources,
+                line: lineIn(BUNDLE_FILES.sources, `/sources/${i}`),
+                pointer: `/sources/${i}`,
+                message: `Source "${s.id}" is synthetic evidence and is labelled as such in every output.`,
+            });
+        }
+    });
+    /* ---------------------------- brief / check completeness ------------------- */
+    if (recipe && brief) {
+        for (const path of recipe.data.brief) {
+            for (const ptr of failingPointers(brief, path)) {
+                emit('incompleteData', {
+                    code: 'FIELD_REQUIRED_MISSING',
+                    path: BUNDLE_FILES.brief,
+                    line: lineIn(BUNDLE_FILES.brief, ptr),
+                    pointer: ptr,
+                    message: `brief.yaml requires "${path}".`,
+                });
+            }
+        }
+        (brief.inputs ?? []).forEach((input, i) => {
+            for (const f of recipe.data.input) {
+                for (const ptr of failingPointers(input, f, `/inputs/${i}`)) {
+                    emit('incompleteData', {
+                        code: 'FIELD_REQUIRED_MISSING',
+                        path: BUNDLE_FILES.brief,
+                        line: lineIn(BUNDLE_FILES.brief, ptr),
+                        pointer: ptr,
+                        message: `Input "${input.id}" needs "${f}".`,
+                    });
+                }
+            }
+        });
+        (brief.pauseRules ?? []).forEach((rule, i) => {
+            for (const f of recipe.data.pauseRule) {
+                for (const ptr of failingPointers(rule, f, `/pauseRules/${i}`)) {
+                    emit('incompleteData', {
+                        code: 'FIELD_REQUIRED_MISSING',
+                        path: BUNDLE_FILES.brief,
+                        line: lineIn(BUNDLE_FILES.brief, ptr),
+                        pointer: ptr,
+                        message: `Pause rule "${rule.id}" needs "${f}" (trigger, decision owner, work that may continue, resume condition).`,
+                    });
+                }
+            }
+        });
+        (brief.reportBack ?? []).forEach((rb, i) => {
+            for (const f of recipe.data.reportBackField) {
+                for (const ptr of failingPointers(rb, f, `/reportBack/${i}`)) {
+                    emit('incompleteData', {
+                        code: 'FIELD_REQUIRED_MISSING',
+                        path: BUNDLE_FILES.brief,
+                        line: lineIn(BUNDLE_FILES.brief, ptr),
+                        pointer: ptr,
+                        message: `Report-back field "${rb.id}" needs "${f}".`,
+                    });
+                }
+            }
+        });
+    }
+    if (recipe && checks) {
+        if (!(checks.checks ?? []).length) {
+            emit('incompleteData', {
+                code: 'FIELD_REQUIRED_MISSING',
+                path: BUNDLE_FILES.checks,
+                line: 1,
+                message: 'checks.yaml needs at least one acceptance check.',
+            });
+        }
+        (checks.checks ?? []).forEach((c, i) => {
+            for (const f of recipe.data.check) {
+                for (const ptr of failingPointers(c, f, `/checks/${i}`)) {
+                    emit('incompleteData', {
+                        code: 'FIELD_REQUIRED_MISSING',
+                        path: BUNDLE_FILES.checks,
+                        line: lineIn(BUNDLE_FILES.checks, ptr),
+                        pointer: ptr,
+                        message: `Check "${c.id}" needs "${f}".`,
+                    });
+                }
+            }
+        });
+        for (const kind of ['usable', 'flawed']) {
+            if (!(checks.results ?? []).some((r) => r.kind === kind)) {
+                emit('incompleteData', {
+                    code: 'FIELD_REQUIRED_MISSING',
+                    path: BUNDLE_FILES.checks,
+                    line: lineIn(BUNDLE_FILES.checks, '/results') ?? 1,
+                    pointer: '/results',
+                    message: `checks.yaml needs a worked ${kind} result recorded against the acceptance checks.`,
+                });
+            }
+        }
+        (checks.results ?? []).forEach((r, i) => {
+            for (const f of recipe.data.resultPresent) {
+                if (r[f] === undefined) {
+                    emit('incompleteData', {
+                        code: 'FIELD_REQUIRED_MISSING',
+                        path: BUNDLE_FILES.checks,
+                        line: lineIn(BUNDLE_FILES.checks, `/results/${i}`),
+                        pointer: `/results/${i}`,
+                        message: `Result "${r.id}" must state "${f}" (completed actions, observations, gaps and next steps are kept distinct).`,
+                    });
+                }
+            }
+        });
+    }
+    /* ----------------------------------- blocks -------------------------------- */
+    for (const { entry, block } of allBlocks(model)) {
+        const p = block.props;
+        const at = (pointer) => block.lineOf(`/props${pointer}`) ?? block.line;
+        const bad = (pointer, what, id) => err({
+            code: 'REF_UNRESOLVED',
+            path: entry.path,
+            line: at(pointer),
+            blockId: block.id,
+            pointer: `/props${pointer}`,
+            message: `${what} "${id}" does not exist.`,
+        });
+        const checkRefList = (key, set, what) => {
+            const list = p[key];
+            if (Array.isArray(list))
+                list.forEach((id, i) => typeof id === 'string' && !set.has(id) && bad(`/${key}/${i}`, what, id));
+        };
+        switch (block.type) {
+            case 'decision': {
+                const evidenceRefs = (list, base) => {
+                    if (Array.isArray(list))
+                        list.forEach((r, i) => typeof r === 'string' && !refExists(r) && bad(`${base}/${i}`, 'Evidence reference', r));
+                };
+                evidenceRefs(p.evidence, '/evidence');
+                if (Array.isArray(p.options))
+                    p.options.forEach((o, i) => evidenceRefs(o?.evidence, `/options/${i}/evidence`));
+                break;
+            }
+            case 'pause':
+                if (typeof p.rule === 'string' && !pauseIds.has(p.rule))
+                    bad('/rule', 'Pause rule', p.rule);
+                break;
+            case 'human-action':
+                if (typeof p.pause === 'string' && !pauseIds.has(p.pause))
+                    bad('/pause', 'Pause rule', p.pause);
+                break;
+            case 'evidence-comparison':
+                if (typeof p.usable === 'string' && !resultIds.has(p.usable))
+                    bad('/usable', 'Result', p.usable);
+                if (typeof p.flawed === 'string' && !resultIds.has(p.flawed))
+                    bad('/flawed', 'Result', p.flawed);
+                checkRefList('decisiveChecks', checkIds, 'Check');
+                break;
+            case 'review-checklist':
+                checkRefList('checks', checkIds, 'Check');
+                break;
+            case 'figure':
+                if (typeof p.asset === 'string' && !assetIds.has(p.asset))
+                    bad('/asset', 'Asset', p.asset);
+                break;
+            case 'job-map': {
+                const stageIds = new Set((p.stages ?? []).map((s) => s.id));
+                (p.failurePoints ?? []).forEach((f, i) => {
+                    if (f.stage && !stageIds.has(f.stage))
+                        bad(`/failurePoints/${i}/stage`, 'Stage', f.stage);
+                });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    // pause coverage in the ownership section
+    const ownership = entriesOf(model, 'human').find((e) => e.role === 'ownership');
+    if (ownership) {
+        const covered = new Set(blocksOf(ownership)
+            .filter((b) => b.type === 'pause')
+            .map((b) => b.props.rule));
+        (brief?.pauseRules ?? []).forEach((r, i) => {
+            if (!covered.has(r.id)) {
+                emit('missingBlocks', {
+                    code: 'PAUSE_NOT_COVERED',
+                    path: BUNDLE_FILES.brief,
+                    line: lineIn(BUNDLE_FILES.brief, `/pauseRules/${i}`),
+                    pointer: `/pauseRules/${i}`,
+                    message: `Pause rule "${r.id}" is not shown in the ownership section (${ownership.path}).`,
+                });
+            }
+        });
+    }
+    /* --------------------------------- inline refs ----------------------------- */
+    for (const entry of model.entries) {
+        for (const node of entry.nodes) {
+            if (node.kind !== 'markdown')
+                continue;
+            for (const r of extractInlineRefs(node)) {
+                const ref = `${r.kind}:${r.id}${r.anchor ? `#${r.anchor}` : ''}`;
+                if (!refExists(ref)) {
+                    err({
+                        code: 'REF_UNRESOLVED',
+                        path: entry.path,
+                        line: r.line,
+                        message: `Reference ${r.raw} does not resolve${r.kind === 'entry' && r.anchor ? ' (check the entry id and heading anchor)' : ''}.`,
+                    });
+                }
+            }
+        }
+    }
+    /* ---------------------------- profile & examples --------------------------- */
+    if (recipe)
+        validateProfile(model, recipe, emit, err);
+    validateExamples(model, emit, err);
+    /* ----------------------------------- assets -------------------------------- */
+    (model.assets?.assets ?? []).forEach((a, i) => {
+        const base = `/assets/${i}`;
+        const line = lineIn(BUNDLE_FILES.assets, base);
+        if (!a.path.startsWith('assets/')) {
+            err({ code: 'BUNDLE_PATH_UNSAFE', path: BUNDLE_FILES.assets, line, pointer: `${base}/path`, message: `Asset path "${a.path}" must be under assets/.` });
+            return;
+        }
+        const bytes = model.files.bytes(a.path);
+        if (!bytes) {
+            err({ code: 'ASSET_FILE_MISSING', path: BUNDLE_FILES.assets, line, pointer: `${base}/path`, message: `Asset file ${a.path} does not exist.` });
+        }
+        else {
+            const digest = sha256Digest(bytes);
+            if (digest !== a.digest) {
+                err({
+                    code: 'ASSET_DIGEST_MISMATCH',
+                    path: BUNDLE_FILES.assets,
+                    line: lineIn(BUNDLE_FILES.assets, `${base}/digest`),
+                    pointer: `${base}/digest`,
+                    message: `Asset "${a.id}" does not match its recorded digest.`,
+                    hint: `recorded ${a.digest}; actual ${digest}`,
+                });
+            }
+        }
+        const ext = a.path.split('.').pop()?.toLowerCase() ?? '';
+        const allowed = MEDIA_BY_EXT[ext];
+        if (allowed && !allowed.includes(a.mediaType)) {
+            err({
+                code: 'ASSET_MEDIA_TYPE_MISMATCH',
+                path: BUNDLE_FILES.assets,
+                line: lineIn(BUNDLE_FILES.assets, `${base}/mediaType`),
+                pointer: `${base}/mediaType`,
+                message: `Asset "${a.id}" is .${ext} but declares ${a.mediaType}; expected ${allowed.join(' or ')}.`,
+            });
+        }
+        if (a.decorative && a.alt) {
+            err({ code: 'ASSET_ALT_MISSING', path: BUNDLE_FILES.assets, line, pointer: base, message: `Asset "${a.id}" is both decorative and has alternative text; choose one.` });
+        }
+        else if (!a.decorative && !(a.alt ?? '').trim()) {
+            emit('missingFields', {
+                code: 'ASSET_ALT_MISSING',
+                path: BUNDLE_FILES.assets,
+                line,
+                pointer: base,
+                message: `Asset "${a.id}" needs alternative text or decorative: true.`,
+            });
+        }
+    });
+    /* ------------------------------- publication ------------------------------- */
+    const usage = computeUsage(model);
+    const sourceVisibility = new Map((sources?.sources ?? []).map((s) => [s.id, s.visibility ?? 'private']));
+    (sources?.sources ?? []).forEach((s, i) => {
+        if (usage.sources.has(s.id) && (s.visibility ?? 'private') !== 'public') {
+            emit('privateReferences', {
+                code: 'PUBLICATION_PRIVATE_REFERENCE',
+                path: BUNDLE_FILES.sources,
+                line: lineIn(BUNDLE_FILES.sources, `/sources/${i}`),
+                pointer: `/sources/${i}`,
+                message: `Source "${s.id}" is cited by published content but is private. Set visibility: public once it may be published.`,
+            });
+        }
+    });
+    (model.assets?.assets ?? []).forEach((a, i) => {
+        if (usage.assets.has(a.id) && (a.visibility ?? 'private') !== 'public') {
+            emit('privateReferences', {
+                code: 'PUBLICATION_PRIVATE_REFERENCE',
+                path: BUNDLE_FILES.assets,
+                line: lineIn(BUNDLE_FILES.assets, `/assets/${i}`),
+                pointer: `/assets/${i}`,
+                message: `Asset "${a.id}" is used by published content but is private. Set visibility: public once it may be published.`,
+            });
+        }
+    });
+    void sourceVisibility;
+    /* ------------------------- anchors, placeholders, secrets ------------------- */
+    for (const entry of model.entries) {
+        for (const h of entry.headings) {
+            if (!h.explicit) {
+                emit('unstableAnchors', {
+                    code: 'ANCHOR_UNSTABLE',
+                    path: entry.path,
+                    line: h.line,
+                    message: `Heading "${h.text}" has no explicit anchor; editing it changes its link. Add {#${h.anchor}} (made-easy anchors --fix).`,
+                });
+            }
+        }
+    }
+    for (const path of model.files.paths()) {
+        const isEntry = model.entries.some((e) => e.path === path);
+        const isYaml = /\.ya?ml$/i.test(path) && !path.startsWith('operator/fixtures/');
+        const text = TEXT_FILE.test(path) ? model.files.text(path) : undefined;
+        if (text === undefined)
+            continue;
+        if (isEntry || isYaml) {
+            for (const hit of scanPlaceholders(text, isEntry)) {
+                emit('placeholders', {
+                    code: 'PLACEHOLDER_PRESENT',
+                    path,
+                    line: hit.line,
+                    message: `Placeholder remains: ${hit.text}`,
+                });
+            }
+        }
+        const lines = text.split(/\r?\n/);
+        lines.forEach((l, i) => {
+            for (const [name, re] of SECRET_PATTERNS) {
+                if (re.test(l)) {
+                    err({
+                        code: 'SECRET_DETECTED',
+                        path,
+                        line: i + 1,
+                        message: `This line looks like a ${name}. Keep secrets and job-specific credentials out of the bundle; use an input placeholder instead.`,
+                    });
+                }
+            }
+        });
+    }
+    const diagnostics = sortDiagnostics(dedupeDiagnostics(out));
+    const summary = summarizeDiagnostics(diagnostics);
+    return {
+        ok: summary.errors === 0,
+        mode,
+        guideId: guide?.guideId,
+        revision: model.revision,
+        referenceRevision: model.referenceRevision,
+        summary,
+        diagnostics,
+    };
+}
+/* ------------------------------ requirement check ------------------------- */
+function checkRequirement(req, role, entry, blocks, emit) {
+    const matching = blocks.filter((b) => b.type === req.type &&
+        Object.entries(req.where ?? {}).every(([k, v]) => b.props[k] === v));
+    const missingOf = (b) => (req.fields ?? []).flatMap((f) => failingPointers(b.props, f, '').map((ptr) => ({ field: f, pointer: ptr })));
+    const scored = matching.map((b) => ({ b, missing: missingOf(b) })).sort((a, b) => a.missing.length - b.missing.length);
+    const satisfied = scored.filter((s) => s.missing.length === 0).length;
+    if (satisfied >= req.min)
+        return;
+    const label = req.label ?? req.type;
+    const whereText = req.where ? ` (${Object.entries(req.where).map(([k, v]) => `${k}: ${v}`).join(', ')})` : '';
+    const shortfall = req.min - satisfied;
+    const partial = scored.filter((s) => s.missing.length > 0).slice(0, shortfall);
+    for (const { b, missing } of partial) {
+        for (const m of missing) {
+            emit('missingFields', {
+                code: 'FIELD_REQUIRED_MISSING',
+                path: entry.path,
+                line: b.lineOf(`/props${m.pointer}`) ?? b.line,
+                blockId: b.id,
+                pointer: `/props${m.pointer}`,
+                message: `The "${role}" section's ${label}${whereText} needs "${m.field}".`,
+            });
+        }
+    }
+    const absent = shortfall - partial.length;
+    if (absent > 0) {
+        emit('missingBlocks', {
+            code: 'BLOCK_REQUIRED_MISSING',
+            path: entry.path,
+            line: 1,
+            message: `The "${role}" section needs ${absent > 1 ? `${absent} more` : 'a'} ${req.type} block${whereText}${req.fields?.length ? ` with ${req.fields.join(', ')}` : ''}.`,
+        });
+    }
+}
+/** Scan for `[[TODO: ...]]` in prose and YAML values; fenced code is ignored in Markdown. */
+export function scanPlaceholders(text, markdown) {
+    const out = [];
+    const lines = text.split(/\r?\n/);
+    let fence;
+    lines.forEach((l, i) => {
+        if (markdown) {
+            const m = /^ {0,3}(`{3,}|~{3,})[ \t]*(.*)$/.exec(l);
+            if (m) {
+                const marks = m[1];
+                if (!fence) {
+                    fence = { char: marks[0], length: marks.length, structured: /^made-easy(\s|$)/.test(m[2] ?? '') };
+                    return;
+                }
+                if (marks[0] === fence.char && marks.length >= fence.length && (m[2] ?? '').trim() === '') {
+                    fence = undefined;
+                    return;
+                }
+            }
+            // Ordinary code fences are literal; structured made-easy blocks are scanned.
+            if (fence && !fence.structured)
+                return;
+        }
+        const masked = markdown && !fence ? l.replace(/(`+)([^`]|[^`][\s\S]*?[^`])\1(?!`)/g, (x) => ' '.repeat(x.length)) : l;
+        for (const m of masked.matchAll(new RegExp(PLACEHOLDER_PATTERN.source, 'g')))
+            out.push({ line: i + 1, text: m[0] });
+    });
+    return out;
+}
+/* ------------------------------- profile checks --------------------------- */
+function validateProfile(model, recipe, emit, err) {
+    void err;
+    const profile = recipe.profileDefinition;
+    const scope = entriesOf(model, 'operator').find((e) => e.role === 'scope');
+    if (!scope)
+        return;
+    const block = blocksOf(scope).find((b) => b.type === 'reference-profile');
+    if (!block) {
+        emit('profileFields', {
+            code: 'PROFILE_FIELD_MISSING',
+            path: scope.path,
+            line: 1,
+            message: `The scope entry needs a reference-profile block for the ${recipe.profile} profile (${profile.referenceFields.filter((f) => !f.optional).map((f) => f.key).join(', ')}).`,
+        });
+        return;
+    }
+    const props = block.props;
+    const fields = props.fields ?? {};
+    if (props.profile && props.profile !== recipe.profile) {
+        emit('profileFields', {
+            code: 'SUBJECT_RECIPE_MISMATCH',
+            path: scope.path,
+            line: block.lineOf('/props/profile') ?? block.line,
+            blockId: block.id,
+            message: `reference-profile declares "${props.profile}" but the recipe profile is "${recipe.profile}".`,
+        });
+    }
+    const need = [...profile.referenceFields.filter((f) => !f.optional)];
+    const distribution = String(fields.distribution ?? '').toLowerCase();
+    if (recipe.profile === 'sdk' && /\bnpm\b/.test(distribution))
+        need.push(...(profile.npmFields ?? []));
+    for (const f of need) {
+        if (!isFilled(fields[f.key])) {
+            emit('profileFields', {
+                code: 'PROFILE_FIELD_MISSING',
+                path: scope.path,
+                line: block.lineOf(`/props/fields/${f.key}`) ?? block.line,
+                blockId: block.id,
+                pointer: `/props/fields/${f.key}`,
+                message: `The ${recipe.profile} profile requires "${f.key}" (${f.label}).`,
+            });
+        }
+    }
+    if (profile.requiresExactVersion && isFilled(fields.version) && !EXACT_VERSION.test(String(fields.version))) {
+        emit('sdkExactness', {
+            code: 'SDK_VERSION_NOT_EXACT',
+            path: scope.path,
+            line: block.lineOf('/props/fields/version') ?? block.line,
+            blockId: block.id,
+            pointer: '/props/fields/version',
+            message: `Version "${String(fields.version)}" is not exact. Resolve the requested range to one registry version (made-easy resolve npm <package>).`,
+        });
+    }
+    if (recipe.profile === 'sdk' && /\bnpm\b/.test(distribution) && isFilled(fields.integrity)) {
+        if (!/^sha(1|256|384|512)-[A-Za-z0-9+/=]+$/.test(String(fields.integrity))) {
+            emit('sdkExactness', {
+                code: 'SDK_INTEGRITY_MISSING',
+                path: scope.path,
+                line: block.lineOf('/props/fields/integrity') ?? block.line,
+                blockId: block.id,
+                pointer: '/props/fields/integrity',
+                message: 'The integrity value is not a valid SRI string (for example sha512-...).',
+            });
+        }
+    }
+    if (profile.requiresRunnableExample) {
+        const runnable = allBlocks(model).some(({ block: b }) => {
+            if (b.type !== 'example')
+                return false;
+            const p = b.props;
+            return p.executable !== false && isFilled(p.fixture) && isFilled(p.run) && isFilled(p.expected);
+        });
+        if (!runnable) {
+            emit('profileFields', {
+                code: 'SDK_EXAMPLE_MISSING',
+                path: scope.path,
+                line: 1,
+                message: 'The sdk profile requires a complete runnable example block (fixture, run commands and expected output).',
+            });
+        }
+    }
+}
+/* ------------------------------ example checks ---------------------------- */
+function validateExamples(model, emit, err) {
+    const records = model.verification?.records ?? [];
+    for (const { entry, block } of exampleBlocks(model)) {
+        const p = block.props;
+        const fixture = typeof p.fixture === 'string' ? p.fixture.replace(/\/$/, '') : '';
+        const at = (ptr) => block.lineOf(`/props${ptr}`) ?? block.line;
+        if (!fixture || !fixture.startsWith('operator/fixtures/') || fixture.includes('..')) {
+            emit('missingFields', {
+                code: 'EXAMPLE_FIXTURE_MISSING',
+                path: entry.path,
+                line: at('/fixture'),
+                blockId: block.id,
+                message: `Example "${block.id}" needs a fixture directory under operator/fixtures/.`,
+            });
+            continue;
+        }
+        const fixtureFiles = model.files.paths().filter((x) => x.startsWith(`${fixture}/`));
+        if (!fixtureFiles.length) {
+            emit('missingFields', {
+                code: 'EXAMPLE_FIXTURE_MISSING',
+                path: entry.path,
+                line: at('/fixture'),
+                blockId: block.id,
+                message: `Fixture directory ${fixture}/ has no files.`,
+            });
+            continue;
+        }
+        p.files?.forEach((f, i) => {
+            const resolved = resolveRelative(`${fixture}/x`, f);
+            if (!resolved || !resolved.startsWith(`${fixture}/`) || !model.files.has(resolved)) {
+                err({
+                    code: 'REF_UNRESOLVED',
+                    path: entry.path,
+                    line: at(`/files/${i}`),
+                    blockId: block.id,
+                    pointer: `/props/files/${i}`,
+                    message: `Example file "${f}" is not inside ${fixture}/.`,
+                });
+            }
+        });
+        if (!isFilled(p.run) || !isFilled(p.expected)) {
+            emit('missingFields', {
+                code: 'FIELD_REQUIRED_MISSING',
+                path: entry.path,
+                line: at(''),
+                blockId: block.id,
+                message: `Example "${block.id}" needs run commands and expected output.`,
+            });
+        }
+        const record = records.find((r) => r.example === block.id);
+        if (!record) {
+            emit('unverifiedExamples', {
+                code: 'EXAMPLE_UNVERIFIED',
+                path: entry.path,
+                line: block.line,
+                blockId: block.id,
+                message: `Executable example "${block.id}" has no verification record (made-easy verify, or a matching CI record in operator/fixtures/verification.yaml).`,
+            });
+            continue;
+        }
+        const digest = exampleDigest(model, p);
+        if (record.digest !== digest) {
+            emit('unverifiedExamples', {
+                code: 'EXAMPLE_VERIFICATION_STALE',
+                path: 'operator/fixtures/verification.yaml',
+                line: model.lines['operator/fixtures/verification.yaml']?.(`/records/${records.indexOf(record)}/digest`),
+                blockId: block.id,
+                message: `The verification record for "${block.id}" does not match the current example or fixture files. Re-verify it.`,
+                hint: `recorded ${record.digest}; current ${digest}`,
+            });
+        }
+        else if (record.result !== 'pass') {
+            emit('unverifiedExamples', {
+                code: 'EXAMPLE_VERIFICATION_FAILED',
+                path: 'operator/fixtures/verification.yaml',
+                line: model.lines['operator/fixtures/verification.yaml']?.(`/records/${records.indexOf(record)}/result`),
+                blockId: block.id,
+                message: `The verification record for "${block.id}" reports a failing example.`,
+            });
+        }
+    }
+}
+export { pointerFromPath };
+//# sourceMappingURL=validate.js.map