chore: add jsdoc types and typechecking

Co-authored-by: Vitor Henrique <[email protected]>

Author: SethFalco

.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

lib/cache.js

@@ -15,7 +15,9 @@ class Cache {
   }
 
   /**
-   * Fetch stats from the cache folder.
+   * 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() {
@@ -24,8 +26,8 @@ class Cache {
 
   /**
    * Fetch a page from cache using preferred language and preferred platform.
-   * @param page {} A
-   * @returns {Promise<unknown>}
+   * @param {string} page
+   * @returns {Promise<string>}
    */
   getPage(page) {
     let preferredPlatform = platforms.getPreferredPlatformFolder(this.config);
@@ -52,8 +54,10 @@ class Cache {
   }
 
   /**
-   * Update the cache folder and returns the English entries.
-   * @returns {Promise<any>} A promise with the index.
+   * 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}
@@ -82,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:
@@ -93,7 +99,8 @@ function hasLang(targets, preferredLanguage) {
 
 /**
  * Check if a page is in the index.
- * @returns {boolean} A boolean that indicates if the page is present.
+ *
+ * @returns {boolean} The presence of the page in the index.
  */
 function hasPage(page) {
   // hasPage is always called after the index is created,
@@ -106,23 +113,21 @@ function hasPage(page) {
 }
 
 /**
- * Return all commands available in the local cache.
- * @returns {Promise<string[]>} A promise with the commands from 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.
+ * Return all commands for a given platform. The 'common' platform is always
+ * included.
  *
- * The 'common' platform is always included.
- * @param platform {string} The platform.
- * @returns {Promise<string[]>} A promise with the commands for a given platform.
+ * @param {string} platform The desired platform.
+ * @returns {Promise<string[]>} The commands for a given platform.
  */
 function commandsFor(platform) {
   return getShortIndex()
@@ -171,9 +176,9 @@ function rebuildPagesIndex() {
 }
 
 /**
- * Return the index.
+ * 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.
  *
- * If the index is not loaded, read the file and load it.
  * @returns {Promise<any>} The index entries.
  */
 function getShortIndex() {

lib/parser.js

@@ -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: '',

lib/remote.js

@@ -8,7 +8,8 @@ const axios = require('axios');
 
 /**
  * Download the zip file from GitHub and extract it to folder.
- * @param path {string} Path to destination 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) => {
@@ -25,7 +26,7 @@ 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);

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];

lib/search.js

@@ -9,26 +9,53 @@ const utils = require('./utils');
 const index = require('./index');
 const platforms = require('./platforms');
 
+/**
+ * @typedef {object} Corpus
+ * @property {Record<string, Record<string, number>>} fileWords
+ * @property {Record<string, number>} fileLengths
+ * @property {Record<string, string[]>} invertedIndex
+ * @property {any} allTokens
+ * @property {Record<string, Record<string, number>>} tfidf
+ *
+ * @typedef {object} Query
+ * @property {?string} raw
+ * @property {?string[]} tokens
+ * @property {Record<string, number>} frequency
+ * @property {Record<string, number>} score
+ * @property {QueryRank[]} ranks
+ *
+ * @typedef {object} QueryRank
+ * @property {string} file
+ * @property {number} score
+ */
+
 const CACHE_FOLDER = path.join(config.get().cache, 'cache');
 
 const filepath = CACHE_FOLDER + '/search-corpus.json';
 
-let corpus = {};
-
-corpus.fileWords = {};
-corpus.fileLengths = {};
-corpus.invertedIndex = {};
-corpus.allTokens = new Set();
-corpus.tfidf = {};
 
-let query = {};
+/** @type {Corpus} */
+let corpus = {
+  fileWords: {},
+  fileLengths: {},
+  invertedIndex: {},
+  allTokens: new Set(),
+  tfidf: {},
+};
 
-query.raw = null;
-query.tokens = null;
-query.frequency = {};
-query.score = {};
-query.ranks = [];
+/** @type {Query} */
+let query = {
+  raw: null,
+  tokens: null,
+  frequency: {},
+  score: {},
+  ranks: [],
+};
 
+/**
+ * @param {string} data
+ * @returns {string[]}
+ */
 let getTokens = (data) => {
   let tokenizer = new natural.WordTokenizer();
   let tokens = tokenizer.tokenize(data);
@@ -139,6 +166,9 @@ let readCorpus = () => {
     });
 };
 
+/**
+ * @param {string} rawquery
+ */
 let processQuery = (rawquery) => {
   query.raw = rawquery;
   query.tokens = getTokens(rawquery);
@@ -156,10 +186,9 @@ let processQuery = (rawquery) => {
   query.score = {};
   query.tokens.forEach((word) => {
     if (corpus.invertedIndex[word]) {
-      let logbase = 10;
       let df = corpus.invertedIndex[word].length;
-      let idf = Math.log(numberOfFiles / df, logbase);
-      let wordWeight = idf * (1 + Math.log(query.frequency[word], logbase));
+      let idf = Math.log10(numberOfFiles / df);
+      let wordWeight = idf * (1 + Math.log10(query.frequency[word]));
       corpus.invertedIndex[word].forEach((file) => {
         let fileWeight = corpus.tfidf[file][word];
         if (query.score[file]) {
@@ -209,7 +238,7 @@ exports.printResults = (results, config) => {
       outputs.add(output);
     });
 
-    console.log('Searching for:', query.raw.trim());
+    console.log('Searching for:', /** @type {string} */ (query.raw).trim());
     console.log();
     Array.from(outputs).forEach((elem) => {
       console.log(elem);
@@ -220,7 +249,7 @@ exports.printResults = (results, config) => {
 };
 
 exports.createIndex = () => {
-  return utils.glob(CACHE_FOLDER + '/pages/**/*.md', {})
+  return utils.glob(CACHE_FOLDER + '/pages/**/*.md')
     .then((files) => {
       let promises = [];
       files.forEach((file) => {
@@ -246,6 +275,10 @@ exports.createIndex = () => {
     });
 };
 
+/**
+ * @param {string} rawquery
+ * @returns
+ */
 exports.getResults = (rawquery) => {
   query.ranks = [];
   return readCorpus()