eidosmd 0.2.0 → 0.3.1

package/dist/src/core/canvas.js

@@ -9,7 +9,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import path from 'node:path';
 import { parse as parseYaml, Document } from 'yaml';
 import { blueprintId, blueprintTitle, propertyString } from './blueprint.js';
-import { FRAMEWORK_DIR, PLUGINS_DIR, TOOL_KEY } from './framework-model.js';
+import { FRAMEWORK_DIR, PLUGINS_DIR, readValueStyle, TOOL_KEY } from './framework-model.js';
 import { kebab } from './naming.js';
 // Relative to `.eidos/`: the folder the standard reserves for this tool.
 export const MAPS_DIR = `${PLUGINS_DIR}/${TOOL_KEY}/maps`;
@@ -119,22 +119,7 @@ export function readBox(value) {
         return null;
     return { w: Math.max(40, Math.round(value['w'])), h: Math.max(24, Math.round(value['h'])) };
 }
-export function readStyle(value) {
-    if (!isPlain(value))
-        return null;
-    const style = {};
-    if (text(value['shape']) !== '')
-        style.shape = text(value['shape']);
-    if (text(value['color']) !== '')
-        style.color = text(value['color']);
-    if (value['fill'] === 'solid' || value['fill'] === 'tint' || value['fill'] === 'none')
-        style.fill = value['fill'];
-    if (text(value['fill_color']) !== '')
-        style.fill_color = text(value['fill_color']);
-    if (value['size'] === 'small' || value['size'] === 'medium' || value['size'] === 'large')
-        style.size = value['size'];
-    return Object.keys(style).length > 0 ? style : null;
-}
+export const readStyle = readValueStyle;
 function readPage(value, index, problems) {
     const where = `pages[${index}]`;
     if (!isPlain(value) || text(value['id']) === '') {
@@ -393,44 +378,65 @@ export const NODE_WIDTH = 220;
 export function canvasProperties(framework) {
     return framework.schema.custom.filter((property) => property.canvas !== undefined);
 }
+// The style a property gives one value, matched without regard to case.
+export function valueStyle(hint, value) {
+    const key = Object.keys(hint.styles ?? {}).find((candidate) => candidate.toLowerCase() === value.toLowerCase());
+    return key ? (hint.styles?.[key] ?? null) : null;
+}
 // The default look a node's property values give it. Properties are read in
-// schema order and the top-most that names the value wins each of shape and
-// color, so the order of the custom block is the precedence.
+// schema order and, field by field, the top-most that sets it for the value
+// wins, so the order of the custom block is the precedence.
 export function styleFor(framework, values) {
-    let shape = null;
-    let color = null;
+    const found = {};
     const shown = [];
     for (const property of canvasProperties(framework)) {
         const value = values[property.name];
         if (value === undefined || value === '')
             continue;
-        const key = Object.keys(property.canvas.shape ?? {}).find((candidate) => candidate.toLowerCase() === value.toLowerCase());
-        if (shape === null && key && property.canvas.shape?.[key])
-            shape = property.canvas.shape[key];
-        const colorKey = Object.keys(property.canvas.color ?? {}).find((candidate) => candidate.toLowerCase() === value.toLowerCase());
-        if (color === null && colorKey && property.canvas.color?.[colorKey])
-            color = property.canvas.color[colorKey];
+        const style = valueStyle(property.canvas, value);
+        if (style) {
+            if (found.shape === undefined && style.shape)
+                found.shape = style.shape;
+            if (found.color === undefined && style.color)
+                found.color = style.color;
+            if (found.fill === undefined && style.fill)
+                found.fill = style.fill;
+            if (found.fill_color === undefined && style.fill_color)
+                found.fill_color = style.fill_color;
+            if (found.size === undefined && style.size)
+                found.size = style.size;
+        }
         if (property.canvas.show)
             shown.push({ property: property.name, value });
     }
-    return { shape: shape ?? 'box', color, shown };
+    return { ...withLegacyShape(found), shown };
 }
-// The override laid over the default: each of shape, color, fill, and size
-// the node sets itself, the rest from the properties. Shapes that were
-// really colors in earlier files (dark, accent, text) read as a box with
-// the fill they meant.
-function drawn(node, defaults) {
+// Shapes that were really colors in the first canvases (dark, accent, text)
+// read as a box with the fill they meant.
+function withLegacyShape(style) {
     const legacy = { dark: { fill: 'solid', fill_color: '#191b1f' }, accent: { fill: 'tint' }, text: { fill: 'none' } };
-    const chosen = node.style?.shape ?? defaults.shape;
-    const meant = legacy[chosen];
+    const meant = style.shape ? legacy[style.shape] : undefined;
     return {
-        shape: meant ? 'box' : chosen,
-        color: node.style?.color ?? defaults.color,
-        fill: node.style?.fill ?? meant?.fill ?? 'solid',
-        fill_color: node.style?.fill_color ?? meant?.fill_color ?? null,
-        size: node.style?.size ?? 'medium',
+        shape: meant ? 'box' : (style.shape ?? 'box'),
+        color: style.color ?? null,
+        fill: style.fill ?? meant?.fill ?? 'solid',
+        fill_color: style.fill_color ?? meant?.fill_color ?? null,
+        size: style.size ?? 'medium',
     };
 }
+// The override laid over the default: each field the node sets itself, the
+// rest from the properties.
+function drawn(node, defaults) {
+    const style = node.style ?? {};
+    const own = withLegacyShape({
+        shape: style.shape ?? defaults.shape,
+        ...(style.color ?? defaults.color ? { color: style.color ?? defaults.color ?? '' } : {}),
+        fill: style.fill ?? defaults.fill,
+        ...(style.fill_color ?? defaults.fill_color ? { fill_color: style.fill_color ?? defaults.fill_color ?? '' } : {}),
+        size: style.size ?? defaults.size,
+    });
+    return { shape: own.shape, color: own.color, fill: own.fill, fill_color: own.fill_color, size: own.size };
+}
 // A simple layered layout from the edges: a node's column is the longest path
 // from a source to it, its row its order within the column. Frames are drawn
 // around their members by the page. Overrides win.
@@ -520,7 +526,7 @@ export function renderPage(framework, blueprints, page) {
                 style: drawn(node, style),
                 font: null,
                 box: node.box ?? null,
-                defaults: { shape: style.shape, color: style.color },
+                defaults: { shape: style.shape, color: style.color, fill: style.fill, fill_color: style.fill_color, size: style.size },
                 override: node.style ?? null,
                 styled: node.styled === true,
                 shown: style.shown,
@@ -543,7 +549,7 @@ export function renderPage(framework, blueprints, page) {
                 style: { shape: 'text', color: node.style?.color ?? null, fill: 'none', fill_color: null, size: node.text.size ?? 'medium' },
                 font: node.text.font ?? null,
                 box: node.box ?? null,
-                defaults: { shape: 'text', color: null },
+                defaults: { shape: 'text', color: null, fill: 'solid', fill_color: null, size: 'medium' },
                 override: node.style ?? null,
                 styled: node.styled === true,
                 shown: [],
@@ -566,7 +572,7 @@ export function renderPage(framework, blueprints, page) {
                 style: { shape: 'annotation', color: node.annotation.color ?? null, fill: 'solid', fill_color: null, size: node.style?.size ?? 'medium' },
                 font: null,
                 box: node.box ?? null,
-                defaults: { shape: 'annotation', color: null },
+                defaults: { shape: 'annotation', color: null, fill: 'solid', fill_color: null, size: 'medium' },
                 override: node.style ?? null,
                 styled: node.styled === true,
                 shown: [],
@@ -589,7 +595,7 @@ export function renderPage(framework, blueprints, page) {
                 style: { shape: 'sticky', color: node.sticky.color ?? null, fill: 'solid', fill_color: null, size: node.style?.size ?? 'medium' },
                 font: null,
                 box: node.box ?? null,
-                defaults: { shape: 'sticky', color: null },
+                defaults: { shape: 'sticky', color: null, fill: 'solid', fill_color: null, size: 'medium' },
                 override: node.style ?? null,
                 styled: node.styled === true,
                 shown: [],
@@ -614,7 +620,7 @@ export function renderPage(framework, blueprints, page) {
             style: drawn(node, style),
             font: null,
             box: node.box ?? null,
-            defaults: { shape: style.shape, color: style.color },
+            defaults: { shape: style.shape, color: style.color, fill: style.fill, fill_color: style.fill_color, size: style.size },
             override: node.style ?? null,
             styled: node.styled === true,
             shown: style.shown,
@@ -627,8 +633,9 @@ export function renderPage(framework, blueprints, page) {
 // `kind` and `status` read as the first shape- and color-styled properties.
 export function sketchValues(framework, sketch) {
     const values = {};
-    const kindProperty = canvasProperties(framework).find((property) => property.canvas.shape);
-    const statusProperty = canvasProperties(framework).find((property) => property.canvas.color);
+    const styles = (property) => Object.values(property.canvas.styles ?? {});
+    const kindProperty = canvasProperties(framework).find((property) => styles(property).some((style) => style.shape));
+    const statusProperty = canvasProperties(framework).find((property) => styles(property).some((style) => style.color));
     if (sketch.kind && kindProperty)
         values[kindProperty.name] = sketch.kind;
     if (sketch.status && statusProperty)
@@ -702,14 +709,17 @@ export function toJsonCanvas(framework, blueprints, page) {
 }
 // --- the software seed's default palette, written by init --------------------
 // The legend the owner already uses, as values of the seed's own properties.
+const shaped = (shape) => ({ shape });
+const colored = (color) => ({ color });
 export const DEFAULT_CANVAS_HINTS = {
     type: {
         show: true,
-        shape: { page: 'pill', feature: 'box', capability: 'box', integration: 'box', background: 'box', module: 'box', decision: 'parallelogram', note: 'box' },
+        styles: { page: shaped('pill'), feature: shaped('box'), capability: shaped('box'), integration: shaped('box'), background: shaped('box'), module: shaped('box'), decision: shaped('parallelogram'), note: shaped('box') },
     },
     status: {
         show: true,
-        color: { Draft: '#6b665e', Intake: '#7a4a1f', 'In Progress': '#2f6fd0', Done: '#2f6b3a', Archived: '#8a8a8a', Deprecated: '#8a8a8a', 'needs-clarification': '#2f6fd0', maybe: '#b23a2a', visionary: '#1f7a5a' },
+        // the browser's standard colors (PALETTE in the canvas model), so a default and a hand-picked swatch never clash
+        styles: { Draft: colored('#8b9099'), Intake: colored('#d3a53c'), 'In Progress': colored('#5f80cf'), Done: colored('#7fae6c'), Archived: colored('#8b9099'), Deprecated: colored('#cf7b8f'), 'needs-clarification': colored('#5f80cf'), maybe: colored('#e08a63'), visionary: colored('#4aa39f') },
     },
 };
 export function applyDefaultCanvasHints(properties) {

package/dist/src/core/check.js

@@ -5,13 +5,14 @@
 // note and offer, never refuse.
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { blueprintId, blueprintTitle, propertyString, resolveVariant } from './blueprint.js';
-import { appliesTo, unitOf } 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 { 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']);
@@ -50,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) {
@@ -110,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) {
@@ -136,12 +159,17 @@ function checkFramework(framework, out, options) {
     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');
     }
-    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)) {
+        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);
         }
     }
     // A collection's templates are named for its unit, `<unit>.<variant>.md`;
@@ -155,6 +183,9 @@ function checkFramework(framework, out, options) {
             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`);
             }
@@ -167,11 +198,28 @@ function checkFramework(framework, out, options) {
             out.warn('collection-folder-missing', null, `collection ${collection.name} is declared but has no folder`);
         }
     }
+    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);
@@ -180,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 the framework document 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);
@@ -201,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 the framework document`);
-                }
+        // 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`);
@@ -239,7 +306,7 @@ function checkLayout(framework, blueprints, out) {
 function checkVocabulary(framework, blueprint, out) {
     if (framework.vocabulary.length === 0 || blueprint.body.trim() === '')
         return;
-    const body = blueprint.body.toLowerCase();
+    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() ?? '';
@@ -287,12 +354,14 @@ function checkBlueprint(framework, blueprint, templates, out) {
     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)) {
@@ -318,6 +387,11 @@ function checkBlueprint(framework, blueprint, templates, 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) {
@@ -337,8 +411,9 @@ function checkBlueprint(framework, blueprint, templates, 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);
         }