@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/manifest/checks/serviceDb.js

@@ -0,0 +1,388 @@
+'use strict';
+
+/**
+ * Whether this service has a database — and whether the repository agrees with
+ * what it declared.
+ *
+ * The fact has an owner already: `config/service/integration-contract.json` →
+ * `requiredConnectors.db`, which `utils/installContract.js` derives the whole
+ * SQL half of its contract from. So this uniform introduces NO second
+ * declaration (no `oa.db` field): confirmation 005 point 3 asks for a
+ * declaration only where the fact cannot be derived, and here it is already
+ * declared, once (lead decision `api/shared/TODO.md` §0.2b-9 point 1, reported
+ * to the owner as this reading of 005 under 004).
+ *
+ * Whether the declaration is THERE and is a boolean is decided by `C-CONTRACT`,
+ * which calls the contract validator that owns every rule of this file
+ * (`utils/bizCiGateContract.js`): a missing or non-boolean `requiredConnectors.db`
+ * is its `[BizCiGate] Invalid contract field` message. This uniform once carried
+ * a `D-DB-DECL` row saying the same thing in its own words; two rows for one
+ * rule is the duplicate `change-discipline.md` § One rail per concern forbids,
+ * and it was removed when `C-CONTRACT` began calling the validator (d.217b, lead
+ * decision).
+ *
+ * What the row below adds is the comparison the contract cannot make on its own:
+ * `false` against a repository that has migrations or a database client anyway,
+ * and `true` against a repository with nothing to install. Both directions,
+ * because a contract that lies in either direction sends the installer the
+ * wrong way — measured precedent: three repositories carried `REPO_HAS_DB=false`
+ * while their contract declared a database, and the SQL half checked nothing
+ * while printing PASS.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-005
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { readIdentity, IDENTITY_FILE } = require('../serviceIdentity');
+const { DATABASE_PREFIX } = require('./serviceIdentityRows');
+
+/** Where the fact lives, and the key that carries it. */
+const CONTRACT_PATH = 'config/service/integration-contract.json';
+const MIGRATIONS_DIR = 'migrations';
+
+/** The document an operator runs the SQL package from; the contract §3 requires it. */
+const MIGRATIONS_README = 'migrations/README.md';
+
+/** Where a service keeps its env templates, and the one that is not its own. */
+const ENV_TEMPLATE_DIR = 'config/env-templates';
+const SHARED_ENV = 'shared.env';
+
+/** The key an env template declares the database account under. */
+const ACCOUNT_KEY = 'DB_USER';
+
+/**
+ * @param {string} serviceRoot repository root
+ * @returns {{ db: boolean }|{ problem: string }}
+ */
+function declaredDb(serviceRoot) {
+  const file = path.join(serviceRoot, ...CONTRACT_PATH.split('/'));
+  if (!fs.existsSync(file)) return { problem: 'the contract is absent' };
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    return { problem: `the contract is not valid JSON — ${error.message}` };
+  }
+
+  const value = (parsed.requiredConnectors || {}).db;
+  if (typeof value !== 'boolean') return { problem: 'requiredConnectors.db is missing' };
+  return { db: value };
+}
+
+const hasMigrations = (serviceRoot) => fs.existsSync(path.join(serviceRoot, MIGRATIONS_DIR));
+
+/**
+ * @param {string} serviceRoot repository root
+ * @param {ReadonlyArray<string>} packages the database clients the row names
+ * @returns {string[]} the ones this repository depends on
+ */
+function databaseClients(serviceRoot, packages) {
+  const file = path.join(serviceRoot, 'package.json');
+  if (!fs.existsSync(file)) return [];
+  const dependencies = JSON.parse(fs.readFileSync(file, 'utf8')).dependencies || {};
+  return packages.filter((name) => dependencies[name] !== undefined);
+}
+
+const dbConsistent = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['forbidden_packages']),
+
+  run({ row, serviceRoot }) {
+    const declaration = declaredDb(serviceRoot);
+    // The declaration itself is C-CONTRACT's finding; this row says nothing
+    // about a fact it could not read, rather than guessing which way it went.
+    if (declaration.problem !== undefined) return [];
+
+    if (declaration.db === true) {
+      if (hasMigrations(serviceRoot)) return [];
+      return [{
+        where: CONTRACT_PATH,
+        what: 'requiredConnectors.db is true and there is no migrations/ directory — '
+          + 'a fresh install of this service has nothing to run'
+      }];
+    }
+
+    const findings = [];
+    if (hasMigrations(serviceRoot)) {
+      findings.push({
+        where: CONTRACT_PATH,
+        what: 'requiredConnectors.db is false and migrations/ exists — one of the two is wrong'
+      });
+    }
+    for (const client of databaseClients(serviceRoot, row.forbidden_packages)) {
+      findings.push({
+        where: 'package.json',
+        what: `requiredConnectors.db is false and ${JSON.stringify(client)} is a dependency — one of the two is wrong`
+      });
+    }
+    return findings;
+  }
+});
+
+
+/**
+ * The migration files of ONE level: `migrations/*.sql`, sorted.
+ *
+ * One level and no deeper, because that is exactly as far as the convention
+ * reaches. `BASELINE/` and `SEED/**` are the SQL package the installation
+ * contract owns, and what it says about them is what they must CONTAIN (§4, the
+ * four header fields — `D-DB-HEADERS`) and never what they are called;
+ * `archive/` and `superseded/` are history a repository keeps. Writing a regex
+ * over any of the three would be this row inventing a rule
+ * (`.claude/rules/truth-over-agreement.md` §6).
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {string[]} file names
+ */
+function migrationFiles(serviceRoot, relative = MIGRATIONS_DIR) {
+  const dir = path.join(serviceRoot, ...relative.replace(/\/$/, '').split('/'));
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.sql'))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+/**
+ * The short name every per-service name is built from, or null when the
+ * repository has not said who it is — which is `C-SERVICE`'s finding, not this
+ * section's (`change-discipline.md` § One rail per concern).
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {string|null}
+ */
+function shortNameOf(serviceRoot) {
+  const identity = readIdentity(serviceRoot);
+  return identity.problem === undefined ? identity.params.service_name : null;
+}
+
+/**
+ * The value one env template declares for a key, or null.
+ *
+ * Read as the file is written — `KEY=value`, the first declaration winning, the
+ * way a shell reading it would. A commented-out line declares nothing, which is
+ * the case `D-DB-ACCOUNT` reports rather than passing over.
+ *
+ * @param {string} text the template
+ * @param {string} key the name
+ * @returns {string|null}
+ */
+function declaredValue(text, key) {
+  for (const line of text.split('\n')) {
+    const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/);
+    if (match !== null && match[1] === key) return match[2].trim();
+  }
+  return null;
+}
+
+/**
+ * The env template a service owns — the one named after it. `C-ENV` decides
+ * whether it is there and whether there is exactly one, and `C-IDENTITY`
+ * whether it carries this service's name; this function only finds it.
+ *
+ * @param {string} serviceRoot repository root
+ * @param {string} shortName
+ * @returns {{relative: string, text: string}|null}
+ */
+function ownEnvTemplate(serviceRoot, shortName) {
+  const relative = `${ENV_TEMPLATE_DIR}/${shortName}.env`;
+  const file = path.join(serviceRoot, ...relative.split('/'));
+  if (fs.existsSync(file)) return { relative, text: fs.readFileSync(file, 'utf8') };
+
+  const dir = path.join(serviceRoot, ...ENV_TEMPLATE_DIR.split('/'));
+  if (!fs.existsSync(dir)) return null;
+  const others = fs.readdirSync(dir).filter((name) => name !== SHARED_ENV && name.endsWith('.env')).sort();
+  if (others.length !== 1) return null;
+  const only = `${ENV_TEMPLATE_DIR}/${others[0]}`;
+  return { relative: only, text: fs.readFileSync(path.join(serviceRoot, ...only.split('/')), 'utf8') };
+}
+
+/**
+ * The three rows below ask their question only of a repository that DECLARES a
+ * database, and say nothing about a declaration they could not read — that one
+ * is `C-CONTRACT`'s, which calls the validator owning every rule of that file.
+ *
+ * @param {string} serviceRoot repository root
+ * @returns {boolean}
+ */
+const hasDatabase = (serviceRoot) => declaredDb(serviceRoot).db === true;
+
+/**
+ * `D-DB-NAMING` — what a migration is CALLED is the only thing a reader has
+ * before opening it, and the only thing an ordering depends on.
+ *
+ * The shape is not this row's to invent: it is read back from the node that
+ * owns it, `api/docs/biz/70-contracts/database-contract.md` §5 — three digits,
+ * an underscore, a lowercase description. No second word is demanded, which is
+ * why `000_baseline.sql` passes: §5 prints it as an example and §8 makes a
+ * regenerated baseline an applied migration. No leading verb is demanded
+ * either, and the reason is measured rather than assumed —
+ * `converter/migrations/009_cnv_batch_drop_pending_status.sql` opens with a
+ * table prefix and is right. The three digits are not decoration: `999a_…`
+ * sorts after `999_…` only by accident of the byte after the digits, and a
+ * package installed in the wrong order is the failure the whole SQL contract
+ * exists to prevent.
+ *
+ * @see api/docs/biz/70-contracts/database-contract.md
+ */
+const dbMigrationNaming = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path', 'naming']),
+
+  run({ row, serviceRoot }) {
+    if (!hasDatabase(serviceRoot)) return [];
+
+    const shape = new RegExp(row.naming);
+    const dir = row.path.replace(/\/$/, '');
+    return migrationFiles(serviceRoot, dir)
+      .filter((name) => !shape.test(name))
+      .map((name) => ({
+        where: `${dir}/${name}`,
+        what: 'the name does not read NNN_snake_case.sql — three digits, an underscore, then a '
+          + `lowercase description (${row.naming})`
+      }));
+  }
+});
+
+/**
+ * `D-DB-README` — the document that says in which order the package is run.
+ *
+ * `D-DB-PACKAGE` calls the installation contract's `SQL_PACKAGE` requirement,
+ * and that requirement checks the three directories and that each holds a `.sql`
+ * file. The contract §3 asks for a fourth thing it does not check:
+ * `migrations/README.md`. So the row is not a second owner of `SQL_PACKAGE` —
+ * it is the half of §3 nothing was looking at.
+ */
+const dbReadme = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path']),
+
+  run({ row, serviceRoot }) {
+    if (!hasDatabase(serviceRoot)) return [];
+    if (fs.existsSync(path.join(serviceRoot, ...row.path.split('/')))) return [];
+
+    return [{
+      where: row.path,
+      what: 'the SQL package carries no README — the documented execution order that reproduces a working '
+        + 'instance is the fourth thing the installation contract §3 requires, and the only one nothing '
+        + 'else checks'
+    }];
+  }
+});
+
+/**
+ * `D-DB-ACCOUNT` — the service reaches its schema as ITSELF.
+ *
+ * Confirmation `db-accounts-per-service` 001: every service has its own account
+ * with grants on its own schemas, and root stops being an operational identity.
+ * The name is the same derivation `C-IDENTITY` holds `database.schema` to, read
+ * from the same file and built with the same prefix, so the account and the
+ * schema cannot drift into two spellings of one service.
+ *
+ * A repository that declares a database and no `DB_USER` is a FINDING, not a
+ * silence: an account nobody declared is one somebody will invent at install
+ * time, and that is how root became the identity of nine containers.
+ */
+const dbAccount = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path', 'key']),
+
+  run({ row, serviceRoot }) {
+    if (!hasDatabase(serviceRoot)) return [];
+
+    const shortName = shortNameOf(serviceRoot);
+    if (shortName === null) return [];
+
+    const expected = `${DATABASE_PREFIX}${shortName}`;
+    const template = ownEnvTemplate(serviceRoot, shortName);
+    if (template === null) {
+      return [{
+        where: row.path,
+        what: `no env template of this service's own declares ${row.key}, and this service's account is `
+          + `${JSON.stringify(expected)}`
+      }];
+    }
+
+    const declared = declaredValue(template.text, row.key);
+    if (declared === null) {
+      return [{
+        where: template.relative,
+        what: `declares no ${row.key}, and this service's account is ${JSON.stringify(expected)}`
+      }];
+    }
+    if (declared === expected) return [];
+
+    return [{
+      where: template.relative,
+      what: `${row.key} is ${JSON.stringify(declared)}, and the account derived from ${IDENTITY_FILE} `
+        + `is ${JSON.stringify(expected)}`
+    }];
+  }
+});
+
+/**
+ * `D-DB-COLLATION` — the schema is created with a collation this service CHOSE.
+ *
+ * Owner decision 2026-09-14 (`db-collation-declaration` 001): the collation of a
+ * biz schema is the service's own declaration, one key in the `database` block,
+ * and the CI gate and the production runbook both read it. Without it each of
+ * them invents one — which is how six schemas came to exist with the image
+ * default `utf8mb4_general_ci` while every table inside them declares
+ * `utf8mb4_bin` or `utf8mb4_unicode_ci` (measured 2026-09-14: 122 of 123
+ * permanent tables declare their collation explicitly).
+ *
+ * This row asks ONE question — is the key there — and deliberately not the other
+ * two. Whether the VALUE is a collation name is the contract validator's rule,
+ * which `C-CONTRACT` calls; refusing to BUILD without it is
+ * `utils/setupDatabase.js`, at the moment it would have to interpolate the
+ * value. A row restating either would be the duplicate that already cost
+ * `D-DB-DECL` its place (see the head of this file).
+ *
+ * It reads the `database` BLOCK rather than `requiredConnectors.db`, because the
+ * block is what the gate builds from: a contract without one has no schema to
+ * create, and `biz-ci-gate setup-db` says NOT APPLICABLE over it.
+ *
+ * @see api/docs/governance/confirmations/db-collation-declaration.md
+ */
+const dbCollation = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path', 'key']),
+
+  run({ row, serviceRoot }) {
+    const file = path.join(serviceRoot, ...row.path.split('/'));
+    if (!fs.existsSync(file)) return [];
+
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (error) {
+      // An unreadable contract is `C-CONTRACT`'s finding, with its own fix.
+      return [];
+    }
+
+    const database = parsed.database;
+    if (database === undefined || database === null || typeof database !== 'object') return [];
+
+    const declared = database[row.key];
+    if (typeof declared === 'string' && declared.trim() !== '') return [];
+
+    return [{
+      where: row.path,
+      what: `the database block declares no database.${row.key} — the CI gate and the production runbook both create `
+        + 'this schema with the collation the service declares, and there is no default'
+    }];
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'db-consistent', check: dbConsistent },
+    { name: 'db-collation', check: dbCollation },
+    { name: 'db-migration-naming', check: dbMigrationNaming },
+    { name: 'db-readme', check: dbReadme },
+    { name: 'db-account', check: dbAccount }
+  ]
+};