hawkeyexl · hawkeyexl · Dec 4, 2024 · Dec 3, 2024 · Dec 3, 2024 · Dec 3, 2024
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@ Doc Structure Linter is a tool designed to validate the structure of documents (
 ## Features
 
 - Validate Markdown and AsciiDoc files against custom templates
-- Automatically detect file type based on extension or content
+- Validate ordered sequences of content elements within sections
 - Check for required sections, paragraph counts, and code block requirements
 - Flexible template definitions using YAML
 - Output results in both human-readable text and structured JSON formats
@@ -90,6 +90,7 @@ markdown-structure-linter/
 
 Templates are defined in the `templates.yaml` file. Each template specifies the expected structure of a document, including:
 
+- Sequencing of content within sections
 - Required sections
 - Paragraph count limits
 - Code block requirements

diff --git a/src/markdownParser.js b/src/markdownParser.js
@@ -34,10 +34,38 @@ export function parseMarkdown(content) {
     }
   };
 
+  /**
+   * Adds a node to a section's content sequence based on the specified type.
+   * If the last element in the section's content is not of the specified type,
+   * a new sequence node is created and added to the content. Otherwise, the node
+   * is appended to the existing sequence of the same type.
+   *
+   * @param {Object} section - The section object containing the content array.
+   * @param {string} type - The type of the node to be added.
+   * @param {Object} node - The node to be added to the section's content.
+   */
+  const addToSequence = (section, type, node) => {
+    if (
+      section.content.length > 0 &&
+      Object.hasOwn(section.content[section.content.length - 1], type)
+    ) {
+      section.content[section.content.length - 1][type].push(node);
+      section.content[section.content.length - 1].position.end = node.position.end;
+    } else {
+      const sequenceNode = {
+        heading: section.heading,
+        position: node.position,
+      };
+      sequenceNode[type] = [node];
+      section.content.push(sequenceNode);
+    }
+  };
+
   const processSection = (node) => {
     const newSection = {
       id: uuid(),
       position: node.position,
+      content: [],
       heading: {
         level: node.depth,
         position: node.position,
@@ -53,23 +81,22 @@ export function parseMarkdown(content) {
 
   const processParagraph = (node) => {
     const result = {
-      position: node.position,
       content: node.children.map((child) => child.value).join(""),
+      position: node.position,
     };
     return result;
   };
 
   const processCodeBlock = (node) => {
     const result = {
-      position: node.position,
       content: `\`\`\`${node.lang}\n${node.value}\`\`\``,
+      position: node.position,
     };
     return result;
   };
 
   const processList = (node) => {
     const result = {
-      position: node.position,
       ordered: node.ordered,
       items: node.children.map((item) => {
         if (item.type === "listItem") {
@@ -88,11 +115,12 @@ export function parseMarkdown(content) {
                     position: child.position,
                     content: child.value || "",
                   };
-                }
+              }
             }),
           };
         }
       }),
+      position: node.position,
     };
     return result;
   };
@@ -137,14 +165,17 @@ export function parseMarkdown(content) {
     } else if (node.type === "paragraph") {
       const paragraph = processParagraph(node);
       updateParentPositions(parentSection, node.position.end);
+      addToSequence(currentSection, "paragraphs", paragraph);
       currentSection.paragraphs.push(paragraph);
     } else if (node.type === "code") {
       const codeBlock = processCodeBlock(node);
       updateParentPositions(parentSection, node.position.end);
+      addToSequence(currentSection, "code_blocks", codeBlock);
       currentSection.codeBlocks.push(codeBlock);
     } else if (node.type === "list") {
       const list = processList(node);
       updateParentPositions(parentSection, node.position.end);
+      addToSequence(currentSection, "lists", list);
       currentSection.lists.push(list);
     }
 

diff --git a/src/rules/sequenceValidator.js b/src/rules/sequenceValidator.js
@@ -0,0 +1,88 @@
+import { validateParagraphs } from "./paragraphsValidator.js";
+import { validateCodeBlocks } from "./codeBlocksValidator.js";
+import { validateLists } from "./listValidator.js";
+
+export function validateSequence(structure, template) {
+  const errors = [];
+  if (!template.sequence || !structure.content) return errors;
+
+  // Check sequence length
+  if (template.sequence.length !== structure.content.length) {
+    errors.push({
+      type: "sequence_length_error",
+      head: structure.heading.content,
+      message: `Expected ${template.sequence.length} content types in sequence, but found ${structure.content.length}`,
+      position: structure.position,
+    });
+    return errors;
+  }
+
+  // Check sequence order
+  const templateItemTypes = template.sequence.map(item => Object.keys(item)[0]);
+  const structureItemTypes = structure.content.map(item => {
+    if (Object.hasOwn(item, "paragraphs")) {
+      return "paragraphs";
+    } else if (Object.hasOwn(item, "code_blocks")) {
+      return "code_blocks";
+    } else if (Object.hasOwn(item, "lists")) {
+      return "lists";
+    } else {
+      return null;
+    }
+  });
+  // Check for unexpected content types
+  if (structureItemTypes.includes(null)) {
+    errors.push({
+      type: "sequence_order_error",
+      head: structure.heading.content,
+      message: `Unexpected content type (${type}) found in sequence`,
+      position: structure.position,
+    });
+    return errors;
+  }
+  // Check for sequence order mismatch
+  if (JSON.stringify(templateItemTypes) !== JSON.stringify(structureItemTypes)) {
+    errors.push({
+      type: "sequence_order_error",
+      head: structure.heading.content,
+      message: `Expected sequence ${JSON.stringify(templateItemTypes)}, but found sequence ${JSON.stringify(structureItemTypes)}`,
+      position: structure.position,
+    });
+    return errors;
+  }
+
+  // Validate each sequence item against rules
+  for (
+    let index = 0;
+    index < template.sequence.length;
+    index++
+  ) {
+    const templateItem = template.sequence[index];
+    const structureItem = structure.content[index];
+    const type = templateItemTypes[index];
+
+    switch (type) {
+      case "paragraphs":
+        errors.push(...validateParagraphs(structureItem, templateItem));
+        break;
+
+      case "code_blocks":
+        errors.push(...validateCodeBlocks(structureItem, templateItem));
+        break;
+
+      case "lists":
+        errors.push(...validateLists(structureItem, templateItem));
+        break;
+
+      default:
+        errors.push({
+          type: "sequence_order_error",
+          head: structure.heading.content,
+          message: `Unexpected content type (${type}) found in sequence`,
+          position: structure.position,
+        });
+    }
+  }
+
+  return errors;
+}
diff --git a/src/schema.js b/src/schema.js
@@ -90,27 +90,39 @@ export const schema = {
             },
             lists: {
               $ref: "#/definitions/lists",
-            }
+            },
           },
-        }
+        },
       },
     },
     sequence_item: {
       type: "object",
-      properties: {
-        type: {
-          type: "string",
-          enum: ["paragraph", "code_block", "list", "section"]
+      anyOf: [
+        {
+          additionalProperties: false,
+          properties: {
+            paragraphs: {
+              $ref: "#/definitions/paragraphs",
            },
+          },
         },
-        min: {
-          type: "integer",
-          minimum: 0
+        {
+          additionalProperties: false,
+          properties: {
+            code_blocks: {
+              $ref: "#/definitions/code_blocks",
+            },
+          },
         },
-        max: {
-          type: "integer"
-        }
-      },
-      required: ["type"]
+        {
+          additionalProperties: false,
+          properties: {
+            lists: {
+              $ref: "#/definitions/lists",
+            },
+          },
+        },
+      ],
     },
     section: {
       description: "A section of a document demarkated by a heading",
@@ -148,6 +160,14 @@ export const schema = {
           type: "boolean",
           default: true,
         },
+        sequence: {
+          description: "Ordered sequence of elements in the section",
+          type: "array",
+          minItems: 1,
+          items: {
+            $ref: "#/definitions/sequence_item",
+          },
+        },
         paragraphs: {
           $ref: "#/definitions/paragraphs",
         },
@@ -162,13 +182,6 @@ export const schema = {
           type: "boolean",
           default: false,
         },
-        sequence: {
-          description: "Ordered sequence of elements in the section",
-          type: "array",
-          items: {
-            $ref: "#/definitions/sequence_item"
-          }
-        },
         sections: {
           description: "Object of subsections",
           type: "object",

diff --git a/src/structureValidator.js b/src/structureValidator.js
@@ -2,6 +2,7 @@ import { validateHeading } from "./rules/headingValidator.js";
 import { validateParagraphs } from "./rules/paragraphsValidator.js";
 import { validateCodeBlocks } from "./rules/codeBlocksValidator.js";
 import { validateLists } from "./rules/listValidator.js";
+import { validateSequence } from "./rules/sequenceValidator.js";
 
 export { validateStructure, validateSection };
 
@@ -30,6 +31,11 @@ function validateStructure(structure, template) {
 function validateSection(structureSection, templateSection) {
   let errors = [];
 
+  // Check sequence if defined
+  if (templateSection.sequence) {
+    errors = errors.concat(validateSequence(structureSection, templateSection));
+  }
+
   // Check heading
   if (templateSection.heading && structureSection.heading) {
     errors = errors.concat(validateHeading(structureSection, templateSection));

diff --git a/templates.yaml b/templates.yaml
@@ -3,7 +3,7 @@ info:
   title: Sample Templates
   version: 1.0.0
 
-templates:                            # Array of templates, each with a unique key
+templates: # Array of templates, each with a unique key
   How-to:
     sections:
       Title:
@@ -33,19 +33,22 @@ templates:                            # Array of templates, each with a unique k
               const: See also
             paragraphs:
               min: 1
-  Sample:                             # Template definition correspondings to the H1 level of the document
-    sections:                         # Array of sections, each with a unique key
-      Introduction:                   # Each sections corresponds to a heading level one below the parent, starting with an H1 at the first level
+  Sample: # Template definition correspondings to the H1 level of the document
+    sections: # Array of sections, each with a unique key
+      Introduction: # Each sections corresponds to a heading level one below the parent, starting with an H1 at the first level
         description: A template for how-to guides that include prerequisites, setup, usage, troubleshooting, and next steps sections.
+        sequence:
+          - paragraphs:
+              min: 2
         paragraphs:
           min: 2
           max: 5
         code_blocks:
-          max: 1                          # Allow a maximum of 1 code block
-        sections:                         # Array of sections, each with a unique key
-          Prerequisites:                  # Each section corresponds to a heading level one below the parent, in this case Prerequisites is an H2
-            heading: 
-              const: Prerequisites          # Require the section to be titled "Prerequisites"
+          max: 1 # Allow a maximum of 1 code block
+        sections: # Array of sections, each with a unique key
+          Prerequisites: # Each section corresponds to a heading level one below the parent, in this case Prerequisites is an H2
+            heading:
+              const: Prerequisites # Require the section to be titled "Prerequisites"
             paragraphs:
               max: 3
             lists:
@@ -55,28 +58,28 @@ templates:                            # Array of templates, each with a unique k
                 max: 7
           Setup:
             paragraphs:
-              max: 5                      # Allow a maximum of 5 paragraphs
+              max: 5 # Allow a maximum of 5 paragraphs
           Usage:
             paragraphs:
               max: 4
             code_blocks:
-              min: 1                      # Require at least one code block
-            additionalSections: true     # Allow additional use case sections
+              min: 1 # Require at least one code block
+            additionalSections: true # Allow additional use case sections
             sections:
               Troubleshooting:
-                heading: 
-                  const: Troubleshooting    # Require the section to be titled "Troubleshooting"
+                heading:
+                  const: Troubleshooting # Require the section to be titled "Troubleshooting"
                 paragraphs:
                   max: 5
           Next steps:
-            $ref: '#/components/sections/Next steps'   # Reference the 'Next steps' section component
+            $ref: "#/components/sections/Next steps" # Reference the 'Next steps' section component
 
 components:
   sections:
     Next steps:
-      heading: 
-        const: Next steps             # Back to an H2 level section
-      required: false               # Allow the section to be omitted
+      heading:
+        const: Next steps # Back to an H2 level section
+      required: false # Allow the section to be omitted
       paragraphs:
         min: 1
       lists: