@graphql-markdown/core 1.24.1 → 1.26.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/README.md +4 -3
- package/dist/config.d.ts +9 -6
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +37 -20
- package/dist/const/homepage.d.ts +6 -0
- package/dist/const/homepage.d.ts.map +1 -1
- package/dist/const/homepage.js +7 -1
- package/dist/const/patterns.d.ts.map +1 -1
- package/dist/diff.d.ts +2 -2
- package/dist/diff.d.ts.map +1 -1
- package/dist/diff.js +19 -3
- package/dist/event-emitter.d.ts.map +1 -1
- package/dist/event-handlers.js +5 -5
- package/dist/event-map.d.ts +8 -0
- package/dist/event-map.d.ts.map +1 -1
- package/dist/event-map.js +21 -30
- package/dist/events/index.d.ts +17 -17
- package/dist/events/index.d.ts.map +1 -1
- package/dist/events/index.js +34 -34
- 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 +95 -52
- package/dist/graphql-config.d.ts.map +1 -1
- package/dist/graphql-config.js +22 -7
- package/dist/index.d.ts +18 -18
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +25 -25
- package/dist/optional-dependencies.d.ts +2 -0
- package/dist/optional-dependencies.d.ts.map +1 -0
- package/dist/optional-dependencies.js +9 -0
- package/dist/renderer.d.ts +13 -3
- package/dist/renderer.d.ts.map +1 -1
- package/dist/renderer.js +65 -36
- package/dist/telemetry.d.ts +53 -0
- package/dist/telemetry.d.ts.map +1 -0
- package/dist/telemetry.js +153 -0
- package/dist/version.d.ts +6 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +8 -0
- package/package.json +16 -14
package/dist/renderer.js
CHANGED
|
@@ -5,11 +5,11 @@ const node_path_1 = require("node:path");
|
|
|
5
5
|
const graphql_1 = require("@graphql-markdown/graphql");
|
|
6
6
|
const utils_1 = require("@graphql-markdown/utils");
|
|
7
7
|
const logger_1 = require("@graphql-markdown/logger");
|
|
8
|
-
const
|
|
9
|
-
const
|
|
10
|
-
const
|
|
11
|
-
const
|
|
12
|
-
const
|
|
8
|
+
const config_ts_1 = require("./config.js");
|
|
9
|
+
const homepage_ts_1 = require("./const/homepage.js");
|
|
10
|
+
const validation_ts_1 = require("./directives/validation.js");
|
|
11
|
+
const event_emitter_ts_1 = require("./event-emitter.js");
|
|
12
|
+
const index_ts_1 = require("./events/index.js");
|
|
13
13
|
/**
|
|
14
14
|
* Constant representing the string literal for deprecated entities.
|
|
15
15
|
* Used for grouping deprecated schema entities when the deprecated option is set to "group".
|
|
@@ -114,7 +114,7 @@ exports.API_GROUPS = {
|
|
|
114
114
|
// Used only by unit tests for direct whitebox coverage; not part of the production public API.
|
|
115
115
|
const getApiGroupFolder = (type, groups) => {
|
|
116
116
|
let folderNames = exports.API_GROUPS;
|
|
117
|
-
if ((0,
|
|
117
|
+
if ((0, validation_ts_1.isGroupsObject)(groups)) {
|
|
118
118
|
folderNames = { ...exports.API_GROUPS, ...groups };
|
|
119
119
|
}
|
|
120
120
|
return (0, graphql_1.isApiType)(type) ? folderNames.operations : folderNames.types;
|
|
@@ -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;
|
|
@@ -331,8 +336,8 @@ class Renderer {
|
|
|
331
336
|
const finalOptions = options ?? defaultOptions;
|
|
332
337
|
const sidebarPosition = finalOptions.sidebarPosition ??
|
|
333
338
|
this.categoryPositionManager.getPosition(category);
|
|
334
|
-
const events = (0,
|
|
335
|
-
const event = new
|
|
339
|
+
const events = (0, event_emitter_ts_1.getEvents)();
|
|
340
|
+
const event = new index_ts_1.GenerateIndexMetafileEvent({
|
|
336
341
|
dirPath,
|
|
337
342
|
category,
|
|
338
343
|
outputAdapter: this.outputAdapter,
|
|
@@ -344,14 +349,14 @@ class Renderer {
|
|
|
344
349
|
});
|
|
345
350
|
// emitAsync resolves to an EmitResult, never an array: the previous
|
|
346
351
|
// Array.isArray() guard was always false, so handler errors went unreported
|
|
347
|
-
const { errors } = await events.emitAsync(
|
|
348
|
-
(0, exports.logHandlerErrors)(
|
|
349
|
-
const { errors: afterErrors } = await events.emitAsync(
|
|
352
|
+
const { errors } = await events.emitAsync(index_ts_1.GenerateIndexMetafileEvents.BEFORE_GENERATE, event);
|
|
353
|
+
(0, exports.logHandlerErrors)(index_ts_1.GenerateIndexMetafileEvents.BEFORE_GENERATE, errors);
|
|
354
|
+
const { errors: afterErrors } = await events.emitAsync(index_ts_1.GenerateIndexMetafileEvents.AFTER_GENERATE, new index_ts_1.GenerateIndexMetafileEvent({
|
|
350
355
|
dirPath,
|
|
351
356
|
category,
|
|
352
357
|
outputAdapter: this.outputAdapter,
|
|
353
358
|
}));
|
|
354
|
-
(0, exports.logHandlerErrors)(
|
|
359
|
+
(0, exports.logHandlerErrors)(index_ts_1.GenerateIndexMetafileEvents.AFTER_GENERATE, afterErrors);
|
|
355
360
|
}
|
|
356
361
|
/**
|
|
357
362
|
* Generates the directory path and metafiles for a specific schema entity type.
|
|
@@ -365,10 +370,10 @@ class Renderer {
|
|
|
365
370
|
*/
|
|
366
371
|
async generateCategoryMetafileType(type, name, rootTypeName) {
|
|
367
372
|
let dirPath = this.outputDir;
|
|
368
|
-
if (!(0,
|
|
373
|
+
if (!(0, validation_ts_1.isPath)(dirPath)) {
|
|
369
374
|
throw new Error("Output directory is empty or not specified");
|
|
370
375
|
}
|
|
371
|
-
if (isHierarchy(this.options,
|
|
376
|
+
if (isHierarchy(this.options, config_ts_1.TypeHierarchy.FLAT)) {
|
|
372
377
|
return dirPath;
|
|
373
378
|
}
|
|
374
379
|
// Deprecated gets highest priority - at ROOT level before even custom groups
|
|
@@ -390,9 +395,9 @@ class Renderer {
|
|
|
390
395
|
dirPath = (0, node_path_1.join)(dirPath, formattedRootGroup);
|
|
391
396
|
await this.generateIndexMetafile(dirPath, rootGroup);
|
|
392
397
|
}
|
|
393
|
-
const useApiGroup = isHierarchy(this.options,
|
|
394
|
-
? this.options.hierarchy[
|
|
395
|
-
: !isHierarchy(this.options,
|
|
398
|
+
const useApiGroup = isHierarchy(this.options, config_ts_1.TypeHierarchy.API)
|
|
399
|
+
? this.options.hierarchy[config_ts_1.TypeHierarchy.API]
|
|
400
|
+
: !isHierarchy(this.options, config_ts_1.TypeHierarchy.ENTITY);
|
|
396
401
|
if (useApiGroup) {
|
|
397
402
|
const typeCat = (0, exports.getApiGroupFolder)(type, useApiGroup);
|
|
398
403
|
// API groups are root-level if no custom groups exist, nested if custom groups exist
|
|
@@ -427,7 +432,7 @@ class Renderer {
|
|
|
427
432
|
if (typeof type !== "object" || type === null) {
|
|
428
433
|
return undefined;
|
|
429
434
|
}
|
|
430
|
-
const isFlat = isHierarchy(this.options,
|
|
435
|
+
const isFlat = isHierarchy(this.options, config_ts_1.TypeHierarchy.FLAT);
|
|
431
436
|
const isOperationRootType = rootTypeName === "queries" ||
|
|
432
437
|
rootTypeName === "mutations" ||
|
|
433
438
|
rootTypeName === "subscriptions";
|
|
@@ -469,7 +474,7 @@ class Renderer {
|
|
|
469
474
|
* @example
|
|
470
475
|
*/
|
|
471
476
|
async renderTypeEntities(dirPath, name, type, operationNamespaceParts, entity) {
|
|
472
|
-
if (!(0,
|
|
477
|
+
if (!(0, validation_ts_1.isPath)(dirPath)) {
|
|
473
478
|
throw new Error("Output directory is empty or not specified");
|
|
474
479
|
}
|
|
475
480
|
// Regex patterns to parse page metadata from file paths
|
|
@@ -478,7 +483,7 @@ class Renderer {
|
|
|
478
483
|
// NOSONAR - pattern is safe, hyphen in character class doesn't cause backtracking
|
|
479
484
|
const PageRegex = /(?<category>[a-z0-9-]+)[\\/]+(?<pageId>[a-z0-9-]+)\.mdx?$/i; // NOSONAR
|
|
480
485
|
const PageRegexFlat = /(?<pageId>[a-z0-9-]+)\.mdx?$/i; // NOSONAR
|
|
481
|
-
const isFlat = isHierarchy(this.options,
|
|
486
|
+
const isFlat = isHierarchy(this.options, config_ts_1.TypeHierarchy.FLAT);
|
|
482
487
|
// Flat hierarchy has no folders to keep same-named entities of different
|
|
483
488
|
// kinds apart (a `type User` and a `Query.user` field both slugify to
|
|
484
489
|
// "user") — prefixing with `entity` (the `SchemaEntity` root type this
|
|
@@ -543,22 +548,42 @@ class Renderer {
|
|
|
543
548
|
? page.groups.pageId
|
|
544
549
|
: stripNumericPrefix(page.groups.category);
|
|
545
550
|
const category = isFlat ? "schema" : (0, utils_1.startCase)(extractedCategory);
|
|
546
|
-
const events = (0,
|
|
547
|
-
const event = new
|
|
551
|
+
const events = (0, event_emitter_ts_1.getEvents)();
|
|
552
|
+
const event = new index_ts_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
|
-
const { errors } = await events.emitAsync(
|
|
555
|
-
(0, exports.logHandlerErrors)(
|
|
561
|
+
const { errors } = await events.emitAsync(index_ts_1.RenderTypeEntitiesEvents.AFTER_RENDER, event);
|
|
562
|
+
(0, exports.logHandlerErrors)(index_ts_1.RenderTypeEntitiesEvents.AFTER_RENDER, errors);
|
|
556
563
|
return {
|
|
557
564
|
category,
|
|
558
565
|
filePath,
|
|
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_ts_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
|
|
@@ -581,13 +606,13 @@ class Renderer {
|
|
|
581
606
|
const rootCategories = new Set();
|
|
582
607
|
const nestedCategories = new Set();
|
|
583
608
|
// Skip if flat hierarchy
|
|
584
|
-
if (isHierarchy(this.options,
|
|
609
|
+
if (isHierarchy(this.options, config_ts_1.TypeHierarchy.FLAT)) {
|
|
585
610
|
return;
|
|
586
611
|
}
|
|
587
612
|
// Determine if using API hierarchy
|
|
588
|
-
const useApiGroup = isHierarchy(this.options,
|
|
589
|
-
? this.options.hierarchy[
|
|
590
|
-
: !isHierarchy(this.options,
|
|
613
|
+
const useApiGroup = isHierarchy(this.options, config_ts_1.TypeHierarchy.API)
|
|
614
|
+
? this.options.hierarchy[config_ts_1.TypeHierarchy.API]
|
|
615
|
+
: !isHierarchy(this.options, config_ts_1.TypeHierarchy.ENTITY);
|
|
591
616
|
// Register custom groups at root level
|
|
592
617
|
this.registerCustomGroups(rootCategories);
|
|
593
618
|
// Register categories based on hierarchy type
|
|
@@ -613,13 +638,16 @@ class Renderer {
|
|
|
613
638
|
* @example
|
|
614
639
|
*/
|
|
615
640
|
async renderHomepage(homepageLocation) {
|
|
616
|
-
if (typeof homepageLocation !== "string"
|
|
641
|
+
if (typeof homepageLocation !== "string" &&
|
|
642
|
+
homepageLocation !== config_ts_1.ASSET_HOMEPAGE_LOCATION) {
|
|
617
643
|
return;
|
|
618
644
|
}
|
|
619
|
-
if (!(0,
|
|
645
|
+
if (!(0, validation_ts_1.isPath)(this.outputDir)) {
|
|
620
646
|
throw new Error("Output directory is empty or not specified");
|
|
621
647
|
}
|
|
622
|
-
const homePage =
|
|
648
|
+
const homePage = homepageLocation === config_ts_1.ASSET_HOMEPAGE_LOCATION
|
|
649
|
+
? homepage_ts_1.DEFAULT_HOMEPAGE_FILENAME
|
|
650
|
+
: (0, node_path_1.basename)(homepageLocation);
|
|
623
651
|
const destLocation = (0, node_path_1.join)(this.outputDir, homePage);
|
|
624
652
|
const slug = utils_1.pathUrl.resolve("/", this.baseURL);
|
|
625
653
|
try {
|
|
@@ -630,8 +658,8 @@ class Renderer {
|
|
|
630
658
|
//
|
|
631
659
|
// The built-in template is inlined, so the default path performs no
|
|
632
660
|
// filesystem read at all. Only a caller-supplied `homepage` path does.
|
|
633
|
-
const template = homepageLocation ===
|
|
634
|
-
?
|
|
661
|
+
const template = homepageLocation === config_ts_1.ASSET_HOMEPAGE_LOCATION
|
|
662
|
+
? homepage_ts_1.DEFAULT_HOMEPAGE_TEMPLATE
|
|
635
663
|
: await (0, utils_1.readFile)(homepageLocation);
|
|
636
664
|
const data = template
|
|
637
665
|
.toString()
|
|
@@ -640,7 +668,7 @@ class Renderer {
|
|
|
640
668
|
await this.writeOutput(destLocation, data);
|
|
641
669
|
}
|
|
642
670
|
catch (error) {
|
|
643
|
-
(0, logger_1.log)(`An error occurred while processing the homepage ${homepageLocation}: ${error}`, logger_1.LogLevel.warn);
|
|
671
|
+
(0, logger_1.log)(`An error occurred while processing the homepage ${String(homepageLocation)}: ${error}`, logger_1.LogLevel.warn);
|
|
644
672
|
}
|
|
645
673
|
}
|
|
646
674
|
/**
|
|
@@ -816,7 +844,7 @@ exports.Renderer = Renderer;
|
|
|
816
844
|
* });
|
|
817
845
|
* ```
|
|
818
846
|
*/
|
|
819
|
-
const getRenderer = async ({ printer, outputDir, baseURL, group, prettify, docOptions, mdxExtension, outputAdapter = undefined, }) => {
|
|
847
|
+
const getRenderer = async ({ printer, outputDir, baseURL, linkRoot, group, prettify, docOptions, mdxExtension, outputAdapter = undefined, }) => {
|
|
820
848
|
const adapter = outputAdapter ?? utils_1.fsOutputAdapter;
|
|
821
849
|
// Optional on the interface: a destination with no directory concept (an
|
|
822
850
|
// object store, a CMS collection) has nothing to prepare.
|
|
@@ -825,6 +853,7 @@ const getRenderer = async ({ printer, outputDir, baseURL, group, prettify, docOp
|
|
|
825
853
|
printer,
|
|
826
854
|
outputDir,
|
|
827
855
|
baseURL,
|
|
856
|
+
...(linkRoot !== undefined && { linkRoot }),
|
|
828
857
|
group,
|
|
829
858
|
prettify,
|
|
830
859
|
docOptions,
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Anonymous usage telemetry hook for `buildConfig`.
|
|
3
|
+
*
|
|
4
|
+
* Fire and forget: nothing here can throw, reject or delay the caller.
|
|
5
|
+
*
|
|
6
|
+
* @module telemetry
|
|
7
|
+
*/
|
|
8
|
+
import type { CliOptions, ConfigOptions, Maybe, TelemetryTrigger } from "@graphql-markdown/types";
|
|
9
|
+
/** Internal context passed by our own entry points. */
|
|
10
|
+
export interface BuildConfigContext {
|
|
11
|
+
trigger?: TelemetryTrigger;
|
|
12
|
+
}
|
|
13
|
+
export interface TelemetryReport {
|
|
14
|
+
configFileOpts: Maybe<ConfigOptions>;
|
|
15
|
+
extension: Maybe<ConfigOptions>;
|
|
16
|
+
cliOpts: Maybe<CliOptions>;
|
|
17
|
+
id?: Maybe<string>;
|
|
18
|
+
trigger?: TelemetryTrigger;
|
|
19
|
+
}
|
|
20
|
+
/** Telemetry decision made once by `buildConfig`, reused at generation time. */
|
|
21
|
+
export interface TelemetryContext {
|
|
22
|
+
trigger?: TelemetryTrigger;
|
|
23
|
+
option?: boolean;
|
|
24
|
+
}
|
|
25
|
+
/** Outcome of a documentation generation run. */
|
|
26
|
+
export interface GenerationReport {
|
|
27
|
+
telemetry?: TelemetryContext;
|
|
28
|
+
pages: number;
|
|
29
|
+
durationMs: number;
|
|
30
|
+
/** Error thrown by the run, if any. */
|
|
31
|
+
error?: unknown;
|
|
32
|
+
/** Explicit error type, takes precedence over `error`. */
|
|
33
|
+
errorType?: string;
|
|
34
|
+
/** The run failed without throwing because the schema could not be loaded. */
|
|
35
|
+
noSchema?: boolean;
|
|
36
|
+
/** First post-processing error, when the run completed incompletely. */
|
|
37
|
+
postError?: unknown;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Resolves the telemetry opt-in and trigger from the configuration sources.
|
|
41
|
+
*/
|
|
42
|
+
export declare const resolveTelemetryContext: (report: Pick<TelemetryReport, "cliOpts" | "configFileOpts" | "extension" | "trigger">) => TelemetryContext;
|
|
43
|
+
/**
|
|
44
|
+
* Reports the resolved configuration once per distinct config and process.
|
|
45
|
+
* Never throws and never rejects.
|
|
46
|
+
*/
|
|
47
|
+
export declare const reportTelemetry: (report: TelemetryReport) => Promise<void>;
|
|
48
|
+
/**
|
|
49
|
+
* Reports the outcome of a generation run.
|
|
50
|
+
* Never throws and never rejects.
|
|
51
|
+
*/
|
|
52
|
+
export declare const reportGeneration: (report: GenerationReport) => Promise<void>;
|
|
53
|
+
//# sourceMappingURL=telemetry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,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;AA0BF;;;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,153 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Anonymous usage telemetry hook for `buildConfig`.
|
|
4
|
+
*
|
|
5
|
+
* Fire and forget: nothing here can throw, reject or delay the caller.
|
|
6
|
+
*
|
|
7
|
+
* @module telemetry
|
|
8
|
+
*/
|
|
9
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
10
|
+
exports.reportGeneration = exports.reportTelemetry = exports.resolveTelemetryContext = void 0;
|
|
11
|
+
const version_ts_1 = require("./version.js");
|
|
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 readGraphqlMajor = async () => {
|
|
65
|
+
try {
|
|
66
|
+
const { versionInfo } = await import("graphql");
|
|
67
|
+
return versionInfo.major;
|
|
68
|
+
}
|
|
69
|
+
catch {
|
|
70
|
+
return undefined;
|
|
71
|
+
}
|
|
72
|
+
};
|
|
73
|
+
/**
|
|
74
|
+
* Reports the resolved configuration once per distinct config and process.
|
|
75
|
+
* Never throws and never rejects.
|
|
76
|
+
*/
|
|
77
|
+
const reportTelemetry = async (report) => {
|
|
78
|
+
try {
|
|
79
|
+
const option = resolveOption(report.cliOpts?.telemetry, report.configFileOpts?.telemetry, report.extension?.telemetry);
|
|
80
|
+
if (!isEnabled(option, report.trigger, process.env)) {
|
|
81
|
+
return;
|
|
82
|
+
}
|
|
83
|
+
const fingerprint = fingerprintOf(report);
|
|
84
|
+
if (reported.has(fingerprint)) {
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
reported.add(fingerprint);
|
|
88
|
+
pending = (async () => {
|
|
89
|
+
try {
|
|
90
|
+
const { track } = await import("@graphql-markdown/telemetry");
|
|
91
|
+
await track({
|
|
92
|
+
trigger: report.trigger ?? "programmatic",
|
|
93
|
+
option,
|
|
94
|
+
pkg: "@graphql-markdown/core",
|
|
95
|
+
pkgVersion: version_ts_1.VERSION,
|
|
96
|
+
graphqlMajor: await readGraphqlMajor(),
|
|
97
|
+
config: { ...report.extension, ...report.configFileOpts },
|
|
98
|
+
cli: report.cliOpts ?? undefined,
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
catch {
|
|
102
|
+
// telemetry must never affect a run
|
|
103
|
+
}
|
|
104
|
+
})();
|
|
105
|
+
await pending;
|
|
106
|
+
}
|
|
107
|
+
catch {
|
|
108
|
+
// telemetry must never affect a run
|
|
109
|
+
}
|
|
110
|
+
};
|
|
111
|
+
exports.reportTelemetry = reportTelemetry;
|
|
112
|
+
/**
|
|
113
|
+
* Reports the outcome of a generation run.
|
|
114
|
+
* Never throws and never rejects.
|
|
115
|
+
*/
|
|
116
|
+
const reportGeneration = async (report) => {
|
|
117
|
+
try {
|
|
118
|
+
const { trigger, option } = report.telemetry ?? {};
|
|
119
|
+
if (!isEnabled(option, trigger, process.env)) {
|
|
120
|
+
return;
|
|
121
|
+
}
|
|
122
|
+
// avoids racing the config event on the state file
|
|
123
|
+
await pending;
|
|
124
|
+
const { track, errorTypeOf, NO_SCHEMA_ERROR, POST_ERROR_PREFIX } = await import("@graphql-markdown/telemetry");
|
|
125
|
+
let errorType = report.errorType;
|
|
126
|
+
if (errorType === undefined) {
|
|
127
|
+
if (report.error !== undefined) {
|
|
128
|
+
errorType = errorTypeOf(report.error);
|
|
129
|
+
}
|
|
130
|
+
else if (report.noSchema) {
|
|
131
|
+
errorType = NO_SCHEMA_ERROR;
|
|
132
|
+
}
|
|
133
|
+
else if (report.postError !== undefined) {
|
|
134
|
+
errorType = `${POST_ERROR_PREFIX}${errorTypeOf(report.postError)}`;
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
await track({
|
|
138
|
+
event: "generate",
|
|
139
|
+
trigger: trigger ?? "programmatic",
|
|
140
|
+
option,
|
|
141
|
+
pkg: "@graphql-markdown/core",
|
|
142
|
+
pkgVersion: version_ts_1.VERSION,
|
|
143
|
+
graphqlMajor: await readGraphqlMajor(),
|
|
144
|
+
pages: report.pages,
|
|
145
|
+
durationMs: report.durationMs,
|
|
146
|
+
errorType,
|
|
147
|
+
});
|
|
148
|
+
}
|
|
149
|
+
catch {
|
|
150
|
+
// telemetry must never affect a run
|
|
151
|
+
}
|
|
152
|
+
};
|
|
153
|
+
exports.reportGeneration = reportGeneration;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,MAAiB,CAAC"}
|
package/dist/version.js
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.VERSION = void 0;
|
|
4
|
+
/**
|
|
5
|
+
* Package version, kept as a constant (no runtime `package.json` lookup) for ESM/JSR compatibility.
|
|
6
|
+
* A unit test asserts it matches `package.json`.
|
|
7
|
+
*/
|
|
8
|
+
exports.VERSION = "1.26.0";
|
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@graphql-markdown/core",
|
|
3
3
|
"homepage": "https://graphql-markdown.dev",
|
|
4
|
-
"description": "GraphQL-Markdown
|
|
4
|
+
"description": "Core of GraphQL-Markdown: generates Markdown documentation from a GraphQL schema.",
|
|
5
5
|
"bugs": {
|
|
6
6
|
"url": "https://github.com/graphql-markdown/graphql-markdown/issues"
|
|
7
7
|
},
|
|
8
|
-
"version": "1.
|
|
8
|
+
"version": "1.26.0",
|
|
9
9
|
"license": "MIT",
|
|
10
10
|
"repository": {
|
|
11
11
|
"type": "git",
|
|
@@ -62,8 +62,8 @@
|
|
|
62
62
|
"build": "tsgo --build",
|
|
63
63
|
"lint": "eslint --config ../../packages/tooling-config/eslint/config.ts \"{src,tests}/**/*.{ts,js,json,gql}\"",
|
|
64
64
|
"lint:fix": "eslint --config ../../packages/tooling-config/eslint/config.ts \"{src,tests}/**/*.{ts,js,json,gql}\" --fix",
|
|
65
|
-
"prettier": "prettier \"{src,tests,assets}/**/*.{ts,js,json,md,gql}\" --check",
|
|
66
|
-
"prettier:fix": "prettier \"{src,tests,assets}/**/*.{ts,js,json,md,gql}\" --write",
|
|
65
|
+
"prettier": "prettier \"{src,tests,assets}/**/*.{ts,js,json,md,gql}\" README.md --check",
|
|
66
|
+
"prettier:fix": "prettier \"{src,tests,assets}/**/*.{ts,js,json,md,gql}\" README.md --write",
|
|
67
67
|
"ts:check": "tsgo --noEmit",
|
|
68
68
|
"test": "vitest run --passWithNoTests",
|
|
69
69
|
"test:unit": "vitest run --passWithNoTests tests/unit",
|
|
@@ -72,20 +72,22 @@
|
|
|
72
72
|
"test:watch": "vitest --watch"
|
|
73
73
|
},
|
|
74
74
|
"dependencies": {
|
|
75
|
-
"@fastify/deepmerge": "^3.2.
|
|
76
|
-
"@graphql-markdown/graphql": "^1.3.
|
|
77
|
-
"@graphql-markdown/logger": "^1.1.
|
|
78
|
-
"@graphql-markdown/printer-legacy": "^1.19.
|
|
79
|
-
"@graphql-markdown/
|
|
80
|
-
"@graphql-markdown/
|
|
75
|
+
"@fastify/deepmerge": "^3.2.4",
|
|
76
|
+
"@graphql-markdown/graphql": "^1.3.4",
|
|
77
|
+
"@graphql-markdown/logger": "^1.1.4",
|
|
78
|
+
"@graphql-markdown/printer-legacy": "^1.19.3",
|
|
79
|
+
"@graphql-markdown/telemetry": "^0.1.1",
|
|
80
|
+
"@graphql-markdown/types": "^1.17.1",
|
|
81
|
+
"@graphql-markdown/utils": "^1.14.1"
|
|
81
82
|
},
|
|
82
83
|
"devDependencies": {
|
|
83
84
|
"@graphql-markdown/tooling-config": "^1.0.0"
|
|
84
85
|
},
|
|
85
86
|
"peerDependencies": {
|
|
86
|
-
"@graphql-markdown/diff": "^1.1.
|
|
87
|
-
"@graphql-markdown/helpers": "^1.2.
|
|
88
|
-
"graphql
|
|
87
|
+
"@graphql-markdown/diff": "^1.1.23",
|
|
88
|
+
"@graphql-markdown/helpers": "^1.2.4",
|
|
89
|
+
"graphql": "^16.0.0 || ^17.0.0",
|
|
90
|
+
"graphql-config": "^5.1.8 || ^6.0.0"
|
|
89
91
|
},
|
|
90
92
|
"peerDependenciesMeta": {
|
|
91
93
|
"@graphql-markdown/diff": {
|
|
@@ -102,7 +104,7 @@
|
|
|
102
104
|
"test": "tests"
|
|
103
105
|
},
|
|
104
106
|
"engines": {
|
|
105
|
-
"node": ">=22.
|
|
107
|
+
"node": ">=22.18.0"
|
|
106
108
|
},
|
|
107
109
|
"publishConfig": {
|
|
108
110
|
"access": "public"
|