Add types to source code (simple-icons#10637)

Author: mondeja

.npmignore

@@ -16,3 +16,4 @@
 !sdk.js
 !sdk.d.ts
 !.jsonschema.json
+!jsconfig.json

.xo-config.json

@@ -2,6 +2,7 @@
   "prettier": true,
   "space": 2,
   "plugins": ["import"],
+  "extends": ["plugin:jsdoc/recommended"],
   "rules": {
     "sort-imports": [
       "error",
@@ -27,7 +28,8 @@
         "newlines-between": "never"
       }
     ],
-    "no-console": ["error", {"allow": ["warn", "error"]}]
+    "no-console": ["error", {"allow": ["warn", "error"]}],
+    "jsdoc/require-file-overview": "error"
   },
   "overrides": [
     {
@@ -46,6 +48,12 @@
         "svgo.config.mjs"
       ],
       "nodeVersion": ">=18"
+    },
+    {
+      "files": ["svglint.config.mjs"],
+      "rules": {
+        "max-depth": "off"
+      }
     }
   ]
 }

jsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "node16",
+    "moduleResolution": "node16",
+    "checkJs": true,
+    "skipLibCheck": false,
+    "strict": true,
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}

package.json

@@ -86,10 +86,12 @@
   "devDependencies": {
     "@inquirer/core": "8.1.0",
     "@inquirer/prompts": "5.0.2",
+    "@types/node": "20.14.2",
     "chalk": "5.3.0",
     "editorconfig-checker": "5.1.5",
     "esbuild": "0.20.2",
     "eslint-plugin-import": "2.29.1",
+    "eslint-plugin-jsdoc": "48.2.8",
     "fake-diff": "1.0.0",
     "fast-fuzzy": "1.12.0",
     "get-relative-luminance": "1.0.0",
@@ -99,8 +101,8 @@
     "markdown-link-check": "3.12.1",
     "mocha": "10.4.0",
     "named-html-entities-json": "1.0.0",
-    "svg-path-bbox": "1.2.6",
-    "svg-path-segments": "2.0.0",
+    "svg-path-bbox": "2.0.0",
+    "svg-path-segments": "2.0.1",
     "svglint": "2.7.1",
     "svgo": "3.2.0",
     "svgpath": "2.6.0",

scripts/add-icon-data.js

@@ -1,4 +1,12 @@
 #!/usr/bin/env node
+/**
+ * @file
+ * Script to add data for a new icon to the simple-icons dataset.
+ */
+
+/**
+ * @typedef {import("../sdk.js").IconData} IconData
+ */
 import process from 'node:process';
 import {ExitPromptError} from '@inquirer/core';
 import {checkbox, confirm, input} from '@inquirer/prompts';
@@ -15,6 +23,7 @@ import {
 } from '../sdk.mjs';
 import {getJsonSchemaData, writeIconsData} from './utils.js';
 
+/** @type {{icons: import('../sdk.js').IconData[]}} */
 const iconsData = JSON.parse(await getIconsDataString());
 const jsonSchema = await getJsonSchemaData();
 
@@ -25,25 +34,42 @@ const aliasTypes = ['aka', 'old'].map((key) => ({
   value: key,
 }));
 
+/** @type {{name: string, value: string}[]} */
 const licenseTypes =
   jsonSchema.definitions.brand.properties.license.oneOf[0].properties.type.enum.map(
-    (license) => ({name: license, value: license}),
+    (/** @type {string} */ license) => ({name: license, value: license}),
   );
 
+/**
+ * @param {string} input URL input
+ * @returns {Promise<boolean|string>} Whether the input is a valid URL
+ */
 const isValidURL = async (input) => {
   const regex = await urlRegex();
   return regex.test(input) || 'Must be a valid and secure (https://) URL.';
 };
 
+/**
+ * @param {string} input Hex color
+ * @returns {boolean|string} Whether the input is a valid hex color
+ */
 const isValidHexColor = (input) =>
   HEX_REGEX.test(input) || 'Must be a valid hex code.';
 
+/**
+ * @param {string} input New icon input
+ * @returns {boolean} Whether the icon is new
+ */
 const isNewIcon = (input) =>
   !iconsData.icons.some(
     (icon) =>
       icon.title === input || titleToSlug(icon.title) === titleToSlug(input),
-  ) || 'This icon title or slug already exists.';
+  );
 
+/**
+ * @param {string} input Color input
+ * @returns {string} Preview of the color
+ */
 const previewHexColor = (input) => {
   const color = normalizeColor(input);
   const luminance = HEX_REGEX.test(input)
@@ -60,7 +86,9 @@ try {
     title: await input({
       message: 'What is the title of this icon?',
       validate: (input) =>
-        input.trim().length > 0 ? isNewIcon(input) : 'This field is required.',
+        input.trim().length > 0
+          ? isNewIcon(input) || 'This icon title or slug already exists.'
+          : 'This field is required.',
     }),
     hex: normalizeColor(
       await input({
@@ -111,6 +139,7 @@ try {
         }).then(async (aliases) => {
           const result = {};
           for (const alias of aliases) {
+            // @ts-ignore
             // eslint-disable-next-line no-await-in-loop
             result[alias] = await input({
               message: `What ${alias} aliases would you like to add? (separate with commas)`,

scripts/build/clean.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * @fileoverview
+ * @file
  * Clean files built by the build process.
  */
 

scripts/build/package.js

@@ -1,9 +1,14 @@
 #!/usr/bin/env node
 /**
- * @fileoverview
+ * @file
  * Simple Icons package build script.
  */
 
+/**
+ * @typedef {import('../../types.js').License} License
+ * @typedef {import('esbuild').TransformOptions} EsBuildTransformOptions
+ */
+
 import {promises as fs} from 'node:fs';
 import path from 'node:path';
 import util from 'node:util';
@@ -36,62 +41,78 @@ const iconObjectTemplateFile = path.resolve(
   'icon-object.js.template',
 );
 
+const icons = await getIconsData();
+const iconObjectTemplate = await fs.readFile(iconObjectTemplateFile, UTF8);
+
+/**
+ * @param {string} value The value to escape
+ * @returns {string} The escaped value
+ */
+const escape = (value) => {
+  return value.replaceAll(/(?<!\\)'/g, "\\'");
+};
+
+/**
+ * @param {License} license The license object or URL
+ * @returns {License} The license object with a URL
+ */
+const licenseToObject = (license) => {
+  if (license.url === undefined) {
+    license.url = `https://spdx.org/licenses/${license.type}`;
+  }
+
+  return license;
+};
+
+// TODO: Find a way to type this object without decreasing performance
+// @ts-ignore
+const iconToJsObject = (icon) => {
+  return util.format(
+    iconObjectTemplate,
+    escape(icon.title),
+    escape(icon.slug),
+    escape(titleToHtmlFriendly(icon.title)),
+    escape(icon.path),
+    escape(icon.source),
+    escape(icon.hex),
+    icon.guidelines ? `\n  guidelines: '${escape(icon.guidelines)}',` : '',
+    icon.license === undefined
+      ? ''
+      : `\n  license: ${JSON.stringify(licenseToObject(icon.license))},`,
+  );
+};
+
+/**
+ * @param {string} filepath The path to the file to write
+ * @param {string} rawJavaScript The raw JavaScript content to write to the file
+ * @param {EsBuildTransformOptions | null} options The options to pass to esbuild
+ */
+const writeJs = async (filepath, rawJavaScript, options = null) => {
+  options = options === null ? {minify: true} : options;
+  const {code} = await esbuildTransform(rawJavaScript, options);
+  await fs.writeFile(filepath, code);
+};
+
+/**
+ * @param {string} filepath The path to the file to write
+ * @param {string} rawTypeScript The raw TypeScript content to write to the file
+ */
+const writeTs = async (filepath, rawTypeScript) => {
+  await fs.writeFile(filepath, rawTypeScript);
+};
+
 const build = async () => {
-  const icons = await getIconsData();
-  const iconObjectTemplate = await fs.readFile(iconObjectTemplateFile, UTF8);
-
-  // Local helper functions
-  const escape = (value) => {
-    return value.replaceAll(/(?<!\\)'/g, "\\'");
-  };
-
-  const licenseToObject = (license) => {
-    if (license === undefined) {
-      return;
-    }
-
-    if (license.url === undefined) {
-      license.url = `https://spdx.org/licenses/${license.type}`;
-    }
-
-    return license;
-  };
-
-  const iconToObject = (icon) => {
-    return util.format(
-      iconObjectTemplate,
-      escape(icon.title),
-      escape(icon.slug),
-      escape(titleToHtmlFriendly(icon.title)),
-      escape(icon.path),
-      escape(icon.source),
-      escape(icon.hex),
-      icon.guidelines ? `\n  guidelines: '${escape(icon.guidelines)}',` : '',
-      licenseToObject(icon.license)
-        ? `\n  license: ${JSON.stringify(licenseToObject(icon.license))},`
-        : '',
-    );
-  };
-
-  const writeJs = async (filepath, rawJavaScript, options = null) => {
-    options = options === null ? {minify: true} : options;
-    const {code} = await esbuildTransform(rawJavaScript, options);
-    await fs.writeFile(filepath, code);
-  };
-
-  const writeTs = async (filepath, rawTypeScript) => {
-    await fs.writeFile(filepath, rawTypeScript);
-  };
-
-  // 'main'
   const buildIcons = await Promise.all(
     icons.map(async (icon) => {
       const filename = getIconSlug(icon);
       const svgFilepath = path.resolve(iconsDirectory, `${filename}.svg`);
+      // TODO: Find a way to type these objects without decreasing performance
+      // @ts-ignore
       icon.svg = await fs.readFile(svgFilepath, UTF8);
+      // @ts-ignore
       icon.path = svgToPath(icon.svg);
       icon.slug = filename;
-      const iconObject = iconToObject(icon);
+      const iconObject = iconToJsObject(icon);
       const iconExportName = slugToVariableName(icon.slug);
       return {icon, iconObject, iconExportName};
     }),

scripts/get-filename.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * @fileoverview
+ * @file
  * Script that takes a brand name as argument and outputs the corresponding
  * icon SVG filename to standard output.
  */

scripts/lint/jsonlint.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * @fileoverview
+ * @file
  * CLI tool to run jsonschema on the simple-icons.json data file.
  */