@mapled/cli 0.1.0 → 0.3.0

package/dist/pin.js

@@ -0,0 +1,297 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { typeLabel } from "./manifest.js";
+import { schemaHash } from "./schema.js";
+/** mapled/schema.json — the repository's pin of the schema it was last
+    synced with (§21.5). `mapled schema diff` compares it with the live
+    schema and says which changes a site that READS the content must
+    care about; `schema pull` and `types generate` move the pin. The
+    file is deterministic: no timestamps, ids or counters. */
+export const SCHEMA_FILE = "mapled/schema.json";
+function pinSubField(s) {
+    const out = { key: s.key, displayName: s.displayName, type: s.type, required: s.required === true };
+    out.helpText = s.helpText ?? null;
+    out.options = s.options ?? null;
+    out.sensitive = s.sensitive === true;
+    return out;
+}
+function pinField(f) {
+    const out = {
+        key: f.key,
+        displayName: f.displayName,
+        type: f.type,
+        required: f.required === true,
+        helpText: f.helpText ?? null,
+        options: f.options ?? null,
+        relation: f.relation
+            ? {
+                target: f.relation.target,
+                cardinality: f.relation.cardinality,
+                ...(f.relation.onDelete ? { onDelete: f.relation.onDelete } : {}),
+            }
+            : null,
+        sensitive: f.sensitive === true,
+        group: f.group
+            ? {
+                repeatable: f.group.repeatable,
+                ...(f.group.maxItems ? { maxItems: f.group.maxItems } : {}),
+                fields: f.group.fields.map(pinSubField),
+            }
+            : null,
+    };
+    if (f.validation !== undefined && f.validation !== null)
+        out.validation = f.validation;
+    if (f.defaultValue !== undefined && f.defaultValue !== null)
+        out.defaultValue = f.defaultValue;
+    return out;
+}
+/** The schema reduced to what the pin keeps — the live answer of
+    GET /v1/agent/schema without ids, positions and counters. */
+export function pinSchema(schema, project) {
+    const collections = schema.collections.map((c) => ({
+        key: c.key,
+        displayName: c.displayName,
+        kind: c.kind,
+        accessClass: c.accessClass,
+        mode: c.mode,
+        fields: c.fields.map(pinField),
+    }));
+    return { project, hash: schemaHash({ collections }), collections };
+}
+export function parsePin(raw, file) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError(`${file} isn't valid JSON — delete it and run \`mapled schema pull\` again.`);
+    }
+    const obj = data && typeof data === "object" && !Array.isArray(data) ? data : null;
+    const collections = obj?.collections;
+    if (!obj ||
+        typeof obj.project !== "string" ||
+        typeof obj.hash !== "string" ||
+        !Array.isArray(collections) ||
+        collections.some((c) => !c || typeof c !== "object" || typeof c.key !== "string" || !Array.isArray(c.fields))) {
+        throw new CliError(`${file} isn't a schema pin written by \`mapled schema pull\` — delete it and pull again.`);
+    }
+    return pinSchema({ collections: collections }, obj.project);
+}
+export async function readPin(dir) {
+    const file = path.join(dir, SCHEMA_FILE);
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+    return { file, pin: parsePin(raw, SCHEMA_FILE) };
+}
+export async function writePin(dir, pin) {
+    const file = path.join(dir, SCHEMA_FILE);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(pin, null, 2) + "\n");
+    return file;
+}
+const q = (s) => `“${s}”`;
+function describeType(f, names) {
+    if (f.type === "relation" && "relation" in f && f.relation) {
+        const target = names.get(f.relation.target) ?? f.relation.target;
+        return `relation to ${target}${f.relation.cardinality === "many" ? " (many)" : ""}`;
+    }
+    if (f.type === "group" && "group" in f && f.group) {
+        return `group of ${f.group.fields.length} field${f.group.fields.length === 1 ? "" : "s"}${f.group.repeatable ? ", repeatable" : ""}`;
+    }
+    return typeLabel(f.type);
+}
+function diffCommon(before, after, names, push) {
+    if (before.type !== after.type) {
+        push("changed", `${describeType(before, names)} → ${describeType(after, names)}`, "breaking");
+    }
+    if (before.required === true && after.required !== true) {
+        push("changed", "required → optional (may be empty now)", "breaking");
+    }
+    else if (before.required !== true && after.required === true) {
+        push("changed", "optional → required", "safe");
+    }
+    if (before.displayName !== after.displayName)
+        push("changed", `name ${q(before.displayName)} → ${q(after.displayName)}`, "safe");
+    if ((before.helpText ?? null) !== (after.helpText ?? null))
+        push("changed", "help text changed", "safe");
+    const beforeOptions = before.options ?? [];
+    const afterOptions = after.options ?? [];
+    for (const o of beforeOptions)
+        if (!afterOptions.includes(o))
+            push("changed", `option ${q(o)} removed`, "breaking");
+    for (const o of afterOptions)
+        if (!beforeOptions.includes(o))
+            push("changed", `option ${q(o)} added`, "safe");
+    if (before.sensitive !== true && after.sensitive === true) {
+        push("changed", "now sensitive — no longer delivered to the site", "breaking");
+    }
+    else if (before.sensitive === true && after.sensitive !== true) {
+        push("changed", "no longer sensitive — delivered to the site now", "safe");
+    }
+}
+function sameJson(a, b) {
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+/** 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. */
+export function diffSchema(before, after) {
+    const changes = [];
+    const names = new Map();
+    for (const c of before)
+        names.set(c.key, c.displayName);
+    for (const c of after)
+        names.set(c.key, c.displayName);
+    const afterByKey = new Map(after.map((c) => [c.key, c]));
+    const beforeByKey = new Map(before.map((c) => [c.key, c]));
+    for (const b of before) {
+        const a = afterByKey.get(b.key);
+        const base = { collection: b.key, collectionName: a?.displayName ?? b.displayName };
+        if (!a) {
+            changes.push({ ...base, scope: "collection", op: "removed", detail: "removed", severity: "breaking" });
+            continue;
+        }
+        const col = (detail, severity) => changes.push({ ...base, scope: "collection", op: "changed", detail, severity });
+        if (b.kind !== a.kind)
+            col(`${b.kind} → ${a.kind}`, "breaking");
+        if (b.accessClass !== a.accessClass)
+            col(`access ${b.accessClass} → ${a.accessClass}`, "breaking");
+        if (b.mode !== a.mode)
+            col(`mode ${b.mode} → ${a.mode}`, "breaking");
+        if (b.displayName !== a.displayName)
+            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]));
+        for (const bf of b.fields) {
+            const 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 push = (op, detail, severity) => changes.push({ ...base, scope: "field", field: bf.key, 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) {
+                    push("changed", `relation to ${names.get(bf.relation.target) ?? bf.relation.target} → ${names.get(af.relation.target) ?? af.relation.target}`, "breaking");
+                }
+                if (bf.relation.cardinality !== af.relation.cardinality)
+                    push("changed", `${bf.relation.cardinality} → ${af.relation.cardinality}`, "breaking");
+                if ((bf.relation.onDelete ?? null) !== (af.relation.onDelete ?? null)) {
+                    push("changed", `on delete ${bf.relation.onDelete ?? "default"} → ${af.relation.onDelete ?? "default"}`, "safe");
+                }
+            }
+            if (bf.type === "group" && af.type === "group" && bf.group && af.group) {
+                if (bf.group.repeatable !== af.group.repeatable) {
+                    push("changed", bf.group.repeatable ? "repeatable → single item" : "single item → repeatable", "breaking");
+                }
+                if ((bf.group.maxItems ?? null) !== (af.group.maxItems ?? null)) {
+                    const limit = (n) => (n ? `up to ${n} items` : "no item limit");
+                    push("changed", `${limit(bf.group.maxItems)} → ${limit(af.group.maxItems)}`, "safe");
+                }
+                const afterSubs = new Map(af.group.fields.map((s) => [s.key, s]));
+                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}`;
+                    if (!as) {
+                        changes.push({ ...base, scope: "subfield", field: sub, op: "removed", detail: `removed — ${describeType(bs, names)}`, severity: "breaking" });
+                        continue;
+                    }
+                    diffCommon(bs, as, names, (op, detail, severity) => changes.push({ ...base, scope: "subfield", field: sub, op, detail, severity }));
+                }
+                for (const as of af.group.fields) {
+                    if (beforeSubs.has(as.key))
+                        continue;
+                    changes.push({
+                        ...base,
+                        scope: "subfield",
+                        field: `${bf.key}.${as.key}`,
+                        op: "added",
+                        detail: `added — ${describeType(as, names)}, ${as.required ? "required" : "optional"}`,
+                        severity: "safe",
+                    });
+                }
+            }
+            if (!sameJson(bf.validation, af.validation))
+                push("changed", "validation changed", "safe");
+            if (!sameJson(bf.defaultValue, af.defaultValue))
+                push("changed", "default value changed", "safe");
+        }
+        for (const af of a.fields) {
+            if (beforeFields.has(af.key))
+                continue;
+            changes.push({
+                ...base,
+                scope: "field",
+                field: af.key,
+                op: "added",
+                detail: `added — ${describeType(af, names)}, ${af.required ? "required" : "optional"}`,
+                severity: "safe",
+            });
+        }
+    }
+    for (const a of after) {
+        if (beforeByKey.has(a.key))
+            continue;
+        changes.push({
+            collection: a.key,
+            collectionName: a.displayName,
+            scope: "collection",
+            op: "added",
+            detail: `new ${a.kind} — ${a.fields.length} field${a.fields.length === 1 ? "" : "s"}`,
+            severity: "safe",
+        });
+    }
+    return changes;
+}
+const GLYPH = { added: "+", removed: "-", changed: "~" };
+/** 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) {
+    const lines = [];
+    const order = [];
+    const byCollection = new Map();
+    for (const c of changes) {
+        if (!byCollection.has(c.collection)) {
+            byCollection.set(c.collection, []);
+            order.push(c.collection);
+        }
+        byCollection.get(c.collection).push(c);
+    }
+    const width = Math.max(0, ...changes.filter((c) => c.field).map((c) => c.field.length));
+    const detailWidth = Math.max(0, ...changes.map((c) => c.detail.length));
+    for (const key of order) {
+        const list = byCollection.get(key);
+        const name = list[0].collectionName;
+        const whole = list.find((c) => c.scope === "collection" && c.op !== "changed");
+        if (whole) {
+            lines.push(`${GLYPH[whole.op]} ${name} (${key})  ${whole.detail.padEnd(detailWidth)}  ${paint(whole.severity, whole.severity)}`);
+            continue;
+        }
+        lines.push(`${name} (${key})`);
+        for (const c of list) {
+            const label = c.scope === "collection" ? "(collection)" : c.field;
+            lines.push(`  ${GLYPH[c.op]} ${label.padEnd(width)}  ${c.detail.padEnd(detailWidth)}  ${paint(c.severity, c.severity)}`);
+        }
+    }
+    return lines;
+}
+export function summarizeChanges(changes) {
+    const breaking = changes.filter((c) => c.severity === "breaking").length;
+    const safe = changes.length - breaking;
+    const p = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+    if (changes.length === 0)
+        return "No changes";
+    const parts = [];
+    if (breaking > 0)
+        parts.push(`${p(breaking, "breaking change")}`);
+    if (safe > 0)
+        parts.push(`${p(safe, "safe change")}`);
+    return parts.join(", ");
+}

package/dist/scan.d.ts

@@ -0,0 +1,73 @@
+import type * as TS from "typescript";
+import { type Manifest, type ManifestBinding, type ManifestPage } from "./manifest.js";
+import type { Schema } from "./schema.js";
+/** `mapled scan` (§19.5, §21.4 — the standalone scanner of wave 2): reads
+    the site's source and writes down what the code reads from Mapled —
+    the pages (from the framework's file conventions) and one binding per
+    place a collection or field is used. The parser is the repository's
+    own TypeScript (AST, per §19.6); without it a tokenizer finds the
+    reads but not the fields. Source code never leaves the machine: only
+    the manifest does, and only when `bindings push` is run. */
+export type TypeScriptModule = typeof TS;
+export type ScanOptions = {
+    framework?: string | null;
+    schema: Schema;
+    ts: TypeScriptModule | null;
+    /** Files to read at most (a note is added past it). */
+    maxFiles?: number;
+};
+export type Read = {
+    method: string;
+    collection: string;
+    fields: Set<string>;
+    /** Where the read happens (the file and the function it sits in). */
+    file: string;
+    component: string | null;
+    /** Fields traced into other components: field → { component, file }. */
+    fieldSites: Map<string, {
+        component: string | null;
+        file: string;
+    }>;
+    bySlug: boolean;
+};
+export type ScanResult = {
+    framework: string | null;
+    parser: "typescript" | "tokens";
+    files: number;
+    pages: ManifestPage[];
+    bindings: ManifestBinding[];
+    notes: string[];
+};
+export declare const SDK_METHODS: Set<string>;
+/** The repository's TypeScript, when it has one; the CLI ships none. */
+export declare function loadTypeScript(dir: string): TypeScriptModule | null;
+export type RouteMap = {
+    pages: Map<string, string>;
+    layouts: Map<string, string>;
+};
+export declare function detectRoutes(files: string[], framework: string | null): RouteMap;
+export type Token = {
+    kind: "ident" | "string" | "punct";
+    value: string;
+};
+/** JavaScript tokens: identifiers, string literals and punctuation, with
+    comments and template bodies dropped. A regex literal after an
+    operator is skipped; JSX text is read as code, so an apostrophe in
+    prose can swallow a stretch — a false negative, never a crash. */
+export declare function tokenize(text: string): Token[];
+export declare function routeKey(route: string): string;
+export declare function scanRepository(dir: string, opts: ScanOptions): Promise<ScanResult>;
+export type MergeResult = {
+    manifest: Manifest;
+    added: string[];
+    changed: string[];
+    unchanged: string[];
+    /** Bindings the scan didn't produce: kept (or dropped with prune). */
+    kept: string[];
+    dropped: string[];
+};
+/** The scan's bindings replace the ones with the same key; bindings the
+    scanner can't see (an agent's, hand-written) stay unless pruned. */
+export declare function mergeManifest(existing: Manifest | null, scan: ScanResult, opts: {
+    prune: boolean;
+}): MergeResult;