@graphql-markdown/core 1.24.0 → 1.25.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.d.ts +3 -2
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +18 -4
- package/dist/events/render-type-entities.d.ts +6 -0
- package/dist/events/render-type-entities.d.ts.map +1 -1
- package/dist/generator.d.ts.map +1 -1
- package/dist/generator.js +45 -15
- package/dist/graphql-config.js +2 -2
- package/dist/renderer.d.ts +12 -2
- package/dist/renderer.d.ts.map +1 -1
- package/dist/renderer.js +28 -2
- package/dist/telemetry.d.ts +46 -0
- package/dist/telemetry.d.ts.map +1 -0
- package/dist/telemetry.js +162 -0
- package/package.json +12 -10
package/dist/config.d.ts
CHANGED
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
* @packageDocumentation
|
|
17
17
|
*/
|
|
18
18
|
import type { CliOptions, ConfigDocOptions, ConfigOptions, ConfigPrintTypeOptions, CustomDirective, Decorators, DirectiveName, GroupByDirectiveOptions, Maybe, Options, TypeDiffMethod, TypeHierarchyObjectType, TypeHierarchyType, TypeHierarchyValueType } from "@graphql-markdown/types";
|
|
19
|
+
import type { BuildConfigContext } from "./telemetry";
|
|
19
20
|
/**
|
|
20
21
|
* Type hierarchy options for organizing schema documentation.
|
|
21
22
|
*
|
|
@@ -97,7 +98,7 @@ export declare const DEFAULT_HIERARCHY: {
|
|
|
97
98
|
* @public
|
|
98
99
|
* @see {@link Options} for the complete configuration interface
|
|
99
100
|
*/
|
|
100
|
-
export declare const DEFAULT_OPTIONS: Readonly<Pick<ConfigOptions, "customDirective" | "decorators" | "groupByDirective" | "loaders" | "outputAdapter"> & Required<Omit<ConfigOptions, "customDirective" | "decorators" | "formatter" | "groupByDirective" | "loaders" | "mdxParser" | "outputAdapter" | "printTypeOptions">>> & {
|
|
101
|
+
export declare const DEFAULT_OPTIONS: Readonly<Pick<ConfigOptions, "customDirective" | "decorators" | "groupByDirective" | "loaders" | "outputAdapter"> & Required<Omit<ConfigOptions, "customDirective" | "decorators" | "formatter" | "groupByDirective" | "loaders" | "mdxParser" | "outputAdapter" | "printTypeOptions" | "telemetry">>> & {
|
|
101
102
|
printTypeOptions: Required<Omit<ConfigPrintTypeOptions, "exampleSection" | "hierarchy">> & {
|
|
102
103
|
exampleSection: ConfigPrintTypeOptions["exampleSection"];
|
|
103
104
|
hierarchy: Required<Pick<TypeHierarchyObjectType, TypeHierarchy.API>>;
|
|
@@ -321,5 +322,5 @@ export declare const getDecoratorsOption: (decorators: Maybe<Decorators>) => May
|
|
|
321
322
|
*/
|
|
322
323
|
export declare const parseGroupByOption: (groupOptions: unknown) => Maybe<GroupByDirectiveOptions>;
|
|
323
324
|
export declare const parseHomepageOption: (cliHomepage: Maybe<string | false>, configHomepage: Maybe<string | false>) => Maybe<string>;
|
|
324
|
-
export declare const buildConfig: (configFileOpts: Maybe<ConfigOptions>, cliOpts?: Maybe<CliOptions>, id?: Maybe<string
|
|
325
|
+
export declare const buildConfig: (configFileOpts: Maybe<ConfigOptions>, cliOpts?: Maybe<CliOptions>, id?: Maybe<string>, context?: BuildConfigContext) => Promise<Options>;
|
|
325
326
|
//# sourceMappingURL=config.d.ts.map
|
package/dist/config.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACtB,eAAe,EAGf,UAAU,EACV,aAAa,EACb,uBAAuB,EACvB,KAAK,EACL,OAAO,EAGP,cAAc,EACd,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
|
package/dist/config.js
CHANGED
|
@@ -24,6 +24,7 @@ const deepmerge_1 = require("@fastify/deepmerge");
|
|
|
24
24
|
const logger_1 = require("@graphql-markdown/logger");
|
|
25
25
|
const printer_legacy_1 = require("@graphql-markdown/printer-legacy");
|
|
26
26
|
const graphql_config_1 = require("./graphql-config");
|
|
27
|
+
const telemetry_1 = require("./telemetry");
|
|
27
28
|
const patterns_1 = require("./const/patterns");
|
|
28
29
|
const validation_1 = require("./directives/validation");
|
|
29
30
|
const builder_1 = require("./options/builder");
|
|
@@ -634,11 +635,14 @@ const getDecoratorsOption = (decorators) => {
|
|
|
634
635
|
return decorators;
|
|
635
636
|
};
|
|
636
637
|
exports.getDecoratorsOption = getDecoratorsOption;
|
|
638
|
+
const resolveDeprecatedOption = (cliOpts, configOptions) => {
|
|
639
|
+
return (cliOpts?.deprecated ??
|
|
640
|
+
configOptions?.deprecated ??
|
|
641
|
+
exports.DEFAULT_OPTIONS.printTypeOptions.deprecated).toLocaleLowerCase();
|
|
642
|
+
};
|
|
637
643
|
const getPrintTypeOptions = (cliOpts, configOptions) => {
|
|
638
644
|
return {
|
|
639
|
-
deprecated: (cliOpts
|
|
640
|
-
configOptions?.deprecated ??
|
|
641
|
-
exports.DEFAULT_OPTIONS.printTypeOptions.deprecated).toLocaleLowerCase(),
|
|
645
|
+
deprecated: resolveDeprecatedOption(cliOpts, configOptions),
|
|
642
646
|
exampleSection: configOptions?.exampleSection ??
|
|
643
647
|
exports.DEFAULT_OPTIONS.printTypeOptions.exampleSection,
|
|
644
648
|
parentTypePrefix: resolveNegatableOption(cliOpts?.noParentType, configOptions?.parentTypePrefix, exports.DEFAULT_OPTIONS.printTypeOptions.parentTypePrefix),
|
|
@@ -703,7 +707,7 @@ const parseHomepageOption = (cliHomepage, configHomepage) => {
|
|
|
703
707
|
return exports.DEFAULT_OPTIONS.homepage;
|
|
704
708
|
};
|
|
705
709
|
exports.parseHomepageOption = parseHomepageOption;
|
|
706
|
-
const buildConfig = async (configFileOpts, cliOpts, id = "default") => {
|
|
710
|
+
const buildConfig = async (configFileOpts, cliOpts, id = "default", context) => {
|
|
707
711
|
cliOpts ??= {};
|
|
708
712
|
const graphqlConfig = await (0, graphql_config_1.loadConfiguration)(id);
|
|
709
713
|
(0, exports.parseDeprecatedPrintTypeOptions)(cliOpts, {
|
|
@@ -748,6 +752,15 @@ const buildConfig = async (configFileOpts, cliOpts, id = "default") => {
|
|
|
748
752
|
.addFromCli(cliOpts.tmp, "tmpDir")
|
|
749
753
|
.build();
|
|
750
754
|
const printTypeOptions = getPrintTypeOptions(cliOpts, config.printTypeOptions);
|
|
755
|
+
const telemetryReport = {
|
|
756
|
+
configFileOpts,
|
|
757
|
+
extension: graphqlConfig,
|
|
758
|
+
cliOpts,
|
|
759
|
+
id,
|
|
760
|
+
trigger: context?.trigger,
|
|
761
|
+
};
|
|
762
|
+
// fire and forget: async, never throws nor rejects (see reportTelemetry)
|
|
763
|
+
void (0, telemetry_1.reportTelemetry)(telemetryReport);
|
|
751
764
|
return {
|
|
752
765
|
baseURL,
|
|
753
766
|
customDirective: (0, exports.getCustomDirectives)(config.customDirective, skipDocDirective),
|
|
@@ -771,6 +784,7 @@ const buildConfig = async (configFileOpts, cliOpts, id = "default") => {
|
|
|
771
784
|
printTypeOptions,
|
|
772
785
|
schemaLocation,
|
|
773
786
|
skipDocDirective,
|
|
787
|
+
telemetryContext: (0, telemetry_1.resolveTelemetryContext)(telemetryReport),
|
|
774
788
|
tmpDir,
|
|
775
789
|
};
|
|
776
790
|
};
|
|
@@ -13,18 +13,24 @@ import { DataEvent } from "@graphql-markdown/utils";
|
|
|
13
13
|
*/
|
|
14
14
|
export declare class RenderTypeEntitiesEvent extends DataEvent<{
|
|
15
15
|
baseURL: string;
|
|
16
|
+
/** Root for documentation links, as used when printing them. */
|
|
17
|
+
linkRoot?: string;
|
|
16
18
|
name: string;
|
|
17
19
|
filePath: string;
|
|
18
20
|
outputDir: string;
|
|
19
21
|
/** Destination the page was written to; use it to read the page back. */
|
|
20
22
|
outputAdapter?: OutputAdapter;
|
|
23
|
+
/** Root-level generated doc paths, known before concurrent pages are written. */
|
|
24
|
+
knownDocPaths?: ReadonlySet<string>;
|
|
21
25
|
}> {
|
|
22
26
|
constructor(data: {
|
|
23
27
|
baseURL: string;
|
|
28
|
+
linkRoot?: string;
|
|
24
29
|
name: string;
|
|
25
30
|
filePath: string;
|
|
26
31
|
outputDir: string;
|
|
27
32
|
outputAdapter?: OutputAdapter;
|
|
33
|
+
knownDocPaths?: ReadonlySet<string>;
|
|
28
34
|
}, options?: CancellableEventOptions);
|
|
29
35
|
}
|
|
30
36
|
//# sourceMappingURL=render-type-entities.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"render-type-entities.d.ts","sourceRoot":"","sources":["../../src/events/render-type-entities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,SAAS,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,aAAa,CAAC,EAAE,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"render-type-entities.d.ts","sourceRoot":"","sources":["../../src/events/render-type-entities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,SAAS,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,iFAAiF;IACjF,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACrC,CAAC;IACA,YACE,IAAI,EAAE;QACJ,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,aAAa,CAAC;QAC9B,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;KACrC,EACD,OAAO,CAAC,EAAE,uBAAuB,EAGlC;CACF"}
|
package/dist/generator.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAEV,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,WAAW,EAEX,cAAc,EAEf,MAAM,yBAAyB,CAAC;
|
|
1
|
+
{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAEV,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,WAAW,EAEX,cAAc,EAEf,MAAM,yBAAyB,CAAC;AAkEjC;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,cACb,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,KACrC,OAAO,CAAC,OAAO,CAYjB,CAAC;AAiBF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,aACzB,OAAO,gBACJ,MAAM,KACnB,CAAC,GAAG,SAmBN,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,cACzB,OAAO,SACX,QAAQ,KACd,OAAO,CAAC,SAAS,CAAC,GAAG,SA+CvB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,mBACZ,MAAM,eACT,KAAK,CAAC,YAAY,CAAC,KAC/B,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAY9B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,sBAAsB,WACzB,aAAa,kBACL,MAAM,cACV,KAAK,CAAC,cAAc,CAAC,UACzB,MAAM,KACb,OAAO,CAAC,OAAO,CAWjB,CAAC;AAEF;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,4BAA4B,qBACrB,KAAK,CAAC,aAAa,GAAG,aAAa,EAAE,CAAC,oBACtC,KAAK,CAAC,aAAa,GAAG,aAAa,EAAE,CAAC,UAChD,aAAa,KACpB,gBAAgB,EAAE,EAsBpB,CAAC;AAmRF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,YACvB,gBAAgB,KACxB,OAAO,CAAC,IAAI,CAsBd,CAAC"}
|
package/dist/generator.js
CHANGED
|
@@ -46,6 +46,7 @@ const renderer_1 = require("./renderer");
|
|
|
46
46
|
const event_emitter_1 = require("./event-emitter");
|
|
47
47
|
const events_1 = require("./events");
|
|
48
48
|
const event_handlers_1 = require("./event-handlers");
|
|
49
|
+
const telemetry_1 = require("./telemetry");
|
|
49
50
|
/**
|
|
50
51
|
* Supported file extensions for generated documentation files.
|
|
51
52
|
*
|
|
@@ -265,21 +266,8 @@ const resolveSkipAndOnlyDirectives = (onlyDocDirective, skipDocDirective, schema
|
|
|
265
266
|
});
|
|
266
267
|
};
|
|
267
268
|
exports.resolveSkipAndOnlyDirectives = resolveSkipAndOnlyDirectives;
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
*
|
|
271
|
-
* This function coordinates the entire documentation generation process:
|
|
272
|
-
* - Loads and validates the schema
|
|
273
|
-
* - Checks for schema changes if diffing is enabled
|
|
274
|
-
* - Processes directives and groups
|
|
275
|
-
* - Initializes printers and renderers
|
|
276
|
-
* - Generates markdown files
|
|
277
|
-
*
|
|
278
|
-
* @param options - Complete configuration for the documentation generation
|
|
279
|
-
* @returns Promise that resolves when documentation is fully generated
|
|
280
|
-
*/
|
|
281
|
-
const generateDocFromSchema = async (options) => {
|
|
282
|
-
const start = process.hrtime.bigint();
|
|
269
|
+
// fallow-ignore-next-line complexity
|
|
270
|
+
const runGeneration = async (options, start, outcome) => {
|
|
283
271
|
await (0, logger_1.default)(options.loggerModule);
|
|
284
272
|
const mdxModule = await (0, exports.loadMDXModule)(options.formatter);
|
|
285
273
|
// Register MDX lifecycle event handlers if mdxModule loaded successfully
|
|
@@ -301,6 +289,7 @@ const generateDocFromSchema = async (options) => {
|
|
|
301
289
|
}));
|
|
302
290
|
if (!schema) {
|
|
303
291
|
(0, logger_1.log)(`Failed to load GraphQL schema from location "${(0, utils_1.toString)(schemaLocation)}".`, "error");
|
|
292
|
+
outcome.noSchema = true;
|
|
304
293
|
return;
|
|
305
294
|
}
|
|
306
295
|
await events.emitAsync(events_1.DiffEvents.BEFORE_CHECK, new events_1.DiffCheckEvent({
|
|
@@ -365,6 +354,7 @@ const generateDocFromSchema = async (options) => {
|
|
|
365
354
|
printer,
|
|
366
355
|
outputDir,
|
|
367
356
|
baseURL,
|
|
357
|
+
linkRoot,
|
|
368
358
|
group: groups,
|
|
369
359
|
prettify,
|
|
370
360
|
docOptions: {
|
|
@@ -378,6 +368,7 @@ const generateDocFromSchema = async (options) => {
|
|
|
378
368
|
});
|
|
379
369
|
// Pre-collect all categories before rendering to ensure consistent positions
|
|
380
370
|
renderer.preCollectCategories(Object.keys(rootTypes));
|
|
371
|
+
renderer.preCollectGeneratedDocPaths(rootTypes);
|
|
381
372
|
const beforeRenderRootTypesEvent = new events_1.RenderRootTypesEvent({
|
|
382
373
|
rootTypes,
|
|
383
374
|
});
|
|
@@ -386,6 +377,7 @@ const generateDocFromSchema = async (options) => {
|
|
|
386
377
|
const typeName = name;
|
|
387
378
|
return renderer.renderRootTypes(typeName, rootTypes[typeName]);
|
|
388
379
|
}));
|
|
380
|
+
outcome.pages = pages.flat().length;
|
|
389
381
|
const afterRenderRootTypesEvent = new events_1.RenderRootTypesEvent({
|
|
390
382
|
rootTypes,
|
|
391
383
|
});
|
|
@@ -410,6 +402,7 @@ const generateDocFromSchema = async (options) => {
|
|
|
410
402
|
// without this a failure to write mdBook's SUMMARY.md is dropped, and the
|
|
411
403
|
// success line below claims the documentation is complete
|
|
412
404
|
(0, renderer_1.logHandlerErrors)(events_1.RenderFilesEvents.AFTER_RENDER, renderFilesErrors);
|
|
405
|
+
outcome.postError = renderFilesErrors[0];
|
|
413
406
|
const duration = (Number(process.hrtime.bigint() - start) / NS_PER_SEC).toFixed(SEC_DECIMALS);
|
|
414
407
|
// a formatter that could not finish its output must not be reported as a
|
|
415
408
|
// success: mdBook cannot build without the SUMMARY.md written by that hook
|
|
@@ -421,4 +414,41 @@ const generateDocFromSchema = async (options) => {
|
|
|
421
414
|
}
|
|
422
415
|
(0, logger_1.log)(`${pages.flat().length} pages generated in ${duration}s from schema "${(0, utils_1.toString)(schemaLocation)}".`);
|
|
423
416
|
};
|
|
417
|
+
/**
|
|
418
|
+
* Main entry point for generating Markdown documentation from a GraphQL schema.
|
|
419
|
+
*
|
|
420
|
+
* This function coordinates the entire documentation generation process:
|
|
421
|
+
* - Loads and validates the schema
|
|
422
|
+
* - Checks for schema changes if diffing is enabled
|
|
423
|
+
* - Processes directives and groups
|
|
424
|
+
* - Initializes printers and renderers
|
|
425
|
+
* - Generates markdown files
|
|
426
|
+
*
|
|
427
|
+
* @param options - Complete configuration for the documentation generation
|
|
428
|
+
* @returns Promise that resolves when documentation is fully generated
|
|
429
|
+
*/
|
|
430
|
+
const generateDocFromSchema = async (options) => {
|
|
431
|
+
const start = process.hrtime.bigint();
|
|
432
|
+
const outcome = { pages: 0, noSchema: false };
|
|
433
|
+
let failed = false;
|
|
434
|
+
let thrown;
|
|
435
|
+
try {
|
|
436
|
+
await runGeneration(options, start, outcome);
|
|
437
|
+
}
|
|
438
|
+
catch (error) {
|
|
439
|
+
failed = true;
|
|
440
|
+
thrown = error;
|
|
441
|
+
throw error;
|
|
442
|
+
}
|
|
443
|
+
finally {
|
|
444
|
+
void (0, telemetry_1.reportGeneration)({
|
|
445
|
+
telemetry: options.telemetryContext,
|
|
446
|
+
pages: outcome.pages,
|
|
447
|
+
durationMs: Number(process.hrtime.bigint() - start) / 1e6,
|
|
448
|
+
error: failed ? (thrown ?? new Error("unknown")) : undefined,
|
|
449
|
+
noSchema: outcome.noSchema,
|
|
450
|
+
postError: outcome.postError,
|
|
451
|
+
});
|
|
452
|
+
}
|
|
453
|
+
};
|
|
424
454
|
exports.generateDocFromSchema = generateDocFromSchema;
|
package/dist/graphql-config.js
CHANGED
|
@@ -112,8 +112,8 @@ const loadConfiguration = async (id, options, { throwOnMissing, throwOnEmpty } =
|
|
|
112
112
|
try {
|
|
113
113
|
graphQLConfig = await import("graphql-config");
|
|
114
114
|
}
|
|
115
|
-
catch {
|
|
116
|
-
(0, logger_1.log)(
|
|
115
|
+
catch (error) {
|
|
116
|
+
(0, logger_1.log)(`Cannot load module 'graphql-config': ${error.message}`);
|
|
117
117
|
return undefined;
|
|
118
118
|
}
|
|
119
119
|
const config = await graphQLConfig.loadConfig({
|
package/dist/renderer.d.ts
CHANGED
|
@@ -83,6 +83,8 @@ export interface RendererOptions {
|
|
|
83
83
|
outputDir: string;
|
|
84
84
|
/** Base URL for the documentation */
|
|
85
85
|
baseURL: string;
|
|
86
|
+
/** Root for documentation links, forwarded to render hooks */
|
|
87
|
+
linkRoot?: string;
|
|
86
88
|
/** Optional grouping configuration for schema entities */
|
|
87
89
|
group: Maybe<SchemaEntitiesGroupMap>;
|
|
88
90
|
/** Whether to format the generated markdown */
|
|
@@ -109,6 +111,7 @@ export declare class Renderer {
|
|
|
109
111
|
readonly group: Maybe<SchemaEntitiesGroupMap>;
|
|
110
112
|
readonly outputDir: string;
|
|
111
113
|
readonly baseURL: string;
|
|
114
|
+
readonly linkRoot?: string;
|
|
112
115
|
readonly prettify: boolean;
|
|
113
116
|
readonly options: Maybe<RendererDocOptions>;
|
|
114
117
|
readonly mdxExtension: string;
|
|
@@ -116,13 +119,14 @@ export declare class Renderer {
|
|
|
116
119
|
private readonly printer;
|
|
117
120
|
private readonly rootLevelPositionManager;
|
|
118
121
|
private readonly categoryPositionManager;
|
|
122
|
+
private readonly knownDocPaths;
|
|
119
123
|
/**
|
|
120
124
|
* Creates a new Renderer instance.
|
|
121
125
|
*
|
|
122
126
|
* @param options - Renderer construction options
|
|
123
127
|
* @example
|
|
124
128
|
*/
|
|
125
|
-
constructor({ printer, outputDir, baseURL, group, prettify, docOptions, mdxExtension, outputAdapter, }: RendererOptions);
|
|
129
|
+
constructor({ printer, outputDir, baseURL, linkRoot, group, prettify, docOptions, mdxExtension, outputAdapter, }: RendererOptions);
|
|
126
130
|
/**
|
|
127
131
|
* Generates an index metafile for a category directory if MDX support is available.
|
|
128
132
|
*
|
|
@@ -172,6 +176,12 @@ export declare class Renderer {
|
|
|
172
176
|
* @example
|
|
173
177
|
*/
|
|
174
178
|
renderTypeEntities(dirPath: string, name: string, type: unknown, operationNamespaceParts?: string[], entity?: SchemaEntity): Promise<Maybe<Category>>;
|
|
179
|
+
/**
|
|
180
|
+
* Pre-collects root-level generated document paths for flat hierarchy.
|
|
181
|
+
*
|
|
182
|
+
* @param rootTypes - Map of schema entity names to their generated types
|
|
183
|
+
*/
|
|
184
|
+
preCollectGeneratedDocPaths(rootTypes: object): void;
|
|
175
185
|
/**
|
|
176
186
|
* Pre-collects all category names that will be generated during rendering.
|
|
177
187
|
* This allows the position manager to assign consistent positions before
|
|
@@ -277,5 +287,5 @@ export declare class Renderer {
|
|
|
277
287
|
* });
|
|
278
288
|
* ```
|
|
279
289
|
*/
|
|
280
|
-
export declare const getRenderer: ({ printer, outputDir, baseURL, group, prettify, docOptions, mdxExtension, outputAdapter, }: RendererOptions) => Promise<InstanceType<typeof Renderer>>;
|
|
290
|
+
export declare const getRenderer: ({ printer, outputDir, baseURL, linkRoot, group, prettify, docOptions, mdxExtension, outputAdapter, }: RendererOptions) => Promise<InstanceType<typeof Renderer>>;
|
|
281
291
|
//# sourceMappingURL=renderer.d.ts.map
|
package/dist/renderer.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,QAAQ,EAER,KAAK,EAEL,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,EAGb,MAAM,yBAAyB,CAAC;AA0FjC;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,oBAAoB,CAG5C,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,iBAAiB,SACtB,OAAO,WACJ,KAAK,CAAC,oBAAoB,GAAG,OAAO,CAAC,KAC7C,MAMF,CAAC;AA6CF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAoGD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,cAAe,MAAM,UAAU,KAAK,EAAE,KAAG,IAIrE,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,OAAO,EAAE,OAAO,QAAQ,CAAC;IACzB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,KAAK,EAAE,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACrC,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,UAAU,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACtC,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;;;;;GAUG;AAGH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAEtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAA0B;IACnE,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAA0B;
|
|
1
|
+
{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"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"}
|
package/dist/renderer.js
CHANGED
|
@@ -278,6 +278,7 @@ class Renderer {
|
|
|
278
278
|
group;
|
|
279
279
|
outputDir;
|
|
280
280
|
baseURL;
|
|
281
|
+
linkRoot;
|
|
281
282
|
prettify;
|
|
282
283
|
options;
|
|
283
284
|
mdxExtension;
|
|
@@ -286,17 +287,21 @@ class Renderer {
|
|
|
286
287
|
printer;
|
|
287
288
|
rootLevelPositionManager;
|
|
288
289
|
categoryPositionManager;
|
|
290
|
+
knownDocPaths = new Set();
|
|
289
291
|
/**
|
|
290
292
|
* Creates a new Renderer instance.
|
|
291
293
|
*
|
|
292
294
|
* @param options - Renderer construction options
|
|
293
295
|
* @example
|
|
294
296
|
*/
|
|
295
|
-
constructor({ printer, outputDir, baseURL, group, prettify, docOptions, mdxExtension, outputAdapter = undefined, }) {
|
|
297
|
+
constructor({ printer, outputDir, baseURL, linkRoot, group, prettify, docOptions, mdxExtension, outputAdapter = undefined, }) {
|
|
296
298
|
this.printer = printer;
|
|
297
299
|
this.group = group;
|
|
298
300
|
this.outputDir = outputDir;
|
|
299
301
|
this.baseURL = baseURL;
|
|
302
|
+
if (linkRoot !== undefined) {
|
|
303
|
+
this.linkRoot = linkRoot;
|
|
304
|
+
}
|
|
300
305
|
this.prettify = prettify;
|
|
301
306
|
this.options = docOptions;
|
|
302
307
|
this.mdxExtension = mdxExtension;
|
|
@@ -546,10 +551,12 @@ class Renderer {
|
|
|
546
551
|
const events = (0, event_emitter_1.getEvents)();
|
|
547
552
|
const event = new events_1.RenderTypeEntitiesEvent({
|
|
548
553
|
baseURL: this.baseURL,
|
|
554
|
+
...(this.linkRoot !== undefined && { linkRoot: this.linkRoot }),
|
|
549
555
|
name,
|
|
550
556
|
filePath,
|
|
551
557
|
outputDir: this.outputDir,
|
|
552
558
|
outputAdapter: this.outputAdapter,
|
|
559
|
+
knownDocPaths: this.knownDocPaths,
|
|
553
560
|
});
|
|
554
561
|
const { errors } = await events.emitAsync(events_1.RenderTypeEntitiesEvents.AFTER_RENDER, event);
|
|
555
562
|
(0, exports.logHandlerErrors)(events_1.RenderTypeEntitiesEvents.AFTER_RENDER, errors);
|
|
@@ -559,6 +566,24 @@ class Renderer {
|
|
|
559
566
|
name,
|
|
560
567
|
};
|
|
561
568
|
}
|
|
569
|
+
/**
|
|
570
|
+
* Pre-collects root-level generated document paths for flat hierarchy.
|
|
571
|
+
*
|
|
572
|
+
* @param rootTypes - Map of schema entity names to their generated types
|
|
573
|
+
*/
|
|
574
|
+
preCollectGeneratedDocPaths(rootTypes) {
|
|
575
|
+
if (!isHierarchy(this.options, config_1.TypeHierarchy.FLAT)) {
|
|
576
|
+
return;
|
|
577
|
+
}
|
|
578
|
+
for (const [entity, type] of Object.entries(rootTypes)) {
|
|
579
|
+
if (typeof type !== "object" || type === null) {
|
|
580
|
+
continue;
|
|
581
|
+
}
|
|
582
|
+
for (const name of Object.keys(type)) {
|
|
583
|
+
this.knownDocPaths.add(`${entity}-${(0, utils_1.slugify)(name)}`);
|
|
584
|
+
}
|
|
585
|
+
}
|
|
586
|
+
}
|
|
562
587
|
/**
|
|
563
588
|
* Pre-collects all category names that will be generated during rendering.
|
|
564
589
|
* This allows the position manager to assign consistent positions before
|
|
@@ -816,7 +841,7 @@ exports.Renderer = Renderer;
|
|
|
816
841
|
* });
|
|
817
842
|
* ```
|
|
818
843
|
*/
|
|
819
|
-
const getRenderer = async ({ printer, outputDir, baseURL, group, prettify, docOptions, mdxExtension, outputAdapter = undefined, }) => {
|
|
844
|
+
const getRenderer = async ({ printer, outputDir, baseURL, linkRoot, group, prettify, docOptions, mdxExtension, outputAdapter = undefined, }) => {
|
|
820
845
|
const adapter = outputAdapter ?? utils_1.fsOutputAdapter;
|
|
821
846
|
// Optional on the interface: a destination with no directory concept (an
|
|
822
847
|
// object store, a CMS collection) has nothing to prepare.
|
|
@@ -825,6 +850,7 @@ const getRenderer = async ({ printer, outputDir, baseURL, group, prettify, docOp
|
|
|
825
850
|
printer,
|
|
826
851
|
outputDir,
|
|
827
852
|
baseURL,
|
|
853
|
+
...(linkRoot !== undefined && { linkRoot }),
|
|
828
854
|
group,
|
|
829
855
|
prettify,
|
|
830
856
|
docOptions,
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { CliOptions, ConfigOptions, Maybe, TelemetryTrigger } from "@graphql-markdown/types";
|
|
2
|
+
/** Internal context passed by our own entry points. */
|
|
3
|
+
export interface BuildConfigContext {
|
|
4
|
+
trigger?: TelemetryTrigger;
|
|
5
|
+
}
|
|
6
|
+
export interface TelemetryReport {
|
|
7
|
+
configFileOpts: Maybe<ConfigOptions>;
|
|
8
|
+
extension: Maybe<ConfigOptions>;
|
|
9
|
+
cliOpts: Maybe<CliOptions>;
|
|
10
|
+
id?: Maybe<string>;
|
|
11
|
+
trigger?: TelemetryTrigger;
|
|
12
|
+
}
|
|
13
|
+
/** Telemetry decision made once by `buildConfig`, reused at generation time. */
|
|
14
|
+
export interface TelemetryContext {
|
|
15
|
+
trigger?: TelemetryTrigger;
|
|
16
|
+
option?: boolean;
|
|
17
|
+
}
|
|
18
|
+
/** Outcome of a documentation generation run. */
|
|
19
|
+
export interface GenerationReport {
|
|
20
|
+
telemetry?: TelemetryContext;
|
|
21
|
+
pages: number;
|
|
22
|
+
durationMs: number;
|
|
23
|
+
/** Error thrown by the run, if any. */
|
|
24
|
+
error?: unknown;
|
|
25
|
+
/** Explicit error type, takes precedence over `error`. */
|
|
26
|
+
errorType?: string;
|
|
27
|
+
/** The run failed without throwing because the schema could not be loaded. */
|
|
28
|
+
noSchema?: boolean;
|
|
29
|
+
/** First post-processing error, when the run completed incompletely. */
|
|
30
|
+
postError?: unknown;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Resolves the telemetry opt-in and trigger from the configuration sources.
|
|
34
|
+
*/
|
|
35
|
+
export declare const resolveTelemetryContext: (report: Pick<TelemetryReport, "cliOpts" | "configFileOpts" | "extension" | "trigger">) => TelemetryContext;
|
|
36
|
+
/**
|
|
37
|
+
* Reports the resolved configuration once per distinct config and process.
|
|
38
|
+
* Never throws and never rejects.
|
|
39
|
+
*/
|
|
40
|
+
export declare const reportTelemetry: (report: TelemetryReport) => Promise<void>;
|
|
41
|
+
/**
|
|
42
|
+
* Reports the outcome of a generation run.
|
|
43
|
+
* Never throws and never rejects.
|
|
44
|
+
*/
|
|
45
|
+
export declare const reportGeneration: (report: GenerationReport) => Promise<void>;
|
|
46
|
+
//# sourceMappingURL=telemetry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,UAAU,EACV,aAAa,EACb,KAAK,EACL,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAEjC,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IACrC,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAChC,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC3B,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACnB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAgDD;;GAEG;AACH,eAAO,MAAM,uBAAuB,WAC1B,IAAI,CACV,eAAe,EACf,SAAS,GAAG,gBAAgB,GAAG,WAAW,GAAG,SAAS,CACvD,KACA,gBASF,CAAC;AAqCF;;;GAGG;AACH,eAAO,MAAM,eAAe,WAClB,eAAe,KACtB,OAAO,CAAC,IAAI,CAoCd,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,WACnB,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAqCd,CAAC"}
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.reportGeneration = exports.reportTelemetry = exports.resolveTelemetryContext = void 0;
|
|
4
|
+
/**
|
|
5
|
+
* Anonymous usage telemetry hook for `buildConfig`.
|
|
6
|
+
*
|
|
7
|
+
* Fire and forget: nothing here can throw, reject or delay the caller.
|
|
8
|
+
*
|
|
9
|
+
* @module telemetry
|
|
10
|
+
*/
|
|
11
|
+
const node_module_1 = require("node:module");
|
|
12
|
+
/** In-flight config event, awaited before the generate event is sent. */
|
|
13
|
+
let pending = Promise.resolve();
|
|
14
|
+
/** Fingerprints already reported by this process. */
|
|
15
|
+
const reported = new Set();
|
|
16
|
+
const isSet = (value) => {
|
|
17
|
+
return (value !== undefined && value !== "" && value !== "0" && value !== "false");
|
|
18
|
+
};
|
|
19
|
+
/**
|
|
20
|
+
* Cheap opt-out checks, run before the telemetry package is even imported.
|
|
21
|
+
* The package repeats and completes them (state file, endpoint, ...).
|
|
22
|
+
*/
|
|
23
|
+
const isEnabled = (option, trigger, env) => {
|
|
24
|
+
if (isSet(env.DO_NOT_TRACK) ||
|
|
25
|
+
isSet(env.GRAPHQL_MARKDOWN_TELEMETRY_DISABLED) ||
|
|
26
|
+
env.VITEST !== undefined ||
|
|
27
|
+
env.JEST_WORKER_ID !== undefined ||
|
|
28
|
+
env.NODE_TEST_CONTEXT !== undefined ||
|
|
29
|
+
env.NODE_ENV === "test") {
|
|
30
|
+
return false;
|
|
31
|
+
}
|
|
32
|
+
if (option === false) {
|
|
33
|
+
return false;
|
|
34
|
+
}
|
|
35
|
+
return trigger !== undefined || option === true;
|
|
36
|
+
};
|
|
37
|
+
const resolveOption = (...values) => {
|
|
38
|
+
if (values.includes(false)) {
|
|
39
|
+
return false;
|
|
40
|
+
}
|
|
41
|
+
return values.includes(true) ? true : undefined;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* Resolves the telemetry opt-in and trigger from the configuration sources.
|
|
45
|
+
*/
|
|
46
|
+
const resolveTelemetryContext = (report) => {
|
|
47
|
+
return {
|
|
48
|
+
trigger: report.trigger,
|
|
49
|
+
option: resolveOption(report.cliOpts?.telemetry, report.configFileOpts?.telemetry, report.extension?.telemetry),
|
|
50
|
+
};
|
|
51
|
+
};
|
|
52
|
+
exports.resolveTelemetryContext = resolveTelemetryContext;
|
|
53
|
+
const fingerprintOf = (report) => {
|
|
54
|
+
return JSON.stringify([
|
|
55
|
+
report.configFileOpts,
|
|
56
|
+
report.extension,
|
|
57
|
+
report.cliOpts,
|
|
58
|
+
report.id,
|
|
59
|
+
report.trigger,
|
|
60
|
+
], (_key, value) => {
|
|
61
|
+
return typeof value === "function" ? "<function>" : value;
|
|
62
|
+
});
|
|
63
|
+
};
|
|
64
|
+
const readVersion = () => {
|
|
65
|
+
try {
|
|
66
|
+
const pkg = (0, node_module_1.createRequire)(__filename)("../package.json");
|
|
67
|
+
return pkg.version ?? "unknown";
|
|
68
|
+
}
|
|
69
|
+
catch {
|
|
70
|
+
return "unknown";
|
|
71
|
+
}
|
|
72
|
+
};
|
|
73
|
+
const readGraphqlMajor = async () => {
|
|
74
|
+
try {
|
|
75
|
+
const { versionInfo } = await import("graphql");
|
|
76
|
+
return versionInfo.major;
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
return undefined;
|
|
80
|
+
}
|
|
81
|
+
};
|
|
82
|
+
/**
|
|
83
|
+
* Reports the resolved configuration once per distinct config and process.
|
|
84
|
+
* Never throws and never rejects.
|
|
85
|
+
*/
|
|
86
|
+
const reportTelemetry = async (report) => {
|
|
87
|
+
try {
|
|
88
|
+
const option = resolveOption(report.cliOpts?.telemetry, report.configFileOpts?.telemetry, report.extension?.telemetry);
|
|
89
|
+
if (!isEnabled(option, report.trigger, process.env)) {
|
|
90
|
+
return;
|
|
91
|
+
}
|
|
92
|
+
const fingerprint = fingerprintOf(report);
|
|
93
|
+
if (reported.has(fingerprint)) {
|
|
94
|
+
return;
|
|
95
|
+
}
|
|
96
|
+
reported.add(fingerprint);
|
|
97
|
+
pending = (async () => {
|
|
98
|
+
try {
|
|
99
|
+
const { track } = await import("@graphql-markdown/telemetry");
|
|
100
|
+
await track({
|
|
101
|
+
trigger: report.trigger ?? "programmatic",
|
|
102
|
+
option,
|
|
103
|
+
pkg: "@graphql-markdown/core",
|
|
104
|
+
pkgVersion: readVersion(),
|
|
105
|
+
graphqlMajor: await readGraphqlMajor(),
|
|
106
|
+
config: { ...report.extension, ...report.configFileOpts },
|
|
107
|
+
cli: report.cliOpts ?? undefined,
|
|
108
|
+
});
|
|
109
|
+
}
|
|
110
|
+
catch {
|
|
111
|
+
// telemetry must never affect a run
|
|
112
|
+
}
|
|
113
|
+
})();
|
|
114
|
+
await pending;
|
|
115
|
+
}
|
|
116
|
+
catch {
|
|
117
|
+
// telemetry must never affect a run
|
|
118
|
+
}
|
|
119
|
+
};
|
|
120
|
+
exports.reportTelemetry = reportTelemetry;
|
|
121
|
+
/**
|
|
122
|
+
* Reports the outcome of a generation run.
|
|
123
|
+
* Never throws and never rejects.
|
|
124
|
+
*/
|
|
125
|
+
const reportGeneration = async (report) => {
|
|
126
|
+
try {
|
|
127
|
+
const { trigger, option } = report.telemetry ?? {};
|
|
128
|
+
if (!isEnabled(option, trigger, process.env)) {
|
|
129
|
+
return;
|
|
130
|
+
}
|
|
131
|
+
// avoids racing the config event on the state file
|
|
132
|
+
await pending;
|
|
133
|
+
const { track, errorTypeOf, NO_SCHEMA_ERROR, POST_ERROR_PREFIX } = await import("@graphql-markdown/telemetry");
|
|
134
|
+
let errorType = report.errorType;
|
|
135
|
+
if (errorType === undefined) {
|
|
136
|
+
if (report.error !== undefined) {
|
|
137
|
+
errorType = errorTypeOf(report.error);
|
|
138
|
+
}
|
|
139
|
+
else if (report.noSchema) {
|
|
140
|
+
errorType = NO_SCHEMA_ERROR;
|
|
141
|
+
}
|
|
142
|
+
else if (report.postError !== undefined) {
|
|
143
|
+
errorType = `${POST_ERROR_PREFIX}${errorTypeOf(report.postError)}`;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
await track({
|
|
147
|
+
event: "generate",
|
|
148
|
+
trigger: trigger ?? "programmatic",
|
|
149
|
+
option,
|
|
150
|
+
pkg: "@graphql-markdown/core",
|
|
151
|
+
pkgVersion: readVersion(),
|
|
152
|
+
graphqlMajor: await readGraphqlMajor(),
|
|
153
|
+
pages: report.pages,
|
|
154
|
+
durationMs: report.durationMs,
|
|
155
|
+
errorType,
|
|
156
|
+
});
|
|
157
|
+
}
|
|
158
|
+
catch {
|
|
159
|
+
// telemetry must never affect a run
|
|
160
|
+
}
|
|
161
|
+
};
|
|
162
|
+
exports.reportGeneration = reportGeneration;
|
package/package.json
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
"bugs": {
|
|
6
6
|
"url": "https://github.com/graphql-markdown/graphql-markdown/issues"
|
|
7
7
|
},
|
|
8
|
-
"version": "1.
|
|
8
|
+
"version": "1.25.0",
|
|
9
9
|
"license": "MIT",
|
|
10
10
|
"repository": {
|
|
11
11
|
"type": "git",
|
|
@@ -72,19 +72,21 @@
|
|
|
72
72
|
"test:watch": "vitest --watch"
|
|
73
73
|
},
|
|
74
74
|
"dependencies": {
|
|
75
|
-
"@fastify/deepmerge": "^3.2.
|
|
76
|
-
"@graphql-markdown/graphql": "",
|
|
77
|
-
"@graphql-markdown/logger": "",
|
|
78
|
-
"@graphql-markdown/printer-legacy": "",
|
|
79
|
-
"@graphql-markdown/
|
|
80
|
-
"@graphql-markdown/
|
|
75
|
+
"@fastify/deepmerge": "^3.2.2",
|
|
76
|
+
"@graphql-markdown/graphql": "^1.3.3",
|
|
77
|
+
"@graphql-markdown/logger": "^1.1.3",
|
|
78
|
+
"@graphql-markdown/printer-legacy": "^1.19.2",
|
|
79
|
+
"@graphql-markdown/telemetry": "^0.1.0",
|
|
80
|
+
"@graphql-markdown/types": "^1.17.0",
|
|
81
|
+
"@graphql-markdown/utils": "^1.14.0"
|
|
81
82
|
},
|
|
82
83
|
"devDependencies": {
|
|
83
|
-
"@graphql-markdown/tooling-config": ""
|
|
84
|
+
"@graphql-markdown/tooling-config": "^1.0.0"
|
|
84
85
|
},
|
|
85
86
|
"peerDependencies": {
|
|
86
|
-
"@graphql-markdown/diff": "",
|
|
87
|
-
"@graphql-markdown/helpers": "",
|
|
87
|
+
"@graphql-markdown/diff": "^1.1.22",
|
|
88
|
+
"@graphql-markdown/helpers": "^1.2.3",
|
|
89
|
+
"graphql": "^16.0.0 || ^17.0.0",
|
|
88
90
|
"graphql-config": "5.1.6"
|
|
89
91
|
},
|
|
90
92
|
"peerDependenciesMeta": {
|