@htilabs/platform-common-models 0.8.12 → 0.8.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +44 -0
- package/dist/config/index.cjs +4 -0
- package/dist/config/index.cjs.map +1 -1
- package/dist/config/index.d.cts +16 -1
- package/dist/config/index.d.ts +16 -1
- package/dist/config/index.js +2 -0
- package/dist/config/index.js.map +1 -1
- package/dist/constants/index.cjs +143 -287
- package/dist/constants/index.cjs.map +1 -1
- package/dist/constants/index.d.cts +1 -1
- package/dist/constants/index.d.ts +1 -1
- package/dist/constants/index.js +143 -275
- package/dist/constants/index.js.map +1 -1
- package/dist/cvcs/index.cjs +12173 -969
- package/dist/cvcs/index.cjs.map +1 -1
- package/dist/cvcs/index.d.cts +14927 -2662
- package/dist/cvcs/index.d.ts +14927 -2662
- package/dist/cvcs/index.js +12141 -968
- package/dist/cvcs/index.js.map +1 -1
- package/dist/{index-I-DiX9eQ.d.ts → index-CDoqrfc1.d.ts} +1 -1
- package/dist/{index-CoVr1jIV.d.cts → index-Zu_mOJRn.d.cts} +1 -1
- package/dist/index.cjs +13297 -1361
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1118 -130
- package/dist/index.d.ts +1118 -130
- package/dist/index.js +13239 -1346
- package/dist/index.js.map +1 -1
- package/dist/models/index.d.cts +2 -2
- package/dist/models/index.d.ts +2 -2
- package/dist/mongo/index.cjs +383 -0
- package/dist/mongo/index.cjs.map +1 -0
- package/dist/mongo/index.d.cts +221 -0
- package/dist/mongo/index.d.ts +221 -0
- package/dist/mongo/index.js +351 -0
- package/dist/mongo/index.js.map +1 -0
- package/dist/{platform-auth-BwfZ0bxU.d.cts → platform-auth-AsfnIXfK.d.cts} +2 -74
- package/dist/{platform-auth-BwfZ0bxU.d.ts → platform-auth-AsfnIXfK.d.ts} +2 -74
- package/dist/schemas/index.cjs +5 -153
- package/dist/schemas/index.cjs.map +1 -1
- package/dist/schemas/index.d.cts +29 -25
- package/dist/schemas/index.d.ts +29 -25
- package/dist/schemas/index.js +5 -153
- package/dist/schemas/index.js.map +1 -1
- package/dist/services/index.cjs +0 -3
- package/dist/services/index.cjs.map +1 -1
- package/dist/services/index.js +0 -3
- package/dist/services/index.js.map +1 -1
- package/dist/types/index.d.cts +2 -2
- package/dist/types/index.d.ts +2 -2
- package/package.json +13 -1
- package/src/__sot__/README.md +56 -0
- package/src/__sot__/coreIndicators.pin.json +220 -0
- package/src/__sot__/cvcIndex.pin.json +268 -0
- package/src/__sot__/scoringEmits.pin.json +176 -0
- package/src/__tests__/__snapshots__/cvc-sot.snap +125 -37
- package/src/__tests__/cvc-136-scoring-invariant.test.ts +326 -0
- package/src/__tests__/cvc-drift-gate.test.ts +607 -0
- package/src/__tests__/cvc-sot-snapshot.test.ts +50 -8
- package/src/__tests__/cvc-structural.test.ts +43 -1
- package/src/__tests__/mongo-verifier.test.ts +502 -0
- package/src/config/index.ts +8 -2
- package/src/constants/ic.ts +213 -333
- package/src/constants/service-catalog.ts +4 -2
- package/src/cvcs/adminRoles.v1.0.0.json +153 -0
- package/src/cvcs/administeringJurisdiction.v1.0.0.json +40 -40
- package/src/cvcs/ageBinReporting.v1.0.0.json +40 -40
- package/src/cvcs/assertionDomain.v1.1.0.json +78 -105
- package/src/cvcs/assertionStatus.v1.0.0.json +80 -0
- package/src/cvcs/citizenship.v1.0.0.json +3062 -0
- package/src/cvcs/contactInfoTypes.v1.0.0.json +40 -40
- package/src/cvcs/coreDhState.v1.0.0.json +113 -0
- package/src/cvcs/coreIndicators.v1.0.0.json +2905 -0
- package/src/cvcs/createdBySystem.v1.0.0.json +89 -0
- package/src/cvcs/employmentStatus.v1.0.0.json +60 -60
- package/src/cvcs/exploitationType.v1.0.0.json +106 -0
- package/src/cvcs/facilitatorEntityType.v1.0.0.json +40 -40
- package/src/cvcs/highestEducationLevelCompleted.v1.0.0.json +50 -50
- package/src/cvcs/hmisCurrentLivingSituation.v1.0.0.json +409 -0
- package/src/cvcs/hmisSex.v1.0.0.json +89 -0
- package/src/cvcs/homelessStatus.v1.0.0.json +27 -27
- package/src/cvcs/housingSubsidyTypes.v1.0.0.json +26 -24
- package/src/cvcs/incarcerationEpisodeType.v1.0.0.json +106 -0
- package/src/cvcs/incidentInvolvementRoles.v1.0.0.json +40 -40
- package/src/cvcs/incidentParticipationRoles.v1.0.0.json +40 -40
- package/src/cvcs/index.ts +73 -2
- package/src/cvcs/juvenileJusticeEpisodeType.v1.0.0.json +106 -0
- package/src/cvcs/juvenileJusticeInvolvementStatus.v1.0.0.json +32 -32
- package/src/cvcs/militaryBranch.v1.0.0.json +20 -20
- package/src/cvcs/militaryStatus.v1.0.0.json +20 -20
- package/src/cvcs/minorAdultStatus.v1.0.0.json +80 -0
- package/src/cvcs/nameType.v1.0.0.json +40 -40
- package/src/cvcs/offenderStatus.v1.0.0.json +40 -40
- package/src/cvcs/offenderStatusFamily.v1.0.0.json +36 -36
- package/src/cvcs/poPetitionBasis.v1.0.0.json +96 -0
- package/src/cvcs/poStatus.v1.0.0.json +144 -0
- package/src/cvcs/poViolationStatus.v1.0.0.json +76 -0
- package/src/cvcs/radiusBucket.v1.0.0.json +23 -11
- package/src/cvcs/recencyBand.v1.0.0.json +126 -42
- package/src/cvcs/referralEntityCategory.v1.0.0.json +40 -40
- package/src/cvcs/riskSeverityBand.v1.0.0.json +139 -0
- package/src/cvcs/roiScope.v1.0.0.json +111 -3
- package/src/cvcs/roiStatus.v1.0.0.json +18 -10
- package/src/cvcs/romanticRelationshipChangeType.v1.0.0.json +2 -1
- package/src/cvcs/serviceCategories.v1.0.0.json +44 -44
- package/src/cvcs/serviceDeliveryChannel.v1.0.0.json +147 -0
- package/src/cvcs/serviceMechanisms.v1.0.0.json +36 -36
- package/src/cvcs/serviceStates.v1.0.0.json +40 -40
- package/src/cvcs/sessionTemplate.v1.0.0.json +261 -0
- package/src/cvcs/sexProviderSubrole.v1.0.0.json +35 -28
- package/src/cvcs/smtType.v1.0.0.json +40 -40
- package/src/cvcs/sourceCategory.v1.1.0.json +8 -1
- package/src/cvcs/sourceInstrument.v1.0.0.json +458 -0
- package/src/cvcs/sourceSystem.v1.0.0.json +203 -0
- package/src/cvcs/subjectType.v1.0.0.json +80 -0
- package/src/cvcs/traffickingRelevantRole.v1.0.0.json +104 -0
- package/src/cvcs/userRoles.v1.0.0.json +203 -0
- package/src/cvcs/victimStatusFamily.v1.0.0.json +40 -40
- package/src/cvcs/whyNots.v1.0.0.json +385 -0
- package/src/generated/cvc-enums.ts +1121 -127
- package/src/index.ts +20 -0
- package/src/mongo/catalog.ts +65 -0
- package/src/mongo/contract.ts +157 -0
- package/src/mongo/index.ts +343 -0
- package/src/mongo/similarity.ts +133 -0
- package/src/mongo/uri.ts +53 -0
- package/src/schemas/common.ts +4 -0
- package/src/services/cvcRegistryService.ts +1 -1
- package/src/cvcs/riskBand.v1.0.0.json +0 -98
- package/dist/{cvcEntry-BCj1OWqL.d.cts → cvcEntry-0BIB9sen.d.cts} +8 -8
- package/dist/{cvcEntry-BCj1OWqL.d.ts → cvcEntry-0BIB9sen.d.ts} +8 -8
package/src/index.ts
CHANGED
|
@@ -88,3 +88,23 @@ export { compileModel as compileCvcEntryModel } from "./models/cvcEntryModel.js"
|
|
|
88
88
|
// filesystem access. See `./cvcs/index.ts` for the full list and naming.
|
|
89
89
|
|
|
90
90
|
export * from "./cvcs/index.js";
|
|
91
|
+
|
|
92
|
+
// ─── SOT-first CVC flat-array aliases ───────────────────────────────────────
|
|
93
|
+
// Legacy-shaped `CVC_<N>_VALUES` arrays for CVCs that are SOT-native (no
|
|
94
|
+
// ic.ts constants). Derived from the SOT JSON envelope's `entries` filtered
|
|
95
|
+
// to `selectable: true` so the SOT JSON remains the single source of truth
|
|
96
|
+
// AND the non-selectable `missingness_root` grouping code is excluded (it
|
|
97
|
+
// would otherwise fail schema enum validation on write).
|
|
98
|
+
|
|
99
|
+
import recencyBandSot from "./cvcs/recencyBand.v1.0.0.json" with { type: "json" };
|
|
100
|
+
import juvenileJusticeEpisodeTypeSot from "./cvcs/juvenileJusticeEpisodeType.v1.0.0.json" with { type: "json" };
|
|
101
|
+
|
|
102
|
+
const selectableCodes = (envelope: {
|
|
103
|
+
entries: ReadonlyArray<{ code: string; selectable: boolean }>;
|
|
104
|
+
}): string[] =>
|
|
105
|
+
envelope.entries.filter((e) => e.selectable).map((e) => e.code);
|
|
106
|
+
|
|
107
|
+
export const CVC_137_VALUES: string[] = selectableCodes(recencyBandSot);
|
|
108
|
+
export const CVC_197_VALUES: string[] = selectableCodes(
|
|
109
|
+
juvenileJusticeEpisodeTypeSot,
|
|
110
|
+
);
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @htilabs/platform-common-models — read-only MongoDB catalogue
|
|
3
|
+
*
|
|
4
|
+
* The verifier reaches MongoDB ONLY through this interface. It exposes two
|
|
5
|
+
* read operations and nothing else: there is no method here that can create,
|
|
6
|
+
* write, or drop anything. The read-only guarantee is enforced by the type,
|
|
7
|
+
* not by convention.
|
|
8
|
+
*
|
|
9
|
+
* Injecting the catalogue also keeps the package's test suite free of a real
|
|
10
|
+
* MongoDB, matching how `runCvcBootCheck` injects `exit` and `logger`.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
export interface MongoCatalog {
|
|
14
|
+
/** Names of databases that physically exist (i.e. hold data). */
|
|
15
|
+
listDatabases(): Promise<string[]>;
|
|
16
|
+
/** Names of collections that physically exist in `database`. */
|
|
17
|
+
listCollections(database: string): Promise<string[]>;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Minimal structural view of a `mongodb` MongoClient. Declared structurally so
|
|
22
|
+
* this package takes no dependency on the `mongodb` driver — apps pass their
|
|
23
|
+
* own client, whatever major version they are on.
|
|
24
|
+
*/
|
|
25
|
+
export interface MongoClientLike {
|
|
26
|
+
db(name?: string): {
|
|
27
|
+
admin(): {
|
|
28
|
+
listDatabases(): Promise<{ databases: Array<{ name: string }> }>;
|
|
29
|
+
};
|
|
30
|
+
listCollections(
|
|
31
|
+
filter?: Record<string, unknown>,
|
|
32
|
+
options?: Record<string, unknown>,
|
|
33
|
+
): { toArray(): Promise<Array<{ name: string }>> };
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Minimal structural view of a Mongoose Connection. */
|
|
38
|
+
export interface MongooseConnectionLike {
|
|
39
|
+
getClient(): MongoClientLike;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Build a catalogue from a native `mongodb` client. */
|
|
43
|
+
export function catalogFromClient(client: MongoClientLike): MongoCatalog {
|
|
44
|
+
return {
|
|
45
|
+
async listDatabases(): Promise<string[]> {
|
|
46
|
+
const { databases } = await client.db().admin().listDatabases();
|
|
47
|
+
return databases.map((d) => d.name);
|
|
48
|
+
},
|
|
49
|
+
async listCollections(database: string): Promise<string[]> {
|
|
50
|
+
// `nameOnly` keeps the server from materializing collection options.
|
|
51
|
+
const infos = await client
|
|
52
|
+
.db(database)
|
|
53
|
+
.listCollections({}, { nameOnly: true })
|
|
54
|
+
.toArray();
|
|
55
|
+
return infos.map((c) => c.name);
|
|
56
|
+
},
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Build a catalogue from an open Mongoose connection. */
|
|
61
|
+
export function catalogFromMongoose(
|
|
62
|
+
connection: MongooseConnectionLike,
|
|
63
|
+
): MongoCatalog {
|
|
64
|
+
return catalogFromClient(connection.getClient());
|
|
65
|
+
}
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @htilabs/platform-common-models — `mongo:` contract block
|
|
3
|
+
*
|
|
4
|
+
* Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)
|
|
5
|
+
* with a declaration of the databases and collections a service expects.
|
|
6
|
+
*
|
|
7
|
+
* The declaration is deliberately data, not code: `expansion` is Python and
|
|
8
|
+
* parses the same YAML. Nothing here may depend on a TypeScript-only construct.
|
|
9
|
+
*
|
|
10
|
+
* ## Why declared rather than introspected
|
|
11
|
+
*
|
|
12
|
+
* Reading collection names off registered Mongoose models would cover only the
|
|
13
|
+
* Mongoose apps (thread, leads, pave) and would report false findings: thread
|
|
14
|
+
* registers `AgencyInfo` (collection `agencyinfos`), which exists in NO
|
|
15
|
+
* database because nothing has ever written to it. Mongo creates collections
|
|
16
|
+
* lazily. A declaration states intent; introspection only restates the code.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/** One database a service connects to, and the collections it uses. */
|
|
20
|
+
export interface MongoDbSpec {
|
|
21
|
+
/** Contract variable holding the database NAME (e.g. `THREAD_DB`). */
|
|
22
|
+
db_var: string;
|
|
23
|
+
/**
|
|
24
|
+
* Contract variable holding the connection URI or cluster prefix
|
|
25
|
+
* (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and
|
|
26
|
+
* no `db_var` applies, set `db_var` to the same variable — the name is then
|
|
27
|
+
* parsed out of the URI.
|
|
28
|
+
*/
|
|
29
|
+
uri_var: string;
|
|
30
|
+
/**
|
|
31
|
+
* Collections the service reads or writes. Declare only what the service
|
|
32
|
+
* USES — not everything present in the database. An undeclared collection
|
|
33
|
+
* present in Mongo is reported, never fatal.
|
|
34
|
+
*
|
|
35
|
+
* An EMPTY list opts out of collection checking entirely: only the database
|
|
36
|
+
* name is verified, and `listCollections` is never called. Use it when a
|
|
37
|
+
* service reaches a database whose collections it cannot practically
|
|
38
|
+
* enumerate. Declaring even one collection opts back in.
|
|
39
|
+
*/
|
|
40
|
+
collections: string[];
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Per-environment database-name affinity. When the deploy environment has an
|
|
45
|
+
* entry here, every resolved database name must end with the given suffix.
|
|
46
|
+
*
|
|
47
|
+
* This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):
|
|
48
|
+
* it is the only check that catches a test run pointed at a production
|
|
49
|
+
* database, and it needs no connection to MongoDB.
|
|
50
|
+
*/
|
|
51
|
+
export type EnvAffinity = Record<string, string>;
|
|
52
|
+
|
|
53
|
+
export interface MongoContractBlock {
|
|
54
|
+
/** e.g. `{ test: "-test", dev: "-dev" }`. Environments omitted are unconstrained. */
|
|
55
|
+
env_affinity?: EnvAffinity;
|
|
56
|
+
databases: MongoDbSpec[];
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Prefix for every diagnostic this module emits. */
|
|
60
|
+
const TAG = "[platform-common/mongo]";
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Validate and normalize the `mongo:` block of a parsed contract.
|
|
64
|
+
*
|
|
65
|
+
* Returns `null` when the contract declares no `mongo:` block — a service that
|
|
66
|
+
* does not use MongoDB is not an error.
|
|
67
|
+
*
|
|
68
|
+
* Throws on a malformed block: a contract that lies about its shape is a
|
|
69
|
+
* programming error, not a runtime finding.
|
|
70
|
+
*/
|
|
71
|
+
export function parseMongoBlock(
|
|
72
|
+
raw: unknown,
|
|
73
|
+
contractPath: string,
|
|
74
|
+
): MongoContractBlock | null {
|
|
75
|
+
if (raw === undefined || raw === null) return null;
|
|
76
|
+
|
|
77
|
+
if (typeof raw !== "object" || Array.isArray(raw)) {
|
|
78
|
+
throw new Error(`${TAG} ${contractPath}: "mongo" must be a mapping`);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
const block = raw as Partial<MongoContractBlock>;
|
|
82
|
+
|
|
83
|
+
if (!Array.isArray(block.databases) || block.databases.length === 0) {
|
|
84
|
+
throw new Error(
|
|
85
|
+
`${TAG} ${contractPath}: "mongo.databases" must be a non-empty list`,
|
|
86
|
+
);
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
block.databases.forEach((db, i) => {
|
|
90
|
+
const where = `${contractPath}: mongo.databases[${i}]`;
|
|
91
|
+
if (!db || typeof db !== "object") {
|
|
92
|
+
throw new Error(`${TAG} ${where} must be a mapping`);
|
|
93
|
+
}
|
|
94
|
+
if (typeof db.db_var !== "string" || db.db_var.length === 0) {
|
|
95
|
+
throw new Error(`${TAG} ${where}.db_var must be a non-empty string`);
|
|
96
|
+
}
|
|
97
|
+
if (typeof db.uri_var !== "string" || db.uri_var.length === 0) {
|
|
98
|
+
throw new Error(`${TAG} ${where}.uri_var must be a non-empty string`);
|
|
99
|
+
}
|
|
100
|
+
if (!Array.isArray(db.collections)) {
|
|
101
|
+
throw new Error(`${TAG} ${where}.collections must be a list`);
|
|
102
|
+
}
|
|
103
|
+
db.collections.forEach((c, j) => {
|
|
104
|
+
if (typeof c !== "string" || c.length === 0) {
|
|
105
|
+
throw new Error(
|
|
106
|
+
`${TAG} ${where}.collections[${j}] must be a non-empty string`,
|
|
107
|
+
);
|
|
108
|
+
}
|
|
109
|
+
});
|
|
110
|
+
});
|
|
111
|
+
|
|
112
|
+
if (block.env_affinity !== undefined) {
|
|
113
|
+
if (typeof block.env_affinity !== "object" || Array.isArray(block.env_affinity)) {
|
|
114
|
+
throw new Error(
|
|
115
|
+
`${TAG} ${contractPath}: "mongo.env_affinity" must be a mapping of env -> suffix`,
|
|
116
|
+
);
|
|
117
|
+
}
|
|
118
|
+
for (const [env, suffix] of Object.entries(block.env_affinity)) {
|
|
119
|
+
if (typeof suffix !== "string" || suffix.length === 0) {
|
|
120
|
+
throw new Error(
|
|
121
|
+
`${TAG} ${contractPath}: mongo.env_affinity.${env} must be a non-empty string`,
|
|
122
|
+
);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
return {
|
|
128
|
+
env_affinity: block.env_affinity,
|
|
129
|
+
databases: block.databases as MongoDbSpec[],
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Check a resolved database name against the environment's affinity suffix.
|
|
135
|
+
*
|
|
136
|
+
* Returns `null` when the name is acceptable (or the environment declares no
|
|
137
|
+
* affinity), otherwise a human-readable violation message.
|
|
138
|
+
*
|
|
139
|
+
* Requires NO MongoDB connection. This is the check that catches
|
|
140
|
+
* `NODE_ENV=test` pointed at `platform-db`.
|
|
141
|
+
*/
|
|
142
|
+
export function checkEnvAffinity(
|
|
143
|
+
dbName: string,
|
|
144
|
+
dbVar: string,
|
|
145
|
+
env: string,
|
|
146
|
+
affinity: EnvAffinity | undefined,
|
|
147
|
+
): string | null {
|
|
148
|
+
const suffix = affinity?.[env];
|
|
149
|
+
if (!suffix) return null;
|
|
150
|
+
if (dbName.endsWith(suffix)) return null;
|
|
151
|
+
|
|
152
|
+
return (
|
|
153
|
+
`${dbVar}="${dbName}" is not valid in environment "${env}": ` +
|
|
154
|
+
`database names must end with "${suffix}". ` +
|
|
155
|
+
`Refusing to run against a database outside this environment.`
|
|
156
|
+
);
|
|
157
|
+
}
|
|
@@ -0,0 +1,343 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @htilabs/platform-common-models — MongoDB connection/collection verifier
|
|
3
|
+
*
|
|
4
|
+
* Sibling to `./config`. Where `validateAgainstContract` proves the env vars
|
|
5
|
+
* are present and well-typed, `verifyMongo` proves they point somewhere real.
|
|
6
|
+
*
|
|
7
|
+
* ## What this catches
|
|
8
|
+
* - a database name that does not exist and looks like a typo of one that does
|
|
9
|
+
* - a collection name that does not exist and looks like a typo of one that does
|
|
10
|
+
* - a database name that does not belong to the current environment
|
|
11
|
+
* (env-affinity; needs no connection — generalizes thread's `assertTestDb`)
|
|
12
|
+
* - collections present in MongoDB but undeclared by the service (reported)
|
|
13
|
+
*
|
|
14
|
+
* ## What this CANNOT catch
|
|
15
|
+
* A plausible-but-wrong POPULATED database. `leads-platform-prod-test` exists
|
|
16
|
+
* and carries the same collection names as `leads-platform-test`; every
|
|
17
|
+
* name-existence check passes. Detecting that needs an identity marker
|
|
18
|
+
* written inside the database, which is outside this utility's read-only
|
|
19
|
+
* remit. Do not claim otherwise in adoption docs.
|
|
20
|
+
*
|
|
21
|
+
* ## Read-only
|
|
22
|
+
* Reaches MongoDB solely through {@link MongoCatalog}: listDatabases and
|
|
23
|
+
* listCollections. It never creates, writes, or drops anything.
|
|
24
|
+
*
|
|
25
|
+
* ## Severity
|
|
26
|
+
* MongoDB creates namespaces lazily, so ABSENCE IS AMBIGUOUS (typo vs
|
|
27
|
+
* unseeded environment). Absence alone warns; absence with a plausible
|
|
28
|
+
* near-neighbour is fatal. See `similarity.ts`.
|
|
29
|
+
*
|
|
30
|
+
* FACT (verified 2026-07-10, read-only): thread registers the Mongoose model
|
|
31
|
+
* `AgencyInfo` (collection `agencyinfos`), and that collection exists in
|
|
32
|
+
* neither `platform-test` (15 collections) nor `platform-dev` (41). A
|
|
33
|
+
* registered model with zero documents has no collection. The warn-on-absence
|
|
34
|
+
* rule exists because of this; do not "tighten" it to fatal.
|
|
35
|
+
*/
|
|
36
|
+
|
|
37
|
+
import {
|
|
38
|
+
loadContract,
|
|
39
|
+
resolveDefault,
|
|
40
|
+
type ServiceContract,
|
|
41
|
+
} from "../config/index.js";
|
|
42
|
+
import {
|
|
43
|
+
parseMongoBlock,
|
|
44
|
+
checkEnvAffinity,
|
|
45
|
+
type MongoContractBlock,
|
|
46
|
+
type MongoDbSpec,
|
|
47
|
+
} from "./contract.js";
|
|
48
|
+
import { nearestNames, formatSuggestions } from "./similarity.js";
|
|
49
|
+
import { parseDbName } from "./uri.js";
|
|
50
|
+
import type { MongoCatalog } from "./catalog.js";
|
|
51
|
+
|
|
52
|
+
export type { MongoCatalog, MongoClientLike, MongooseConnectionLike } from "./catalog.js";
|
|
53
|
+
export { catalogFromClient, catalogFromMongoose } from "./catalog.js";
|
|
54
|
+
export type { MongoContractBlock, MongoDbSpec, EnvAffinity } from "./contract.js";
|
|
55
|
+
export { parseDbName, isTestDb, TEST_DB_SUFFIX } from "./uri.js";
|
|
56
|
+
|
|
57
|
+
const TAG = "[platform-common/mongo]";
|
|
58
|
+
|
|
59
|
+
export type Severity = "fatal" | "warn";
|
|
60
|
+
|
|
61
|
+
export type FindingKind =
|
|
62
|
+
| "env_var_missing"
|
|
63
|
+
| "db_shape_violation"
|
|
64
|
+
| "db_absent_typo"
|
|
65
|
+
| "db_absent_unseeded"
|
|
66
|
+
| "collection_absent_typo"
|
|
67
|
+
| "collection_absent_unseeded"
|
|
68
|
+
| "collection_undeclared";
|
|
69
|
+
|
|
70
|
+
export interface Finding {
|
|
71
|
+
severity: Severity;
|
|
72
|
+
kind: FindingKind;
|
|
73
|
+
message: string;
|
|
74
|
+
dbVar?: string;
|
|
75
|
+
database?: string;
|
|
76
|
+
collection?: string;
|
|
77
|
+
/**
|
|
78
|
+
* Existing names this looks like a typo of. More than one means the evidence
|
|
79
|
+
* is ambiguous — the message lists them all rather than guessing.
|
|
80
|
+
*/
|
|
81
|
+
suggestions?: string[];
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export interface MongoVerifyReport {
|
|
85
|
+
/** True when no fatal finding was produced. Warnings do not clear `ok`. */
|
|
86
|
+
ok: boolean;
|
|
87
|
+
findings: Finding[];
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
export interface VerifyMongoOptions {
|
|
91
|
+
/** Read-only catalogue. Required — this package takes no driver dependency. */
|
|
92
|
+
catalog: MongoCatalog;
|
|
93
|
+
/** Environment name for affinity checks. Defaults to NODE_ENV, then "local". */
|
|
94
|
+
env?: string;
|
|
95
|
+
/** Env source. Defaults to `process.env`. */
|
|
96
|
+
processEnv?: NodeJS.ProcessEnv;
|
|
97
|
+
/** If true, throw instead of `exit(1)`. Defaults to false (production exits). */
|
|
98
|
+
throwOnFailure?: boolean;
|
|
99
|
+
/** Injected for tests. Defaults to `process.exit`. */
|
|
100
|
+
exit?: (code: number) => never;
|
|
101
|
+
/** Injected for tests. Defaults to `console`. */
|
|
102
|
+
logger?: Pick<Console, "error" | "warn">;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Resolve the database name for a spec, applying the same per-environment
|
|
107
|
+
* defaults that `validateAgainstContract` applies. Reading `process.env` alone
|
|
108
|
+
* would miss a value the contract supplies as a default (thread declares
|
|
109
|
+
* `PLATFORM_DB.default.prod: platform-prod`) and report a false fatal.
|
|
110
|
+
*
|
|
111
|
+
* When `db_var` and `uri_var` name the same variable, the database is embedded
|
|
112
|
+
* in the connection string (auth does this for `LEADS_MONGODB_URI` and
|
|
113
|
+
* friends) and must be parsed out of it.
|
|
114
|
+
*
|
|
115
|
+
* A variable the contract marks `required: false` and that carries no value is
|
|
116
|
+
* SKIPPED, not failed: thread's `PAVE_DB` is optional and its absence simply
|
|
117
|
+
* means the read-only pave connection is not configured. Required-ness comes
|
|
118
|
+
* from the contract so there is no second place to declare it.
|
|
119
|
+
*/
|
|
120
|
+
function resolveDbName(
|
|
121
|
+
spec: MongoDbSpec,
|
|
122
|
+
contract: ServiceContract,
|
|
123
|
+
env: string,
|
|
124
|
+
processEnv: NodeJS.ProcessEnv,
|
|
125
|
+
): { name?: string; error?: string; skip?: boolean } {
|
|
126
|
+
const varSpec = contract.variables[spec.db_var];
|
|
127
|
+
const raw =
|
|
128
|
+
processEnv[spec.db_var] ??
|
|
129
|
+
(varSpec ? resolveDefault(varSpec, env) : undefined);
|
|
130
|
+
|
|
131
|
+
if (raw === undefined || raw === "") {
|
|
132
|
+
// A variable absent from `variables` is treated as required: the mongo
|
|
133
|
+
// block references something the contract never declared.
|
|
134
|
+
if (varSpec && varSpec.required === false) return { skip: true };
|
|
135
|
+
return { error: `${spec.db_var}: required by mongo contract but not set` };
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
if (spec.db_var !== spec.uri_var) return { name: raw };
|
|
139
|
+
|
|
140
|
+
const parsed = parseDbName(raw);
|
|
141
|
+
if (parsed === null) {
|
|
142
|
+
return {
|
|
143
|
+
error:
|
|
144
|
+
`${spec.db_var}: connection string carries no database name. ` +
|
|
145
|
+
`Either embed one (mongodb://host/<db>) or declare a separate db_var.`,
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
return { name: parsed };
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
async function verifyDatabase(
|
|
152
|
+
spec: MongoDbSpec,
|
|
153
|
+
dbName: string,
|
|
154
|
+
block: MongoContractBlock,
|
|
155
|
+
env: string,
|
|
156
|
+
catalog: MongoCatalog,
|
|
157
|
+
existingDatabases: readonly string[],
|
|
158
|
+
): Promise<Finding[]> {
|
|
159
|
+
const findings: Finding[] = [];
|
|
160
|
+
|
|
161
|
+
// 1. Env affinity — no connection required, and the only check that catches
|
|
162
|
+
// a test run pointed at production.
|
|
163
|
+
const violation = checkEnvAffinity(dbName, spec.db_var, env, block.env_affinity);
|
|
164
|
+
if (violation) {
|
|
165
|
+
findings.push({
|
|
166
|
+
severity: "fatal",
|
|
167
|
+
kind: "db_shape_violation",
|
|
168
|
+
message: violation,
|
|
169
|
+
dbVar: spec.db_var,
|
|
170
|
+
database: dbName,
|
|
171
|
+
});
|
|
172
|
+
// A database in the wrong environment must not be probed further.
|
|
173
|
+
return findings;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
// 2. Existence.
|
|
177
|
+
if (!existingDatabases.includes(dbName)) {
|
|
178
|
+
const suggestions = nearestNames(dbName, existingDatabases);
|
|
179
|
+
if (suggestions.length > 0) {
|
|
180
|
+
findings.push({
|
|
181
|
+
severity: "fatal",
|
|
182
|
+
kind: "db_absent_typo",
|
|
183
|
+
message:
|
|
184
|
+
`${spec.db_var}="${dbName}" does not exist. ` +
|
|
185
|
+
`Did you mean ${formatSuggestions(suggestions)}?`,
|
|
186
|
+
dbVar: spec.db_var,
|
|
187
|
+
database: dbName,
|
|
188
|
+
suggestions,
|
|
189
|
+
});
|
|
190
|
+
} else {
|
|
191
|
+
findings.push({
|
|
192
|
+
severity: "warn",
|
|
193
|
+
kind: "db_absent_unseeded",
|
|
194
|
+
message:
|
|
195
|
+
`${spec.db_var}="${dbName}" does not exist yet. Treating as an ` +
|
|
196
|
+
`unseeded environment; MongoDB will create it on first write.`,
|
|
197
|
+
dbVar: spec.db_var,
|
|
198
|
+
database: dbName,
|
|
199
|
+
});
|
|
200
|
+
}
|
|
201
|
+
// Nothing to compare collections against.
|
|
202
|
+
return findings;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
// 3. An empty `collections` list opts out of collection checking: verify the
|
|
206
|
+
// database NAME only. This lets a service adopt incrementally — expansion
|
|
207
|
+
// reaches the leads databases but enumerating their collections is not
|
|
208
|
+
// tractable, and sweeping a 467MB database would emit a warning per
|
|
209
|
+
// collection. Declaring even one collection opts back in.
|
|
210
|
+
if (spec.collections.length === 0) return findings;
|
|
211
|
+
|
|
212
|
+
// 4. Collections, both directions.
|
|
213
|
+
const actual = await catalog.listCollections(dbName);
|
|
214
|
+
|
|
215
|
+
for (const declared of spec.collections) {
|
|
216
|
+
if (actual.includes(declared)) continue;
|
|
217
|
+
|
|
218
|
+
const suggestions = nearestNames(declared, actual);
|
|
219
|
+
if (suggestions.length > 0) {
|
|
220
|
+
findings.push({
|
|
221
|
+
severity: "fatal",
|
|
222
|
+
kind: "collection_absent_typo",
|
|
223
|
+
message:
|
|
224
|
+
`${dbName}: declared collection "${declared}" does not exist. ` +
|
|
225
|
+
`Did you mean ${formatSuggestions(suggestions)}?`,
|
|
226
|
+
dbVar: spec.db_var,
|
|
227
|
+
database: dbName,
|
|
228
|
+
collection: declared,
|
|
229
|
+
suggestions,
|
|
230
|
+
});
|
|
231
|
+
} else {
|
|
232
|
+
findings.push({
|
|
233
|
+
severity: "warn",
|
|
234
|
+
kind: "collection_absent_unseeded",
|
|
235
|
+
message:
|
|
236
|
+
`${dbName}: declared collection "${declared}" does not exist yet ` +
|
|
237
|
+
`(no documents written). MongoDB creates collections lazily.`,
|
|
238
|
+
dbVar: spec.db_var,
|
|
239
|
+
database: dbName,
|
|
240
|
+
collection: declared,
|
|
241
|
+
});
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
const declaredSet = new Set(spec.collections);
|
|
246
|
+
for (const present of actual) {
|
|
247
|
+
if (declaredSet.has(present)) continue;
|
|
248
|
+
findings.push({
|
|
249
|
+
severity: "warn",
|
|
250
|
+
kind: "collection_undeclared",
|
|
251
|
+
message:
|
|
252
|
+
`${dbName}: collection "${present}" exists but is not declared in the ` +
|
|
253
|
+
`mongo contract.`,
|
|
254
|
+
dbVar: spec.db_var,
|
|
255
|
+
database: dbName,
|
|
256
|
+
collection: present,
|
|
257
|
+
});
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
return findings;
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/**
|
|
264
|
+
* Verify every database and collection declared in `runtimeYamlPath` against a
|
|
265
|
+
* live MongoDB catalogue.
|
|
266
|
+
*
|
|
267
|
+
* Collects ALL findings before deciding, exactly as `validateAgainstContract`
|
|
268
|
+
* does — an operator fixing a misconfiguration should see every problem at
|
|
269
|
+
* once, not one per restart.
|
|
270
|
+
*
|
|
271
|
+
* Resolves to the report when no fatal finding is produced. On a fatal finding
|
|
272
|
+
* it prints every finding and calls `exit(1)`, or throws when
|
|
273
|
+
* `throwOnFailure` is set.
|
|
274
|
+
*
|
|
275
|
+
* A contract with no `mongo:` block is a no-op success.
|
|
276
|
+
*/
|
|
277
|
+
export async function verifyMongo(
|
|
278
|
+
runtimeYamlPath: string,
|
|
279
|
+
opts: VerifyMongoOptions,
|
|
280
|
+
): Promise<MongoVerifyReport> {
|
|
281
|
+
const processEnv = opts.processEnv ?? process.env;
|
|
282
|
+
const logger = opts.logger ?? console;
|
|
283
|
+
const exit = opts.exit ?? ((code: number) => process.exit(code));
|
|
284
|
+
const env = opts.env ?? processEnv.NODE_ENV ?? "local";
|
|
285
|
+
|
|
286
|
+
const contract = loadContract(runtimeYamlPath);
|
|
287
|
+
const block = parseMongoBlock(contract.mongo, runtimeYamlPath);
|
|
288
|
+
if (block === null) return { ok: true, findings: [] };
|
|
289
|
+
|
|
290
|
+
const findings: Finding[] = [];
|
|
291
|
+
const resolved: Array<{ spec: MongoDbSpec; name: string }> = [];
|
|
292
|
+
|
|
293
|
+
for (const spec of block.databases) {
|
|
294
|
+
const { name, error, skip } = resolveDbName(spec, contract, env, processEnv);
|
|
295
|
+
if (skip) continue; // optional database, not configured in this environment
|
|
296
|
+
if (error !== undefined || name === undefined) {
|
|
297
|
+
findings.push({
|
|
298
|
+
severity: "fatal",
|
|
299
|
+
kind: "env_var_missing",
|
|
300
|
+
message: error ?? `${spec.db_var}: unresolved`,
|
|
301
|
+
dbVar: spec.db_var,
|
|
302
|
+
});
|
|
303
|
+
continue;
|
|
304
|
+
}
|
|
305
|
+
resolved.push({ spec, name });
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
// One catalogue read shared across every database in the contract.
|
|
309
|
+
const existingDatabases =
|
|
310
|
+
resolved.length > 0 ? await opts.catalog.listDatabases() : [];
|
|
311
|
+
|
|
312
|
+
for (const { spec, name } of resolved) {
|
|
313
|
+
findings.push(
|
|
314
|
+
...(await verifyDatabase(
|
|
315
|
+
spec,
|
|
316
|
+
name,
|
|
317
|
+
block,
|
|
318
|
+
env,
|
|
319
|
+
opts.catalog,
|
|
320
|
+
existingDatabases,
|
|
321
|
+
)),
|
|
322
|
+
);
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
const fatals = findings.filter((f) => f.severity === "fatal");
|
|
326
|
+
const warns = findings.filter((f) => f.severity === "warn");
|
|
327
|
+
|
|
328
|
+
for (const w of warns) logger.warn(`${TAG} ${w.message}`);
|
|
329
|
+
|
|
330
|
+
if (fatals.length > 0) {
|
|
331
|
+
const message = [
|
|
332
|
+
`${TAG} verifyMongo failed for ${runtimeYamlPath} (env "${env}")`,
|
|
333
|
+
`${fatals.length} fatal finding(s):`,
|
|
334
|
+
...fatals.map((f) => ` - ${f.message}`),
|
|
335
|
+
].join("\n");
|
|
336
|
+
|
|
337
|
+
if (opts.throwOnFailure) throw new Error(message);
|
|
338
|
+
logger.error(message);
|
|
339
|
+
exit(1);
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
return { ok: fatals.length === 0, findings };
|
|
343
|
+
}
|