@metaobjectsdev/metadata 0.24.0-rc.1 → 0.24.0

package/dist/vocabulary-rewrite.js

@@ -0,0 +1,310 @@
+// server/typescript/packages/metadata/src/vocabulary-rewrite.ts
+//
+// The raw-document rewriter behind `meta upgrade`.
+//
+// WHY IT CANNOT USE THE LOADER — the constraint that shapes everything here. Once an
+// attribute is deregistered, metadata carrying it FAILS THE LOAD; that is the point of a
+// retirement. So load → transform → canonical-serialize is impossible: the input does not
+// load, and the canonical serializer needs a loaded model. This operates on RAW TEXT.
+//
+// That is also what makes the upgrade path exist at all. An adopter installs the new CLI and
+// runs this against metadata the new CLI REFUSES. A fixer that needed a successful load
+// would be a chicken-and-egg with no exit.
+//
+// SURGICAL, NOT PARSE-AND-REPRINT. Adopters author JSONC with comments and meaningful key
+// order — `meta gen`'s output order, review conventions, "do not reorder" notes. A
+// round-trip through JSON.parse/stringify destroys all of it while reporting success. So
+// every edit here is a span replacement on the original text, and any region we did not
+// deliberately change comes back byte-identical.
+//
+// IT SCOPES EVERY OCCURRENCE, NOT EVERY FILE. Retirements are type-scoped — `@unique` is
+// retired on `identity.secondary` and perfectly live on a field — so the governing type is
+// a property of WHERE the attribute sits, not of the document it sits in. A file-level
+// scope was the original shape and it was wrong in both directions: a caller that ran one
+// pass per type key present in the file let the `identity.secondary` scope reach a
+// `field.string`'s `@unique` (branding live vocabulary retired, and with a `dropAttr` entry
+// DELETING it), and reported every wildcard-scoped refusal once per subtype key in the file.
+// `scopeRanges` below recovers the enclosing `"<type>.<subType>"` for each occurrence, so
+// one pass over the document answers both correctly.
+//
+// CANONICAL JSON ONLY. YAML authoring is real (ADR-0006) but is not rewritable here: a
+// correct YAML editor needs the `yaml` package's CST, and this module is reachable from
+// `src/index.ts`, which the browser-safety test forbids from importing it. A hand-rolled
+// YAML mode was tried and shipped a file-corrupting bug — a multi-item block sequence lost
+// every item but the first, because the value scanner stops at a newline — while the
+// dominant in-repo authoring style (flow mappings, `{ name: x, readOnly: true }`) was not
+// matched at all, so the rename silently did nothing. `meta upgrade` refuses YAML by name
+// instead; a refusal an adopter can act on beats a success they cannot trust.
+//
+// IT REFUSES WHAT IT CANNOT KNOW. A retirement with no `rewrite` (`@status: abandoned`) is
+// reported, never guessed at. Deleting the node, retyping it, and fixing the residue it
+// describes are all defensible, and a wrong guess emits metadata that LOADS and means
+// something different — strictly worse than leaving it alone, because the adopter would
+// believe the migration finished.
+import { RETIRED_VOCABULARY, note, scopeMatches, } from "./retired-vocabulary.js";
+/** `0.24.0` → `[0,24,0]`, for an ordered comparison rather than a string one. */
+function parts(v) {
+    return v.split(".").map((n) => Number.parseInt(n, 10) || 0);
+}
+function atOrBefore(a, b) {
+    const [x, y] = [parts(a), parts(b)];
+    for (let i = 0; i < Math.max(x.length, y.length); i++) {
+        const d = (x[i] ?? 0) - (y[i] ?? 0);
+        if (d !== 0)
+            return d < 0;
+    }
+    return true;
+}
+/** 1-indexed line of `index` in `text`. */
+function lineAt(text, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < text.length; i++)
+        if (text[i] === "\n")
+            line++;
+    return line;
+}
+/**
+ * Offset just past the bracket closing the one at `open`, or undefined if unbalanced.
+ * String-aware, so a brace inside a JSON string literal cannot unbalance the scan.
+ */
+function closingBracket(text, open) {
+    const close = text[open] === "[" ? "]" : "}";
+    const openCh = text[open];
+    let depth = 0;
+    let inStr = false;
+    for (let j = open; j < text.length; j++) {
+        const c = text[j];
+        if (inStr) {
+            if (c === "\\")
+                j++;
+            else if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"')
+            inStr = true;
+        else if (c === openCh)
+            depth++;
+        else if (c === close) {
+            depth--;
+            if (depth === 0)
+                return j + 1;
+        }
+    }
+    return undefined;
+}
+/**
+ * Every node body in the document, in source order.
+ *
+ * A canonical-JSON node is `{ "<type>.<subType>": { …body… } }`, so an attribute belongs to
+ * the INNERMOST body containing it — which is what makes per-occurrence scoping possible
+ * without a parser we deliberately do not have.
+ */
+function scopeRanges(source) {
+    const ranges = [];
+    const re = /"([a-z][A-Za-z0-9]*)\.([A-Za-z0-9_*]+)"\s*:\s*\{/g;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        const bodyStart = m.index + m[0].length - 1;
+        const bodyEnd = closingBracket(source, bodyStart);
+        if (bodyEnd === undefined)
+            continue;
+        ranges.push({ typeKey: `${m[1]}.${m[2]}`, keyIndex: m.index, bodyStart, bodyEnd });
+    }
+    return ranges;
+}
+/** The type key governing `offset` — the innermost body containing it. */
+function scopeAt(ranges, offset) {
+    let best;
+    for (const r of ranges) {
+        if (offset <= r.bodyStart || offset >= r.bodyEnd)
+            continue;
+        // Properly nested ranges: the innermost containing one starts last.
+        if (best === undefined || r.bodyStart > best.bodyStart)
+            best = r;
+    }
+    return best?.typeKey;
+}
+/**
+ * Matches `"@name"` at a key position, plus the separator that follows, capturing the key
+ * separately so a replacement can keep the original spacing.
+ *
+ * Deliberately NOT a full parser. A parser would have to reproduce the document to emit it,
+ * which is the thing this exists to avoid; matching a key occurrence lets every untouched
+ * byte survive by construction.
+ */
+function keyPattern(attr) {
+    return new RegExp(`("@?${attr}")(\\s*:\\s*)`, "g");
+}
+/** The JSON value token starting at `from` — a scalar, or a bracketed array/object. */
+function valueSpan(text, from) {
+    let i = from;
+    while (i < text.length && /\s/.test(text[i] ?? ""))
+        i++;
+    const open = text[i];
+    if (open === "[" || open === "{") {
+        const end = closingBracket(text, i);
+        return end === undefined ? undefined : { start: i, end, raw: text.slice(i, end) };
+    }
+    // Scalar: to the next comma, closing brace, or newline, whichever comes first.
+    let j = i;
+    let inStr = false;
+    for (; j < text.length; j++) {
+        const c = text[j];
+        if (inStr) {
+            if (c === "\\")
+                j++;
+            else if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"')
+            inStr = true;
+        else if (c === "," || c === "}" || c === "\n")
+            break;
+    }
+    return { start: i, end: j, raw: text.slice(i, j).trim() };
+}
+/** Does the raw token equal this literal? Compares JSON-decoded where possible so
+ *  `"readOnly"` and `readOnly` both match a string literal. */
+function rawEquals(raw, want) {
+    try {
+        return JSON.parse(raw) === want;
+    }
+    catch {
+        return raw === String(want);
+    }
+}
+/**
+ * The span to delete so that removing a key leaves loadable JSON.
+ *
+ * The arithmetic is fiddly and every branch is load-bearing, so it lives here with its
+ * steps named rather than inline in the dispatch below.
+ */
+function dropSpan(source, keyStart, valueEnd) {
+    // 1. Absorb the value's trailing spaces, then its trailing comma if it has one.
+    let end = valueEnd;
+    while (end < source.length && /[ \t]/.test(source[end] ?? ""))
+        end++;
+    const hadTrailingComma = source[end] === ",";
+    if (hadTrailingComma)
+        end++;
+    // 2. Absorb the key's own indentation, so the removal does not leave a ragged line.
+    let start = keyStart;
+    while (start > 0 && /[ \t]/.test(source[start - 1] ?? ""))
+        start--;
+    // 3. THE LAST-KEY CASE, found by dogfooding rather than by a unit test: when the retired
+    //    attr is last in its object there IS no trailing comma — the comma belongs to the
+    //    PRECEDING key. Dropping without taking it leaves `"...",\n}`, which does not parse.
+    //    A tool whose whole job is producing loadable metadata cannot emit invalid JSON.
+    if (!hadTrailingComma) {
+        let back = start;
+        while (back > 0 && /\s/.test(source[back - 1] ?? ""))
+            back--;
+        if (source[back - 1] === ",")
+            start = back - 1;
+    }
+    // 4. If the key owned its whole line, take the line terminator too rather than leaving a
+    //    blank line. Otherwise the key shares a line with other content, so undo step 2's
+    //    indentation trim — it would eat the separating space after the preceding key's comma.
+    if (source[start - 1] === "\n" && source[end] === "\n")
+        end++;
+    else if (start > 0 && source[start - 1] !== "\n" && hadTrailingComma)
+        start = keyStart;
+    return { start, end };
+}
+/**
+ * Rewrite retired vocabulary in one raw canonical-JSON metadata document.
+ *
+ * Pure: no filesystem, no loader, no registry. Returns the new text plus every change and
+ * every refusal, so a caller can print a diff and exit non-zero when work remains.
+ */
+export function rewriteDocument(source, opts = {}) {
+    const changes = [];
+    const refusals = [];
+    // Edits are collected as spans against the ORIGINAL text and applied in one pass at the
+    // end, right-to-left. Rewriting incrementally would invalidate every later offset.
+    const edits = [];
+    const inWindow = (e) => opts.maxVersion === undefined || atOrBefore(e.since, opts.maxVersion);
+    const ranges = scopeRanges(source);
+    // A retired SUBTYPE has no attribute to rewrite — the node itself has to be re-modelled
+    // (`origin.collection` becomes `origin.aggregate @agg: collect`), which is a judgment the
+    // adopter makes. Reporting it is what keeps `meta upgrade` from exiting 0 on a document
+    // that still will not load; it used to be filtered out entirely and was invisible.
+    for (const r of ranges) {
+        for (const entry of RETIRED_VOCABULARY) {
+            if (entry.isSubTypeRetirement !== true || !inWindow(entry))
+                continue;
+            if (`${entry.type}.${entry.subType}` !== r.typeKey)
+                continue;
+            refusals.push({ ...note(entry), subject: r.typeKey, line: lineAt(source, r.keyIndex) });
+        }
+    }
+    for (const entry of RETIRED_VOCABULARY.filter((e) => e.attr !== undefined && inWindow(e))) {
+        const attr = entry.attr;
+        const re = keyPattern(attr);
+        let m;
+        while ((m = re.exec(source)) !== null) {
+            const keyStart = m.index;
+            const keyEnd = keyStart + (m[1]?.length ?? 0);
+            const afterKey = m.index + m[0].length;
+            // Scope is decided HERE, per occurrence, from the enclosing node.
+            const scope = scopeAt(ranges, keyStart);
+            if (scope === undefined || !scopeMatches(entry, scope))
+                continue;
+            const line = lineAt(source, keyStart);
+            const span = valueSpan(source, afterKey);
+            // A VALUE-scoped retirement only fires on the retired values. `@dbColumnType: jsonb`
+            // is live vocabulary on the same attribute; touching it would silently change the
+            // column type.
+            if (entry.attrValues !== undefined) {
+                if (!entry.attrValues.some((v) => rawEquals(span?.raw ?? "", v)))
+                    continue;
+            }
+            const refuse = () => {
+                refusals.push({
+                    ...note(entry),
+                    subject: `@${attr}`,
+                    ...(span?.raw !== undefined ? { value: span.raw } : {}),
+                    line,
+                });
+            };
+            const drop = () => {
+                if (span === undefined)
+                    return;
+                const { start, end } = dropSpan(source, keyStart, span.end);
+                edits.push({ start, end, text: "" });
+                changes.push({ attr, from: attr, to: "(removed)", line });
+            };
+            const rw = entry.rewrite;
+            if (rw === undefined)
+                refuse();
+            else if (rw.kind === "renameAttr") {
+                edits.push({ start: keyStart, end: keyEnd, text: `"@${rw.to}"` });
+                changes.push({ attr, from: attr, to: rw.to, line });
+            }
+            else if (rw.kind === "dropAttr")
+                drop();
+            else if (span === undefined)
+                continue;
+            else if (rawEquals(span.raw, rw.fromValue)) {
+                const valText = JSON.stringify(rw.toValue);
+                edits.push({ start: keyStart, end: keyEnd, text: `"@${rw.toAttr}"` });
+                edits.push({ start: span.start, end: span.end, text: valText });
+                changes.push({ attr, from: `${attr}: ${span.raw}`, to: `${rw.toAttr}: ${valText}`, line });
+            }
+            // Every other value of a retired attribute still has to go somewhere — the entry says
+            // which, and the type makes saying it mandatory.
+            else if (rw.otherwise === "drop")
+                drop();
+            else
+                refuse();
+        }
+    }
+    edits.sort((a, b) => b.start - a.start);
+    let text = source;
+    for (const e of edits)
+        text = text.slice(0, e.start) + e.text + text.slice(e.end);
+    return { text, changes, refusals };
+}
+//# sourceMappingURL=vocabulary-rewrite.js.map

package/dist/vocabulary-rewrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary-rewrite.js","sourceRoot":"","sources":["../src/vocabulary-rewrite.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/metadata",
-  "version": "0.24.0-rc.1",
+  "version": "0.24.0",
   "description": "Metamodel loader, types, and constants for the MetaObjects standard.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,6 +16,11 @@
       "types": "./dist/core/index.d.ts",
       "default": "./dist/core/index.js"
     },
+    "./library": {
+      "bun": "./src/library/library-sources.ts",
+      "types": "./dist/library/library-sources.d.ts",
+      "default": "./dist/library/library-sources.js"
+    },
     "./constants": {
       "bun": "./src/constants.ts",
       "types": "./dist/constants.d.ts",

package/src/attr-schema-validate.ts

@@ -47,6 +47,9 @@ import type { AttrSchema, TypeRegistry } from "./registry.js";
 import { childRuleMatches } from "./registry.js";
 import { TYPE_FIELD, TYPE_METADATA } from "./shared/base-types.js";
 import { ATTR_SUBTYPE_PROPERTIES } from "./core/attr/attr-constants.js";
+// #337: turns "unknown X" into "retired in V — here is the migration". Changes no load
+// outcome; retired vocabulary still fails with the same code.
+import { retiredAttr, retiredAttrValue, retirementHint } from "./retired-vocabulary.js";
 import {
   FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_VALUES,
@@ -164,10 +167,17 @@ function validateNode(
       // @-attr still fails — only the `properties` subtype is exempt.)
       if (inst.subType === ATTR_SUBTYPE_PROPERTIES) continue;
       if (!byName.has(inst.name)) {
+        // #337: if we RETIRED this name, say so. "Not declared by any registered
+        // provider" is true and reads as "your metadata is malformed", which sent one
+        // adopter to file a registration bug against a deliberate, documented breaking
+        // change. Unrecognised names still report generically — a typo is a typo.
+        const retired = retiredAttr(typeKey, inst.name);
         errors.push(
           new ParseError(
             `Unknown attribute '@${inst.name}' on ${nodeLabel(node)} — ` +
-              `not declared by any registered provider for ${typeKey}`,
+              (retired !== undefined
+                ? retirementHint(retired)
+                : `not declared by any registered provider for ${typeKey}`),
             { code: "ERR_UNKNOWN_ATTR", source: node.source },
           ),
         );
@@ -290,11 +300,16 @@ function validateNode(
           ? []
           : [value];
       for (const bad of offenders) {
+        // #337: a member we REMOVED reads very differently from a member that never
+        // existed. `@status: abandoned` was valid one release ago, so "not one of the
+        // allowed values" invites the reader to conclude the enum is broken.
+        const retiredValue = retiredAttrValue(typeKey, inst.name, bad);
         errors.push(
           new ParseError(
             `${nodeLabel(node)} attribute '@${inst.name}' has value ` +
               `'${String(bad)}' which is not one of the allowed values: ` +
-              `${allowed.map((v) => String(v)).join(", ")}`,
+              `${allowed.map((v) => String(v)).join(", ")}` +
+              (retiredValue !== undefined ? ` — ${retirementHint(retiredValue)}` : ""),
             { code: "ERR_BAD_ATTR_VALUE", source: node.source },
           ),
         );

package/src/core/field/field-constants.ts

@@ -64,11 +64,30 @@ export type FieldSubType = (typeof FIELD_SUBTYPES)[number];
 export const FIELD_ATTR_REQUIRED = "required";
 export const FIELD_ATTR_UNIQUE = "unique";
 
-/** FR-013: when true, the field is read-only from the application's perspective.
- *  Codegen emits no setter; persistence skips the column on INSERT/UPDATE; Zod
- *  create/update variants omit the field. Default false (writable). See ADR-0013
- *  layer split — this is logical (no DB-introspection round-trip). */
-export const FIELD_ATTR_READ_ONLY = "readOnly";
+/** FR-037 R1: who may write this field, and when. One axis, three mutually
+ *  exclusive modes, so the illegal pair (`readOnly` + `writeOnce`) is
+ *  unrepresentable and inheritance has a total order. Absent ⇒ `readWrite`.
+ *  See ADR-0013 layer split — this is logical (no DB-introspection round-trip). */
+export const FIELD_ATTR_MUTABILITY = "mutability";
+
+/** `readWrite` — the caller may set it on create and change it on update. */
+export const MUTABILITY_READ_WRITE = "readWrite";
+/** `writeOnce` — set on create, then excluded from the update shape. A value
+ *  presented on PATCH is IGNORED, not rejected (the uniform behaviour of every
+ *  excluded-settable-set key, and the generated edit form submits every field). */
+export const MUTABILITY_WRITE_ONCE = "writeOnce";
+/** `readOnly` — nobody writes it: no setter, skipped on INSERT/UPDATE, omitted
+ *  from every input variant. Populated by the DB, replication, or another owner. */
+export const MUTABILITY_READ_ONLY = "readOnly";
+
+/** Declaration order IS the tightening order — index in this array is the mode's
+ *  rank, so "may only tighten" is an index comparison rather than a lookup table. */
+export const MUTABILITY_MODES = [
+  MUTABILITY_READ_WRITE,
+  MUTABILITY_WRITE_ONCE,
+  MUTABILITY_READ_ONLY,
+] as const;
+export type MutabilityMode = (typeof MUTABILITY_MODES)[number];
 export const FIELD_ATTR_DEFAULT = "default";
 export const FIELD_ATTR_MAX_LENGTH = "maxLength";
 

package/src/core/field/field-definition.embedded.ts

@@ -46,11 +46,16 @@ export const FIELD_DEFINITION: ProviderDefinition = {
         },
         {
           "type": "attr",
-          "subType": "boolean",
-          "name": "readOnly",
+          "subType": "string",
+          "name": "mutability",
           "min": 0,
           "max": 1,
-          "description": "FR-013: when true, the field is read-only — codegen emits no setter / writable property, the persistence layer skips the column on INSERT/UPDATE, and Zod/Pydantic/class-validator schemas mark it read-only on input variants. The value is populated by the database (computed column, default expression, trigger), by replication, or by another external owner."
+          "allowedValues": [
+            "readWrite",
+            "writeOnce",
+            "readOnly"
+          ],
+          "description": "FR-037 R1: who may write this field, and when. 'readWrite' (the default when absent) — the caller may set it on create and change it on update. 'writeOnce' — the caller sets it on create; it is excluded from the update shape thereafter, so a value presented on PATCH is ignored rather than rejected. 'readOnly' — nobody writes it: codegen emits no setter / writable property, the persistence layer skips the column on INSERT/UPDATE, and Zod/Pydantic/class-validator schemas omit it from input variants; the value is populated by the database (computed column, default expression, trigger), by replication, or by another external owner. The three are mutually exclusive modes of ONE axis — who may write, and when — so the illegal pair is unrepresentable and inheritance has a total order: a subtype may TIGHTEN an inherited mode (readWrite < writeOnce < readOnly) and never loosen it (ERR_MUTABILITY_DOWNGRADE). Pairing a non-readWrite mode with @autoSet is ERR_MUTABILITY_AUTOSET_CONFLICT: @autoSet already says the SERVER supplies the value, which is a different axis from who may write it."
         },
         {
           "type": "attr",