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
This commit is contained in:
+106
-31
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user