Merge branch 'main' into dependabot/npm_and_yarn/commander-13.0.0

Author: sebastiaanspeck

.github/workflows/test.yml

@@ -37,4 +37,5 @@ jobs:
         node-version: ${{ matrix.node-version }}
 
     - run: npm ci
+    - run: npm run typecheck
     - run: npm run test:all

README.md

@@ -62,7 +62,7 @@ For the list of available translations, please refer to the main [tldr](https://
 
 You can configure the `tldr` client by adding a `.tldrrc` file in your HOME directory. You can copy the contents of the `config.json` file from the repo to get the basic structure to start with, and modify it to suit your needs.
 
-The default color theme is the one named `"simple"`. You can change the theme by assigning a different value to the `"theme"` variable -- either to one of the pre-configured themes, or to a new theme that you have previously created in the `"themes"` section. Note that the colors and text effects you can choose are limited. Refer to the [chalk documentation](https://github.com/chalk/chalk#styles) for all options.
+The default color theme is the one named `"simple"`. You can change the theme by assigning a different value to the `"theme"` variable -- either to one of the pre-configured themes, or to a new theme that you have previously created in the `"themes"` section. Note that the colors and text effects you can choose are limited. Refer to the [Node.js documentation](https://nodejs.org/api/util.html#modifiers) for all options.
 
 ```json
 {

lib/cache.js

@@ -14,10 +14,21 @@ class Cache {
     this.cacheFolder = path.join(config.cache, 'cache');
   }
 
+  /**
+   * Fetch stats from the cache folder for getting its last modified time
+   * (mtime).
+   *
+   * @returns {Promise<any>} A promise with the stats of the cache folder.
+   */
   lastUpdated() {
     return fs.stat(this.cacheFolder);
   }
 
+  /**
+   * Fetch a page from cache using preferred language and preferred platform.
+   * @param {string} page
+   * @returns {Promise<string>}
+   */
   getPage(page) {
     let preferredPlatform = platforms.getPreferredPlatformFolder(this.config);
     const preferredLanguage = process.env.LANG || 'en';
@@ -34,10 +45,20 @@ class Cache {
       });
   }
 
+  /**
+   * Clean the cache folder.
+   * @returns {Promise<any>} A promise when the remove is completed.
+   */
   clear() {
     return fs.remove(this.cacheFolder);
   }
 
+  /**
+   * Update the cache folder using a temporary directory, update the index and
+   * return it.
+   *
+   * @returns {Promise<any>} The index.
+   */
   update() {
     // Temporary folder path: /tmp/tldr/{randomName}
     const tempFolder = path.join(os.tmpdir(), 'tldr', utils.uniqueId());
@@ -65,7 +86,6 @@ class Cache {
           index.rebuildPagesIndex(),
         ]);
       })
-       
       .then(([_, shortIndex]) => {
         return shortIndex;
       });

lib/completion.js

@@ -22,7 +22,7 @@ class Completion {
 
   appendScript(script) {
     const rcFilePath = this.getFilePath();
-    return new Promise((resolve, reject) => {
+    return new Promise((/** @type {(v?: never) => void} */ resolve, reject) => {
       fs.appendFile(rcFilePath, `\n${script}\n`, (err) => {
         if (err) {
           reject((new CompletionScriptError(`Error appending to ${rcFilePath}: ${err.message}`)));
@@ -79,4 +79,4 @@ fi
   }
 }
 
-module.exports = Completion;
+module.exports = Completion;

lib/config.js

@@ -11,12 +11,12 @@ exports.get = () => {
   const DEFAULT = path.join(__dirname, '..', 'config.json');
   const CUSTOM = path.join(osHomedir(), '.tldrrc');
 
-  let defaultConfig = JSON.parse(fs.readFileSync(DEFAULT));
+  let defaultConfig = JSON.parse(fs.readFileSync(DEFAULT, 'utf-8'));
   defaultConfig.cache = path.join(osHomedir(), '.tldr');
 
   let customConfig = {};
   try {
-    customConfig = JSON.parse(fs.readFileSync(CUSTOM));
+    customConfig = JSON.parse(fs.readFileSync(CUSTOM, 'utf-8'));
   } catch (ex) {
     if (ex instanceof SyntaxError) {
       throw new Error('The content of .tldrrc is not a valid JSON object:\n' + ex);

lib/index.js

@@ -10,6 +10,12 @@ let shortIndex = null;
 const pagesPath = path.join(config.get().cache, 'cache');
 const shortIndexFile = path.join(pagesPath, 'shortIndex.json');
 
+/**
+ * @param {string} page
+ * @param {string|undefined} preferredPlatform
+ * @param {string} preferredLanguage
+ * @returns {Promise<?string>}
+ */
 function findPage(page, preferredPlatform, preferredLanguage) {
   // Load the index
   return getShortIndex()
@@ -33,7 +39,7 @@ function findPage(page, preferredPlatform, preferredLanguage) {
         ll = preferredLanguage.substring(0, preferredLanguage.indexOf('_'));
       }
       if (!hasLang(targets, preferredLanguage)) {
-        preferredLanguage = ll;
+        preferredLanguage = /** @type {string} */ (ll);
       }
 
       // Page resolution logic:
@@ -91,25 +97,38 @@ function hasLang(targets, preferredLanguage) {
   });
 }
 
-// hasPage is always called after the index is created,
-// hence just return the variable in memory.
-// There is no need to re-read the index file again.
+/**
+ * Check if a page is in the index.
+ *
+ * @returns {boolean} The presence of the page in the index.
+ */
 function hasPage(page) {
+  // hasPage is always called after the index is created,
+  // hence just return the variable in memory.
+  // There is no need to re-read the index file again.
   if (!shortIndex) {
     return false;
   }
   return page in shortIndex;
 }
 
-// Return all commands available in the local cache.
+/**
+ * Return all commands available in the local index.
+ * @returns {Promise<string[]>} A promise with the commands from the index.
+ */
 function commands() {
   return getShortIndex().then((idx) => {
     return Object.keys(idx).sort();
   });
 }
 
-// Return all commands for a given platform.
-// P.S. - The platform 'common' is always included.
+/**
+ * Return all commands for a given platform. The 'common' platform is always
+ * included.
+ *
+ * @param {string} platform The desired platform.
+ * @returns {Promise<string[]>} The commands for a given platform.
+ */
 function commandsFor(platform) {
   return getShortIndex()
     .then((idx) => {
@@ -124,7 +143,11 @@ function commandsFor(platform) {
     });
 }
 
-// Delete the index file.
+/**
+ * Delete the index file.
+ *
+ * @returns {Promise<any>} A promise when the remove is completed.
+ */
 function clearPagesIndex() {
   return fs.unlink(shortIndexFile)
     .then(() => {
@@ -139,7 +162,9 @@ function clearPagesIndex() {
     });
 }
 
-// Set the shortIndex variable to null.
+/**
+ * Set the shortIndex variable to null.
+ */
 function clearRuntimeIndex() {
   shortIndex = null;
 }
@@ -150,18 +175,26 @@ function rebuildPagesIndex() {
   });
 }
 
-// If the variable is not set, read the file and set it.
-// Else, just return the variable.
+/**
+ * Return the index, that contains all available commands with their target os
+ * and platform. If the index is not loaded, read the file and load it.
+ *
+ * @returns {Promise<any>} The index entries.
+ */
 function getShortIndex() {
   if (shortIndex) {
     return Promise.resolve(shortIndex);
   }
   return readShortPagesIndex();
 }
 
-// Read the index file, and load it into memory.
-// If the file does not exist, create the data structure, write the file,
-// and load it into memory.
+/**
+ * Read the index file, and load it into memory.
+ *
+ * If the file does not exist, create the data structure, write the file,
+ * and load it into memory.
+ * @returns {Promise<any>} The index entries.
+ */
 function readShortPagesIndex() {
   return fs.readJson(shortIndexFile)
     .then((idx) => {

lib/parser.js

@@ -1,8 +1,8 @@
 'use strict';
 
+const { styleText } = require('node:util');
 const unescape = require('lodash/unescape');
 const marked = require('marked');
-const chalk = require('chalk');
 const index = require('./index');
 
 const allElements = [
@@ -17,6 +17,7 @@ function unhtml(text){
 
 exports.parse = (markdown) => {
   // Creating the page structure
+  /** @type {Required<import('./tldr').TldrPage> & { examples: any[] }} */
   let page = {
     name: '',
     description: '',
@@ -70,11 +71,11 @@ exports.parse = (markdown) => {
   };
 
   r.strong = (text) => {
-    return chalk.bold(text);
+    return styleText('bold', text);
   };
 
   r.em = (text) => {
-    return chalk.italic(text);
+    return styleText('italic', text);
   };
 
   r.listitem = (text) => {

lib/remote.js

@@ -6,7 +6,12 @@ const unzip = require('adm-zip');
 const config = require('./config');
 const axios = require('axios');
 
-// Downloads the zip file from github and extracts it to folder
+/**
+ * Download the zip file from GitHub and extract it to folder.
+ * @param {string} loc Path to a directory on disk.
+ * @param {string} lang Language/locale code.
+ * @returns {Promise<void>} A promise when the operation is completed.
+ */
 exports.download = (loc, lang) => {
   // If the lang is english then keep the url simple, otherwise add language.
   const suffix = (lang === 'en' ? '' : '.' + lang);
@@ -21,12 +26,12 @@ exports.download = (loc, lang) => {
     headers: { 'User-Agent' : 'tldr-node-client' },
     timeout: REQUEST_TIMEOUT,
   }).then((response) => {
-    return new Promise((resolve, reject) => {
+    return new Promise((/** @type {(v?: never) => void} */ resolve, reject) => {
       let fileName = path.join(loc, 'download_' + lang + '.zip');
 
       const writer = fs.createWriteStream(fileName);
       response.data.pipe(writer);
-    
+
       writer.on('finish', () => {
         writer.end();
         const zip = new unzip(fileName);
@@ -41,4 +46,4 @@ exports.download = (loc, lang) => {
   }).catch((err) => {
     return Promise.reject(err);
   });
-};
+};

lib/render.js

@@ -3,8 +3,14 @@
 const Theme = require('./theme');
 const he = require('he'); // Import the 'he' library
 
-// The page structure is passed to this function, and then the theme is applied
-// to different parts of the page and rendered to the console
+/**
+ * Page structure is passed to this function, and then the theme is applied to
+ * different parts of the page and rendered to the console.
+ *
+ * @param {import('./tldr').TldrPage} page
+ * @param {any} config
+ * @returns {string|void}
+ */
 exports.toANSI = (page, config) => {
   // Creating the theme object
   let themeOptions = config.themes[config.theme];