@cparra/apexdocs 3.3.0-alpha.0 → 3.3.1

package/README.md

@@ -168,6 +168,7 @@ apexdocs openapi -s force-app -t docs -n MyNamespace --title "My Custom OpenApi
 | `--targetDir`          | `-t`  | The directory location where the changelog file will be generated. | `./docs/`   | No       |
 | `--fileName`           | N/A   | The name of the changelog file to be generated.                    | `changelog` | No       |
 | `--scope`              | N/A   | The list of scope to respect when generating the changelog.        | ['global']  | No       |
+| `--skipIfNoChanges`    | N/A   | Whether to skip generating the changelog if there are no changes.  | `true`      | No       |
 
 #### Sample Usage
 
@@ -263,9 +264,8 @@ export default {
 
 Then you only need to run the top level `apexdocs` command, and it will generate both types of documentation.
 
-```bash
-apexdocs
-```
+Note that you can still run the individual commands if you only want to generate one type of documentation by
+providing the subcommand, e.g `apexdocs markdown` or `apexdocs changelog`.
 
 ### Excluding Tags from Appearing in the Documentation
 

package/dist/cli/generate.js

@@ -1,14 +1,13 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger$1 = require('../logger-C3kCwNpQ.js');
+var logger$1 = require('../logger-Q5m1eQv2.js');
+var module$1 = require('module');
 var cosmiconfig = require('cosmiconfig');
-var yargs = require('yargs');
 var E = require('fp-ts/Either');
 var cosmiconfigTypescriptLoader = require('cosmiconfig-typescript-loader');
 var _function = require('fp-ts/function');
 require('fp-ts/TaskEither');
-require('simple-git');
 require('js-yaml');
 require('path');
 require('fp-ts/Task');
@@ -21,30 +20,34 @@ require('fp-ts/boolean');
 require('fs');
 require('fp-ts/lib/TaskEither');
 require('minimatch');
-require('node:path');
-require('node:fs');
 require('chalk');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopNamespaceDefault(e) {
-  var n = Object.create(null);
-  if (e) {
-    Object.keys(e).forEach(function (k) {
-      if (k !== 'default') {
-        var d = Object.getOwnPropertyDescriptor(e, k);
-        Object.defineProperty(n, k, d.get ? d : {
-          enumerable: true,
-          get: function () { return e[k]; }
-        });
-      }
-    });
-  }
-  n.default = e;
-  return Object.freeze(n);
+	var n = Object.create(null);
+	if (e) {
+		Object.keys(e).forEach(function (k) {
+			if (k !== 'default') {
+				var d = Object.getOwnPropertyDescriptor(e, k);
+				Object.defineProperty(n, k, d.get ? d : {
+					enumerable: true,
+					get: function () { return e[k]; }
+				});
+			}
+		});
+	}
+	n.default = e;
+	return Object.freeze(n);
 }
 
-var yargs__namespace = /*#__PURE__*/_interopNamespaceDefault(yargs);
 var E__namespace = /*#__PURE__*/_interopNamespaceDefault(E);
 
+var require$1 = (
+			false
+				? /* @__PURE__ */ module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli/generate.js', document.baseURI).href)))
+				: require
+		);
+
 const markdownOptions = {
   sourceDir: {
     type: "string",
@@ -136,18 +139,7 @@ const changeLogOptions = {
     type: "string",
     alias: "p",
     demandOption: true,
-    describe: "The directory location of the previous version of the source code. If previousGitReference is provided, this value should be the directory in which the Apex source code resides within the repository."
-  },
-  // TODO: Validate that if previousGitReference is provided, repoPath is also provided.
-  repoPath: {
-    type: "string",
-    alias: "g",
-    describe: "The path to the git repository. Must be provided if previousGitReference is provided."
-  },
-  previousGitReference: {
-    type: "string",
-    alias: "r",
-    describe: "The git reference of the previous version of the source code."
+    describe: "The directory location of the previous version of the source code."
   },
   currentVersionDir: {
     type: "string",
@@ -172,6 +164,11 @@ const changeLogOptions = {
     alias: "s",
     default: logger$1.changeLogDefaults.scope,
     describe: "The list of scope to respect when generating the changelog. Values should be separated by a space, e.g --scope global public namespaceaccessible. Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled."
+  },
+  skipIfNoChanges: {
+    type: "boolean",
+    default: logger$1.changeLogDefaults.skipIfNoChanges,
+    describe: "Skip the changelog generation if there are no changes between the previous and current version."
   }
 };
 
@@ -214,6 +211,7 @@ var __async$1 = (__this, __arguments, generator) => {
     step((generator = generator.apply(__this, __arguments)).next());
   });
 };
+const yargs = require$1("yargs");
 const configOnlyMarkdownDefaults = {
   targetGenerator: "markdown",
   excludeTags: [],
@@ -279,22 +277,32 @@ function extractArgsForCommandProvidedThroughCli(extractFromProcessFn, config) {
   }
 }
 function extractArgsForCommandsProvidedInConfig(extractFromProcessFn, config) {
-  const configs = Object.entries(config).map(([generator, generatorConfig]) => {
+  const providedThroughCli = yargs.parseSync(extractFromProcessFn());
+  const hasACommandBeenProvided = providedThroughCli._.length > 0;
+  const configs = Object.entries(config).filter(([generator]) => hasACommandBeenProvided ? providedThroughCli._[0] === generator : true).map(([generator, generatorConfig]) => {
     switch (generator) {
       case "markdown":
         return _function.pipe(
-          validateMultiCommandConfig(extractFromProcessFn, "markdown", generatorConfig),
-          E__namespace.map(() => __spreadValues(__spreadValues({}, configOnlyMarkdownDefaults), generatorConfig))
+          extractMultiCommandConfig(extractFromProcessFn, "markdown", generatorConfig),
+          E__namespace.map((cliArgs) => {
+            console.log("markdown", cliArgs);
+            return cliArgs;
+          }),
+          E__namespace.map((cliArgs) => __spreadValues(__spreadValues(__spreadValues({}, configOnlyMarkdownDefaults), generatorConfig), cliArgs))
         );
       case "openapi":
         return _function.pipe(
-          validateMultiCommandConfig(extractFromProcessFn, "openapi", generatorConfig),
-          E__namespace.map(() => __spreadValues(__spreadValues({}, configOnlyOpenApiDefaults), generatorConfig))
+          extractMultiCommandConfig(extractFromProcessFn, "openapi", generatorConfig),
+          E__namespace.map((cliArgs) => __spreadValues(__spreadValues(__spreadValues({}, configOnlyOpenApiDefaults), generatorConfig), cliArgs))
         );
       case "changelog":
         return _function.pipe(
-          validateMultiCommandConfig(extractFromProcessFn, "changelog", generatorConfig),
-          E__namespace.map(() => __spreadValues(__spreadValues({}, configOnlyChangelogDefaults), generatorConfig))
+          extractMultiCommandConfig(extractFromProcessFn, "changelog", generatorConfig),
+          E__namespace.map((cliArgs) => {
+            console.log("changelog", cliArgs);
+            return cliArgs;
+          }),
+          E__namespace.map((cliArgs) => __spreadValues(__spreadValues(__spreadValues({}, configOnlyChangelogDefaults), generatorConfig), cliArgs))
         );
     }
   });
@@ -321,21 +329,21 @@ function getConfigType(config) {
   return E__namespace.right({ _type: "single-command-config" });
 }
 function extractYargsDemandingCommand(extractFromProcessFn, config) {
-  return yargs__namespace.config(config.config).command(
+  return yargs.config(config.config).command(
     "markdown",
     "Generate documentation from Apex classes as a Markdown site.",
     (yargs2) => yargs2.options(markdownOptions)
   ).command(
     "openapi",
     "Generate an OpenApi REST specification from Apex classes.",
-    () => yargs__namespace.options(openApiOptions)
+    () => yargs.options(openApiOptions)
   ).command(
     "changelog",
     "Generate a changelog from 2 versions of the source code.",
-    () => yargs__namespace.options(changeLogOptions)
+    () => yargs.options(changeLogOptions)
   ).demandCommand().parseSync(extractFromProcessFn());
 }
-function validateMultiCommandConfig(extractFromProcessFn, command, config) {
+function extractMultiCommandConfig(extractFromProcessFn, command, config) {
   function getOptions(generator) {
     switch (generator) {
       case "markdown":
@@ -347,19 +355,11 @@ function validateMultiCommandConfig(extractFromProcessFn, command, config) {
     }
   }
   const options = getOptions(command);
+  console.log("config", config);
   return E__namespace.tryCatch(() => {
-    yargs__namespace.config(config).options(options).check((argv) => {
-      if (argv._.length > 0) {
-        throw new Error(
-          `Unexpected command "${argv._[0]}". 
-            The command name should be provided in the configuration when using the current configuration format.`
-        );
-      } else {
-        return true;
-      }
-    }).fail((msg) => {
+    return yargs(extractFromProcessFn()).config(config).options(options).fail((msg) => {
       throw new Error(`Invalid configuration for command "${command}": ${msg}`);
-    }).parse(extractFromProcessFn());
+    }).parseSync();
   }, E__namespace.toError);
 }
 

package/dist/index.d.ts

@@ -40,13 +40,12 @@ type UserDefinedOpenApiConfig = {
 type UserDefinedChangelogConfig = {
   targetGenerator: 'changelog';
   previousVersionDir: string;
-  repoPath?: string;
-  previousGitReference?: string;
   currentVersionDir: string;
   targetDir: string;
   fileName: string;
   scope: string[];
   exclude: string[];
+  skipIfNoChanges: boolean;
 };
 
 type UserDefinedConfig = UserDefinedMarkdownConfig | UserDefinedOpenApiConfig | UserDefinedChangelogConfig;
@@ -138,6 +137,11 @@ type TransformDocPage = (
   doc: DocPageData,
 ) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;
 
+/**
+ * Represents a file to be skipped.
+ */
+declare function skip(): Skip;
+
 type CallableConfig = Partial<UserDefinedConfig> & {
     sourceDir: string;
     targetGenerator: Generators;
@@ -166,9 +170,5 @@ type ConfigurableChangelogConfig = Omit<Partial<UserDefinedChangelogConfig>, 'ta
  * @param config The configuration to use.
  */
 declare function defineChangelogConfig(config: ConfigurableChangelogConfig): Partial<UserDefinedChangelogConfig>;
-/**
- * Represents a file to be skipped.
- */
-declare function skip(): Skip;
 
 export { type ConfigurableChangelogConfig, type ConfigurableDocPageData, type ConfigurableDocPageReference, type ConfigurableHooks, type ConfigurableMarkdownConfig, type ConfigurableOpenApiConfig, type DocPageData, type DocPageReference, type ReferenceGuidePageData, type Skip, type TransformDocPage, type TransformDocs, type TransformReference, type TransformReferenceGuide, defineChangelogConfig, defineMarkdownConfig, defineOpenApiConfig, process, skip };

package/dist/index.js

@@ -1,10 +1,9 @@
 'use strict';
 
-var logger = require('./logger-C3kCwNpQ.js');
+var logger = require('./logger-Q5m1eQv2.js');
 var E = require('fp-ts/Either');
 require('fp-ts/function');
 require('fp-ts/TaskEither');
-require('simple-git');
 require('js-yaml');
 require('path');
 require('fp-ts/Task');
@@ -17,8 +16,6 @@ require('fp-ts/boolean');
 require('fs');
 require('fp-ts/lib/TaskEither');
 require('minimatch');
-require('node:path');
-require('node:fs');
 require('chalk');
 
 function _interopNamespaceDefault(e) {
@@ -140,14 +137,9 @@ function defineChangelogConfig(config) {
     targetGenerator: "changelog"
   });
 }
-function skip() {
-  return {
-    _tag: "Skip"
-  };
-}
 
+exports.skip = logger.skip;
 exports.defineChangelogConfig = defineChangelogConfig;
 exports.defineMarkdownConfig = defineMarkdownConfig;
 exports.defineOpenApiConfig = defineOpenApiConfig;
 exports.process = process;
-exports.skip = skip;

package/dist/{logger-DIyKhj0a.js → logger-Q5m1eQv2.js}

@@ -1355,7 +1355,8 @@ const openApiDefaults = __spreadProps$b(__spreadValues$b({}, commonDefaults), {
 const changeLogDefaults = __spreadProps$b(__spreadValues$b({}, commonDefaults), {
   fileName: "changelog",
   scope: ["global"],
-  exclude: []
+  exclude: [],
+  skipIfNoChanges: true
 });
 
 const convertToDocumentationBundle = (referenceGuideTitle, referenceGuideTemplate, { referencesByGroup, renderables }) => ({
@@ -1603,6 +1604,11 @@ function sortClassMembers(shouldSort, classType) {
   });
 }
 
+function skip() {
+  return {
+    _tag: "Skip"
+  };
+}
 function isSkip(value) {
   return Object.prototype.hasOwnProperty.call(value, "_tag") && value._tag === "Skip";
 }
@@ -3057,6 +3063,9 @@ function areMethodsEqual(method1, method2) {
   return true;
 }
 
+function hasChanges(changelog) {
+  return changelog.newTypes.length > 0 || changelog.removedTypes.length > 0 || changelog.newOrModifiedMembers.length > 0;
+}
 function processChangelog(oldVersion, newVersion) {
   return {
     newTypes: getNewTypes(oldVersion, newVersion),
@@ -3313,18 +3322,22 @@ function generateChangeLog(oldBundles, newBundles, config) {
     return _function.pipe(reflectBundles(sourceFiles), TE__namespace.map(filterOutOfScope));
   }
   const convertToPageData = apply(toPageData, config.fileName);
+  function handleConversion({ changelog, newManifest }) {
+    if (config.skipIfNoChanges && !hasChanges(changelog)) {
+      return skip();
+    }
+    return _function.pipe(convertToRenderableChangelog(changelog, newManifest.types), compile, convertToPageData);
+  }
   return _function.pipe(
     reflect(oldBundles),
     TE__namespace.bindTo("oldVersion"),
     TE__namespace.bind("newVersion", () => reflect(newBundles)),
     TE__namespace.map(toManifests),
     TE__namespace.map(({ oldManifest, newManifest }) => ({
-      changeLog: processChangelog(oldManifest, newManifest),
+      changelog: processChangelog(oldManifest, newManifest),
       newManifest
     })),
-    TE__namespace.map(({ changeLog, newManifest }) => convertToRenderableChangelog(changeLog, newManifest.types)),
-    TE__namespace.map(compile),
-    TE__namespace.map(convertToPageData)
+    TE__namespace.map(handleConversion)
   );
 }
 function toManifests({ oldVersion, newVersion }) {
@@ -3353,15 +3366,19 @@ function toPageData(fileName, content) {
 }
 
 function generate(oldBundles, newBundles, config) {
-  return _function.pipe(
-    generateChangeLog(oldBundles, newBundles, config),
-    TE__namespace.flatMap((files) => writeFilesToSystem(files, config.targetDir))
-  );
+  function handleFile(file) {
+    if (isSkip(file)) {
+      return TE__namespace.right("\u2714\uFE0F Done! Skipped writing files to the system.");
+    }
+    return writeFilesToSystem(file, config.targetDir);
+  }
+  return _function.pipe(generateChangeLog(oldBundles, newBundles, config), TE__namespace.flatMap(handleFile));
 }
 function writeFilesToSystem(pageData, outputDir) {
   return _function.pipe(
     [pageData],
     (files) => writeFiles(files, outputDir),
+    TE__namespace.map(() => "\u2714\uFE0F Changelog generated successfully!"),
     TE__namespace.mapLeft((error) => {
       return new FileWritingError("An error occurred while writing files to the system.", error);
     })
@@ -3583,7 +3600,6 @@ function processChangeLog(config) {
     return _function.pipe(
       TE__namespace.tryCatch(loadFiles, (e) => new FileReadingError("An error occurred while reading files.", e)),
       TE__namespace.flatMap(([previous, current]) => generate(previous, current, config)),
-      TE__namespace.map(() => "\u2714\uFE0F Changelog generated successfully!"),
       TE__namespace.mapLeft(toErrors)
     );
   });
@@ -3656,3 +3672,4 @@ exports.StdOutLogger = StdOutLogger;
 exports.changeLogDefaults = changeLogDefaults;
 exports.markdownDefaults = markdownDefaults;
 exports.openApiDefaults = openApiDefaults;
+exports.skip = skip;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.3.0-alpha.0",
+  "version": "3.3.1",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",
@@ -21,7 +21,7 @@
   "scripts": {
     "test": "npm run build && jest",
     "test:cov": "npm run build && jest --coverage",
-    "build": "rimraf ./lib && npm run lint && tsc --noEmit && pkgroll",
+    "build": "rimraf ./dist && npm run lint && tsc --noEmit && pkgroll",
     "lint": "eslint \"./src/**/*.{js,ts}\" --quiet --fix",
     "prepare": "npm run build",
     "version": "npm run format && git add -A src",
@@ -61,7 +61,7 @@
     ]
   },
   "dependencies": {
-    "@cparra/apex-reflection": "2.13.1",
+    "@cparra/apex-reflection": "2.15.0",
     "@types/js-yaml": "^4.0.9",
     "@types/yargs": "^17.0.32",
     "chalk": "^4.1.2",
@@ -72,7 +72,6 @@
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.0",
     "minimatch": "^10.0.1",
-    "simple-git": "^3.27.0",
     "yargs": "^17.7.2"
   },
   "imports": {

package/dist/defaults-BcE8DTat.js

@@ -1,13 +0,0 @@
-'use strict';
-
-const defaults = {
-  targetGenerator: "markdown",
-  targetDir: "./docs/",
-  scope: ["global"],
-  defaultGroupName: "Miscellaneous",
-  includeMetadata: false,
-  sortAlphabetically: false,
-  linkingStrategy: "relative"
-};
-
-exports.defaults = defaults;

package/dist/defaults-D07y_bq4.js

@@ -1,40 +0,0 @@
-'use strict';
-
-var __defProp = Object.defineProperty;
-var __defProps = Object.defineProperties;
-var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
-var __getOwnPropSymbols = Object.getOwnPropertySymbols;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __propIsEnum = Object.prototype.propertyIsEnumerable;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues = (a, b) => {
-  for (var prop in b || (b = {}))
-    if (__hasOwnProp.call(b, prop))
-      __defNormalProp(a, prop, b[prop]);
-  if (__getOwnPropSymbols)
-    for (var prop of __getOwnPropSymbols(b)) {
-      if (__propIsEnum.call(b, prop))
-        __defNormalProp(a, prop, b[prop]);
-    }
-  return a;
-};
-var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
-const commonDefaults = {
-  targetDir: "./docs/"
-};
-const markdownDefaults = __spreadProps(__spreadValues({}, commonDefaults), {
-  scope: ["global"],
-  defaultGroupName: "Miscellaneous",
-  includeMetadata: false,
-  sortAlphabetically: false,
-  linkingStrategy: "relative",
-  referenceGuideTitle: "Apex Reference Guide"
-});
-const openApiDefaults = __spreadProps(__spreadValues({}, commonDefaults), {
-  fileName: "openapi",
-  title: "Apex REST API",
-  apiVersion: "1.0.0"
-});
-
-exports.markdownDefaults = markdownDefaults;
-exports.openApiDefaults = openApiDefaults;

package/dist/defaults-DGKfeZq-.js

@@ -1,13 +0,0 @@
-'use strict';
-
-const defaults = {
-  targetGenerator: "markdown",
-  targetDir: "./docs/",
-  scope: ["global"],
-  defaultGroupName: "Miscellaneous",
-  includeMetadata: false,
-  sortMembersAlphabetically: false,
-  linkingStrategy: "relative"
-};
-
-exports.defaults = defaults;

package/dist/defaults-gPzwP66p.js

@@ -1,14 +0,0 @@
-'use strict';
-
-const defaults = {
-  targetGenerator: "markdown",
-  targetDir: "./docs/",
-  scope: ["global"],
-  defaultGroupName: "Miscellaneous",
-  includeMetadata: false,
-  sortAlphabetically: false,
-  linkingStrategy: "relative",
-  referenceGuideTitle: "Apex Reference Guide"
-};
-
-exports.defaults = defaults;