eidosmd 0.1.0 → 0.3.0

package/dist/src/core/framework-markdown.js

@@ -1,13 +1,15 @@
-// The markdown framework document, `_eidos/Framework.md`: frontmatter for the
+// The markdown framework document, `.eidos/Framework.md`: frontmatter for the
 // version and naming convention, and a body indexing the Top-Level docs, the
-// Collections (each a `###` with Leaf, Flavors, Canvas, and grouping bullets),
-// and the property Schema as two tables.
+// Collections (each a `###` with Leaf, Variants, and grouping bullets), the
+// Properties table per owner, the Vocabulary, and the Versions. The 4.x
+// spellings (Schema, Flavors, shape) still read, so `migrate` can load a root
+// it is about to move.
 import { parseFrontmatter } from './frontmatter.js';
-import { groupingProperty, STANDARD_CORE } from './framework-model.js';
+import { coreRequires, groupingProperty, STANDARD_CORE, unitOf } from './framework-model.js';
 import { DEFAULT_NAMING, isNaming } from './naming.js';
 import { section, sections, stripInlineCode } from './markdown.js';
 import path from 'node:path';
-const DECLARED_BULLETS = new Set(['leaf', 'flavors', 'canvas']);
+const DECLARED_BULLETS = new Set(['leaf', 'unit', 'variants', 'flavors', 'canvas']);
 function cleanText(text) {
     return text.replace(/^_+|_+$/g, '').trim();
 }
@@ -46,13 +48,13 @@ function parseCanvas(value) {
     }
     return { mode: 'card', section: null };
 }
-function flavorFromShape(label, shapeRel) {
-    const file = path.posix.basename(shapeRel.replace(/\\/g, '/')).replace(/\.md$/i, '');
+function variantFromTemplate(label, templateRel) {
+    const file = path.posix.basename(templateRel.replace(/\\/g, '/')).replace(/\.md$/i, '');
     const dot = file.indexOf('.');
-    const kind = dot === -1 ? file : file.slice(0, dot);
+    const unit = dot === -1 ? file : file.slice(0, dot);
     const fromFile = dot === -1 ? file : file.slice(dot + 1);
     const name = /\.md$/i.test(label) ? fromFile : label;
-    return { name, kind };
+    return { name, unit };
 }
 function parseCollections(body) {
     const block = section(body, 2, 'Collections');
@@ -62,22 +64,23 @@ function parseCollections(body) {
     const out = [];
     for (const { heading, body: text } of sections(block, 3)) {
         const collection = {
+            type: 'collection',
             name: heading.text,
             description: firstParagraph(text),
-            framing: out.length === 0,
+            framing: false,
             leaf: null,
-            flavors: [],
+            variants: [],
             canvas: null,
             grouping: null,
         };
-        let inFlavors = false;
+        let inVariants = false;
         let inGrouping = false;
         for (const line of text.split('\n')) {
             const bullet = /^-\s+\*\*(.+?):\*\*\s*(.*)$/.exec(line);
             if (bullet && bullet[1] !== undefined) {
                 const label = bullet[1].trim();
                 const rest = (bullet[2] ?? '').trim();
-                inFlavors = label.toLowerCase() === 'flavors';
+                inVariants = label.toLowerCase() === 'variants' || label.toLowerCase() === 'flavors';
                 inGrouping = false;
                 if (label.toLowerCase() === 'leaf') {
                     collection.leaf = parseLink(rest)?.target ?? null;
@@ -96,18 +99,18 @@ function parseCollections(body) {
                 continue;
             }
             const item = nested[1].trim();
-            if (inFlavors) {
-                const flavorLine = /^\[(.+?)\]\((.+?)\)\s*(?:—\s*(.*))?$/.exec(item);
-                if (flavorLine && flavorLine[1] && flavorLine[2]) {
-                    // `(default)` in the description marks the default flavor; it is a flag, not prose.
-                    const described = (flavorLine[3] ?? '').trim();
+            if (inVariants) {
+                const variantLine = /^\[(.+?)\]\((.+?)\)\s*(?:—\s*(.*))?$/.exec(item);
+                if (variantLine && variantLine[1] && variantLine[2]) {
+                    // `(default)` in the description marks the default variant; it is a flag, not prose.
+                    const described = (variantLine[3] ?? '').trim();
                     const isDefault = /\(default\)/i.test(described);
                     const description = described.replace(/\s*\(default\)\.?$/i, '').replace(/\s*\(default\)/i, '').trim();
-                    const { name, kind } = flavorFromShape(flavorLine[1].trim(), flavorLine[2].trim());
-                    collection.flavors.push({
+                    const { name, unit } = variantFromTemplate(variantLine[1].trim(), variantLine[2].trim());
+                    collection.variants.push({
                         name,
-                        kind,
-                        shape: flavorLine[2].trim(),
+                        unit,
+                        template: variantLine[2].trim(),
                         description,
                         isDefault,
                     });
@@ -120,12 +123,13 @@ function parseCollections(body) {
                 }
             }
         }
-        if (collection.flavors.length > 0 && !collection.flavors.some((flavor) => flavor.isDefault)) {
-            const first = collection.flavors[0];
+        if (collection.variants.length > 0 && !collection.variants.some((variant) => variant.isDefault)) {
+            const first = collection.variants[0];
             if (first) {
                 first.isDefault = true;
             }
         }
+        collection.framing = unitOf(collection) === 'frame';
         out.push(collection);
     }
     return out;
@@ -152,23 +156,89 @@ function parseAppliesTo(value) {
     }
     return plain.split(/[,/]/).map((name) => name.trim()).filter((name) => name !== '');
 }
-function parseProperties(block, core) {
+// The standard's columns come first (Name, Type, Meaning for the core; Name,
+// Type, Applies To, Meaning for custom properties); any column past them is a
+// tool's, headed with the tool's name, and rides along as that tool's field.
+function parseProperties(block, core, owner = core ? 'eidos' : 'custom') {
     if (block === null) {
         return [];
     }
     const out = [];
+    const standard = core ? 3 : 4;
+    let header = [];
     for (const cells of parseTable(block)) {
         const name = stripInlineCode(cells[0] ?? '').trim();
-        if (name === '' || name.toLowerCase() === 'name') {
+        if (name === '') {
+            continue;
+        }
+        if (name.toLowerCase() === 'name') {
+            header = cells.map((cell) => stripInlineCode(cell).trim());
             continue;
         }
         const type = (cells[1] ?? 'Text').trim();
-        if (core || cells.length < 4) {
-            out.push({ name, type, appliesTo: 'all', meaning: (cells[cells.length - 1] ?? '').trim(), core });
+        // the 4.x table had no Required column: the core requires what the
+        // standard says it does, and every other property is optional
+        const required = core && coreRequires(name);
+        const property = core || cells.length < 4
+            ? { name, type, appliesTo: 'all', required, meaning: (cells[Math.min(cells.length, standard) - 1] ?? '').trim(), core, owner }
+            : { name, type, appliesTo: parseAppliesTo(cells[2] ?? ''), required, meaning: (cells[3] ?? '').trim(), core, owner };
+        const tools = {};
+        for (let index = standard; index < cells.length; index += 1) {
+            const tool = header[index];
+            const cell = (cells[index] ?? '').trim();
+            if (tool && cell !== '') {
+                tools[tool] = cell;
+            }
         }
-        else {
-            out.push({ name, type, appliesTo: parseAppliesTo(cells[2] ?? ''), meaning: (cells[3] ?? '').trim(), core });
+        if (Object.keys(tools).length > 0) {
+            property.tools = tools;
         }
+        out.push(property);
+    }
+    return out;
+}
+// `## Vocabulary`: Term · Means · Not, one row per term. A Term cell may be a
+// link to the blueprint that defines it; the Not cell lists near-misses, `;` apart.
+function parseVocabulary(body) {
+    const block = section(body, 2, 'Vocabulary');
+    if (block === null)
+        return [];
+    const out = [];
+    for (const row of parseTable(block)) {
+        const [termCell = '', means = '', notCell = ''] = row;
+        const link = parseLink(termCell.trim());
+        const term = (link ? link.title : stripInlineCode(termCell.replace(/\*\*/g, ''))).trim();
+        // the header row, a placeholder row, and a blank row are not terms
+        if (term === '' || term.toLowerCase() === 'term' || /^<.*>$/.test(term) || /^-+$/.test(term))
+            continue;
+        out.push({
+            term,
+            means: cleanText(means),
+            not: notCell
+                .split(';')
+                .map((entry) => cleanText(entry))
+                .filter((entry) => entry !== ''),
+            see: link ? link.target : null,
+        });
+    }
+    return out;
+}
+// `## Versions`: Version · Commit · Tag, newest first, as written. The key
+// left the standard in 5.0.0; `migrate` moves what a 4.x root recorded.
+export function parseVersions(body) {
+    const block = section(body, 2, 'Versions');
+    if (block === null) {
+        return [];
+    }
+    const out = [];
+    for (const cells of parseTable(block)) {
+        const version = stripInlineCode(cells[0] ?? '').replace(/^\*\*|\*\*$/g, '').trim();
+        if (version === '' || version.toLowerCase() === 'version') {
+            continue;
+        }
+        const commit = stripInlineCode(cells[1] ?? '').trim();
+        const tag = stripInlineCode(cells[2] ?? '').trim();
+        out.push({ version, commit, tag: tag === '' || tag === '—' || tag === '-' ? null : tag });
     }
     return out;
 }
@@ -207,11 +277,23 @@ export function parseFrameworkMarkdown(text, root, file) {
         }
     }
     const version = properties?.['eidos_version'];
-    const schemaBlock = section(body, 2, 'Schema') ?? '';
-    const coreBlock = section(schemaBlock, 3, 'Eidos Core');
-    const customBlock = section(schemaBlock, 3, 'Custom Properties');
+    const schemaBlock = section(body, 2, 'Properties') ?? section(body, 2, 'Schema') ?? '';
+    const coreBlock = section(schemaBlock, 3, 'Eidos') ?? section(schemaBlock, 3, 'Eidos Core');
+    const customBlock = section(schemaBlock, 3, 'Custom') ?? section(schemaBlock, 3, 'Custom Properties');
     const core = parseProperties(coreBlock, true);
     const custom = parseProperties(customBlock, false);
+    // `### <tool>` (`### <tool> Properties` before 5.0.0): a block a tool declared and alone writes.
+    const tools = {};
+    for (const { heading, body: block } of sections(schemaBlock, 3)) {
+        const name = heading.text.trim();
+        if (/^(eidos( core)?|custom( properties)?)$/i.test(name))
+            continue;
+        const match = /^(.+?)(?:\s+Properties)?$/i.exec(name);
+        const tool = match?.[1]?.trim() ?? '';
+        if (!match || tool === '' || tool.toLowerCase() === 'custom' || /^<.*>$/.test(tool))
+            continue;
+        tools[tool] = parseProperties(block, false, tool);
+    }
     const collections = parseCollections(body);
     for (const collection of collections) {
         if (collection.grouping) {
@@ -226,8 +308,11 @@ export function parseFrameworkMarkdown(text, root, file) {
         naming,
         namingError,
         topLevel: parseTopLevel(body),
+        // the markdown form predates folder types: every folder it declares is a collection
+        folders: collections,
         collections,
-        schema: { core: core.length > 0 ? core : STANDARD_CORE, custom },
+        schema: { core: core.length > 0 ? core : STANDARD_CORE, custom, tools },
+        vocabulary: parseVocabulary(body),
         problems: [],
     };
 }

package/dist/src/core/framework-model.js

@@ -1,9 +1,15 @@
 // The framework model: everything a framework document declares, whichever
-// of `_eidos/Framework.md`, `.yaml`, or `.json` it is. The version and naming
-// convention, the Top-Level docs, the Collections (each with flavors, canvas
-// style, and grouping), and the property Schema.
+// of `.eidos/Framework.md` or `.yaml` it is. The version and naming
+// convention, the Top-Level docs, the Folders (every folder at the root with
+// its type; a collection carries its variants and grouping), the Properties
+// table (`schema` here, `properties` on disk), and the Vocabulary.
 import { kebab } from './naming.js';
-export const FRAMEWORK_DIR = '_eidos';
+export const FRAMEWORK_DIR = '.eidos';
+// This tool's name, as the standard has a tool sign what it keeps in a
+// framework: its folder under `.eidos/plugins/<name>/`, and its fields on a
+// Properties row (a key on the YAML entry, a column in the markdown table).
+export const TOOL_KEY = 'eidosmd';
+export const PLUGINS_DIR = 'plugins';
 export function isFrameworkFormat(value) {
     return value === 'md' || value === 'yaml';
 }
@@ -13,20 +19,66 @@ export const FRAMEWORK_FILES = [
     { name: 'Framework.yml', format: 'yaml' },
 ];
 export const PROPERTY_TYPES = ['Text', 'List', 'Number', 'Checkbox', 'Date', 'Date & time'];
+export function readValueStyle(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const given = value;
+    const text = (field) => (typeof field === 'string' || typeof field === 'number' ? String(field).trim() : '');
+    const style = {};
+    if (text(given['shape']) !== '')
+        style.shape = text(given['shape']);
+    if (text(given['color']) !== '')
+        style.color = text(given['color']);
+    if (given['fill'] === 'solid' || given['fill'] === 'tint' || given['fill'] === 'none')
+        style.fill = given['fill'];
+    if (text(given['fill_color']) !== '')
+        style.fill_color = text(given['fill_color']);
+    if (given['size'] === 'small' || given['size'] === 'medium' || given['size'] === 'large')
+        style.size = given['size'];
+    return Object.keys(style).length > 0 ? style : null;
+}
+// Every folder at the root is declared with one of the standard's three
+// types (Eidos 5.3.0): a collection holds blueprints; an assets folder holds
+// files that are not markdown; an other folder is whatever its description
+// says. The standard reads nothing inside the last two.
+export const FOLDER_TYPES = ['collection', 'assets', 'other'];
+export function isFolderType(value) {
+    return typeof value === 'string' && FOLDER_TYPES.includes(value);
+}
+export function isCollection(folder) {
+    return folder.type === 'collection';
+}
+// The unit a collection speaks in, the word for one of its blueprints: what
+// its template files are named for (`<unit>.<variant>.md`), read off the
+// default variant. A collection whose unit is `frame` is the framing one, this
+// CLI's recommendation for every product; the standard names no collection.
+export function unitOf(collection) {
+    const variant = collection.variants.find((entry) => entry.isDefault) ?? collection.variants[0];
+    return variant && variant.unit !== '' ? variant.unit : null;
+}
 export class FrameworkError extends Error {
     constructor(message) {
         super(message);
         this.name = 'FrameworkError';
     }
 }
-// The standard's own five, used when a Framework.md carries no core block.
+// The standard's own four (Eidos 5.3.0), two of them required, used when a
+// framework document carries no core block.
 export const STANDARD_CORE = [
-    { name: 'id', type: 'Text', appliesTo: 'all', meaning: 'Stable, unique, kebab-case identity. Assigned once, never renamed.', core: true },
-    { name: 'title', type: 'Text', appliesTo: 'all', meaning: 'Human-readable name.', core: true },
-    { name: 'summary', type: 'Text', appliesTo: 'all', meaning: 'One plain line: what this blueprint is. The source for the collection index.', core: true },
-    { name: 'flavor', type: 'Text', appliesTo: 'all', meaning: 'Which flavor this blueprint follows. Absent = the collection default.', core: true },
-    { name: 'connects_to', type: 'List', appliesTo: 'all', meaning: 'Blueprints this one connects to on the canvas, each a link.', core: true },
+    { name: 'id', type: 'Text', appliesTo: 'all', required: true, meaning: 'Stable, unique identity, in any form. Assigned once, never changed.', core: true, owner: 'eidos' },
+    { name: 'title', type: 'Text', appliesTo: 'all', required: true, meaning: 'Human-readable name.', core: true, owner: 'eidos' },
+    { name: 'summary', type: 'Text', appliesTo: 'all', required: false, meaning: 'One line: what this blueprint is. Feeds the index; absent, the index flags it.', core: true, owner: 'eidos' },
+    { name: 'variant', type: 'Text', appliesTo: 'all', required: false, meaning: "Which variant this blueprint follows. Absent = the collection's default.", core: true, owner: 'eidos' },
 ];
+// Whether the standard's core requires a property of this name: what an
+// absent `required` on a core row means, since the block is the standard's.
+export function coreRequires(name) {
+    return STANDARD_CORE.some((property) => property.name === name && property.required);
+}
+// Every property of the Properties table, whichever block owns it, core first.
+export function allProperties(schema) {
+    return [...schema.core, ...schema.custom, ...Object.values(schema.tools).flat()];
+}
 // `Domains` -> `domain`: the custom property that carries a collection's group,
 // matched by the grouping label's singular against the properties scoped to it.
 export function groupingProperty(collection, custom) {