eidosmd 0.1.0 → 0.3.0

package/dist/src/core/scaffold.js

@@ -1,13 +1,15 @@
-// Scaffolding one blueprint: frontmatter generated from the properties that
-// apply to its collection, body rendered from its flavor's shape, filename in
-// the framework's convention with a permanent kebab-case id inside. Born
+// Scaffolding one blueprint: frontmatter generated from the required
+// properties that apply to its collection plus any optional one given a
+// value, body rendered from its variant's template, filename in the
+// framework's convention with a permanent kebab-case id inside. Born
 // conforming; the prose is still the owner's.
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { blueprintId } from './blueprint.js';
-import { defaultFlavor, findCollection, findFlavor, propertiesFor } from './framework.js';
-import { convert, isKebab, kebab } from './naming.js';
-import { loadShape } from './shape.js';
+import { optionProblem } from './check.js';
+import { defaultVariant, findCollection, findVariant, propertiesFor } from './framework.js';
+import { convert, kebab } from './naming.js';
+import { loadTemplate } from './template.js';
 import { blankBlueprint } from './seed.js';
 export class ScaffoldError extends Error {
     constructor(message) {
@@ -15,7 +17,8 @@ export class ScaffoldError extends Error {
         this.name = 'ScaffoldError';
     }
 }
-function coerce(type, raw) {
+// A value typed on a command line, as the property's declared type holds it.
+export function coerce(type, raw) {
     switch (type.toLowerCase()) {
         case 'list':
             return raw
@@ -38,24 +41,24 @@ export function scaffoldBlueprint(framework, existing, options) {
         const known = framework.collections.map((candidate) => candidate.name).join(', ');
         throw new ScaffoldError(`no collection '${options.collection}' in this framework (declared: ${known})`);
     }
-    const flavor = options.flavor === null ? defaultFlavor(collection) : findFlavor(collection, options.flavor);
-    if (!flavor) {
-        const known = collection.flavors.map((candidate) => candidate.name).join(', ');
-        throw new ScaffoldError(options.flavor === null
-            ? `collection '${collection.name}' declares no flavors`
-            : `no flavor '${options.flavor}' in '${collection.name}' (declared: ${known})`);
+    const variant = options.variant === null ? defaultVariant(collection) : findVariant(collection, options.variant);
+    if (!variant) {
+        const known = collection.variants.map((candidate) => candidate.name).join(', ');
+        throw new ScaffoldError(options.variant === null
+            ? `collection '${collection.name}' declares no variants`
+            : `no variant '${options.variant}' in '${collection.name}' (declared: ${known})`);
     }
-    const shape = loadShape(framework, flavor);
+    const shape = loadTemplate(framework, variant);
     if (!shape) {
-        throw new ScaffoldError(`flavor '${flavor.name}' points at a shape that does not exist: _eidos/${flavor.shape}`);
+        throw new ScaffoldError(`variant '${variant.name}' points at a template that does not exist: .eidos/${variant.template}`);
     }
     const title = options.title.trim();
     if (title === '') {
         throw new ScaffoldError('a blueprint needs a title');
     }
     const id = options.id ?? kebab(title);
-    if (!isKebab(id)) {
-        throw new ScaffoldError(`id '${id}' is not kebab-case`);
+    if (/\s/.test(id)) {
+        throw new ScaffoldError(`id '${id}' has whitespace in it; an id is one token, in any form`);
     }
     const clash = existing.find((blueprint) => blueprintId(blueprint) === id);
     if (clash) {
@@ -67,7 +70,7 @@ export function scaffoldBlueprint(framework, existing, options) {
         const declared = collection.grouping?.groups.find((candidate) => candidate.name.toLowerCase() === options.group?.toLowerCase() || kebab(candidate.name) === kebab(options.group ?? ''));
         group = declared ? declared.name : convert(options.group, framework.naming);
         if (!declared && collection.grouping && collection.grouping.groups.length > 0) {
-            notes.push(`group '${group}' is not declared under ${collection.grouping.label} in Framework.md; add a bullet for it`);
+            notes.push(`group '${group}' is not declared under ${collection.grouping.label} in the framework document; add it there`);
         }
         if (!collection.grouping) {
             notes.push(`collection '${collection.name}' declares no grouping; the sub-folder alone groups this blueprint`);
@@ -83,23 +86,26 @@ export function scaffoldBlueprint(framework, existing, options) {
         id,
         title,
         summary: options.summary ?? '',
-        flavor: flavor.name,
-        status: 'Draft',
+        variant: variant.name,
         date_created: options.date,
         date_modified: options.date,
     };
     if (group !== null && collection.grouping?.property) {
         values[collection.grouping.property] = group;
     }
-    const types = new Map(propertiesFor(framework, collection.name).map((property) => [property.name, property.type]));
+    const declared = new Map(propertiesFor(framework, collection.name).map((property) => [property.name, property]));
+    const types = new Map([...declared].map(([name, property]) => [name, property.type]));
     for (const [key, raw] of Object.entries(options.set)) {
-        const type = types.get(key);
-        if (type === undefined) {
-            notes.push(`property '${key}' is not in the Schema for ${collection.name}; written anyway`);
+        const property = declared.get(key);
+        if (property === undefined) {
+            notes.push(`property '${key}' is not in the Properties table for ${collection.name}; written anyway`);
         }
-        values[key] = coerce(type ?? 'Text', raw);
+        values[key] = coerce(property?.type ?? 'Text', raw);
+        const offList = property ? optionProblem(property, values[key]) : null;
+        if (offList)
+            notes.push(`'${key}: ${offList.off.join(', ')}' is not one of its options (${offList.options.join(', ')}); written anyway, and check reports it`);
     }
-    let content = blankBlueprint(framework, collection.name, values, shape.template, title);
+    let content = blankBlueprint(framework, collection.name, values, shape.text, title);
     const extra = Object.keys(options.set).filter((key) => !types.has(key));
     if (extra.length > 0) {
         const lines = extra.map((key) => `${key}: ${String(values[key])}`).join('\n');
@@ -110,7 +116,7 @@ export function scaffoldBlueprint(framework, existing, options) {
         rel: path.relative(framework.root, file).split(path.sep).join('/'),
         content,
         collection,
-        flavor,
+        variant,
         group,
         id,
         notes,

package/dist/src/core/seed.js

@@ -1,19 +1,21 @@
-// Installing a seed: copy a starting framework into a new root's `_eidos/`,
-// write it as Framework.yaml with its naming convention and starting groups,
-// scaffold a folder per collection, and drop one blank blueprint per framing
-// flavor.
+// Installing a seed: copy a starting framework into a new root's `.eidos/`,
+// set the naming convention, the starting groups, and the folder names in
+// its Framework.yaml (the seed's own comments kept), scaffold every declared
+// folder (a collection's with its groups, an assets folder empty), and drop
+// one blank blueprint per framing variant.
 // It writes no prose: the README's one-liner, each group's description, and
 // every scaffolded blueprint's summary and body stay the owner's.
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { formatFrontmatter } from './frontmatter.js';
 import { parseFramework, propertiesFor } from './framework.js';
-import { frameworkToDocument, serializeDocument } from './framework-structured.js';
 import { buildIndexes } from './index-leaf.js';
 import { listBlueprints } from './blueprint.js';
 import { convert, kebab, titleize } from './naming.js';
-import { renderShape } from './shape.js';
-const GROUP_PROMPT = '_(one line on what belongs here)_';
+import { renderTemplate } from './template.js';
+import { isCollection, TOOL_KEY } from './framework-model.js';
+import { DEFAULT_CANVAS_HINTS } from './canvas.js';
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
 const GITIGNORE_SHIPPED = '_gitignore';
 export function listSeeds(seedsDir) {
     if (!existsSync(seedsDir)) {
@@ -22,12 +24,12 @@ export function listSeeds(seedsDir) {
     return readdirSync(seedsDir)
         .sort()
         .map((name) => path.join(seedsDir, name))
-        .filter((dir) => existsSync(path.join(dir, 'Framework.md')))
+        .filter((dir) => existsSync(path.join(dir, 'Framework.yaml')))
         .map((dir) => ({ name: path.basename(dir), dir, framework: readSeedFramework(dir) }));
 }
 function readSeedFramework(dir) {
-    const file = path.join(dir, 'Framework.md');
-    return parseFramework(readFileSync(file, 'utf8'), 'md', dir, file);
+    const file = path.join(dir, 'Framework.yaml');
+    return parseFramework(readFileSync(file, 'utf8'), 'yaml', dir, file);
 }
 export class InstallError extends Error {
     constructor(message) {
@@ -73,105 +75,219 @@ class Writer {
         }
     }
 }
-function setNaming(text, naming) {
-    if (/^naming:.*$/m.test(text)) {
-        return text.replace(/^naming:.*$/m, `naming: ${naming}`);
+const mapsIn = (value) => (isSeq(value) ? value.items.filter((item) => isMap(item)) : []);
+const nameOf = (map) => String(map.get('name') ?? '');
+// The `folders` list as the seed wrote it (`collections` in a seed older than 5.3.0).
+const foldersOf = (document) => document.get('folders') ?? document.get('collections');
+// The seed's folders and the properties scoped to its collections, renamed
+// into the root's convention; every other key, and every comment, stays as
+// the seed wrote it.
+function renameFolders(document, renames) {
+    for (const folder of mapsIn(foldersOf(document))) {
+        const to = renames.get(nameOf(folder));
+        if (to !== undefined)
+            folder.set('name', to);
+    }
+    const properties = document.get('properties');
+    if (!isMap(properties))
+        return;
+    const blocks = [properties.get('custom'), ...(isMap(properties.get('tools')) ? properties.get('tools').items.map((pair) => pair.value) : [])];
+    for (const block of blocks) {
+        for (const property of mapsIn(block)) {
+            const applies = property.get('applies_to');
+            if (!isSeq(applies))
+                continue;
+            for (const item of applies.items) {
+                if (isScalar(item)) {
+                    const to = renames.get(String(item.value));
+                    if (to !== undefined)
+                        item.value = to;
+                }
+            }
+        }
     }
-    return text.replace(/^---\n/, `---\nnaming: ${naming}\n`);
 }
-// The grouping bullet's placeholder becomes one bullet per starting group, each
-// in the framework's convention so a grouping property's value can match its folder.
-function setGroups(text, label, groups) {
-    const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const pattern = new RegExp(`^-\\s+\\*\\*${escaped}:\\*\\*.*$`, 'm');
-    const bullets = groups.map((group) => `  - **${group}** — ${GROUP_PROMPT}`).join('\n');
-    return text.replace(pattern, `- **${label}:**\n${bullets}`);
+// The canvas hint is the one field the CLI prescribes; a fresh root gets the
+// legend as its default palette on the seed's own status and type.
+function applyDefaultCanvasHints(document) {
+    const properties = document.get('properties');
+    if (!isMap(properties))
+        return;
+    for (const property of mapsIn(properties.get('custom'))) {
+        const hint = DEFAULT_CANVAS_HINTS[nameOf(property)];
+        if (!hint || property.has(TOOL_KEY))
+            continue;
+        // a hint is a map of maps; a seed writes its rows in flow style, which would put all of it on one line
+        property.flow = false;
+        property.set(TOOL_KEY, document.createNode({ canvas: hint }));
+    }
 }
-function renameCollection(text, from, to) {
+// Comments name the seed's collections too; a word-bounded rename follows them.
+function renameInText(text, from, to) {
     const escaped = from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     return text.replace(new RegExp(`(?<![\\w-])${escaped}(?!\\w)`, 'g'), to);
 }
-// A blank blueprint: every property that applies to the collection, with the
-// values given and `[]` for an empty list, then the flavor's shape as the body.
+// A value worth writing: anything but nothing, an empty string, or an empty list.
+function hasValue(value) {
+    return value !== undefined && value !== null && value !== '' && !(Array.isArray(value) && value.length === 0);
+}
+// A blank blueprint: every required property that applies to the collection
+// (with the value given, else blank, `[]` for a list), every optional one
+// that was given a value, then the variant's template as the body. An
+// optional property left out is not a gap, so the file carries nothing it
+// doesn't need.
 export function blankBlueprint(framework, collectionName, values, shapeTemplate, title) {
-    const entries = propertiesFor(framework, collectionName).map((property) => {
+    const entries = [];
+    for (const property of propertiesFor(framework, collectionName)) {
         const value = values[property.name];
-        if ((value === undefined || value === null || value === '') && property.type.toLowerCase() === 'list') {
-            return [property.name, []];
+        if (hasValue(value)) {
+            entries.push([property.name, value]);
         }
-        return [property.name, value ?? ''];
-    });
-    return formatFrontmatter(entries) + '\n' + renderShape(shapeTemplate, title);
+        else if (property.required) {
+            entries.push([property.name, property.type.toLowerCase() === 'list' ? [] : '']);
+        }
+    }
+    return formatFrontmatter(entries) + '\n' + renderTemplate(shapeTemplate, title);
 }
 export function installSeed(options) {
     const seedDir = path.join(options.seedsDir, options.seed);
-    const frameworkSrc = path.join(seedDir, 'Framework.md');
+    const frameworkSrc = path.join(seedDir, 'Framework.yaml');
     if (!existsSync(frameworkSrc)) {
-        throw new InstallError(`no seed '${options.seed}' under ${options.seedsDir} (needs a Framework.md)`);
+        throw new InstallError(`no seed '${options.seed}' under ${options.seedsDir} (needs a Framework.yaml)`);
     }
     const root = path.resolve(options.root);
-    if (existsSync(path.join(root, '_eidos'))) {
-        throw new InstallError(`${root}/_eidos already exists: that is a root; use migrate`);
+    if (existsSync(path.join(root, '.eidos'))) {
+        throw new InstallError(`${root}/.eidos already exists: that is a root; use migrate`);
     }
-    let text = readFileSync(frameworkSrc, 'utf8');
-    const seedFramework = parseFramework(text, 'md', seedDir, frameworkSrc);
+    const text = readFileSync(frameworkSrc, 'utf8');
+    const seedFramework = parseFramework(text, 'yaml', seedDir, frameworkSrc);
+    const document = parseDocument(text);
     if (seedFramework.collections.length === 0) {
         throw new InstallError(`${frameworkSrc} declares no collections`);
     }
     const writer = new Writer(options.dryRun);
     const naming = options.naming;
-    // 1. the framework itself. The seed's README is the root's visible door, so it
-    //    moves to the root; roles/, shapes/, me.md, and .gitignore travel as they are.
-    writer.copyTree(seedDir, path.join(root, '_eidos'));
-    writer.remove(path.join(root, '_eidos', 'README.md'));
+    // The framing collection is the recommendation, not the standard's rule: an
+    // owner who keeps the framing elsewhere leaves it out, templates and all.
+    const leftOut = options.framing === false ? seedFramework.collections.filter((collection) => collection.framing) : [];
+    const installing = seedFramework.collections.filter((collection) => !leftOut.includes(collection));
+    if (installing.length === 0) {
+        throw new InstallError(`'${options.seed}' has only its framing collection; nothing would be left to install`);
+    }
+    // 1. the framework itself. The seed's README is the root's visible door, and so
+    //    is any other top-level doc the seed declares (the software seed's
+    //    Vocabulary), so those move to the root; roles/, templates/, me.md, and
+    //    .gitignore travel as they are.
+    const topLevelDocs = seedFramework.topLevel.filter((doc) => /^\.\.\/[^/]+\.md$/.test(doc.path) && doc.path !== '../README.md').map((doc) => ({ title: doc.title, file: doc.path.slice(3) }));
+    writer.copyTree(seedDir, path.join(root, '.eidos'));
+    writer.remove(path.join(root, '.eidos', 'README.md'));
+    for (const doc of topLevelDocs) {
+        writer.remove(path.join(root, '.eidos', doc.file));
+    }
     // npm never packs a file named .gitignore, so a seed ships it as _gitignore.
     if (existsSync(path.join(seedDir, GITIGNORE_SHIPPED))) {
-        writer.rename(path.join(root, '_eidos', GITIGNORE_SHIPPED), path.join(root, '_eidos', '.gitignore'));
+        writer.rename(path.join(root, '.eidos', GITIGNORE_SHIPPED), path.join(root, '.eidos', '.gitignore'));
+    }
+    // 2. the framework document: naming, starting groups, and each collection in
+    //    convention, edited in place so the seed's comments travel with it.
+    document.set('naming', naming);
+    for (const collection of leftOut) {
+        const folders = foldersOf(document);
+        if (isSeq(folders))
+            folders.items = folders.items.filter((item) => !(isMap(item) && nameOf(item) === collection.name));
+        for (const variant of collection.variants)
+            writer.remove(path.join(root, '.eidos', variant.template));
     }
-    // 2. the Framework: naming, starting groups, and each collection in convention.
-    text = setNaming(text, naming);
     const grouped = seedFramework.collections.find((collection) => collection.grouping && !collection.framing) ?? null;
     if (options.groups.length > 0) {
         if (!grouped || !grouped.grouping) {
             throw new InstallError(`no collection in '${options.seed}' declares a grouping`);
         }
-        text = setGroups(text, grouped.grouping.label, options.groups.map((group) => convert(group, naming)));
+        const groupedNode = mapsIn(foldersOf(document)).find((collection) => nameOf(collection) === grouped.name);
+        const grouping = groupedNode?.get('grouping');
+        if (!isMap(grouping)) {
+            throw new InstallError(`${frameworkSrc}: ${grouped.name} declares a grouping the document does not carry`);
+        }
+        grouping.set('groups', document.createNode(options.groups.map((group) => ({ name: convert(group, naming), description: '' }))));
     }
     const readmeSrc = path.join(seedDir, 'README.md');
     let readme = existsSync(readmeSrc) ? readFileSync(readmeSrc, 'utf8') : null;
     if (readme !== null && options.product !== null) {
         readme = readme.replace(/\{\{Product\}\}/g, options.product);
     }
-    if (readme !== null) {
-        readme = readme.replace(/Framework\.md/g, 'Framework.yaml');
+    // A declared top-level doc is a file a person reads, so it takes the naming
+    // convention (README.md alone keeps its name), and the links to it in the
+    // framework and the README move with it.
+    const docs = [];
+    for (const doc of topLevelDocs) {
+        const source = path.join(seedDir, doc.file);
+        if (!existsSync(source)) {
+            continue;
+        }
+        let body = readFileSync(source, 'utf8');
+        if (options.product !== null) {
+            body = body.replace(/\{\{Product\}\}/g, options.product);
+        }
+        const target = `${convert(doc.title, naming)}.md`;
+        if (target !== doc.file) {
+            for (const entry of mapsIn(document.get('top_level'))) {
+                if (entry.get('path') === `../${doc.file}`)
+                    entry.set('path', `../${target}`);
+            }
+            if (readme !== null) {
+                readme = readme.split(`(${doc.file})`).join(`(${target})`);
+            }
+        }
+        docs.push({ target, body });
     }
+    // Every declared folder takes the naming convention, a collection and an
+    // assets folder alike; the files inside an assets folder keep their names.
     const folders = new Map();
-    for (const collection of seedFramework.collections) {
-        const folder = convert(collection.name, naming);
-        folders.set(collection.name, folder);
-        if (folder !== collection.name) {
-            text = renameCollection(text, collection.name, folder);
+    const renames = new Map();
+    if (readme !== null && leftOut.length > 0) {
+        readme = readme
+            .split('\n')
+            .filter((line) => !leftOut.some((collection) => line.includes(`[${collection.name}]`)))
+            .join('\n');
+    }
+    const plain = seedFramework.folders.filter((folder) => !isCollection(folder));
+    for (const declared of [...installing, ...plain]) {
+        // a seed writes a collection's name in Title Case and its assets folder in
+        // lowercase; the convention is applied to the title-cased word either way
+        const folder = convert(titleize(declared.name), naming);
+        folders.set(declared.name, folder);
+        if (folder !== declared.name) {
+            renames.set(declared.name, folder);
             if (readme !== null) {
-                readme = renameCollection(readme, collection.name, folder);
+                readme = renameInText(readme, declared.name, folder);
             }
         }
     }
-    // The seed's markdown is the source; the root gets the same framework as
-    // YAML, with the guidance as comments. The seed's prose (section intros,
-    // HTML comments) has no field to land in and stays in the seed.
-    const fromSeed = parseFramework(text, 'md', root, path.join(root, '_eidos', 'Framework.md'));
-    writer.remove(path.join(root, '_eidos', 'Framework.md'));
-    const frameworkFile = path.join(root, '_eidos', 'Framework.yaml');
-    const serialized = serializeDocument(frameworkToDocument(fromSeed));
+    renameFolders(document, renames);
+    applyDefaultCanvasHints(document);
+    let serialized = document.toString({ lineWidth: 0 });
+    // comments name the collections too, so the word follows; an assets folder's
+    // name is also a type (`type: assets`), so only its entry is renamed
+    for (const [from, to] of renames) {
+        if (installing.some((collection) => collection.name === from))
+            serialized = renameInText(serialized, from, to);
+    }
+    const frameworkFile = path.join(root, '.eidos', 'Framework.yaml');
     writer.write(frameworkFile, serialized);
     const installed = parseFramework(serialized, 'yaml', root, frameworkFile);
     if (readme !== null) {
         writer.write(path.join(root, 'README.md'), readme);
     }
-    // 3. a folder per collection; blank blueprints for the framing one.
+    for (const doc of docs) {
+        writer.write(path.join(root, doc.target), doc.body);
+    }
+    // 3. a folder per declared folder; blank blueprints for the framing collection.
     const scaffolded = [];
     const groupsInConvention = options.groups.map((group) => convert(group, naming));
-    for (const collection of seedFramework.collections) {
+    for (const folder of plain) {
+        writer.mkdir(path.join(root, folders.get(folder.name) ?? folder.name));
+    }
+    for (const collection of installing) {
         const folderName = folders.get(collection.name) ?? collection.name;
         const folder = path.join(root, folderName);
         writer.mkdir(folder);
@@ -183,22 +299,21 @@ export function installSeed(options) {
         if (!collection.framing) {
             continue;
         }
-        for (const flavor of collection.flavors) {
-            const shapeFile = path.join(seedDir, flavor.shape);
-            if (!existsSync(shapeFile)) {
-                writer.actions.push(`skip   ${collection.name}/${flavor.name}: no shape at ${flavor.shape}`);
+        for (const variant of collection.variants) {
+            const templateFile = path.join(seedDir, variant.template);
+            if (!existsSync(templateFile)) {
+                writer.actions.push(`skip   ${collection.name}/${variant.name}: no template at ${variant.template}`);
                 continue;
             }
-            const title = titleize(flavor.name);
+            const title = titleize(variant.name);
             const values = {
-                id: kebab(flavor.name),
+                id: kebab(variant.name),
                 title,
-                flavor: flavor.name,
-                status: 'Draft',
+                variant: variant.name,
                 date_created: options.date,
                 date_modified: options.date,
             };
-            const body = blankBlueprint(installed, folderName, values, readFileSync(shapeFile, 'utf8'), title);
+            const body = blankBlueprint(installed, folderName, values, readFileSync(templateFile, 'utf8'), title);
             const file = path.join(folder, `${convert(title, naming)}.md`);
             writer.write(file, body);
             scaffolded.push(`${folderName}/${convert(title, naming)}.md`);
@@ -214,7 +329,8 @@ export function installSeed(options) {
         eidosVersion: installed.eidosVersion,
         naming,
         frameworkFile,
-        collections: seedFramework.collections.map((collection) => folders.get(collection.name) ?? collection.name),
+        collections: installing.map((collection) => folders.get(collection.name) ?? collection.name),
+        folders: plain.map((folder) => folders.get(folder.name) ?? folder.name),
         groupedCollection: grouped ? (folders.get(grouped.name) ?? grouped.name) : null,
         groups: groupsInConvention,
         scaffolded,