eidosmd 0.1.0 → 0.3.0

package/dist/src/core/check.js

@@ -1,17 +1,19 @@
-// Validation, framework-defined: every rule reads the root's own Framework.md
-// and shapes, never a contract hardcoded here. Findings surface; a human acts
+// Validation, framework-defined: every rule reads the root's own Framework.yaml
+// and templates, 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 { blueprintId, blueprintTitle, groupDirs, propertyString, resolveVariant } from './blueprint.js';
+import { appliesTo, isCollection, unitOf } from './framework.js';
 import { renderEmbeddedEntries } from './index-leaf.js';
 import { embeddedIndexOf } from './framework-structured.js';
+import { FRAME_REF, isFrameRef, listCanvases } from './canvas.js';
 import { normalizeNewlines } from './markdown.js';
-import { isKebab, kebab } from './naming.js';
-import { loadShape } from './shape.js';
+import { kebab } from './naming.js';
+import { parseRegions, stripRegions } from './regions.js';
+import { loadTemplate } from './template.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) {
@@ -49,6 +51,19 @@ function typeProblem(property, value) {
             return null;
     }
 }
+// Rule 9: a value off a property's declared options, exact, case included:
+// the value (or the List's elements) not on the list, or null when every
+// one is, or when the property declares none. The list rides along so the
+// message can show it.
+export function optionProblem(property, value) {
+    if (!property.options || isEmpty(value)) {
+        return null;
+    }
+    const declared = new Set(property.options);
+    const held = Array.isArray(value) ? value : [value];
+    const off = held.filter((item) => !isEmpty(item) && (typeof item !== 'string' || !declared.has(item))).map((item) => (typeof item === 'string' ? item : JSON.stringify(item)));
+    return off.length > 0 ? { off, options: property.options } : 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) {
@@ -99,8 +114,8 @@ function propertyLinks(value) {
 }
 class Collector {
     findings = [];
-    error(code, file, message) {
-        this.findings.push({ level: 'error', code, path: file, message });
+    error(code, file, message, fix) {
+        this.findings.push({ level: 'error', code, path: file, message, ...(fix ? { fix } : {}) });
     }
     warn(code, file, message) {
         this.findings.push({ level: 'warning', code, path: file, message });
@@ -109,6 +124,15 @@ class Collector {
 function rel(root, file) {
     return path.relative(root, file).split(path.sep).join('/');
 }
+// Rule 20: a region's contents are never faulted, and the one thing about a
+// region that is, whichever tool it names, is an opener with no closer.
+function checkRegions(text, file, out) {
+    for (const region of parseRegions(text)) {
+        if (region.close === null) {
+            out.error('region-unclosed', file, `\`<!-- ${region.tool}:${region.region} -->\` opens a region that never closes; add \`<!-- /${region.tool}:${region.region} -->\` after its contents`);
+        }
+    }
+}
 function checkFramework(framework, out, options) {
     const frameworkRel = rel(framework.root, framework.file);
     for (const problem of framework.problems) {
@@ -123,44 +147,79 @@ function checkFramework(framework, out, options) {
     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)`);
+            out.warn('version-behind', frameworkRel, `targets Eidos ${framework.eidosVersion}; this CLI carries ${options.standardVersion}: run \`eidos 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');
+        out.error('no-collections', frameworkRel, 'declares no collections; a framework needs at least one');
     }
-    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');
+    if (/^versions:/m.test(readFileSync(framework.file, 'utf8'))) {
+        out.warn('versions-legacy', frameworkRel, 'carries a versions key; since Eidos 5.0.0 a root\'s versions are a tool\'s own, and `eidos migrate` moves them to .eidos/plugins/eidosmd/versions.yaml');
     }
     for (const doc of framework.topLevel) {
-        if (isFileTarget(doc.path) && !linkExists(path.dirname(framework.file), doc.path)) {
+        if (!isFileTarget(doc.path)) {
+            continue;
+        }
+        if (!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`);
+            continue;
+        }
+        const file = path.resolve(path.dirname(framework.file), doc.path.split('#')[0] ?? '');
+        if (file.startsWith(framework.root + path.sep) && /\.md$/i.test(file)) {
+            checkRegions(readFileSync(file, 'utf8'), rel(framework.root, file), out);
         }
     }
-    const shapes = new Map();
+    // A collection's templates are named for its unit, `<unit>.<variant>.md`;
+    // a file named otherwise is faulted, as is one that opens with frontmatter.
+    const templates = 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`);
+        const unit = unitOf(collection);
+        for (const variant of collection.variants) {
+            const template = loadTemplate(framework, variant);
+            templates.set(`${collection.name}/${variant.name}`, template);
+            if (template?.frontmatter) {
+                out.error('template-frontmatter', rel(framework.root, template.path), 'carries a frontmatter block; a template is body only, its frontmatter is generated from the Properties table', 'Remove the block');
+            }
+            if (template) {
+                checkRegions(template.text, rel(framework.root, template.path), out);
+            }
+            if (!template) {
+                out.error('template-missing', frameworkRel, `${collection.name}/${variant.name} points at .eidos/${variant.template}, which does not exist`);
+            }
+            const expected = unit ? `${unit}.${variant.name}.md` : null;
+            if (expected && !variant.template.endsWith(`/${expected}`) && variant.template !== expected) {
+                out.error('template-name', frameworkRel, `${collection.name}/${variant.name} is at .eidos/${variant.template}; a template file is templates/${expected} (its unit, then its variant)`);
             }
         }
         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;
+    for (const folder of framework.folders) {
+        if (!isCollection(folder) && !existsSync(path.join(framework.root, folder.name))) {
+            out.warn('folder-missing', null, `${folder.name} is declared as ${folder.type === 'assets' ? 'an assets' : 'an other'} folder but has no folder`);
+        }
+    }
+    return templates;
 }
-function checkLayout(framework, blueprints, out) {
-    const declared = new Set(framework.collections.map((collection) => collection.name));
-    const embedded = embeddedIndexOf(readFileSync(framework.file, 'utf8'));
+// Rule 21: what sits at the root that the framework document does not
+// declare. A folder is `.eidos/` or one under `folders`; a file is one under
+// `top_level`. Hidden entries are the host's and exempt.
+export function undeclaredAtRoot(framework) {
+    const declaredFolders = new Set(framework.folders.map((folder) => folder.name));
+    const declaredFiles = new Set();
+    for (const doc of framework.topLevel) {
+        if (!isFileTarget(doc.path))
+            continue;
+        const file = path.resolve(path.dirname(framework.file), doc.path.split('#')[0] ?? '');
+        if (path.dirname(file) === framework.root)
+            declaredFiles.add(path.basename(file));
+    }
+    const folders = [];
+    const files = [];
     let entries = [];
     try {
         entries = readdirSync(framework.root);
@@ -169,19 +228,30 @@ function checkLayout(framework, blueprints, out) {
         entries = [];
     }
     for (const entry of entries.sort()) {
-        if (entry.startsWith('.') || entry === '_eidos' || SKIPPED_DIRS.has(entry) || declared.has(entry)) {
+        if (entry.startsWith('.') || SKIPPED_DIRS.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');
+            continue;
         }
+        if (isDir && !declaredFolders.has(entry))
+            folders.push(entry);
+        else if (!isDir && !declaredFiles.has(entry))
+            files.push(entry);
+    }
+    return { folders, files };
+}
+function checkLayout(framework, blueprints, out) {
+    const embedded = embeddedIndexOf(readFileSync(framework.file, 'utf8'));
+    const undeclared = undeclaredAtRoot(framework);
+    for (const entry of undeclared.folders) {
+        out.warn('folder-undeclared', entry, 'a folder at the root the framework document does not declare; declare it under folders (a collection, assets, or other) or move it');
+    }
+    for (const entry of undeclared.files) {
+        out.warn('file-undeclared', entry, 'a file at the root that top_level does not list; declare it (`eidos configure:doc add`) or move it');
     }
     for (const collection of framework.collections) {
         const folder = path.join(framework.root, collection.name);
@@ -190,13 +260,21 @@ function checkLayout(framework, blueprints, out) {
         }
         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`);
-                }
+        // Rule 10: a collection is flat or grouped; every sub-folder is a declared
+        // group, and a group holds blueprints and nothing deeper.
+        const declaredGroups = new Map((collection.grouping?.groups ?? []).map((group) => [group.name.toLowerCase(), group.name]));
+        for (const group of groupDirs(folder)) {
+            if (!collection.grouping) {
+                out.warn('group-undeclared', `${collection.name}/${group}`, `a sub-folder of ${collection.name}, which declares no grouping; declare a grouping and the group, or move it`);
             }
+            else if (!declaredGroups.has(group.toLowerCase())) {
+                out.warn('group-undeclared', `${collection.name}/${group}`, `not declared under ${collection.grouping.label} in the framework document`);
+            }
+            for (const nested of groupDirs(path.join(folder, group))) {
+                out.warn('folder-nested', `${collection.name}/${group}/${nested}`, 'a folder inside a group; a group holds blueprints and nothing deeper');
+            }
+        }
+        if (collection.grouping) {
             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`);
@@ -209,10 +287,10 @@ function checkLayout(framework, blueprints, out) {
             }
         }
         if (collection.framing) {
-            for (const flavor of collection.flavors) {
-                const written = own.some((blueprint) => resolveFlavor(blueprint).flavor === flavor);
+            for (const variant of collection.variants) {
+                const written = own.some((blueprint) => resolveVariant(blueprint).variant === variant);
                 if (!written) {
-                    out.warn('frame-unwritten', collection.name, `no ${flavor.name} frame yet; a gap to surface, not a failure`);
+                    out.warn('frame-unwritten', collection.name, `no ${variant.name} frame yet; a gap to surface, not a failure`);
                 }
             }
         }
@@ -223,7 +301,25 @@ function checkLayout(framework, blueprints, out) {
         }
     }
 }
-function checkBlueprint(framework, blueprint, shapes, out) {
+// Rule 19: a near-miss the Vocabulary names is flagged with the declared term
+// beside it, never refused. The near-miss is the clause's opening phrase.
+function checkVocabulary(framework, blueprint, out) {
+    if (framework.vocabulary.length === 0 || blueprint.body.trim() === '')
+        return;
+    const body = stripRegions(blueprint.body).toLowerCase();
+    for (const entry of framework.vocabulary) {
+        for (const clause of entry.not) {
+            const phrase = clause.split(/[,;:(]/)[0]?.trim().toLowerCase() ?? '';
+            if (phrase === '' || phrase === entry.term.toLowerCase())
+                continue;
+            const pattern = new RegExp(`(^|[^a-z0-9])${phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![a-z0-9])`, 'i');
+            if (pattern.test(body)) {
+                out.warn('term-near-miss', blueprint.rel, `uses "${phrase}"; the Vocabulary declares "${entry.term}"${entry.means ? ` (${entry.means})` : ''}`);
+            }
+        }
+    }
+}
+function checkBlueprint(framework, blueprint, templates, out) {
     const file = blueprint.rel;
     if (blueprint.properties === null) {
         if (blueprint.frontmatterError) {
@@ -241,13 +337,7 @@ function checkBlueprint(framework, blueprint, shapes, out) {
     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`);
+        out.error('id-missing', file, 'no `id`; add a permanent identity (a slug, a number, a GUID)');
     }
     if (propertyString(blueprint, 'title') === null) {
         out.error('title-missing', file, 'no `title`');
@@ -255,27 +345,30 @@ function checkBlueprint(framework, blueprint, shapes, out) {
     if (propertyString(blueprint, 'summary') === null) {
         out.warn('summary-missing', file, 'no `summary`; the collection index will flag it');
     }
-    const { flavor, declared, known } = resolveFlavor(blueprint);
+    const { variant, declared, known } = resolveVariant(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 names = collection.variants.map((candidate) => candidate.name).join(', ');
+        out.error('variant-unknown', file, `variant '${declared ?? ''}' is not one of ${collection.name}'s declared variants (${names})`);
     }
     const core = new Set(framework.schema.core.map((property) => property.name));
-    const applicable = framework.schema.custom.filter((property) => appliesTo(property, collection.name));
+    const schemaProperties = [...framework.schema.custom, ...Object.values(framework.schema.tools).flat()];
+    const applicable = schemaProperties.filter((property) => appliesTo(property, collection.name));
     const applicableNames = new Set(applicable.map((property) => property.name));
-    for (const property of applicable) {
+    // Rule 4: a required property absent or blank is a gap to surface; an
+    // optional one absent is nothing, and present it is checked only by type.
+    for (const property of applicable.filter((candidate) => candidate.required)) {
         if (!(property.name in properties)) {
-            out.warn('property-missing', file, `no \`${property.name}\` (${property.type}, applies to ${collection.name})`);
+            out.warn('property-missing', file, `no \`${property.name}\` (${property.type}, required, applies to ${collection.name})`);
         }
         else if (isEmpty(properties[property.name]) && property.type.toLowerCase() !== 'list') {
-            out.warn('property-empty', file, `\`${property.name}\` has no value`);
+            out.warn('property-empty', file, `\`${property.name}\` is required but 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);
+        const elsewhere = schemaProperties.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}`);
@@ -284,7 +377,7 @@ function checkBlueprint(framework, blueprint, shapes, out) {
             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`);
+            out.warn('property-unknown', file, `\`${key}\` is in no block of the Properties table; declare it among the custom properties or drop it`);
         }
     }
     for (const property of [...framework.schema.core, ...applicable]) {
@@ -294,6 +387,11 @@ function checkBlueprint(framework, blueprint, shapes, out) {
         const problem = typeProblem(property, properties[property.name]);
         if (problem) {
             out.warn('property-type', file, `\`${property.name}\` (${property.type}): ${problem}`);
+            continue;
+        }
+        const offList = optionProblem(property, properties[property.name]);
+        if (offList) {
+            out.warn('property-option', file, `\`${property.name}: ${offList.off.join(', ')}\` is not one of its options (${offList.options.join(', ')})`);
         }
     }
     if (collection.grouping?.property) {
@@ -313,8 +411,9 @@ function checkBlueprint(framework, blueprint, shapes, out) {
             }
         }
     }
+    checkRegions(blueprint.body, file, out);
     const brokenInBody = new Map();
-    for (const target of linkTargets(blueprint.body)) {
+    for (const target of linkTargets(stripRegions(blueprint.body))) {
         if (isFileTarget(target) && !linkExists(dir, target)) {
             brokenInBody.set(target, (brokenInBody.get(target) ?? 0) + 1);
         }
@@ -327,38 +426,89 @@ function checkBlueprint(framework, blueprint, shapes, out) {
     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) {
+    const template = variant ? (templates.get(`${collection.name}/${variant.name}`) ?? loadTemplate(framework, variant)) : null;
+    if (!template || !variant) {
         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) {
+    const templateLower = template.sections.map((text) => text.toLowerCase());
+    for (const name of template.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)`);
+            out.warn('section-missing', file, `no \`## ${name}\` (${variant.unit}.${variant.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`);
+            if (!templateLower.includes(name.toLowerCase())) {
+                out.warn('section-unknown', file, `\`## ${name}\` is not a section of ${variant.unit}.${variant.name}; nest it under one that is, or add it to the template`);
             }
         }
     }
-    const order = presentLower.filter((name) => shapeLower.includes(name)).map((name) => shapeLower.indexOf(name));
+    const order = presentLower.filter((name) => templateLower.includes(name)).map((name) => templateLower.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(' → ')})`);
+            out.warn('section-order', file, `sections are not in ${variant.unit}.${variant.name}'s order (${template.sections.join(' → ')})`);
             break;
         }
     }
 }
+function checkCanvases(framework, blueprints, out) {
+    const ids = new Set(blueprints.map((blueprint) => blueprintId(blueprint)).filter((id) => id !== null));
+    const canvases = listCanvases(framework);
+    const canvasIds = new Set(canvases.map((canvas) => canvas.id));
+    for (const canvas of canvases) {
+        const file = rel(framework.root, canvas.file);
+        for (const problem of canvas.problems) {
+            out.error('canvas-invalid', file, problem);
+        }
+        for (const page of canvas.pages) {
+            const nodeIds = new Set(page.nodes.map((node) => node.id));
+            const frameIds = new Set(page.frames.map((frame) => frame.id));
+            for (const node of page.nodes) {
+                if (node.blueprint && !ids.has(node.blueprint)) {
+                    out.error('canvas-node-missing', file, `page ${page.id}, node ${node.id}: no blueprint with id '${node.blueprint}'`);
+                }
+                if (node.frame && !frameIds.has(node.frame)) {
+                    out.warn('canvas-frame-missing', file, `page ${page.id}, node ${node.id}: no frame '${node.frame}' on this page`);
+                }
+                if (node.link?.page && !canvas.pages.some((candidate) => candidate.id === node.link?.page)) {
+                    out.error('canvas-link-missing', file, `page ${page.id}, node ${node.id}: links to page '${node.link.page}', which this canvas does not have`);
+                }
+                if (node.link?.canvas && !canvasIds.has(node.link.canvas)) {
+                    out.error('canvas-link-missing', file, `page ${page.id}, node ${node.id}: links to canvas '${node.link.canvas}', which does not exist`);
+                }
+            }
+            for (const comment of page.comments) {
+                if (comment.node && !page.nodes.some((node) => node.id === comment.node)) {
+                    out.warn('canvas-comment-orphan', file, `page ${page.id}, comment ${comment.id}: pinned to node '${comment.node}', which the page no longer has`);
+                }
+            }
+            const endpoint = (id) => (isFrameRef(id) ? frameIds.has(id.slice(FRAME_REF.length)) : nodeIds.has(id));
+            for (const edge of page.edges) {
+                if (!endpoint(edge.from) || !endpoint(edge.to)) {
+                    out.error('canvas-edge-missing', file, `page ${page.id}: edge ${edge.from} → ${edge.to} names a node or frame the page does not have`);
+                }
+            }
+            for (const node of page.nodes) {
+                if (node.annotation && !page.edges.some((edge) => edge.from === node.id)) {
+                    out.warn('canvas-annotation-unpointed', file, `page ${page.id}, annotation ${node.id}: points at nothing; an annotation exists to point`);
+                }
+            }
+            for (const frame of page.frames) {
+                if (frame.frame && !frameIds.has(frame.frame)) {
+                    out.warn('canvas-frame-missing', file, `page ${page.id}, frame ${frame.id}: attached to frame '${frame.frame}', which the page does not have`);
+                }
+            }
+        }
+    }
+}
 export function checkRoot(framework, blueprints, options) {
     const out = new Collector();
-    const shapes = checkFramework(framework, out, options);
+    const templates = checkFramework(framework, out, options);
     if (!options.only) {
         checkLayout(framework, blueprints, out);
+        checkCanvases(framework, blueprints, out);
     }
     const seen = new Map();
     for (const blueprint of blueprints) {
@@ -381,7 +531,8 @@ export function checkRoot(framework, blueprints, options) {
     }
     const targets = options.only ? blueprints.filter((blueprint) => options.only?.has(blueprint.path)) : blueprints;
     for (const blueprint of targets) {
-        checkBlueprint(framework, blueprint, shapes, out);
+        checkBlueprint(framework, blueprint, templates, out);
+        checkVocabulary(framework, blueprint, out);
     }
     const findings = out.findings.sort((a, b) => {
         const left = a.path ?? '';

package/dist/src/core/convert.js

@@ -1,8 +1,9 @@
-// Converting a markdown root to the form the CLI works in: the same framework
-// written as `Framework.yaml` with the guidance as comments and the index
-// inside it, `Framework.md` and each collection's `index.md` removed. The
-// markdown form's prose (section intros, HTML comments) has no field to land
-// in and is left behind; each collection's own description travels.
+// Converting a 4.x markdown root to Framework.yaml, the framework document
+// since 5.0.0: the same framework written as data with this CLI's guidance
+// as comments and the index inside it, `Framework.md` and each collection's
+// `index.md` removed. `migrate` runs this on the way up. The markdown form's
+// prose (section intros, HTML comments) has no field to land in and is left
+// behind; each collection's own description travels.
 import { existsSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { listBlueprints } from './blueprint.js';
@@ -10,7 +11,7 @@ import { loadFramework } from './framework.js';
 import { frameworkToDocument, serializeDocument } from './framework-structured.js';
 import { buildIndexes } from './index-leaf.js';
 export function convertToYaml(framework, dryRun) {
-    const yamlFile = path.join(framework.root, '_eidos', 'Framework.yaml');
+    const yamlFile = path.join(framework.root, '.eidos', 'Framework.yaml');
     const actions = [];
     const removed = [];
     const text = serializeDocument(frameworkToDocument(framework));