rovecode 0.3.2 → 0.4.0-beta.2

package/src/market/types.ts

@@ -1,236 +0,0 @@
-/** One market, three kinds. `rovecode market …`, the sextant's /market and the site's market page all read
- *  the SAME item type: an MCP server, a skill and a plugin differ in what installing them means, not in how
- *  they are found, described or shown.
- *
- *  Design rules this file exists to hold:
- *  - MCP is WRAPPED, never rewritten: `install.kind === "mcp"` carries the existing `MarketEntry`
- *    (src/mcp/market.ts) untouched, so the curated shelf, the registry re-typing and the install planner
- *    keep working exactly as they do today. A new kind is a new arm of `InstallSpec`, not a new pipeline.
- *  - Everything a UI needs to draw a row is on the item itself (title, publisher, one line, tags, version,
- *    source). Anything that needs the local filesystem — installed? update available? — is a separate
- *    `InstalledState`, because it changes without the catalog changing.
- *  - Catalog data is UNTRUSTED. These types describe what a validator PRODUCES (registry.ts), never what a
- *    response happens to contain. The caps live here so every source is bounded the same way.
- *  - Nothing here reads a file, spawns a process or touches the network: types + pure helpers only, so
- *    importing this module costs nothing at boot (the lazy-import rule). */
-
-import type { MarketEntry } from "../mcp/market.ts";
-
-export type MarketKind = "mcp" | "skill" | "plugin";
-/** where the item was found. "curated" = built into rovecode, hand-checked; "registry" = a live remote
- *  index (the MCP registry today); "catalog" = a rovecode-published catalog file for skills and plugins */
-export type MarketSource = "curated" | "registry" | "catalog";
-/** user = ~/.rovecode (every project sees it) · project = this repo (trust-gated, committed with the repo) */
-export type MarketScope = "user" | "project";
-
-/** Hard ceilings on anything a source contributes. A field past its cap is truncated (strings) or dropped
- *  (list items) — never an error, because one bad row must not blank a whole catalog. */
-export const LIMITS = {
-  /** response body accepted from a remote catalog */
-  body: 2 * 1024 * 1024,
-  /** items accepted from one source */
-  items: 200,
-  /** any short string (id, title, publisher, version, url) */
-  str: 300,
-  /** the one-line description a row shows */
-  desc: 500,
-  /** tags per item, and files per skill */
-  list: 32,
-  /** environment variables one item may declare */
-  env: 24,
-  /** an item's documentation body: markdown, not a label. Nothing else here is remotely this big, which is
-   *  exactly why it needs its own cap — run a 24 KB body through `str()` and it comes back silently cut to
-   *  300 characters, still a valid string, and nobody notices. */
-  docs: 24 * 1024,
-} as const;
-
-/** An item's own documentation, fetched at BUILD time and carried in the catalog.
- *
- *  Never fetched at runtime. The market has to work offline and the site's page is static, and pulling
- *  third-party text into a UI at display time is not something worth doing for a docs pane. The body is
- *  carried as TEXT and nothing more: it is never executed, never evaluated, never parsed as HTML here —
- *  each surface renders it safely on its own side.
- *
- *  Absent when upstream had no readable doc. A row without docs is a normal row, not a broken one. */
-export interface ItemDocs {
-  /** the exact URL it was read from, so a reader can go to the original */
-  source: string;
-  format: "markdown";
-  /** the body's length in bytes BEFORE truncation, so a UI can say how much is missing */
-  bytes: number;
-  truncated: boolean;
-  /** Markdown text, capped at LIMITS.docs. OPTIONAL on purpose: the search path does not carry bodies
-   *  (they are ~200 KB the search never reads), so a row from `searchMarket` has the metadata and
-   *  `body === undefined`. `undefined` means "not carried on this call" and is not the same as an empty
-   *  document — a UI must send the reader to `market docs <id>` rather than say there is nothing. */
-  body?: string;
-}
-
-/** An environment variable an item needs. Same shape the MCP side already uses (mcp/market.ts EnvSpec):
- *  `secret: true` is asked masked on a shell and NEVER written into a project file — it is written as
- *  `${NAME}` and read from the environment at launch. */
-export interface MarketEnv {
-  name: string;
-  description?: string;
-  required: boolean;
-  secret: boolean;
-  /** a value the catalog already knows (a default port, a public URL): not a question */
-  default?: string;
-}
-
-/** What installing this item actually does. One arm per kind — the arm carries whatever the kind's existing
- *  installer needs, so `install.ts` can delegate without re-deriving anything. */
-export type InstallSpec =
-  /** the MCP entry as mcp/market.ts produced it; mcp/market-install.ts plans and writes it */
-  | { kind: "mcp"; entry: MarketEntry }
-  /** a plugin folder or git URL; src/plugins/install.ts addPlugin() clones and copies it.
-   *  `subfolder` is where the plugin.json lives inside that repo — real plugins live in a monorepo
-   *  (plugins/safety-net), so a repo root is the exception, not the rule. Same escape rules as a skill's. */
-  | { kind: "plugin"; source: string; /** true when `source` is a git URL rather than a local folder */ git: boolean; subfolder?: string }
-  /** a skill: a git repo (optionally a subfolder) or a set of files written verbatim.
-   *  `files` is the offline form — a curated skill ships its SKILL.md in the catalog itself. */
-  | { kind: "skill"; source?: { git: string; subfolder?: string }; files?: { path: string; text: string }[] };
-
-/** One row in the market, whatever its kind. */
-export interface MarketItem {
-  /** what `market install <id>` takes. Unique per kind, not across kinds: `mcp:git` and `skill:git` may
-   *  both exist, which is why resolve.ts accepts `kind:id` and lists candidates when a bare id is ambiguous. */
-  id: string;
-  kind: MarketKind;
-  /** display name; falls back to `id` when a source has none */
-  title: string;
-  /** who publishes it — a namespace, an org, or "unknown" */
-  publisher: string;
-  /** one line, already capped at LIMITS.desc */
-  description: string;
-  source: MarketSource;
-  version?: string;
-  repository?: string;
-  homepage?: string;
-  /** free-form, lowercase, capped; a UI may filter on these but must not depend on any particular tag */
-  tags: string[];
-  /** the source's own status when it is anything but normal ("deprecated", "experimental") */
-  status?: string;
-  /** the licence as the publisher states it ("Apache-2.0", "source-available, not open source", "none stated").
-   *  A field, not a note: a market that installs other people's work has to show this before the yes, and a
-   *  UI will want to filter on it. Free text — an SPDX id is common but not required. */
-  license?: string;
-  /** the variables this item needs before it can run. Empty for most skills and plugins. */
-  env: MarketEnv[];
-  install: InstallSpec;
-  /** the item's own documentation, carried in the catalog — see ItemDocs */
-  docs?: ItemDocs;
-  /** extra lines a catalog wants in the approval preview, in its own words ("copies one SKILL.md, runs
-   *  nothing"). install.ts writes the standard plan from `install`; these are appended verbatim, capped
-   *  like every other list. A catalog that has nothing special to say omits them. */
-  planNote?: string[];
-  /** what a plugin brings, as data rather than as a sentence: "commands", "skills", "agents", "hooks",
-   *  "mcpServers", "tools". The catalog has carried this since the generator was written, but only the
-   *  prose form ("contributes: commands, skills") ever reached a reader — so a caller wanting to filter
-   *  on it had to parse English. The prose stays for the approval preview, which is written for a
-   *  person; this is the same fact for anything that has to choose between two candidates. It describes
-   *  what the catalog CLAIMS, exactly like every other field here, and is no more verified than they are. */
-  contributes?: string[];
-}
-
-/** Local truth about one item, computed from disk (never from a catalog). Kept apart from `MarketItem`
- *  because it changes when the user installs something, not when the catalog updates. Its PRESENCE on a
- *  row means installed — `row.installed === undefined` is the not-installed case, so a UI draws the badge
- *  from one check and never from a boolean that could disagree with the path. */
-export interface InstalledState {
-  /** where it landed: the mcp.json, the plugin folder, the skill folder */
-  path: string;
-  scope: MarketScope;
-  /** the version on disk when it is knowable (a plugin manifest, an mcp entry's recorded version) */
-  version?: string;
-  /** true when the catalog's version is a different string from the installed one. Not a semver compare:
-   *  a UI says "update available", the human reads both numbers. */
-  updateAvailable?: boolean;
-  /** project-scope items only: the trust gate's answer. `undefined` for user scope, which is never gated. */
-  trusted?: boolean;
-}
-
-/** A market row as a UI receives it: the catalog item plus what this machine knows about it.
- *  `installed` present = on disk here; absent = not installed. */
-export interface MarketRow extends MarketItem {
-  installed?: InstalledState;
-}
-
-// ---------------------------------------------------------------- results, never exceptions
-
-/** Why a source produced nothing. A UI draws these differently, so they are distinguishable values and not
- *  one error string: `offline` and `stale` still carry rows, `failed` carries the reason. */
-export type SourceStatus =
-  | { ok: true; from: "live" }
-  /** the network was not tried (--offline, no network): rows come from the cache or the curated shelf */
-  | { ok: true; from: "cache"; ageMs: number }
-  | { ok: true; from: "curated" }
-  /** the source was not consulted at all (an empty query never asks the registry): no rows, no failure */
-  | { ok: true; from: "skipped"; why: string }
-  /** the fetch failed and there was nothing cached: this source contributed no rows */
-  | { ok: false; reason: string };
-
-/** What every listing call returns. Never throws for a data problem — a caller that must distinguish
- *  "nothing matched" from "the registry is down" reads `sources`. */
-export interface MarketResult {
-  items: MarketItem[];
-  /** one entry per source consulted, keyed by a stable name ("mcp:curated", "mcp:registry", "skills", "plugins") */
-  sources: Record<string, SourceStatus>;
-  /** human-readable notes worth showing once (a capped field, a dropped row, a stale cache) */
-  notes: string[];
-}
-
-/** The three-step visibility the MCP market established, generalised: a plan is built and SHOWN, the human
- *  says yes, and only then is anything written. `preview` is the whole plan in the human's words. */
-export interface InstallPlanView {
-  item: MarketItem;
-  /** where the write lands (an mcp.json, a plugins folder, a skills folder) */
-  target: string;
-  scope: MarketScope;
-  /** the lines a CLI prints or a card shows — everything that must be seen before a yes */
-  preview: string[];
-  /** variables that will be asked (shell: masked for secrets) or written as `${NAME}` */
-  asks: MarketEnv[];
-  /** required values nobody can fill for the human (a directory to expose, a database URL) */
-  pending: string[];
-  /** true when this install replaces something already there */
-  replaces?: string;
-}
-
-export type InstallOutcome =
-  | { ok: true; item: MarketItem; target: string; scope: MarketScope;
-      /** variable names the written config now refers to; the human must export them before a restart */
-      envNames: string[];
-      /** project scope only: whether the write was recorded as trusted */
-      trusted?: boolean;
-      /** MCP only: `<…>` placeholders the written entry still carries because nobody answered for them; the
-       *  loader skips the server until a hand replaces them, so `next` says that instead of "restart" */
-      fillIn?: string[];
-      /** MCP install-once only (mcp/local-package.ts): the package npm put on disk, as recorded in
-       *  installed.json — `missing` names anything the record could not carry (an integrity hash the lockfile
-       *  did not supply), so a caller can say so rather than print a clean line over a hole */
-      package?: { name: string; version: string; prefix: string; bin: string; integrity?: string; missing?: string[] };
-      /** what the human must do for it to take effect ("restart rovecode — servers are read once per process") */
-      next?: string }
-  | { ok: false; error: string };
-
-// ---------------------------------------------------------------- pure helpers (no I/O)
-
-/** `mcp:filesystem` → {kind, id}; a bare word → {id} with no kind. Anything else → null. */
-export function parseQualifiedId(text: string): { kind?: MarketKind; id: string } | null {
-  const t = text.trim();
-  if (t.length === 0 || t.length > LIMITS.str) return null;
-  const m = /^(mcp|skill|plugin):(.+)$/.exec(t);
-  if (m) return { kind: m[1] as MarketKind, id: m[2]!.trim() };
-  return { id: t };
-}
-
-export const qualify = (item: Pick<MarketItem, "kind" | "id">): string => `${item.kind}:${item.id}`;
-
-/** The one-line row every surface shows. Kept here so the CLI, the TUI and the site cannot drift. */
-export function itemLine(item: MarketItem): string {
-  const bits = [item.kind.padEnd(6), item.title];
-  if (item.version) bits.push(item.version);
-  bits.push(`· ${item.publisher}`);
-  return `${bits.join(" ")} — ${item.description}`;
-}

package/src/market/validate.ts

@@ -1,227 +0,0 @@
-/** Check a catalog before anyone is asked to trust it.
- *
- *  `--check` in CI answers "did OUR generator produce this?", which is the wrong question for someone
- *  else's file. A person writing a private catalog for their team, or preparing one to send us, needs the
- *  question answered the other way round: *given this file, what would rovecode do with it, and which of my
- *  fields would not survive?* That is what this reports, field by field.
- *
- *  THE INVARIANT THAT MATTERS: this must never call a row valid that `registry.ts` would drop. A validator
- *  that disagrees with the loader is worse than none — it hands out a clean bill for a catalog that shows
- *  up empty. So every row is also run through `itemFromCatalog`, the real reader, and a row it refuses
- *  while we found nothing to say produces an error anyway. The checks below exist to explain the refusal in
- *  the author's terms, not to be the authority on it.
- *
- *  Errors and warnings are genuinely different and are not collapsed:
- *    error   — the row (or the file) is dropped. The market will not show it.
- *    warning — the row loads, but not as written: a field was truncated, a list item past the cap was
- *              dropped, a key was not recognised. Silent in production, and exactly what an author wants
- *              to hear before they publish.
- */
-
-import { itemFromCatalog } from "./registry.ts";
-import { LIMITS } from "./types.ts";
-
-export type Severity = "error" | "warning";
-
-export interface Finding {
-  /** where it is, in the author's terms: `items[3].description` */
-  path: string;
-  message: string;
-  severity: Severity;
-}
-
-export interface ValidationReport {
-  ok: boolean;
-  kind: "skill" | "plugin";
-  /** rows that would load */
-  accepted: number;
-  /** rows the market would drop */
-  dropped: number;
-  findings: Finding[];
-}
-
-const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
-const ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
-
-/** The keys each kind's rows may carry. An unrecognised key is a warning, not an error, because a catalog
- *  may legitimately carry more than we read — but `descriptoin` is a typo that would otherwise cost the
- *  author a silent empty description, and that is worth a line. */
-const KNOWN_KEYS: Record<"skill" | "plugin", ReadonlySet<string>> = {
-  skill: new Set(["id", "name", "title", "publisher", "description", "version", "license", "tags", "repository",
-                  "homepage", "source", "files", "bytes", "docs", "env", "status", "planNote"]),
-  plugin: new Set(["id", "name", "title", "publisher", "description", "version", "apiVersion", "license", "tags",
-                   "repository", "homepage", "install", "contributes", "docs", "env", "status", "planNote"]),
-};
-
-/** a subfolder that climbs out of its clone, by the same rules the installers apply */
-function escapes(sub: unknown): boolean {
-  if (typeof sub !== "string" || sub === "") return false;
-  const s = sub.split("\\").join("/");
-  return s.startsWith("/") || /^[A-Za-z]:/.test(s) || s.split("/").includes("..");
-}
-
-export interface ValidateOptions {
-  /** `skill` or `plugin`; when absent it is read from the document's own `kind`, else inferred from a name */
-  kind?: "skill" | "plugin";
-  /** the file name, used only to infer the kind when nothing else says */
-  filename?: string;
-}
-
-export function inferKind(doc: unknown, opts: ValidateOptions = {}): "skill" | "plugin" | undefined {
-  if (opts.kind !== undefined) return opts.kind;
-  if (isRecord(doc) && (doc.kind === "skill" || doc.kind === "plugin")) return doc.kind;
-  const n = (opts.filename ?? "").toLowerCase();
-  if (n.includes("skill")) return "skill";
-  if (n.includes("plugin")) return "plugin";
-  return undefined;
-}
-
-/** Validate one catalog document. `text` is the raw file — parsing is part of what is being checked. */
-export function validateCatalog(text: string, opts: ValidateOptions = {}): ValidationReport {
-  const findings: Finding[] = [];
-  const add = (path: string, message: string, severity: Severity = "error") => findings.push({ path, message, severity });
-
-  if (text.length > LIMITS.body) {
-    return { ok: false, kind: opts.kind ?? "skill", accepted: 0, dropped: 0,
-             findings: [{ path: "", message: `the file is ${Math.round(text.length / 1024)} KB; rovecode reads at most ${LIMITS.body / 1024} KB`, severity: "error" }] };
-  }
-
-  let doc: unknown;
-  try { doc = JSON.parse(text); }
-  catch (e) { return { ok: false, kind: opts.kind ?? "skill", accepted: 0, dropped: 0,
-                       findings: [{ path: "", message: `not valid JSON: ${e instanceof Error ? e.message : String(e)}`, severity: "error" }] }; }
-
-  const kind = inferKind(doc, opts);
-  if (kind === undefined) {
-    return { ok: false, kind: "skill", accepted: 0, dropped: 0,
-             findings: [{ path: "", message: `cannot tell whether this is a skill or a plugin catalog — pass --kind skill|plugin, or give the document a "kind" field`, severity: "error" }] };
-  }
-
-  if (!isRecord(doc)) {
-    return { ok: false, kind, accepted: 0, dropped: 0, findings: [{ path: "", message: "the top level must be an object", severity: "error" }] };
-  }
-  if (doc.version === undefined) add("version", "missing; rovecode assumes 1", "warning");
-  else if (doc.version !== 1) add("version", `is ${JSON.stringify(doc.version)}; this rovecode reads version 1`);
-  if (!Array.isArray(doc.items)) {
-    add("items", "missing or not an array — a catalog is { version, items: [...] }");
-    return { ok: false, kind, accepted: 0, dropped: 0, findings };
-  }
-
-  const rows = doc.items;
-  if (rows.length === 0) add("items", "no rows: this catalog would show nothing", "warning");
-  if (rows.length > LIMITS.items) add("items", `${rows.length} rows; rovecode reads the first ${LIMITS.items} and ignores the rest`, "warning");
-
-  const seen = new Map<string, number>();
-  let accepted = 0, dropped = 0;
-
-  rows.forEach((raw: unknown, i: number) => {
-    const at = `items[${i}]`;
-    const before = findings.length;
-
-    if (!isRecord(raw)) { add(at, "not an object"); dropped++; return; }
-
-    const id = typeof raw.id === "string" ? raw.id : typeof raw.name === "string" ? raw.name : undefined;
-    if (id === undefined) add(`${at}.id`, "missing (a row needs an id, or a name to use as one)");
-    else if (!ID.test(id)) add(`${at}.id`, `"${id}" is not a bare slug — lowercase letters, digits, dot, dash, underscore, at most 64`);
-    else {
-      const first = seen.get(id);
-      if (first !== undefined) add(`${at}.id`, `"${id}" is already used by items[${first}]; ids are unique within a kind`);
-      else seen.set(id, i);
-    }
-
-    if (typeof raw.description !== "string" || raw.description.trim() === "") add(`${at}.description`, "missing (a row needs one line describing it)");
-    else if (raw.description.length > LIMITS.desc) add(`${at}.description`, `${raw.description.length} characters; will be cut to ${LIMITS.desc}`, "warning");
-
-    for (const k of ["title", "publisher", "version", "license", "repository", "homepage"] as const) {
-      const v = raw[k];
-      if (v !== undefined && typeof v !== "string") add(`${at}.${k}`, `must be a string, not ${Array.isArray(v) ? "an array" : typeof v}`, "warning");
-      else if (typeof v === "string" && v.length > LIMITS.str) add(`${at}.${k}`, `${v.length} characters; will be cut to ${LIMITS.str}`, "warning");
-    }
-    if (raw.publisher === undefined) add(`${at}.publisher`, 'missing; the row will say "unknown"', "warning");
-
-    if (raw.tags !== undefined) {
-      if (!Array.isArray(raw.tags)) add(`${at}.tags`, "must be an array of strings", "warning");
-      else if (raw.tags.length > LIMITS.list) add(`${at}.tags`, `${raw.tags.length} tags; only the first ${LIMITS.list} are read`, "warning");
-    }
-
-    validateInstall(kind, raw, at, add);
-    validateDocs(raw.docs, `${at}.docs`, add);
-
-    for (const key of Object.keys(raw)) {
-      if (!KNOWN_KEYS[kind].has(key)) add(`${at}.${key}`, "not a field rovecode reads — a typo, or something it will ignore", "warning");
-    }
-
-    // The authority, not us: whatever we found or missed, the real reader decides whether this row loads.
-    const notes: string[] = [];
-    const item = itemFromCatalog(kind, raw, notes);
-    const errorsHere = findings.slice(before).some((f) => f.severity === "error");
-    if (item === null) {
-      dropped++;
-      if (!errorsHere) add(at, `rovecode drops this row${notes.length ? `: ${notes[notes.length - 1]}` : ""} — the checks above did not explain why, which is a gap in this validator`);
-    } else {
-      if (errorsHere) add(at, "the row loads despite the errors above; treat them as the more careful reading", "warning");
-      accepted++;
-    }
-  });
-
-  return { ok: findings.every((f) => f.severity !== "error"), kind, accepted, dropped, findings };
-}
-
-function validateInstall(kind: "skill" | "plugin", raw: Record<string, unknown>, at: string,
-                         add: (p: string, m: string, s?: Severity) => void): void {
-  if (kind === "skill") {
-    const source = isRecord(raw.source) ? raw.source : undefined;
-    const files = Array.isArray(raw.files) ? raw.files : undefined;
-    if (source === undefined && files === undefined) {
-      add(`${at}.source`, "missing: a skill needs either source.git (a repository) or files (the text itself)");
-      return;
-    }
-    if (source !== undefined) {
-      if (typeof source.git !== "string" || !/^https?:\/\//.test(source.git)) add(`${at}.source.git`, "must be an http(s) repository URL");
-      if (escapes(source.subfolder)) add(`${at}.source.subfolder`, `"${String(source.subfolder)}" climbs out of the clone`);
-    }
-    files?.forEach((f: unknown, j: number) => {
-      const p = isRecord(f) ? f.path : undefined;
-      if (typeof p !== "string" || p === "") add(`${at}.files[${j}].path`, "missing");
-      else if (escapes(p)) add(`${at}.files[${j}].path`, `"${p}" writes outside the skill's folder`);
-      if (isRecord(f) && typeof f.text !== "string") add(`${at}.files[${j}].text`, "missing (the file's contents)");
-    });
-    if (files !== undefined && files.length > LIMITS.list) add(`${at}.files`, `${files.length} files; only the first ${LIMITS.list} are read`, "warning");
-    return;
-  }
-
-  const install = isRecord(raw.install) ? raw.install : undefined;
-  if (install === undefined) { add(`${at}.install`, "missing: a plugin needs install.source (a repository URL or a folder)"); return; }
-  if (typeof install.source !== "string" || install.source === "") { add(`${at}.install.source`, "missing"); return; }
-  if (install.git === true && !/^https?:\/\//.test(install.source)) add(`${at}.install.source`, `"${install.source}" is marked git: true but is not an http(s) URL`);
-  if (escapes(install.subfolder)) add(`${at}.install.subfolder`, `"${String(install.subfolder)}" climbs out of the clone`);
-  // Not an error, and said plainly: rovecode's own three plugins all live in a subfolder, so a row without
-  // one is claiming the manifest sits at the repository root — right sometimes, a mistake more often.
-  if (install.subfolder === undefined) add(`${at}.install.subfolder`, "absent: the plugin.json must then be at the repository root", "warning");
-}
-
-function validateDocs(docs: unknown, at: string, add: (p: string, m: string, s?: Severity) => void): void {
-  if (docs === undefined) return;                       // a row without documentation is a normal row
-  if (!isRecord(docs)) { add(at, "must be an object", "warning"); return; }
-  if (typeof docs.source !== "string" || !/^https?:\/\//.test(docs.source)) add(`${at}.source`, "must be the http(s) URL the document was read from — the docs are dropped without it", "warning");
-  if (docs.format !== "markdown") add(`${at}.format`, `must be "markdown"; the docs are dropped otherwise`, "warning");
-  if (typeof docs.body !== "string" || docs.body.trim() === "") add(`${at}.body`, "empty: the docs are dropped and the row keeps no documentation", "warning");
-  else if (Buffer.byteLength(docs.body, "utf8") > LIMITS.docs) add(`${at}.body`, `${Math.round(Buffer.byteLength(docs.body, "utf8") / 1024)} KB; will be cut to ${LIMITS.docs / 1024} KB`, "warning");
-  if (docs.truncated === true && typeof docs.bytes === "number" && typeof docs.body === "string"
-      && docs.bytes <= Buffer.byteLength(docs.body, "utf8")) {
-    add(`${at}.bytes`, "marked truncated, but bytes is not larger than the body — bytes should be the size BEFORE truncation", "warning");
-  }
-}
-
-/** The report as lines, for a terminal. Errors first: an author fixes those, warnings are a second pass. */
-export function reportLines(r: ValidationReport, where: string): string[] {
-  const errors = r.findings.filter((f) => f.severity === "error");
-  const warnings = r.findings.filter((f) => f.severity === "warning");
-  const lines = [`${where}: ${r.kind} catalog — ${r.ok ? "valid" : "INVALID"}`];
-  lines.push(`  ${r.accepted} row${r.accepted === 1 ? "" : "s"} would load, ${r.dropped} dropped, ${errors.length} error${errors.length === 1 ? "" : "s"}, ${warnings.length} warning${warnings.length === 1 ? "" : "s"}`);
-  for (const f of [...errors, ...warnings]) {
-    lines.push(`  ${f.severity === "error" ? "error  " : "warning"}  ${f.path === "" ? "(file)" : f.path}: ${f.message}`);
-  }
-  if (r.ok && warnings.length > 0) lines.push("  warnings do not stop a catalog loading; they are fields that will not survive as written");
-  return lines;
-}