Run linting/fixing before compare

Author: kraftbj

.github/workflows/verify-docs.yml

@@ -22,20 +22,24 @@ jobs:
           coverage: none
 
       - name: Install dependencies
-        run: composer install --prefer-dist --no-progress
+        run: |
+          # Install PHP dependencies
+          composer install --prefer-dist --no-progress
+          # Install Node.js dependencies
+          npm ci
 
       - name: Generate fresh documentation
         run: |
           # Create temp directory for fresh docs
           mkdir -p temp/code-reference
-          # Generate fresh documentation
-          php docs/bin/generate-parsed-md.php --output=temp/code-reference
+          
+          # Run full docs workflow with new output directory
+          DOCS_OUTPUT_DIR=temp/code-reference composer run docs
 
       - name: Compare documentation
         run: |
-          # Compare generated docs with existing docs
-          if ! diff -r --ignore-all-space --ignore-blank-lines docs/code-reference temp/code-reference; then
+          if ! php docs/bin/verify-docs.php; then
             echo "::error::Documentation in docs/code-reference does not match what would be generated from source code."
-            echo "::error::Please update the source code documentation instead of modifying the generated files directly."
+            echo "::error::The markdown files are generated from PHP docblocks - please update the source code documentation instead."
             exit 1
           fi 

composer.json

@@ -23,7 +23,7 @@
     "scripts": {
         "docs:manifest": "php docs/bin/generate-manifest.php",
         "docs:links": "php docs/bin/update-markdown-links.php",
-        "docs:parse": "php docs/bin/generate-parsed-md.php",
+        "docs:parse": "php docs/bin/generate-parsed-md.php --output=${DOCS_OUTPUT_DIR:-docs/code-reference}",
         "docs:fix": "npm run fix:md",
         "docs:lint": "npm run lint:md",
         "docs": [

docs/bin/verify-docs.php

@@ -0,0 +1,62 @@
+<?php
+/**
+ * Compare generated markdown documentation with existing files.
+ *
+ * @package wordpress/secure-custom-fields
+ */
+
+namespace WordPress\SCF\Docs;
+
+// phpcs:disable WordPress.WP.AlternativeFunctions
+
+/**
+ * Normalize markdown content for comparison by removing formatting.
+ *
+ * @param string $content The markdown content to normalize.
+ * @return string Normalized content.
+ */
+function normalize_content( $content ) {
+	// Remove URL formatting
+	$content = preg_replace( '/<(https?:\/\/[^>]+)>/', '$1', $content );
+	// Normalize list markers
+	$content = preg_replace( '/^[*-]\s+/m', '- ', $content );
+	// Normalize whitespace
+	$content = preg_replace( '/\s+/', ' ', $content );
+	return trim( $content );
+}
+
+/**
+ * Compare two directories of markdown files.
+ *
+ * @param string $dir1 First directory path.
+ * @param string $dir2 Second directory path.
+ * @return bool True if content matches, false otherwise.
+ */
+function compare_dirs( $dir1, $dir2 ) {
+	$files1 = new \RecursiveIteratorIterator( new \RecursiveDirectoryIterator( $dir1 ) );
+	$files2 = new \RecursiveIteratorIterator( new \RecursiveDirectoryIterator( $dir2 ) );
+
+	foreach ( $files1 as $file1 ) {
+		if ( $file1->isFile() && 'md' === $file1->getExtension() ) {
+			$relative_path = str_replace( $dir1 . '/', '', $file1->getPathname() );
+			$file2         = $dir2 . '/' . $relative_path;
+
+			if ( ! file_exists( $file2 ) ) {
+				continue;
+			}
+
+			$content1 = normalize_content( file_get_contents( $file1 ) );
+			$content2 = normalize_content( file_get_contents( $file2 ) );
+
+			if ( $content1 !== $content2 ) {
+				// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
+				echo "Content mismatch in {$relative_path}\n";
+				return false;
+			}
+		}
+	}
+	return true;
+}
+
+$result = compare_dirs( 'docs/code-reference', 'temp/code-reference' );
+exit( $result ? 0 : 1 );