@onlineapps/conn-orch-validator 7.0.0 → 8.0.0

package/src/manifest/checks/libraryPackage.js

@@ -0,0 +1,272 @@
+'use strict';
+
+/**
+ * The rows a library's own `package.json` decides, without looking anywhere else:
+ * the entry point, the Node major, the test script, the dependency specifiers,
+ * and the two duties that belong to one category each (`core` exports and
+ * dependencies, `runtime` resource clients).
+ *
+ * Every check here is `scope: 'service'` — it needs the package directory and
+ * nothing more — except `library-engines`, which resolves the platform major
+ * through the row's `from:` reference and is therefore workspace-scoped.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §11
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { resolveFromValue } = require('../discovery');
+const {
+  readPackage, whereOf, appliesTo, allDeps, scopedDeps, nodeMajorOf
+} = require('./libraryContext');
+
+/** The sections that answer "what does this package pull into a runtime". */
+const RUNTIME_SECTIONS = Object.freeze(['dependencies']);
+
+/** The sections `scripts/ci/verify-manifest-pins.mjs` compares against the SSOT. */
+const PINNED_SECTIONS = Object.freeze(['dependencies', 'devDependencies']);
+
+/** A specifier that is not one exact version, within the scope the SSOT owns. */
+const RANGE_PREFIX = /^[\^~]/;
+
+/** The specifiers that are a range rather than one version. */
+const FLOATING = Object.freeze(['latest', '*']);
+
+/**
+ * Every section npm resolves a dependency from. A `file:` in ANY of them is the
+ * same defect, so the row reads all four — while a RANGE is only judged in the
+ * two the pins row reads, and only inside the scope the SSOT owns.
+ */
+const ALL_DEPENDENCY_SECTIONS = Object.freeze([
+  'dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'
+]);
+
+/** A specifier resolved from a path on the machine that wrote it. */
+const isFileReference = (spec) => spec.startsWith('file:');
+
+/**
+ * Shared preamble: read the package, and decide whether the row applies at all.
+ *
+ * @param {{ block: object, serviceRoot: string|null, workspaceRoot: string|null }} params
+ * @param {string} scope the calling check's scope, which decides what `where` is relative to
+ * @returns {{ pkg: object, where: (relative?: string) => string }|null} null when the row does not apply
+ */
+function contextFor({ block, serviceRoot, workspaceRoot }, scope = 'service') {
+  const { json } = readPackage(serviceRoot);
+  if (json === null) return null;
+  if (!appliesTo(block, json)) return null;
+  return {
+    pkg: json,
+    where: (relative = 'package.json') => whereOf({ scope, serviceRoot, workspaceRoot, relative })
+  };
+}
+
+const libraryMain = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  run({ block, serviceRoot, workspaceRoot }) {
+    const { json } = readPackage(serviceRoot);
+    const where = (relative = 'package.json') => whereOf({ scope: 'service', serviceRoot, workspaceRoot, relative });
+
+    if (json === null) {
+      return [{ where: where(), what: 'package.json is absent — nothing declares this directory a package' }];
+    }
+    if (!appliesTo(block, json)) return [];
+
+    if (typeof json.main !== 'string' || json.main.length === 0) {
+      return [{ where: where(), what: 'declares no "main" — a consumer\'s require() has no entry point to land on' }];
+    }
+    const target = path.join(serviceRoot, ...json.main.split('/'));
+    if (!fs.existsSync(target)) {
+      return [{ where: where(), what: `"main" points at ${json.main}, which does not exist in the package` }];
+    }
+    return [];
+  }
+});
+
+const libraryEngines = Object.freeze({
+  scope: 'bearer',
+  requires: Object.freeze(['from']),
+
+  describeNotRun({ row }) {
+    return `the workspace root is not reachable, so ${row.from.path} cannot be read`;
+  },
+
+  run({ row, block, serviceRoot, workspaceRoot }) {
+    const context = contextFor({ block, serviceRoot, workspaceRoot }, 'bearer');
+    if (context === null) return [];
+
+    const platform = nodeMajorOf(resolveFromValue({ from: row.from, workspaceRoot }));
+    if (platform === null) {
+      throw new Error(`[LibraryManifest] Platform Node major unreadable - ${row.from.path} carries no number. `
+        + 'Fix: repair the file; it is the single owner of the major every package is measured against.');
+    }
+
+    const declared = context.pkg.engines && context.pkg.engines.node;
+    if (typeof declared !== 'string' || declared.length === 0) {
+      return [{
+        where: context.where(),
+        what: `declares no engines.node — the platform runs Node ${platform}`
+      }];
+    }
+    const major = nodeMajorOf(declared);
+    if (major !== platform) {
+      return [{
+        where: context.where(),
+        what: `engines.node is "${declared}" (major ${major}) but the platform major is ${platform}`
+      }];
+    }
+    return [];
+  }
+});
+
+const libraryTestScript = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  run(params) {
+    const context = contextFor(params);
+    if (context === null) return [];
+    const script = context.pkg.scripts && context.pkg.scripts.test;
+    if (typeof script === 'string' && script.length > 0) return [];
+    return [{
+      where: context.where(),
+      what: 'declares no scripts.test — the publish path has no run to make'
+    }];
+  }
+});
+
+/**
+ * Two rules under one row, and the difference between them is who owns the
+ * version.
+ *
+ *   * a RANGE (`^`, `~`, `latest`, `*`) is wrong for an `@onlineapps` package,
+ *     because `api/config/libraries.json` owns that version and a floating range
+ *     installs different code on different days. Outside that scope nothing here
+ *     owns the version, so a caret on `jest` is not this row's business;
+ *   * a `file:` is wrong for ANY package, in any section: it resolves to a path
+ *     on the machine that wrote it and never reaches a published tarball
+ *     (`.claude/rules/architecture-principles.md` § Shared Packages).
+ *
+ * The second half is d.224d. It was `@onlineapps`-only until then — measured by
+ * d.224c: `lodash = file:../lodash` in `devDependencies` passed the uniform, so
+ * the publish gate had to keep rule G2 of its own for exactly that case, which
+ * is one concern on two rails (`change-discipline.md` § One rail per concern).
+ * With the row reading every package, G2 is gone and the gate reads this row.
+ */
+const libraryDepRange = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  run(params) {
+    const context = contextFor(params);
+    if (context === null) return [];
+
+    const files = allDeps(context.pkg, ALL_DEPENDENCY_SECTIONS)
+      .filter(({ spec }) => isFileReference(spec))
+      .map(({ name, spec, section }) => ({
+        where: context.where(),
+        what: `${section} points ${name} at "${spec}" — a file: reference resolves to a path on one machine `
+          + 'and never reaches a published package'
+      }));
+
+    // A `file:` on an @onlineapps package is already above; reported twice it
+    // would be one defect with two sentences and two fixes.
+    const ranges = scopedDeps(context.pkg, PINNED_SECTIONS)
+      .filter(({ spec }) => !isFileReference(spec))
+      .filter(({ spec }) => RANGE_PREFIX.test(spec) || FLOATING.includes(spec))
+      .map(({ name, spec, section }) => ({
+        where: context.where(),
+        what: `${section} pins ${name} at "${spec}", which is not one exact version`
+      }));
+
+    return [...files, ...ranges];
+  }
+});
+
+const libraryCoreDeps = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  run(params) {
+    const context = contextFor(params);
+    if (context === null) return [];
+
+    return scopedDeps(context.pkg, RUNTIME_SECTIONS).map(({ name }) => ({
+      where: context.where(),
+      what: `depends on ${name} — a core package has no @onlineapps dependency at all`
+    }));
+  }
+});
+
+const libraryCoreExports = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  run(params) {
+    const context = contextFor(params);
+    if (context === null) return [];
+    if (context.pkg.exports !== undefined) return [];
+
+    const main = context.pkg.main;
+    if (typeof main !== 'string' || main.length === 0) return [];
+
+    const target = path.join(params.serviceRoot, ...main.split('/'));
+    if (!fs.existsSync(target)) return [];
+
+    let loaded;
+    try {
+      // eslint-disable-next-line global-require, import/no-dynamic-require
+      loaded = require(target);
+    } catch (error) {
+      return [{
+        where: context.where(main),
+        what: `"main" does not load: ${error.message.split('\n')[0]} `
+          + '(run npm install in the package if a dependency is missing, then re-run)'
+      }];
+    }
+
+    const named = loaded !== null && typeof loaded === 'object' && Object.keys(loaded).length > 0;
+    if (named || typeof loaded === 'function') return [];
+    return [{
+      where: context.where(main),
+      what: 'declares no "exports" and "main" exports no named symbol — the contract of an L1 package is not explicit'
+    }];
+  }
+});
+
+const libraryRuntimeClient = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['forbidden_packages']),
+
+  run(params) {
+    const context = contextFor(params);
+    if (context === null) return [];
+
+    const declared = context.pkg.dependencies || {};
+    return params.row.forbidden_packages
+      .filter((name) => Object.prototype.hasOwnProperty.call(declared, name))
+      .map((name) => ({
+        where: context.where(),
+        what: `depends on ${name} directly — storage and database access has one unified rail`
+      }));
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'library-main', check: libraryMain },
+    { name: 'library-engines', check: libraryEngines },
+    { name: 'library-test-script', check: libraryTestScript },
+    { name: 'library-dep-range', check: libraryDepRange },
+    { name: 'library-core-deps', check: libraryCoreDeps },
+    { name: 'library-core-exports', check: libraryCoreExports },
+    { name: 'library-runtime-client', check: libraryRuntimeClient }
+  ],
+  contextFor,
+  PINNED_SECTIONS,
+  RUNTIME_SECTIONS,
+  ALL_DEPENDENCY_SECTIONS
+};

package/src/manifest/checks/librarySource.js

@@ -0,0 +1,274 @@
+'use strict';
+
+/**
+ * `library-source-env` — a connector receives its dependencies, it does not go
+ * looking for them.
+ *
+ * `process.env` inside `src/` is the measurable form of the hidden input
+ * dependency injection exists to remove (architecture-principles §1, §8). One
+ * place is exempt and the row names it: the config module, whose whole job is to
+ * turn the environment into an explicit object the constructor is handed.
+ *
+ * The row states that place as a list, because the module is a concept and not a
+ * shape: a package big enough for a `src/config/` directory and one small enough
+ * for a single `src/config.js` are wearing the same uniform, and the duty is the
+ * same for both (lead decision, `api/shared/TODO.md` §0.2b-15). An entry ending
+ * in `/` exempts a directory, any other entry exempts exactly that one file.
+ *
+ * The question is asked of CODE. A module that documents the duty it obeys —
+ * "this module reads no `process.env`" — is the duty kept, and reporting it is
+ * the check calling a sentence a defect. Measured: `conn-base-db`'s
+ * `src/createSequelize.js` was reported for exactly that sentence in its own
+ * header. So the file is read as source and its prose is blanked before the
+ * search: comments, the text of string and template literals, and
+ * regular-expression literals. What a template literal interpolates is code
+ * again, because `${process.env.X}` really does read the environment.
+ *
+ * @see .claude/rules/architecture-principles.md §1
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { readPackage, whereOf, appliesTo } = require('./libraryContext');
+
+/** Where the search starts. Only shipped source is read; tests are not the rule. */
+const SOURCE_DIR = 'src';
+
+/** The one hidden input this row is about. */
+const ENV_READ = /process\.env\b/;
+
+/** Characters that may open an identifier — and so may continue one. */
+const IDENTIFIER = /[A-Za-z0-9_$]/;
+
+/**
+ * After one of these, a `/` divides; after anything else it opens a regular
+ * expression. Keywords are the exception the other way round: `return /x/` is a
+ * regular expression even though `return` ends in an identifier character.
+ */
+const DIVISION_AFTER = new Set([')', ']', '}', "'", '"', '`']);
+const KEYWORD_BEFORE_REGEX = new Set([
+  'return', 'typeof', 'instanceof', 'in', 'of', 'case', 'delete',
+  'void', 'new', 'do', 'else', 'yield', 'await', 'throw'
+]);
+
+/**
+ * The source with every run of prose replaced by spaces of the same length, so
+ * a textual search answers a question about code and nothing else.
+ *
+ * Newlines are kept, so a position in the result is the same position in the
+ * file. Delimiters that carry meaning for the reader of the result — the quotes
+ * around a blanked string, the `${` and `}` of a live interpolation — are kept;
+ * a comment and a regular-expression literal go entirely, because a surviving
+ * `/` would read as division.
+ *
+ * @param {string} source the file, verbatim
+ * @returns {string} the same length, prose blanked out
+ */
+function codeOnly(source) {
+  const out = source.split('');
+  const blank = (from, to) => {
+    for (let k = from; k < to && k < out.length; k += 1) if (out[k] !== '\n') out[k] = ' ';
+  };
+
+  /** Nested contexts: template text and the code inside its interpolations. */
+  const frames = [{ template: false, braces: 0 }];
+  let previous = '';
+  let word = '';
+  let i = 0;
+
+  const remember = (character) => {
+    if (character === ' ' || character === '\t' || character === '\n' || character === '\r') return;
+    previous = character;
+    word = IDENTIFIER.test(character) ? word + character : '';
+  };
+
+  while (i < source.length) {
+    const frame = frames[frames.length - 1];
+    const character = source[i];
+    const next = source[i + 1];
+
+    if (frame.template) {
+      if (character === '\\') {
+        blank(i, i + 2);
+        i += 2;
+      } else if (character === '`') {
+        frames.pop();
+        previous = '`';
+        word = '';
+        i += 1;
+      } else if (character === '$' && next === '{') {
+        frames.push({ template: false, braces: 0 });
+        previous = '{';
+        word = '';
+        i += 2;
+      } else {
+        blank(i, i + 1);
+        i += 1;
+      }
+      continue;
+    }
+
+    if (character === '/' && next === '/') {
+      let end = i;
+      while (end < source.length && source[end] !== '\n') end += 1;
+      blank(i, end);
+      i = end;
+      continue;
+    }
+
+    if (character === '/' && next === '*') {
+      let end = i + 2;
+      while (end < source.length && !(source[end] === '*' && source[end + 1] === '/')) end += 1;
+      end = Math.min(end + 2, source.length);
+      blank(i, end);
+      i = end;
+      continue;
+    }
+
+    if (character === "'" || character === '"') {
+      let end = i + 1;
+      while (end < source.length && source[end] !== character && source[end] !== '\n') {
+        end += source[end] === '\\' ? 2 : 1;
+      }
+      blank(i + 1, Math.min(end, source.length));
+      i = Math.min(end, source.length) + 1;
+      remember(character);
+      continue;
+    }
+
+    if (character === '`') {
+      frames.push({ template: true, braces: 0 });
+      remember(character);
+      i += 1;
+      continue;
+    }
+
+    if (character === '/') {
+      const end = endOfRegex(source, i);
+      if (end !== -1) {
+        blank(i, end);
+        i = end;
+        previous = '/';
+        word = '';
+        continue;
+      }
+    }
+
+    if (character === '{') frame.braces += 1;
+    if (character === '}') {
+      if (frame.braces === 0 && frames.length > 1) {
+        frames.pop();
+        previous = '}';
+        word = '';
+        i += 1;
+        continue;
+      }
+      frame.braces -= 1;
+    }
+
+    remember(character);
+    i += 1;
+  }
+
+  return out.join('');
+
+  /**
+   * Where the regular-expression literal starting at `start` ends, flags
+   * included — or `-1` when that `/` is a division sign, or opens nothing that
+   * closes on the same line.
+   *
+   * @param {string} text the file
+   * @param {number} start index of the `/`
+   * @returns {number} the index one past the literal, or -1
+   */
+  function endOfRegex(text, start) {
+    if (DIVISION_AFTER.has(previous)) return -1;
+    if (IDENTIFIER.test(previous) && !KEYWORD_BEFORE_REGEX.has(word)) return -1;
+
+    let k = start + 1;
+    let inClass = false;
+    while (k < text.length && text[k] !== '\n') {
+      const character = text[k];
+      if (character === '\\') {
+        k += 2;
+        continue;
+      }
+      if (character === '[') inClass = true;
+      else if (character === ']') inClass = false;
+      else if (character === '/' && !inClass) {
+        k += 1;
+        while (k < text.length && /[a-z]/.test(text[k])) k += 1;
+        return k;
+      }
+      k += 1;
+    }
+    return -1;
+  }
+}
+
+/**
+ * Every `.js` file under `dir`, as paths relative to `root`, `/`-separated.
+ *
+ * @param {string} root the package directory
+ * @param {string} dir absolute directory to walk
+ * @returns {string[]}
+ */
+function sourceFiles(root, dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return [];
+  }
+
+  const found = [];
+  for (const entry of entries) {
+    const absolute = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules') continue;
+      found.push(...sourceFiles(root, absolute));
+    } else if (entry.name.endsWith('.js')) {
+      found.push(path.relative(root, absolute).split(path.sep).join('/'));
+    }
+  }
+  return found;
+}
+
+/**
+ * Is this file part of the config module the row exempts?
+ *
+ * @param {string} relative the file, relative to the package root, `/`-separated
+ * @param {string[]} allowed the row's exemptions — a trailing `/` means a directory
+ * @returns {boolean}
+ */
+function isExempt(relative, allowed) {
+  return allowed.some((entry) => (entry.endsWith('/') ? relative.startsWith(entry) : relative === entry));
+}
+
+const librarySourceEnv = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['allowed']),
+
+  run({ row, block, serviceRoot, workspaceRoot }) {
+    const { json } = readPackage(serviceRoot);
+    if (json === null || !appliesTo(block, json)) return [];
+
+    const allowed = row.allowed;
+
+    return sourceFiles(serviceRoot, path.join(serviceRoot, SOURCE_DIR))
+      .filter((relative) => !isExempt(relative, allowed))
+      .filter((relative) => ENV_READ.test(codeOnly(fs.readFileSync(path.join(serviceRoot, relative), 'utf8'))))
+      .map((relative) => ({
+        where: whereOf({ scope: 'service', serviceRoot, workspaceRoot, relative }),
+        what: `reads process.env outside ${allowed.join(' and ')} — the value belongs in the constructor`
+      }));
+  }
+});
+
+module.exports = {
+  checks: [{ name: 'library-source-env', check: librarySourceEnv }],
+  codeOnly,
+  sourceFiles,
+  isExempt
+};

package/src/manifest/checks/libraryTests.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * The two rows about tests: that the package HAS a unit tier, and that the tier
+ * does not travel to the consumer inside the tarball.
+ *
+ * `library-pack-tests` measures the EFFECT, not the file. Twenty packages keep
+ * tests out with `.npmignore` and eight with a `files` allowlist that simply
+ * never names them (measured over `api/shared` 2026-09-09); a row checking for
+ * `.npmignore` would report eight packages that are already correct, and would
+ * miss the ninth that has the file and lists nothing. So the check reproduces
+ * npm's own precedence — `files` allowlist first, then `.npmignore`, then
+ * `.gitignore` — and asks one question: does `tests/` end up in the tarball.
+ *
+ * @see .claude/rules/architecture-principles.md § Shared Packages
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { readPackage, readText, whereOf, appliesTo } = require('./libraryContext');
+
+/** The directory both rows are about. */
+const TEST_DIR = 'tests';
+
+/** The unit tier, and the two suffixes a test file wears in this workspace. */
+const UNIT_DIR = path.join('tests', 'unit');
+const TEST_FILE = /\.(test|spec)\.js$/;
+
+/**
+ * Does an ignore-file line take `tests/` out of the tarball? npm reads these
+ * with gitignore semantics; the shapes that actually occur are the bare name,
+ * the anchored name, and the name with a trailing slash or glob.
+ *
+ * @param {string} body the contents of .npmignore or .gitignore
+ * @returns {boolean}
+ */
+function ignoresTests(body) {
+  return body
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'))
+    .some((line) => /^\/?tests(\/(\*\*?)?)?$/.test(line));
+}
+
+/**
+ * Does a `files` allowlist entry let `tests/` in? An entry is a path or a glob;
+ * it reaches the directory only when its first segment is the directory itself.
+ *
+ * @param {string[]} files the allowlist
+ * @returns {boolean}
+ */
+function allowsTests(files) {
+  return files.some((entry) => String(entry).replace(/^\.?\//, '').split('/')[0] === TEST_DIR);
+}
+
+const libraryTests = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  run({ block, serviceRoot, workspaceRoot }) {
+    const { json } = readPackage(serviceRoot);
+    if (json === null || !appliesTo(block, json)) return [];
+
+    const where = whereOf({ scope: 'service', serviceRoot, workspaceRoot, relative: UNIT_DIR.split(path.sep).join('/') });
+    const dir = path.join(serviceRoot, UNIT_DIR);
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      return [{ where, what: 'the unit tier is absent — no production code without a test' }];
+    }
+    if (!entries.some((name) => TEST_FILE.test(name))) {
+      return [{ where, what: `the unit tier holds no test file (${entries.length} entr(y|ies), none matching *.test.js)` }];
+    }
+    return [];
+  }
+});
+
+const libraryPackTests = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze([]),
+
+  run({ block, serviceRoot, workspaceRoot }) {
+    const { json } = readPackage(serviceRoot);
+    if (json === null || !appliesTo(block, json)) return [];
+
+    const where = whereOf({ scope: 'service', serviceRoot, workspaceRoot, relative: 'package.json' });
+    if (!fs.existsSync(path.join(serviceRoot, TEST_DIR))) return [];
+
+    if (Array.isArray(json.files)) {
+      if (!allowsTests(json.files)) return [];
+      return [{ where, what: `the files allowlist names ${TEST_DIR} — the tier would ship to every consumer` }];
+    }
+
+    for (const name of ['.npmignore', '.gitignore']) {
+      const body = readText(path.join(serviceRoot, name));
+      if (body === null) continue;
+      if (ignoresTests(body)) return [];
+      return [{
+        where: whereOf({ scope: 'service', serviceRoot, workspaceRoot, relative: name }),
+        what: `does not exclude ${TEST_DIR}/, and no files allowlist does either — the tier would ship to every consumer`
+      }];
+    }
+
+    return [{
+      where,
+      what: `no files allowlist, no .npmignore, no .gitignore — ${TEST_DIR}/ would ship to every consumer`
+    }];
+  }
+});
+
+module.exports = {
+  checks: [
+    { name: 'library-tests', check: libraryTests },
+    { name: 'library-pack-tests', check: libraryPackTests }
+  ],
+  ignoresTests,
+  allowsTests
+};