Ranuk Web Accessibility & AST Security Auditor

ADA-Audits

面向 Python 项目的自动化数据无障碍审计。

📌 功能

• 扫描 Python 文件和笔记本，查找数据无障碍问题
• 检测缺失的文档字符串、类型提示和无障碍标准
• 生成包含可执行建议的报告
• 与 CI/CD 流水线集成

🚀 快速开始

按照以下步骤开始使用 ADA-Audits：

步骤 1：安装

使用 pip：

# Clone the repository
git clone https://github.com/your-org/ada-audits.git
cd ada-audits

# Install in development mode
pip install -e .

使用 Poetry：

# Clone the repository
git clone https://github.com/your-org/ada-audits.git
cd ada-audits

# Install dependencies with Poetry
poetry install

# Activate the virtual environment
poetry shell

步骤 2：创建配置文件

在项目根目录中创建 .ada-audit.yml 文件：

# .ada-audit.yml - Minimal working configuration
targets:
  - src/
  - notebooks/

rules:
  - missing-docstring
  - missing-type-hint
  - accessibility-issue

output:
  format: markdown
  file: audit-report.md

步骤 3：运行首次审计

扫描单个文件：

ada-scan path/to/file.py

预期输出：

✓ Scanning: path/to/file.py
Found 3 issues:
  [WARNING] line 15: Missing docstring for function 'process_data'
  [WARNING] line 23: Missing type hint for parameter 'input_path'
  [ERROR]   line 45: Accessibility issue - missing alt text for image

扫描整个目录：

ada-scan src/

预期输出：

✓ Scanning directory: src/
Found 12 files to analyze
  src/__init__.py .............. OK
  src/main.py .................. 2 issues
  src/utils.py ................. 5 issues
  src/processors/base.py ....... 1 issue
  src/processors/transform.py .. 4 issues

Summary: 12 issues found across 4 files

生成完整报告：

ada-audit --output report.md

预期输出：

✓ ADA Audit Report Generated
  Output: report.md
  Total files scanned: 12
  Issues found: 15
  Compliance score: 78%

📖 用法

命令行界面

命令	描述
ada-scan <path>	扫描文件或目录，查找无障碍问题
ada-audit	根据配置生成完整审计报告
ada-audit --output <file>	使用自定义输出文件名生成报告
ada-audit --format <fmt>	输出格式：markdown、json 或 html

配置参考

.ada-audit.yml 的完整配置选项：

# Paths to scan
targets:
  - src/              # Python source files
  - notebooks/        # Jupyter notebooks
  - tests/            # Test files

# Rules to apply
rules:
  - missing-docstring      # Functions/classes without docstrings
  - missing-type-hint      # Parameters without type annotations
  - accessibility-issue    # Accessibility standard violations

# Output settings
output:
  format: markdown         # Options: markdown, json, html
  file: audit-report.md   # Output filename

# Optional: Exclude patterns
exclude:
  - "**/__pycache__/**"
  - "**/migrations/**"

🤝 参与贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/your-feature）
3. 提交更改（git commit -m 'feat: add new rule [ranukita:xxxxx]'）
4. 推送到该分支（git push origin feature/your-feature）
5. 创建 Pull Request

📄 许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。