Add block directives for applicability and exceptions (#411)

Co-authored-by: Kevin White <[email protected]>

Author: kfranqueiro

README.md

@@ -225,6 +225,33 @@ Your content here
 :::
 ```
 
+### Applicability
+
+The following block will be preceded by "Applies when:".
+This is _only_ valid within requirements.
+
+```
+:::applicability
+a condition is true.
+:::
+```
+
+If the block contains a single paragraph as above, "Applies when:" will appear inline before the content.
+Otherwise (e.g. if the block contains a list), it will appear in a separate paragraph before the content.
+
+### Exceptions
+
+The following block will be preceded by "Except when:".
+This is _only_ valid within requirements that also use `:::applicability`.
+
+```
+:::exceptions
+a condition is true.
+:::
+```
+
+This follows the same behavior as `:::applicability` regarding single paragraphs vs. other cases.
+
 #### Glossary Term References
 
 The text inside `:term[...]` will be transformed into a link referencing a term in the glossary,

src/lib/markdown/guidelines.ts

@@ -1,12 +1,14 @@
 import type { RemarkPlugin } from "@astrojs/markdown-remark";
-
+import type { ContainerDirective } from "mdast-util-directive";
 import { visit } from "unist-util-visit";
 import type { VFile } from "vfile";
 
 const groupsPath = `guidelines/groups`;
 const isGuidelineFile = (file: VFile) => file.dirname?.startsWith(`${file.cwd}/${groupsPath}`);
 
-function getGuidelineFileType(file: VFile) {
+type GuidelineFileType = "group" | "guideline" | "requirement";
+
+function getGuidelineFileType(file: VFile): GuidelineFileType | null {
   if (!isGuidelineFile(file)) return null;
   const remainingPath = file.dirname!.replace(`${file.cwd}/${groupsPath}/`, "");
   const segments = remainingPath?.split("/");
@@ -16,6 +18,17 @@ function getGuidelineFileType(file: VFile) {
   return null;
 }
 
+/** Fails validation if the file passed is not at the expected hierarchy level. */
+function expectGuidelineFileType(
+  file: VFile,
+  expectedType: GuidelineFileType,
+  directiveName: string
+) {
+  const type = getGuidelineFileType(file);
+  if (type !== expectedType)
+    file.fail(`:::${directiveName} expected at ${expectedType} level but found at ${type} level`);
+}
+
 const isTermFile = (file: VFile) => file.dirname?.startsWith(`${file.cwd}/guidelines/terms`);
 
 const getFrontmatter = (file: VFile) => file.data.astro!.frontmatter!;
@@ -36,12 +49,33 @@ const addEmptyTermNote: RemarkPlugin = () => (tree, file) => {
   }
 };
 
+/**
+ * Prepends a <b> element containing the given label.
+ * If the given node contains a single paragraph, it prepends inline;
+ * otherwise, it prepends a preceding paragraph before the node.
+ **/
+function prependBoldText(node: ContainerDirective, label: string) {
+  if (node.children.length === 1 && node.children[0].type === "paragraph") {
+    node.children[0].children.unshift({
+      type: "html",
+      value: `<b>${label}</b> `,
+    });
+  } else {
+    node.children.unshift({
+      type: "html",
+      value: `<p><b>${label}</b></p>`,
+    });
+  }
+}
+
 const customDirectives: RemarkPlugin = () => (tree, file) => {
   const isGuideline = isGuidelineFile(file);
   const isTerm = isTermFile(file);
   if (!isGuideline && !isTerm) return;
 
-  visit(tree, (node) => {
+  const parentsWithApplicability = new Set();
+
+  visit(tree, (node, index, parent) => {
     if (node.type === "containerDirective") {
       if (isGuideline && node.name === "decision-tree") {
         const data = node.data || (node.data = {});
@@ -53,9 +87,7 @@ const customDirectives: RemarkPlugin = () => (tree, file) => {
           value: "<summary>Which foundational requirements apply?</summary>",
         });
       } else if (isGuideline && node.name === "user-needs") {
-        const type = getGuidelineFileType(file);
-        if (type !== "guideline")
-          file.fail(`user-needs expected at guideline level but found at ${type} level`);
+        expectGuidelineFileType(file, "guideline", "user-needs");
 
         const data = node.data || (node.data = {});
         data.hName = "details";
@@ -65,9 +97,7 @@ const customDirectives: RemarkPlugin = () => (tree, file) => {
           value: "<summary>User Needs</summary><p><em>This section is non-normative.</em></p>",
         });
       } else if (isGuideline && node.name === "tests") {
-        const type = getGuidelineFileType(file);
-        if (type !== "requirement")
-          file.fail(`tests expected at requirement level but found at ${type} level`);
+        expectGuidelineFileType(file, "requirement", "tests");
 
         const data = node.data || (node.data = {});
         data.hName = "details";
@@ -76,6 +106,26 @@ const customDirectives: RemarkPlugin = () => (tree, file) => {
           type: "html",
           value: "<summary>Tests</summary><p><em>This section is non-normative.</em></p>",
         });
+      } else if (isGuideline && node.name === "applicability") {
+        expectGuidelineFileType(file, "requirement", "applicability");
+
+        prependBoldText(node, "Applies when:");
+        node.children.push({
+          type: "html",
+          value: "<p><b>Requirement:</b></p>",
+        });
+        if (parent && typeof index !== "undefined") {
+          parentsWithApplicability.add(parent);
+          parent.children.splice(index!, 1, ...node.children);
+        }
+      } else if (isGuideline && node.name === "exceptions") {
+        expectGuidelineFileType(file, "requirement", "exceptions");
+        if (!parent || !parentsWithApplicability.has(parent))
+          file.fail(":::exceptions cannot be used without :::applicability");
+
+        prependBoldText(node, "Except when:");
+        if (parent && typeof index !== "undefined")
+          parent.children.splice(index!, 1, ...node.children);
       } else if (node.name === "ednote") {
         const data = node.data || (node.data = {});
         data.hName = "div";