test: guard the public feature graph

.github/workflows/ci.yml

@@ -36,6 +36,9 @@ jobs:
       - name: Rebuild ReScript code
         run: npm run build
 
+      - name: Check public feature builds
+        run: npm run check:features
+
       - name: Run tests
         run: npm test
 

astro.config.mjs

@@ -7,24 +7,10 @@ const rescriptTM = JSON.parse(
   readFileSync("./docs/assets/rescript.tmLanguage.json", "utf-8"),
 );
 
-const apiSidebarItems = apiModules.map(({ moduleName, link, items }) => {
-  const nestedItems = Object.values(items).map(({ moduleName, link }) => ({
-    label: moduleName,
-    link,
-  }));
-
-  return {
-    label: moduleName,
-    collapsed: true,
-    items: [
-      {
-        label: `Overview`,
-        link,
-      },
-      ...nestedItems,
-    ],
-  };
-});
+const apiSidebarItems = apiModules.map(({ moduleName, link }) => ({
+  label: moduleName,
+  link,
+}));
 
 export default defineConfig({
   srcDir: "docs",

docs/components/apidoc.astro

@@ -1,5 +1,5 @@
 ---
-import { apiModules, getDoc } from "../utils";
+import { getDoc } from "../utils";
 import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
 import Value from "./value.astro";
 import Type from "./type.astro";

docs/content/docs/api-surface.mdx

@@ -41,6 +41,40 @@ Generated implementation modules such as `DomTypes`, `FetchTypes`, `EventTypes`,
 module's `t` type when it has one, or use a dedicated public type module. Otherwise, let
 the value type be inferred from constructors and accessors.
 
+## Consumer feature bundles
+
+Feature names select related bindings and their transitive dependencies. They do not add
+another namespace segment. For example, selecting `WebAPI.Fetch` enables flat modules such
+as `WebAPI.Fetch`, `WebAPI.Request`, `WebAPI.Response`, and `WebAPI.Headers`.
+
+```json
+{
+  "dependencies": [
+    {
+      "name": "@rescript/webapi",
+      "features": ["WebAPI.Fetch", "WebAPI.HTML"]
+    }
+  ]
+}
+```
+
+The supported feature bundles are:
+
+```text
+WebAPI.DOM                 WebAPI.Event           WebAPI.DOMPlatform
+WebAPI.DOMNodes            WebAPI.File            WebAPI.HTML
+WebAPI.Window              WebAPI.CSSOM           WebAPI.CSSFontLoading
+WebAPI.Geometry            WebAPI.SVG             WebAPI.Animation
+WebAPI.Device              WebAPI.Navigator       WebAPI.Canvas
+WebAPI.URL                 WebAPI.Fetch           WebAPI.UIEvents
+WebAPI.Observers           WebAPI.Media           WebAPI.WebAudio
+WebAPI.Storage             WebAPI.Messaging       WebAPI.Workers
+WebAPI.Crypto              WebAPI.Performance     WebAPI.ViewTransitions
+```
+
+The package owns each bundle as one internal source folder. Those internal folder feature
+names are an implementation detail; consumers should use only the qualified names above.
+
 ## Fetch
 
 Use `WebAPI.Fetch.fetch` for string URLs and `WebAPI.Fetch.fetchWithRequest`

docs/llm.js

@@ -2,7 +2,6 @@ import * as path from "node:path";
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import fs from "node:fs/promises";
-import { featureSpecs } from "../scripts/unmonorepo/feature-spec.mjs";
 
 const execAsync = promisify(exec);
 
@@ -95,12 +94,11 @@ Module: ${moduleName}${typeString}${functionString}
 `;
 }
 
-const specByDir = new Map(featureSpecs.map((spec) => [spec.dirName, spec]));
 const rootDir = path.join(import.meta.dirname, "..");
 const rootConfig = JSON.parse(await fs.readFile(path.join(rootDir, "rescript.json"), "utf-8"));
 const publicModulesBySourceDir = new Map(
   rootConfig.sources
-    .filter((source) => typeof source === "object")
+    .filter((source) => source !== null && typeof source === "object")
     .filter((source) => source.dir?.startsWith("src/") && Array.isArray(source.public))
     .map((source) => [source.dir, new Set(source.public)]),
 );
@@ -130,16 +128,7 @@ function isPublicFile(filePath) {
 }
 
 function moduleNameForFile(relativePath) {
-  const [, dirName, fileName] = relativePath.split(path.sep);
-  const spec = specByDir.get(dirName);
-
-  if (!spec) {
-    throw new Error(`Unsupported source directory for documentation: ${relativePath}`);
-  }
-
-  const leafName = path.basename(fileName, ".res");
-
-  return `WebAPI.${leafName}`;
+  return `WebAPI.${path.basename(relativePath, ".res")}`;
 }
 
 const pattern = "../src/*/**/*.res";

docs/utils.js

@@ -3,16 +3,16 @@ import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import { readdirSync, existsSync, readFileSync } from "fs";
 import { micromark } from "micromark";
-import { featureSpecs } from "../scripts/unmonorepo/feature-spec.mjs";
 
 const execAsync = promisify(exec);
 const rootDir = process.cwd();
 const rootConfig = JSON.parse(readFileSync(path.join(rootDir, "rescript.json"), "utf8"));
-const publicModulesBySourceDir = new Map(
-  rootConfig.sources
-    .filter((source) => typeof source === "object")
-    .filter((source) => source.dir?.startsWith("src/") && Array.isArray(source.public))
-    .map((source) => [source.dir, new Set(source.public)]),
+const publicSourceEntries = rootConfig.sources.filter(
+  (source) =>
+    source !== null &&
+    typeof source === "object" &&
+    source.dir?.startsWith("src/") &&
+    Array.isArray(source.public),
 );
 
 function toKebabCase(input) {
@@ -32,64 +32,16 @@ export function createTypeModuleLink(parentModuleLink, typeName) {
   return `${parentModuleLink}/${toKebabCase(typeName)}`;
 }
 
-function mapTypeModules(parentModuleLink, file, spec) {
-  const folder = path.dirname(file);
-
-  if (!existsSync(folder)) {
-    return [];
-  }
-
-  const publicModules = publicModulesBySourceDir.get(spec.sourceDir) ?? new Set();
-  const typesFileName = `${spec.internalPrefix}Types.res`;
-  const files = readdirSync(folder);
-  return files
-    .filter((f) => f.endsWith(".res") && f !== typesFileName)
-    .filter((file) => publicModules.has(file.replace("$", "").replace(".res", "")))
-    .map((file) => {
-      const filePath = path.join(folder, file);
-
-      const leafName = file.replace("$", "").replace(".res", "");
-      const moduleName = leafName;
-      const apiRouteParameter = toKebabCase(moduleName);
-      const link = createTypeModuleLink(parentModuleLink, moduleName);
-      const typeName = moduleName[0].toLocaleLowerCase() + moduleName.slice(1);
-
-      return [
-        typeName,
-        {
-          filePath,
-          moduleName,
-          link,
-          apiRouteParameter,
-        },
-      ];
-    });
-}
-
-function mapRescriptFile(srcDir, file, spec) {
-  const filePath = path.join(srcDir, file);
-  const moduleName = spec.publicModule;
-  const link = createAPIModuleLink(moduleName);
-  const items = Object.fromEntries(mapTypeModules(link, filePath, spec));
-
-  return {
-    filePath,
-    moduleName,
-    link,
-    apiRouteParameter: toKebabCase(moduleName),
-    items,
-  };
-}
-
-const srcRoot = path.resolve(process.cwd(), "src");
-export const apiModules = featureSpecs
-  .map((spec) => ({
-    spec,
-    srcDir: path.join(srcRoot, spec.dirName),
-    typesFileName: `${spec.internalPrefix}Types.res`,
-  }))
-  .filter(({ srcDir, typesFileName }) => existsSync(path.join(srcDir, typesFileName)))
-  .map(({ spec, srcDir, typesFileName }) => mapRescriptFile(srcDir, typesFileName, spec))
+export const apiModules = publicSourceEntries
+  .flatMap((source) =>
+    source.public.map((moduleName) => ({
+      filePath: path.join(rootDir, source.dir, `${moduleName}.res`),
+      moduleName,
+      link: createAPIModuleLink(moduleName),
+      apiRouteParameter: toKebabCase(moduleName),
+    })),
+  )
+  .filter(({ filePath }) => existsSync(filePath))
   .sort((a, b) => a.moduleName.localeCompare(b.moduleName));
 
 async function getRescriptDoc(absoluteFilePath) {

package.json

@@ -38,8 +38,9 @@
   "scripts": {
     "test": "node tests/index.js",
     "build": "rescript",
-    "format": "rescript format && oxfmt ./tests/index.js ./package.json ./docs && prettier --write ./docs/pages",
-    "format:check": "rescript format --check && oxfmt ./tests/index.js ./package.json ./docs --check && prettier --check ./docs/pages",
+    "check:features": "node scripts/check-features.mjs",
+    "format": "rescript format && oxfmt ./tests/index.js ./scripts/check-features.mjs ./package.json ./docs && prettier --write ./docs/pages",
+    "format:check": "rescript format --check && oxfmt ./tests/index.js ./scripts/check-features.mjs ./package.json ./docs --check && prettier --check ./docs/pages",
     "docs": "astro dev",
     "prebuild:docs": "node docs/llm.js",
     "build:docs": "astro build"