feat(mdlint): add rule TOP009 to ensure lesson overview items start with a capital letter and end with a period

.markdownlint-cli2.jsonc

@@ -1,5 +1,4 @@
 // https://github.com/DavidAnson/markdownlint
-
 {
   "config": {
     "default": true,
@@ -87,6 +86,7 @@
     "./markdownlint/TOP006_fullFencedCodeLanguage/TOP006_fullFencedCodeLanguage.js",
     "./markdownlint/TOP007_useMarkdownLinks/TOP007_useMarkdownLinks.js",
     "./markdownlint/TOP008_useBackticksForFencedCodeBlocks/TOP008_useBackticksForFencedCodeBlocks.js",
+    "./markdownlint/TOP009_lessonOverviewItemsSentenceStructure/TOP009_lessonOverviewItemsSentenceStructure.js",
     "./markdownlint/TOP010_useLazyNumbering/TOP010_useLazyNumbering.js"
   ]
 }

markdownlint/TOP009_lessonOverviewItemsSentenceStructure/TOP009_lessonOverviewItemsSentenceStructure.js

@@ -0,0 +1,66 @@
+function isolateBulletList(tokens) {
+  const bulletList = [];
+  let inBulletList = false;
+  let inLessonOverview = false;
+  tokens.forEach((token, index, tokensArr) => {
+    if (
+      tokensArr[index - 1]?.type === "heading_open" &&
+      /lesson overview/i.test(token.content)
+    ) {
+      inLessonOverview = true;
+    } else if (token.type === "bullet_list_open") {
+      inBulletList = true;
+    } else if (tokensArr[index - 1]?.type === "bullet_list_close") {
+      inLessonOverview = false;
+      inBulletList = false;
+    }
+
+    if (inBulletList && inLessonOverview) {
+      bulletList.push(token);
+    }
+  });
+
+  // Only consider tokens that have text in them.
+  return bulletList.filter((token) => token.type === "inline");
+}
+
+function getListItemData(bulletPoint) {
+  const lineNumber = bulletPoint.lineNumber;
+  const context = bulletPoint.content.trim();
+  const firstCharacter = context.at(0);
+  const lastCharacter = context.at(-1);
+  return {
+    firstCharacter,
+    lastCharacter,
+    lineNumber,
+    context,
+  };
+}
+
+module.exports = {
+  names: ["TOP009", "lesson-overview-items-sentence-structure"],
+  description:
+    "Lesson overview items must be statements, not questions, and must begin with a capital letter and end with a period.",
+  tags: ["content"],
+  information: new URL(
+    "https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP009.md",
+  ),
+  function: function TOP009(params, onError) {
+    const bulletPoints = isolateBulletList(params.tokens);
+    bulletPoints.forEach((bulletPoint) => {
+      const { firstCharacter, lastCharacter, lineNumber, context } =
+        getListItemData(bulletPoint);
+      const firstCharacterIsValid =
+        firstCharacter === firstCharacter.toUpperCase();
+      const lastCharacterIsValid = lastCharacter === ".";
+      if (!firstCharacterIsValid || !lastCharacterIsValid) {
+        onError({
+          lineNumber,
+          detail:
+            "Lesson overview items must be statements, not questions, and must begin with a capital letter and end with a period.",
+          context,
+        });
+      }
+    });
+  },
+};

markdownlint/TOP009_lessonOverviewItemsSentenceStructure/tests/TOP009_capital_letter.md

@@ -0,0 +1,38 @@
+### Introduction
+
+This file should be marked with an error because one of the lesson overview items is not properly capitalized.
+
+### Lesson overview
+
+This section contains a general overview of topics that you will learn in this lesson.
+
+- Lesson overview item 1.
+- lesson overview item 2.
+- Lesson overview item 3.
+- Lesson overview item 4.
+
+### Custom section
+
+Text content
+
+### Assignment
+
+<div class="lesson-content__panel" markdown="1">
+
+Assignment content
+
+#### Extra credit
+
+</div>
+
+### Knowledge check
+
+The following questions are an opportunity to reflect on key topics in this lesson. If you can't answer a question, click on it to review the material, but keep in mind you are not expected to memorize or master this knowledge.
+
+- KC item
+
+### Additional resources
+
+This section contains helpful links to related content. It isn't required, so consider it supplemental.
+
+- AR item

markdownlint/TOP009_lessonOverviewItemsSentenceStructure/tests/TOP009_invalid_punctuation.md

@@ -0,0 +1,40 @@
+### Introduction
+
+This file should be marked with an error because one of the lesson overview items is a question.
+
+### Lesson overview
+
+This section contains a general overview of topics that you will learn in this lesson.
+
+- Lesson overview item 1.
+- Lesson overview item 2.
+- Lesson overview item 3?
+- Lesson overview item 5.
+- Lesson overview item 6
+- Lesson overview item 7.
+
+### Custom section
+
+Text content
+
+### Assignment
+
+<div class="lesson-content__panel" markdown="1">
+
+Assignment content
+
+#### Extra credit
+
+</div>
+
+### Knowledge check
+
+The following questions are an opportunity to reflect on key topics in this lesson. If you can't answer a question, click on it to review the material, but keep in mind you are not expected to memorize or master this knowledge.
+
+- KC item
+
+### Additional resources
+
+This section contains helpful links to related content. It isn't required, so consider it supplemental.
+
+- AR item

markdownlint/TOP009_lessonOverviewItemsSentenceStructure/tests/TOP009_test_valid.md

@@ -0,0 +1,38 @@
+### Introduction
+
+This file should not be flagged with any errors.
+
+### Lesson overview
+
+This section contains a general overview of topics that you will learn in this lesson.
+
+- Lesson overview item 1.
+- Lesson overview item 2.
+- Lesson overview item 3.
+- Lesson overview item 4.
+
+### Custom section
+
+Text content
+
+### Assignment
+
+<div class="lesson-content__panel" markdown="1">
+
+Assignment content
+
+#### Extra credit
+
+</div>
+
+### Knowledge check
+
+The following questions are an opportunity to reflect on key topics in this lesson. If you can't answer a question, click on it to review the material, but keep in mind you are not expected to memorize or master this knowledge.
+
+- KC item
+
+### Additional resources
+
+This section contains helpful links to related content. It isn't required, so consider it supplemental.
+
+- AR item

markdownlint/docs/TOP008.md

@@ -20,4 +20,4 @@ You should use backticks instead
 
 Consistent formatting makes it easier to understand a document.
 
-Markdown lint's [MD048 rule](https://github.com/DavidAnson/markdownlint/blob/main/doc/md048.md) already covers this check, but does not include fix information, therefore can only be used to raise errors for manual fixing. This custom rule enforces the same style but includes fix information that can be used alongside our fix scripts.
+Markdown lint's [MD048 rule](https://github.com/DavidAnson/markdownlint/blob/main/doc/md048.md) already covers this check, but does not include fix information, therefore can only be used to raise errors for manual fixing. This custom rule enforces the same style but includes fix information that can be used alongside our fix scripts.

markdownlint/docs/TOP009.md

@@ -0,0 +1,25 @@
+# `TOP009` - Lesson overview items sentence structure
+
+Tags: `content`
+
+Aliases: `lesson-overview-items-sentence-structure`
+
+This rule is triggered when a lesson overview item doesn't end with a period `.` or doesn't start with a capital letter. For example:
+
+```markdown
+- Lesson overview item 1
+- Lesson overview item 2?
+- lesson overview item 3.
+```
+
+To fix this issue, make sure that each bullet point ends with a period `.` and starts with a capital letter.
+
+```markdown
+- Lesson overview item 1.
+- Lesson overview item 2.
+- Lesson overview item 3.
+```
+
+## Rationale
+
+Lesson overview items should follow a consistent structure. They must tell the user what the lesson is about via brief overview statements, and must not be conveyed in the form of a question that the user is expected to be able to answer after completing the lesson.