@htilabs/platform-common-models 0.9.0 → 0.12.0
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/dist/config/index.cjs +85 -0
- package/dist/config/index.cjs.map +1 -1
- package/dist/config/index.d.cts +94 -4
- package/dist/config/index.d.ts +94 -4
- package/dist/config/index.js +81 -1
- package/dist/config/index.js.map +1 -1
- package/dist/constants/index.cjs +456 -181
- 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 +453 -169
- package/dist/constants/index.js.map +1 -1
- package/dist/cvcs/index.cjs +15331 -801
- package/dist/cvcs/index.cjs.map +1 -1
- package/dist/cvcs/index.d.cts +18167 -2208
- package/dist/cvcs/index.d.ts +18167 -2208
- package/dist/cvcs/index.js +15282 -801
- package/dist/cvcs/index.js.map +1 -1
- package/dist/{index-Zu_mOJRn.d.cts → index-CoVr1jIV.d.cts} +1 -1
- package/dist/{index-CDoqrfc1.d.ts → index-I-DiX9eQ.d.ts} +1 -1
- package/dist/index.cjs +17070 -1056
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1638 -12
- package/dist/index.d.ts +1638 -12
- package/dist/index.js +16969 -1043
- 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 +384 -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 +352 -0
- package/dist/mongo/index.js.map +1 -0
- package/dist/{platform-auth-XVB9aHqR.d.cts → platform-auth-v53r3BhN.d.cts} +19 -75
- package/dist/{platform-auth-XVB9aHqR.d.ts → platform-auth-v53r3BhN.d.ts} +19 -75
- package/dist/schemas/index.cjs +25 -156
- package/dist/schemas/index.cjs.map +1 -1
- package/dist/schemas/index.d.cts +25 -25
- package/dist/schemas/index.d.ts +25 -25
- package/dist/schemas/index.js +25 -156
- 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 +9 -1
- package/src/__sot__/README.md +56 -0
- package/src/__sot__/coreIndicators.pin.json +215 -0
- package/src/__sot__/cvcIndex.pin.json +268 -0
- package/src/__sot__/scoringEmits.pin.json +176 -0
- package/src/__tests__/__snapshots__/cvc-sot.snap +227 -35
- package/src/__tests__/cvc-136-scoring-invariant.test.ts +323 -0
- package/src/__tests__/cvc-drift-gate.test.ts +603 -0
- package/src/__tests__/cvc-sot-snapshot.test.ts +122 -11
- package/src/__tests__/cvc-structural.test.ts +56 -1
- package/src/__tests__/mongo-verifier.test.ts +502 -0
- package/src/__tests__/runtime-contract-validator.test.ts +325 -1
- package/src/config/index.ts +197 -6
- package/src/constants/ic.ts +512 -206
- package/src/constants/service-catalog.ts +4 -2
- package/src/cvcs/activityType.v1.0.0.json +143 -0
- 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 +629 -0
- package/src/cvcs/{checkInPhase.v1.0.0.json → checkInPhase.v1.1.0.json} +20 -2
- package/src/cvcs/childChangeType.v1.0.0.json +152 -0
- package/src/cvcs/citizenship.v1.0.0.json +3062 -0
- package/src/cvcs/contactInfoTypes.v1.0.0.json +40 -40
- package/src/cvcs/contactLinkType.v1.0.0.json +89 -0
- package/src/cvcs/coreDhState.v1.0.0.json +113 -0
- package/src/cvcs/coreFunctions.v1.0.0.json +746 -0
- package/src/cvcs/coreIndicators.v1.0.0.json +2840 -0
- package/src/cvcs/coreReferralOutcome.v1.0.0.json +71 -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 +55 -46
- package/src/cvcs/hivStatus.v1.0.0.json +71 -0
- package/src/cvcs/hmisCurrentLivingSituation.v1.0.0.json +409 -0
- package/src/cvcs/hmisRelationshipToHoh.v1.0.0.json +104 -0
- package/src/cvcs/homelessStatus.v1.0.0.json +27 -27
- package/src/cvcs/housingSubsidyTypes.v1.0.0.json +161 -0
- package/src/cvcs/htType.v1.0.0.json +87 -0
- package/src/cvcs/identificationStatus.v1.0.0.json +18 -0
- package/src/cvcs/immigrationLegalStatusChangeType.v1.0.0.json +143 -0
- 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/incomeBenefitsSources.v1.0.0.json +31 -2
- package/src/cvcs/index.ts +106 -1
- package/src/cvcs/juvenileJusticeEpisodeType.v1.0.0.json +28 -18
- package/src/cvcs/juvenileJusticeInvolvementStatus.v1.0.0.json +32 -32
- package/src/cvcs/livingSituation.v1.0.0.json +213 -0
- package/src/cvcs/mentalHealthStatus.v1.0.0.json +71 -0
- package/src/cvcs/militaryBranch.v1.0.0.json +20 -20
- package/src/cvcs/militaryStatus.v1.0.0.json +20 -20
- package/src/cvcs/nameType.v1.0.0.json +40 -40
- package/src/cvcs/needsAssessmentChangeType.v1.0.0.json +134 -0
- 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/programEnrollmentChangeType.v1.0.0.json +134 -0
- package/src/cvcs/provenanceSourceId.v1.0.0.json +134 -0
- package/src/cvcs/radiusBucket.v1.0.0.json +110 -0
- package/src/cvcs/recencyBand.v1.0.0.json +104 -39
- package/src/cvcs/referralEntityCategory.v1.0.0.json +40 -40
- package/src/cvcs/relationshipConcern.v1.0.0.json +114 -0
- package/src/cvcs/riskCategory.v1.0.0.json +134 -0
- package/src/cvcs/riskSeverityBand.v1.0.0.json +139 -0
- package/src/cvcs/roiMethod.v1.0.0.json +107 -0
- package/src/cvcs/roiScope.v1.0.0.json +296 -0
- package/src/cvcs/roiStatus.v1.0.0.json +106 -0
- package/src/cvcs/romanticRelationshipChangeType.v1.0.0.json +162 -0
- package/src/cvcs/serviceAudience.v1.0.0.json +96 -0
- 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 +55 -33
- package/src/cvcs/sessionNoteVisibility.v1.0.0.json +80 -0
- 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/sourceSubtype.v1.1.0.json +36 -0
- package/src/cvcs/sourceSystem.v1.0.0.json +203 -0
- package/src/cvcs/specialNeedsDisabilities.v1.0.0.json +143 -0
- package/src/cvcs/suggestionSource.v1.0.0.json +71 -0
- package/src/cvcs/traffickingRelevantRole.v1.0.0.json +104 -0
- package/src/cvcs/userRoles.v1.0.0.json +203 -0
- package/src/cvcs/verificationMethod.v1.0.0.json +18 -0
- package/src/cvcs/victimAbuseTypes.v1.0.0.json +276 -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 +1729 -7
- 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/services/cvcRegistryService.ts +1 -1
- package/dist/{cvcEntry-0BIB9sen.d.cts → cvcEntry-BCj1OWqL.d.cts} +8 -8
- package/dist/{cvcEntry-0BIB9sen.d.ts → cvcEntry-BCj1OWqL.d.ts} +8 -8
|
@@ -0,0 +1,221 @@
|
|
|
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
|
+
interface MongoCatalog {
|
|
13
|
+
/** Names of databases that physically exist (i.e. hold data). */
|
|
14
|
+
listDatabases(): Promise<string[]>;
|
|
15
|
+
/** Names of collections that physically exist in `database`. */
|
|
16
|
+
listCollections(database: string): Promise<string[]>;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Minimal structural view of a `mongodb` MongoClient. Declared structurally so
|
|
20
|
+
* this package takes no dependency on the `mongodb` driver — apps pass their
|
|
21
|
+
* own client, whatever major version they are on.
|
|
22
|
+
*/
|
|
23
|
+
interface MongoClientLike {
|
|
24
|
+
db(name?: string): {
|
|
25
|
+
admin(): {
|
|
26
|
+
listDatabases(): Promise<{
|
|
27
|
+
databases: Array<{
|
|
28
|
+
name: string;
|
|
29
|
+
}>;
|
|
30
|
+
}>;
|
|
31
|
+
};
|
|
32
|
+
listCollections(filter?: Record<string, unknown>, options?: Record<string, unknown>): {
|
|
33
|
+
toArray(): Promise<Array<{
|
|
34
|
+
name: string;
|
|
35
|
+
}>>;
|
|
36
|
+
};
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
/** Minimal structural view of a Mongoose Connection. */
|
|
40
|
+
interface MongooseConnectionLike {
|
|
41
|
+
getClient(): MongoClientLike;
|
|
42
|
+
}
|
|
43
|
+
/** Build a catalogue from a native `mongodb` client. */
|
|
44
|
+
declare function catalogFromClient(client: MongoClientLike): MongoCatalog;
|
|
45
|
+
/** Build a catalogue from an open Mongoose connection. */
|
|
46
|
+
declare function catalogFromMongoose(connection: MongooseConnectionLike): MongoCatalog;
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* @htilabs/platform-common-models — `mongo:` contract block
|
|
50
|
+
*
|
|
51
|
+
* Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)
|
|
52
|
+
* with a declaration of the databases and collections a service expects.
|
|
53
|
+
*
|
|
54
|
+
* The declaration is deliberately data, not code: `expansion` is Python and
|
|
55
|
+
* parses the same YAML. Nothing here may depend on a TypeScript-only construct.
|
|
56
|
+
*
|
|
57
|
+
* ## Why declared rather than introspected
|
|
58
|
+
*
|
|
59
|
+
* Reading collection names off registered Mongoose models would cover only the
|
|
60
|
+
* Mongoose apps (thread, leads, pave) and would report false findings: thread
|
|
61
|
+
* registers `AgencyInfo` (collection `agencyinfos`), which exists in NO
|
|
62
|
+
* database because nothing has ever written to it. Mongo creates collections
|
|
63
|
+
* lazily. A declaration states intent; introspection only restates the code.
|
|
64
|
+
*/
|
|
65
|
+
/** One database a service connects to, and the collections it uses. */
|
|
66
|
+
interface MongoDbSpec {
|
|
67
|
+
/** Contract variable holding the database NAME (e.g. `THREAD_DB`). */
|
|
68
|
+
db_var: string;
|
|
69
|
+
/**
|
|
70
|
+
* Contract variable holding the connection URI or cluster prefix
|
|
71
|
+
* (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and
|
|
72
|
+
* no `db_var` applies, set `db_var` to the same variable — the name is then
|
|
73
|
+
* parsed out of the URI.
|
|
74
|
+
*/
|
|
75
|
+
uri_var: string;
|
|
76
|
+
/**
|
|
77
|
+
* Collections the service reads or writes. Declare only what the service
|
|
78
|
+
* USES — not everything present in the database. An undeclared collection
|
|
79
|
+
* present in Mongo is reported, never fatal.
|
|
80
|
+
*
|
|
81
|
+
* An EMPTY list opts out of collection checking entirely: only the database
|
|
82
|
+
* name is verified, and `listCollections` is never called. Use it when a
|
|
83
|
+
* service reaches a database whose collections it cannot practically
|
|
84
|
+
* enumerate. Declaring even one collection opts back in.
|
|
85
|
+
*/
|
|
86
|
+
collections: string[];
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Per-environment database-name affinity. When the deploy environment has an
|
|
90
|
+
* entry here, every resolved database name must end with the given suffix.
|
|
91
|
+
*
|
|
92
|
+
* This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):
|
|
93
|
+
* it is the only check that catches a test run pointed at a production
|
|
94
|
+
* database, and it needs no connection to MongoDB.
|
|
95
|
+
*/
|
|
96
|
+
type EnvAffinity = Record<string, string>;
|
|
97
|
+
interface MongoContractBlock {
|
|
98
|
+
/** e.g. `{ test: "-test", dev: "-dev" }`. Environments omitted are unconstrained. */
|
|
99
|
+
env_affinity?: EnvAffinity;
|
|
100
|
+
databases: MongoDbSpec[];
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* @htilabs/platform-common-models — MongoDB URI parsing
|
|
105
|
+
*
|
|
106
|
+
* Home of the connection-string parsing shared by the seed guard
|
|
107
|
+
* (`scripts/lib/confirmTargetDb.ts`) and the runtime verifier
|
|
108
|
+
* (`src/mongo/index.ts`). It lives in `src/` so both can import one
|
|
109
|
+
* implementation; `scripts/` cannot be imported from `src/` at build time.
|
|
110
|
+
*/
|
|
111
|
+
/** Suffix that marks a database as a non-production scratch/test database. */
|
|
112
|
+
declare const TEST_DB_SUFFIX = "-test";
|
|
113
|
+
/**
|
|
114
|
+
* Parse the target database name out of a MongoDB connection URI.
|
|
115
|
+
*
|
|
116
|
+
* The database name is the path segment after the host(s), before any query
|
|
117
|
+
* string (`?...`). Handles both `mongodb://` and `mongodb+srv://` URIs and any
|
|
118
|
+
* userinfo / multi-host / option components. Returns `null` when the URI
|
|
119
|
+
* carries no database name (e.g. `mongodb://localhost:27017` or a trailing
|
|
120
|
+
* slash with nothing after it) — callers must treat a `null` name as
|
|
121
|
+
* prod-shaped and never silently default to a production database.
|
|
122
|
+
*
|
|
123
|
+
* Implemented as manual string parsing rather than `new URL()` because Node's
|
|
124
|
+
* URL parser rejects multi-host `mongodb+srv` authorities and mishandles the
|
|
125
|
+
* comma-separated seed-list form that real connection strings use.
|
|
126
|
+
*/
|
|
127
|
+
declare function parseDbName(uri: string): string | null;
|
|
128
|
+
/**
|
|
129
|
+
* Classify a database name. A name is a "test" database (no confirmation
|
|
130
|
+
* required) only when it is non-null and ends in {@link TEST_DB_SUFFIX}.
|
|
131
|
+
* Everything else — including a `null` name — is prod-shaped.
|
|
132
|
+
*/
|
|
133
|
+
declare function isTestDb(dbName: string | null): boolean;
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* @htilabs/platform-common-models — MongoDB connection/collection verifier
|
|
137
|
+
*
|
|
138
|
+
* Sibling to `./config`. Where `validateAgainstContract` proves the env vars
|
|
139
|
+
* are present and well-typed, `verifyMongo` proves they point somewhere real.
|
|
140
|
+
*
|
|
141
|
+
* ## What this catches
|
|
142
|
+
* - a database name that does not exist and looks like a typo of one that does
|
|
143
|
+
* - a collection name that does not exist and looks like a typo of one that does
|
|
144
|
+
* - a database name that does not belong to the current environment
|
|
145
|
+
* (env-affinity; needs no connection — generalizes thread's `assertTestDb`)
|
|
146
|
+
* - collections present in MongoDB but undeclared by the service (reported)
|
|
147
|
+
*
|
|
148
|
+
* ## What this CANNOT catch
|
|
149
|
+
* A plausible-but-wrong POPULATED database. `leads-platform-prod-test` exists
|
|
150
|
+
* and carries the same collection names as `leads-platform-test`; every
|
|
151
|
+
* name-existence check passes. Detecting that needs an identity marker
|
|
152
|
+
* written inside the database, which is outside this utility's read-only
|
|
153
|
+
* remit. Do not claim otherwise in adoption docs.
|
|
154
|
+
*
|
|
155
|
+
* ## Read-only
|
|
156
|
+
* Reaches MongoDB solely through {@link MongoCatalog}: listDatabases and
|
|
157
|
+
* listCollections. It never creates, writes, or drops anything.
|
|
158
|
+
*
|
|
159
|
+
* ## Severity
|
|
160
|
+
* MongoDB creates namespaces lazily, so ABSENCE IS AMBIGUOUS (typo vs
|
|
161
|
+
* unseeded environment). Absence alone warns; absence with a plausible
|
|
162
|
+
* near-neighbour is fatal. See `similarity.ts`.
|
|
163
|
+
*
|
|
164
|
+
* FACT (verified 2026-07-10, read-only): thread registers the Mongoose model
|
|
165
|
+
* `AgencyInfo` (collection `agencyinfos`), and that collection exists in
|
|
166
|
+
* neither `platform-test` (15 collections) nor `platform-dev` (41). A
|
|
167
|
+
* registered model with zero documents has no collection. The warn-on-absence
|
|
168
|
+
* rule exists because of this; do not "tighten" it to fatal.
|
|
169
|
+
*/
|
|
170
|
+
|
|
171
|
+
type Severity = "fatal" | "warn";
|
|
172
|
+
type FindingKind = "env_var_missing" | "db_shape_violation" | "db_absent_typo" | "db_absent_unseeded" | "collection_absent_typo" | "collection_absent_unseeded" | "collection_undeclared";
|
|
173
|
+
interface Finding {
|
|
174
|
+
severity: Severity;
|
|
175
|
+
kind: FindingKind;
|
|
176
|
+
message: string;
|
|
177
|
+
dbVar?: string;
|
|
178
|
+
database?: string;
|
|
179
|
+
collection?: string;
|
|
180
|
+
/**
|
|
181
|
+
* Existing names this looks like a typo of. More than one means the evidence
|
|
182
|
+
* is ambiguous — the message lists them all rather than guessing.
|
|
183
|
+
*/
|
|
184
|
+
suggestions?: string[];
|
|
185
|
+
}
|
|
186
|
+
interface MongoVerifyReport {
|
|
187
|
+
/** True when no fatal finding was produced. Warnings do not clear `ok`. */
|
|
188
|
+
ok: boolean;
|
|
189
|
+
findings: Finding[];
|
|
190
|
+
}
|
|
191
|
+
interface VerifyMongoOptions {
|
|
192
|
+
/** Read-only catalogue. Required — this package takes no driver dependency. */
|
|
193
|
+
catalog: MongoCatalog;
|
|
194
|
+
/** Environment name for affinity checks. Defaults to NODE_ENV, then "local". */
|
|
195
|
+
env?: string;
|
|
196
|
+
/** Env source. Defaults to `process.env`. */
|
|
197
|
+
processEnv?: NodeJS.ProcessEnv;
|
|
198
|
+
/** If true, throw instead of `exit(1)`. Defaults to false (production exits). */
|
|
199
|
+
throwOnFailure?: boolean;
|
|
200
|
+
/** Injected for tests. Defaults to `process.exit`. */
|
|
201
|
+
exit?: (code: number) => never;
|
|
202
|
+
/** Injected for tests. Defaults to `console`. */
|
|
203
|
+
logger?: Pick<Console, "error" | "warn">;
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* Verify every database and collection declared in `runtimeYamlPath` against a
|
|
207
|
+
* live MongoDB catalogue.
|
|
208
|
+
*
|
|
209
|
+
* Collects ALL findings before deciding, exactly as `validateAgainstContract`
|
|
210
|
+
* does — an operator fixing a misconfiguration should see every problem at
|
|
211
|
+
* once, not one per restart.
|
|
212
|
+
*
|
|
213
|
+
* Resolves to the report when no fatal finding is produced. On a fatal finding
|
|
214
|
+
* it prints every finding and calls `exit(1)`, or throws when
|
|
215
|
+
* `throwOnFailure` is set.
|
|
216
|
+
*
|
|
217
|
+
* A contract with no `mongo:` block is a no-op success.
|
|
218
|
+
*/
|
|
219
|
+
declare function verifyMongo(runtimeYamlPath: string, opts: VerifyMongoOptions): Promise<MongoVerifyReport>;
|
|
220
|
+
|
|
221
|
+
export { type EnvAffinity, type Finding, type FindingKind, type MongoCatalog, type MongoClientLike, type MongoContractBlock, type MongoDbSpec, type MongoVerifyReport, type MongooseConnectionLike, type Severity, TEST_DB_SUFFIX, type VerifyMongoOptions, catalogFromClient, catalogFromMongoose, isTestDb, parseDbName, verifyMongo };
|
|
@@ -0,0 +1,221 @@
|
|
|
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
|
+
interface MongoCatalog {
|
|
13
|
+
/** Names of databases that physically exist (i.e. hold data). */
|
|
14
|
+
listDatabases(): Promise<string[]>;
|
|
15
|
+
/** Names of collections that physically exist in `database`. */
|
|
16
|
+
listCollections(database: string): Promise<string[]>;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Minimal structural view of a `mongodb` MongoClient. Declared structurally so
|
|
20
|
+
* this package takes no dependency on the `mongodb` driver — apps pass their
|
|
21
|
+
* own client, whatever major version they are on.
|
|
22
|
+
*/
|
|
23
|
+
interface MongoClientLike {
|
|
24
|
+
db(name?: string): {
|
|
25
|
+
admin(): {
|
|
26
|
+
listDatabases(): Promise<{
|
|
27
|
+
databases: Array<{
|
|
28
|
+
name: string;
|
|
29
|
+
}>;
|
|
30
|
+
}>;
|
|
31
|
+
};
|
|
32
|
+
listCollections(filter?: Record<string, unknown>, options?: Record<string, unknown>): {
|
|
33
|
+
toArray(): Promise<Array<{
|
|
34
|
+
name: string;
|
|
35
|
+
}>>;
|
|
36
|
+
};
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
/** Minimal structural view of a Mongoose Connection. */
|
|
40
|
+
interface MongooseConnectionLike {
|
|
41
|
+
getClient(): MongoClientLike;
|
|
42
|
+
}
|
|
43
|
+
/** Build a catalogue from a native `mongodb` client. */
|
|
44
|
+
declare function catalogFromClient(client: MongoClientLike): MongoCatalog;
|
|
45
|
+
/** Build a catalogue from an open Mongoose connection. */
|
|
46
|
+
declare function catalogFromMongoose(connection: MongooseConnectionLike): MongoCatalog;
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* @htilabs/platform-common-models — `mongo:` contract block
|
|
50
|
+
*
|
|
51
|
+
* Extends the HTI Runtime Config Contract (`config/runtime/<service>.yaml`)
|
|
52
|
+
* with a declaration of the databases and collections a service expects.
|
|
53
|
+
*
|
|
54
|
+
* The declaration is deliberately data, not code: `expansion` is Python and
|
|
55
|
+
* parses the same YAML. Nothing here may depend on a TypeScript-only construct.
|
|
56
|
+
*
|
|
57
|
+
* ## Why declared rather than introspected
|
|
58
|
+
*
|
|
59
|
+
* Reading collection names off registered Mongoose models would cover only the
|
|
60
|
+
* Mongoose apps (thread, leads, pave) and would report false findings: thread
|
|
61
|
+
* registers `AgencyInfo` (collection `agencyinfos`), which exists in NO
|
|
62
|
+
* database because nothing has ever written to it. Mongo creates collections
|
|
63
|
+
* lazily. A declaration states intent; introspection only restates the code.
|
|
64
|
+
*/
|
|
65
|
+
/** One database a service connects to, and the collections it uses. */
|
|
66
|
+
interface MongoDbSpec {
|
|
67
|
+
/** Contract variable holding the database NAME (e.g. `THREAD_DB`). */
|
|
68
|
+
db_var: string;
|
|
69
|
+
/**
|
|
70
|
+
* Contract variable holding the connection URI or cluster prefix
|
|
71
|
+
* (e.g. `MONGODB_CLUSTER`). When the URI already embeds a database name and
|
|
72
|
+
* no `db_var` applies, set `db_var` to the same variable — the name is then
|
|
73
|
+
* parsed out of the URI.
|
|
74
|
+
*/
|
|
75
|
+
uri_var: string;
|
|
76
|
+
/**
|
|
77
|
+
* Collections the service reads or writes. Declare only what the service
|
|
78
|
+
* USES — not everything present in the database. An undeclared collection
|
|
79
|
+
* present in Mongo is reported, never fatal.
|
|
80
|
+
*
|
|
81
|
+
* An EMPTY list opts out of collection checking entirely: only the database
|
|
82
|
+
* name is verified, and `listCollections` is never called. Use it when a
|
|
83
|
+
* service reaches a database whose collections it cannot practically
|
|
84
|
+
* enumerate. Declaring even one collection opts back in.
|
|
85
|
+
*/
|
|
86
|
+
collections: string[];
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Per-environment database-name affinity. When the deploy environment has an
|
|
90
|
+
* entry here, every resolved database name must end with the given suffix.
|
|
91
|
+
*
|
|
92
|
+
* This generalizes thread's `assertTestDb` (packages/db/src/connections.ts):
|
|
93
|
+
* it is the only check that catches a test run pointed at a production
|
|
94
|
+
* database, and it needs no connection to MongoDB.
|
|
95
|
+
*/
|
|
96
|
+
type EnvAffinity = Record<string, string>;
|
|
97
|
+
interface MongoContractBlock {
|
|
98
|
+
/** e.g. `{ test: "-test", dev: "-dev" }`. Environments omitted are unconstrained. */
|
|
99
|
+
env_affinity?: EnvAffinity;
|
|
100
|
+
databases: MongoDbSpec[];
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* @htilabs/platform-common-models — MongoDB URI parsing
|
|
105
|
+
*
|
|
106
|
+
* Home of the connection-string parsing shared by the seed guard
|
|
107
|
+
* (`scripts/lib/confirmTargetDb.ts`) and the runtime verifier
|
|
108
|
+
* (`src/mongo/index.ts`). It lives in `src/` so both can import one
|
|
109
|
+
* implementation; `scripts/` cannot be imported from `src/` at build time.
|
|
110
|
+
*/
|
|
111
|
+
/** Suffix that marks a database as a non-production scratch/test database. */
|
|
112
|
+
declare const TEST_DB_SUFFIX = "-test";
|
|
113
|
+
/**
|
|
114
|
+
* Parse the target database name out of a MongoDB connection URI.
|
|
115
|
+
*
|
|
116
|
+
* The database name is the path segment after the host(s), before any query
|
|
117
|
+
* string (`?...`). Handles both `mongodb://` and `mongodb+srv://` URIs and any
|
|
118
|
+
* userinfo / multi-host / option components. Returns `null` when the URI
|
|
119
|
+
* carries no database name (e.g. `mongodb://localhost:27017` or a trailing
|
|
120
|
+
* slash with nothing after it) — callers must treat a `null` name as
|
|
121
|
+
* prod-shaped and never silently default to a production database.
|
|
122
|
+
*
|
|
123
|
+
* Implemented as manual string parsing rather than `new URL()` because Node's
|
|
124
|
+
* URL parser rejects multi-host `mongodb+srv` authorities and mishandles the
|
|
125
|
+
* comma-separated seed-list form that real connection strings use.
|
|
126
|
+
*/
|
|
127
|
+
declare function parseDbName(uri: string): string | null;
|
|
128
|
+
/**
|
|
129
|
+
* Classify a database name. A name is a "test" database (no confirmation
|
|
130
|
+
* required) only when it is non-null and ends in {@link TEST_DB_SUFFIX}.
|
|
131
|
+
* Everything else — including a `null` name — is prod-shaped.
|
|
132
|
+
*/
|
|
133
|
+
declare function isTestDb(dbName: string | null): boolean;
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* @htilabs/platform-common-models — MongoDB connection/collection verifier
|
|
137
|
+
*
|
|
138
|
+
* Sibling to `./config`. Where `validateAgainstContract` proves the env vars
|
|
139
|
+
* are present and well-typed, `verifyMongo` proves they point somewhere real.
|
|
140
|
+
*
|
|
141
|
+
* ## What this catches
|
|
142
|
+
* - a database name that does not exist and looks like a typo of one that does
|
|
143
|
+
* - a collection name that does not exist and looks like a typo of one that does
|
|
144
|
+
* - a database name that does not belong to the current environment
|
|
145
|
+
* (env-affinity; needs no connection — generalizes thread's `assertTestDb`)
|
|
146
|
+
* - collections present in MongoDB but undeclared by the service (reported)
|
|
147
|
+
*
|
|
148
|
+
* ## What this CANNOT catch
|
|
149
|
+
* A plausible-but-wrong POPULATED database. `leads-platform-prod-test` exists
|
|
150
|
+
* and carries the same collection names as `leads-platform-test`; every
|
|
151
|
+
* name-existence check passes. Detecting that needs an identity marker
|
|
152
|
+
* written inside the database, which is outside this utility's read-only
|
|
153
|
+
* remit. Do not claim otherwise in adoption docs.
|
|
154
|
+
*
|
|
155
|
+
* ## Read-only
|
|
156
|
+
* Reaches MongoDB solely through {@link MongoCatalog}: listDatabases and
|
|
157
|
+
* listCollections. It never creates, writes, or drops anything.
|
|
158
|
+
*
|
|
159
|
+
* ## Severity
|
|
160
|
+
* MongoDB creates namespaces lazily, so ABSENCE IS AMBIGUOUS (typo vs
|
|
161
|
+
* unseeded environment). Absence alone warns; absence with a plausible
|
|
162
|
+
* near-neighbour is fatal. See `similarity.ts`.
|
|
163
|
+
*
|
|
164
|
+
* FACT (verified 2026-07-10, read-only): thread registers the Mongoose model
|
|
165
|
+
* `AgencyInfo` (collection `agencyinfos`), and that collection exists in
|
|
166
|
+
* neither `platform-test` (15 collections) nor `platform-dev` (41). A
|
|
167
|
+
* registered model with zero documents has no collection. The warn-on-absence
|
|
168
|
+
* rule exists because of this; do not "tighten" it to fatal.
|
|
169
|
+
*/
|
|
170
|
+
|
|
171
|
+
type Severity = "fatal" | "warn";
|
|
172
|
+
type FindingKind = "env_var_missing" | "db_shape_violation" | "db_absent_typo" | "db_absent_unseeded" | "collection_absent_typo" | "collection_absent_unseeded" | "collection_undeclared";
|
|
173
|
+
interface Finding {
|
|
174
|
+
severity: Severity;
|
|
175
|
+
kind: FindingKind;
|
|
176
|
+
message: string;
|
|
177
|
+
dbVar?: string;
|
|
178
|
+
database?: string;
|
|
179
|
+
collection?: string;
|
|
180
|
+
/**
|
|
181
|
+
* Existing names this looks like a typo of. More than one means the evidence
|
|
182
|
+
* is ambiguous — the message lists them all rather than guessing.
|
|
183
|
+
*/
|
|
184
|
+
suggestions?: string[];
|
|
185
|
+
}
|
|
186
|
+
interface MongoVerifyReport {
|
|
187
|
+
/** True when no fatal finding was produced. Warnings do not clear `ok`. */
|
|
188
|
+
ok: boolean;
|
|
189
|
+
findings: Finding[];
|
|
190
|
+
}
|
|
191
|
+
interface VerifyMongoOptions {
|
|
192
|
+
/** Read-only catalogue. Required — this package takes no driver dependency. */
|
|
193
|
+
catalog: MongoCatalog;
|
|
194
|
+
/** Environment name for affinity checks. Defaults to NODE_ENV, then "local". */
|
|
195
|
+
env?: string;
|
|
196
|
+
/** Env source. Defaults to `process.env`. */
|
|
197
|
+
processEnv?: NodeJS.ProcessEnv;
|
|
198
|
+
/** If true, throw instead of `exit(1)`. Defaults to false (production exits). */
|
|
199
|
+
throwOnFailure?: boolean;
|
|
200
|
+
/** Injected for tests. Defaults to `process.exit`. */
|
|
201
|
+
exit?: (code: number) => never;
|
|
202
|
+
/** Injected for tests. Defaults to `console`. */
|
|
203
|
+
logger?: Pick<Console, "error" | "warn">;
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* Verify every database and collection declared in `runtimeYamlPath` against a
|
|
207
|
+
* live MongoDB catalogue.
|
|
208
|
+
*
|
|
209
|
+
* Collects ALL findings before deciding, exactly as `validateAgainstContract`
|
|
210
|
+
* does — an operator fixing a misconfiguration should see every problem at
|
|
211
|
+
* once, not one per restart.
|
|
212
|
+
*
|
|
213
|
+
* Resolves to the report when no fatal finding is produced. On a fatal finding
|
|
214
|
+
* it prints every finding and calls `exit(1)`, or throws when
|
|
215
|
+
* `throwOnFailure` is set.
|
|
216
|
+
*
|
|
217
|
+
* A contract with no `mongo:` block is a no-op success.
|
|
218
|
+
*/
|
|
219
|
+
declare function verifyMongo(runtimeYamlPath: string, opts: VerifyMongoOptions): Promise<MongoVerifyReport>;
|
|
220
|
+
|
|
221
|
+
export { type EnvAffinity, type Finding, type FindingKind, type MongoCatalog, type MongoClientLike, type MongoContractBlock, type MongoDbSpec, type MongoVerifyReport, type MongooseConnectionLike, type Severity, TEST_DB_SUFFIX, type VerifyMongoOptions, catalogFromClient, catalogFromMongoose, isTestDb, parseDbName, verifyMongo };
|