moko-platform/docs/NEW_SCRIPTS.md

New Automation Scripts - v2.0.1

This document describes the new automation scripts added to MokoStandards.

Overview

The following scripts have been added to enhance automation capabilities across analysis, validation, maintenance, documentation, and utility categories.

Analysis Scripts

analyze_dependencies.py

Location: scripts/analysis/analyze_dependencies.py

Analyzes project dependencies across multiple package managers (Python, npm, composer).

Features:

• Scans for requirements.txt, package.json, composer.json
• Lists all dependencies by type (production, dev)
• Optional check for outdated packages
• JSON output support

Usage:

# Analyze current directory
python3 scripts/analysis/analyze_dependencies.py

# Analyze specific path
python3 scripts/analysis/analyze_dependencies.py /path/to/project

# JSON output
python3 scripts/analysis/analyze_dependencies.py --json

# Check for outdated packages
python3 scripts/analysis/analyze_dependencies.py --check-outdated

code_metrics.py

Location: scripts/analysis/code_metrics.py

Analyzes code metrics including lines of code, file counts, and language distribution.

Features:

• Counts total lines, code lines, and comment lines
• Breaks down by programming language
• Identifies largest files
• Comment ratio analysis
• JSON output support

Usage:

# Analyze current directory
python3 scripts/analysis/code_metrics.py

# Analyze specific path
python3 scripts/analysis/code_metrics.py /path/to/project

# JSON output
python3 scripts/analysis/code_metrics.py --json

Automation Scripts

setup_dev_environment.py

Location: scripts/automation/setup_dev_environment.py

Quick setup script for new contributors to configure their development environment.

Features:

• Checks for required tools (git, python3)
• Verifies Python version (3.8+)
• Sets up git commit message template
• Installs Python dependencies
• Configures pre-commit hooks
• Checks environment variables

Usage:

# Full setup
python3 scripts/automation/setup_dev_environment.py

# Skip dependency installation
python3 scripts/automation/setup_dev_environment.py --skip-install

check_outdated_actions.py

Location: scripts/automation/check_outdated_actions.py

Checks for outdated GitHub Actions in workflow files.

Features:

• Scans all workflow files (.yml, .yaml)
• Identifies actions with multiple versions
• Detects SHA-based versions
• Compares against known latest versions
• Provides actionable recommendations

Usage:

# Check default location (.github/workflows)
python3 scripts/automation/check_outdated_actions.py

# Check custom workflow directory
python3 scripts/automation/check_outdated_actions.py --workflow-dir path/to/workflows

Validation Scripts

check_markdown_links.py

Location: scripts/validate/check_markdown_links.py

Validates links in markdown files to ensure they are not broken.

Features:

• Extracts all links from markdown files
• Validates local file links
• Detects broken relative links
• Categorizes links (external, local, anchor)
• Reports broken links with file and line number

Usage:

# Check current directory
python3 scripts/validate/check_markdown_links.py

# Check specific path
python3 scripts/validate/check_markdown_links.py docs/

# Skip external link validation
python3 scripts/validate/check_markdown_links.py --skip-external

Exit Code: Returns 1 if broken links are found, 0 otherwise.

find_todos.py

Location: scripts/validate/find_todos.py

Finds and reports TODO, FIXME, and other code comments across the codebase.

Features:

• Searches for customizable markers (TODO, FIXME, HACK, XXX, BUG, NOTE)
• Supports multiple programming languages
• Groups results by marker type or file
• Excludes common directories (node_modules, vendor, etc.)

Usage:

# Find all markers
python3 scripts/validate/find_todos.py

# Find specific markers
python3 scripts/validate/find_todos.py --markers TODO FIXME

# Group by file instead of marker
python3 scripts/validate/find_todos.py --group-by file

# Search specific directory
python3 scripts/validate/find_todos.py src/

check_license_headers.py

Location: scripts/validate/check_license_headers.py

Checks and optionally fixes missing or incorrect license headers in source files.

Features:

• Validates GPL-3.0-or-later license headers
• Supports multiple file types (Python, JavaScript, PHP, Shell, etc.)
• Can automatically add missing headers
• Respects shebang lines in scripts
• Configurable copyright year

Usage:

# Check for missing headers
python3 scripts/validate/check_license_headers.py

# Add missing headers
python3 scripts/validate/check_license_headers.py --fix

# Use specific year
python3 scripts/validate/check_license_headers.py --fix --year 2026

Exit Code: Returns 1 if missing headers are found, 0 otherwise.

Maintenance Scripts

update_copyright_year.py

Location: scripts/maintenance/update_copyright_year.py

Updates copyright year in file headers across the codebase.

Features:

• Updates various copyright formats
• Processes multiple file types
• Dry-run mode by default
• Excludes common build/dependency directories
• Batch processing

Usage:

# Dry run (preview changes)
python3 scripts/maintenance/update_copyright_year.py

# Actually update files
python3 scripts/maintenance/update_copyright_year.py --apply

# Use specific year
python3 scripts/maintenance/update_copyright_year.py --year 2026 --apply

# Update specific directory
python3 scripts/maintenance/update_copyright_year.py src/ --apply

clean_old_branches.py

Location: scripts/maintenance/clean_old_branches.py

Identifies and optionally deletes old Git branches.

Features:

• Finds branches older than specified days
• Checks if branches are merged
• Protects main/master/develop branches
• Shows last commit date and days since last commit
• Optional forced deletion

Usage:

# Analyze branches older than 90 days
python3 scripts/maintenance/clean_old_branches.py

# Use custom threshold
python3 scripts/maintenance/clean_old_branches.py --days 60

# Delete merged old branches
python3 scripts/maintenance/clean_old_branches.py --delete-merged

# Delete all old branches (caution!)
python3 scripts/maintenance/clean_old_branches.py --delete-all --force

# Use different base branch
python3 scripts/maintenance/clean_old_branches.py --base-branch develop

Documentation Scripts

generate_script_catalog.py

Location: scripts/docs/generate_script_catalog.py

Generates a comprehensive catalog of all scripts in the repository.

Features:

• Scans all script directories
• Extracts metadata from file headers
• Organizes by category
• Generates markdown documentation
• Includes usage examples

Usage:

# Generate catalog to stdout
python3 scripts/docs/generate_script_catalog.py

# Save to file
python3 scripts/docs/generate_script_catalog.py --output SCRIPT_CATALOG.md

# Use custom scripts directory
python3 scripts/docs/generate_script_catalog.py --scripts-dir custom/scripts

check_doc_coverage.py

Location: scripts/docs/check_doc_coverage.py

Checks documentation coverage by identifying undocumented scripts and templates.

Features:

• Analyzes scripts and templates
• Calculates documentation coverage percentage
• Identifies missing README files
• Provides overall quality rating
• Lists undocumented items

Usage:

# Check current directory
python3 scripts/docs/check_doc_coverage.py

# Check specific path
python3 scripts/docs/check_doc_coverage.py /path/to/project

Utility Scripts

git_helper.sh

Location: scripts/run/git_helper.sh

Helper script for common git operations with enhanced output.

Features:

• Enhanced status with statistics
• Interactive cleanup of untracked files
• Branch listing with dates
• Stash management with descriptions
• Commit history visualization
• Search commit messages
• Undo last commit (safely)
• Merge conflict detection

Usage:

# Show enhanced status
bash scripts/run/git_helper.sh status

# Clean untracked files
bash scripts/run/git_helper.sh clean

# Sync with remote
bash scripts/run/git_helper.sh sync

# List branches with dates
bash scripts/run/git_helper.sh branch

# Stash with description
bash scripts/run/git_helper.sh stash "WIP: feature implementation"

# Apply stash
bash scripts/run/git_helper.sh unstash

# Show commit history
bash scripts/run/git_helper.sh history 20

# Search commits
bash scripts/run/git_helper.sh search "fix bug"

# Undo last commit (keeps changes)
bash scripts/run/git_helper.sh undo-commit

# Show diff statistics
bash scripts/run/git_helper.sh diff-stats

# Check for merge conflicts
bash scripts/run/git_helper.sh conflicts

Script Statistics

New Scripts Added: 11

• Analysis: 2
• Automation: 2
• Validation: 3
• Maintenance: 2
• Documentation: 2
• Utility: 1

Total Lines of Code: ~9,800 lines

Common Features

All new scripts include:

• Comprehensive docstrings and headers
• Command-line argument parsing
• Help messages (--help)
• Error handling and validation
• Progress indicators and colored output
• Exclusion of common directories (node_modules, vendor, etc.)
• Support for dry-run modes where applicable

Integration

These scripts integrate seamlessly with the existing MokoStandards automation framework:

• Follow the same file header conventions
• Use consistent coding standards
• Compatible with existing workflows
• Can be called from CI/CD pipelines
• Support batch operations

Future Enhancements

Potential future additions:

• Web-based dashboards for metrics
• GitHub Actions integration for automatic checks
• Email notifications for outdated dependencies
• Automated pull request creation for updates
• Integration with project management tools

Support

For issues or questions about these scripts:

1. Check the script's --help output
2. Review this documentation
3. Open an issue in the repository
4. Contact hello@mokoconsulting.tech