@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/cli/doctor.js

@@ -6,14 +6,18 @@
  */
 import { failed, jsonText, nextBlock, parseCommand } from "./command.js";
 import { out as styleOut, wrap } from "./style.js";
-import { heldPgPort, namedPgPort, portHolder } from "./ports.js";
+import { DEFAULT_UI_PORT, heldPgPort, namedPgPort, portHolder } from "./ports.js";
 import { callRun, RunUnreachable } from "./control.js";
 import { readiness } from "./commands.js";
 import { connectSource, maskedUrl, parseSource, readSourceFacts, versionProblem } from "./preflight.js";
 import { theRun } from "./runs.js";
 import { projectSource } from "./project.js";
 import { DEFAULT_PG_PORT } from "../api/postgres/listener.js";
-import { defaultMemoryLimit, machineMemoryBytes, MEMORY_LIMIT_RE } from "../duck/store.js";
+import { defaultMemoryLimit, machineMemory, memoryLimitBytes, memoryProblems, memoryProblemText, memorySize, memoryWarning, OUTSIDE_RESERVE_BYTES } from "../duck/store.js";
+import { probeExtensions } from "../duck/extensions.js";
+import { readRoleFacts, roleChecks, roleUnknown, ROLE_CODES } from "./source-role.js";
+import { replicatedEntries, shownPath } from "./sources.js";
+import { namedPublication } from "./replication-mode.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 /**
  * THE NODE THE PACKAGE NEEDS, major.minor: cli/package.json's `engines`, this check, `mason --help` and the README read
@@ -25,17 +29,28 @@ const out = (m) => { process.stdout.write(`${m}\n`); };
 export const NODE_MIN = "22.13";
 export const DOCTOR_USAGE = `usage: mason doctor [--json]
 
-  Says whether this machine is ready for Mason — Node ${NODE_MIN} or later, memory (Mason's copy uses up to half of it by
-  default; MASON_DUCKDB_MEMORY=4GiB sets it), the ports Mason listens on — with the way out for anything missing. In a
+  Says whether this machine is ready for Mason — Node ${NODE_MIN} or later, memory (what the engine may use and what it
+  leaves beside it; MASON_DUCKDB_MEMORY=4GiB sets it), Mason's postgres and inet extensions (installed with Mason for this
+  platform, so nothing is downloaded; else the first sync downloads them), the ports Mason listens on — with the way
+  out for anything missing. In a
   project's folder it checks the project's database too; with Mason running for it, the run in a few lines instead: its
-  database, whether every added table is copied, the statements of the last day it refused or answered slowly.
+  database, whether every added table is synced, the statements of the last day it refused or answered slowly. Both
+  say whether the user Mason connects as could change a synced table's rows (a superuser, BYPASSRLS, an owner of a
+  synced table, a write privilege on one or CREATE on its schema; or a write that reaches its rows through a
+  partition, an inheritance child or parent, a foreign key's action, a view or a rule; SECURITY DEFINER code it
+  reaches; a foreign server; ADMIN OPTION or a server role; directly or through a role it is a member of), with the
+  statements that make a role that only reads.
 
     mason doctor
 
-  --json   as data: { ready, verdict, checks: [{ name, ok, detail }], next: [{ command, what }] }; ok is true, false,
-           or null when it could not tell
+  --json   as data: { ready, verdict, checks: [{ name, ok, detail, warn, code, fix }], next: [{ command, what }] }; ok
+           is true, false, or null when it could not tell; warn (only when true): fine to run, but said loudly; code
+           (the role's lines): ${ROLE_CODES.slice(0, 5).join(", ")},
+           ${ROLE_CODES.slice(5).join(", ")};
+           fix (with code): the statements and the edit that make a role that only reads
 
-  Exit status: 0 everything checked is fine; 1 something is not (said, with the way out).
+  Exit status: 0 nothing failed — a warning (!) and a check that could not tell (?) are said, and leave it 0; 1
+  something failed (said, with the way out).
 `;
 export const DOCTOR = {
     name: "doctor",
@@ -45,7 +60,7 @@ export const DOCTOR = {
     json: ["ready", "verdict", "checks", "next"],
 };
 /** The ports a mason start takes by default, and what listens on each. */
-export const PORTS = [[4039, "the mason commands"], [DEFAULT_PG_PORT, "the Postgres API"]];
+export const PORTS = [[DEFAULT_UI_PORT, "the mason commands"], [DEFAULT_PG_PORT, "the Postgres API"]];
 /** Node's version against the package's floor, major then minor. */
 export function nodeCheck(version = process.versions.node) {
     const [major, minor] = version.split(".").map(Number);
@@ -54,21 +69,38 @@ export function nodeCheck(version = process.versions.node) {
         ? { name: "node", ok: true, detail: `Node ${version}` }
         : { name: "node", ok: false, detail: `Node ${version} is too old: mason needs ${NODE_MIN} or later (nodejs.org, or nvm install ${minMajor})` };
 }
-/** The machine's memory and what the copy's engine may use of it (src/duck/store.ts DEFAULT_MEMORY_LIMIT, MASON_DUCKDB_MEMORY). */
-export function memoryCheck(totalBytes = machineMemoryBytes(), env = process.env) {
-    const gib = (totalBytes / 1024 ** 3).toFixed(1);
-    const set = env.MASON_DUCKDB_MEMORY;
-    if (set !== undefined && !MEMORY_LIMIT_RE.test(set)) {
-        return { name: "memory", ok: false, detail: `MASON_DUCKDB_MEMORY=${JSON.stringify(set)} is not a size: write it as 4GiB, 512MiB or 2GB (mason start refuses it too)` };
+/**
+ * The machine's memory and what the copy's engine may use of it (src/duck/store.ts DEFAULT_MEMORY_LIMIT,
+ * MASON_DUCKDB_MEMORY): what a start refuses is said in the start's own words (`memoryProblems`), and what it warns of
+ * under the floor in the run's own words (`memoryWarning`), a warning, never a failure, since the start goes on; so is
+ * a share the operator set that leaves less than OUTSIDE_RESERVE_BYTES beside it.
+ */
+export function memoryCheck(memory = machineMemory(), env = process.env) {
+    const problems = memoryProblems(env);
+    if (problems.length)
+        return { name: "memory", ok: false, detail: problems.map(memoryProblemText).join("; ") };
+    const warned = memoryWarning(memory, env);
+    const set = env.MASON_DUCKDB_MEMORY || undefined;
+    const share = set ?? defaultMemoryLimit(memory.bytes);
+    const outside = memory.bytes - memoryLimitBytes(share);
+    if (warned !== null) {
+        return { name: "memory", ok: true, warn: true,
+            detail: `${memoryProblemText(warned)} (the engine uses up to ${share.trim()}, the default, leaving ${memorySize(Math.max(0, outside))} beside it)` };
     }
-    const share = set ?? defaultMemoryLimit(totalBytes);
-    const low = totalBytes < 2 * 1024 ** 3;
     return {
-        name: "memory", ok: !low,
-        detail: `${gib} GiB; Mason's copy uses up to ${share.trim()}${set !== undefined ? " (MASON_DUCKDB_MEMORY)" : " (half, the default; MASON_DUCKDB_MEMORY sets it)"}` +
-            (low ? ". Under 2 GiB, a large table's copy and a query starve each other: expect statements refused for memory" : ""),
+        name: "memory", ok: true, ...(outside < OUTSIDE_RESERVE_BYTES ? { warn: true } : {}),
+        detail: `${memorySize(memory.bytes)}; the engine uses up to ${share.trim()}${set !== undefined ? " (MASON_DUCKDB_MEMORY)" : " (the default; MASON_DUCKDB_MEMORY sets it)"}, ` +
+            `leaving ${memorySize(Math.max(0, outside))} for Mason beside it` +
+            (outside < OUTSIDE_RESERVE_BYTES ? `, under the ${memorySize(OUTSIDE_RESERVE_BYTES)} it needs (measured, with a margin): the system may stop it in a first sync, ` +
+                "a generated table's build or a burst of writes (a smaller MASON_DUCKDB_MEMORY, or more memory)" : ""),
     };
 }
+/** The copy's extensions (src/duck/extensions.ts): shipped with Mason and loaded by an engine of their own as the run's
+ *  will load them, or not shipped, and why. `probe` is a test's. */
+export async function extensionsCheck(probe = () => probeExtensions()) {
+    const p = await probe();
+    return { name: "extensions", ok: p.ok, detail: p.detail };
+}
 /**
  * Mason's ports in one line, decided by the probe mason start uses (`portHolder`, src/cli/ports.ts: every address, so
  * doctor and start agree on a port another program holds on the wildcard). A taken command port only moves Mason to
@@ -110,25 +142,72 @@ function portOf(url) {
         return null;
     } // not a URL: no port to compare with
 }
-/** The database a URL names: reachable, its version, what this user can read. */
-export async function databaseCheck(url, o = {}) {
-    const parsed = parseSource(url);
+/**
+ * The database a URL names: reachable, its version, what this user can read — and, given `role` (the project's synced
+ * tables), whether that user could write to it (src/cli/source-role.ts), on the same connection. `name` says where the
+ * URL is (`DATABASE_URL in .env`): a refusal names it, never the value (src/cli/preflight.ts shownUrl).
+ */
+export async function databaseChecks(url, o = {}) {
+    const parsed = parseSource(url, o.name);
     if ("problem" in parsed)
-        return { name: "database", ok: false, detail: parsed.problem };
+        return [{ name: "database", ok: false, detail: parsed.problem }];
     const connected = await connectSource(parsed.source, o);
     if ("failure" in connected)
-        return { name: "database", ok: false, detail: `${maskedUrl(parsed.source.url)}: ${connected.failure.message}${connected.failure.hints.map((h) => `\n    - ${h}`).join("")}` };
+        return [{ name: "database", ok: false, detail: `${maskedUrl(parsed.source.url)}: ${connected.failure.message}${connected.failure.hints.map((h) => `\n    - ${h}`).join("")}` }];
+    try {
+        const facts = await readSourceFacts(connected.pg);
+        const tooOld = versionProblem(facts);
+        if (tooOld)
+            return [{ name: "database", ok: false, detail: `${maskedUrl(parsed.source.url)}: ${tooOld}` }];
+        const database = { name: "database", ok: true, detail: `${maskedUrl(parsed.source.url)}: Postgres ${facts.versionText}${facts.standby ? " (a read replica)" : ""}, ${facts.tables.length} table(s) this user can read` };
+        return o.role ? [database, ...await askRole(connected.pg, o.role)] : [database];
+    }
+    finally {
+        connected.pg.close();
+    }
+}
+/** The role's lines, from its one catalog read; a read that failed is "could not tell", never "only reads". */
+async function askRole(pg, ask) {
     let facts;
     try {
-        facts = await readSourceFacts(connected.pg);
+        facts = await readRoleFacts(pg, ask.tables);
+    }
+    catch (e) {
+        return [roleUnknown(e.message)];
+    }
+    return roleChecks(facts, ask);
+}
+/** What the role check asks of a project's sources file: its tables, whether one streams, its publication, its URL. */
+export function roleAsk(src, root, env = process.env) {
+    return {
+        tables: src.tables.map((e) => { const at = e.table.indexOf("."); return { schema: e.table.slice(0, at), table: e.table.slice(at + 1) }; }),
+        replicated: replicatedEntries(src).map((e) => e.table),
+        publication: namedPublication(src, env)?.name ?? null,
+        urlVariable: "env" in src.url ? src.url.env : null, urlFrom: src.from, file: shownPath(root, src.file), url: src.resolved,
+    };
+}
+/**
+ * The role's lines with Mason running (its own checks never connect to the database): the project's sources file read
+ * and the database asked, on a connection of its own. What cannot be read is "could not tell".
+ */
+export async function runRoleChecks(project) {
+    if (project.config.demo === true)
+        return []; // the demo database is Mason's own, inside the run
+    const src = projectSource(project);
+    if ("message" in src)
+        return [roleUnknown(`${src.message} (mason status)`)];
+    const parsed = parseSource(src.resolved);
+    if ("problem" in parsed)
+        return [roleUnknown(parsed.problem)];
+    const connected = await connectSource(parsed.source);
+    if ("failure" in connected)
+        return [roleUnknown(`${maskedUrl(parsed.source.url)}: ${connected.failure.message}`)];
+    try {
+        return await askRole(connected.pg, roleAsk(src, project.root));
     }
     finally {
         connected.pg.close();
     }
-    const tooOld = versionProblem(facts);
-    if (tooOld)
-        return { name: "database", ok: false, detail: `${maskedUrl(parsed.source.url)}: ${tooOld}` };
-    return { name: "database", ok: true, detail: `${maskedUrl(parsed.source.url)}: Postgres ${facts.versionText}${facts.standby ? " (a read replica)" : ""}, ${facts.tables.length} table(s) this user can read` };
 }
 /** The run's health, from its own state: every table copied, failing, or still at work; and what it refused or answered slowly. */
 export async function runChecks(run) {
@@ -153,7 +232,7 @@ export async function runChecks(run) {
     else if (ready.waiting.length)
         checks.push({ name: "project", ok: null, detail: `still at work: ${ready.waiting.join("; ")} (mason wait)` });
     else
-        checks.push({ name: "project", ok: true, detail: picked ? `${picked} table(s) copied and kept current` : "no table added yet (mason tables, then mason add <table>)" });
+        checks.push({ name: "project", ok: true, detail: picked ? `${picked} table(s) synced and kept current` : "no table added yet (mason tables, then mason add <table>)" });
     const slow = await callRun(run, "GET", "/api/slow"), refused = await callRun(run, "GET", "/api/refused");
     const slowN = slow.status === 200 ? slow.body.slow.length : null, refusedN = refused.status === 200 ? refused.body.refused.length : null;
     checks.push(slowN === null || refusedN === null
@@ -170,12 +249,12 @@ export function nextSteps(checks, run, project) {
         return [["mason doctor", "again, once .mason/config.json is repaired or moved aside (the detail above says how)"]];
     // the demo database is hosted by the run itself (src/cli/demo.ts): down until mason start makes it
     if (bad("database") && project?.config.demo === true)
-        return [["mason start", "hosts the demo database, then copies its tables"]];
+        return [["mason start", "hosts the demo database, then syncs its tables"]];
     if (bad("database"))
         return [["mason start", `once the connection works (the detail above says how; the URL is in ${project ? `${project.dir}/config.json` : ".mason/config.json"})`]];
     if (project === null)
         return [
-            ["mason init", "in your app's folder: the database from DATABASE_URL in .env.local, .env or the shell"],
+            ["mason init", "in your app's folder: the database from MASON_DATABASE_URL or DATABASE_URL in .env.local, .env or the shell"],
             ["mason init postgres://user:password@localhost:5432/your_app", "or name it"],
         ];
     if (run === null)
@@ -185,7 +264,7 @@ export function nextSteps(checks, run, project) {
     if (bad("project"))
         return [["mason wait", "each problem, with the way out"]];
     if (checks.some((c) => c.name === "project" && /no table added/.test(c.detail)))
-        return [["mason tables", "the database's tables and their columns"], ["mason add <table>", "copy a table into Mason"]];
+        return [["mason tables", "the database's tables and their columns"], ["mason add <table>", "sync a table into Mason"]];
     if (bad("queries"))
         return [["mason status", "the refused and slow statements, each with what to do"]];
     return [["mason user add <name>", "a user for a BI tool or your app: its password and URL, printed once"]];
@@ -205,7 +284,7 @@ export function verdictOf(checks, run, project) {
 }
 /** A check's mark: ok, !! a failure, ? could not tell. */
 function markOf(c, s) {
-    return c.ok === false ? s.red("!! ") : c.ok === null ? s.yellow("?  ") : s.green("ok ");
+    return c.ok === false ? s.red("!! ") : c.ok === null ? s.yellow("?  ") : c.warn === true ? s.yellow("!  ") : s.green("ok ");
 }
 export async function doctor(argv, deps = {}) {
     const f = parseCommand(DOCTOR, argv);
@@ -222,12 +301,18 @@ export async function doctor(argv, deps = {}) {
     if (run === null) {
         checks.push(nodeCheck());
         checks.push(memoryCheck());
+        checks.push(await extensionsCheck());
         checks.push(await portsCheck([], portHolder, process.env, project?.config.pgPort ?? null));
         if (project) {
             // the database the project's sources file names (src/cli/sources.ts): a file that cannot be read is the failing line
             const src = projectSource(project);
-            checks.push("message" in src ? { name: "database", ok: false, detail: `${src.message}${src.why ? `: ${src.why.replace(/\n/g, "; ")}` : ""}. ${src.fix?.split("\n")[0] ?? ""}`.trim() }
-                : await databaseCheck(src.resolved, { demo: project.config.demo === true }));
+            if ("message" in src)
+                checks.push({ name: "database", ok: false, detail: `${src.message}${src.why ? `: ${src.why.replace(/\n/g, "; ")}` : ""}. ${src.fix?.split("\n")[0] ?? ""}`.trim() });
+            // the demo database is Mason's own, inside the run: whom it connects as is not the person's to change
+            else if (project.config.demo === true)
+                checks.push(...await databaseChecks(src.resolved, { demo: true, name: src.from }));
+            else
+                checks.push(...await databaseChecks(src.resolved, { role: roleAsk(src, project.root), name: src.from }));
         }
         // a project here whose config cannot be read: init would refuse, so "Ready: mason init" would send a person nowhere
         if ("code" in which && which.code === "bad_config")
@@ -235,6 +320,8 @@ export async function doctor(argv, deps = {}) {
     }
     else {
         checks.push(...await runChecks(run));
+        if (project)
+            checks.push(...await runRoleChecks(project));
     }
     const next = nextSteps(checks, run, project);
     const { ready, verdict } = verdictOf(checks, run, project);
@@ -252,8 +339,14 @@ export async function doctor(argv, deps = {}) {
         const mark = markOf(c, s);
         out(`  ${mark} ${c.name.padEnd(w)}  ${wrap(c.detail, s.width, 2 + 3 + 1 + w + 2)}`);
     }
+    // a way out several lines share, once, under them: SQL as what you type, the rest as its words
+    for (const fix of new Set(checks.map((c) => c.fix).filter((x) => x !== undefined))) {
+        out("");
+        for (const line of fix.split("\n"))
+            out(`    ${/;(\s+--.*)?$/.test(line) ? s.cyan(line) : line.startsWith("--") ? s.dim(line) : wrap(line, s.width, 4)}`);
+    }
     if (run !== null)
-        out(s.dim(`  its copy of the data and its state in ${run.home}. mason status for the details`));
+        out(s.dim(`  its synced data and its state in ${run.home}. mason status for the details`));
     if (run === null || !ready)
         out(nextBlock(next));
     return ready ? 0 : 1;

package/dist/src/cli/generated-files.js

@@ -0,0 +1,143 @@
+/**
+ * THE PROJECT'S GENERATED TABLES (issue 124): a folder beside the sources file, one file per table, the project's to
+ * commit and review. The file's name is the table's: `requests.yml` is `public.requests`, `reports.daily.yml` is
+ * `reports.daily`.
+ *
+ *   kind: scheduled               what the table promises: `scheduled` (any SELECT, up to target_lag behind its base)
+ *   target_lag: 5m                how far behind it may be
+ *   sql: |                        what it holds
+ *     SELECT tenant_id, count(*) AS requests FROM events GROUP BY 1
+ *   order_by: tenant_id           optional: what follows ORDER BY, over its columns, one SQL string
+ *   comment: Requests per tenant. optional: COMMENT ON TABLE
+ *
+ * Read here for its shape alone: each mistake at its key, with the reason and the way out, all of a file's at once. What
+ * its SQL means is the catalog's to say (src/duck/generated-plan.ts). A mistake never stops the run or another table,
+ * unlike a sources file's: a table already deployed keeps serving what it was built from (src/duck/generated.ts).
+ *
+ * `GENERATED_KEYS` is the one list of keys: a key the reader takes and the guide says (`mason help generated`), so neither
+ * can name one the other does not.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseDocument } from "yaml";
+import { didYouMean } from "../lib/did-you-mean.js";
+import { parseLag } from "../lib/table-sync.js";
+import { shownPath, tableNameProblem } from "./sources.js";
+/** Where a project's generated tables are: `<folder>/generated_tables/`, beside `sources/`. */
+export const GENERATED_DIR = "generated_tables";
+export const generatedDir = (folder) => path.join(folder, GENERATED_DIR);
+/** Every key a file takes, and what it says, as a person reads it. */
+export const GENERATED_KEYS = {
+    kind: "required: how the table stays current. scheduled: any SELECT, up to target_lag behind its base. live is not available yet",
+    sql: "required: the one SELECT that gives the table, over the tables the sources file syncs",
+    target_lag: "required for scheduled: how far behind its base it may be, like 30s, 5m or 1h (at least 1s, at most 24h). Mason looks at each table every 5s, so a table under 5s can be up to 5s behind",
+    order_by: "optional: the table's rows are written in this order, as what follows ORDER BY, over its columns, one SQL string",
+    comment: "optional: the table's comment, as COMMENT ON TABLE",
+};
+const KEYS = Object.keys(GENERATED_KEYS);
+const LIVE_WHY = "A table kept current in its base's own write isn't built yet, and Mason never runs a table as another kind than its file says.";
+const isPlain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const refusal = (key, message, options = [], why = null) => ({ key, message, why, options });
+/** The file's text read as a definition, or everything wrong with it. */
+export function parseGeneratedText(text, name, file) {
+    const at = { name: `${name.schema}.${name.table}`, schema: name.schema, table: name.table, file };
+    const doc = parseDocument(text, { uniqueKeys: true });
+    if (doc.errors.length)
+        return { ...at, kind: null, refusals: [refusal(null, `it is not YAML: ${doc.errors[0].message.split("\n")[0]}`)] };
+    const v = doc.toJS();
+    if (!isPlain(v))
+        return { ...at, kind: null, refusals: [refusal(null, `it is ${v === null || v === undefined ? "empty" : "not a mapping"}`, ["write kind: scheduled, target_lag: 5m and sql: SELECT …"])] };
+    const refusals = [];
+    for (const k of Object.keys(v))
+        if (!KEYS.includes(k))
+            refusals.push(refusal(k, `is not a key${didYouMean(k, KEYS)}`, [`a generated table takes ${KEYS.join(", ")}`]));
+    const kind = typeof v.kind === "string" ? v.kind : null;
+    const lagWritten = v.target_lag !== undefined;
+    const lag = lagWritten ? parseLag(v.target_lag) : null;
+    if (v.kind === undefined || v.kind === null)
+        refusals.push(refusal("kind", "is missing", ["write kind: scheduled with a target_lag, e.g. target_lag: 5m"], "Mason never decides how a table stays current for you."));
+    else if (kind === "live") {
+        refusals.push(refusal("kind", "live isn't available yet", ["set kind: scheduled with a target_lag, e.g. target_lag: 5m"], LIVE_WHY));
+        if (lagWritten)
+            refusals.push(refusal("target_lag", "contradicts kind: live", ["remove target_lag", "or set kind: scheduled"], "A live table is as fresh as its base, so it has no lag to choose."));
+    }
+    else if (kind !== "scheduled")
+        refusals.push(refusal("kind", `${String(v.kind)} is not a kind${kind === null ? "" : didYouMean(kind, ["live", "scheduled"])}`, ["write kind: scheduled with a target_lag, e.g. target_lag: 5m"]));
+    else if (!lagWritten)
+        refusals.push(refusal("target_lag", "is missing", ["write how stale is acceptable, e.g. target_lag: 5m"], "A scheduled table may lag its base, so its file says by how much."));
+    if (lag !== null && "problem" in lag)
+        refusals.push(refusal("target_lag", lag.problem));
+    const text1 = (key) => {
+        const x = v[key];
+        if (x === undefined)
+            return null;
+        if (typeof x === "string" && x.trim() !== "")
+            return x;
+        refusals.push(refusal(key, key === "order_by" ? "is one SQL string, as after ORDER BY" : "is empty or not text", key === "order_by" ? ["write order_by: day, tenant_id: a list would split on the commas inside an expression"] : []));
+        return null;
+    };
+    const sql = text1("sql");
+    if (v.sql === undefined)
+        refusals.push(refusal("sql", "is missing", ["write sql: | and the SELECT that gives the table"]));
+    const orderBy = text1("order_by"), comment = text1("comment");
+    if (refusals.length > 0 || sql === null || lag === null || "problem" in lag)
+        return { ...at, kind, refusals };
+    return { ...at, sql, orderBy: orderBy?.trim() ?? null, targetLag: lag, comment };
+}
+/** a file's name as the table it names: `requests.yml`, `reports.daily.yml`; or why it names none */
+function tableOfFile(file) {
+    const name = file.replace(/\.ya?ml$/, "");
+    const bad = tableNameProblem(name);
+    if (bad !== null)
+        return bad;
+    const dot = name.indexOf(".");
+    const schema = dot < 0 ? "public" : name.slice(0, dot), table = dot < 0 ? name : name.slice(dot + 1);
+    if (schema === "_mason" || schema === "information_schema" || schema.startsWith("pg_") || table.startsWith("pg_") || table.includes("__mason"))
+        return `${name} is a name Postgres or Mason keeps for itself`;
+    return { schema, table };
+}
+/** The folder as it is now: every definition in shape, and every file refused. A folder that is not there holds none. */
+export function readGenerated(folder, root) {
+    const dir = generatedDir(folder);
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((f) => /\.ya?ml$/.test(f) && !f.startsWith(".")).sort();
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return { definitions: [], refused: [] };
+        throw e;
+    }
+    const out = { definitions: [], refused: [] };
+    const seen = new Map();
+    for (const name of names) {
+        const full = path.join(dir, name), shown = shownPath(root, full);
+        const stem = name.replace(/\.ya?ml$/, "");
+        const t = tableOfFile(name);
+        if (typeof t === "string") {
+            const dot = stem.indexOf(".");
+            out.refused.push({ name: dot < 0 ? `public.${stem}` : stem, schema: dot < 0 ? "public" : stem.slice(0, dot), table: dot < 0 ? stem : stem.slice(dot + 1), file: shown, kind: null, refusals: [refusal(null, t, ["rename the file: its name is the table's"])] });
+            continue;
+        }
+        const table = `${t.schema}.${t.table}`, before = seen.get(table);
+        if (before !== undefined) {
+            out.refused.push({ name: table, ...t, file: shown, kind: null, refusals: [refusal(null, `names the table ${table}, as ${before} does`, ["keep one"])] });
+            continue;
+        }
+        seen.set(table, shown);
+        let text;
+        try {
+            text = fs.readFileSync(full, "utf8");
+        }
+        catch (e) {
+            out.refused.push({ name: table, ...t, file: shown, kind: null, refusals: [refusal(null, `it cannot be read: ${e.message}`)] });
+            continue;
+        }
+        const read = parseGeneratedText(text, t, shown);
+        if ("refusals" in read)
+            out.refused.push(read);
+        else
+            out.definitions.push(read);
+    }
+    return out;
+}