Add script to inspect compat key notes (web-platform-dx#3294)

Author: ddbeck

index.ts

@@ -4,14 +4,9 @@ import path from 'path';
 import { Temporal } from '@js-temporal/polyfill';
 import { fdir } from 'fdir';
 import YAML from 'yaml';
+import { convertMarkdown } from "./text";
 import { FeatureData, GroupData, SnapshotData, WebFeaturesData } from './types';
 
-import { toString as hastTreeToString } from 'hast-util-to-string';
-import rehypeStringify from 'rehype-stringify';
-import remarkParse from 'remark-parse';
-import remarkRehype from 'remark-rehype';
-import { unified } from 'unified';
-
 import { BASELINE_LOW_TO_HIGH_DURATION, coreBrowserSet, parseRangedDateString } from 'compute-baseline';
 import { Compat } from 'compute-baseline/browser-compat-data';
 
@@ -121,20 +116,6 @@ function* identifiers(value) {
     }
 }
 
-function convertMarkdown(markdown: string) {
-    const mdTree = unified().use(remarkParse).parse(markdown);
-    const htmlTree = unified().use(remarkRehype).runSync(mdTree);
-    const text = hastTreeToString(htmlTree);
-
-    let html = unified().use(rehypeStringify).stringify(htmlTree);
-    // Remove leading <p> and trailing </p> if there is only one of each in the
-    // description. (If there are multiple paragraphs, let them be.)
-    if (html.lastIndexOf('<p>') === 0 && html.indexOf('</p>') === html.length - 4) {
-      html = html.substring(3, html.length - 4);
-    }
-
-    return { text, html };
-}
 
 // Map from BCD keys/paths to web-features identifiers.
 const bcdToFeatureId: Map<string, string> = new Map();

package-lock.json

@@ -48,11 +48,13 @@
     "caniuse-lite": "^1.0.30001737",
     "cheerio": "^1.1.2",
     "diff": "^8.0.2",
+    "escape-html": "^1.0.3",
     "eslint-plugin-new-with-error": "^5.0.0",
     "fast-json-stable-stringify": "^2.1.0",
     "fdir": "^6.5.0",
     "hast-util-to-string": "^3.0.1",
     "prettier": "^3.6.2",
+    "rehype-parse": "^9.0.1",
     "rehype-stringify": "^10.0.1",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",

package.json

@@ -0,0 +1,133 @@
+import { coreBrowserSet, getStatus } from "compute-baseline";
+import escapeHtml from "escape-html";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import YAML from "yaml";
+import yargs from "yargs";
+import { features } from "..";
+import { defaultCompat } from "../packages/compute-baseline/dist/browser-compat-data/compat";
+import { feature } from "../packages/compute-baseline/dist/browser-compat-data/feature";
+import { SupportStatement } from "../packages/compute-baseline/dist/browser-compat-data/supportStatements";
+import { convertHTML } from "../text";
+import { FeatureData } from "../types";
+
+interface Args {
+  paths: string[];
+  verbose: number;
+}
+
+const argv = yargs(process.argv.slice(2))
+  .scriptName("dist")
+  .usage("$0 [paths..]", "Inspect a .yml or .dist file", (yargs) =>
+    yargs.positional("paths", {
+      describe: "Directories or files to inspect.",
+      default: ["features/a.yml"],
+    }),
+  )
+  .option("verbose", {
+    alias: "v",
+    describe: "Show more detail",
+    type: "count",
+    default: 0,
+    defaultDescription: "warn",
+  }).argv as Args;
+
+function main(): void {
+  for (const filePath of argv.paths) {
+    const { name, ext, dir } = path.parse(filePath);
+    const id = ext === ".dist" ? path.basename(name, ".yml") : name;
+
+    const yamlFile = path.join(dir, `${id}.yml`);
+    const distFile = `${yamlFile}.dist`;
+
+    const feature = features[id];
+    if (!feature) {
+      throw new Error(`No feature found for ID ${id}`);
+    }
+
+    const { compat_features } = feature;
+
+    console.log(`${escapeHtml(feature.name)} (${yamlFile}, ${distFile})\n`);
+
+    // Iterate over the compat keys in the order given by the dist file
+    const yml = YAML.parse(
+      fs.readFileSync(distFile, { encoding: "utf-8" }),
+    ) as Partial<FeatureData>;
+    let compatKeys: string[];
+    if (yml.compat_features?.length > 0) {
+      compatKeys = yml.compat_features;
+    } else if (compat_features && compat_features.length > 0) {
+      compatKeys = compat_features;
+    } else {
+      compatKeys = [];
+    }
+
+    for (const compatKey of compatKeys) {
+      const status = getStatus(id, compatKey);
+      console.log(
+        `- ${compatKey}${status.baseline ? ` (${status.baseline})` : ""}`,
+      );
+      for (const [browser, notes] of getNotes(compatKey).entries()) {
+        console.log(`    - ${browser}`);
+        for (const note of notes) {
+          console.log(`      - ${convertHTML(note).text}`);
+        }
+      }
+    }
+  }
+}
+
+function getNotes(compatKey: string): Map<string, string[]> {
+  const browserNotes = new Map<string, string[]>();
+  const f = feature(compatKey);
+  for (const browserKey of coreBrowserSet) {
+    const statements = f
+      .supportStatements(defaultCompat.browser(browserKey))
+      .filter(isEligibleStatement);
+    for (const statement of statements) {
+      const notes = Array.isArray(statement.data.notes!)
+        ? statement.data.notes
+        : [statement.data.notes];
+      for (const note of notes) {
+        browserNotes.set(statement.browser.id, [
+          ...(browserNotes.get(statement.browser.id) ?? []),
+          `${statement.partial_implementation ? `[partial_implementation] ` : ""}${statement.version_added}+: ${note}`,
+        ]);
+      }
+    }
+  }
+  return browserNotes;
+}
+
+function isEligibleStatement(statement: SupportStatement): boolean {
+  if (statement.version_added === false) {
+    return false;
+  }
+  if (statement.version_removed) {
+    return false;
+  }
+  if (statement.flags.length) {
+    return false;
+  }
+  if (statement.data.alternative_name) {
+    return false;
+  }
+  if (statement.data.prefix) {
+    return false;
+  }
+  const { notes } = statement.data;
+  if (notes === undefined) {
+    return false;
+  }
+  if (notes.length === 0) {
+    return false;
+  }
+  return true;
+}
+
+if (import.meta.url.startsWith("file:")) {
+  if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main();
+  }
+}

scripts/inspect-feature.ts

@@ -0,0 +1,31 @@
+import { toString as hastTreeToString } from "hast-util-to-string";
+import rehypeParse from "rehype-parse";
+import rehypeStringify from "rehype-stringify";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+
+export function convertMarkdown(markdown: string) {
+  const mdTree = unified().use(remarkParse).parse(markdown);
+  const htmlTree = unified().use(remarkRehype).runSync(mdTree);
+  const text = hastTreeToString(htmlTree);
+
+  let html = unified().use(rehypeStringify).stringify(htmlTree);
+  // Remove leading <p> and trailing </p> if there is only one of each in the
+  // description. (If there are multiple paragraphs, let them be.)
+  if (
+    html.lastIndexOf("<p>") === 0 &&
+    html.indexOf("</p>") === html.length - 4
+  ) {
+    html = html.substring(3, html.length - 4);
+  }
+
+  return { text, html };
+}
+
+export function convertHTML(html: string) {
+  const htmlTree = unified().use(rehypeParse).parse(html);
+  const text = hastTreeToString(htmlTree);
+
+  return { text };
+}