Add environment variable for skipping early-stage entries (#316)

* Add environment variable for skipping needsAdditionalResearch entries
* Also skip placeholder/exploratory entries
* Set default status for requirements; limit values on groups/guidelines
* Update README to reflect status field changes

Author: kfranqueiro

README.md

@@ -93,6 +93,7 @@ Each group is defined in a JSON file, with its child guidelines located in a
 subdirectory with the same name.
 
 - Supports [common fields](#common-fields): `children`, `status`
+  - `status` for groups is optional, limited to `developing`, `refining`, `mature`
 - No additional unique fields
 
 #### Guidelines
@@ -102,13 +103,15 @@ listed under. Each guideline is defined in a Markdown file, with its child
 requirements/assertions located in a subdirectory with the same name.
 
 - Supports [common fields](#common-fields): `children`, `howto`, `status`, `title`
+  - `status` for guidelines is optional, limited to `developing`, `refining`, `mature`
 - No additional unique fields
 
 #### Requirements and Assertions
 
 Represents each fifth-level heading specifying an individual requirement or assertion.
 
 - Supports [common fields](#common-fields): `howto`, `status`, `title`
+  - `status` for requirements and assertions defaults to `exploratory` if not specified
 - `needsAdditionalResearch` - Optional boolean, indicating whether to
   display a "needs additional research" editor's note
 - `type` - Optional string: `foundational`, `supplemental`, or `assertion`
@@ -308,8 +311,13 @@ create a Markdown file under `terms`, then populate its content and any applicab
 
 ### `WCAG_DIFFABLE`
 
-Filters build output to reduce noise when diffing output between changes.
+When set, filters build output to reduce noise when diffing output between changes.
 This is for maintenance purposes only, to catch regressions;
 built code is not expected to run properly when this is active!
 
 **Default:** Unset (set to any non-empty value to enable)
+
+### `WCAG_SKIP_WIP`
+
+When set, excludes requirements/assertions that have `needsAdditionalResearch` set to `true`,
+or that have `status` set to `placeholder` or `exploratory`.

src/content.config.ts

@@ -5,11 +5,11 @@ import uniq from "lodash-es/uniq";
 /** howto can be set to true to indicate the informative and normative slugs are identical */
 const howtoSchema = z.boolean().or(z.string().regex(/^[\w-]+$/));
 const statusSchema = z.enum(["placeholder", "exploratory", "developing", "refining", "mature"]);
+const parentStatusSchema = statusSchema.exclude(["placeholder", "exploratory"]);
 
 /** Contains fields common between guidelines and requirements */
 const commonChildSchema = z.object({
   howto: howtoSchema.optional(),
-  status: statusSchema.optional(),
   title: z.string().optional(),
 });
 
@@ -43,7 +43,7 @@ export const collections = {
     loader: glob({ pattern: "*.json", base: "./guidelines/groups", ignore: "index.json" }),
     schema: z.object({
       children: childrenSchema,
-      status: statusSchema.optional(),
+      status: parentStatusSchema.optional(),
       title: z.string().optional(),
     }),
   }),
@@ -55,12 +55,14 @@ export const collections = {
       // Moreover, we can't override generateId for requirements to only use slug,
       // due to duplicates across separate guidelines, e.g. "style-guide"
       children: childrenSchema,
+      status: parentStatusSchema.optional(),
     }),
   }),
   requirements: defineCollection({
     loader: glob({ pattern: "*/*/*.md", base: "./guidelines/groups" }),
     schema: commonChildSchema.extend({
       needsAdditionalResearch: z.boolean().optional(),
+      status: statusSchema.default("exploratory"),
       type: z
         .enum([
           "foundational",

src/lib/guidelines.ts

@@ -1,6 +1,33 @@
 import { getCollection, getEntry, type CollectionEntry, type CollectionKey } from "astro:content";
 import capitalize from "lodash-es/capitalize";
 
+/**
+ * Returns a filtered list of requirement/assertion slugs under the given group and guideline,
+ * excluding any marked as needing additional research if WCAG_SKIP_WIP is set.
+ */
+async function getFilteredRequirements(groupId: string, guidelineSlug: string) {
+  const guideline = await getEntry("guidelines", `${groupId}/${guidelineSlug}`);
+  if (!guideline) throw new Error(`Unresolvable guideline ID: ${guidelineSlug}`);
+
+  const filteredRequirements: string[] = [];
+  for (const requirementSlug of guideline.data.children) {
+    const requirement = await getEntry(
+      "requirements",
+      `${groupId}/${guidelineSlug}/${requirementSlug}`
+    );
+    if (!requirement) throw new Error(`Unresolvable requirement ID: ${requirementSlug}`);
+    if (
+      import.meta.env.WCAG_SKIP_WIP &&
+      (requirement.data.needsAdditionalResearch ||
+        requirement.data.status === "placeholder" ||
+        requirement.data.status === "exploratory")
+    )
+      continue;
+    filteredRequirements.push(requirementSlug);
+  }
+  return filteredRequirements;
+}
+
 let groupIds = (await getCollection("groupOrder")).map(({ id }) => id);
 let groups: Record<string, CollectionEntry<"groups">> = {};
 let guidelines: Record<string, CollectionEntry<"guidelines">> = {};
@@ -17,6 +44,7 @@ export async function buildGuidelinesHierarchy() {
       for (const guidelineSlug of group.data.children) {
         const guideline = await getEntry("guidelines", `${groupId}/${guidelineSlug}`);
         if (!guideline) throw new Error(`Unresolvable guideline ID: ${guidelineSlug}`);
+        guideline.data.children = await getFilteredRequirements(groupId, guidelineSlug);
         guidelines[guideline.id] = guideline;
 
         for (const requirementSlug of guideline.data.children) {