Provide discriminator property on feature data

Author: ddbeck

features/numeric-separators.yml.dist

@@ -1,6 +1,7 @@
 # Generated from: numeric-separators.yml
 # Do not edit this file by hand. Edit the source file instead!
 
+kind: feature
 status:
   baseline: high
   baseline_low_date: 2020-07-28

features/numeric-seperators.yml

@@ -1,3 +1,2 @@
-redirect:
-  reason: moved
-  target: numeric-separators
+kind: moved
+redirect_target: numeric-separators

features/webcodecs.yml

@@ -1,5 +1,4 @@
-redirect:
-  reason: split
-  targets:
-    - audio-codecs
-    - video-codecs
+kind: split
+redirect_targets:
+  - audio-codecs
+  - video-codecs

index.ts

@@ -14,7 +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';
+import { isMoved, isSplit } from './type-guards';
 
 // The longest name allowed, to allow for compact display.
 const nameMaxLength = 80;
@@ -188,7 +188,7 @@ for (const [key, data] of yamlEntries('features')) {
 
 function assertValidReference(sourceID: string, targetID: string): void {
     if (targetID in features) {
-        if (isRedirectData(features[targetID])) {
+        if (isMoved(features[targetID]) || isSplit(features[targetID])) {
             throw new Error(`${sourceID} references a redirect "${targetID}" instead of an ordinary feature ID`);
         }
         return;
@@ -197,27 +197,24 @@ function assertValidReference(sourceID: string, targetID: string): void {
 }
 
 for (const [id, feature] of Object.entries(features)) {
-    if (isOrdinaryFeatureData(feature)) {
-        for (const alternative of feature.discouraged?.alternatives ?? []) {
-            assertValidReference(id, alternative);
-        }
-    }
-
-    if (isRedirectData(feature)) {
-        const { reason } = feature.redirect;
-        switch (reason) {
-            case 'moved':
-                assertValidReference(id, feature.redirect.target);
-                break;
-            case 'split':
-                for (const target of feature.redirect.targets) {
-                    assertValidReference(id, target);
-                }
-                break;
-            default:
-                reason satisfies never;
-                throw new Error(`Unhandled redirect reason ${reason}}`);
-        }
+    const { kind } = feature;
+    switch (kind) {
+        case "feature":
+            for (const alternative of feature.discouraged?.alternatives ?? []) {
+                assertValidReference(id, alternative);
+            }
+            break;
+        case "moved":
+            assertValidReference(id, feature.redirect_target);
+            break;
+        case "split":
+            for (const target of feature.redirect_targets) {
+                assertValidReference(id, target);
+            }
+            break;
+        default:
+            kind satisfies never;
+            throw new Error(`Unhandled feature kind ${kind}}`);
     }
 }
 

schemas/data.schema.json

@@ -54,7 +54,8 @@
           {
             "$ref": "#/definitions/FeatureSplitData"
           }
-        ]
+        ],
+        "$comment": "Use the `kind` property as a discriminator."
       }
     },
     "groups": {
@@ -112,6 +113,9 @@
       "description": "A feature data entry",
       "type": "object",
       "properties": {
+        "kind": {
+          "const": "feature"
+        },
         "name": {
           "description": "Short name",
           "type": "string"
@@ -153,7 +157,14 @@
           "$ref": "#/definitions/Discouraged"
         }
       },
-      "required": ["name", "description", "description_html", "spec", "status"],
+      "required": [
+        "kind",
+        "name",
+        "description",
+        "description_html",
+        "spec",
+        "status"
+      ],
       "additionalProperties": false
     },
     "GroupData": {
@@ -191,44 +202,30 @@
       "description": "A feature has permanently moved to exactly one other ID",
       "type": "object",
       "properties": {
-        "redirect": {
-          "type": "object",
-          "properties": {
-            "reason": {
-              "const": "moved"
-            },
-            "target": {
-              "description": "The new ID for this feature",
-              "type": "string"
-            }
-          },
-          "required": ["reason", "target"],
-          "additionalProperties": false
+        "kind": {
+          "const": "moved"
+        },
+        "redirect_target": {
+          "description": "The new ID for this feature",
+          "type": "string"
         }
       },
-      "required": ["redirect"],
+      "required": ["kind", "redirect_target"],
       "additionalProperties": false
     },
     "FeatureSplitData": {
       "description": "A feature has split into two or more other features",
       "type": "object",
       "properties": {
-        "redirect": {
-          "type": "object",
-          "properties": {
-            "reason": {
-              "const": "split"
-            },
-            "targets": {
-              "description": "The new IDs for this feature",
-              "$ref": "#/definitions/Strings"
-            }
-          },
-          "required": ["reason", "targets"],
-          "additionalProperties": false
+        "kind": {
+          "const": "split"
+        },
+        "redirect_targets": {
+          "description": "The new IDs for this feature",
+          "$ref": "#/definitions/Strings"
         }
       },
-      "required": ["redirect"],
+      "required": ["kind", "redirect_targets"],
       "additionalProperties": false
     },
     "Status": {

scripts/build.ts

@@ -7,6 +7,7 @@ import { basename } from "node:path";
 import winston from "winston";
 import yargs from "yargs";
 import * as data from "../index.js";
+import { isOrdinaryFeatureData } from "../type-guards.js";
 import { validate } from "./validate.js";
 
 const logger = winston.createLogger({
@@ -68,7 +69,7 @@ function buildPackage() {
 
 function buildExtendedJSON() {
   for (const [id, featureData] of Object.entries(data.features)) {
-    if ("redirect" in featureData) {
+    if (!isOrdinaryFeatureData(featureData)) {
       continue;
     }
 

scripts/dist.ts

@@ -14,12 +14,7 @@ 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";
+import type { FeatureData, FeatureMovedData, FeatureSplitData } from "../types";
 
 const compat = new Compat();
 
@@ -189,7 +184,7 @@ function compareStatus(a: SupportStatus, b: SupportStatus) {
 
 function toRedirectDist(
   id: string,
-  source: FeatureMovedData | FeatureRedirectData,
+  source: FeatureMovedData | FeatureSplitData,
 ): YAML.Document {
   const dist = new Document({});
 
@@ -199,17 +194,20 @@ function toRedirectDist(
     `Do not edit this file.`,
   ];
 
-  switch (source.redirect.reason) {
+  const { kind } = source;
+  switch (kind) {
     case "moved":
       comment.push(
-        `The data for this feature has moved to ${(source as FeatureMovedData).redirect.target}.yml`,
+        `The data for this feature has moved to ${source.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`));
+      comment.push(...source.redirect_targets.map((dest) => `  - ${dest}.yml`));
       break;
+    default:
+      source satisfies never;
+      throw new Error(`Unhandled feature kind ${kind}}`);
   }
 
   dist.commentBefore = comment.map((line) => ` ${line}`).join("\n");
@@ -228,9 +226,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)) {
+  if ("redirect_target" in source || "redirect_targets" in source) {
     return toRedirectDist(id, source);
   }
+  source as Partial<FeatureData>;
 
   // Collect tagged compat features. A `compat_features` list in the source
   // takes precedence, but can be removed if it matches the tagged features.
@@ -340,7 +339,7 @@ function toDist(sourcePath: string): YAML.Document {
   }
 
   // Assemble and return the dist YAML.
-  const dist = new Document({});
+  const dist = new Document({ kind: "feature" });
 
   dist.commentBefore = [
     `Generated from: ${id}.yml`,

scripts/specs.ts

@@ -3,7 +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";
+import { isOrdinaryFeatureData } 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
@@ -192,7 +192,7 @@ for (const [allowedUrl, message] of defaultAllowlist) {
 }
 
 for (const [id, data] of Object.entries(features)) {
-    if (isRedirectData(data)) {
+    if (!isOrdinaryFeatureData(data)) {
         continue;
     }
 

type-guards.ts

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

types.quicktype.ts

@@ -90,6 +90,7 @@ export interface FeatureData {
    * Group identifier(s)
    */
   group?: string[] | string;
+  kind: Kind;
   /**
    * Short name
    */
@@ -107,7 +108,14 @@ export interface FeatureData {
    * that status
    */
   status?: StatusHeadline;
-  redirect?: Redirect;
+  /**
+   * The new ID for this feature
+   */
+  redirect_target?: string;
+  /**
+   * The new IDs for this feature
+   */
+  redirect_targets?: string[];
 }
 
 /**
@@ -125,19 +133,7 @@ export interface Discouraged {
   alternatives?: string[];
 }
 
-export interface Redirect {
-  reason: Reason;
-  /**
-   * The new ID for this feature
-   */
-  target?: string;
-  /**
-   * The new IDs for this feature
-   */
-  targets?: string[];
-}
-
-export type Reason = "moved" | "split";
+export type Kind = "feature" | "moved" | "split";
 
 /**
  * Whether a feature is considered a "Baseline" web platform feature and when it achieved