chore: add documentation linting step to presubmit workflow

Included a new step to run a smoke check on documentation as part of the presubmit workflow. Updated the documentation generation command in the error message for clarity. Added a new script command for linting documentation in package.json.

Author: omalleyandy

.github/workflows/presubmit.yml

@@ -54,12 +54,15 @@ jobs:
       - name: Generate documents
         run: npm run docs
 
+      - name: Run docs smoke check
+        run: npm run docs:lint
+
       - name: Check if autogenerated docs differ
         run: |
           diff_file=$(mktemp doc_diff_XXXXXX)
           git diff --color > $diff_file
           if [[ -s $diff_file ]]; then
-            echo "Please update the documentation by running 'npm run generate-docs'. The following was the diff"
+            echo "Please update the documentation by running 'npm run docs'. The following was the diff"
             cat $diff_file
             rm $diff_file
             exit 1

package.json

@@ -14,6 +14,7 @@
     "check-format": "eslint --cache . && prettier --check --cache .;",
     "docs": "npm run build && npm run docs:generate && npm run format",
     "docs:generate": "node --experimental-strip-types scripts/generate-docs.ts",
+    "docs:lint": "node --experimental-strip-types scripts/check-docs.ts",
     "start": "npm run build && node build/src/index.js",
     "start-debug": "DEBUG=mcp:* DEBUG_COLORS=false npm run build && node build/src/index.js",
     "test": "npm run build && node scripts/test.mjs",

scripts/check-docs.ts

@@ -0,0 +1,94 @@
+/**
+ * Minimal markdown smoke check for docs.
+ *
+ * Goals:
+ * - Ensure all markdown files under docs/ are readable.
+ * - Fail fast on obvious bad states (e.g. unresolved merge markers).
+ *
+ * This is intentionally lightweight and dependency-free so it can run quickly in CI.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DOCS_ROOT = path.join(process.cwd(), 'docs');
+
+function isMarkdownFile(filePath: string): boolean {
+  return filePath.toLowerCase().endsWith('.md');
+}
+
+function findMarkdownFiles(root: string): string[] {
+  const results: string[] = [];
+
+  function walk(current: string) {
+    const entries = fs.readdirSync(current, {withFileTypes: true});
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile() && isMarkdownFile(entry.name)) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  walk(root);
+  return results;
+}
+
+function checkFile(filePath: string): string[] {
+  const errors: string[] = [];
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  if (!content.trim()) {
+    errors.push('file is empty');
+  }
+
+  const lines = content.split(/\r?\n/);
+  lines.forEach((line, index) => {
+    const lineNumber = index + 1;
+    if (line.includes('<<<<<<<') || line.includes('=======') || line.includes('>>>>>>>')) {
+      errors.push(`unresolved merge marker on line ${lineNumber}`);
+    }
+  });
+
+  return errors;
+}
+
+function main() {
+  if (!fs.existsSync(DOCS_ROOT)) {
+    console.error(`Docs directory not found at ${DOCS_ROOT}`);
+    process.exit(1);
+  }
+
+  const markdownFiles = findMarkdownFiles(DOCS_ROOT);
+  const allErrors: string[] = [];
+
+  for (const file of markdownFiles) {
+    try {
+      const errors = checkFile(file);
+      for (const err of errors) {
+        allErrors.push(`${path.relative(process.cwd(), file)}: ${err}`);
+      }
+    } catch (error) {
+      allErrors.push(
+        `${path.relative(process.cwd(), file)}: failed to read or parse file: ${
+          (error as Error).message
+        }`,
+      );
+    }
+  }
+
+  if (allErrors.length > 0) {
+    console.error('Docs smoke check failed with the following issues:\n');
+    for (const msg of allErrors) {
+      console.error(`- ${msg}`);
+    }
+    process.exit(1);
+  }
+
+  console.log(`Docs smoke check passed for ${markdownFiles.length} markdown file(s).`);
+}
+
+main();
+