okmodel 0.8.0 → 0.9.1

package/dist/tooling/driver-run.js

@@ -20,12 +20,11 @@ import {
   compareText,
   enumType,
   domainType,
-  isDomain,
   sameEnumLabels,
   indexObjects,
   orderIndexed,
-  creationOrder2,
   quoteLiteral,
+  renderCatalog2,
   clientGenerator,
   readClientGenerator,
   definition,
@@ -46,7 +45,7 @@ import {
   jsonb,
   quote,
   primaryUrl
-} from "./shared/f9mphxej.js";
+} from "./shared/2jdn09e2.js";
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
@@ -353,8 +352,7 @@ function registerDriverSuite(suite) {
       try {
         const setting = await scalar(second, "SELECT current_setting('okm.p13', true)");
         expect(setting).not.toBe("yes");
-        expect(await scalar(second, "SELECT pg_backend_pid()::text")).toBe(pid);
-        expect(await scalar(second, "SELECT count(*)::text FROM pg_locks WHERE locktype = 'advisory' AND pid = pg_backend_pid()")).toBe("0");
+        expect(await scalar(second, `SELECT count(*)::text FROM pg_locks WHERE locktype = 'advisory' AND pid = ${pid}`)).toBe("0");
       } finally {
         await second.release();
       }
@@ -445,9 +443,28 @@ async function using(open, fn) {
   try {
     await fn(pool);
   } finally {
+    await dropOkmTables(pool);
     await pool.close();
   }
 }
+async function dropOkmTables(pool) {
+  try {
+    await pool.execute(`
+      do $$
+      declare
+        r record;
+      begin
+        for r in
+          select tablename
+          from pg_tables
+          where schemaname = current_schema()
+            and tablename like 'okm\\_%' escape '\\'
+        loop
+          execute format('drop table if exists %I cascade', r.tablename);
+        end loop;
+      end $$`);
+  } catch {}
+}
 function tableName() {
   return `okm_${Math.random().toString(36).slice(2, 10)}`;
 }
@@ -615,9 +632,28 @@ async function using2(open, fn) {
   try {
     await fn(pool);
   } finally {
+    await dropOkmTables2(pool);
     await pool.close();
   }
 }
+async function dropOkmTables2(pool) {
+  try {
+    await pool.execute(`
+      do $$
+      declare
+        r record;
+      begin
+        for r in
+          select tablename
+          from pg_tables
+          where schemaname = current_schema()
+            and tablename like 'okm\\_%' escape '\\'
+        loop
+          execute format('drop table if exists %I cascade', r.tablename);
+        end loop;
+      end $$`);
+  } catch {}
+}
 async function mapped(pending) {
   try {
     await pending;
@@ -693,322 +729,6 @@ function assertForeignKeys(objects, keys) {
   }
 }
 
-// src/dialects/pg/ddl.ts
-function quoteIdent(name) {
-  return `"${name.replaceAll('"', '""')}"`;
-}
-function renderCatalog(source, schema) {
-  const folded = foldedKeys(source);
-  const statements = [];
-  const ordered = creationOrder2(source);
-  const created = uniqueBeforeForeignKey(ordered);
-  for (const object of ordered) {
-    if (object.kind !== "type" || object.owner === "ignored")
-      continue;
-    const sql = createObjectSql(object, schema);
-    if (sql !== undefined)
-      statements.push(sql);
-  }
-  for (const object of created) {
-    if (object.kind === "type" || object.kind === "function" || object.kind === "trigger" || object.kind === "view" || object.kind === "materializedView" || object.kind === "policy" || ownedByView(object)) {
-      continue;
-    }
-    if (object.owner === "ignored")
-      continue;
-    const key = identityKey(object.identity);
-    if (object.kind === "table") {
-      statements.push(createTableSql(object, source, schema));
-      continue;
-    }
-    if (folded.has(key))
-      continue;
-    const sql = createObjectSql(object, schema);
-    if (sql !== undefined)
-      statements.push(sql);
-  }
-  for (const object of created) {
-    if (object.kind !== "policy" || object.owner === "ignored")
-      continue;
-    for (const step of policyCreatePlan(object, schema))
-      statements.push(step.sql);
-  }
-  for (const kind of ["function", "trigger"]) {
-    for (const object of ordered) {
-      if (object.kind !== kind || object.owner === "ignored")
-        continue;
-      const sql = createObjectSql(object, schema);
-      if (sql !== undefined)
-        statements.push(sql);
-    }
-  }
-  for (const kind of ["view", "materializedView"]) {
-    for (const object of ordered) {
-      if (object.kind !== kind || object.owner === "ignored")
-        continue;
-      const sql = createObjectSql(object, schema);
-      if (sql !== undefined)
-        statements.push(sql);
-    }
-  }
-  for (const object of ordered) {
-    if (!ownedByView(object) || object.owner === "ignored")
-      continue;
-    const sql = createObjectSql(object, schema);
-    if (sql !== undefined)
-      statements.push(sql);
-  }
-  return statements;
-}
-function uniqueBeforeForeignKey(objects) {
-  const uniques = objects.filter((object) => object.kind === "constraint" && object.definition.constraintKind === "unique");
-  if (uniques.length === 0)
-    return objects;
-  const emitted = new Set;
-  const result = [];
-  for (const object of objects) {
-    if (emitted.has(object))
-      continue;
-    if (object.kind === "constraint" && object.definition.constraintKind === "foreignKey") {
-      const target = object.definition.references;
-      if (target !== undefined && !coveredByPrimary(objects, target.parent, target.columns)) {
-        const columns = target.columns.join("\x00");
-        for (const unique of uniques) {
-          if (emitted.has(unique))
-            continue;
-          if (!sameRef(unique.identity.parent, target.parent))
-            continue;
-          if (unique.definition.columns.join("\x00") !== columns)
-            continue;
-          result.push(unique);
-          emitted.add(unique);
-        }
-      }
-    }
-    result.push(object);
-    emitted.add(object);
-  }
-  return result;
-}
-function coveredByPrimary(objects, parent, columns) {
-  const key = columns.join("\x00");
-  return objects.some((object) => object.kind === "constraint" && object.definition.constraintKind === "primaryKey" && sameRef(object.identity.parent, parent) && object.definition.columns.join("\x00") === key);
-}
-function sameRef(left, right) {
-  if (left.name !== right.name || left.namespace.form !== right.namespace.form)
-    return false;
-  if (left.namespace.form === "static" && right.namespace.form === "static") {
-    return left.namespace.name === right.namespace.name;
-  }
-  return left.namespace.form === "template" && right.namespace.form === "template" ? left.namespace.pattern === right.namespace.pattern : false;
-}
-function ownedByView(object) {
-  if (object.kind !== "index")
-    return false;
-  return object.dependencies.some((edge) => edge.target.kind === "view" || edge.target.kind === "materializedView");
-}
-function createObjectSql(object, schema) {
-  switch (object.kind) {
-    case "column":
-      return `alter table ${qualify(schema, object.identity.parent.name)} add column ${columnSql(object)}`;
-    case "index":
-      return createIndexSql(object, schema);
-    case "constraint":
-      return `alter table ${qualify(schema, object.identity.parent.name)} add constraint ${quoteIdent(object.identity.name)} ${constraintBody(object, schema)}`;
-    case "sequence":
-      return createSequenceSql(object, schema);
-    case "type":
-      return createTypeSql(object, schema);
-    case "extension":
-      return createExtensionSql(object);
-    case "function":
-      return functionSql(object, schema, false);
-    case "trigger":
-      return triggerSql(object, schema);
-    case "view":
-      return viewSql(object, schema, false);
-    case "materializedView":
-      return materializedViewSql(object, schema);
-    case "table":
-      return;
-    default:
-      return;
-  }
-}
-function functionSql(object, schema, replace) {
-  const definition = object.definition;
-  const args = definition.arguments.map((argument) => `${quoteIdent(argument.name)} ${argument.type}`).join(", ");
-  const head = `${replace ? "create or replace" : "create"} function ${qualify(schema, object.identity.name)}(${args})`;
-  const security = ` security ${definition.security}`;
-  const path = definition.searchPath === undefined ? "" : ` set search_path to ${definition.searchPath}`;
-  const tail = `returns ${definition.returns} language ${definition.language} ${definition.volatility}${security}${path}`;
-  if (definition.atomic)
-    return `${head} ${tail} ${definition.body}`;
-  return `${head} ${tail} as ${dollarQuote(definition.body)}`;
-}
-function viewSql(object, schema, replace) {
-  const verb = replace ? "create or replace view" : "create view";
-  const invoker = object.definition.securityInvoker === true ? " with (security_invoker = true)" : "";
-  return `${verb} ${qualify(schema, object.identity.name)}${invoker} as ${object.definition.query}`;
-}
-function policyCreatePlan(object, schema) {
-  const table = qualify(schema, object.identity.parent.name);
-  const name = quoteIdent(object.identity.name);
-  const command = object.definition.command === "all" ? "all" : "select";
-  const check = object.definition.command === "all" ? ` with check ${object.definition.expression}` : "";
-  const create = {
-    sql: `create policy ${name} on ${table} as permissive for ${command} using ${object.definition.expression}${check}`,
-    kind: "create-policy"
-  };
-  if (object.definition.command !== "all")
-    return [create];
-  return [
-    { sql: `alter table ${table} enable row level security`, kind: "enable-rls" },
-    { sql: `alter table ${table} force row level security`, kind: "enable-rls" },
-    create
-  ];
-}
-function materializedViewSql(object, schema) {
-  return `create materialized view ${qualify(schema, object.identity.name)} as ${object.definition.query} with no data`;
-}
-function triggerSql(object, schema) {
-  const definition = object.definition;
-  const timing = definition.timing === "instead" ? "instead of" : definition.timing;
-  const events = definition.events.map((event) => {
-    if (event !== "update" || definition.updateOf === undefined)
-      return event;
-    return `update of ${definition.updateOf.map((column) => quoteIdent(column)).join(", ")}`;
-  }).join(" or ");
-  const when = definition.when === undefined ? "" : ` when (${definition.when})`;
-  const args = definition.calls.argTypes.join(", ");
-  const fn = `${qualify(schema, definition.calls.name)}(${args})`;
-  return `create trigger ${quoteIdent(object.identity.name)} ${timing} ${events} on ${qualify(schema, object.identity.parent.name)} for each ${definition.level}${when} execute function ${fn}`;
-}
-function dollarQuote(body) {
-  let tag = "okm";
-  while (body.includes(`$${tag}$`))
-    tag = `${tag}_`;
-  return `$${tag}$${body}$${tag}$`;
-}
-function identitySequence(sequence, source) {
-  const key = identityKey(sequence.identity);
-  return source.objects.some((object) => {
-    if (object.kind !== "column" || object.definition.identity === undefined)
-      return false;
-    return object.dependencies.some((edge) => identityKey(edge.target) === key);
-  });
-}
-function foldedKeys(source) {
-  const keys = new Set;
-  for (const object of source.objects) {
-    if (object.kind === "column")
-      keys.add(identityKey(object.identity));
-    if (object.kind === "constraint" && object.definition.constraintKind === "primaryKey") {
-      keys.add(identityKey(object.identity));
-    }
-    if (object.kind === "sequence" && identitySequence(object, source)) {
-      keys.add(identityKey(object.identity));
-    }
-  }
-  return keys;
-}
-function createTableSql(tableObject, source, schema) {
-  const parent = tableObject.identity.name;
-  const columns = source.objects.filter((object) => object.kind === "column" && object.identity.parent.name === parent);
-  const primary = source.objects.find((object) => object.kind === "constraint" && object.definition.constraintKind === "primaryKey" && object.identity.parent.name === parent);
-  const lines = columns.map((column) => columnSql(column));
-  if (primary !== undefined) {
-    const cols = primary.definition.columns.map((name) => quoteIdent(name)).join(", ");
-    lines.push(`constraint ${quoteIdent(primary.identity.name)} primary key (${cols})`);
-  }
-  const partition = tableObject.definition.partition;
-  const tail = partition === undefined ? "" : ` partition by ${partition.method} (${partition.columns.map((name) => quoteIdent(name)).join(", ")})`;
-  return `create table ${qualify(schema, parent)} (
-  ${lines.join(`,
-  `)}
-)${tail}`;
-}
-function collateSql(collation) {
-  if (collation === undefined)
-    return "";
-  return ` collate ${quoteIdent(collation)}`;
-}
-function createTypeSql(object, schema) {
-  if (isDomain(object.definition)) {
-    const name = object.identity.name;
-    const constraint = quoteIdent(fitIdentifier(`${name}_check`));
-    return `create domain ${qualify(schema, name)} as ${object.definition.base} constraint ${constraint} check (${object.definition.check})`;
-  }
-  const labels = object.definition.labels.map((label) => quoteLiteral(label)).join(", ");
-  return `create type ${qualify(schema, object.identity.name)} as enum (${labels})`;
-}
-function columnSql(column) {
-  const definition = column.definition;
-  let sql = `${quoteIdent(column.identity.name)} ${definition.dataType}${collateSql(definition.collation)}`;
-  if (definition.identity !== undefined) {
-    sql += definition.identity.always ? " generated always as identity" : " generated by default as identity";
-  } else if (definition.generated !== undefined) {
-    sql += ` generated always as (${definition.generated.expression}) stored`;
-  }
-  if (!definition.nullable)
-    sql += " not null";
-  if (definition.defaultExpression !== undefined)
-    sql += ` default ${definition.defaultExpression}`;
-  return sql;
-}
-function createIndexSql(object, schema) {
-  const unique = object.definition.unique ? "unique " : "";
-  const where = object.definition.predicate === undefined ? "" : ` where ${object.definition.predicate}`;
-  const expression = object.definition.expression;
-  const name = quoteIdent(object.identity.name);
-  const on = qualify(schema, object.identity.parent.name);
-  if (expression !== undefined && expression.startsWith("using ")) {
-    return `create ${unique}index ${name} on ${on} ${expression}${where}`;
-  }
-  const target = expression !== undefined ? `(${expression})` : object.definition.columns.map((column) => quoteIdent(column)).join(", ");
-  return `create ${unique}index ${name} on ${on} (${target})${where}`;
-}
-function createExtensionSql(object) {
-  const version = object.definition.version;
-  const pinned = version !== undefined && /^\d+(?:\.\d+)*$/.test(version) ? ` version ${quoteLiteral(version)}` : "";
-  return `create extension ${quoteIdent(object.identity.name)} schema ${quoteIdent(object.definition.schema)}${pinned}`;
-}
-function createSequenceSql(object, schema) {
-  const definition = object.definition;
-  const cycle = definition.cycle ? " cycle" : "";
-  return `create sequence ${qualify(schema, object.identity.name)} as ${definition.dataType} start ${definition.start} increment ${definition.increment}${cycle}`;
-}
-function constraintBody(object, schema) {
-  const definition = object.definition;
-  const columns = definition.columns.map((name) => quoteIdent(name)).join(", ");
-  switch (definition.constraintKind) {
-    case "primaryKey":
-      return `primary key (${columns})`;
-    case "unique": {
-      const nulls = definition.nullsNotDistinct ? " nulls not distinct" : "";
-      return `unique${nulls} (${columns})${deferClause(definition)}`;
-    }
-    case "check":
-      return `check (${definition.expression ?? "true"})${deferClause(definition)}`;
-    case "foreignKey": {
-      const references = definition.references;
-      const target = references === undefined ? "" : ` references ${qualify(schema, references.parent.name)} (${references.columns.map((name) => quoteIdent(name)).join(", ")})`;
-      const onDelete = references?.onDelete === undefined ? "" : ` on delete ${references.onDelete}`;
-      const onUpdate = references?.onUpdate === undefined ? "" : ` on update ${references.onUpdate}`;
-      return `foreign key (${columns})${target}${onDelete}${onUpdate}${deferClause(definition)}`;
-    }
-    default:
-      return definition.constraintKind;
-  }
-}
-function deferClause(definition) {
-  if (!definition.deferrable)
-    return "";
-  return ` deferrable initially ${definition.initially}`;
-}
-function qualify(schema, name) {
-  return `${quoteIdent(schema)}.${quoteIdent(name)}`;
-}
-
 // src/contracts/location.ts
 function callerLocation(skip) {
   const lines = new Error().stack?.split(`
@@ -1204,29 +924,29 @@ function readTenancy(value) {
 }
 
 // src/dialects/pg/filters.ts
-function openFilters(table, relations, spec, hiddenFields) {
+function openFilters(table, relations, spec, isHidden) {
   const allow = spec.allow ?? {};
   const sort = spec.sort ?? [];
   for (const field of Object.keys(allow))
-    deny(hiddenFields, table, field);
+    deny(isHidden, table, field);
   for (const field of sort)
-    deny(hiddenFields, table, field);
+    deny(isHidden, table, field);
   const nested = spec.relations;
   if (nested !== undefined) {
     for (const name of Object.keys(nested)) {
       const target = relationTable(relations, name);
       for (const field of nested[name] ?? [])
-        deny(hiddenFields, target, field);
+        deny(isHidden, target, field);
     }
   }
   return {
     parse(query) {
-      return import("./shared/03k6res6.js").then((mod) => mod.parseQuery(allow, sort, query, nested));
+      return import("./shared/f4gep0nk.js").then((mod) => mod.parseQuery(allow, sort, query, nested));
     }
   };
 }
-function deny(hiddenFields, table, field) {
-  if (!hiddenFields.has(`${table}.${field}`))
+function deny(isHidden, table, field) {
+  if (!isHidden(table, field))
     return;
   throw new OkmError("OKM1123", `Field ${table}.${field} is hidden.`, {
     fix: {
@@ -1279,7 +999,8 @@ function table2(name, columns, options) {
     name,
     columns,
     filters(spec) {
-      return openFilters(name, options?.relations, spec, hiddenFields);
+      const ownHidden = hiddenColumnFields(columns);
+      return openFilters(name, options?.relations, spec, (tableName, field) => tableName === name ? ownHidden.has(field) : hiddenFields.has(`${tableName}.${field}`));
     },
     ...options !== undefined ? { options } : {},
     ...source !== undefined ? { source } : {}
@@ -1343,11 +1064,23 @@ function rejectLater(options, known, later, where) {
   }
 }
 var hiddenFields = new Set;
-function remember(name, columns) {
+function hiddenColumnFields(columns) {
+  const fields = new Set;
   for (const field of Object.keys(columns)) {
     const column = columns[field];
     if (column?.state?.hidden === true)
-      hiddenFields.add(`${name}.${field}`);
+      fields.add(field);
+  }
+  return fields;
+}
+function remember(name, columns) {
+  const prefix = `${name}.`;
+  for (const key of hiddenFields) {
+    if (key.startsWith(prefix))
+      hiddenFields.delete(key);
+  }
+  for (const field of hiddenColumnFields(columns)) {
+    hiddenFields.add(`${name}.${field}`);
   }
 }
 
@@ -3777,7 +3510,7 @@ function registerTxSuite(suite) {
         max: options.max ?? 4,
         ...options.url ? { url: options.url } : {}
       });
-      const ddl = [...renderCatalog(built.catalog, schemaName), ...options.sql ?? []];
+      const ddl = [...renderCatalog2(built.catalog, schemaName), ...options.sql ?? []];
       for (const statement of ddl)
         await (setup ?? pool).execute(statement);
       const db = await suite.connect(pool, {
@@ -4622,7 +4355,7 @@ function skipped(test, reason) {
   return skipFor(test, reason, (name) => `${name} (${reason})`);
 }
 async function openSuiteAdmin(url) {
-  const { openPostgres } = await import("./shared/pwsytxm5.js");
+  const { openPostgres } = await import("./shared/gefmpwsa.js");
   return openPostgres(url);
 }
 async function failure2(promise) {
@@ -4655,14 +4388,45 @@ function barrier(parties) {
 }
 
 // packages/harness/src/driver-run.ts
+var MIN_BUN = "1.4.0";
 async function executeDriverTest(argv) {
   process.env.TZ = "UTC";
+  refuseOldBun();
   const parsed = parseArgs(argv);
   const target = await loadTarget(parsed.driver, parsed.url);
   const rows = await runTarget(target);
   const failed = rows.filter((row) => row.result === "fail").length;
   return { text: render(target.name, rows), failed };
 }
+function refuseOldBun() {
+  if (typeof Bun === "undefined")
+    return;
+  const version = typeof Bun.version === "string" ? Bun.version : "";
+  if (bunAtLeast(version, MIN_BUN))
+    return;
+  throw new Error(`okm driver test needs Bun >=${MIN_BUN} (package.json engines.bun). This process is ${version === "" ? "Bun (unknown version)" : `Bun ${version}`}.`);
+}
+function bunAtLeast(version, minimum) {
+  const left = parseSemver(version);
+  const right = parseSemver(minimum);
+  if (left === undefined || right === undefined)
+    return false;
+  for (let index = 0;index < 3; index += 1) {
+    const a = left[index] ?? 0;
+    const b = right[index] ?? 0;
+    if (a > b)
+      return true;
+    if (a < b)
+      return false;
+  }
+  return true;
+}
+function parseSemver(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value.trim());
+  if (match === null)
+    return;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
 if (__require.main == __require.module) {
   executeDriverTest(process.argv.slice(2)).then((report) => {
     process.stdout.write(report.text);
@@ -4720,8 +4484,8 @@ async function loadTarget(driver, url) {
 }
 async function firstParty(driver, url) {
   if (driver === "pglite") {
-    const adapter = await import("./shared/dy672fz6.js");
-    const runtime = await import("./shared/9xzm7hjg.js");
+    const adapter = await import("./shared/19msgrsc.js");
+    const runtime = await import("./shared/p6tjv97k.js");
     return {
       name: "pglite",
       capabilities: adapter.capabilities,
@@ -4736,8 +4500,8 @@ async function firstParty(driver, url) {
   if (url === undefined)
     throw new Error(`okm driver test ${driver} needs --url or DATABASE_URL.`);
   if (driver === "postgresjs") {
-    const adapter = await import("./shared/y031jct9.js");
-    const runtime = await import("./shared/vraj6d74.js");
+    const adapter = await import("./shared/d8q00vxg.js");
+    const runtime = await import("./shared/y4gq9rbe.js");
     return networked("postgres.js", adapter.capabilities, true, url, (config) => adapter.open({
       url: config.url ?? url,
       max: config.max,
@@ -4746,8 +4510,8 @@ async function firstParty(driver, url) {
     }), (pool, options) => runtime.connect(pool, options));
   }
   if (driver === "pg") {
-    const adapter = await import("./shared/nf7jmhfa.js");
-    const runtime = await import("./shared/jne7b93p.js");
+    const adapter = await import("./shared/jm30k2ca.js");
+    const runtime = await import("./shared/2qrte2ct.js");
     return networked("node-postgres", adapter.capabilities, true, url, (config) => adapter.open({
       url: config.url ?? url,
       max: config.max,
@@ -4756,8 +4520,8 @@ async function firstParty(driver, url) {
     }), (pool, options) => runtime.connect(pool, options));
   }
   if (driver === "neon") {
-    const adapter = await import("./shared/7ae7rjmn.js");
-    const runtime = await import("./shared/8sqrsw3s.js");
+    const adapter = await import("./shared/0v9ptnxp.js");
+    const runtime = await import("./shared/jgzt69pa.js");
     return networked("neon", adapter.capabilities, false, url, (config) => adapter.open({
       url: config.url ?? url,
       max: config.max,
@@ -4768,8 +4532,8 @@ async function firstParty(driver, url) {
   if (typeof Bun === "undefined" || typeof Bun.SQL !== "function") {
     throw new Error("bun runs only under Bun.");
   }
-  const adapter = await import("./shared/a7q7t4n3.js");
-  const runtime = await import("./shared/a6pp9d12.js");
+  const adapter = await import("./shared/ryc5sa58.js");
+  const runtime = await import("./shared/0yhf1db4.js");
   return networked("bun.sql", adapter.capabilities, false, url, (config) => adapter.open({
     url: config.url ?? url,
     max: config.max,
@@ -4967,5 +4731,7 @@ function render(driver, rows) {
 `;
 }
 export {
+  MIN_BUN,
+  bunAtLeast,
   executeDriverTest
 };

package/dist/tooling/github/comment.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pull-request comment for `okm migrate plan --json` (D279).
+ *
+ * The text comes from the plan document. It does not read the human plan.
+ */
+import { type PlanDocument } from "../migrate/plan-json.js";
+/**
+ * Hidden marker that identifies the sticky comment.
+ *
+ * A later push updates the comment whose body contains this marker.
+ */
+export declare const PLAN_COMMENT_MARKER = "<!-- okmodel-migrate-plan -->";
+/** Default login that posts the Action comment with `GITHUB_TOKEN`. */
+export declare const PLAN_COMMENT_BOT = "github-actions[bot]";
+/** A comment the sticky update may replace. */
+export type StickyComment = {
+    readonly id: number;
+    readonly body: string;
+    /** GitHub login of the comment author. */
+    readonly author: string;
+};
+/**
+ * Renders the plan comment.
+ *
+ * The first heading is the strictest class. Each step is one table row
+ * with its class and lock. The lock is the plan's lock line, including a
+ * row estimate when the plan printed one. Lint findings keep their codes.
+ *
+ * @param plan - Document from `okm migrate plan --json`
+ * @returns Markdown, including {@link PLAN_COMMENT_MARKER}
+ */
+export declare function renderPlanComment(plan: PlanDocument): string;
+/**
+ * Comment body for a plan file, or a status line when the file is not a document.
+ *
+ * The status line records exit codes only. It does not include command text.
+ *
+ * @param text - Stdout of `okm migrate plan --json`, when the file exists
+ * @param checkStatus - Exit code of `okm migrate check`
+ * @param planStatus - Exit code of `okm migrate plan --json`
+ * @returns The comment body
+ */
+export declare function planCommentBody(text: string | undefined, checkStatus: string, planStatus: string): string;
+/**
+ * The comment to update, when one already carries the marker and an allowed author.
+ *
+ * The first match wins. A missing match means the caller creates a comment.
+ * A marker on another author's comment is ignored so the Action never edits it.
+ *
+ * @param comments - Comments already on the pull request
+ * @param authors - Logins allowed to own the sticky comment. Default is the Actions bot
+ * @returns The id to update, or `undefined` to create one
+ */
+export declare function stickyCommentTarget(comments: readonly StickyComment[], authors?: readonly string[]): {
+    readonly updateId: number;
+} | undefined;

package/dist/tooling/github/post-comment.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Creates or updates the sticky plan comment (D279).
+ *
+ * Uses `GITHUB_TOKEN` only. The workflow needs `pull-requests: write`.
+ * The token is not written to stdout or stderr.
+ */
+/**
+ * Posts the plan comment for one pull request.
+ *
+ * An existing comment that contains the marker is updated. Otherwise a
+ * comment is created. The body comes from {@link planCommentBody}.
+ *
+ * @param planPath - File written by `okm migrate plan --json`
+ * @param checkStatus - Exit code of `okm migrate check`
+ * @param planStatus - Exit code of `okm migrate plan --json`
+ */
+export declare function postPlanComment(planPath: string, checkStatus: string, planStatus: string): Promise<void>;