@cparra/apexdocs 2.25.0-alpha.8 → 2.25.0-alpha.9

package/dist/cli/generate.js

@@ -9,6 +9,7 @@ var apexReflection = require('@cparra/apex-reflection');
 var O = require('fp-ts/Option');
 var fastXmlParser = require('fast-xml-parser');
 var Handlebars = require('handlebars');
+var defaults = require('../defaults-DUwru49Q.js');
 var fs = require('fs');
 var path = require('path');
 var chalk = require('chalk');
@@ -16,7 +17,6 @@ var logUpdate = require('log-update');
 var cosmiconfig = require('cosmiconfig');
 var yargs = require('yargs');
 var cosmiconfigTypescriptLoader = require('cosmiconfig-typescript-loader');
-var defaults = require('../defaults-DUwru49Q.js');
 
 function _interopNamespaceDefault(e) {
   var n = Object.create(null);
@@ -425,7 +425,7 @@ function typeToRenderable(parsedFile, linkGenerator, config) {
     }
   }
   return __spreadProps$d(__spreadValues$d({}, getRenderable()), {
-    filePath: parsedFile.filePath,
+    filePath: parsedFile.source.filePath,
     namespace: config.namespace
   });
 }
@@ -569,116 +569,53 @@ function singleGroup(headingLevel, groupName, adapter, members, linkGenerator) {
   };
 }
 
-function parsedFilesToRenderableBundle(config, parsedFiles) {
-  return parsedFiles.reduce(
-    (acc, parsedFile) => {
-      var _a;
-      const renderable = typeToRenderable(
-        parsedFile,
-        (referenceName) => {
-          return linkFromTypeNameGenerator(
-            parsedFile.type,
-            parsedFiles.map((file) => file.type),
-            referenceName,
-            config
-          );
-        },
-        config
-      );
-      acc.renderables.push(renderable);
-      const descriptionLines = (_a = parsedFile.type.docComment) == null ? void 0 : _a.descriptionLines;
-      const reference = {
-        typeName: parsedFile.type.name,
-        directory: getDirectoryFromRoot(config, parsedFile.type),
-        title: getLinkFromRoot(config, parsedFile.type),
-        description: adaptDescribable(
-          descriptionLines,
-          (referenceName) => getPossibleLinkFromRoot(
-            config,
-            referenceName,
-            findType(
-              parsedFiles.map((file) => file.type),
-              referenceName
-            )
-          )
-        ).description
-      };
-      const group = getTypeGroup(parsedFile.type, config);
-      if (!acc.references[group]) {
-        acc.references[group] = [];
-      }
-      acc.references[group].push(reference);
+function parsedFilesToRenderableBundle(config, parsedFiles, references) {
+  const referenceFinder = apply(linkGenerator, references);
+  function toReferenceGuide(parsedFiles2) {
+    return parsedFiles2.reduce(
+      addToReferenceGuide(referenceFinder, config, references),
+      {}
+    );
+  }
+  function toRenderables(parsedFiles2) {
+    return parsedFiles2.reduce((acc, parsedFile) => {
+      const renderable = typeToRenderable(parsedFile, referenceFinder, config);
+      acc.push(renderable);
       return acc;
-    },
-    {
-      references: {},
-      renderables: []
-    }
-  );
-}
-function linkFromTypeNameGenerator(typeBeingDocumented, repository, referenceName, config) {
-  const type = findType(repository, referenceName);
-  if (!type) {
-    return referenceName;
+    }, []);
   }
-  const [fullClassName, fileLink] = getFileLinkTuple(typeBeingDocumented, type, config);
   return {
-    __type: "link",
-    title: fullClassName,
-    url: fileLink
+    referencesByGroup: toReferenceGuide(parsedFiles),
+    renderables: toRenderables(parsedFiles)
   };
 }
-function getPossibleLinkFromRoot(config, fallback, type) {
-  if (!type) {
-    return fallback;
-  }
-  const namespacePrefix = config.namespace ? `${config.namespace}.` : "";
-  const title = `${namespacePrefix}${type.name}`;
-  return {
-    __type: "link",
-    title,
-    url: `${getDirectoryFromRoot(config, type)}/${title}.md`
+function addToReferenceGuide(findLinkFromHome, config, references) {
+  return (acc, parsedFile) => {
+    var _a, _b;
+    const group = getTypeGroup$1(parsedFile.type, config);
+    if (!acc[group]) {
+      acc[group] = [];
+    }
+    acc[group].push({
+      reference: references[parsedFile.type.name],
+      title: findLinkFromHome(parsedFile.type.name),
+      description: (_b = adaptDescribable((_a = parsedFile.type.docComment) == null ? void 0 : _a.descriptionLines, findLinkFromHome).description) != null ? _b : null
+    });
+    return acc;
   };
 }
-function getDirectoryFromRoot(config, type) {
-  if (!type) {
-    return "";
-  }
-  return `./${getSanitizedGroup(type, config)}`;
-}
-function findType(repository, referenceName) {
-  return repository.find((currentType) => currentType.name.toLowerCase() === referenceName.toLowerCase());
-}
-function getFileLinkTuple(typeBeingDocumented, referencedType, config) {
-  const namespacePrefix = config.namespace ? `${config.namespace}.` : "";
-  const directoryRoot = `${getDirectoryRoot(typeBeingDocumented, referencedType, config)}`;
-  const fullClassName = `${namespacePrefix}${referencedType.name}`;
-  return [fullClassName, `${directoryRoot}${fullClassName}.md`];
-}
-function getDirectoryRoot(typeBeingDocumented, referencedType, config) {
-  if (getTypeGroup(typeBeingDocumented, config) === getTypeGroup(referencedType, config)) {
-    return "./";
-  } else {
-    return `../${getSanitizedGroup(referencedType, config)}/`;
-  }
-}
-function getTypeGroup(type, config) {
+const linkGenerator = (references, referenceName) => {
+  const reference = references[referenceName];
+  return reference ? (
+    // Starting the path with a "/" will ensure the link will always be relative to the root of the site.
+    { __type: "link", title: reference.displayName, url: `/${reference.pathFromRoot}` }
+  ) : referenceName;
+};
+function getTypeGroup$1(type, config) {
   var _a, _b;
   const groupAnnotation = (_a = type.docComment) == null ? void 0 : _a.annotations.find((annotation) => annotation.name.toLowerCase() === "group");
   return (_b = groupAnnotation == null ? void 0 : groupAnnotation.body) != null ? _b : config.defaultGroupName;
 }
-function getSanitizedGroup(classModel, config) {
-  return getTypeGroup(classModel, config).replace(/ /g, "-").replace(".", "");
-}
-function getLinkFromRoot(config, type) {
-  const namespacePrefix = config.namespace ? `${config.namespace}.` : "";
-  const title = `${namespacePrefix}${type.name}`;
-  return {
-    __type: "link",
-    title,
-    url: `${getDirectoryFromRoot(config, type)}/${title}.md`
-  };
-}
 
 function parseApexMetadata(input) {
   var _a;
@@ -730,7 +667,11 @@ function reflectSourceBody(apexBundle) {
   const { filePath, content: input, metadataContent: metadata } = apexBundle;
   const result = apexReflection.reflect(input);
   return result.error ? E__namespace.left(new ReflectionError(filePath, result.error.message)) : E__namespace.right({
-    filePath,
+    source: {
+      filePath,
+      name: result.typeMirror.name,
+      type: result.typeMirror.type_name
+    },
     type: addFileMetadataToTypeAnnotation(result.typeMirror, metadata)
   });
 }
@@ -1249,15 +1190,15 @@ const link = (source) => {
   }
 };
 
-const convertToDocumentationBundle = (referenceGuideTemplate, { references, renderables }) => ({
+const convertToDocumentationBundle = (referenceGuideTemplate, { referencesByGroup, renderables }) => ({
   referenceGuide: {
-    directory: "",
     frontmatter: null,
-    content: referencesToReferenceGuideContent(references, referenceGuideTemplate),
-    fileExtension: "md",
-    fileName: "index"
+    content: referencesToReferenceGuideContent(referencesByGroup, referenceGuideTemplate),
+    filePath: "index.md"
   },
-  docs: renderables.map((renderable) => renderableToPageData(Object.values(references).flat(), renderable))
+  docs: renderables.map(
+    (renderable) => renderableToPageData(Object.values(referencesByGroup).flat(), renderable)
+  )
 });
 function referencesToReferenceGuideContent(references, template) {
   function alphabetizeReferences(references2) {
@@ -1279,21 +1220,18 @@ function renderableToPageData(referenceGuideReference, renderable) {
   function buildDocOutput(renderable2, docContents) {
     var _a;
     const reference = referenceGuideReference.find(
-      (ref) => ref.typeName.toLowerCase() === renderable2.name.toLowerCase()
+      (ref) => ref.reference.source.name.toLowerCase() === renderable2.name.toLowerCase()
     );
-    const namespacePrefix = renderable2.namespace ? `${renderable2.namespace}.` : "";
     return {
       source: {
         filePath: renderable2.filePath,
         name: renderable2.name,
         type: renderable2.type
       },
-      fileName: `${namespacePrefix}${renderable2.name}`,
-      fileExtension: "md",
-      directory: `${reference == null ? void 0 : reference.directory}`,
+      filePath: reference.reference.pathFromRoot,
       frontmatter: null,
       content: docContents,
-      group: (_a = renderable2.doc.group) != null ? _a : "Miscellaneous"
+      group: (_a = renderable2.doc.group) != null ? _a : defaults.defaults.defaultGroupName
     };
   }
   return _function.pipe(renderable, resolveApexTypeTemplate, compile, (docContents) => buildDocOutput(renderable, docContents));
@@ -1501,6 +1439,28 @@ function isSkip(value) {
   return Object.prototype.hasOwnProperty.call(value, "_tag") && value._tag === "Skip";
 }
 
+function parsedFilesToReferenceGuide(config, parsedFiles) {
+  return parsedFiles.reduce((acc, parsedFile) => {
+    acc[parsedFile.type.name] = parsedFileToDocPageReference(config, parsedFile);
+    return acc;
+  }, {});
+}
+function parsedFileToDocPageReference(config, parsedFile) {
+  return {
+    source: parsedFile.source,
+    displayName: parsedFile.type.name,
+    pathFromRoot: `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`
+  };
+}
+function getTypeGroup(type, config) {
+  var _a, _b;
+  const groupAnnotation = (_a = type.docComment) == null ? void 0 : _a.annotations.find((annotation) => annotation.name.toLowerCase() === "group");
+  return (_b = groupAnnotation == null ? void 0 : groupAnnotation.body) != null ? _b : config.defaultGroupName;
+}
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-").replace(/-+/g, "-");
+}
+
 var __defProp$7 = Object.defineProperty;
 var __defProps$7 = Object.defineProperties;
 var __getOwnPropDescs$7 = Object.getOwnPropertyDescriptors;
@@ -1548,6 +1508,7 @@ class HookError {
 }
 function generateDocs(apexBundles, config) {
   const filterOutOfScope = apply(filterScope, config.scope);
+  const convertToReferences = apply(parsedFilesToReferenceGuide, config);
   const convertToRenderableBundle = apply(parsedFilesToRenderableBundle, config);
   const convertToDocumentationBundleForTemplate = apply(convertToDocumentationBundle, config.referenceGuideTemplate);
   const sortTypeMembers = apply(sortMembers, config.sortMembersAlphabetically);
@@ -1559,52 +1520,50 @@ function generateDocs(apexBundles, config) {
     E__namespace.map(addInheritedMembersToTypes),
     E__namespace.map(addInheritanceChainToTypes),
     E__namespace.map(sortTypeMembers),
-    E__namespace.map(convertToRenderableBundle),
-    E__namespace.map(convertToDocumentationBundleForTemplate),
+    E__namespace.bindTo("parsedFiles"),
+    E__namespace.bind("references", ({ parsedFiles }) => E__namespace.right(convertToReferences(parsedFiles))),
     TE__namespace.fromEither,
-    TE__namespace.flatMap(
-      (bundle) => TE__namespace.tryCatch(
-        () => documentationBundleHook(bundle, config),
-        (error) => new HookError(error)
-      )
-    ),
-    TE__namespace.map((bundle) => ({
-      referenceGuide: isSkip(bundle.referenceGuide) ? bundle.referenceGuide : __spreadProps$7(__spreadValues$7({}, bundle.referenceGuide), {
-        content: Template.getInstance().compile({
-          source: {
-            frontmatter: toFrontmatterString(bundle.referenceGuide.frontmatter),
-            content: bundle.referenceGuide.content
-          },
-          template: hookableTemplate
-        })
-      }),
-      docs: bundle.docs.map((doc) => __spreadProps$7(__spreadValues$7({}, doc), {
-        content: Template.getInstance().compile({
-          source: {
-            frontmatter: toFrontmatterString(doc.frontmatter),
-            content: doc.content
-          },
-          template: hookableTemplate
-        })
-      }))
-    }))
+    TE__namespace.flatMap(({ parsedFiles, references }) => transformReferenceHook(config)({ references, parsedFiles })),
+    TE__namespace.map(({ parsedFiles, references }) => convertToRenderableBundle(parsedFiles, references)),
+    TE__namespace.map(convertToDocumentationBundleForTemplate),
+    TE__namespace.flatMap(transformDocumentationBundleHook(config)),
+    TE__namespace.map(postHookCompile)
   );
 }
-function toFrontmatterString(frontmatter) {
-  if (typeof frontmatter === "string") {
-    return frontmatter;
-  }
-  if (!frontmatter) {
-    return "";
+function transformReferenceHook(config) {
+  function _execute(references, parsedFiles, transformReference) {
+    return __async$2(this, null, function* () {
+      return {
+        references: yield execTransformReferenceHook(Object.values(references), transformReference),
+        parsedFiles
+      };
+    });
   }
-  const yamlString = yaml.dump(frontmatter);
-  return `---
-${yamlString}---
-`;
+  return ({ references, parsedFiles }) => TE__namespace.tryCatch(
+    () => _execute(references, parsedFiles, config.transformReference),
+    (error) => new HookError(error)
+  );
+}
+function transformDocumentationBundleHook(config) {
+  return (bundle) => TE__namespace.tryCatch(
+    () => documentationBundleHook(bundle, config),
+    (error) => new HookError(error)
+  );
 }
 function passThroughHook(value) {
   return value;
 }
+const execTransformReferenceHook = (_0, ..._1) => __async$2(void 0, [_0, ..._1], function* (references, hook = passThroughHook) {
+  const hooked = references.map((reference) => __async$2(void 0, null, function* () {
+    const hookedResult = yield hook(reference);
+    return __spreadValues$7(__spreadValues$7({}, reference), hookedResult);
+  }));
+  const awaited = yield Promise.all(hooked);
+  return awaited.reduce((acc, reference) => {
+    acc[reference.source.name] = reference;
+    return acc;
+  }, {});
+});
 const documentationBundleHook = (bundle, config) => __async$2(void 0, null, function* () {
   return {
     referenceGuide: yield transformReferenceGuide(bundle.referenceGuide, config.transformReferenceGuide),
@@ -1625,6 +1584,40 @@ const transformDocs = (_0, ..._1) => __async$2(void 0, [_0, ..._1], function* (d
 const transformDocPage = (_0, ..._1) => __async$2(void 0, [_0, ..._1], function* (doc, hook = passThroughHook) {
   return __spreadValues$7(__spreadValues$7({}, doc), yield hook(doc));
 });
+function postHookCompile(bundle) {
+  return {
+    referenceGuide: isSkip(bundle.referenceGuide) ? bundle.referenceGuide : __spreadProps$7(__spreadValues$7({}, bundle.referenceGuide), {
+      content: Template.getInstance().compile({
+        source: {
+          frontmatter: toFrontmatterString(bundle.referenceGuide.frontmatter),
+          content: bundle.referenceGuide.content
+        },
+        template: hookableTemplate
+      })
+    }),
+    docs: bundle.docs.map((doc) => __spreadProps$7(__spreadValues$7({}, doc), {
+      content: Template.getInstance().compile({
+        source: {
+          frontmatter: toFrontmatterString(doc.frontmatter),
+          content: doc.content
+        },
+        template: hookableTemplate
+      })
+    }))
+  };
+}
+function toFrontmatterString(frontmatter) {
+  if (typeof frontmatter === "string") {
+    return frontmatter;
+  }
+  if (!frontmatter) {
+    return "";
+  }
+  const yamlString = yaml.dump(frontmatter);
+  return `---
+${yamlString}---
+`;
+}
 
 var __defProp$6 = Object.defineProperty;
 var __defProps$6 = Object.defineProperties;
@@ -1648,18 +1641,15 @@ var __spreadProps$6 = (a, b) => __defProps$6(a, __getOwnPropDescs$6(b));
 class FileWriter {
   static write(files, outputDir, onWriteCallback) {
     files.forEach((file) => {
-      const resolvedFile = this.getTargetLocation(file, outputDir);
-      if (!fs__namespace.existsSync(resolvedFile.directory)) {
-        fs__namespace.mkdirSync(resolvedFile.directory, { recursive: true });
-      }
-      const filePath = path__namespace.join(resolvedFile.directory, `${resolvedFile.fileName}.${resolvedFile.fileExtension}`);
-      fs__namespace.writeFileSync(filePath, resolvedFile.content, "utf8");
-      onWriteCallback(resolvedFile);
+      const { filePath, content } = this.getTargetLocation(file, outputDir);
+      fs__namespace.mkdirSync(path__namespace.dirname(filePath), { recursive: true });
+      fs__namespace.writeFileSync(filePath, content, "utf8");
+      onWriteCallback(file);
     });
   }
   static getTargetLocation(file, outputDir) {
     return __spreadProps$6(__spreadValues$6({}, file), {
-      directory: path__namespace.join(outputDir, file.directory)
+      filePath: path__namespace.join(outputDir, file.filePath)
     });
   }
 }
@@ -1775,7 +1765,7 @@ function writeFilesToSystem(files, outputDir) {
     [files.referenceGuide, ...files.docs].filter((file) => !isSkip(file)),
     outputDir,
     (file) => {
-      Logger.logSingle(`${file.fileName} processed.`, false, "green", false);
+      Logger.logSingle(`${file.filePath} processed.`, false, "green", false);
     }
   );
 }
@@ -2660,9 +2650,7 @@ var __spreadProps$1 = (a, b) => __defProps$1(a, __getOwnPropDescs$1(b));
 function createOpenApiFile(fileName, openApiModel) {
   const content = JSON.stringify(__spreadProps$1(__spreadValues$1({}, openApiModel), { namespace: void 0 }), null, 2);
   return {
-    fileExtension: "json",
-    fileName,
-    directory: "",
+    filePath: "",
     content,
     frontmatter: null,
     group: null
@@ -2735,7 +2723,7 @@ function openApi(fileBodies, config) {
   Transpiler.generate(filteredTypes, processor);
   const generatedFiles = processor.fileBuilder().files();
   FileWriter.write(generatedFiles, config.targetDir, (file) => {
-    Logger.logSingle(`${file.fileName} processed.`, false, "green", false);
+    Logger.logSingle(`${file.filePath} processed.`, false, "green", false);
   });
   ErrorLogger.logErrors(filteredTypes);
 }

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 import { SetOptional } from 'type-fest';
 
+/**
+ * The configurable hooks that can be used to modify the output of the generator.
+ */
 type ConfigurableHooks = {
   transformReferenceGuide: TransformReferenceGuide;
   transformDocs: TransformDocs;
   transformDocPage: TransformDocPage;
+  transformReference: TransformReference;
 };
 
 type UserDefinedMarkdownConfig = {
@@ -17,46 +21,80 @@ type UserDefinedMarkdownConfig = {
   includeMetadata: boolean;
 } & Partial<ConfigurableHooks>;
 
+type SourceFileMetadata = {
+  filePath: string;
+  name: string;
+  type: 'interface' | 'class' | 'enum';
+};
+
+type DocPageReference = {
+  source: SourceFileMetadata;
+  // The name under which the type should be displayed in the documentation.
+  // By default, this will match the source.name, but it can be configured by the user.
+  displayName: string;
+  // The location of the file relative to the root of the documentation.
+  pathFromRoot: string;
+};
+
 type Frontmatter = string | Record<string, unknown> | null;
 
 type ReferenceGuidePageData = {
-  directory: string;
   frontmatter: Frontmatter;
   content: string;
-  fileExtension: string;
-  fileName: string;
+  filePath: string;
 };
 
 type DocPageData = {
-  source: {
-    filePath: string;
-    name: string;
-    type: 'interface' | 'class' | 'enum';
-  };
+  source: SourceFileMetadata;
   group: string | null;
-  fileName: string;
-  fileExtension: string;
-  directory: string;
+  filePath: string;
   frontmatter: Frontmatter;
   content: string;
 };
 
+/**
+ * Represents a file to be skipped.
+ */
 type Skip = {
   readonly _tag: 'Skip';
 };
 
 // Configurable Hooks
 
+type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
+
+type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'filePath'>;
+
+/**
+ * Allows changing where the files are written to.
+ */
+type TransformReference = (
+  reference: DocPageReference,
+) => Partial<ConfigurableDocPageReference> | Promise<ConfigurableDocPageReference>;
+
+/**
+ * Allows changing the frontmatter and content of the reference guide, or even if creating a reference
+ * guide will be skipped altogether.
+ */
 type TransformReferenceGuide = (
   referenceGuide: ReferenceGuidePageData,
 ) => Partial<ReferenceGuidePageData> | Skip | Promise<Partial<ReferenceGuidePageData> | Skip>;
 
+/**
+ * The main purpose if for allowing for doc pages to be skipped, but it can also be used to change the frontmatter
+ * and content of the doc pages.
+ */
 type TransformDocs = (docs: DocPageData[]) => DocPageData[] | Promise<DocPageData[]>;
 
-type TransformDocPage = (doc: DocPageData) => Partial<DocPageData> | Promise<Partial<DocPageData>>;
+/**
+ * Allows changing the frontmatter and content of the doc pages.
+ */
+type TransformDocPage = (
+  doc: DocPageData,
+) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;
 
 type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically'>, 'targetGenerator'>;
 declare function defineMarkdownConfig(config: ConfigurableMarkdownConfig): UserDefinedMarkdownConfig;
 declare function skip(): Skip;
 
-export { type ConfigurableHooks, type DocPageData, type ReferenceGuidePageData, defineMarkdownConfig, skip };
+export { type ConfigurableHooks, type DocPageData, type DocPageReference, type ReferenceGuidePageData, defineMarkdownConfig, skip };