@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 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>) => Promise<Options>;
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
@@ -1 +1 @@
1
- {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
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?.deprecated ??
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;CAC/B,CAAC;IACA,YACE,IAAI,EAAE;QACJ,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,aAAa,CAAC;KAC/B,EACD,OAAO,CAAC,EAAE,uBAAuB,EAGlC;CACF"}
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"}
@@ -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;AAiEjC;;;;;;;;;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;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,YACvB,gBAAgB,KACxB,OAAO,CAAC,IAAI,CA+Pd,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
- * Main entry point for generating Markdown documentation from a GraphQL schema.
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;
@@ -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)("Cannot find module 'graphql-config'!");
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({
@@ -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
@@ -1 +1 @@
1
- {"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"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"}
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.24.0",
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.1",
76
- "@graphql-markdown/graphql": "",
77
- "@graphql-markdown/logger": "",
78
- "@graphql-markdown/printer-legacy": "",
79
- "@graphql-markdown/types": "",
80
- "@graphql-markdown/utils": ""
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": {