@onlineapps/conn-orch-validator 6.0.1 → 8.0.0

package/manifests/library.manifest.json

@@ -0,0 +1,324 @@
+{
+  "uniform": "library",
+  "doc": "api/docs/governance/confirmations/biz-service-manifest.md §10-§15",
+  "owner": "BIZ-general",
+  "blocking_severities": [
+    "publish"
+  ],
+  "verdict": {
+    "blocked": "NOT PUBLISHABLE",
+    "clear": "PUBLISHABLE",
+    "incomplete": "INCOMPLETE: {count} publish row(s) not run ({ids}). Fix: run the uniform from the api checkout — npx oa-validate --library --all --workspace <workspace root>"
+  },
+  "discovery": {
+    "library": {
+      "concern": "which directories wear this uniform, and who says they exist",
+      "pattern": "api/shared/**/package.json",
+      "exclude": [
+        "**/node_modules/**",
+        "**/tests/fixtures/**"
+      ],
+      "from": {
+        "path": "api/config/libraries.json",
+        "list": "libraries",
+        "names": "keys"
+      },
+      "categories": {
+        "core": {
+          "layer": "L1",
+          "concern": "no @onlineapps dependency at all - the foundation every other layer may reach for",
+          "may_depend_on": [],
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+        },
+        "connector": {
+          "layer": "L2",
+          "concern": "one external resource each, reached by injection; consumed by services and by orchestration",
+          "may_depend_on": [
+            "core",
+            "connector"
+          ],
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+        },
+        "orchestration": {
+          "layer": "L3",
+          "concern": "coordinates connectors; consumed by services and by runtime",
+          "may_depend_on": [
+            "core",
+            "connector",
+            "orchestration"
+          ],
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+        },
+        "runtime": {
+          "layer": "L4",
+          "concern": "what a running service boots into; consumed by services",
+          "may_depend_on": [
+            "core",
+            "connector",
+            "orchestration",
+            "runtime"
+          ],
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+        },
+        "tooling": {
+          "layer": "none",
+          "concern": "developers and CI, never a running service",
+          "may_depend_on": [
+            "core",
+            "connector",
+            "orchestration",
+            "runtime",
+            "tooling"
+          ],
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+        }
+      },
+      "rows": [
+        {
+          "id": "U-ORPHAN",
+          "check": "library-orphan",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "a package on disk the SSOT does not know is published by nothing and pinned by nobody; a name in the SSOT with no package is a version declared for code that does not exist",
+          "fix": "declare the package in api/config/libraries.json (libraries), or remove it from api/shared/",
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-005"
+        },
+        {
+          "id": "U-MISMATCH",
+          "check": "library-category",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "the category is the one fact about a library that cannot be derived - it is the intent, and the dependency graph is the measurement it is checked against",
+          "fix": "declare \"oa\": { \"category\": \"<core|connector|orchestration|runtime|tooling>\" } in package.json, and make the dependencies agree with the category's may_depend_on",
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-005"
+        }
+      ]
+    }
+  },
+  "duties": {
+    "all": {
+      "concern": "what every library owes, whatever it is for",
+      "applies_to": "*",
+      "rows": [
+        {
+          "id": "L-MAIN",
+          "check": "library-main",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "a package whose entry point is undeclared or missing installs and then fails at the consumer's first require",
+          "fix": "declare \"main\" in package.json and make it point at a file that exists",
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+        },
+        {
+          "id": "L-ENGINES",
+          "check": "library-engines",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "one Node major runs the whole platform; a library declaring another one lets npm install it into a runtime nobody tested it on",
+          "fix": "set engines.node to the platform major, e.g. \">=24.0.0 <25\"",
+          "doc": "api/docs/governance/confirmations/node-runtime-version.md § Confirmation 20260908-node-runtime-version-003",
+          "from": {
+            "path": "api/.nvmrc",
+            "text": true
+          }
+        },
+        {
+          "id": "L-TESTS",
+          "check": "library-tests",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "no production code without a test (architecture-principles §10); a package with no unit tier has nothing to run before publishing",
+          "fix": "add tests/unit with at least one *.test.js",
+          "doc": ".claude/rules/architecture-principles.md §10"
+        },
+        {
+          "id": "L-TEST-SCRIPT",
+          "check": "library-test-script",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "the publish path runs `npm test`; a package without that script is published without a run",
+          "fix": "declare scripts.test in package.json",
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+        },
+        {
+          "id": "L-PACK-TESTS",
+          "check": "library-pack-tests",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "tests in the published tarball ship fixtures and dev assumptions into every consumer; the effect is what matters, and a files allowlist achieves it without .npmignore",
+          "fix": "add a files allowlist to package.json that omits tests, or exclude tests/ in .npmignore",
+          "doc": ".claude/rules/architecture-principles.md § Shared Packages"
+        },
+        {
+          "id": "L-PINS",
+          "check": "library-pins",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "the same commit must install the same code; the manifest is the single owner of every @onlineapps version",
+          "fix": "run api/scripts/sync-versions-to-exact.sh, or publish the version the package needs and sync the manifest",
+          "doc": ".claude/rules/architecture-principles.md § Version pinning",
+          "from": {
+            "path": "api/config/libraries.json",
+            "list": "libraries",
+            "names": "keys"
+          }
+        },
+        {
+          "id": "L-NO-FILE-RANGE",
+          "check": "library-dep-range",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "a range or a file: reference makes the installed code depend on the day and on the machine",
+          "fix": "pin the exact version the SSOT declares - no ^, no ~, no file:",
+          "doc": ".claude/rules/architecture-principles.md § Version pinning"
+        },
+        {
+          "id": "L-CHANGELOG",
+          "check": "file-present",
+          "path": "CHANGELOG.md",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "a published version whose change nobody wrote down is a version nobody can reason about afterwards",
+          "fix": "add CHANGELOG.md with an entry for the version being published",
+          "doc": "api/docs/guides/library-publishing-process.md"
+        },
+        {
+          "id": "L-README",
+          "check": "library-readme",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "a README that cannot say which fact class it owns has no reason to exist, and nobody can tell a live one from a stale one",
+          "fix": "give README.md the node header - \"> Owns: <the fact class this file is the single owner of>\" and \"> Status: current|draft|archived\"",
+          "doc": "api/docs/standards/INFRA-DOC-STANDARD.md"
+        },
+        {
+          "id": "L-README-REGION",
+          "check": "library-readme-region",
+          "path": "README.md",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "the same duty as L-README one row up, on the half of the file that is generated: L-README asks whether the node header is there, this row asks whether the rendered uniform pointer still says what the manifest says. A separate row because the two have separate fixes - one is written by a human, the other by a command",
+          "fix": "npx oa-sync-template readme-uniform --all",
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md § Confirmation 20260909-biz-service-manifest-005"
+        },
+        {
+          "id": "L-CONSUMER",
+          "check": "library-consumer",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "a library nobody depends on is either unwired or dead, and the third option does not exist",
+          "fix": "wire the package into the consumer that should use it, or delete it - git keeps the history",
+          "doc": ".claude/rules/change-discipline.md § Removing something removes its declaration",
+          "consumer_patterns": [
+            "api_biz/*/package.json",
+            "api/infra/*/package.json",
+            "api/shared/**/package.json",
+            "api/package.json"
+          ]
+        }
+      ]
+    },
+    "core": {
+      "concern": "layer L1 - the foundation",
+      "applies_to": "core",
+      "rows": [
+        {
+          "id": "L-CORE-DEPS",
+          "check": "library-core-deps",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "core is L1 by construction, not by intention - one @onlineapps dependency and it is a connector wearing the wrong name",
+          "fix": "remove the @onlineapps dependency, or declare the category the graph shows",
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+        },
+        {
+          "id": "L-CORE-EXPORTS",
+          "check": "library-core-exports",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "everything above L1 imports from here, so what the package exports is its contract and must be explicit",
+          "fix": "declare exports in package.json, or make main resolve to a module that exports named symbols",
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+        }
+      ]
+    },
+    "connector": {
+      "concern": "layer L2 - one external resource each",
+      "applies_to": "connector",
+      "rows": [
+        {
+          "id": "L-CONNECTOR-ENV",
+          "check": "library-source-env",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "a connector receives its dependencies, it does not go looking for them; reading the environment outside the config module is the hidden input DI exists to remove - the module is one file or one directory, the concept is the same",
+          "fix": "take the value through the constructor and read the environment in the config module only - src/config/ or src/config.js",
+          "doc": ".claude/rules/architecture-principles.md §1",
+          "allowed": [
+            "src/config/",
+            "src/config.js"
+          ]
+        }
+      ]
+    },
+    "runtime": {
+      "concern": "layer L4 - what a running service boots into",
+      "applies_to": "runtime",
+      "rows": [
+        {
+          "id": "L-RUNTIME-CLIENT",
+          "check": "library-runtime-client",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "storage and database access has one unified rail; a runtime package holding its own client is a second one",
+          "fix": "depend on the connector that owns the resource instead of on the client library",
+          "doc": "api/.claude/rules/package-management.md § Storage Architecture",
+          "forbidden_packages": [
+            "minio",
+            "mysql2",
+            "pg",
+            "sequelize"
+          ]
+        }
+      ]
+    },
+    "tooling": {
+      "concern": "developers and CI, never a running service",
+      "applies_to": "tooling",
+      "rows": [
+        {
+          "id": "L-TOOLING",
+          "check": "library-tooling",
+          "severity": "publish",
+          "owner": "BIZ-general",
+          "why": "tooling is reached by a command, not by an import; a service carrying it in dependencies ships a developer tool into production",
+          "fix": "declare a bin entry, and move the package out of every service's dependencies",
+          "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11",
+          "service_pattern": "api_biz/*/package.json"
+        }
+      ]
+    }
+  },
+  "guidance": {
+    "L-LINT": {
+      "why": "not a row: three eslint configs, four lint scripts and no gate anywhere in api/shared (measured 2026-09-09). Under this manifest exactly one of two things is true - one shared config in this package, run by the publish gate, or no config anywhere. Leave-as-is is the defect state, not an option; the execution is d.213.",
+      "doc": "api/docs/governance/confirmations/biz-service-manifest.md §14"
+    },
+    "L-LOGGER-ERROR-CONTRACT": {
+      "why": "not a row: 002 §11 asks a connector to implement the logger contract and the error contract, but names no observable that decides it. A pin on @onlineapps/logger-contract is not the duty - 2 of 8 connectors carry one and that says nothing about behaviour. No check, so not a rule (001 §6).",
+      "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+    },
+    "L-BOOT-PHASES": {
+      "why": "not a row: 002 §11 asks a runtime package to ship its boot phases with [Context] Problem - Fix messages. Which phases a package owns is not declared anywhere, so nothing can decide the duty. No check, so not a rule (001 §6).",
+      "doc": ".claude/rules/architecture-principles.md §5"
+    },
+    "L-EXPORT-MAJOR": {
+      "why": "not a row: a removed or renamed export must bump the major, which needs the previous published version's exports to compare against. That comparison belongs to the publish path, where the registry is reachable - the candidate check is a diff of exports against the published version in publish-library.sh (d.214).",
+      "doc": ".claude/rules/architecture-principles.md § Shared Packages"
+    },
+    "L-TEST-SCRIPT-BODY": {
+      "why": "not a row: 002 §11 asks for a test script equal to the category's canonical body, and no canonical body is decided. Measured today: 2 bodies for scripts.test, 3 for scripts.test:unit, and the split follows no category. L-TEST-SCRIPT therefore checks existence only.",
+      "doc": "api/docs/governance/confirmations/biz-service-manifest.md §11"
+    }
+  }
+}

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "6.0.1",
+  "version": "8.0.0",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
+  "oa": {
+    "category": "orchestration"
+  },
   "main": "src/index.js",
   "bin": {
-    "oa-biz-ci-gate": "src/cli/biz-ci-gate.js"
+    "oa-biz-ci-gate": "src/cli/biz-ci-gate.js",
+    "oa-lint-scripts": "src/cli/oa-lint-scripts.js",
+    "oa-sync-template": "src/cli/oa-sync-template.js",
+    "oa-validate": "src/cli/oa-validate.js"
   },
   "scripts": {
-    "test": "jest",
+    "test": "npm run test:unit",
     "test:unit": "jest tests/unit",
-    "test:integration": "jest tests/integration",
     "test:coverage": "jest --coverage"
   },
   "keywords": [
@@ -23,13 +28,14 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
-    "@onlineapps/service-validator-core": "1.0.15"
+    "@onlineapps/logger-contract": "1.1.0",
+    "@onlineapps/service-validator-core": "2.0.0"
   },
   "devDependencies": {
     "jest": "^29.5.0"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=24.0.0 <25"
   },
   "directories": {
     "doc": "docs",