@loomcli/core 0.2.0 → 0.3.0

package/dist/view.js

@@ -0,0 +1,307 @@
+import { DeclarationError, defaultText, FatalError, notTextReason, reasonOf } from './errors.js';
+import { escapeText } from './style.js';
+/** Authored declarations register here, so a hand-built object with an identity is a bare view. */
+const declarations = new WeakMap();
+/** The runtime value `view()` returns for a whole view. Its identity and function are public. */
+class ViewDeclaration {
+    identity;
+    render;
+    constructor(identity, definition) {
+        this.identity = identity;
+        this.render = definition.render;
+        declarations.set(this, this);
+        Object.freeze(this);
+    }
+}
+/** The runtime value `view()` returns for a row view, which carries its three functions. */
+class RowViewDeclaration {
+    identity;
+    row;
+    head;
+    tail;
+    constructor(identity, definition) {
+        this.identity = identity;
+        this.row = definition.row;
+        if (definition.head) {
+            this.head = definition.head;
+        }
+        if (definition.tail) {
+            this.tail = definition.tail;
+        }
+        declarations.set(this, this);
+        Object.freeze(this);
+    }
+}
+/**
+ * The shape one value names. The argument is read defensively, because every call that takes a view
+ * is reachable from JavaScript and `null` is one such value.
+ */
+function shapeOf(value) {
+    const row = typeof value?.row === 'function';
+    const render = typeof value?.render === 'function';
+    if (row && render) {
+        return 'both';
+    }
+    if (row) {
+        return 'row';
+    }
+    return render ? 'render' : 'neither';
+}
+function view(identity, definition) {
+    const shape = shapeOf(definition);
+    if (shape === 'both') {
+        throw new DeclarationError(`View "${identity}" carries render and row. Supply one of the two.`);
+    }
+    if (shape === 'neither') {
+        throw new DeclarationError(`View "${identity}" carries neither render nor row. Supply a view with render or a row view with row.`);
+    }
+    return typeof definition.row === 'function'
+        ? new RowViewDeclaration(identity, definition)
+        : new ViewDeclaration(identity, definition);
+}
+/** Authored overrides register here, so the public type publishes nothing to reach. */
+const overrides = new WeakMap();
+/** The runtime value `override()` returns. Its pair lives in the registry above. */
+class OverrideDeclaration {
+    constructor(record) {
+        overrides.set(this, record);
+        Object.freeze(this);
+    }
+}
+function override(key, replacement) {
+    const stored = {
+        head: replacement.head,
+        render: replacement.render,
+        row: replacement.row,
+        tail: replacement.tail,
+    };
+    const declared = declarations.get(key);
+    if (declared) {
+        return new OverrideDeclaration({ key: { kind: 'view', view: declared }, replacement: stored });
+    }
+    return new OverrideDeclaration({ key: failureKey(key), replacement: stored });
+}
+/**
+ * The key one failure-class override answers. A class is a function whose `prototype` is the
+ * object a thrown failure's chain holds, so anything else is no key at all and build reports it as
+ * the entry fault of the list that holds it, rather than colliding with every other such value.
+ */
+function failureKey(key) {
+    if (typeof key !== 'function' || !('prototype' in key)) {
+        return { kind: 'invalid' };
+    }
+    const prototype = key.prototype;
+    if (typeof prototype !== 'object' || prototype === null) {
+        return { kind: 'invalid' };
+    }
+    const name = 'name' in key && typeof key.name === 'string' && key.name !== '' ? key.name : 'a failure class';
+    return { kind: 'failure', name, prototype };
+}
+/** The identity register one build starts from, holding the views core itself declares. */
+function viewIdentities(declared) {
+    const identities = new Map();
+    for (const value of declared) {
+        registerIdentity(identities, value);
+    }
+    return identities;
+}
+/** One identity means one declared view, wherever on the graph that view appears. */
+function registerIdentity(identities, declared) {
+    const known = identities.get(declared.identity);
+    if (known === undefined) {
+        identities.set(declared.identity, declared);
+        return;
+    }
+    if (known !== declared) {
+        throw new DeclarationError(`View "${declared.identity}" is declared by two distinct objects. Install one copy of the package that declares it.`);
+    }
+}
+/** The sentence one contributor's list reports for a value it cannot read. */
+function entryFault(subject) {
+    return subject.declares
+        ? `${subject.sentence} holds a value that is not a view. Supply the value returned by view(identity, definition) or override(key, view).`
+        : `${subject.sentence} holds a value that is not a view override. Supply the value returned by override(key, view).`;
+}
+/** A `views` slot holds a list, so anything else is the same declaration fault. */
+function readContributions(subject, declared) {
+    if (declared === undefined) {
+        return [];
+    }
+    if (!Array.isArray(declared)) {
+        throw new DeclarationError(subject.declares
+            ? `${subject.sentence} declares views that are not an array. Supply a list of declared views and override values.`
+            : entryFault(subject));
+    }
+    return declared;
+}
+/** The override one entry carries; anything else is a declaration fault of the slot. */
+function overrideOf(subject, entry) {
+    const record = typeof entry === 'object' && entry !== null ? overrides.get(entry) : undefined;
+    if (!record) {
+        throw new DeclarationError(entryFault(subject));
+    }
+    return record;
+}
+/**
+ * One override recorded under the key it answers. One key answers to one override inside one
+ * contributor, so a second override for it is a declaration fault; the same key overridden by two
+ * contributors resolves first-in-wins. A key that is neither a declared view nor a failure class
+ * is the entry fault of the list that holds it, reported here rather than at the `override()` call.
+ */
+function recordOverride(build, { key, replacement }) {
+    if (key.kind === 'invalid') {
+        throw new DeclarationError(entryFault(build.subject));
+    }
+    if (key.kind === 'failure') {
+        recordFailureOverride(build, key, replacement);
+        return;
+    }
+    recordViewOverride(build, key.view, replacement);
+}
+/** One failure class answers to one override inside one contributor, keyed by its prototype. */
+function recordFailureOverride({ contributions, subject }, key, replacement) {
+    if (contributions.failures.has(key.prototype)) {
+        throw new DeclarationError(`${subject.sentence} overrides the view for "${key.name}" twice. Remove one override.`);
+    }
+    contributions.failures.set(key.prototype, replacement);
+}
+/** Naming a declared view as a key registers its identity, as listing the declaration does. */
+function recordViewOverride({ contributions, identities, subject }, key, replacement) {
+    registerIdentity(identities, key);
+    if (contributions.views.has(key)) {
+        throw new DeclarationError(`${subject.sentence} overrides view "${key.identity}" twice. Remove one override.`);
+    }
+    contributions.views.set(key, replacement);
+}
+/**
+ * One contributor's own overrides, with the identity of every declared view it lists or names as a
+ * key registered. Listing a declared view is what puts its identity on the graph; an application
+ * lists overrides alone, so a declaration in its list is the same fault as any other value.
+ */
+function buildViews(subject, declared, identities) {
+    const contributions = { failures: new Map(), views: new Map() };
+    for (const entry of readContributions(subject, declared)) {
+        const listed = typeof entry === 'object' && entry !== null ? declarations.get(entry) : undefined;
+        if (listed && !subject.declares) {
+            throw new DeclarationError(entryFault(subject));
+        }
+        if (listed) {
+            registerIdentity(identities, listed);
+        }
+        else {
+            recordOverride({ contributions, identities, subject }, overrideOf(subject, entry));
+        }
+    }
+    return contributions;
+}
+/** One stored view value, read back over the data its own key carries. */
+function readStored(stored) {
+    // Last resort: no typed path exists.
+    // A registry holds one entry per key and cannot carry a type parameter per entry.
+    // A stored view value therefore reads back with its data type erased.
+    // It holds because `override(key, replacement)` typed the replacement against its key's data.
+    // Resolution reaches a stored value through that key alone.
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    return stored;
+}
+/**
+ * The stand-in for a function the stored shape does not carry. A JavaScript author's replacement
+ * of the wrong shape reaches it, and the throw is the output-view fault of the write site.
+ */
+function missing(name, key) {
+    return () => {
+        throw new Error(`The replacement view for "${key}" supplies no ${name} function.`);
+    };
+}
+/** One stored whole view, read back as the function the write site calls, named by its key. */
+function callView(stored, key) {
+    return readStored(stored).render ?? missing('render', key);
+}
+/** Every prototype in a failure's chain, most derived first, so one walk reads one contributor. */
+function chainOf(failure) {
+    const chain = [];
+    let prototype = Object.getPrototypeOf(failure);
+    while (prototype !== null) {
+        chain.push(prototype);
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return chain;
+}
+/**
+ * The view function one declared view resolves to: the first contributor that overrides it, then
+ * its own default. A bare view is never overridden, so it resolves to its own function.
+ */
+function resolveView(registry, value) {
+    const declared = declarations.get(value);
+    if (declared) {
+        for (const contributor of registry) {
+            const replacement = contributor.views.get(declared);
+            if (replacement) {
+                return callView(replacement, declared.identity);
+            }
+        }
+    }
+    return (data, context) => value.render(data, context);
+}
+/**
+ * The row functions one row view resolves to, by the walk `resolveView` defines. A replacement
+ * supplies the whole shape, so an override that omits `head` drops the default's `head` with it.
+ */
+function resolveRowView(registry, value) {
+    const declared = declarations.get(value);
+    if (declared) {
+        for (const contributor of registry) {
+            const replacement = contributor.views.get(declared);
+            if (replacement) {
+                const resolved = readStored(replacement);
+                const row = resolved.row ?? missing('row', declared.identity);
+                return { head: resolved.head, row, tail: resolved.tail };
+            }
+        }
+    }
+    return { head: value.head, row: value.row, tail: value.tail };
+}
+/**
+ * The override one failure resolves to, or nothing when core's own text answers it. The chain is
+ * walked in full at each contributor before the next is consulted, so an application's override
+ * for a base class beats a plugin's override for a subclass.
+ */
+function resolveFailure(registry, failure) {
+    const chain = chainOf(failure);
+    for (const contributor of registry) {
+        for (const prototype of chain) {
+            const replacement = contributor.failures.get(prototype);
+            if (replacement) {
+                return replacement;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * The text core writes for one failure. Resolution walks the registry as `resolveFailure` defines
+ * it and falls to core's own default text, which escapes the raw facts it interpolates. A
+ * `FatalError` keeps the authored marked message it was given.
+ */
+function describeFailure(registry, failure, context) {
+    const replacement = resolveFailure(registry, failure);
+    if (!replacement) {
+        return {
+            kind: 'rendered',
+            text: failure instanceof FatalError ? defaultText(failure) : escapeText(defaultText(failure)),
+        };
+    }
+    try {
+        if (context === undefined) {
+            throw new Error('Missing rendering context.');
+        }
+        const text = callView(replacement, failure.name)(failure, context);
+        return typeof text === 'string'
+            ? { kind: 'rendered', text }
+            : { kind: 'unrendered', reason: notTextReason(text), text: defaultText(failure) };
+    }
+    catch (error) {
+        return { kind: 'unrendered', reason: reasonOf(error), text: defaultText(failure) };
+    }
+}
+export { buildViews, describeFailure, override, resolveRowView, resolveView, shapeOf, view, viewIdentities, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcli/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The Loom CLI core package. Provides the scaffolding for creating new Loom CLI applications.",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,7 @@
     }
   },
   "dependencies": {
+    "@rockorager/uucode": "2.2.1",
     "@standard-schema/spec": "^1.1.0",
     "@types/node": "22.20.1"
   },