Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (93 loc) · 4.12 KB

CONTRIBUTING.md

File metadata and controls

129 lines (93 loc) · 4.12 KB

Contributing to AppSecOne

Thank you for your interest in contributing to AppSecOne! This guide covers everything you need to get started.

Development Setup

Prerequisites

  • Python 3.12 or higher
  • Git

Installation

git clone https://github.com/polprog-tech/AppSecOne.git
cd AppSecOne
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Verify the installation:

appsecone version

Pre-commit hook

cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

The hook runs ruff lint (with auto-fix), a ruff format check, and the full test suite before each commit.

Running the development server

appsecone serve --config appsecone.json --port 8080 --verbose

Running Tests

pytest                                     # all tests
pytest -v                                  # verbose
pytest tests/unit/policy                   # specific directory
pytest tests/unit/policy/test_policy_engine.py::TestPolicyEngine  # specific class

Tests follow the GIVEN/WHEN/THEN docstring pattern (see existing tests for examples).

Code Quality

ruff check src/ tests/
ruff format src/ tests/

Project Structure

src/appsecone/
├── domain/          # Pure domain models and enums (zero I/O)
├── config/          # Configuration loading and validation
├── fortify/         # Fortify SSC integration client
│   ├── client/      # HTTP client, auth, endpoints
│   └── mappers/     # DTO -> domain model mapping
├── persistence/     # Database layer (SQLite)
├── application/     # Sync and query services (async)
├── analysis/        # Trend analytics & historical snapshots
├── presentation/    # Jinja2 renderer, view models, templates
│   └── templates/   # HTML templates with design system
├── web/             # FastAPI server, middleware, routes
├── cli/             # Typer CLI commands
├── i18n/            # Internationalization catalogs (EN, PL)
│   └── locales/     # JSON translation files
└── shared/          # Logging, networking, type aliases

Code Style

  • Python 3.12+ features encouraged (StrEnum, type unions, f-strings)
  • Ruff for linting and formatting (config in pyproject.toml)
  • Frozen dataclasses for domain models - immutability by default
  • Type hints everywhere - no untyped public APIs
  • Async for all I/O operations (database, network, file system)
  • CSS custom properties for all design tokens - no hardcoded colors or spacing in templates
  • No inline styles - all visual styling via CSS classes
  • CSP-safe JavaScript - all scripts use nonce attributes, no inline event handlers

Architecture Principles

  • Domain layer has zero I/O - pure functions and frozen dataclasses only
  • Application layer is async - all database and network calls are awaited
  • Presentation layer builds view models - no business logic in templates
  • Web layer is thin - routes delegate to services, never contain business logic
  • Config-driven policy - release readiness rules live in JSON, not code
  • Security by default - CSP headers, CSRF protection, rate limiting, API key auth

Internationalization

AppSecOne supports multiple languages. Translation catalogs live in src/appsecone/i18n/locales/.

  • Use t('key.name') in Jinja2 templates
  • Use t('key', count=N) for pluralization (keys: .one, .other, .few for Polish)
  • Always add keys to both en.json and pl.json

How to Contribute

Reporting Bugs

Include: expected vs actual behavior, appsecone.json (redacted), Python/OS version, steps to reproduce. For UI issues, include the browser, theme, and language used.

Pull Requests

  1. Branch from main
  2. Make changes + add tests
  3. Run pytest and ruff check src/ tests/
  4. Verify no UI regressions: pytest tests/unit/presentation/ -q
  5. Open PR with a clear description

Commit Convention

Conventional Commits: feat:, fix:, docs:, test:, refactor:, chore:

License

See LICENSE.