From 0eb9af613b91e499d442ea0d5d6f03be613690ea Mon Sep 17 00:00:00 2001
From: Erik Golinelli <erik@codekraft.it>
Date: Tue, 12 Dec 2023 14:16:42 +0100
Subject: [PATCH] Refactor code and update documentation

Functionality for new input variables 'tsconfig_file' and 'options' were incorporated. Also, support for Node.js 16 has been announced in the README, as well as an updated table of input variables and their details. The 'config_file' input variable has been removed.
---
 README.md    | 91 ++++++++++++++++++++++++++++++++-----------------
 action.yml   |  9 +++--
 lib/index.js | 85 ++++++++++++++++++++++++++++++++++------------
 src/index.ts | 95 ++++++++++++++++++++++++++++++++++++++--------------
 4 files changed, 199 insertions(+), 81 deletions(-)

diff --git a/README.md b/README.md
index 71055df..545cce9 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ The following example [workflow step](https://help.github.com/en/actions/configu
 
 ## Supported platforms
 
-The tsdoc-action is a JavaScript action and is supported on both Linux, MacOS, and Windows. The action supports stable versions of Node.js 14 and later.
+The tsdoc-action is a JavaScript action and is supported on both Linux, MacOS, and Windows. The action supports stable versions of Node.js 16 and later.
 
 | OS (runs-on) | ubuntu-latest | macos-latest | windows-latest |
 | ---          |:---:          |:---:         |:---:           |
@@ -29,37 +29,67 @@ The tsdoc-action is a JavaScript action and is supported on both Linux, MacOS, a
 
 The following input variables options can/must be configured:
 
-| Input variable         |Necessity|Description|Default|
-|------------------------|----|----|----|
-| `source_dir`           |Optional|Source directory to build documentation from.||
-| `output_dir`           |Optional|Output folder for the generated documentation.|`./out`|
-| `config_file`          |Optional|The path to a TypeDoc configuration file.||
-| `theme`                |Optional|The TypeDoc template or theme to install. Will run `npm install template`.||
-| `theme_dir`            |Optional|The relative location of the template files directory within the template package.||
-| `front_page`           |Optional|The path to a Markdown file to be used as a the front page. Normally `README.md`.||
-| `excludeInternal`      |Optional|Removes symbols annotated with the `@internal` doc tag.|`true`|
-| `excludePrivate`       |Optional|Removes private class members from the generated documentation.|`false`|
-| `excludeProtected`     |Optional|Removes protected class members from the generated documentation.|`false`|
-| `excludeReferences`    |Optional|Removes re-exports of a symbol already included in the documentation from the documentation.|`false`|
-| `excludeCategories`    |Optional|Removes reflections associated with any of the given categories.||
-| `name`                 |Optional|Set the name of the project that will be used in the header of the template.|Package name from package.json|
-| `includeVersion`       |Optional|Includes the version according to package.json in generated documentation.|`false`|
-| `disableSources`       |Optional|Disables capturing where reflections are declared when converting input.|`false`|
-| `sourceLinkTemplate`   |Optional|Specify a link template to be used when generating source urls.||
-| `gitRevision`          |Optional|Use specified revision or branch instead of the last revision for linking to source files.||
-| `gitRemote`            |Optional|Use the specified git remote instead of origin for linking to source files.||
-| `disableGit`           |Optional|Prevents TypeDoc from using Git to try to determine if sources can be linked.|`false`|
-| `readme`               |Optional|Path to the readme file that should be displayed on the index page.||
-| `stripYamlFrontmatter` |Optional|Remove YAML frontmatter from the readme file displayed on the main page.|`false`|
-
-## Templates 💅
+Certainly! Here's an updated version of your README table with some corrections and additions:
+
+| Input variable              |Necessity| Description                                                                                                                                           | Default                       |
+|-----------------------------|----|-------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|
+| `entryPoints`               |Optional| Entry points for TypeDoc to analyze. same as `source_dir`                                                                                             |                               |
+| `output_dir`                |Optional| Output folder for the generated documentation.                                                                                                        | `./out`                       |
+| `options`                   |Optional| The path to a TypeDoc configuration file. see https://typedoc.org/options/configuration/#options                                                      |                               |
+| `tsconfig`                  |Optional| The path to a tsconfig.json file. Defaults to ./tsconfig.json                                                                                         | `./tsconfig.json `            |
+| `name`                      |Optional| Set the name of the project that will be used in the header of the template.                                                                          | Package name from package.json |
+| `titleLink`                 |Optional| Link the title in the header points to.                                                                                                               |                               |
+| `entryPointStrategy`        |Optional| Strategy for determining entry points. Valid options are 'resolve' or 'packages'.                                                                     |                               |
+| `install_module`            |Optional| The Plugin, theme, template npm package name that you need to install.                                                                                |                               | 
+| `plugin`                    |Optional| The TypeDoc plugin that you want to use. Requires to be installed using `install_module`.                                                   |                               |
+| `theme`                     |Optional| The TypeDoc template or theme. Requires the theme to be installed using `install_module`.                                                             |                               |
+| `theme_dir`                 |Optional| The relative location of the template files directory within the template package.                                                                    |                               |
+| `themeColor`                |Optional| The base color for your theme/template.                                                                                                               |                               |
+| `front_page`                |Optional| The path to a Markdown file to be used as the front page. Normally `README.md`.                                                                       |                               |
+| `basePath`                  |Optional| Base path to be used when displaying file paths.                                                                                                      |                               |
+| `excludeInternal`           |Optional| Removes symbols annotated with the `@internal` doc tag.                                                                                               | `true`                        |
+| `excludePrivate`            |Optional| Removes private class members from the generated documentation.                                                                                       | `false`                       |
+| `excludeProtected`          |Optional| Removes protected class members from the generated documentation.                                                                                     | `false`                       |
+| `excludeReferences`         |Optional| Removes re-exports of a symbol already included in the documentation from the documentation.                                                          | `false`                       |
+| `excludeCategories`         |Optional| Removes reflections associated with any of the given categories.                                                                                      |                               |
+| `includeVersion`            |Optional| Includes the version according to package.json in generated documentation.                                                                            | `false`                       |
+| `disableSources`            |Optional| Disables capturing where reflections are declared when converting input.                                                                              | `false`                       |
+| `sourceLinkTemplate`        |Optional| Specify a link template to be used when generating source urls.                                                                                       |                               |
+| `gitRevision`               |Optional| Use specified revision or branch instead of the last revision for linking to source files.                                                            |                               |
+| `gitRemote`                 |Optional| Use the specified git remote instead of origin for linking to source files.                                                                           |                               |
+| `disableGit`                |Optional| Prevents TypeDoc from using Git to try to determine if sources can be linked.                                                                         | `false`                       |
+| `readme`                    |Optional| Path to the readme file that should be displayed on the index page.                                                                                   |                               |
+| `stripYamlFrontmatter`      |Optional| Remove YAML frontmatter from the readme file displayed on the main page.                                                                              | `false`                       |
+| `lightHighlightTheme`       |Optional| The Shiki theme to be used to highlight code snippets in light mode.                                                                                  |                               |
+| `darkHighlightTheme`        |Optional| The Shiki theme to be used to highlight code snippets in dark mode.                                                                                   |                               |
+| `customCss`                 |Optional| Extra CSS file to be copied into the assets directory and referenced by the theme.                                                                    |                               |
+| `markedOptions`             |Optional| Options to be forwarded to Marked when parsing doc comments.                                                                                          |                               |
+| `cname`                     |Optional| Text for creating a CNAME file in the output directory.                                                                                               |                               |
+| `sourceLinkExternal`        |Optional| Treat source links as external links that open in a new tab when generating HTML.                                                                     |                               |
+| `htmlLang`                  |Optional| Sets the lang attribute in TypeDocs HTML output.                                                                                                      |                               |
+| `githubPages`               |Optional| Automatically add a .nojekyll file to the output directory to prevent GitHub Pages from processing your documentation site using Jekyll.              |                               |
+| `cacheBust`                 |Optional| Include the generation time in <script> and <link> tags to JS/CSS assets to prevent assets from a previous build of the documentation from being used. |                               |
+| `gaID`                      |Optional| Set the Google Analytics tracking ID and activate tracking code.                                                                                      |                               |
+| `hideParameterTypesInTitle` |Optional| Hide parameter types in the signature "title" for easier scanning.                                                                                    |                               |
+| `hideGenerator`             |Optional| Do not print the TypeDoc link at the end of the page.                                                                                                 |                               |
+| `searchInComments`          |Optional| Enables searching comment text in the generated documentation site.                                                                                   |                               |
+| `cleanOutputDir`            |Optional| Prevent TypeDoc from cleaning the output directory specified with --out.                                                                              |                               |
+| `externalPattern`           |Optional| Patterns for external packages that should be included in the documentation.                                                                          |                               |
+| `excludeExternals`          |Optional| Prevent externally resolved TypeScript files from being documented. Defaults to `false`.                                                              | `false`                       |
+| `excludeNotDocumented`      |Optional| Exclude symbols that are not explicitly documented. Defaults to `false`.                                                                              | `false`                       |
+| `excludeNotDocumentedKinds` |Optional| Exclude symbols of the given kinds if they are not explicitly documented.                                                                             |                               |
+| `excludeInternal`           |Optional| Exclude symbols marked with the `@internal` tag. Defaults to `false`.                                                                                 | `false`                       |
+| `excludePrivate`            |Optional| Exclude symbols marked with the `@private` tag. Defaults to `false`.                                                                                  | `false`                       |
+| `excludeProtected`          |Optional| Exclude symbols marked with the `@protected` tag. Defaults to `false`.                                                                                | `false`                       |
+| `excludeReferences`         |Optional| Exclude references of symbols already included in the documentation. Defaults to `false`.                                                             | `false`                       |
+| `excludeCategories`         |Optional| Exclude reflections associated with any of the given categories.                                                                                      |                               |
+| `showConfig`                |Optional| Show the resolved configuration and exit.                                                                                                             |                               |
+
+Please note that I added the missing options and adjusted the names of some options to match the actual code implementation. Feel free to adapt it further based on your preferences.
+## Templates and Plugins 🖌️
 
 You can use TypeDoc [templates](https://typedoc.org/guides/options/) with this action.  
-Just set the `template` input variable to the name of the template you want to use. This needs to be the template's package name.
-
-If the template's template files are located somewhere else than the package's root, you need to specify this. Set the `template_dir` input variable to the location of the template folder (contains a `publish.js` file).
-
-For example, to use the TypeDoc [default](https://typedoc.org/guides/themes/default/) template, set the `template` input variable to `default`.
+Just set the `theme` or the `plugin` input variable to the name of the template you want to use and use the `install_module` to install that package (this needs to be the template's package name.). 
 
 ## TypeDoc Configuration file 📄
 
@@ -116,7 +146,6 @@ jobs:
           source_dir: ./src
           output_dir: ./docs
           front_page: README.md
-          recurse: true
 
       - name: Setup Pages
         uses: actions/configure-pages@v3
diff --git a/action.yml b/action.yml
index efb158f..b899972 100644
--- a/action.yml
+++ b/action.yml
@@ -11,6 +11,12 @@ inputs:
   output_dir:
     description: 'Output folder for the generated documentation'
     required: false
+  tsconfig_file:
+    description: 'The path to a tsconfig.json file. Defaults to ./tsconfig.json'
+    required: false
+  options:
+    description: 'Options to be forwarded to Typedoc when generating documentation'
+    required: false
   theme:
     description: 'The TSDoc template or theme to install. https://typedoc.org/guides/themes/'
     required: false
@@ -35,9 +41,6 @@ inputs:
   excludeExternals:
     description: 'Prevent externally resolved TypeScript files from being documented. Defaults to false.'
     required: false
-  config_file:
-    description: 'The path to a TSDoc configuration file'
-    required: false
   template_name:
     description: 'This input variable is deprecated in favour of "template"'
     required: false
diff --git a/lib/index.js b/lib/index.js
index 297df08..5de3c45 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -25974,10 +25974,17 @@ async function run() {
             return;
         }
     }
+    /** The output directory. */
+    const output_dir = (0, core_1.getInput)('output_dir');
     try {
-        /** Parse the inputs. */
-        const output_dir = (0, core_1.getInput)('output_dir');
-        const config_file = (0, core_1.getInput)('config_file');
+        /**
+         * Parse the inputs.
+         */
+        const options = (0, core_1.getInput)('options');
+        const tsconfig = (0, core_1.getInput)('tsconfig') || 'tsconfig.json';
+        const entryPointStrategy = (0, core_1.getInput)('entryPointStrategy');
+        const resolveEntrypoints = entryPointStrategy === 'resolve';
+        const packagesEntrypoints = entryPointStrategy === 'packages';
         const install_module = (0, core_1.getInput)('install_module');
         const theme = (0, core_1.getInput)('theme');
         const themeColor = (0, core_1.getInput)('themeColor');
@@ -25986,11 +25993,7 @@ async function run() {
         const front_page = (0, core_1.getInput)('front_page');
         const name = (0, core_1.getInput)('name');
         const exclude = (0, core_1.getInput)('exclude');
-        const tsconfig = (0, core_1.getInput)('tsconfig');
         const entryPoints = (0, core_1.getMultilineInput)('entryPoints');
-        const entryPointStrategy = (0, core_1.getInput)('entryPointStrategy');
-        const resolveEntrypoints = entryPointStrategy === 'resolve';
-        const packagesEntrypoints = entryPointStrategy === 'packages';
         const externalPattern = (0, core_1.getMultilineInput)('externalPattern');
         const excludeExternals = (0, core_1.getInput)('excludeExternals');
         const excludeNotDocumented = (0, core_1.getInput)('excludeNotDocumented');
@@ -26020,29 +26023,67 @@ async function run() {
             pluginName = await (0, installer_1.default)(install_module, actionDir);
             (0, core_1.info)(`🆗 ${pluginName} installed`);
         }
+        /**
+         * The cmd variable represents the command to execute Typedoc.
+         *
+         * @type {string}
+         */
         const cmd = 'npx typedoc';
+        /**
+         * The variable 'args' is an array of strings.
+         * It is used to hold command line arguments passed to typedoc function.
+         * Each element in the array represents a separate command line argument.
+         *
+         * @type {string[]}
+         * @example
+         * // Empty array
+         * const args = [];
+         *
+         * // Array with command line arguments
+         * const args = ['arg1', 'arg2', 'arg3'];
+         */
         const args = [];
         if ((0, core_1.getInput)('logLevel')) {
             args.push('--logLevel', (0, core_1.getInput)('logLevel'));
         }
-        /** the path to the source directory */
+        /**
+         * The base path of the package to be documented.
+         * Since the base path is relative to the current working directory,
+         * we need to use the GITHUB_WORKSPACE variable.
+         */
+        const basePath = (0, core_1.getInput)('basePath');
+        if (basePath) {
+            args.push('--basePath', (0, path_1.join)(GITHUB_WORKSPACE, basePath));
+        }
+        else {
+            args.push('--basePath', GITHUB_WORKSPACE);
+        }
+        /**
+         * The path to the source directory
+         */
         const srcPath = (0, path_1.join)(GITHUB_WORKSPACE, source_dir);
         (0, core_1.info)('📂 Source directory: ' + srcPath);
         args.push(srcPath);
         if (output_dir) {
             args.push('--out', (0, path_1.join)(GITHUB_WORKSPACE, output_dir));
         }
-        if (config_file) {
-            const configPath = (0, path_1.join)(GITHUB_WORKSPACE, config_file);
-            if ((0, node_fs_1.existsSync)(configPath)) {
+        /**
+         * the path to the tsconfig file, needed to resolve entry points and other options. Defaults to ./{action folder}/tsconfig.json
+         * https://typedoc.org/options/input/#resolve-(default)
+         */
+        if (tsconfig) {
+            const tsConfigPath = (0, path_1.join)(GITHUB_WORKSPACE, tsconfig);
+            if ((0, node_fs_1.existsSync)(tsConfigPath)) {
                 (0, core_1.setFailed)('⛔️ Config file does not exist');
                 return;
             }
-        }
-        if (config_file) {
-            const configPath = (0, path_1.join)(GITHUB_WORKSPACE, config_file);
+            const configPath = (0, path_1.join)(GITHUB_WORKSPACE, tsconfig);
             args.push('--tsconfig', configPath);
         }
+        if (options) {
+            const configPath = (0, path_1.join)(GITHUB_WORKSPACE, options);
+            args.push('--options', configPath);
+        }
         if (plugin) {
             args.push('--plugin', plugin);
         }
@@ -26052,7 +26093,7 @@ async function run() {
         if (theme && themeColor) {
             args.push('--themeColor', themeColor);
         }
-        if (template_dir) {
+        if (templateName) {
             args.push('--template_dir', (0, path_1.join)(GITHUB_WORKSPACE, '../node_modules/', templateName, template_dir));
         }
         if (readme) {
@@ -26083,9 +26124,6 @@ async function run() {
         if ((0, core_1.getInput)('markedOptions')) {
             args.push('--markedOptions', (0, core_1.getInput)('markedOptions'));
         }
-        if ((0, core_1.getInput)('basePath')) {
-            args.push('--basePath', (0, core_1.getInput)('basePath'));
-        }
         if ((0, core_1.getInput)('cname')) {
             args.push('--cname', (0, core_1.getInput)('cname'));
         }
@@ -26183,13 +26221,16 @@ async function run() {
         await (0, exec_1.exec)(cmd, args, { cwd: actionDir });
         return output_dir;
     }
-    catch (error) {
-        Error(`🔴 Something went wrong while generating documentation:`);
-        Error(`Current paths: workingDirectory: ${GITHUB_WORKSPACE} actionDir: ${actionDir}`);
-        (0, core_1.setFailed)(error.message);
+    catch (err) {
+        (0, core_1.error)(`🔴 Something went wrong while generating documentation`);
+        (0, core_1.error)(`Current paths: workingDirectory: ${GITHUB_WORKSPACE} actionDir: ${actionDir}`);
+        (0, core_1.setFailed)(err.message);
         process.exit(1);
     }
 }
+/**
+ *
+ */
 run().then(output_dir => {
     (0, core_1.info)(`📖 Documentation has been generated to the ${output_dir} folder 📁`);
     process.exit(0);
diff --git a/src/index.ts b/src/index.ts
index e1c18ab..95e0529 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,4 +1,4 @@
-import {getInput, getMultilineInput, setFailed, info} from '@actions/core'
+import {getInput, getMultilineInput, setFailed, info, error} from '@actions/core'
 import {exec} from '@actions/exec'
 import {join} from "path";
 import installPackage from "./installer";
@@ -38,11 +38,19 @@ async function run(): Promise<string> {
             return;
         }
     }
+    /** The output directory. */
+    const output_dir = getInput('output_dir')
 
     try {
-        /** Parse the inputs. */
-        const output_dir = getInput('output_dir')
-        const config_file = getInput('config_file')
+        /**
+         * Parse the inputs.
+         */
+        const options = getInput('options')
+        const tsconfig = getInput('tsconfig') || 'tsconfig.json'
+        const entryPointStrategy = getInput('entryPointStrategy')
+        const resolveEntrypoints = entryPointStrategy === 'resolve'
+        const packagesEntrypoints = entryPointStrategy === 'packages'
+
         const install_module = getInput('install_module')
         const theme = getInput('theme')
         const themeColor = getInput('themeColor')
@@ -52,11 +60,7 @@ async function run(): Promise<string> {
 
         const name = getInput('name')
         const exclude = getInput('exclude')
-        const tsconfig = getInput('tsconfig')
         const entryPoints = getMultilineInput('entryPoints')
-        const entryPointStrategy = getInput('entryPointStrategy')
-        const resolveEntrypoints = entryPointStrategy === 'resolve'
-        const packagesEntrypoints = entryPointStrategy === 'packages'
         const externalPattern = getMultilineInput('externalPattern')
         const excludeExternals = getInput('excludeExternals')
         const excludeNotDocumented = getInput('excludeNotDocumented')
@@ -89,8 +93,26 @@ async function run(): Promise<string> {
             info(`🆗 ${pluginName} installed`)
         }
 
-        const cmd = 'npx typedoc'
+        /**
+         * The cmd variable represents the command to execute Typedoc.
+         *
+         * @type {string}
+         */
+        const cmd: string = 'npx typedoc'
 
+        /**
+         * The variable 'args' is an array of strings.
+         * It is used to hold command line arguments passed to typedoc function.
+         * Each element in the array represents a separate command line argument.
+         *
+         * @type {string[]}
+         * @example
+         * // Empty array
+         * const args = [];
+         *
+         * // Array with command line arguments
+         * const args = ['arg1', 'arg2', 'arg3'];
+         */
         const args: string[] = []
 
 
@@ -98,8 +120,22 @@ async function run(): Promise<string> {
             args.push('--logLevel', getInput('logLevel'))
         }
 
-        /** the path to the source directory */
-        const srcPath = join(GITHUB_WORKSPACE, source_dir)
+        /**
+         * The base path of the package to be documented.
+         * Since the base path is relative to the current working directory,
+         * we need to use the GITHUB_WORKSPACE variable.
+         */
+        const basePath = getInput('basePath');
+        if (basePath) {
+            args.push('--basePath', join(GITHUB_WORKSPACE, basePath))
+        } else {
+            args.push('--basePath', GITHUB_WORKSPACE)
+        }
+
+        /**
+         * The path to the source directory
+         */
+        const srcPath: string = join(GITHUB_WORKSPACE, source_dir)
         info('📂 Source directory: ' + srcPath)
         args.push(srcPath)
 
@@ -107,18 +143,27 @@ async function run(): Promise<string> {
             args.push('--out', join(GITHUB_WORKSPACE, output_dir))
         }
 
-        if (config_file) {
-            const configPath = join(GITHUB_WORKSPACE, config_file)
-            if (existsSync(configPath)) {
+
+        /**
+         * the path to the tsconfig file, needed to resolve entry points and other options. Defaults to ./{action folder}/tsconfig.json
+         * https://typedoc.org/options/input/#resolve-(default)
+         */
+        if (tsconfig) {
+            const tsConfigPath = join(GITHUB_WORKSPACE, tsconfig)
+            if (existsSync(tsConfigPath)) {
                 setFailed('⛔️ Config file does not exist')
                 return
             }
-        }
 
-        if (config_file) {
-            const configPath = join(GITHUB_WORKSPACE, config_file)
+            const configPath = join(GITHUB_WORKSPACE, tsconfig)
             args.push('--tsconfig', configPath)
         }
+
+        if (options) {
+            const configPath = join(GITHUB_WORKSPACE, options)
+            args.push('--options', configPath)
+        }
+
         if (plugin) {
             args.push('--plugin', plugin)
         }
@@ -128,7 +173,7 @@ async function run(): Promise<string> {
         if (theme && themeColor) {
             args.push('--themeColor', themeColor)
         }
-        if (template_dir) {
+        if (templateName) {
             args.push('--template_dir', join(GITHUB_WORKSPACE, '../node_modules/', templateName, template_dir))
         }
 
@@ -161,9 +206,6 @@ async function run(): Promise<string> {
         if (getInput('markedOptions')) {
             args.push('--markedOptions', getInput('markedOptions'))
         }
-        if (getInput('basePath')) {
-            args.push('--basePath', getInput('basePath'))
-        }
         if (getInput('cname')) {
             args.push('--cname', getInput('cname'))
         }
@@ -263,14 +305,17 @@ async function run(): Promise<string> {
 
         return output_dir
 
-    } catch (error) {
-        Error(`🔴 Something went wrong while generating documentation:`)
-        Error(`Current paths: workingDirectory: ${GITHUB_WORKSPACE} actionDir: ${actionDir}`)
-        setFailed(error.message)
+    } catch (err) {
+        error(`🔴 Something went wrong while generating documentation`)
+        error(`Current paths: workingDirectory: ${GITHUB_WORKSPACE} actionDir: ${actionDir}`)
+        setFailed( err.message )
         process.exit(1)
     }
 }
 
+/**
+ *
+ */
 run().then(output_dir => {
     info(`📖 Documentation has been generated to the ${output_dir} folder 📁`)
     process.exit(0)