document-model 6.2.3 → 6.3.0-dev.1

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.
@@ -0,0 +1,668 @@
1
+ import { DefinitionCheckProfile, DefinitionCheckReport, DefinitionCheckSkipReason, DefinitionDiagnostic, DefinitionPath, DefinitionSource, DocumentModelDefinition, DocumentModelModule, DocumentModelPHState, Sha256Digest, SubgraphDefinition, UpgradeManifest } from "@powerhousedao/shared/document-model";
2
+ //#region src/definition/kernel/diagnostics.d.ts
3
+ /** @experimental A source as `specifier#/export/path`, each segment escaped as a JSON Pointer token. */
4
+ export declare function formatDefinitionSource(source: DefinitionSource): string;
5
+ /** @experimental One line: code, severity and phase, location, message, expected, received, related and repair. */
6
+ export declare function formatDefinitionDiagnostic(diagnostic: DefinitionDiagnostic): string;
7
+ //#endregion
8
+ //#region src/definition/tooling/adapters/types.d.ts
9
+ /**
10
+ * @experimental The shape both authoring paths normalize into. A consumer
11
+ * reads it without learning which adapter produced it.
12
+ */
13
+ type NormalizedDocumentModelArtifact = {
14
+ readonly kind: "powerhouse.document-model-artifact";
15
+ readonly source: DefinitionSource;
16
+ readonly documentType: string;
17
+ readonly version: number;
18
+ readonly definition: DocumentModelDefinition;
19
+ readonly digest: Sha256Digest;
20
+ readonly documentModel: DocumentModelPHState;
21
+ };
22
+ /** @experimental */
23
+ type NormalizedDocumentModelResult = {
24
+ readonly artifacts: readonly NormalizedDocumentModelArtifact[];
25
+ readonly upgradeManifest: UpgradeManifest<readonly number[]> | null;
26
+ readonly diagnostics: readonly DefinitionDiagnostic[];
27
+ };
28
+ //#endregion
29
+ //#region src/definition/tooling/adapters/code-first-document-model-source-adapter.d.ts
30
+ /**
31
+ * @experimental Normalizes one materialized code-first module, or a family
32
+ * and its versions in order. A family reports every malformed member: a
33
+ * valid sibling never makes a broken one pass.
34
+ */
35
+ export declare function adaptCodeFirstDocumentModelSource(value: unknown, source: DefinitionSource): NormalizedDocumentModelResult;
36
+ //#endregion
37
+ //#region src/definition/tooling/model-directories.d.ts
38
+ /** @experimental The models directory a config without `documentModelsDir` uses. */
39
+ export declare const DEFAULT_DOCUMENT_MODELS_DIR = "./document-models";
40
+ /**
41
+ * @experimental What one immediate directory of the models directory holds.
42
+ *
43
+ * - `stored`: a schema-first model, because `<name>/<name>.json` exists. An
44
+ * unreadable or invalid file is still this model's, never a code-first one.
45
+ * - `generated`: schema-first generated code (`gen/` or `v<N>/gen/`) without
46
+ * its stored specification. Its generated modules stay; nothing is pruned.
47
+ * - `module`: a code-first model, whose entry is the directory's one
48
+ * `index.<ext>` module. Generated code wins over an index, which codegen
49
+ * writes into schema-first directories too.
50
+ * - `invalid`: a directory discovery cannot classify; a diagnostic says why.
51
+ * - `none`: no model entry. The declaration scan reports code-first models
52
+ * declared here without an entry.
53
+ */
54
+ type DocumentModelDirectory = {
55
+ readonly name: string;
56
+ /** Absolute, as spelled under the models directory. */
57
+ readonly path: string;
58
+ } & ({
59
+ readonly kind: "stored";
60
+ readonly specification: `./${string}`;
61
+ } | {
62
+ readonly kind: "generated";
63
+ } | {
64
+ readonly kind: "module";
65
+ readonly entry: `./${string}`;
66
+ } | {
67
+ readonly kind: "invalid";
68
+ } | {
69
+ readonly kind: "none";
70
+ });
71
+ /** @experimental The classified model directories, sorted by name. */
72
+ type DocumentModelDirectories = {
73
+ /** Absolute. */
74
+ readonly documentModelsDir: string;
75
+ readonly directories: readonly DocumentModelDirectory[];
76
+ readonly diagnostics: readonly DefinitionDiagnostic[];
77
+ };
78
+ /**
79
+ * The configured models directory, resolved inside the package, or why it
80
+ * cannot be read. The package root itself is refused: its directories are
81
+ * the package's other sources, not models.
82
+ */
83
+ export declare function resolveDocumentModelsDir(packageRoot: string, config: Readonly<Record<string, unknown>>): {
84
+ readonly ok: true;
85
+ readonly path: string;
86
+ } | {
87
+ readonly ok: false;
88
+ readonly diagnostic: DefinitionDiagnostic;
89
+ };
90
+ /**
91
+ * @experimental Classifies each immediate directory of the models directory
92
+ * by the files it holds, without importing anything. Discovery never reads
93
+ * the generated barrels beside the directories. A missing models directory
94
+ * holds no models; a directory that cannot be read is `invalid` with a
95
+ * diagnostic, so no caller mistakes it for an absent model.
96
+ */
97
+ export declare function discoverDocumentModelDirectories(packageRoot: string, documentModelsDir: string): DocumentModelDirectories;
98
+ //#endregion
99
+ //#region src/definition/tooling/definition-source-types.d.ts
100
+ /**
101
+ * @experimental The discovered sources, exactly as a definition report
102
+ * carries them. Defined from the stored report type so the two cannot
103
+ * disagree.
104
+ */
105
+ type DefinitionSourceSet = DefinitionCheckReport["sourceSet"];
106
+ /** @experimental Whether discovery or a caller chose the sources. */
107
+ type DefinitionSourceOrigin = DefinitionSourceSet["origin"];
108
+ /**
109
+ * @experimental The loader's one substitutable dependency: something that
110
+ * turns a package-relative TypeScript path into a module namespace. Codegen
111
+ * supplies a Vite environment; a build can supply its own module graph.
112
+ */
113
+ interface TypeScriptSourceImportInterface {
114
+ importModule(request: {
115
+ readonly packageRoot: string;
116
+ readonly specifier: `./${string}`;
117
+ readonly packageRevision: Sha256Digest;
118
+ readonly signal?: AbortSignal;
119
+ }): Promise<Readonly<Record<string, unknown>>>;
120
+ disposeRevision?(packageRevision?: Sha256Digest): Promise<void> | void;
121
+ }
122
+ /**
123
+ * @experimental The package whose models are discovered: the directory of
124
+ * `configFile`, read with the config's `documentModelsDir`. A missing config
125
+ * fails unless `allowMissingConfig`, which then reads the default directory.
126
+ */
127
+ type DefinitionSourceSelectionRequest = {
128
+ readonly configFile?: string;
129
+ readonly allowMissingConfig?: boolean;
130
+ };
131
+ /** @experimental */
132
+ type DefinitionSourceLoadRequest = DefinitionSourceSelectionRequest & {
133
+ /**
134
+ * Binds the imported bytes this load may reuse. A definition digest is not
135
+ * enough: editing a reducer helper leaves every definition digest unchanged.
136
+ */
137
+ readonly packageRevision: Sha256Digest;
138
+ readonly signal?: AbortSignal;
139
+ };
140
+ /** @experimental The discovered sources, resolved without importing anything. */
141
+ type DefinitionSourceResolution = {
142
+ readonly packageRoot: string;
143
+ readonly sourceSet: DefinitionSourceSet;
144
+ readonly diagnostics: readonly DefinitionDiagnostic[];
145
+ } & ({
146
+ readonly status: "ready" | "failed";
147
+ readonly skipReason?: never;
148
+ } | {
149
+ readonly status: "skipped";
150
+ readonly skipReason: DefinitionCheckSkipReason;
151
+ });
152
+ /** @experimental One value the traversal recognized, and where it was found. */
153
+ type LoadedDefinition<TValue> = {
154
+ readonly source: DefinitionSource;
155
+ readonly path: DefinitionPath;
156
+ readonly value: TValue;
157
+ };
158
+ /** @experimental */
159
+ type LoadedDefinitionSet = DefinitionSourceResolution & {
160
+ /** Absolute; absent when the configured models directory cannot be read. */
161
+ readonly documentModelsDir?: string;
162
+ /** What discovery found in each model directory; absent for requested sources. */
163
+ readonly directories?: readonly DocumentModelDirectory[];
164
+ readonly documentModels: readonly LoadedDefinition<DocumentModelModule>[];
165
+ readonly upgradeManifests: readonly LoadedDefinition<UpgradeManifest<readonly number[]>>[];
166
+ /**
167
+ * The sources that export a definition. A value several sources export is
168
+ * listed above under the first one only, so a source that re-exports
169
+ * another's definitions is named here and nowhere else.
170
+ */
171
+ readonly sourcesWithDefinitions: readonly DefinitionSource[];
172
+ };
173
+ //#endregion
174
+ //#region src/definition/tooling/definition-source-loader.d.ts
175
+ /**
176
+ * @experimental Imports the discovered definition sources and finds the
177
+ * materialized document models, families and upgrade manifests they export.
178
+ * It folds aliases, reports two values that claim one `documentType@version`,
179
+ * and returns everything sorted by source, so neither directory order nor
180
+ * import completion order changes a result. Validity belongs to the
181
+ * adapters; registration belongs to the host.
182
+ */
183
+ export declare class DefinitionSourceLoader {
184
+ #private;
185
+ constructor(importer: TypeScriptSourceImportInterface);
186
+ resolve(request: DefinitionSourceSelectionRequest): DefinitionSourceResolution;
187
+ /**
188
+ * Imports the entry module of every model directory discovery finds and
189
+ * collects the models, families and upgrade manifests it exports.
190
+ */
191
+ normalizeDefinitionSources(request: DefinitionSourceLoadRequest): Promise<LoadedDefinitionSet>;
192
+ /**
193
+ * @experimental Loads sources the caller names, through the same imports
194
+ * and checks as discovered ones.
195
+ */
196
+ normalizeRequestedSources(request: DefinitionSourceLoadRequest & {
197
+ readonly sources: readonly unknown[];
198
+ }): Promise<LoadedDefinitionSet>;
199
+ /**
200
+ * @experimental Imports one package module through the same importer and
201
+ * package revision as the selected sources, so a module both reach is
202
+ * evaluated once. A module outside the package root is refused as an
203
+ * outside source is. Experimental: tooling uses it for the project scalars
204
+ * module while code-first projects are introduced.
205
+ */
206
+ importPackageModule(request: DefinitionSourceLoadRequest & {
207
+ readonly specifier: `./${string}`;
208
+ }): Promise<{
209
+ readonly ok: true;
210
+ readonly namespace: Readonly<Record<string, unknown>>;
211
+ } | {
212
+ readonly ok: false;
213
+ readonly diagnostics: readonly DefinitionDiagnostic[];
214
+ }>;
215
+ dispose(): Promise<void>;
216
+ }
217
+ //#endregion
218
+ //#region src/definition/tooling/definition-source-resolution.d.ts
219
+ /**
220
+ * @experimental The sources discovery finds, resolved without importing
221
+ * anything and without any machine-specific path but the root.
222
+ */
223
+ export declare function resolveDefinitionSelection(request: DefinitionSourceSelectionRequest): DefinitionSourceResolution;
224
+ //#endregion
225
+ //#region src/definition/tooling/adapters/producer.d.ts
226
+ /**
227
+ * Maps a path a check reports in normalized coordinates (served data under
228
+ * `documentModel/global`, definition data under `specifications`) to where
229
+ * the source's author edits it.
230
+ */
231
+ type DefinitionRelocation = (path: DefinitionPath) => DefinitionPath;
232
+ type ProducedDefinitions = {
233
+ readonly artifacts: readonly NormalizedDocumentModelArtifact[];
234
+ readonly diagnostics: readonly DefinitionDiagnostic[];
235
+ /** By source specifier. A source authored in normalized coordinates has none. */
236
+ readonly relocations: ReadonlyMap<string, DefinitionRelocation>;
237
+ };
238
+ type DefinitionProducerInput = {
239
+ readonly loader: DefinitionSourceLoader;
240
+ readonly configFile: string;
241
+ readonly packageRevision: Sha256Digest;
242
+ readonly signal?: AbortSignal;
243
+ /** Absolute. */
244
+ readonly packageRoot: string;
245
+ /** The selected code-first sources, imported once for every producer. */
246
+ readonly loaded: LoadedDefinitionSet;
247
+ /** Absolute and inside the package; absent when the configured directory cannot be read. */
248
+ readonly documentModelsDir?: string;
249
+ };
250
+ type DefinitionProducer = (input: DefinitionProducerInput) => ProducedDefinitions | Promise<ProducedDefinitions>;
251
+ //#endregion
252
+ //#region src/definition/tooling/report/types.d.ts
253
+ /** A code-first declaration under the document models directory that no model entry exports. */
254
+ type UnregisteredDefinition = {
255
+ readonly kind: "document-model";
256
+ /** `./<documentModelsDir>/<name>/`. */
257
+ readonly unit: `./${string}`;
258
+ /** The declaring module: the directory's `index.ts` when it declares, else the first declaring file. */
259
+ readonly specifier: `./${string}`;
260
+ /**
261
+ * `not-exported`: an entry module evaluated the declaring files without
262
+ * exporting the model. `stored-directory`: the directory holds a stored
263
+ * specification, so discovery reads it as schema-first.
264
+ */
265
+ readonly reason: "unreached" | "not-exported" | "stored-directory";
266
+ };
267
+ /**
268
+ * @experimental What every registered check reads. A wider input, such as
269
+ * ph-cli's release evidence, lets a later layer register checks that need
270
+ * more, without changing the runner.
271
+ */
272
+ type DefinitionCheckInput = {
273
+ readonly sourceSet: DefinitionSourceSet;
274
+ /** Sorted by document type, version and source. */
275
+ readonly artifacts: readonly NormalizedDocumentModelArtifact[];
276
+ readonly unregistered: readonly UnregisteredDefinition[];
277
+ };
278
+ /** What the check runner and inspection need besides the check input. */
279
+ type LoadedDefinitionProject = DefinitionCheckInput & {
280
+ readonly skipReason?: DefinitionCheckSkipReason;
281
+ /** Load and adapter diagnostics, with package-relative text. */
282
+ readonly diagnostics: readonly DefinitionDiagnostic[];
283
+ /** By source specifier: where a check's normalized path sits in that source. */
284
+ readonly relocations?: ReadonlyMap<string, DefinitionRelocation>;
285
+ };
286
+ //#endregion
287
+ //#region src/definition/tooling/check/types.d.ts
288
+ /**
289
+ * @experimental One named check over normalized artifacts, which ph-cli passes
290
+ * to `checkProjectDefinitions`. It reports normalized paths.
291
+ */
292
+ type DefinitionCheck<TInput extends DefinitionCheckInput = DefinitionCheckInput> = {
293
+ readonly name: string;
294
+ readonly run: (input: TInput) => readonly DefinitionDiagnostic[] | Promise<readonly DefinitionDiagnostic[]>;
295
+ };
296
+ //#endregion
297
+ //#region src/definition/tooling/check/check-project-definitions.d.ts
298
+ /**
299
+ * @experimental The checks `ph model check` runs on document models. A later
300
+ * layer, such as ph-cli's release profile, adds its own with
301
+ * `[...documentModelChecks, ...theirs]`.
302
+ */
303
+ export declare const documentModelChecks: readonly DefinitionCheck[];
304
+ /**
305
+ * @experimental Runs every check over a loaded project and builds the stored
306
+ * check report with the project's load diagnostics. `definitions` adds
307
+ * inventory entries a caller checked itself; `profile` (default `edit`) names
308
+ * the check list the caller ran. Experimental while code-first projects are
309
+ * introduced.
310
+ */
311
+ export declare function checkProjectDefinitions<TInput extends DefinitionCheckInput = DefinitionCheckInput>(project: LoadedDefinitionProject & TInput, options?: {
312
+ readonly checks?: readonly DefinitionCheck<TInput>[];
313
+ readonly definitions?: DefinitionCheckReport["definitions"];
314
+ readonly profile?: DefinitionCheckProfile;
315
+ }): Promise<DefinitionCheckReport>;
316
+ //#endregion
317
+ //#region src/definition/tooling/release/types.d.ts
318
+ /**
319
+ * One reason a host would not serve a model as declared. Plain data, so a
320
+ * host's validator result is passed in as is and tooling never imports a host.
321
+ */
322
+ type HostValidationFindingData = {
323
+ readonly kind: "scalar-unbound";
324
+ readonly documentType: string;
325
+ readonly scalar: string;
326
+ } | {
327
+ /** `scalar-uncomparable`: equal metadata, validators that could not be compared. */
328
+ readonly kind: "scalar-mismatch" | "scalar-uncomparable";
329
+ readonly documentType: string;
330
+ readonly scalar: string;
331
+ readonly packageName: string;
332
+ /** Canonical JSON of the stored scalar metadata, with the validator when known. */
333
+ readonly declared: string;
334
+ readonly registered: string;
335
+ } | {
336
+ readonly kind: "definition-invalid" | "definition-mismatch";
337
+ readonly documentType: string;
338
+ /** The host's wire diagnostics, with paths into the module. */
339
+ readonly diagnostics: readonly DefinitionDiagnostic[];
340
+ };
341
+ /** @experimental A host validator's result, as ph-cli passes it to `releaseChecks`. */
342
+ type HostValidationEvidence = {
343
+ readonly completed: true;
344
+ readonly findings: readonly HostValidationFindingData[];
345
+ } | {
346
+ /** The host validator could not run over the package. */
347
+ readonly completed: false;
348
+ /** What stopped it, package relative. */
349
+ readonly reason: string;
350
+ readonly findings: readonly HostValidationFindingData[];
351
+ };
352
+ /** @experimental The evidence ph-cli gathers for the release profile. */
353
+ type ReleaseEvidence = {
354
+ readonly host: HostValidationEvidence;
355
+ };
356
+ /** @experimental The input `releaseChecks` read. */
357
+ type ReleaseCheckInput = DefinitionCheckInput & {
358
+ readonly release: ReleaseEvidence;
359
+ };
360
+ //#endregion
361
+ //#region src/definition/tooling/release/release-checks.d.ts
362
+ /**
363
+ * @experimental The checks the release profile of `ph build --release` and
364
+ * `ph model check --release` adds to `documentModelChecks`. They read the
365
+ * release evidence a caller gathered.
366
+ */
367
+ export declare const releaseChecks: readonly DefinitionCheck<ReleaseCheckInput>[];
368
+ //#endregion
369
+ //#region src/definition/tooling/report/status.d.ts
370
+ type DefinitionStatus = DefinitionCheckReport["status"];
371
+ //#endregion
372
+ //#region src/definition/tooling/inspect/types.d.ts
373
+ /**
374
+ * @experimental One served version of a family, as `ph model inspect` prints
375
+ * it. Experimental while code-first projects are introduced.
376
+ */
377
+ type DocumentModelInspection = {
378
+ readonly version: number;
379
+ readonly source: DefinitionSource;
380
+ readonly scopes: {
381
+ readonly global: string;
382
+ readonly local: string | null;
383
+ };
384
+ readonly modules: readonly {
385
+ readonly key: string;
386
+ readonly name: string;
387
+ readonly operations: readonly {
388
+ readonly key: string;
389
+ readonly name: string | null;
390
+ readonly actionType: string;
391
+ readonly scope: "global" | "local";
392
+ readonly input: string | null;
393
+ readonly errors: readonly {
394
+ readonly key: string;
395
+ readonly code: string | null;
396
+ }[];
397
+ }[];
398
+ }[];
399
+ readonly scalars: readonly {
400
+ readonly name: string;
401
+ readonly implementation: string;
402
+ }[];
403
+ readonly types: readonly string[];
404
+ };
405
+ /**
406
+ * @experimental One definition and the versions it serves. Every version
407
+ * carries the whole history, so the digest, name and compatibility belong to
408
+ * the family, not to a version. Experimental while code-first projects are
409
+ * introduced.
410
+ */
411
+ type DocumentModelFamilyInspection = {
412
+ readonly documentType: string;
413
+ readonly name: string;
414
+ readonly extension: string;
415
+ readonly digest: Sha256Digest;
416
+ readonly compatibility: DocumentModelDefinition["compatibility"];
417
+ readonly versions: readonly DocumentModelInspection[];
418
+ };
419
+ /**
420
+ * @experimental What `ph model inspect --json` prints: deterministic, package
421
+ * relative, and diffable between releases. Experimental while code-first
422
+ * projects are introduced.
423
+ */
424
+ type DefinitionInspectionReport = {
425
+ readonly kind: "powerhouse.definition-inspection";
426
+ readonly formatVersion: 2;
427
+ readonly status: DefinitionStatus;
428
+ readonly sourceSet: DefinitionSourceSet;
429
+ readonly families: readonly DocumentModelFamilyInspection[];
430
+ readonly diagnostics: readonly DefinitionDiagnostic[];
431
+ /** Present only when a selection matched exactly one model. */
432
+ readonly definition?: DocumentModelDefinition;
433
+ };
434
+ /** @experimental */
435
+ type DefinitionInspectionSelection = {
436
+ readonly documentType: string;
437
+ readonly version: number;
438
+ };
439
+ //#endregion
440
+ //#region src/definition/tooling/inspect/inspect-project-definitions.d.ts
441
+ /**
442
+ * @experimental Describes the loaded models without running checks. With a
443
+ * selection it answers for that model only, and adds its full definition
444
+ * when exactly one model serves it. Experimental while code-first projects
445
+ * are introduced.
446
+ */
447
+ export declare function inspectProjectDefinitions(project: LoadedDefinitionProject, options?: {
448
+ readonly selection?: DefinitionInspectionSelection;
449
+ }): DefinitionInspectionReport;
450
+ //#endregion
451
+ //#region src/definition/tooling/project/unregistered-definitions.d.ts
452
+ /**
453
+ * Each `<documentModelsDir>/<name>/` whose sources declare a code-first model
454
+ * that no entry module's import reached, or that an entry reached without
455
+ * exporting the model's literal id. An entry that did not import reaches
456
+ * files no one can name, so the scan then reports nothing.
457
+ */
458
+ export declare function findUnregisteredDefinitions(request: {
459
+ readonly packageRoot: string;
460
+ /** Absolute, and already checked to stay inside the package root. */
461
+ readonly documentModelsDir: string;
462
+ readonly sources: readonly DefinitionSource[];
463
+ /** Absolute paths of every module the import of `specifier` evaluated, its own included. */
464
+ readonly importedFiles: (specifier: string) => readonly string[];
465
+ readonly loadedDocumentTypes: ReadonlySet<string>;
466
+ /** Units (`./<documentModelsDir>/<name>/`) a stored specification owns. */
467
+ readonly storedUnits?: ReadonlySet<string>;
468
+ }): {
469
+ readonly unregistered: readonly UnregisteredDefinition[];
470
+ readonly diagnostics: readonly DefinitionDiagnostic[];
471
+ };
472
+ /**
473
+ * @experimental The package-relative files under `directory` that declare a
474
+ * code-first document model, read from source text without running them.
475
+ * Codegen refuses to write a stored model over them.
476
+ */
477
+ export declare function codeFirstDeclarationFiles(packageRoot: string, directory: string): readonly `./${string}`[];
478
+ //#endregion
479
+ //#region src/definition/tooling/check/checks/unregistered-definitions.d.ts
480
+ /** @experimental Reports declarations that an entry does not publish. */
481
+ export declare function unregisteredDefinitionDiagnostics(unregistered: readonly UnregisteredDefinition[]): import("@powerhousedao/shared/document-model").DefinitionDiagnostic[];
482
+ //#endregion
483
+ //#region src/definition/tooling/project/project-definitions.d.ts
484
+ /**
485
+ * @experimental A package's document models, loaded once and read by both
486
+ * `ph model check` and `ph model inspect`. Experimental while code-first
487
+ * projects are introduced.
488
+ */
489
+ type ProjectDefinitions = LoadedDefinitionProject & {
490
+ /** Absolute. No report carries it. */
491
+ readonly packageRoot: string;
492
+ };
493
+ /**
494
+ * @experimental Loads the code-first model directories discovery finds and
495
+ * the package's stored schema-first models, and scans for code-first
496
+ * declarations no entry module reaches. Artifacts and diagnostics are
497
+ * sorted and package relative. `producers` replaces the default readers.
498
+ * `importedFiles` names the absolute paths of every module the loader's
499
+ * import of a discovered specifier evaluated, so reach follows whatever the
500
+ * importer resolved. Experimental while code-first projects are introduced.
501
+ */
502
+ export declare function loadProjectDefinitions(request: {
503
+ readonly loader: DefinitionSourceLoader;
504
+ readonly configFile: string;
505
+ readonly allowMissingConfig?: boolean;
506
+ readonly packageRevision: Sha256Digest;
507
+ readonly signal?: AbortSignal;
508
+ readonly producers?: readonly DefinitionProducer[];
509
+ readonly importedFiles: (specifier: string) => readonly string[];
510
+ }): Promise<ProjectDefinitions>;
511
+ //#endregion
512
+ //#region src/definition/tooling/subgraph/read.d.ts
513
+ /** @experimental The definition a code-first class's `describe()` compiled. */
514
+ type TypedSubgraphDefinition = Extract<SubgraphDefinition, {
515
+ readonly schemaKind: "typed";
516
+ }>;
517
+ /** @experimental A code-first subgraph whose description compiled. */
518
+ type CodeFirstSubgraph = {
519
+ readonly name: string;
520
+ readonly source: DefinitionSource;
521
+ readonly definition: TypedSubgraphDefinition;
522
+ };
523
+ /** @experimental What {@link readSubgraphDefinitions} found in a module. */
524
+ type SubgraphDefinitions = {
525
+ /** In export order: the module's own order, or name order for an ES module namespace. */
526
+ readonly subgraphs: readonly CodeFirstSubgraph[];
527
+ /** Protocol, describe and name problems, and each description's own diagnostics. */
528
+ readonly diagnostics: readonly DefinitionDiagnostic[];
529
+ };
530
+ /**
531
+ * @experimental Reads the code-first subgraph classes a module exports, as
532
+ * the host's extraction reaches them: each export, and each value of an
533
+ * exported object. It calls each class's protocol `describe()` and never
534
+ * constructs a class, so a constructor that needs a database or environment
535
+ * does not run. Schema-first classes and other values are left out. A
536
+ * code-first class without a name is a base: it is skipped when another
537
+ * export extends it, and reported when none does.
538
+ */
539
+ export declare function readSubgraphDefinitions(exports: object, options?: {
540
+ readonly specifier?: `./${string}`;
541
+ }): SubgraphDefinitions;
542
+ //#endregion
543
+ //#region src/definition/tooling/subgraph/schema-first/sdl-conflicts.d.ts
544
+ /**
545
+ * @experimental The source text of one schema-first subgraph, as ph-cli
546
+ * finds it next to the subgraph's class. Tooling never imports or
547
+ * constructs a schema-first class, so its SDL is read from text.
548
+ */
549
+ type SchemaFirstSubgraphSource = {
550
+ /** The subgraph's directory, `./subgraphs/<dir>/`. */
551
+ readonly unit: `./${string}`;
552
+ /** The name the class assigns, when its text shows a literal one. */
553
+ readonly name: string | null;
554
+ /** The file the SDL is read from. */
555
+ readonly source: DefinitionSource;
556
+ /** `graphql` for an SDL file, `typescript` for a module holding gql templates. */
557
+ readonly language: "graphql" | "typescript";
558
+ /** `null` when the subgraph has no file to read. */
559
+ readonly text: string | null;
560
+ };
561
+ //#endregion
562
+ //#region src/definition/tooling/subgraph/input.d.ts
563
+ /**
564
+ * @experimental Everything the subgraph checks read: the code-first
565
+ * subgraphs as their classes describe them, the text of the schema-first
566
+ * ones, and the scalars the package exports.
567
+ */
568
+ type SubgraphCheckInput = {
569
+ readonly codeFirst: readonly CodeFirstSubgraph[];
570
+ readonly schemaFirst: readonly SchemaFirstSubgraphSource[];
571
+ /**
572
+ * The scalar names `scalars/index.ts` exports under their own name, sorted.
573
+ * `undefined` when it was not read, which skips the scalar check.
574
+ */
575
+ readonly packageScalars: readonly string[] | undefined;
576
+ /** Import, protocol and describe problems, and each description's own diagnostics. */
577
+ readonly diagnostics: readonly DefinitionDiagnostic[];
578
+ /** What a host's admission does with each code-first subgraph, as the caller replayed it; empty when it did not. */
579
+ readonly hostConflicts: readonly SubgraphHostConflict[];
580
+ };
581
+ /**
582
+ * @experimental A code-first subgraph a host would refuse or leave out, from
583
+ * a replay of the host's admission: `nameHeldBy` when a built-in subgraph or
584
+ * a document model's subgraph holds its name, and `claims` for the types and
585
+ * root fields other subgraphs own, with their owners.
586
+ */
587
+ type SubgraphHostConflict = {
588
+ readonly subgraph: string;
589
+ readonly nameHeldBy?: "core" | "document model";
590
+ readonly claims: readonly {
591
+ readonly claim: string;
592
+ readonly owner: string;
593
+ }[];
594
+ };
595
+ /** @experimental A code-first subgraph's entry in the check report. */
596
+ type SubgraphInventoryEntry = DefinitionCheckReport["definitions"][number];
597
+ /** @experimental A package module the caller could not import, and why, in package-relative words. */
598
+ type SubgraphImportFailure = {
599
+ readonly specifier: `./${string}`;
600
+ readonly reason: string;
601
+ };
602
+ /**
603
+ * @experimental Builds the subgraph check input and the inventory entries
604
+ * once, for the check, inspection and release callers to share. `scalars`
605
+ * is the namespace of `scalars/index.ts`: `null` when the package has none,
606
+ * absent when the caller did not read it. `importFailures` names the
607
+ * modules the caller could not import. `hostConflicts` is the caller's replay
608
+ * of a host's admission of the code-first subgraphs.
609
+ */
610
+ export declare function subgraphCheckInput(request: {
611
+ readonly definitions: SubgraphDefinitions;
612
+ readonly schemaFirst?: readonly SchemaFirstSubgraphSource[];
613
+ readonly scalars?: object | null;
614
+ readonly importFailures?: readonly SubgraphImportFailure[];
615
+ readonly hostConflicts?: readonly SubgraphHostConflict[];
616
+ }): {
617
+ readonly input: SubgraphCheckInput;
618
+ readonly inventory: readonly SubgraphInventoryEntry[];
619
+ };
620
+ //#endregion
621
+ //#region src/definition/tooling/subgraph/checks.d.ts
622
+ /** @experimental The input of {@link subgraphChecks}. */
623
+ type SubgraphChecksInput = DefinitionCheckInput & {
624
+ readonly subgraphs: SubgraphCheckInput;
625
+ };
626
+ type SubgraphCheck = DefinitionCheck<SubgraphChecksInput>;
627
+ /**
628
+ * @experimental The checks `ph model check` adds when a project has a
629
+ * code-first subgraph. A caller registers them with
630
+ * `[...documentModelChecks, ...subgraphChecks]` and a
631
+ * {@link SubgraphChecksInput}.
632
+ */
633
+ export declare const subgraphChecks: readonly SubgraphCheck[];
634
+ //#endregion
635
+ //#region src/definition/tooling/subgraph/inspection.d.ts
636
+ /** @experimental One subgraph, as `ph model inspect` prints it. */
637
+ type SubgraphInspection = {
638
+ readonly style: "code-first";
639
+ readonly name: string;
640
+ readonly source: DefinitionSource;
641
+ readonly digest: Sha256Digest;
642
+ readonly hasSubscriptions: boolean;
643
+ /** Schema coordinates of the entries, in entry order: `Query.x`, `Type.field`, or the abstract type a resolveType serves. */
644
+ readonly entries: readonly string[];
645
+ readonly types: readonly string[];
646
+ readonly scalars: readonly {
647
+ readonly name: string;
648
+ readonly implementation: string;
649
+ }[];
650
+ } | {
651
+ readonly style: "schema-first";
652
+ readonly name: string | null;
653
+ readonly source: DefinitionSource;
654
+ };
655
+ /** @experimental An inspection report with the project's subgraphs. */
656
+ type SubgraphInspectionReport = DefinitionInspectionReport & {
657
+ readonly subgraphs: readonly SubgraphInspection[];
658
+ };
659
+ /**
660
+ * @experimental Adds the project's subgraphs to an inspection report: a
661
+ * `subgraphs` section, the subgraph diagnostics, and a status that counts
662
+ * them. A project whose only definitions are subgraphs is not skipped.
663
+ */
664
+ export declare function withSubgraphInspection(project: LoadedDefinitionProject, report: DefinitionInspectionReport, subgraphs: SubgraphCheckInput): SubgraphInspectionReport;
665
+ //#endregion
666
+ export type { CodeFirstSubgraph, DefinitionCheck, DefinitionCheckInput, DefinitionInspectionReport, DefinitionSourceLoadRequest, DefinitionSourceOrigin, DefinitionSourceResolution, DefinitionSourceSelectionRequest, DefinitionSourceSet, DocumentModelDirectories, DocumentModelDirectory, DocumentModelFamilyInspection, DocumentModelInspection, HostValidationEvidence, LoadedDefinition, LoadedDefinitionSet, NormalizedDocumentModelArtifact, NormalizedDocumentModelResult, ProjectDefinitions, ReleaseCheckInput, ReleaseEvidence, SchemaFirstSubgraphSource, SubgraphCheckInput, SubgraphChecksInput, SubgraphDefinitions, SubgraphHostConflict, SubgraphImportFailure, SubgraphInspection, SubgraphInspectionReport, SubgraphInventoryEntry, TypeScriptSourceImportInterface, TypedSubgraphDefinition };
667
+ export {};
668
+ //# sourceMappingURL=tooling.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tooling.d.mts","names":[],"sources":["../src/definition/kernel/diagnostics.ts","../src/definition/tooling/adapters/types.ts","../src/definition/tooling/adapters/code-first-document-model-source-adapter.ts","../src/definition/tooling/model-directories.ts","../src/definition/tooling/definition-source-types.ts","../src/definition/tooling/definition-source-loader.ts","../src/definition/tooling/definition-source-resolution.ts","../src/definition/tooling/adapters/producer.ts","../src/definition/tooling/report/types.ts","../src/definition/tooling/check/types.ts","../src/definition/tooling/check/check-project-definitions.ts","../src/definition/tooling/release/types.ts","../src/definition/tooling/release/release-checks.ts","../src/definition/tooling/report/status.ts","../src/definition/tooling/inspect/types.ts","../src/definition/tooling/inspect/inspect-project-definitions.ts","../src/definition/tooling/project/unregistered-definitions.ts","../src/definition/tooling/check/checks/unregistered-definitions.ts","../src/definition/tooling/project/project-definitions.ts","../src/definition/tooling/subgraph/read.ts","../src/definition/tooling/subgraph/schema-first/sdl-conflicts.ts","../src/definition/tooling/subgraph/input.ts","../src/definition/tooling/subgraph/checks.ts","../src/definition/tooling/subgraph/inspection.ts"],"mappings":"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"}