@cardanvil/frame-kit 0.2.0

package/dist/cli/report.js

@@ -0,0 +1,74 @@
+/** Renders a problem as one line: `frame › path — message`. */
+export function formatProblem(problem) {
+    const where = [problem.frame, problem.path].filter(Boolean).join(" › ");
+    return where ? `${where} — ${problem.message}` : problem.message;
+}
+/**
+ * GitHub Actions workflow-command form, which turns a problem into an inline
+ * annotation on the pull request diff. Emitting these from here is why neither
+ * CI workflow needs a reporting step of its own.
+ */
+function toAnnotation(problem) {
+    const parts = [
+        problem.file ? `file=${problem.file}` : undefined,
+        problem.frame ? `title=${problem.frame}` : undefined,
+    ].filter((part) => part !== undefined);
+    const head = `::${problem.severity} ${parts.join(",")}`;
+    // Newlines terminate a workflow command, so they have to be escaped.
+    const body = formatProblem(problem).replace(/\r?\n/g, "%0A");
+    return `${head}::${body}`;
+}
+export class Reporter {
+    problems = [];
+    add(problem) {
+        this.problems.push(problem);
+    }
+    error(problem) {
+        this.add({ ...problem, severity: "error" });
+    }
+    warn(problem) {
+        this.add({ ...problem, severity: "warning" });
+    }
+    get errors() {
+        return this.problems.filter((problem) => problem.severity === "error");
+    }
+    get warnings() {
+        return this.problems.filter((problem) => problem.severity === "warning");
+    }
+    get ok() {
+        return this.errors.length === 0;
+    }
+    /** Human-readable lines for a terminal. */
+    toText() {
+        return this.problems
+            .map((problem) => `${problem.severity}: ${formatProblem(problem)}`)
+            .join("\n");
+    }
+    /** Workflow commands, one per problem. Empty outside GitHub Actions. */
+    toAnnotations() {
+        return this.problems.map(toAnnotation).join("\n");
+    }
+    toMarkdown() {
+        if (this.problems.length === 0) {
+            return "";
+        }
+        const rows = this.problems.map((problem) => {
+            const cells = [
+                problem.severity,
+                problem.frame ?? "",
+                problem.path ?? problem.file ?? "",
+                problem.message.replace(/\r?\n/g, " ").replaceAll("|", String.raw `\|`),
+            ];
+            return `| ${cells.join(" | ")} |`;
+        });
+        return [
+            "| | Frame | Where | Problem |",
+            "| --- | --- | --- | --- |",
+            ...rows,
+        ].join("\n");
+    }
+}
+/** True when running inside GitHub Actions, where annotations are understood. */
+export function inGitHubActions() {
+    return process.env.GITHUB_ACTIONS === "true";
+}

package/dist/cli/schema.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The formats this package defines, and what each is called on disk.
+ *
+ * Useful to anything that is not TypeScript — an editor offering completion in
+ * `frame.meta.json`, or a marketplace validating an index it fetched.
+ * TypeScript consumers should use the zod schemas directly instead.
+ */
+declare const SCHEMA_FILES: {
+    /** A frame descriptor. Authors write these by hand, so completion helps. */
+    readonly meta: "frame-meta.schema.json";
+    /** A release index. What an aggregator validates before trusting a repo. */
+    readonly index: "frame-index.schema.json";
+    /** A `.cardframe`'s frame.json. Large — emitted on request, not shipped. */
+    readonly manifest: "frame-manifest.schema.json";
+    /** A frame object. Large — emitted on request, not shipped. */
+    readonly frame: "frame.schema.json";
+};
+export type SchemaName = keyof typeof SCHEMA_FILES;
+export declare const SCHEMA_NAMES: SchemaName[];
+/**
+ * Emitted with the *input* view: these describe documents being written or
+ * read, where a field with a default is optional. The output view would mark
+ * those required, which is wrong for a document an author is authoring.
+ */
+export declare function toJsonSchema(name: SchemaName): unknown;
+export declare function schemaFilename(name: SchemaName): string;
+/**
+ * The schemas small enough, and useful enough, to ship in the package. The
+ * other two are hundreds of kilobytes and have no consumer that could not use
+ * the zod schema instead.
+ */
+export declare const SHIPPED_SCHEMAS: SchemaName[];
+export {};

package/dist/cli/schema.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { FrameManifestSchema } from "../manifest/contract.js";
+import { FrameSchema } from "../schema/frame.js";
+import { FrameMetaSchema } from "../schema/frameMeta.js";
+import { FrameIndexSchema } from "./frameIndex.js";
+/**
+ * The formats this package defines, and what each is called on disk.
+ *
+ * Useful to anything that is not TypeScript — an editor offering completion in
+ * `frame.meta.json`, or a marketplace validating an index it fetched.
+ * TypeScript consumers should use the zod schemas directly instead.
+ */
+const SCHEMA_FILES = {
+    /** A frame descriptor. Authors write these by hand, so completion helps. */
+    meta: "frame-meta.schema.json",
+    /** A release index. What an aggregator validates before trusting a repo. */
+    index: "frame-index.schema.json",
+    /** A `.cardframe`'s frame.json. Large — emitted on request, not shipped. */
+    manifest: "frame-manifest.schema.json",
+    /** A frame object. Large — emitted on request, not shipped. */
+    frame: "frame.schema.json",
+};
+/**
+ * Annotated as `z.ZodType` on purpose. Without it TypeScript inlines each
+ * schema's full inferred type into this module's declarations, which turns a
+ * fifty-line file into a megabyte of .d.ts.
+ */
+const SCHEMAS = {
+    meta: FrameMetaSchema,
+    index: FrameIndexSchema,
+    manifest: FrameManifestSchema,
+    frame: FrameSchema,
+};
+export const SCHEMA_NAMES = Object.keys(SCHEMA_FILES);
+/**
+ * Emitted with the *input* view: these describe documents being written or
+ * read, where a field with a default is optional. The output view would mark
+ * those required, which is wrong for a document an author is authoring.
+ */
+export function toJsonSchema(name) {
+    return z.toJSONSchema(SCHEMAS[name], { io: "input" });
+}
+export function schemaFilename(name) {
+    return SCHEMA_FILES[name];
+}
+/**
+ * The schemas small enough, and useful enough, to ship in the package. The
+ * other two are hundreds of kilobytes and have no consumer that could not use
+ * the zod schema instead.
+ */
+export const SHIPPED_SCHEMAS = ["meta", "index"];

package/dist/cli/stableJson.d.ts

@@ -0,0 +1,11 @@
+/**
+ * JSON with object keys sorted, recursively.
+ *
+ * A manifest's bytes should depend only on the frame, never on the order zod
+ * happened to build an object in — so two builds of the same source produce an
+ * identical `frame.json`, and diffing two releases is diffing text.
+ *
+ * Arrays keep their order: `assets` is already sorted by path, and layout
+ * ordering is meaningful.
+ */
+export declare function stableStringify(value: unknown): string;

package/dist/cli/stableJson.js

@@ -0,0 +1,27 @@
+/**
+ * JSON with object keys sorted, recursively.
+ *
+ * A manifest's bytes should depend only on the frame, never on the order zod
+ * happened to build an object in — so two builds of the same source produce an
+ * identical `frame.json`, and diffing two releases is diffing text.
+ *
+ * Arrays keep their order: `assets` is already sorted by path, and layout
+ * ordering is meaningful.
+ */
+export function stableStringify(value) {
+    return `${JSON.stringify(sortKeys(value), null, 2)}\n`;
+}
+function sortKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeys);
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    const source = value;
+    const sorted = {};
+    for (const key of Object.keys(source).sort()) {
+        sorted[key] = sortKeys(source[key]);
+    }
+    return sorted;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./authoring/index.js";
+export * from "./schema/index.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./authoring/index.js";
+export * from "./schema/index.js";