eidosmd 0.1.0 → 0.2.0

package/dist/src/core/migrate.js

@@ -0,0 +1,243 @@
+// `eidos migrate`: the mechanical hop from a 4.x root to the standard this CLI
+// carries (5.0.0). Five names move on disk and nothing is dropped: `_eidos/`
+// becomes `.eidos/`, `shapes/` becomes `templates/`, the framework document
+// takes the 5.0.0 keys, every blueprint's `flavor` becomes `variant`, and
+// `eidos_version` is set. A root that kept the markdown Framework.md gets
+// Framework.yaml in its place, the index inside it. A template that opens
+// with frontmatter loses the block; one named off its unit is noted, since
+// only the owner can say which name is right.
+import { existsSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+import { FRAMEWORK_DIR, FRAMEWORK_FILES, STANDARD_CORE, unitOf } from './framework-model.js';
+import { convertToYaml } from './convert.js';
+import { annotateYaml } from './framework-structured.js';
+import { parseFramework } from './framework.js';
+import { parseVersions } from './framework-markdown.js';
+import { stripFrontmatter } from './template.js';
+import { readVersions, writeVersions, versionsFile } from './versions.js';
+import { standardVersion } from '../paths.js';
+export const LEGACY_DIR = '_eidos';
+export class MigrationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MigrationError';
+    }
+}
+// A root for this command is a folder with `.eidos/` or the older `_eidos/`,
+// found upward from `start` the way every other command finds one.
+export function findMigratableRoot(start, explicit) {
+    const has = (dir) => existsSync(path.join(dir, FRAMEWORK_DIR)) || existsSync(path.join(dir, LEGACY_DIR));
+    if (explicit !== undefined) {
+        const resolved = path.resolve(start, explicit);
+        if (!has(resolved))
+            throw new MigrationError(`${resolved} is not a root: no ${FRAMEWORK_DIR}/ (or ${LEGACY_DIR}/) inside it`);
+        return resolved;
+    }
+    let current = path.resolve(start);
+    for (;;) {
+        if (has(current))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            throw new MigrationError(`no root found from ${start}: no ${FRAMEWORK_DIR}/ (or ${LEGACY_DIR}/) here or above`);
+        current = parent;
+    }
+}
+const rel = (root, file) => path.relative(root, file).split(path.sep).join('/');
+function markdownFiles(dir) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir).sort()) {
+        if (entry.startsWith('.'))
+            continue;
+        const full = path.join(dir, entry);
+        if (statSync(full).isDirectory())
+            out.push(...markdownFiles(full));
+        else if (/\.md$/i.test(entry))
+            out.push(full);
+    }
+    return out;
+}
+const keyOf = (pair) => (isScalar(pair.key) ? String(pair.key.value) : null);
+const renameKey = (pair, to) => {
+    if (isScalar(pair.key))
+        pair.key.value = to;
+};
+// The YAML form, key by key, comments kept: `schema` → `properties`,
+// `flavors` → `variants`, each variant's `shape` → `template` (with its path),
+// `unit` gone, the version set, and this CLI's guidance comments refreshed.
+export function migrateYamlDocument(text, version) {
+    const document = parseDocument(text);
+    const top = document.contents;
+    if (!isMap(top))
+        return text;
+    // the root's versions left the framework document in 5.0.0; migrateRoot moves them
+    top.items = top.items.filter((pair) => keyOf(pair) !== 'versions');
+    for (const pair of top.items) {
+        const key = keyOf(pair);
+        if (key === 'schema')
+            renameKey(pair, 'properties');
+        // the standard's own block is migrate's to rewrite: its rows are the 5.0.0 core
+        if ((key === 'schema' || key === 'properties') && isMap(pair.value)) {
+            for (const entry of pair.value.items) {
+                if (keyOf(entry) === 'core' && isSeq(entry.value) && entry.value.items.length > 0) {
+                    entry.value = document.createNode(STANDARD_CORE.map(({ name, type, meaning }) => ({ name, type, meaning })));
+                }
+            }
+        }
+        if (key === 'eidos_version' && isScalar(pair.value))
+            pair.value.value = version;
+        if (key === 'collections' && isSeq(pair.value)) {
+            for (const collection of pair.value.items) {
+                if (!isMap(collection))
+                    continue;
+                const map = collection;
+                map.items = map.items.filter((entry) => keyOf(entry) !== 'unit');
+                for (const entry of map.items) {
+                    if (keyOf(entry) === 'flavors')
+                        renameKey(entry, 'variants');
+                    if ((keyOf(entry) === 'variants' || keyOf(entry) === 'flavors') && isSeq(entry.value)) {
+                        for (const variant of entry.value.items) {
+                            if (!isMap(variant))
+                                continue;
+                            for (const field of variant.items) {
+                                if (keyOf(field) === 'shape') {
+                                    renameKey(field, 'template');
+                                    if (isScalar(field.value))
+                                        field.value.value = String(field.value.value).replace(/^shapes\//, 'templates/');
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    annotateYaml(document);
+    return document.toString({ lineWidth: 0 });
+}
+// What a 4.x document recorded under `versions`, in either form, for the move
+// to this CLI's own file.
+export function legacyVersions(text, format) {
+    if (format === 'md')
+        return parseVersions(text);
+    const top = parseDocument(text).contents;
+    if (!isMap(top))
+        return [];
+    const out = [];
+    for (const pair of top.items) {
+        if (keyOf(pair) !== 'versions' || !isSeq(pair.value))
+            continue;
+        for (const row of pair.value.items) {
+            if (!isMap(row))
+                continue;
+            const version = String(row.get('version') ?? '').trim();
+            const commit = String(row.get('commit') ?? '').trim();
+            if (version === '' || commit === '')
+                continue;
+            const tag = String(row.get('tag') ?? '').trim();
+            out.push({ version, commit, tag: tag === '' ? null : tag });
+        }
+    }
+    return out;
+}
+// A document already on this standard is left alone, except for a `versions`
+// key it may still carry.
+function withoutVersions(text) {
+    const document = parseDocument(text);
+    if (!isMap(document.contents) || !document.has('versions'))
+        return text;
+    document.delete('versions');
+    return document.toString({ lineWidth: 0 });
+}
+// The markdown form, line by line: the headings, the bullets, the links, the core row, the version.
+export function migrateMarkdownDocument(text, version) {
+    return text
+        .replace(/^eidos_version:\s*\S+/m, `eidos_version: ${version}`)
+        .replace(/^## Schema\s*$/m, '## Properties')
+        .replace(/^### Eidos Core\s*$/m, '### Eidos')
+        .replace(/^### Custom Properties\s*$/m, '### Custom')
+        .replace(/^### (.+?) Properties\s*$/gm, '### $1')
+        .replace(/^(\s*)- \*\*Flavors:\*\*/gm, '$1- **Variants:**')
+        .replace(/^\s*- \*\*Unit:\*\*[^\n]*\n/gm, '')
+        .replace(/\]\(shapes\//g, '](templates/')
+        .replace(/^(\|\s*)flavor(\s*\|)/gm, '$1variant$2')
+        .replace(/_eidos\//g, '.eidos/');
+}
+export function migrateRoot(root, options) {
+    const actions = [];
+    const notes = [];
+    const version = standardVersion();
+    const act = (what, run) => {
+        actions.push(what);
+        if (!options.dryRun)
+            run();
+    };
+    const legacy = path.join(root, LEGACY_DIR);
+    const dir = path.join(root, FRAMEWORK_DIR);
+    if (existsSync(legacy) && !existsSync(dir))
+        act(`rename ${LEGACY_DIR}/ to ${FRAMEWORK_DIR}/`, () => renameSync(legacy, dir));
+    else if (!existsSync(dir))
+        throw new MigrationError(`${root} is not a root: no ${FRAMEWORK_DIR}/ (or ${LEGACY_DIR}/) inside it`);
+    // on a dry run the folder may still be the old one
+    const live = existsSync(dir) ? dir : legacy;
+    const shapes = path.join(live, 'shapes');
+    const templates = path.join(live, 'templates');
+    if (existsSync(shapes) && !existsSync(templates))
+        act(`rename ${FRAMEWORK_DIR}/shapes/ to ${FRAMEWORK_DIR}/templates/`, () => renameSync(shapes, templates));
+    const liveTemplates = existsSync(templates) ? templates : shapes;
+    const found = FRAMEWORK_FILES.map((entry) => ({ ...entry, file: path.join(live, entry.name) })).find((entry) => existsSync(entry.file));
+    if (!found)
+        throw new MigrationError(`no Framework.yaml or Framework.md under ${rel(root, live)}/`);
+    const text = readFileSync(found.file, 'utf8');
+    const from = /^eidos_version:\s*([^\s#]+)/m.exec(text)?.[1] ?? null;
+    // A YAML root already on this standard is left as it is, its comments included.
+    const next = found.format === 'yaml' ? (from === version ? withoutVersions(text) : migrateYamlDocument(text, version)) : migrateMarkdownDocument(text, version);
+    if (next !== text)
+        act(`rewrite ${FRAMEWORK_DIR}/${found.name} in the ${version} form`, () => writeFileSync(found.file, next, 'utf8'));
+    const recorded = legacyVersions(text, found.format);
+    if (recorded.length > 0) {
+        act(`move ${recorded.length} recorded version${recorded.length === 1 ? '' : 's'} to ${rel(root, versionsFile(root))}, this CLI's own record`, () => {
+            const kept = readVersions(root);
+            writeVersions(root, [...recorded.filter((entry) => !kept.some((held) => held.version === entry.version)), ...kept]);
+        });
+    }
+    const ignore = path.join(root, '.gitignore');
+    if (existsSync(ignore)) {
+        const held = readFileSync(ignore, 'utf8');
+        if (held.includes(`${LEGACY_DIR}/`))
+            act(`point .gitignore at ${FRAMEWORK_DIR}/`, () => writeFileSync(ignore, held.replace(new RegExp(`${LEGACY_DIR}/`, 'g'), `${FRAMEWORK_DIR}/`), 'utf8'));
+    }
+    const framework = parseFramework(next, found.format, root, path.join(dir, found.name));
+    // The markdown form left the standard in 5.0.0: the same framework is written
+    // as data, and the markdown document and each collection's index.md go.
+    if (found.format === 'md') {
+        act(`write ${FRAMEWORK_DIR}/Framework.yaml from ${found.name}, the index inside it; remove ${found.name} and each collection's index.md`, () => {
+            convertToYaml(framework, false);
+        });
+    }
+    for (const collection of framework.collections) {
+        for (const file of markdownFiles(path.join(root, collection.name))) {
+            const content = readFileSync(file, 'utf8');
+            const block = /^---\r?\n[\s\S]*?\r?\n---/.exec(content);
+            if (!block || !/^flavor:/m.test(block[0]))
+                continue;
+            act(`rename flavor to variant in ${rel(root, file)}`, () => writeFileSync(file, content.replace(block[0], block[0].replace(/^flavor:/m, 'variant:')), 'utf8'));
+        }
+        const unit = unitOf(collection);
+        for (const variant of collection.variants) {
+            const file = path.join(liveTemplates, path.basename(variant.template));
+            if (existsSync(file)) {
+                const body = readFileSync(file, 'utf8');
+                if (/^---[ \t]*\r?\n/.test(body))
+                    act(`strip the frontmatter block from ${FRAMEWORK_DIR}/templates/${path.basename(file)}`, () => writeFileSync(file, stripFrontmatter(body), 'utf8'));
+            }
+            const expected = unit ? `${unit}.${variant.name}.md` : null;
+            if (expected && path.basename(variant.template) !== expected)
+                notes.push(`${collection.name}/${variant.name} is at ${variant.template}; a template is named templates/${expected}, and only you can say which name is right`);
+        }
+    }
+    return { root, from, to: version, actions, notes, dryRun: options.dryRun };
+}

package/dist/src/core/naming.js

@@ -15,7 +15,7 @@ export function kebab(label) {
 export function isKebab(value) {
     return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
 }
-// `prior work` -> `Prior Work`; a declared flavor label as a human title.
+// `prior work` -> `Prior Work`; a declared variant label as a human title.
 export function titleize(label) {
     return label
         .split(' ')

package/dist/src/core/root.js

@@ -1,4 +1,4 @@
-// Finding the root: the one folder with `_eidos/` inside it, never a folder
+// Finding the root: the one folder with `.eidos/` inside it, never a folder
 // with a particular name. Looks at the starting folder, then its ancestors,
 // then one and two levels beneath it, so `eidos check` works from a repo root
 // that keeps its blueprints in `Blueprints/`.
@@ -62,7 +62,7 @@ export function findRoot(start, explicit) {
     if (explicit !== undefined) {
         const resolved = path.resolve(start, explicit);
         if (!isRoot(resolved)) {
-            throw new RootError(`${resolved} is not a root: no ${FRAMEWORK_DIR}/Framework.md inside it`);
+            throw new RootError(`${resolved} is not a root: no ${FRAMEWORK_DIR}/Framework.yaml inside it`);
         }
         return resolved;
     }

package/dist/src/core/scaffold.js

@@ -1,13 +1,13 @@
 // Scaffolding one blueprint: frontmatter generated from the properties that
-// apply to its collection, body rendered from its flavor's shape, filename in
+// apply to its collection, body rendered from its variant's shape, 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 { 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) {
@@ -38,24 +38,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 +67,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,7 +83,7 @@ export function scaffoldBlueprint(framework, existing, options) {
         id,
         title,
         summary: options.summary ?? '',
-        flavor: flavor.name,
+        variant: variant.name,
         status: 'Draft',
         date_created: options.date,
         date_modified: options.date,
@@ -95,11 +95,11 @@ export function scaffoldBlueprint(framework, existing, options) {
     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`);
+            notes.push(`property '${key}' is not in the Properties table for ${collection.name}; written anyway`);
         }
         values[key] = coerce(type ?? 'Text', raw);
     }
-    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 +110,7 @@ export function scaffoldBlueprint(framework, existing, options) {
         rel: path.relative(framework.root, file).split(path.sep).join('/'),
         content,
         collection,
-        flavor,
+        variant,
         group,
         id,
         notes,