Switch to ESM modules and bump version of Reffy (#659)

This replaces calls to `require` with `import` syntaxes.

Also taking this opportunity to fix the `study-backrefs.js` CLI, which was
still expecting a results format that got changed a long time ago.

Note: We will probably want to merge these individual CLIs into the main strudy
CLI at some point.

index.js

@@ -1,5 +1,8 @@
-module.exports = {
-  studyCrawl: require("./src/lib/study-crawl").studyCrawl,
-  studyWebIdl: require("./src/lib/study-webidl").studyWebIdl,
-  generateReport: require("./src/lib/generate-report").generateReport,
-};
+import studyCrawl from './src/lib/study-crawl.js';
+import studyWebIdl from './src/lib/study-webidl.js';
+import generateReport from './src/lib/generate-report.js';
+
+export { studyCrawl, studyWebIdl, generateReport };
+
+const strudy = { studyCrawl, studyWebIdl, generateReport };
+export default strudy;

package.json

@@ -28,6 +28,7 @@
   "engines": {
     "node": ">=18"
   },
+  "type": "module",
   "main": "index.js",
   "bin": "./strudy.js",
   "devDependencies": {
@@ -42,7 +43,7 @@
     "jsdom": "^24.1.1",
     "node-fetch": "^2.6.5",
     "node-pandoc": "0.3.0",
-    "reffy": "^16.0.0",
+    "reffy": "^17.1.1",
     "semver": "^7.3.5",
     "webidl2": "^24.2.2"
   },

src/cli/check-missing-dfns.js

@@ -22,7 +22,10 @@
  * @module checker
  */
 
-const path = require('path');
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import loadJSON from '../lib/load-json.js';
+
 
 /**
  * List of spec shortnames that, so far, don't follow the dfns data model
@@ -358,19 +361,19 @@ function matchIdlDfn(expected, actual,
  *   an array of missing CSS or IDL definitions. The function returns null when
  *   there are no missing definitions.
  */
-function checkSpecDefinitions(spec, options = {}) {
+async function checkSpecDefinitions(spec, options = {}) {
   if (!options.includeObsolete && specsWithObsoleteDfnsModel.includes(spec.shortname)) {
     return { obsoleteDfnsModel: true };
   }
 
   const dfns = (typeof spec.dfns === "string") ?
-    require(path.resolve(options.rootFolder, spec.dfns)).dfns :
+    (await loadJSON(path.resolve(options.rootFolder, spec.dfns))).dfns :
     (spec.dfns || []);
   const css = (typeof spec.css === "string") ?
-    require(path.resolve(options.rootFolder, spec.css)) :
+    (await loadJSON(path.resolve(options.rootFolder, spec.css))) :
     (spec.css || {});
   const idl = (typeof spec.idlparsed === "string") ?
-    require(path.resolve(options.rootFolder, spec.idlparsed)).idlparsed :
+    (await loadJSON(path.resolve(options.rootFolder, spec.idlparsed))).idlparsed :
     spec.idlparsed;
 
   // Make sure that all expected CSS definitions exist in the dfns extract
@@ -466,29 +469,31 @@ function checkSpecDefinitions(spec, options = {}) {
  *  identify the specification, and a `missing` property that is an object that
  *  may have `css` and `idl` properties which list missing CSS/IDL definitions.
  */
-function checkDefinitions(pathToReport, options = {}) {
+async function checkDefinitions(pathToReport, options = {}) {
   const rootFolder = path.resolve(process.cwd(), pathToReport);
-  const index = require(path.resolve(rootFolder, 'index.json')).results;
+  const index = (await loadJSON(path.resolve(rootFolder, 'index.json'))).results;
 
   // Check all dfns against CSS and IDL extracts
   const checkOptions = {
     rootFolder,
     includeObsolete: !!options.shortname
   };
-  const missing = index
-    .filter(spec => !options.shortname || spec.shortname === options.shortname)
-    .map(spec => {
-      const res = {
-        url: spec.url,
-        crawled: spec.crawled,
-        shortname: spec.shortname,
-      };
-      if (!spec.dfns) {
+  const missing = await Promise.all(
+    index
+      .filter(spec => !options.shortname || spec.shortname === options.shortname)
+      .map(async spec => {
+        const res = {
+          url: spec.url,
+          crawled: spec.crawled,
+          shortname: spec.shortname,
+        };
+        if (!spec.dfns) {
+          return res;
+        }
+        res.missing = await checkSpecDefinitions(spec, checkOptions);
         return res;
-      }
-      res.missing = checkSpecDefinitions(spec, checkOptions);
-      return res;
-    });
+      })
+  );
 
   return missing;
 }
@@ -516,26 +521,27 @@ function reportMissing(missing) {
 /**************************************************
 Export methods for use as module
 **************************************************/
-module.exports.checkSpecDefinitions = checkSpecDefinitions;
-module.exports.checkDefinitions = checkDefinitions;
-
-// "Inner" functions that the IDL names generator uses to link IDL terms with
-// their definition (see generate-idlnames.js)
-module.exports.getExpectedDfnFromIdlDesc = getExpectedDfnFromIdlDesc;
-module.exports.matchIdlDfn = matchIdlDfn;
-
+export {
+  checkSpecDefinitions,
+  checkDefinitions,
+
+  // "Inner" functions that the IDL names generator uses to link IDL terms with
+  // their definition (see generate-idlnames.js)
+  getExpectedDfnFromIdlDesc,
+  matchIdlDfn
+}
 
 
 /**************************************************
 Code run if the code is run as a stand-alone module
 **************************************************/
-if (require.main === module) {
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
     const pathToReport = process.argv[2];
     const shortname = process.argv[3] || 'all';
     const format = process.argv[4] || 'markdown';
 
     const options = (shortname === 'all') ? undefined : { shortname };
-    let res = checkDefinitions(pathToReport, options);
+    let res = await checkDefinitions(pathToReport, options);
     if (shortname === 'all') {
       res = res
         .filter(result => result.missing &&

src/cli/study-algorithms.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
-const { loadCrawlResults } = require('../lib/util');
-const { studyAlgorithms } = require('../lib/study-algorithms');
-const requireFromWorkingDirectory = require('../lib/require-cwd');
-const { expandCrawlResult } = require("reffy");
-const path = require("path");
+import { loadCrawlResults } from '../lib/util.js';
+import studyAlgorithms from '../lib/study-algorithms.js';
+import loadJSON from '../lib/load-json.js';
+import { expandCrawlResult } from 'reffy';
+import path from 'node:path';
 
 function reportToConsole(results) {
   const toreport = [];
@@ -35,12 +35,9 @@ async function main(crawlPath, anomalyType) {
     crawlPath = path.join(crawlPath, 'index.json');
   }
 
-  let crawl;
-  try {
-    crawl = requireFromWorkingDirectory(crawlPath);
-  }
-  catch(e) {
-    throw "Impossible to read " + crawlPath + ": " + e;
+  const crawl = await loadJSON(crawlPath);
+  if (!crawl) {
+    throw new Error("Impossible to read " + crawlPath);
   }
 
   const expanded = await expandCrawlResult(crawl, crawlPath.replace(/index\.json$/, ''), ['algorithms']);
@@ -49,18 +46,14 @@ async function main(crawlPath, anomalyType) {
 }
 
 /**************************************************
-Code run if the code is run as a stand-alone module
+Main loop
 **************************************************/
-if (require.main === module) {
-  const crawlPath = process.argv[2];
-
-  if (!crawlPath) {
-    console.error('Web IDL analyzer must be called with a paths to crawl results as first parameter');
-    process.exit(2);
-  }
-
-  main(crawlPath).catch(e => {
-    console.error(e);
-    process.exit(3);
-  });
+const crawlPath = process.argv[2];
+if (!crawlPath) {
+  console.error('Web IDL analyzer must be called with a paths to crawl results as first parameter');
+  process.exit(2);
 }
+main(crawlPath).catch(e => {
+  console.error(e);
+  process.exit(3);
+});