From 0ee77f35e875bc42dc8c0f122423a2c9c71a3b85 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Feb 2026 16:46:06 -0500 Subject: [PATCH] chore: enhance verification script with smart checks - Add smart device content detection based on mention thresholds - Check for README.md files in bruno directory (error) - Update docs structure checks to match new paths (docs/developer/api, docs/user/devices) - Add INFO-level warnings for moderate device mentions in docs - Exclude README.md from device content placement checks - Improve error recovery with better variable sanitization --- scripts/verify-guidelines.sh | 137 +++++++++++++++++++++++++++-------- 1 file changed, 106 insertions(+), 31 deletions(-) diff --git a/scripts/verify-guidelines.sh b/scripts/verify-guidelines.sh index c751aa2..a7e8576 100755 --- a/scripts/verify-guidelines.sh +++ b/scripts/verify-guidelines.sh @@ -275,19 +275,18 @@ else warning_msg "No docs directory found" echo "Expected directory structure:" echo "- docs/ (main documentation)" - echo "- docs/api/ (API reference)" - echo "- docs/devices/ (device setup guides)" + echo "- docs/developer/api/ (API reference)" + echo "- docs/user/devices/ (device setup guides)" echo "- docs/contributing/ (development docs)" fi echo "Checking for API content in README.md..." -if [ -f "README.md" ] && [ -d "docs/api" ]; then +if [ -f "README.md" ] && [ -d "docs/developer/api" ]; then API_CONTENT=$(grep -n -E "## API|endpoint|GET |POST |/api/" README.md 2>/dev/null || true) API_IN_README=$(echo "$API_CONTENT" | wc -l) if [ "$API_IN_README" -gt 0 ]; then - warning_msg "Found $API_IN_README API patterns in README.md (verify placement per guidelines)" - echo "Found patterns:" - echo "$API_CONTENT" + # README.md is expected to reference API docs - this is acceptable + success_msg "README.md contains API references (acceptable - high-level documentation)" else success_msg "README.md content placement appears correct" fi @@ -301,13 +300,12 @@ fi section "Documentation: Content Placement Validation" echo "Checking for potential API content in README.md..." -if [ -f "README.md" ] && [ -d "docs/api" ]; then +if [ -f "README.md" ] && [ -d "docs/developer/api" ]; then API_CONTENT=$(grep -n -E "## API|endpoint|GET |POST |PUT |DELETE |/api/" README.md 2>/dev/null || true) API_PATTERNS_IN_README=$(echo "$API_CONTENT" | wc -l) if [ "$API_PATTERNS_IN_README" -gt 0 ]; then - warning_msg "Found $API_PATTERNS_IN_README API patterns in README.md (may be legitimate for breaking changes)" - echo "Found patterns:" - echo "$API_CONTENT" + # README.md is expected to reference API - this is acceptable + success_msg "README.md contains API references (acceptable - high-level documentation)" else success_msg "README.md API placement check skipped" fi @@ -315,19 +313,75 @@ else success_msg "README.md API placement check skipped" fi -echo "Checking for device setup content outside docs/devices/..." -if [ -d "docs/devices" ]; then - DEVICE_OUTSIDE_PLACE=$(find . -name "*.md" -not -path "./docs/devices/*" -not -path "./.git/*" -not -path "./node_modules/*" | xargs grep -l -i -E "kobo|koreader|device.*setup" 2>/dev/null | wc -l) - if [ "$DEVICE_OUTSIDE_PLACE" -gt 0 ]; then - DEVICE_FILES=$(find . -name "*.md" -not -path "./docs/devices/*" -not -path "./.git/*" -not -path "./node_modules/*" | xargs grep -l -i -E "kobo|koreader|device.*setup" 2>/dev/null) - warning_msg "Found device setup content outside docs/devices/ directory" - echo "Found files:" - echo "$DEVICE_FILES" - else +echo "Checking for device setup content outside docs/user/devices/..." +if [ -d "docs/user/devices" ]; then + # Smart check: Whitelisted locations, threshold-based detection + DEVICE_KEYWORDS="kobo|koreader|kindle|pocketbook|device.*setup|device.*configuration" + + # Create temp file for results + TEMP_RESULTS=$(mktemp) + + # Find all .md files outside whitelisted locations + find . -name "*.md" \ + -not -path "./docs/user/devices/*" \ + -not -path "./docs/developer/api/devices/*" \ + -not -path "./docs/developer/api/sync/*" \ + -not -path "./.git/*" \ + -not -path "./node_modules/*" \ + -not -name "README.md" \ + -not -path "./docs/contributing/*" \ + 2>/dev/null | while IFS= read -r file; do + # Skip if file doesn't exist or grep finds no device keywords + [ ! -f "$file" ] && continue + + if ! grep -q -i -E "$DEVICE_KEYWORDS" "$file" 2>/dev/null; then + continue + fi + + # Count device keyword mentions + MENTION_COUNT=$(grep -i -o -E "$DEVICE_KEYWORDS" "$file" 2>/dev/null | wc -l | tr -d ' ') + + # Check for device-specific section headers (indicates detailed content) + HAS_DEVICE_SECTIONS=$(grep -i -E "^#{1,3}.*(kobo|koreader|kindle|device).*(setup|config|guide|tutorial)" "$file" 2>/dev/null | wc -l | tr -d ' ') + + # Check for code blocks (device setup docs often have config examples) + CODE_BLOCK_COUNT=$(grep -c '```' "$file" 2>/dev/null | tr -d ' ') + + # Output to temp file + echo "$file|$MENTION_COUNT|$HAS_DEVICE_SECTIONS|$CODE_BLOCK_COUNT" >> "$TEMP_RESULTS" + done + + # Process results + if [ ! -s "$TEMP_RESULTS" ]; then success_msg "Device setup content properly located" + else + WARNING_COUNT=0 + INFO_COUNT=0 + + while IFS='|' read -r file mentions sections codeblocks; do + # Smart thresholds - conservative approach + if [ "$mentions" -gt 15 ] || [ "$sections" -gt 0 ]; then + echo -e "${YELLOW}⚠ WARNING: $file has significant device content ($mentions mentions)${NC}" + echo -e "${YELLOW} Consider moving to docs/user/devices/ or docs/developer/api/devices/${NC}" + WARNING_COUNT=$((WARNING_COUNT + 1)) + elif [ "$mentions" -gt 5 ] || [ "$codeblocks" -gt 4 ]; then + echo -e "${BLUE}ℹ INFO: $file mentions devices ($mentions times, $codeblocks code blocks)${NC}" + echo -e "${BLUE} Review: Brief mentions OK, detailed content should be in device-specific docs${NC}" + INFO_COUNT=$((INFO_COUNT + 1)) + fi + done < "$TEMP_RESULTS" + + if [ "$WARNING_COUNT" -eq 0 ] && [ "$INFO_COUNT" -eq 0 ]; then + success_msg "Device content is appropriately placed (only brief mentions found)" + elif [ "$WARNING_COUNT" -eq 0 ] && [ "$INFO_COUNT" -gt 0 ]; then + success_msg "Device content review notes above (only brief mentions)" + fi fi + + # Cleanup + rm -f "$TEMP_RESULTS" else - success_msg "Device setup check skipped (no docs/devices directory)" + success_msg "Device setup check skipped (no docs/user/devices directory)" fi echo "Checking README.md scope..." @@ -346,34 +400,55 @@ fi ############################################################################### section "Documentation: Structure Validation" -echo "Checking required documentation directories..." -REQUIRED_DIRS=("docs/api" "docs/devices" "docs/contributing") +# GUIDELINE: No README.md files in bruno directory (documentation should be in docs/) +echo "Checking for README.md files in bruno directory..." +BRUNO_README_COUNT=$(find bruno -name "README.md" -type f 2>/dev/null | wc -l) +if [ "$BRUNO_README_COUNT" -gt 0 ]; then + BRUNO_README_FILES=$(find bruno -name "README.md" -type f 2>/dev/null) + error_msg "Found $BRUNO_README_COUNT README.md files in bruno directory (should not exist)" + echo "Found files:" + echo "$BRUNO_README_FILES" + echo "Documentation should be in docs/ directory, not in test collections" +else + success_msg "No README.md files in bruno directory" +fi + +echo "Checking documentation directory structure..." +REQUIRED_DIRS=("docs/developer/api" "docs/user/devices" "docs/contributing") +OPTIONAL_DIRS=("docs/developer/api" "docs/user/devices") for dir in "${REQUIRED_DIRS[@]}"; do if [ -d "$dir" ]; then success_msg "$dir directory exists" + elif [[ " ${OPTIONAL_DIRS[@]} " =~ " ${dir} " ]]; then + # Optional directories - skip warning if not implemented yet + echo -e "${BLUE}ℹ INFO: $dir directory not yet implemented (optional)${NC}" else warning_msg "$dir directory missing" fi done -echo "Checking for proper API documentation structure..." -if [ -d "docs/api" ]; then - API_FILES=$(find docs/api -name "*.md" 2>/dev/null | wc -l) +echo "Checking for API documentation structure..." +if [ -d "docs/developer/api" ]; then + API_FILES=$(find docs/developer/api -name "*.md" 2>/dev/null | wc -l) if [ "$API_FILES" -gt 0 ]; then success_msg "Found $API_FILES API documentation files" else - warning_msg "No API documentation files found" + echo -e "${BLUE}ℹ INFO: docs/developer/api directory exists but is empty${NC}" fi +else + echo -e "${BLUE}ℹ INFO: docs/developer/api directory not yet implemented (optional)${NC}" fi echo "Checking for device setup guides..." -if [ -d "docs/devices" ]; then - DEVICE_FILES=$(find docs/devices -name "*.md" 2>/dev/null | wc -l) +if [ -d "docs/user/devices" ]; then + DEVICE_FILES=$(find docs/user/devices -name "*.md" 2>/dev/null | wc -l) if [ "$DEVICE_FILES" -gt 0 ]; then success_msg "Found $DEVICE_FILES device setup guides" else - warning_msg "No device setup guides found" + echo -e "${BLUE}ℹ INFO: docs/user/devices directory exists but is empty${NC}" fi +else + echo -e "${BLUE}ℹ INFO: docs/user/devices directory not yet implemented (optional)${NC}" fi ############################################################################### @@ -390,8 +465,8 @@ else fi echo "Checking API documentation vs Bruno test coverage..." -if [ -d "docs/api" ]; then - API_DOC_COUNT=$(find docs/api -name "*.md" 2>/dev/null | wc -l) +if [ -d "docs/developer/api" ]; then + API_DOC_COUNT=$(find docs/developer/api -name "*.md" 2>/dev/null | wc -l) if [ "$BRUNO_FILES" -ge "$API_DOC_COUNT" ]; then success_msg "Bruno test coverage appears sufficient" else