ref!: add types, switch to ESM (no bugfixes)

Author: coolaj86

host-targets.js

@@ -1,11 +1,10 @@
-'use strict';
-
 /** @typedef {import('./types.js').OsString} OsString */
 /** @typedef {import('./types.js').LibcString} LibcString */
 /** @typedef {import('./types.js').ArchString} ArchString */
 /** @typedef {import('./types.js').TargetTriplet} TargetTriplet */
+/** @typedef {import('./types.js').TargetMatcher} TargetMatcher */
 
-var HostTargets = module.exports;
+let HostTargets = {};
 
 let reVersionOnly = /^[\d\.]+(-RELEASE)?$/;
 let reLeadingVer = /^\d([\d\.\-\+_])+/;
@@ -64,6 +63,7 @@ let T = {
 };
 
 // OS, Arch, Libc
+/** @type {Object.<String, import('./types.js').TargetMatcher>}  */
 HostTargets.TERMS = {
   // agent
   webi: {},
@@ -137,19 +137,21 @@ HostTargets._MATCHERS = {
 };
 
 /**
- * @param {Object.<"os"|"arch"|"libc", String>} target
+ * @param {Object.<"os"|"arch"|"libc", String>} targetIsh
  * @param {Array<String>} terms
  */
-HostTargets.termsToTarget = function (target, terms) {
+HostTargets.termsToTarget = function (targetIsh, terms) {
   let bogoTerms = [];
 
-  Object.assign(target, { errors: [] });
+  let target = Object.assign(targetIsh, { errors: [] });
 
   for (let term of terms) {
     let lterm = term.toLowerCase();
     let hints = HostTargets.TERMS[lterm];
     if (hints) {
-      upsertHints(target, terms, term, hints);
+      let debugUa = terms.join(',');
+      let debugTerms = [term];
+      upsertHints(target, debugUa, debugTerms, hints);
       continue;
     }
 
@@ -199,15 +201,26 @@ HostTargets.termsToTarget = function (target, terms) {
   return bogoTerms;
 };
 
+/**
+ * @param {TargetTriplet} target
+ * @param {String} ua
+ * @param {Array<String>} terms
+ * @param {TargetMatcher} hints
+ */
 function upsertHints(target, ua, terms, hints) {
   if (!hints) {
     throw new Error("[SANITY FAIL] 'hints' not provided");
   }
 
+  // TODO maybe use utility type 'keyof'
+  /** @type {["os","arch","libc","vendor"]} */ //@ts-expect-error
   let keys = Object.keys(hints);
   for (let key of keys) {
     if (!target[key]) {
-      target[key] = hints[key];
+      if (hints[key]) {
+        //@ts-expect-error TODO
+        target[key] = hints[key];
+      }
     }
     if (target[key] !== hints[key]) {
       let msg = `'${key}' already set to '${target[key]}', not updated to '${hints[key]}'`;
@@ -222,19 +235,30 @@ function upsertHints(target, ua, terms, hints) {
           ignore = true;
         } else if (hints[key] === 'musl') {
           // musl can be installed on a GNU system
+          //@ts-expect-error - TODO find out if we depend on this libs vs libcs typo (we probably do)
           target.libs = [target.libc, 'musl'];
           ignore = true;
         }
       }
       if (!ignore) {
+        //@ts-expect-error
         target.errors.push({ [key]: hints[key], message: msg, terms: terms });
         throw new Error(`${msg} for '${ua}' / '${terms}'`);
       }
     }
   }
 }
 
-// Workaround for current (2023-q4) Android misclassification
+/**
+ * @typedef HasErrors
+ * @prop {Array<any>} errors
+ */
+
+/**
+ * Workaround for current (2023-q4) Android misclassification
+ * @param {TargetTriplet & HasErrors} target
+ * @param {Array<String>} terms
+ */
 function upsertAndroidTerms(target, terms) {
   if (!target.android) {
     return;
@@ -268,3 +292,9 @@ function upsertAndroidTerms(target, terms) {
     }
   }
 }
+
+export let TERMS = HostTargets.TERMS;
+export let WATERFALL = HostTargets.WATERFALL;
+export let _MATCHERS = HostTargets._MATCHERS;
+export let termsToTarget = HostTargets.termsToTarget;
+export default HostTargets;

lexver-test.js

@@ -1,6 +1,6 @@
 'use strict';
 
-let Lexver = require('./lexver.js');
+import Lexver from './lexver.js';
 
 async function main() {
   let matchVer = process.argv[2];
@@ -77,6 +77,7 @@ async function main() {
   let knownKeys = Object.keys(known);
 
   for (let key of knownKeys) {
+    //@ts-expect-error - ignore dynamic key errors in test
     if (selected[key].toString() !== known[key].toString()) {
       console.error('Expected:');
       console.error(known);

lexver.js

@@ -1,6 +1,4 @@
-'use strict';
-
-var Lexver = module.exports;
+let Lexver = {};
 
 // hotfix is post-stable
 let channels = ['alpha', 'beta', 'dev', 'pre', 'preview', 'rc', 'hotfix'];
@@ -12,6 +10,12 @@ let channelsRePost;
   channelsRePost = new RegExp(`(${channelsOr})([\\.\\-\\+]?)(\\d+)`);
 }
 let channelsPrePlacer = '$1-$2';
+/**
+ * @param {unknown} _
+ * @param {String} chan
+ * @param {String} sep
+ * @param {String} ver
+ */
 let channelsPostPlacer = function (_, chan, sep, ver) {
   ver = ver.padStart(2, '0');
 
@@ -23,6 +27,11 @@ let digitsOnlyRe = /^\d+$/;
 // this is a special case, but if it gets complicated in the future, we'll drop it
 // and just treat it like a build hash and open an issue for to the maintainer
 let channelsReB = /(\.\d+b)(\d+)$/;
+/**
+ * @param {unknown} _
+ * @param {String} sep
+ * @param {String} ver
+ */
 let channelsBPlacer = function (_, sep, ver) {
   ver = ver.padStart(2, '0');
   let rel = `${sep}${ver}`;
@@ -75,8 +84,8 @@ Lexver.sortedToTags = function (descVersions) {
 /**
  * Parse a semver or non-standard version and return a lexical version
  * Ex: 1.2beta-3 =>  0001.0002.0000.0000-beta-03
- * @param {String} version - a semver or other version
- * @param {Object} _opts - no public options
+ * @param {String} fullVersion - a semver or other version
+ * @param {Object} [_opts] - no public options
  * @param {Boolean} _opts._asPrefix - don't expand 1.0 to 1.0.0, etc
  * @returns {String}
  */
@@ -89,9 +98,11 @@ Lexver.parseVersion = function (fullVersion, _opts) {
   // 1.2beta1 => 1.2beta1
   let rels = fullVersion.split('-');
 
+  /** @type {String} */ //@ts-expect-error - even an empty string splits
   let version = rels.shift();
   if (version.includes('+')) {
     let parts = version.split('+');
+    /** @type {String} */ //@ts-expect-error - even an empty string splits
     version = parts.shift();
     let build = parts.join(`${sortSuffixBuild}`);
     rels.unshift(`${sortSuffixBuild}${build}`);
@@ -105,6 +116,7 @@ Lexver.parseVersion = function (fullVersion, _opts) {
 
   // 1.2-beta1-a => 1.2, beta1, a
   let subparts = version.split('-');
+  /** @type {String} */ //@ts-expect-error - even an empty string splits
   version = subparts.shift();
 
   // beta1, a => beta1-a
@@ -117,6 +129,7 @@ Lexver.parseVersion = function (fullVersion, _opts) {
   let levels = version.split('.');
   let digits = [];
   for (; levels.length; ) {
+    /** @type {String} */ //@ts-expect-error - even an empty string splits
     let level = levels.shift();
     if (!digitsOnlyRe.test(level)) {
       levels.unshift(level);
@@ -247,3 +260,10 @@ Lexver.matchSorted = function (versions, prefix) {
   };
   return matchInfo;
 };
+
+export let toTags = Lexver.toTags;
+export let sortedToTags = Lexver.sortedToTags;
+export let parseVersion = Lexver.parseVersion;
+export let parsePrefix = Lexver.parsePrefix;
+export let matchSorted = Lexver.matchSorted;
+export default Lexver;

lint-host-targets.js

@@ -1,22 +1,34 @@
-'use strict';
+import HostTargets from './host-targets.js';
 
-let HostTargets = require('./host-targets.js');
+import Fs from 'node:fs/promises';
+import Path from 'node:path';
 
-let uaMap = require('./uas.json');
-let uas = Object.keys(uaMap);
+/** @typedef {import('./types.js').TargetTriplet} TargetTriplet */
 
+/** @type {Object.<String, Number>} */
 let partialsMap = {};
+/** @type {Object.<String, Number>} */
 let termsMap = {};
 let termNames = Object.keys(HostTargets.TERMS);
 for (let term of termNames) {
   termsMap[term] = 0;
 }
 
-function main() {
+async function main() {
   //let hostTargets = HostTargets.create({});
+  /** @type {Object.<String, Boolean>} */
   let tripletsMap = {};
 
+  let modulePath = import.meta.url.slice('file://'.length);
+  let moduleDir = Path.dirname(modulePath);
+  let uasPath = Path.join(moduleDir, './uas.json');
+
+  let uaJson = await Fs.readFile(uasPath, 'utf8');
+  let uaMap = JSON.parse(uaJson);
+  let uas = Object.keys(uaMap);
+
   for (let ua of uas) {
+    /** @type {Array<String>} */
     let terms = [];
 
     let parts = ua.split(/\s+/g);
@@ -33,6 +45,7 @@ function main() {
       terms = terms.concat(_terms);
     }
 
+    /** @type {Partial<TargetTriplet>} */
     let target = {};
     let bogoTerms;
     try {
@@ -104,4 +117,7 @@ function main() {
   }
 }
 
-main();
+main().catch(function (e) {
+  console.error(e.stack);
+  process.exit(1);
+});

lint-versions.js

@@ -1,9 +1,9 @@
 'use strict';
 
-let Path = require('node:path');
-let Fs = require('node:fs/promises');
+import Path from 'node:path';
+import Fs from 'node:fs/promises';
 
-let Lexver = require('./lexver.js');
+import Lexver from './lexver.js';
 
 async function main() {
   let matchVer = process.argv[2];
@@ -14,7 +14,9 @@ async function main() {
 
   let versions;
   {
-    let filepath = Path.join(__dirname, 'versions.txt');
+    let modulePath = import.meta.url.slice('file://'.length);
+    let moduleDir = Path.dirname(modulePath);
+    let filepath = Path.join(moduleDir, 'versions.txt');
     let versionsTxt = await Fs.readFile(filepath, 'utf-8');
     versionsTxt = versionsTxt.trim();
     versions = versionsTxt.split('\n');