Update scripts to use redirects

Author: ddbeck

index.ts

@@ -4,7 +4,7 @@ import path from 'path';
 import { Temporal } from '@js-temporal/polyfill';
 import { fdir } from 'fdir';
 import YAML from 'yaml';
-import { FeatureData, GroupData, SnapshotData, WebFeaturesData } from './types';
+import { GroupData, SnapshotData, WebFeaturesData } from './types';
 
 import { toString as hastTreeToString } from 'hast-util-to-string';
 import rehypeStringify from 'rehype-stringify';
@@ -14,6 +14,7 @@ import { unified } from 'unified';
 
 import { BASELINE_LOW_TO_HIGH_DURATION, coreBrowserSet, parseRangedDateString } from 'compute-baseline';
 import { Compat } from 'compute-baseline/browser-compat-data';
+import { isOrdinaryFeatureData, isRedirectData } from './type-guards';
 
 // The longest name allowed, to allow for compact display.
 const nameMaxLength = 80;
@@ -117,7 +118,7 @@ function convertMarkdown(markdown: string) {
 // Map from BCD keys/paths to web-features identifiers.
 const bcdToFeatureId: Map<string, string> = new Map();
 
-const features: { [key: string]: FeatureData } = {};
+const features: WebFeaturesData["features"] = {};
 for (const [key, data] of yamlEntries('features')) {
     // Draft features reserve an identifier but aren't complete yet. Skip them.
     if (data[draft]) {
@@ -182,11 +183,34 @@ for (const [key, data] of yamlEntries('features')) {
     features[key] = data;
 }
 
-// Assert that discouraged feature's alternatives are valid
+// Assert that feature references are valid
 for (const [id, feature] of Object.entries(features)) {
-    for (const alternative of feature.discouraged?.alternatives ?? []) {
-        if (!(alternative in features)) {
-            throw new Error(`${id}'s alternative "${alternative}" is not a valid feature ID`);
+    if (isOrdinaryFeatureData(feature)) {
+        for (const alternative of feature.discouraged?.alternatives ?? []) {
+            if (!(alternative in features)) {
+                throw new Error(`${id}'s alternative "${alternative}" is not a valid feature ID`);
+            }
+        }
+    }
+
+    if (isRedirectData(feature)) {
+        const { reason } = feature.redirect;
+        switch (reason) {
+            case 'moved':
+                if (!(feature.redirect.target in features)) {
+                    throw new Error(`${id}'s redirect target "${feature.redirect.target} is not a valid feature ID`);
+                }
+                break;
+            case 'split':
+                for (const target of feature.redirect.targets) {
+                    if (!(target in features)) {
+                        throw new Error(`${id}'s redirect target "${target}" is not a valid feature ID`);
+                    }
+                }
+                break;
+            default:
+                reason satisfies never;
+                throw new Error(`Unhandled redirect reason ${reason}}`);
         }
     }
 }

scripts/build.ts

@@ -68,6 +68,10 @@ function buildPackage() {
 
 function buildExtendedJSON() {
   for (const [id, featureData] of Object.entries(data.features)) {
+    if ("redirect" in featureData) {
+      continue;
+    }
+
     if (
       Array.isArray(featureData.compat_features) &&
       featureData.compat_features.length &&

scripts/dist.ts

@@ -14,6 +14,12 @@ import { isDeepStrictEqual } from "node:util";
 import winston from "winston";
 import YAML, { Document, Scalar, YAMLSeq } from "yaml";
 import yargs from "yargs";
+import { isRedirectData } from "../type-guards";
+import {
+  FeatureMovedData,
+  FeatureRedirectData,
+  FeatureSplitData,
+} from "../types";
 
 const compat = new Compat();
 
@@ -181,6 +187,36 @@ function compareStatus(a: SupportStatus, b: SupportStatus) {
   return 0;
 }
 
+function toRedirectDist(
+  id: string,
+  source: FeatureMovedData | FeatureRedirectData,
+): YAML.Document {
+  const dist = new Document({});
+
+  const comment = [
+    `Generated from: ${id}.yml`,
+    `This file intentionally left blank.`,
+    `Do not edit this file.`,
+  ];
+
+  switch (source.redirect.reason) {
+    case "moved":
+      comment.push(
+        `The data for this feature has moved to ${(source as FeatureMovedData).redirect.target}.yml`,
+      );
+      break;
+    case "split":
+      const targets = (source as FeatureSplitData).redirect.targets;
+      comment.push(`The data for this feature has moved to:`);
+      comment.push(...targets.map((to) => `  - ${to}.yml`));
+      break;
+  }
+
+  dist.commentBefore = comment.map((line) => ` ${line}`).join("\n");
+
+  return dist;
+}
+
 /**
  * Generate a dist YAML document from a feature definition YAML file path.
  *
@@ -192,6 +228,10 @@ function toDist(sourcePath: string): YAML.Document {
   const source = YAML.parse(fs.readFileSync(sourcePath, { encoding: "utf-8" }));
   const { name: id } = path.parse(sourcePath);
 
+  if (isRedirectData(source)) {
+    return toRedirectDist(id, source);
+  }
+
   // Collect tagged compat features. A `compat_features` list in the source
   // takes precedence, but can be removed if it matches the tagged features.
   const taggedCompatFeatures = (tagsToFeatures.get(`web-features:${id}`) ?? [])

scripts/find-ranged-headline-statuses.ts

@@ -1,7 +1,13 @@
 import { features } from "../index";
+import { isOrdinaryFeatureData } from "../type-guards";
 
 for (const [key, data] of Object.entries(features)) {
-  if ((data.status.baseline_low_date ?? "").includes("≤")) {
-    console.log(key);
+  if (isOrdinaryFeatureData(data)) {
+    if (
+      "status" in data &&
+      (data.status.baseline_low_date ?? "").includes("≤")
+    ) {
+      console.log(key);
+    }
   }
 }

scripts/specs.ts

@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
 import webSpecs from 'web-specs' with { type: 'json' };
 
 import { features } from '../index.js';
+import { isRedirectData } from "../type-guards.js";
 
 // Specs needs to be in "good standing". Nightly URLs are used if available,
 // otherwise the snapshot/versioned URL is used. See browser-specs/web-specs
@@ -191,6 +192,10 @@ for (const [allowedUrl, message] of defaultAllowlist) {
 }
 
 for (const [id, data] of Object.entries(features)) {
+    if (isRedirectData(data)) {
+        continue;
+    }
+
     const specs = Array.isArray(data.spec) ? data.spec : [data.spec];
     for (const spec of specs) {
         let url: URL;

scripts/stats.ts

@@ -2,6 +2,7 @@ import { Compat } from "compute-baseline/browser-compat-data";
 import { fileURLToPath } from "node:url";
 import yargs from "yargs";
 import { features } from "../index.js";
+import { isOrdinaryFeatureData } from "../type-guards.js";
 
 const argv = yargs(process.argv.slice(2))
   .scriptName("stats")
@@ -14,11 +15,20 @@ const argv = yargs(process.argv.slice(2))
   }).argv;
 
 export function stats(detailed: boolean = false) {
-  const featureCount = Object.keys(features).length;
+  const featureCount = Object.values(features).filter(
+    isOrdinaryFeatureData,
+  ).length;
 
   const keys = [];
   const doneKeys = Array.from(
-    new Set(Object.values(features).flatMap((f) => f.compat_features ?? [])),
+    new Set(
+      Object.values(features).flatMap((f) => {
+        if (isOrdinaryFeatureData(f)) {
+          return f.compat_features ?? [];
+        }
+        return [];
+      }),
+    ),
   );
   const toDoKeys = [];
 
@@ -35,6 +45,7 @@ export function stats(detailed: boolean = false) {
   }
 
   const featureSizes = Object.values(features)
+    .filter(isOrdinaryFeatureData)
     .map((feature) => (feature.compat_features ?? []).length)
     .sort((a, b) => a - b);
 

scripts/update-drafts.ts

@@ -11,6 +11,7 @@ import { Document, parse } from "yaml";
 import yargs from "yargs";
 
 import { features } from "../index.js";
+import { isOrdinaryFeatureData } from "../type-guards.js";
 import { FeatureData } from "../types.js";
 
 type WebSpecsSpec = (typeof webSpecs)[number];
@@ -84,7 +85,7 @@ async function main() {
   // Build a map of used BCD keys to feature.
   const webFeatures = new Map<string, string>();
   Object.values(features).map((data) => {
-    if (data.compat_features) {
+    if (isOrdinaryFeatureData(data) && data.compat_features) {
       for (const compatFeature of data.compat_features) {
         webFeatures.set(compatFeature, data.name);
       }
@@ -261,9 +262,12 @@ async function main() {
   }
 
   // Clean up completed specs, even if they've been superseded
-  const assignedKeys = Object.values(features).flatMap(
-    (f) => f.compat_features ?? [],
-  );
+  const assignedKeys = Object.values(features).flatMap((f) => {
+    if (isOrdinaryFeatureData(f)) {
+      return f.compat_features ?? [];
+    }
+    return [];
+  });
   for (const spec of webSpecs) {
     const id = formatIdentifier(spec.shortname);
     const destination = `features/draft/spec/${id}.yml`;

type-guards.ts

@@ -0,0 +1,9 @@
+import type { FeatureData, FeatureRedirectData } from "./types";
+
+export function isOrdinaryFeatureData(x: unknown): x is FeatureData {
+  return typeof x === "object" && "name" in x;
+}
+
+export function isRedirectData(x: unknown): x is FeatureRedirectData {
+  return typeof x === "object" && "redirect" in x;
+}