document-model 6.2.3-dev.90 → 6.2.3-dev.92

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,321 @@
1
+ import { DefinitionCheckReport, DefinitionCheckSkipReason, DefinitionDiagnostic, DefinitionPath, DefinitionSource, DocumentModelDefinition, DocumentModelModule, DocumentModelPHState, Sha256Digest, UpgradeManifest } from "@powerhousedao/shared/document-model";
2
+ //#region src/definition/kernel/diagnostics.d.ts
3
+ /** @experimental One line: code, severity and phase, location, message, expected, received, related and repair. */
4
+ export declare function formatDefinitionDiagnostic(diagnostic: DefinitionDiagnostic): string;
5
+ //#endregion
6
+ //#region src/definition/tooling/adapters/types.d.ts
7
+ /**
8
+ * @experimental The shape both authoring paths normalize into. A consumer
9
+ * reads it without learning which adapter produced it.
10
+ */
11
+ type NormalizedDocumentModelArtifact = {
12
+ readonly kind: "powerhouse.document-model-artifact";
13
+ readonly source: DefinitionSource;
14
+ readonly documentType: string;
15
+ readonly version: number;
16
+ readonly definition: DocumentModelDefinition;
17
+ readonly digest: Sha256Digest;
18
+ readonly documentModel: DocumentModelPHState;
19
+ };
20
+ /** @experimental */
21
+ type NormalizedDocumentModelResult = {
22
+ readonly artifacts: readonly NormalizedDocumentModelArtifact[];
23
+ readonly upgradeManifest: UpgradeManifest<readonly number[]> | null;
24
+ readonly diagnostics: readonly DefinitionDiagnostic[];
25
+ };
26
+ //#endregion
27
+ //#region src/definition/tooling/adapters/code-first-document-model-source-adapter.d.ts
28
+ /**
29
+ * @experimental Normalizes one materialized code-first module, or a family
30
+ * and its versions in order. A family reports every malformed member: a
31
+ * valid sibling never makes a broken one pass.
32
+ */
33
+ export declare function adaptCodeFirstDocumentModelSource(value: unknown, source: DefinitionSource): NormalizedDocumentModelResult;
34
+ //#endregion
35
+ //#region src/definition/tooling/definition-source-types.d.ts
36
+ /**
37
+ * @experimental The selected sources, exactly as a definition report carries
38
+ * them. Defined from the stored report type so the two cannot disagree.
39
+ */
40
+ type DefinitionSourceSet = DefinitionCheckReport["sourceSet"];
41
+ /** @experimental Where the selected source list came from. */
42
+ type DefinitionSourceOrigin = DefinitionSourceSet["origin"];
43
+ /**
44
+ * @experimental The loader's one substitutable dependency: something that
45
+ * turns a package-relative TypeScript path into a module namespace. Codegen
46
+ * supplies a Vite environment; a build can supply its own module graph.
47
+ */
48
+ interface TypeScriptSourceImportInterface {
49
+ importModule(request: {
50
+ readonly packageRoot: string;
51
+ readonly specifier: `./${string}`;
52
+ readonly packageRevision: Sha256Digest;
53
+ readonly signal?: AbortSignal;
54
+ }): Promise<Readonly<Record<string, unknown>>>;
55
+ disposeRevision?(packageRevision?: Sha256Digest): Promise<void> | void;
56
+ }
57
+ /** @experimental */
58
+ type DefinitionSourceSelectionRequest = {
59
+ readonly configFile?: string;
60
+ readonly allowMissingConfig?: boolean;
61
+ };
62
+ /** @experimental */
63
+ type DefinitionSourceLoadRequest = DefinitionSourceSelectionRequest & {
64
+ /**
65
+ * Binds the imported bytes this load may reuse. A definition digest is not
66
+ * enough: editing a reducer helper leaves every definition digest unchanged.
67
+ */
68
+ readonly packageRevision: Sha256Digest;
69
+ readonly signal?: AbortSignal;
70
+ };
71
+ /** @experimental A selection, resolved without importing anything. */
72
+ type DefinitionSourceResolution = {
73
+ readonly packageRoot: string;
74
+ readonly sourceSet: DefinitionSourceSet;
75
+ readonly diagnostics: readonly DefinitionDiagnostic[];
76
+ } & ({
77
+ readonly status: "ready" | "failed";
78
+ readonly skipReason?: never;
79
+ } | {
80
+ readonly status: "skipped";
81
+ readonly skipReason: DefinitionCheckSkipReason;
82
+ });
83
+ /** @experimental One value the traversal recognized, and where it was found. */
84
+ type LoadedDefinition<TValue> = {
85
+ readonly source: DefinitionSource;
86
+ readonly path: DefinitionPath;
87
+ readonly value: TValue;
88
+ };
89
+ /** @experimental */
90
+ type LoadedDefinitionSet = DefinitionSourceResolution & {
91
+ readonly documentModels: readonly LoadedDefinition<DocumentModelModule>[];
92
+ readonly upgradeManifests: readonly LoadedDefinition<UpgradeManifest<readonly number[]>>[];
93
+ };
94
+ //#endregion
95
+ //#region src/definition/tooling/definition-source-loader.d.ts
96
+ /**
97
+ * @experimental Imports the selected definition sources and finds the
98
+ * materialized document models, families and upgrade manifests they export.
99
+ * It folds aliases, reports two values that claim one `documentType@version`,
100
+ * and returns everything sorted by source, so neither config order nor
101
+ * import completion order changes a result. Validity belongs to the
102
+ * adapters; registration belongs to the host.
103
+ */
104
+ export declare class DefinitionSourceLoader {
105
+ #private;
106
+ constructor(importer: TypeScriptSourceImportInterface);
107
+ resolve(request: DefinitionSourceSelectionRequest): DefinitionSourceResolution;
108
+ normalizeDefinitionSources(request: DefinitionSourceLoadRequest): Promise<LoadedDefinitionSet>;
109
+ /**
110
+ * @experimental Imports one package module through the same importer and
111
+ * package revision as the selected sources, so a module both reach is
112
+ * evaluated once. A module outside the package root is refused as an
113
+ * outside source is. Experimental: tooling uses it for the project scalars
114
+ * module while code-first projects are introduced.
115
+ */
116
+ importPackageModule(request: DefinitionSourceLoadRequest & {
117
+ readonly specifier: `./${string}`;
118
+ }): Promise<{
119
+ readonly ok: true;
120
+ readonly namespace: Readonly<Record<string, unknown>>;
121
+ } | {
122
+ readonly ok: false;
123
+ readonly diagnostics: readonly DefinitionDiagnostic[];
124
+ }>;
125
+ dispose(): Promise<void>;
126
+ }
127
+ //#endregion
128
+ //#region src/definition/tooling/definition-source-resolution.d.ts
129
+ /**
130
+ * @experimental The selection a command would load, resolved without
131
+ * importing anything and without any machine-specific path but the root.
132
+ */
133
+ export declare function resolveDefinitionSelection(request: DefinitionSourceSelectionRequest): DefinitionSourceResolution;
134
+ //#endregion
135
+ //#region src/definition/tooling/adapters/producer.d.ts
136
+ /**
137
+ * Maps a path a check reports in normalized coordinates (served data under
138
+ * `documentModel/global`, definition data under `specifications`) to where
139
+ * the source's author edits it.
140
+ */
141
+ type DefinitionRelocation = (path: DefinitionPath) => DefinitionPath;
142
+ type ProducedDefinitions = {
143
+ readonly artifacts: readonly NormalizedDocumentModelArtifact[];
144
+ readonly diagnostics: readonly DefinitionDiagnostic[];
145
+ /** By source specifier. A source authored in normalized coordinates has none. */
146
+ readonly relocations: ReadonlyMap<string, DefinitionRelocation>;
147
+ };
148
+ type DefinitionProducerInput = {
149
+ readonly loader: DefinitionSourceLoader;
150
+ readonly configFile: string;
151
+ readonly packageRevision: Sha256Digest;
152
+ readonly signal?: AbortSignal;
153
+ /** Absolute. */
154
+ readonly packageRoot: string;
155
+ /** The selected code-first sources, imported once for every producer. */
156
+ readonly loaded: LoadedDefinitionSet;
157
+ /** Absolute and inside the package; absent when the configured directory cannot be read. */
158
+ readonly documentModelsDir?: string;
159
+ };
160
+ type DefinitionProducer = (input: DefinitionProducerInput) => ProducedDefinitions | Promise<ProducedDefinitions>;
161
+ //#endregion
162
+ //#region src/definition/tooling/report/types.d.ts
163
+ /** A code-first declaration under the document models directory that no `definitionSources` entry reaches. */
164
+ type UnregisteredDefinition = {
165
+ readonly kind: "document-model";
166
+ /** `./<documentModelsDir>/<name>/`. */
167
+ readonly unit: `./${string}`;
168
+ /** The module an entry should name to register it. */
169
+ readonly specifier: `./${string}`;
170
+ };
171
+ /**
172
+ * What every registered check reads. A wider input lets a later layer
173
+ * register checks that need more, without changing the runner.
174
+ */
175
+ type DefinitionCheckInput = {
176
+ readonly sourceSet: DefinitionSourceSet;
177
+ /** Sorted by document type, version and source. */
178
+ readonly artifacts: readonly NormalizedDocumentModelArtifact[];
179
+ readonly unregistered: readonly UnregisteredDefinition[];
180
+ };
181
+ /** What the check runner and inspection need besides the check input. */
182
+ type LoadedDefinitionProject = DefinitionCheckInput & {
183
+ readonly skipReason?: DefinitionCheckSkipReason;
184
+ /** Load and adapter diagnostics, with package-relative text. */
185
+ readonly diagnostics: readonly DefinitionDiagnostic[];
186
+ /** By source specifier: where a check's normalized path sits in that source. */
187
+ readonly relocations?: ReadonlyMap<string, DefinitionRelocation>;
188
+ };
189
+ //#endregion
190
+ //#region src/definition/tooling/check/types.d.ts
191
+ /** One named check over normalized artifacts. It reports normalized paths. */
192
+ type DefinitionCheck<TInput extends DefinitionCheckInput = DefinitionCheckInput> = {
193
+ readonly name: string;
194
+ readonly run: (input: TInput) => readonly DefinitionDiagnostic[] | Promise<readonly DefinitionDiagnostic[]>;
195
+ };
196
+ //#endregion
197
+ //#region src/definition/tooling/check/check-project-definitions.d.ts
198
+ /**
199
+ * @experimental Runs every check over a loaded project and builds the stored
200
+ * check report with the project's load diagnostics. `definitions` adds
201
+ * inventory entries a caller checked itself. Experimental while code-first
202
+ * projects are introduced.
203
+ */
204
+ export declare function checkProjectDefinitions<TInput extends DefinitionCheckInput = DefinitionCheckInput>(project: LoadedDefinitionProject & TInput, options?: {
205
+ readonly checks?: readonly DefinitionCheck<TInput>[];
206
+ readonly definitions?: DefinitionCheckReport["definitions"];
207
+ }): Promise<DefinitionCheckReport>;
208
+ //#endregion
209
+ //#region src/definition/tooling/report/status.d.ts
210
+ type DefinitionStatus = DefinitionCheckReport["status"];
211
+ //#endregion
212
+ //#region src/definition/tooling/inspect/types.d.ts
213
+ /**
214
+ * @experimental One served version of a family, as `ph model inspect` prints
215
+ * it. Experimental while code-first projects are introduced.
216
+ */
217
+ type DocumentModelInspection = {
218
+ readonly version: number;
219
+ readonly source: DefinitionSource;
220
+ readonly scopes: {
221
+ readonly global: string;
222
+ readonly local: string | null;
223
+ };
224
+ readonly modules: readonly {
225
+ readonly key: string;
226
+ readonly name: string;
227
+ readonly operations: readonly {
228
+ readonly key: string;
229
+ readonly name: string | null;
230
+ readonly actionType: string;
231
+ readonly scope: "global" | "local";
232
+ readonly input: string | null;
233
+ readonly errors: readonly {
234
+ readonly key: string;
235
+ readonly code: string | null;
236
+ }[];
237
+ }[];
238
+ }[];
239
+ readonly scalars: readonly {
240
+ readonly name: string;
241
+ readonly implementation: string;
242
+ }[];
243
+ readonly types: readonly string[];
244
+ };
245
+ /**
246
+ * @experimental One definition and the versions it serves. Every version
247
+ * carries the whole history, so the digest, name and compatibility belong to
248
+ * the family, not to a version. Experimental while code-first projects are
249
+ * introduced.
250
+ */
251
+ type DocumentModelFamilyInspection = {
252
+ readonly documentType: string;
253
+ readonly name: string;
254
+ readonly extension: string;
255
+ readonly digest: Sha256Digest;
256
+ readonly compatibility: DocumentModelDefinition["compatibility"];
257
+ readonly versions: readonly DocumentModelInspection[];
258
+ };
259
+ /**
260
+ * @experimental What `ph model inspect --json` prints: deterministic, package
261
+ * relative, and diffable between releases. Experimental while code-first
262
+ * projects are introduced.
263
+ */
264
+ type DefinitionInspectionReport = {
265
+ readonly kind: "powerhouse.definition-inspection";
266
+ readonly formatVersion: 1;
267
+ readonly status: DefinitionStatus;
268
+ readonly sourceSet: DefinitionSourceSet;
269
+ readonly families: readonly DocumentModelFamilyInspection[];
270
+ readonly diagnostics: readonly DefinitionDiagnostic[];
271
+ /** Present only when a selection matched exactly one model. */
272
+ readonly definition?: DocumentModelDefinition;
273
+ };
274
+ /** @experimental */
275
+ type DefinitionInspectionSelection = {
276
+ readonly documentType: string;
277
+ readonly version: number;
278
+ };
279
+ //#endregion
280
+ //#region src/definition/tooling/inspect/inspect-project-definitions.d.ts
281
+ /**
282
+ * @experimental Describes the loaded models without running checks. With a
283
+ * selection it answers for that model only, and adds its full definition
284
+ * when exactly one model serves it. Experimental while code-first projects
285
+ * are introduced.
286
+ */
287
+ export declare function inspectProjectDefinitions(project: LoadedDefinitionProject, options?: {
288
+ readonly selection?: DefinitionInspectionSelection;
289
+ }): DefinitionInspectionReport;
290
+ //#endregion
291
+ //#region src/definition/tooling/project/project-definitions.d.ts
292
+ /**
293
+ * @experimental A package's document models, loaded once and read by both
294
+ * `ph model check` and `ph model inspect`. Experimental while code-first
295
+ * projects are introduced.
296
+ */
297
+ type ProjectDefinitions = LoadedDefinitionProject & {
298
+ /** Absolute. No report carries it. */
299
+ readonly packageRoot: string;
300
+ };
301
+ /**
302
+ * @experimental Loads the selected code-first sources and the package's stored
303
+ * schema-first models, and scans for code-first declarations no source
304
+ * reaches. Artifacts and diagnostics are sorted and package relative.
305
+ * `producers` replaces the default readers. `importedFiles` names the
306
+ * absolute paths of every module the loader's import of a selected
307
+ * specifier evaluated, so reach follows whatever the importer resolved.
308
+ * Experimental while code-first projects are introduced.
309
+ */
310
+ export declare function loadProjectDefinitions(request: {
311
+ readonly loader: DefinitionSourceLoader;
312
+ readonly configFile: string;
313
+ readonly packageRevision: Sha256Digest;
314
+ readonly signal?: AbortSignal;
315
+ readonly producers?: readonly DefinitionProducer[];
316
+ readonly importedFiles: (specifier: string) => readonly string[];
317
+ }): Promise<ProjectDefinitions>;
318
+ //#endregion
319
+ export type { DefinitionInspectionReport, DefinitionSourceLoadRequest, DefinitionSourceOrigin, DefinitionSourceResolution, DefinitionSourceSelectionRequest, DefinitionSourceSet, DocumentModelFamilyInspection, DocumentModelInspection, LoadedDefinition, LoadedDefinitionSet, NormalizedDocumentModelArtifact, NormalizedDocumentModelResult, ProjectDefinitions, TypeScriptSourceImportInterface };
320
+ export {};
321
+ //# 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/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/report/status.ts","../src/definition/tooling/inspect/types.ts","../src/definition/tooling/inspect/inspect-project-definitions.ts","../src/definition/tooling/project/project-definitions.ts"],"mappings":";;;wBAuQgB,2BACd,YAAY;;;;;;;KC3PF;WACD;WACA,QAAQ;WACR;WAEA;WAEA,YAAY;WAEZ,QAAQ;WAER,eAAe;;;KAId;WACD,oBAAoB;WAEpB,iBAAiB;WACjB,sBAAsB;;;;;;;;;wBC2NjB,kCACd,gBACA,QAAQ,mBACP;;;;;;;KC/OS,sBAAsB;;KAGtB,yBAAyB;;;;;;UAOpB;EACf,aAAa;aACF;aACA;aACA,iBAAiB;aACjB,SAAS;MAChB,QAAQ,SAAS;EAErB,iBAAiB,kBAAkB,eAAe;;;KAIxC;WACD;WAEA;;;KAIC,8BAA8B;;;;;WAK/B,iBAAiB;WACjB,SAAS;;;KAIR;WACD;WACA,WAAW;WACX,sBAAsB;;WAElB;WAAqC;;WAErC;WACA,YAAY;;;KAKf,iBAAiB;WAClB,QAAQ;WAER,MAAM;WACN,OAAO;;;KAIN,sBAAsB;WACvB,yBAAyB,iBAAiB;WAC1C,2BAA2B,iBAClC;;;;;;;;;;;;qBCqfS;;EAQX,YAAY,UAAU;EAItB,QACE,SAAS,mCACR;EAIG,2BACJ,SAAS,8BACR,QAAQ;;;;;;;;EA6EL,oBACJ,SAAS;aACE;MAEV;aAEY;aACA,WAAW,SAAS;;aAGpB;aACA,sBAAsB;;EAuB/B,WAAW;;;;;;;;wBC7IH,2BACd,SAAS,mCACR;;;;;;;;KC7iBS,wBAAwB,MAAM,mBAAmB;KAEjD;WACD,oBAAoB;WACpB,sBAAsB;;WAEtB,aAAa,oBAAoB;;KAGhC;WACD,QAAQ;WACR;WACA,iBAAiB;WACjB,SAAS;;WAET;;WAEA,QAAQ;;WAER;;KAGC,sBACV,OAAO,4BACJ,sBAAsB,QAAQ;;;;KC7BvB;WACD;;WAEA;;WAEA;;;;;;KAOC;WACD,WAAW;;WAEX,oBAAoB;WACpB,uBAAuB;;;KAItB,0BAA0B;WAC3B,aAAa;;WAEb,sBAAsB;;WAEtB,cAAc,oBAAoB;;;;;KC9BjC,gBACV,eAAe,uBAAuB;WAE7B;WACA,MACP,OAAO,oBAEI,yBACT,iBAAiB;;;;;;;;;;wBCkDD,wBACpB,eAAe,uBAAuB,sBAEtC,SAAS,0BAA0B,QACnC;WACW,kBAAkB,gBAAgB;WAClC,cAAc;IAExB,QAAQ;;;KC5DC,mBAAmB;;;;;;;KCGnB;WACD;WACA,QAAQ;WACR;aACE;aACA;;WAEF;aACE;aACA;aACA;eACE;eACA;eACA;eACA;eACA;eACA;iBACE;iBACA;;;;WAIN;aACE;aACA;;WAEF;;;;;;;;KASC;WACD;WACA;WACA;WACA,QAAQ;WACR,eAAe;WACf,mBAAmB;;;;;;;KAQlB;WACD;WACA;WACA,QAAQ;WACR,WAAW;WACX,mBAAmB;WACnB,sBAAsB;;WAEtB,aAAa;;;KAIZ;WACD;WACA;;;;;;;;;;wBC+CK,0BACd,SAAS,yBACT;WAAoB,YAAY;IAC/B;;;;;;;;KCjGS,qBAAqB;;WAEtB;;;;;;;;;;;wBAyJW,uBAAuB;WAClC,QAAQ;WACR;WACA,iBAAiB;WACjB,SAAS;WACT,qBAAqB;WACrB,gBAAgB;IACvB,QAAQ"}