Provide an approved method to get a status for a single BCD key

packages/compute-baseline/README.md

@@ -2,23 +2,21 @@
 
 By the [W3C WebDX Community Group](https://www.w3.org/community/webdx/) and contributors.
 
-`compute-baseline` computes preliminary [Baseline statuses](https://github.com/web-platform-dx/web-features/blob/main/docs/baseline.md) from `@mdn/browser-compat-data` feature keys.
+`compute-baseline` computes [Baseline statuses](https://github.com/web-platform-dx/web-features/blob/main/docs/baseline.md) from `@mdn/browser-compat-data` feature keys.
 You can use `compute-baseline` to help you find interoperable web platform features, propose new [`web-features`](https://github.com/web-platform-dx/web-features/) features, or compare support between features.
 
 `compute-baseline` also provides utility classes for working with `@mdn/browser-compat-data` generally.
 
 ## Limitations
 
-If you need authoritative Baseline statuses, check out the [`web-features`](https://github.com/web-platform-dx/web-features/tree/main/packages/web-features) package instead.
+If you need authoritative Baseline statuses, check out the [`web-features`](https://github.com/web-platform-dx/web-features/tree/main/packages/web-features) package first.
+Most of the time, the status information provided by `web-features` is the best representation of a feature overall.
 
-Don't use `compute-baseline` to generate publishable Baseline statuses for arbitrary web platform features.
-The results of `compute-baseline` invocations have _not_ received editorial review.
-Strictly speaking, a Baseline status requires editorial review, so statuses generated by `compute-baseline` are tentative.
-If you need authoritative Baseline statuses, check out the [`web-features`](https://github.com/web-platform-dx/web-features/tree/main/packages/web-features) package instead.
-
-You can use `compute-baseline` to explore possibilities or do error correction.
-For example, you might use `compute-baseline` to hide a Baseline status, when showing a broader feature's status might be misleading.
+If you need to know the Baseline status of a specific browser compatibility data entry within a `web-features` feature, then you can use the `getStatus` method.
+The `web-features` package and the `getStatus` method are the **only** ways to get a status that have completed the full Baseline editorial review process.
 
+All other invocations of `compute-baseline` have _not_ received editorial review.
+Don't use `compute-baseline` to generate publishable Baseline statuses for arbitrary web platform features.
 If you're not sure whether your application fits with the definition of Baseline, please [file an issue](https://github.com/web-platform-dx/web-features/issues/new).
 
 ## Prerequisites
@@ -40,6 +38,33 @@ Run:
 
 ## Usage
 
+### Get a Baseline status for a portion of a feature
+
+```javascript
+import { getStatus } from "compute-baseline";
+
+getStatus("fetch", "api.Response.json");
+```
+
+Returns:
+
+```
+{
+  baseline: 'high',
+  baseline_low_date: '2017-03-27',
+  baseline_high_date: '2019-09-27',
+  support: {
+    chrome: '42',
+    chrome_android: '42',
+    edge: '14',
+    firefox: '39',
+    firefox_android: '39',
+    safari: '10.1',
+    safari_ios: '10.3'
+  }
+}
+```
+
 ### Check support for a group of compat keys
 
 ```javascript
@@ -92,17 +117,12 @@ If you don't want to import `@mdn/browser-compat-data` as your data source, you
 
 ```javascript
 import data from "some-parsed-json-file";
-import { computeBaseline } from "compute-baseline";
+import { getStatus } from "compute-baseline";
 import { Compat } from "compute-baseline/browser-compat-data";
 
 const compat = new Compat(data);
 
-computeBaseline(
-  {
-    compatKeys: ["css.properties.border-color"],
-  },
-  compat,
-);
+getStatus("fetch", "api.Response.json", compat);
 ```
 
 <!-- TODO: API reference -->

packages/compute-baseline/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compute-baseline",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A library for computing web-features statuses from browser compatibility data",
   "exports": {
     ".": "./dist/baseline/index.js",

packages/compute-baseline/src/baseline/index.test.ts

@@ -4,10 +4,26 @@ import { Temporal } from "@js-temporal/polyfill";
 import * as chai from "chai";
 import chaiJestSnapshot from "chai-jest-snapshot";
 
-import { computeBaseline, keystoneDateToStatus } from "./index.js";
+import { computeBaseline, getStatus, keystoneDateToStatus } from "./index.js";
 
 chai.use(chaiJestSnapshot);
 
+describe("getStatus", function () {
+  before(function () {
+    chaiJestSnapshot.resetSnapshotRegistry();
+  });
+
+  beforeEach(function () {
+    chaiJestSnapshot.configureUsingMochaContext(this);
+  });
+
+  it("returns a status", function () {
+    const result = getStatus("fetch", "api.Response.json");
+    assert.equal(result.baseline, "high");
+    chai.expect(result).to.matchSnapshot();
+  });
+});
+
 describe("computeBaseline", function () {
   before(function () {
     chaiJestSnapshot.resetSnapshotRegistry();

packages/compute-baseline/src/baseline/index.test.ts.snap

@@ -130,3 +130,20 @@ Object {
 }",
 }
 `;
+
+exports[`getStatus returns a status 1`] = `
+Object {
+  "baseline": "high",
+  "baseline_high_date": "2019-09-27",
+  "baseline_low_date": "2017-03-27",
+  "support": Object {
+    "chrome": "42",
+    "chrome_android": "42",
+    "edge": "14",
+    "firefox": "39",
+    "firefox_android": "39",
+    "safari": "10.1",
+    "safari_ios": "10.3",
+  },
+}
+`;

packages/compute-baseline/src/baseline/index.ts

@@ -44,6 +44,33 @@ interface SupportStatus {
   toJSON: () => string;
 }
 
+/**
+ * Calculate a Baseline status for specific browser compat data keys within a
+ * web-features feature, in the style of a web-feature's `status` key. Use this
+ * method to calculate fine-grained support statuses. This is the only method
+ * approved to compute Baseline statuses not otherwise published in the
+ * `web-features` package.
+ *
+ * For example, suppose you want to show a Baseline status for a specific method
+ * in a feature, which might've been supported earlier or later than the broader
+ * feature overall. Then you'd call `getStatus('example-feature',
+ * 'api.ExampleManager.doExample')`.
+ */
+export function getStatus(
+  featureId: string,
+  compatKey: string,
+  compat: Compat = defaultCompat,
+) {
+  // TODO: actually check that featureId is a valid feature
+  // TODO: actually check that compatKey is tagged as featureId in BCD _or_ listed in web-features
+  return JSON.parse(
+    computeBaseline(
+      { compatKeys: [compatKey], checkAncestors: true },
+      compat,
+    ).toJSON(),
+  );
+}
+
 /**
  * Given a set of compat keys, compute the aggregate Baseline support ("high",
  * "low" or false, dates, and releases) for those keys.