@mapled/cli 0.5.0 → 0.6.0

package/README.md

@@ -84,7 +84,9 @@ Articles (articles)
 4 breaking changes, 2 safe changes, judged for a site that reads the content. Update the site where needed, then run `mapled types generate` (it refreshes mapled/schema.json as well).
 ```
 
-Breaking: a collection, field or option the site may rely on disappears, a type changes, a required field becomes optional, a field becomes sensitive (it stops being delivered), a relation points elsewhere. Safe: additions, renamed labels, help texts, validation rules. `--json` for scripts and agents; `--exit-code` exits 1 when anything changed, for CI.
+Breaking: a collection, field or option the site may rely on disappears, a type changes, a required field becomes optional, a field becomes sensitive (it stops being delivered), a relation points elsewhere. Safe: additions, renamed labels, help texts, validation rules — and a renamed key while its old one is still an alias (`> price  renamed to “amount” — “price” still works as an alias`): the site keeps reading it, the rest of the field is compared under the new key, and `types generate` types the old key `@deprecated`. Once the alias is removed in Mapled the old key is a removed field. `--json` for scripts and agents; `--exit-code` exits 1 when anything changed, for CI.
+
+The pin keeps formulas of computed fields and previous keys. (A pin written by 0.5.0 lost the formulas, so its hash never matched a project that has computed fields — run `schema pull` once after upgrading.)
 
 ## Scan the code into a manifest
 
@@ -153,7 +155,7 @@ Mapled doctor — Dolphin Landing
 ✓ MAPLED.md            MAPLED.md matches the schema (3f9a1c2b4d5e) and manifest v3
 ✓ Environment          MAPLED_KEY and MAPLED_WEBHOOK_SECRET in .env.local
 ✓ Secrets in git       No env files or Mapled secrets are tracked.
-✓ @mapled/next         0.6.0 (current)
+✓ @mapled/next         0.7.0 (current)
 ✓ mapled CLI           0.2.0 (current)
 ✓ Revalidation route   app/api/mapled/revalidate/route.ts
 ⚠ Preview route        app/api/mapled/preview/route.ts is missing — mount createPreviewHandler from "@mapled/next/server" so Preview from Mapled works.

package/dist/manifest.d.ts

@@ -62,6 +62,8 @@ export type SchemaIndex = Map<string, {
         displayName: string;
         type: string;
     }>;
+    /** previous key → current key (§33.5): a binding on it still works, through the alias */
+    aliases: Map<string, string>;
 }>;
 export declare function indexSchema(schema: Schema): SchemaIndex;
 /** What a well-formed manifest still gets wrong: bindings the schema

package/dist/manifest.js

@@ -242,13 +242,16 @@ export function indexSchema(schema) {
     const index = new Map();
     for (const c of schema.collections) {
         const fields = new Map();
+        const aliases = new Map();
         // a computed field (§14.9) binds as a field of its result type
         const COMPUTED_AS = { number: "number", text: "short_text", boolean: "boolean", date: "date", datetime: "datetime" };
         for (const f of c.fields) {
             const type = f.type === "computed" && f.computed ? (COMPUTED_AS[f.computed.resultType] ?? f.type) : f.type;
             fields.set(f.key, { displayName: f.displayName, type });
+            for (const a of f.aliases ?? [])
+                aliases.set(a, f.key);
         }
-        index.set(c.key, { displayName: c.displayName, kind: c.kind, fields });
+        index.set(c.key, { displayName: c.displayName, kind: c.kind, fields, aliases });
     }
     return index;
 }
@@ -278,7 +281,11 @@ export async function checkManifest(manifest, opts) {
                 warn(`${at}.collection`, `${who}: no collection "${b.collection}" in the schema — Mapled marks it outdated.`);
             else if (b.field) {
                 const field = collection.fields.get(b.field);
-                if (!field) {
+                const renamedTo = collection.aliases.get(b.field);
+                if (!field && renamedTo) {
+                    warn(`${at}.field`, `${who}: "${b.field}" in "${collection.displayName}" was renamed to "${renamedTo}" — it still works through an alias, and Mapled marks the binding outdated. Read "${renamedTo}", then remove the alias.`);
+                }
+                else if (!field) {
                     warn(`${at}.field`, `${who}: no field "${b.field}" in "${collection.displayName}" — Mapled marks it outdated.`);
                 }
                 else {

package/dist/pin.d.ts

@@ -20,7 +20,7 @@ export declare function readPin(dir: string): Promise<{
 } | null>;
 export declare function writePin(dir: string, pin: SchemaPin): Promise<string>;
 export type Severity = "breaking" | "safe";
-export type ChangeOp = "added" | "removed" | "changed";
+export type ChangeOp = "added" | "removed" | "changed" | "renamed";
 export type SchemaChange = {
     scope: "collection" | "field" | "subfield";
     collection: string;
@@ -33,7 +33,10 @@ export type SchemaChange = {
 };
 /** What changed between two schemas, judged for a site that reads the
     content: anything that can make a read fail or a value disappear is
-    breaking; additions and renames of labels are safe. */
+    breaking; additions and renames of labels are safe. A renamed key
+    (§33.5) is safe while the old one is still an alias of the field —
+    the site keeps reading it — and the rest of the field is compared
+    under its new key; once the alias is removed it is a removed field. */
 export declare function diffSchema(before: SchemaCollection[], after: SchemaCollection[]): SchemaChange[];
 /** The diff as terminal lines: one heading per collection, one line per
     change, the severity in the last column. */

package/dist/pin.js

@@ -44,6 +44,11 @@ function pinField(f) {
         out.validation = f.validation;
     if (f.defaultValue !== undefined && f.defaultValue !== null)
         out.defaultValue = f.defaultValue;
+    // the formula is part of the schema hash: a pin without it would never match the live schema
+    if (f.type === "computed" && f.computed)
+        out.computed = { expression: f.computed.expression, resultType: f.computed.resultType };
+    if (f.aliases && f.aliases.length > 0)
+        out.aliases = [...f.aliases];
     return out;
 }
 /** The schema reduced to what the pin keeps — the live answer of
@@ -143,7 +148,10 @@ function sameJson(a, b) {
 }
 /** What changed between two schemas, judged for a site that reads the
     content: anything that can make a read fail or a value disappear is
-    breaking; additions and renames of labels are safe. */
+    breaking; additions and renames of labels are safe. A renamed key
+    (§33.5) is safe while the old one is still an alias of the field —
+    the site keeps reading it — and the rest of the field is compared
+    under its new key; once the alias is removed it is a removed field. */
 export function diffSchema(before, after) {
     const changes = [];
     const names = new Map();
@@ -171,13 +179,21 @@ export function diffSchema(before, after) {
             col(`name ${q(b.displayName)} → ${q(a.displayName)}`, "safe");
         const afterFields = new Map(a.fields.map((f) => [f.key, f]));
         const beforeFields = new Map(b.fields.map((f) => [f.key, f]));
+        const renamedTo = new Set();
         for (const bf of b.fields) {
-            const af = afterFields.get(bf.key);
+            let af = afterFields.get(bf.key);
             if (!af) {
-                changes.push({ ...base, scope: "field", field: bf.key, op: "removed", detail: `removed — ${describeType(bf, names)}`, severity: "breaking" });
-                continue;
+                const heir = a.fields.find((f) => !beforeFields.has(f.key) && !renamedTo.has(f.key) && f.aliases?.includes(bf.key));
+                if (!heir) {
+                    changes.push({ ...base, scope: "field", field: bf.key, op: "removed", detail: `removed — ${describeType(bf, names)}`, severity: "breaking" });
+                    continue;
+                }
+                renamedTo.add(heir.key);
+                changes.push({ ...base, scope: "field", field: bf.key, op: "renamed", detail: `renamed to ${q(heir.key)} — ${q(bf.key)} still works as an alias`, severity: "safe" });
+                af = heir;
             }
-            const push = (op, detail, severity) => changes.push({ ...base, scope: "field", field: bf.key, op, detail, severity });
+            const under = af.key;
+            const push = (op, detail, severity) => changes.push({ ...base, scope: "field", field: under, op, detail, severity });
             diffCommon(bf, af, names, push);
             if (bf.type === "relation" && af.type === "relation" && bf.relation && af.relation) {
                 if (bf.relation.target !== af.relation.target) {
@@ -209,7 +225,7 @@ export function diffSchema(before, after) {
                 const beforeSubs = new Map(bf.group.fields.map((s) => [s.key, s]));
                 for (const bs of bf.group.fields) {
                     const as = afterSubs.get(bs.key);
-                    const sub = `${bf.key}.${bs.key}`;
+                    const sub = `${under}.${bs.key}`;
                     if (!as) {
                         changes.push({ ...base, scope: "subfield", field: sub, op: "removed", detail: `removed — ${describeType(bs, names)}`, severity: "breaking" });
                         continue;
@@ -222,7 +238,7 @@ export function diffSchema(before, after) {
                     changes.push({
                         ...base,
                         scope: "subfield",
-                        field: `${bf.key}.${as.key}`,
+                        field: `${under}.${as.key}`,
                         op: "added",
                         detail: `added — ${describeType(as, names)}, ${as.required ? "required" : "optional"}`,
                         severity: "safe",
@@ -235,7 +251,7 @@ export function diffSchema(before, after) {
                 push("changed", "default value changed", "safe");
         }
         for (const af of a.fields) {
-            if (beforeFields.has(af.key))
+            if (beforeFields.has(af.key) || renamedTo.has(af.key))
                 continue;
             changes.push({
                 ...base,
@@ -261,7 +277,7 @@ export function diffSchema(before, after) {
     }
     return changes;
 }
-const GLYPH = { added: "+", removed: "-", changed: "~" };
+const GLYPH = { added: "+", removed: "-", changed: "~", renamed: ">" };
 /** The diff as terminal lines: one heading per collection, one line per
     change, the severity in the last column. */
 export function formatChanges(changes, paint = (_, t) => t) {

package/dist/schema.d.ts

@@ -37,6 +37,10 @@ export type SchemaField = {
         expression: string;
         resultType: string;
     } | null;
+    /** Previous keys (§33.5): the field was renamed, and Mapled serves and
+        accepts it under these too until they are removed. Not part of the
+        schema hash — a rename changes the key, which is. */
+    aliases?: string[];
 };
 export type SchemaCollection = {
     key: string;

package/dist/types.js

@@ -115,14 +115,26 @@ function fieldLine(key, displayName, required, rendered) {
 function renderSubField(sub) {
     return fieldLine(sub.key, sub.displayName, sub.required, scalarType(sub.type, sub.options));
 }
+/** The field's line, followed by one per previous key (§33.5): a
+    renamed field is still delivered under them, typed as the field, and
+    the editor strikes them through until the site stops reading them. */
 function renderField(field, owner, names, extras) {
+    const { required, rendered } = renderedField(field, owner, names, extras);
+    const lines = [fieldLine(field.key, field.displayName, required, rendered)];
+    for (const alias of field.aliases ?? []) {
+        lines.push(`  /** @deprecated Renamed to "${comment(field.key)}" — still delivered under this key until the alias is removed in Mapled. */\n` +
+            `  ${prop(alias)}?: ${rendered.type} | null;`);
+    }
+    return lines.join("\n");
+}
+function renderedField(field, owner, names, extras) {
     if (field.type === "relation" && field.relation) {
         const target = names.get(field.relation.target) ?? field.relation.target;
         const many = field.relation.cardinality === "many";
-        return fieldLine(field.key, field.displayName, field.required, {
-            type: many ? "MapledRecordId[]" : "MapledRecordId",
-            note: `relation to ${comment(target)}${many ? " (many)" : ""}`,
-        });
+        return {
+            required: field.required,
+            rendered: { type: many ? "MapledRecordId[]" : "MapledRecordId", note: `relation to ${comment(target)}${many ? " (many)" : ""}` },
+        };
     }
     if (field.type === "group" && field.group) {
         const itemName = `${owner}${pascal(wordsOf(field.key))}${field.group.repeatable ? "Item" : ""}`;
@@ -136,15 +148,12 @@ function renderField(field, owner, names, extras) {
         const note = field.group.repeatable
             ? `group${field.group.maxItems ? `, up to ${field.group.maxItems} items` : ""}`
             : "group";
-        return fieldLine(field.key, field.displayName, field.required, {
-            type: field.group.repeatable ? `${itemName}[]` : itemName,
-            note,
-        });
+        return { required: field.required, rendered: { type: field.group.repeatable ? `${itemName}[]` : itemName, note } };
     }
     if (field.type === "computed" && field.computed) {
-        return fieldLine(field.key, field.displayName, false, computedType(field.computed.resultType));
+        return { required: false, rendered: computedType(field.computed.resultType) };
     }
-    return fieldLine(field.key, field.displayName, field.required, scalarType(field.type, field.options));
+    return { required: field.required, rendered: scalarType(field.type, field.options) };
 }
 /** Unique type names: the singular PascalCase of the key; the raw
     PascalCase when two keys meet there; a numeric suffix as a last resort. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Mapled CLI — sign in, link a project, generate TypeScript types for its content and check the site's integration.",
   "license": "MIT",
   "homepage": "https://mapled.io",