eidosmd 0.1.0

package/dist/src/commands/whoami.js

@@ -0,0 +1,84 @@
+// `eidos roles` and `eidos whoami`: the cast a framework installed, and the
+// actor in the seat.
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { findRole, listRoles, meFile, readActor, renderActor, writeActor } from '../core/me.js';
+import { CliError, EXIT_OK, print, printJson } from '../output.js';
+export function runRoles(context, options) {
+    const roles = listRoles(context.root);
+    if (options.json) {
+        printJson(roles.map((role) => ({ name: role.name, title: role.title, path: path.relative(context.root, role.file).split(path.sep).join('/'), summary: role.summary })));
+        return EXIT_OK;
+    }
+    if (roles.length === 0) {
+        print('no roles installed under _eidos/roles/; an older framework, or one that declares none');
+        return EXIT_OK;
+    }
+    for (const role of roles) {
+        print(`${role.name}  —  ${role.title}`);
+        if (role.summary) {
+            print(`  ${role.summary}`);
+        }
+    }
+    print('', 'set yours: eidos whoami --role <name> [--ownership "..."] [--experience "..."] [--capacity "..."]');
+    return EXIT_OK;
+}
+function actorJson(file, exists, actor) {
+    return { path: file, exists, role: actor.role, role_file: actor.roleFile, note: actor.note, ownership: actor.ownership, experience: actor.experience, capacity: actor.capacity };
+}
+export function runWhoami(context, options) {
+    const setting = options.role !== undefined || options.ownership !== undefined || options.experience !== undefined || options.capacity !== undefined;
+    if (options.clear) {
+        const file = writeActor(context.root, renderActor(null, null, { ownership: null, experience: null, capacity: null }));
+        print(`cleared ${path.relative(context.root, file)}; the agent defaults to full facilitation`);
+        return EXIT_OK;
+    }
+    if (setting) {
+        const current = readActor(context.root).actor;
+        let role = null;
+        let custom = null;
+        const roleName = options.role ?? current.role;
+        if (roleName !== null && roleName !== undefined) {
+            role = findRole(context.root, roleName);
+            if (!role) {
+                if (options.role !== undefined && listRoles(context.root).length > 0) {
+                    const known = listRoles(context.root).map((candidate) => candidate.name).join(', ');
+                    throw new CliError(`no role '${options.role}' under _eidos/roles/ (installed: ${known}); a custom role is set by editing _eidos/me.md`);
+                }
+                custom = roleName;
+            }
+        }
+        const text = renderActor(role, custom, {
+            ownership: options.ownership ?? current.ownership,
+            experience: options.experience ?? current.experience,
+            capacity: options.capacity ?? current.capacity,
+        });
+        const file = writeActor(context.root, text);
+        if (options.json) {
+            printJson(actorJson(path.relative(context.root, file), true, readActor(context.root).actor));
+            return EXIT_OK;
+        }
+        print(`✓ ${path.relative(context.root, file)}`, '', text.trimEnd());
+        return EXIT_OK;
+    }
+    const { exists, actor } = readActor(context.root);
+    if (options.json) {
+        printJson(actorJson(path.relative(context.root, meFile(context.root)), exists, actor));
+        return EXIT_OK;
+    }
+    if (!exists) {
+        print('no _eidos/me.md: the actor is unset, so the agent defaults to full facilitation', 'set it: eidos whoami --role <name>');
+        return EXIT_OK;
+    }
+    if (actor.role === null) {
+        print('the actor is blank (full facilitation); roles installed here:', '');
+        return runRoles(context, { json: false });
+    }
+    print(`you are: ${actor.role}`);
+    const roleFile = actor.roleFile ? path.resolve(context.root, '_eidos', actor.roleFile) : null;
+    if (roleFile && existsSync(roleFile)) {
+        print(`role file: ${path.relative(context.root, roleFile).split(path.sep).join('/')}`, '', readFileSync(roleFile, 'utf8').trimEnd(), '');
+    }
+    print('calibration:', `  ownership: ${actor.ownership ?? '(unset)'}`, `  experience with the scope: ${actor.experience ?? '(unset)'}`, `  technical capacity: ${actor.capacity ?? '(unset)'}`);
+    return EXIT_OK;
+}

package/dist/src/context.js

@@ -0,0 +1,35 @@
+// What every root-bound command needs: the root, its framework, and its
+// blueprints, resolved once from the working directory or --root.
+import { listBlueprints } from './core/blueprint.js';
+import { FrameworkError, loadFramework } from './core/framework.js';
+import { findRoot, RootError } from './core/root.js';
+import { CliError, EXIT_USAGE } from './output.js';
+// The CLI works on Framework.yaml. A root that keeps Framework.md is read only
+// to convert it (or to print it), so every other command points at `convert`.
+export function loadRoot(globals, cwd = process.cwd(), options = {}) {
+    let root;
+    try {
+        root = findRoot(cwd, globals.root);
+    }
+    catch (cause) {
+        if (cause instanceof RootError) {
+            const hint = cause.candidates.length === 0 ? '\n\nFor the way in, run: eidos instructions init-required' : '';
+            throw new CliError(cause.message + hint, EXIT_USAGE);
+        }
+        throw cause;
+    }
+    let framework;
+    try {
+        framework = loadFramework(root);
+    }
+    catch (cause) {
+        if (cause instanceof FrameworkError) {
+            throw new CliError(cause.message, EXIT_USAGE);
+        }
+        throw cause;
+    }
+    if (framework.format === 'md' && !options.allowMarkdown) {
+        throw new CliError(`${root} keeps its framework as _eidos/Framework.md. The eidos CLI works on Framework.yaml: run \`eidos convert\` to move it (Framework.md and each collection's index.md are removed; the markdown form's prose has no field to land in). \`eidos convert --dry-run\` shows the writes, and \`eidos framework --as yaml\` prints the result without touching anything.`, EXIT_USAGE);
+    }
+    return { cwd, root, framework, blueprints: listBlueprints(framework) };
+}

package/dist/src/core/blueprint.js

@@ -0,0 +1,129 @@
+// Blueprints on disk: one markdown file per unit, directly in a collection
+// folder or one level of sub-folders beneath it. Loading reads the frontmatter
+// and the body's sections; nothing here judges the file (that is `check`).
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { parseFrontmatter } from './frontmatter.js';
+import { defaultFlavor, findFlavor } from './framework.js';
+import { headings, sections } from './markdown.js';
+import { kebab } from './naming.js';
+export function blueprintFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => /\.md$/i.test(entry) && entry.toLowerCase() !== 'index.md' && !entry.startsWith('.'))
+        .filter((entry) => {
+        try {
+            return statSync(path.join(dir, entry)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+}
+export function groupDirs(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => !entry.startsWith('.'))
+        .filter((entry) => {
+        try {
+            return statSync(path.join(dir, entry)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+}
+export function loadBlueprint(root, collection, group, file) {
+    const full = group === null ? path.join(root, collection.name, file) : path.join(root, collection.name, group, file);
+    const text = readFileSync(full, 'utf8');
+    const { properties, body, error } = parseFrontmatter(text);
+    return {
+        path: full,
+        rel: path.relative(root, full).split(path.sep).join('/'),
+        collection,
+        group,
+        file,
+        stem: file.replace(/\.md$/i, ''),
+        properties,
+        frontmatterError: error,
+        body,
+        headings: headings(body),
+        sections: sections(body, 2),
+    };
+}
+export function listBlueprints(framework, collections = framework.collections) {
+    const out = [];
+    for (const collection of collections) {
+        const dir = path.join(framework.root, collection.name);
+        for (const file of blueprintFiles(dir)) {
+            out.push(loadBlueprint(framework.root, collection, null, file));
+        }
+        for (const group of groupDirs(dir)) {
+            for (const file of blueprintFiles(path.join(dir, group))) {
+                out.push(loadBlueprint(framework.root, collection, group, file));
+            }
+        }
+    }
+    return out;
+}
+export function propertyString(blueprint, key) {
+    const value = blueprint.properties?.[key];
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        return value.trim() === '' ? null : value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return null;
+}
+export function blueprintId(blueprint) {
+    return propertyString(blueprint, 'id');
+}
+export function blueprintTitle(blueprint) {
+    return propertyString(blueprint, 'title') ?? blueprint.stem;
+}
+// The flavor a blueprint follows: the one it names, else its collection's default.
+export function resolveFlavor(blueprint) {
+    const declared = propertyString(blueprint, 'flavor');
+    if (declared === null) {
+        return { flavor: defaultFlavor(blueprint.collection), declared: null, known: true };
+    }
+    const flavor = findFlavor(blueprint.collection, declared);
+    return { flavor, declared, known: flavor !== null };
+}
+// A blueprint by path, by id, or by filename stem, in that order.
+export function resolveBlueprint(ref, blueprints, cwd) {
+    const asPath = path.resolve(cwd, ref);
+    const byPath = blueprints.find((blueprint) => path.resolve(blueprint.path) === asPath);
+    if (byPath) {
+        return byPath;
+    }
+    const wanted = ref.trim().toLowerCase();
+    const byId = blueprints.find((blueprint) => blueprintId(blueprint)?.toLowerCase() === wanted);
+    if (byId) {
+        return byId;
+    }
+    const byKebab = blueprints.find((blueprint) => blueprintId(blueprint) === kebab(ref));
+    if (byKebab) {
+        return byKebab;
+    }
+    const byStem = blueprints.filter((blueprint) => blueprint.stem.toLowerCase() === wanted || kebab(blueprint.stem) === kebab(ref));
+    return byStem.length === 1 ? (byStem[0] ?? null) : null;
+}

package/dist/src/core/check.js

@@ -0,0 +1,407 @@
+// Validation, framework-defined: every rule reads the root's own Framework.md
+// and shapes, never a contract hardcoded here. Findings surface; a human acts
+// on them. Errors are things that are wrong on any reading (a malformed file,
+// an id used twice, a link to nowhere); warnings are gaps the standard says to
+// note and offer, never refuse.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { blueprintId, blueprintTitle, propertyString, resolveFlavor } from './blueprint.js';
+import { appliesTo } from './framework.js';
+import { renderEmbeddedEntries } from './index-leaf.js';
+import { embeddedIndexOf } from './framework-structured.js';
+import { normalizeNewlines } from './markdown.js';
+import { isKebab, kebab } from './naming.js';
+import { loadShape } from './shape.js';
+const WORK_TRACKING_FIELDS = new Set(['sprint', 'estimate', 'assignee', 'story_points']);
+const SKIPPED_DIRS = new Set(['node_modules', 'dist', 'build']);
+function compareVersions(a, b) {
+    const left = a.split('.').map((part) => Number.parseInt(part, 10) || 0);
+    const right = b.split('.').map((part) => Number.parseInt(part, 10) || 0);
+    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+        const diff = (left[index] ?? 0) - (right[index] ?? 0);
+        if (diff !== 0) {
+            return diff < 0 ? -1 : 1;
+        }
+    }
+    return 0;
+}
+function isEmpty(value) {
+    return value === undefined || value === null || (typeof value === 'string' && value.trim() === '');
+}
+function typeProblem(property, value) {
+    if (isEmpty(value)) {
+        return null;
+    }
+    switch (property.type.toLowerCase()) {
+        case 'text':
+            return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' ? null : 'expected a single text value';
+        case 'list':
+            return Array.isArray(value) ? null : 'expected a list (`[]` or `- item` lines)';
+        case 'number':
+            return typeof value === 'number' ? null : 'expected a number';
+        case 'checkbox':
+            return typeof value === 'boolean' ? null : 'expected true or false';
+        case 'date':
+            return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value) ? null : 'expected a YYYY-MM-DD date';
+        case 'date & time':
+            return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(value) ? null : 'expected a YYYY-MM-DD HH:MM date and time';
+        default:
+            return null;
+    }
+}
+// Every markdown link target in a piece of text, outside code fences and
+// inline code. Scheme-bearing targets and pure anchors are not files.
+function linkTargets(text) {
+    const out = [];
+    const stripped = normalizeNewlines(text)
+        .replace(/```[\s\S]*?```/g, '')
+        .replace(/`[^`\n]*`/g, '');
+    const pattern = /\[[^\]]*\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g;
+    let match = pattern.exec(stripped);
+    while (match !== null) {
+        if (match[1] !== undefined) {
+            out.push(match[1]);
+        }
+        match = pattern.exec(stripped);
+    }
+    return out;
+}
+function isFileTarget(target) {
+    return !/^[a-z][a-z0-9+.-]*:/i.test(target) && !target.startsWith('#') && !target.startsWith('//');
+}
+function linkExists(fromDir, target) {
+    const withoutAnchor = target.split('#')[0] ?? '';
+    if (withoutAnchor === '') {
+        return true;
+    }
+    let decoded = withoutAnchor;
+    try {
+        decoded = decodeURIComponent(withoutAnchor);
+    }
+    catch {
+        // an undecodable target is checked as written
+    }
+    return existsSync(path.resolve(fromDir, decoded));
+}
+function propertyLinks(value) {
+    const values = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const item of values) {
+        if (typeof item !== 'string') {
+            continue;
+        }
+        const match = /^\s*\[[^\]]*\]\(\s*<?([^)\s>]+)>?\s*\)\s*$/.exec(item);
+        if (match && match[1] !== undefined) {
+            out.push(match[1]);
+        }
+    }
+    return out;
+}
+class Collector {
+    findings = [];
+    error(code, file, message) {
+        this.findings.push({ level: 'error', code, path: file, message });
+    }
+    warn(code, file, message) {
+        this.findings.push({ level: 'warning', code, path: file, message });
+    }
+}
+function rel(root, file) {
+    return path.relative(root, file).split(path.sep).join('/');
+}
+function checkFramework(framework, out, options) {
+    const frameworkRel = rel(framework.root, framework.file);
+    for (const problem of framework.problems) {
+        out.error('framework-invalid', frameworkRel, problem);
+    }
+    if (framework.namingError) {
+        out.error('naming-invalid', frameworkRel, framework.namingError);
+    }
+    if (framework.eidosVersion === null) {
+        out.warn('version-missing', frameworkRel, `no eidos_version; this CLI carries the standard at ${options.standardVersion}`);
+    }
+    else {
+        const diff = compareVersions(framework.eidosVersion, options.standardVersion);
+        if (diff < 0) {
+            out.warn('version-behind', frameworkRel, `targets Eidos ${framework.eidosVersion}; this CLI carries ${options.standardVersion} (migrate when ready)`);
+        }
+        else if (diff > 0) {
+            out.warn('version-ahead', frameworkRel, `targets Eidos ${framework.eidosVersion}, newer than the ${options.standardVersion} this CLI carries`);
+        }
+    }
+    if (framework.collections.length === 0) {
+        out.error('no-collections', frameworkRel, 'declares no collections under ## Collections; a framework needs at least a framing collection');
+    }
+    if (!existsSync(path.join(framework.root, 'README.md'))) {
+        out.warn('readme-missing', null, 'no README.md at the root; the visible front door is missing');
+    }
+    for (const doc of framework.topLevel) {
+        if (isFileTarget(doc.path) && !linkExists(path.dirname(framework.file), doc.path)) {
+            out.warn('top-level-missing', frameworkRel, `## Top-Level lists ${doc.title} at ${doc.path}, which does not exist`);
+        }
+    }
+    const shapes = new Map();
+    for (const collection of framework.collections) {
+        if (collection.flavors.length === 0) {
+            out.error('flavor-none', frameworkRel, `collection ${collection.name} declares no flavors`);
+        }
+        for (const flavor of collection.flavors) {
+            const shape = loadShape(framework, flavor);
+            shapes.set(`${collection.name}/${flavor.name}`, shape);
+            if (!shape) {
+                out.error('shape-missing', frameworkRel, `${collection.name}/${flavor.name} points at _eidos/${flavor.shape}, which does not exist`);
+            }
+        }
+        if (!existsSync(path.join(framework.root, collection.name))) {
+            out.warn('collection-folder-missing', null, `collection ${collection.name} is declared but has no folder`);
+        }
+    }
+    return shapes;
+}
+function checkLayout(framework, blueprints, out) {
+    const declared = new Set(framework.collections.map((collection) => collection.name));
+    const embedded = embeddedIndexOf(readFileSync(framework.file, 'utf8'));
+    let entries = [];
+    try {
+        entries = readdirSync(framework.root);
+    }
+    catch {
+        entries = [];
+    }
+    for (const entry of entries.sort()) {
+        if (entry.startsWith('.') || entry === '_eidos' || SKIPPED_DIRS.has(entry) || declared.has(entry)) {
+            continue;
+        }
+        let isDir = false;
+        try {
+            isDir = statSync(path.join(framework.root, entry)).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (isDir) {
+            out.warn('folder-undeclared', entry, 'a folder at the root that no collection declares; declare it in Framework.md or move it');
+        }
+    }
+    for (const collection of framework.collections) {
+        const folder = path.join(framework.root, collection.name);
+        if (!existsSync(folder)) {
+            continue;
+        }
+        const own = blueprints.filter((blueprint) => blueprint.collection === collection);
+        const groupsOnDisk = [...new Set(own.map((blueprint) => blueprint.group).filter((group) => group !== null))];
+        if (collection.grouping && collection.grouping.groups.length > 0) {
+            const declaredGroups = new Map(collection.grouping.groups.map((group) => [group.name.toLowerCase(), group.name]));
+            for (const group of groupsOnDisk) {
+                if (!declaredGroups.has(group.toLowerCase())) {
+                    out.warn('group-undeclared', `${collection.name}/${group}`, `not declared under ${collection.grouping.label} in Framework.md`);
+                }
+            }
+            for (const group of collection.grouping.groups) {
+                if (!existsSync(path.join(folder, group.name))) {
+                    out.warn('group-folder-missing', `${collection.name}/${group.name}`, `declared under ${collection.grouping.label} but has no folder`);
+                }
+            }
+        }
+        if (collection.grouping && groupsOnDisk.length > 0) {
+            for (const blueprint of own.filter((candidate) => candidate.group === null)) {
+                out.warn('blueprint-ungrouped', blueprint.rel, `sits at the top of ${collection.name}, which groups by ${collection.grouping.label}`);
+            }
+        }
+        if (collection.framing) {
+            for (const flavor of collection.flavors) {
+                const written = own.some((blueprint) => resolveFlavor(blueprint).flavor === flavor);
+                if (!written) {
+                    out.warn('frame-unwritten', collection.name, `no ${flavor.name} frame yet; a gap to surface, not a failure`);
+                }
+            }
+        }
+        const wanted = JSON.stringify(renderEmbeddedEntries(collection, blueprints));
+        const held = embedded?.[collection.name];
+        if (JSON.stringify(held ?? null) !== wanted) {
+            out.warn('index-stale', rel(framework.root, framework.file), `index.${collection.name} is ${held === undefined ? 'missing' : 'out of date'}; run \`eidos index\``);
+        }
+    }
+}
+function checkBlueprint(framework, blueprint, shapes, out) {
+    const file = blueprint.rel;
+    if (blueprint.properties === null) {
+        if (blueprint.frontmatterError) {
+            out.error('frontmatter-invalid', file, blueprint.frontmatterError);
+        }
+        else {
+            out.error('frontmatter-missing', file, 'no frontmatter block; every blueprint opens with the properties its collection declares');
+        }
+        return;
+    }
+    if (blueprint.frontmatterError) {
+        out.warn('frontmatter-yaml', file, blueprint.frontmatterError);
+    }
+    const properties = blueprint.properties;
+    const collection = blueprint.collection;
+    const id = propertyString(blueprint, 'id');
+    if (id === null) {
+        out.error('id-missing', file, 'no `id`; add a permanent kebab-case identity');
+    }
+    else if (!isKebab(id)) {
+        out.error('id-format', file, `id '${id}' is not kebab-case`);
+    }
+    else if (framework.naming === 'kebab-case' && blueprint.stem !== id) {
+        out.warn('id-filename', file, `in a kebab-case root the filename is the id; expected ${id}.md`);
+    }
+    if (propertyString(blueprint, 'title') === null) {
+        out.error('title-missing', file, 'no `title`');
+    }
+    if (propertyString(blueprint, 'summary') === null) {
+        out.warn('summary-missing', file, 'no `summary`; the collection index will flag it');
+    }
+    const { flavor, declared, known } = resolveFlavor(blueprint);
+    if (!known) {
+        const names = collection.flavors.map((candidate) => candidate.name).join(', ');
+        out.error('flavor-unknown', file, `flavor '${declared ?? ''}' is not one of ${collection.name}'s declared flavors (${names})`);
+    }
+    const core = new Set(framework.schema.core.map((property) => property.name));
+    const applicable = framework.schema.custom.filter((property) => appliesTo(property, collection.name));
+    const applicableNames = new Set(applicable.map((property) => property.name));
+    for (const property of applicable) {
+        if (!(property.name in properties)) {
+            out.warn('property-missing', file, `no \`${property.name}\` (${property.type}, applies to ${collection.name})`);
+        }
+        else if (isEmpty(properties[property.name]) && property.type.toLowerCase() !== 'list') {
+            out.warn('property-empty', file, `\`${property.name}\` has no value`);
+        }
+    }
+    for (const key of Object.keys(properties)) {
+        if (core.has(key) || applicableNames.has(key)) {
+            continue;
+        }
+        const elsewhere = framework.schema.custom.find((property) => property.name === key);
+        if (elsewhere) {
+            const scope = elsewhere.appliesTo === 'all' ? 'all' : elsewhere.appliesTo.join(', ');
+            out.warn('property-scope', file, `\`${key}\` applies to ${scope}, not ${collection.name}`);
+        }
+        else if (WORK_TRACKING_FIELDS.has(key.toLowerCase())) {
+            out.warn('work-tracking-field', file, `\`${key}\` is a work-tracking field; a blueprint captures state and intent, not work (link to a tracker instead)`);
+        }
+        else {
+            out.warn('property-unknown', file, `\`${key}\` is not in the Schema; declare it under ### Custom Properties or drop it`);
+        }
+    }
+    for (const property of [...framework.schema.core, ...applicable]) {
+        if (!(property.name in properties)) {
+            continue;
+        }
+        const problem = typeProblem(property, properties[property.name]);
+        if (problem) {
+            out.warn('property-type', file, `\`${property.name}\` (${property.type}): ${problem}`);
+        }
+    }
+    if (collection.grouping?.property) {
+        const value = propertyString(blueprint, collection.grouping.property);
+        if (value !== null && blueprint.group === null) {
+            out.warn('group-mismatch', file, `\`${collection.grouping.property}: ${value}\` but the blueprint is not in a sub-folder`);
+        }
+        else if (value !== null && blueprint.group !== null && value !== blueprint.group) {
+            out.warn('group-mismatch', file, `\`${collection.grouping.property}: ${value}\` does not match its folder ${blueprint.group}/`);
+        }
+    }
+    const dir = path.dirname(blueprint.path);
+    for (const [key, value] of Object.entries(properties)) {
+        for (const target of propertyLinks(value)) {
+            if (isFileTarget(target) && !linkExists(dir, target)) {
+                out.error('link-broken', file, `\`${key}\` links to ${target}, which does not exist`);
+            }
+        }
+    }
+    const brokenInBody = new Map();
+    for (const target of linkTargets(blueprint.body)) {
+        if (isFileTarget(target) && !linkExists(dir, target)) {
+            brokenInBody.set(target, (brokenInBody.get(target) ?? 0) + 1);
+        }
+    }
+    for (const [target, count] of brokenInBody) {
+        out.error('link-broken', file, `the body links to ${target}, which does not exist${count > 1 ? ` (${count} times)` : ''}`);
+    }
+    const title = blueprintTitle(blueprint);
+    const h1 = blueprint.headings.find((heading) => heading.level === 1);
+    if (h1 && h1.text !== title && kebab(h1.text) !== kebab(title)) {
+        out.warn('title-mismatch', file, `the heading '${h1.text}' differs from title '${title}'`);
+    }
+    const shape = flavor ? (shapes.get(`${collection.name}/${flavor.name}`) ?? loadShape(framework, flavor)) : null;
+    if (!shape || !flavor) {
+        return;
+    }
+    const present = blueprint.sections.map((section) => section.heading.text);
+    const presentLower = present.map((text) => text.toLowerCase());
+    const shapeLower = shape.sections.map((text) => text.toLowerCase());
+    for (const name of shape.sections) {
+        if (!presentLower.includes(name.toLowerCase())) {
+            out.warn('section-missing', file, `no \`## ${name}\` (${flavor.kind}.${flavor.name} declares it; leave it out only if it genuinely does not apply)`);
+        }
+    }
+    if (!collection.framing) {
+        for (const name of present) {
+            if (!shapeLower.includes(name.toLowerCase())) {
+                out.warn('section-unknown', file, `\`## ${name}\` is not a section of ${flavor.kind}.${flavor.name}; nest it under one that is, or add it to the shape`);
+            }
+        }
+    }
+    const order = presentLower.filter((name) => shapeLower.includes(name)).map((name) => shapeLower.indexOf(name));
+    for (let index = 1; index < order.length; index += 1) {
+        if ((order[index] ?? 0) < (order[index - 1] ?? 0)) {
+            out.warn('section-order', file, `sections are not in ${flavor.kind}.${flavor.name}'s order (${shape.sections.join(' → ')})`);
+            break;
+        }
+    }
+}
+export function checkRoot(framework, blueprints, options) {
+    const out = new Collector();
+    const shapes = checkFramework(framework, out, options);
+    if (!options.only) {
+        checkLayout(framework, blueprints, out);
+    }
+    const seen = new Map();
+    for (const blueprint of blueprints) {
+        const id = blueprintId(blueprint);
+        if (id === null) {
+            continue;
+        }
+        const first = seen.get(id);
+        if (!first) {
+            seen.set(id, blueprint);
+            continue;
+        }
+        const inScope = (candidate) => !options.only || options.only.has(candidate.path);
+        if (inScope(blueprint)) {
+            out.error('id-duplicate', blueprint.rel, `id '${id}' is also used by ${first.rel}`);
+        }
+        else if (inScope(first)) {
+            out.error('id-duplicate', first.rel, `id '${id}' is also used by ${blueprint.rel}`);
+        }
+    }
+    const targets = options.only ? blueprints.filter((blueprint) => options.only?.has(blueprint.path)) : blueprints;
+    for (const blueprint of targets) {
+        checkBlueprint(framework, blueprint, shapes, out);
+    }
+    const findings = out.findings.sort((a, b) => {
+        const left = a.path ?? '';
+        const right = b.path ?? '';
+        if (left !== right) {
+            return left < right ? -1 : 1;
+        }
+        if (a.level !== b.level) {
+            return a.level === 'error' ? -1 : 1;
+        }
+        return 0;
+    });
+    return {
+        root: framework.root,
+        eidosVersion: framework.eidosVersion,
+        naming: framework.naming,
+        blueprints: targets.length,
+        collections: framework.collections.length,
+        errors: findings.filter((finding) => finding.level === 'error').length,
+        warnings: findings.filter((finding) => finding.level === 'warning').length,
+        findings,
+    };
+}