@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.
Files changed (41) hide show
  1. package/README.md +4 -3
  2. package/dist/config.d.ts +9 -6
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/config.js +37 -20
  5. package/dist/const/homepage.d.ts +6 -0
  6. package/dist/const/homepage.d.ts.map +1 -1
  7. package/dist/const/homepage.js +7 -1
  8. package/dist/const/patterns.d.ts.map +1 -1
  9. package/dist/diff.d.ts +2 -2
  10. package/dist/diff.d.ts.map +1 -1
  11. package/dist/diff.js +19 -3
  12. package/dist/event-emitter.d.ts.map +1 -1
  13. package/dist/event-handlers.js +5 -5
  14. package/dist/event-map.d.ts +8 -0
  15. package/dist/event-map.d.ts.map +1 -1
  16. package/dist/event-map.js +21 -30
  17. package/dist/events/index.d.ts +17 -17
  18. package/dist/events/index.d.ts.map +1 -1
  19. package/dist/events/index.js +34 -34
  20. package/dist/events/render-type-entities.d.ts +6 -0
  21. package/dist/events/render-type-entities.d.ts.map +1 -1
  22. package/dist/generator.d.ts.map +1 -1
  23. package/dist/generator.js +95 -52
  24. package/dist/graphql-config.d.ts.map +1 -1
  25. package/dist/graphql-config.js +22 -7
  26. package/dist/index.d.ts +18 -18
  27. package/dist/index.d.ts.map +1 -1
  28. package/dist/index.js +25 -25
  29. package/dist/optional-dependencies.d.ts +2 -0
  30. package/dist/optional-dependencies.d.ts.map +1 -0
  31. package/dist/optional-dependencies.js +9 -0
  32. package/dist/renderer.d.ts +13 -3
  33. package/dist/renderer.d.ts.map +1 -1
  34. package/dist/renderer.js +65 -36
  35. package/dist/telemetry.d.ts +53 -0
  36. package/dist/telemetry.d.ts.map +1 -0
  37. package/dist/telemetry.js +153 -0
  38. package/dist/version.d.ts +6 -0
  39. package/dist/version.d.ts.map +1 -0
  40. package/dist/version.js +8 -0
  41. 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 config_1 = require("./config");
9
- const homepage_1 = require("./const/homepage");
10
- const validation_1 = require("./directives/validation");
11
- const event_emitter_1 = require("./event-emitter");
12
- const events_1 = require("./events");
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, validation_1.isGroupsObject)(groups)) {
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, event_emitter_1.getEvents)();
335
- const event = new events_1.GenerateIndexMetafileEvent({
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(events_1.GenerateIndexMetafileEvents.BEFORE_GENERATE, event);
348
- (0, exports.logHandlerErrors)(events_1.GenerateIndexMetafileEvents.BEFORE_GENERATE, errors);
349
- const { errors: afterErrors } = await events.emitAsync(events_1.GenerateIndexMetafileEvents.AFTER_GENERATE, new events_1.GenerateIndexMetafileEvent({
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)(events_1.GenerateIndexMetafileEvents.AFTER_GENERATE, afterErrors);
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, validation_1.isPath)(dirPath)) {
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, config_1.TypeHierarchy.FLAT)) {
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, config_1.TypeHierarchy.API)
394
- ? this.options.hierarchy[config_1.TypeHierarchy.API]
395
- : !isHierarchy(this.options, config_1.TypeHierarchy.ENTITY);
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, config_1.TypeHierarchy.FLAT);
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, validation_1.isPath)(dirPath)) {
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, config_1.TypeHierarchy.FLAT);
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, event_emitter_1.getEvents)();
547
- const event = new events_1.RenderTypeEntitiesEvent({
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(events_1.RenderTypeEntitiesEvents.AFTER_RENDER, event);
555
- (0, exports.logHandlerErrors)(events_1.RenderTypeEntitiesEvents.AFTER_RENDER, errors);
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, config_1.TypeHierarchy.FLAT)) {
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, config_1.TypeHierarchy.API)
589
- ? this.options.hierarchy[config_1.TypeHierarchy.API]
590
- : !isHierarchy(this.options, config_1.TypeHierarchy.ENTITY);
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, validation_1.isPath)(this.outputDir)) {
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 = (0, node_path_1.basename)(homepageLocation);
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 === config_1.ASSET_HOMEPAGE_LOCATION
634
- ? homepage_1.DEFAULT_HOMEPAGE_TEMPLATE
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,6 @@
1
+ /**
2
+ * Package version, kept as a constant (no runtime `package.json` lookup) for ESM/JSR compatibility.
3
+ * A unit test asserts it matches `package.json`.
4
+ */
5
+ export declare const VERSION: string;
6
+ //# sourceMappingURL=version.d.ts.map
@@ -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"}
@@ -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 core package for generating Markdown documentation from a GraphQL schema.",
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.24.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.1",
76
- "@graphql-markdown/graphql": "^1.3.2",
77
- "@graphql-markdown/logger": "^1.1.2",
78
- "@graphql-markdown/printer-legacy": "^1.19.1",
79
- "@graphql-markdown/types": "^1.16.1",
80
- "@graphql-markdown/utils": "^1.13.3"
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.21",
87
- "@graphql-markdown/helpers": "^1.2.2",
88
- "graphql-config": "5.1.6"
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.12.0"
107
+ "node": ">=22.18.0"
106
108
  },
107
109
  "publishConfig": {
108
110
  "access": "public"