From ad55731dc2aba24719e475f2f1caf066a8c1bebd Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Thu, 28 May 2026 22:16:54 +0530 Subject: [PATCH 01/12] Create pr-size-warning.yml --- .github/workflows/pr-size-warning.yml | 66 +++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 .github/workflows/pr-size-warning.yml diff --git a/.github/workflows/pr-size-warning.yml b/.github/workflows/pr-size-warning.yml new file mode 100644 index 00000000..fa7f8267 --- /dev/null +++ b/.github/workflows/pr-size-warning.yml @@ -0,0 +1,66 @@ +name: PR Size and Artifact Check + +on: + pull_request: + types: [opened, synchronize, reopened] + +permissions: + pull-requests: read + +jobs: + check-pr-size: + runs-on: ubuntu-latest + env: + GH_TOKEN: ${{ github.token }} + # Define thresholds here so they are easily adjustable + MAX_FILES: 50 + MAX_LINES: 1000 + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Analyze PR Diffs and Artifacts + id: analyze + run: | + PR_NUMBER=${{ github.event.pull_request.number }} + + # Extract stats directly from GitHub event payload + ADDITIONS=${{ github.event.pull_request.additions }} + DELETIONS=${{ github.event.pull_request.deletions }} + CHANGED_FILES=${{ github.event.pull_request.changed_files }} + TOTAL_LINES=$((ADDITIONS + DELETIONS)) + + echo "PR Stats: $CHANGED_FILES files changed, $ADDITIONS additions, $DELETIONS deletions." + + # Fetch changed file paths via GitHub CLI + FILES=$(gh pr view $PR_NUMBER --json files --jq '.files[].path') + + WARNINGS="" + + # 1. Check for oversized diffs + if [ "$CHANGED_FILES" -gt "$MAX_FILES" ] || [ "$TOTAL_LINES" -gt "$MAX_LINES" ]; then + MSG="PR is unusually large ($CHANGED_FILES files, $TOTAL_LINES lines changed). The advisory threshold is $MAX_FILES files or $MAX_LINES lines." + echo "::warning title=Large PR Detected::$MSG Consider breaking this into smaller PRs to help reviewers." + WARNINGS="${WARNINGS}- ⚠️ **Large PR Detected:** $MSG\n" + fi + + # 2. Check for generated artifact directories + # The regex specifically looks for paths containing these directory names + if echo "$FILES" | grep -q -E "playwright-report/|test-results/"; then + MSG="PR contains generated testing artifacts (e.g., 'playwright-report/' or 'test-results/')." + echo "::warning title=Generated Artifacts Included::$MSG Please remove them from your commits." + WARNINGS="${WARNINGS}- 🚫 **Generated Artifacts Detected:** $MSG\n" + fi + + # 3. Output to GitHub Step Summary for easy visibility + if [ -n "$WARNINGS" ]; then + echo "### ⚠️ PR Review Advisory" >> $GITHUB_STEP_SUMMARY + echo -e "$WARNINGS" >> $GITHUB_STEP_SUMMARY + echo "> _This is an advisory warning to assist reviewers and will not fail your CI build._" >> $GITHUB_STEP_SUMMARY + else + echo "### ✅ PR Size and Content Check Passed" >> $GITHUB_STEP_SUMMARY + echo "No unusually large diffs or accidentally committed artifacts detected." >> $GITHUB_STEP_SUMMARY + fi + + # Force a successful exit (0) so the CI check always stays green (Advisory only) + exit 0 From 9e53884ee5504d8e577ae171d0af2272ec62f5b3 Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Thu, 28 May 2026 22:19:25 +0530 Subject: [PATCH 02/12] Update CONTRIBUTING.md --- CONTRIBUTING.md | 450 ++++++++++++++++++++++-------------------------- 1 file changed, 207 insertions(+), 243 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9bebba48..8d98928f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,15 +5,13 @@ Thank you for contributing to SecuScan. This project is open to first-time contr SecuScan is built for learning, defensive security workflows, and ethical testing. Please keep all contributions aligned with authorized, consent-based use. ## Before You Start - - Start with a small, reviewable task if this is your first contribution. -- Read [README.md](README.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md) before opening a pull request. -- Read the repository [LICENSE](LICENSE) so you understand how contributions are distributed. +- Read `README.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` before opening a pull request. +- Read the repository `LICENSE` so you understand how contributions are distributed. - If you want to work on a larger feature, open or comment on an issue first so effort does not overlap. - If you are contributing through GSSoC, mention that in the issue or pull request so maintainers can guide scope and review expectations. ## Good First Contribution Areas - - Documentation fixes, setup clarification, and onboarding polish - Frontend UX improvements in `frontend/src` - Backend validation, test coverage, and API consistency in `backend/secuscan` @@ -25,383 +23,349 @@ When issue labels are available, look for tags such as `good first issue`, `docu ## Local Setup ### Prerequisites - -- Python `3.11+` -- Node.js `20+` recommended -- `npm` +- Python 3.11+ +- Node.js 20+ recommended +- npm - Docker optional for plugins that depend on containerized tooling ### Recommended Setup - ```bash ./setup.sh ./start.sh -``` This starts: -- Backend: `http://127.0.0.1:8000` -- Frontend: `http://127.0.0.1:5173` -- API docs: `http://127.0.0.1:8000/docs` + - Backend: http://127.0.0.1:8000 + - Frontend: http://127.0.0.1:5173 + - API docs: http://127.0.0.1:8000/docs -### Manual Setup +Manual Setup -Backend: +Backend: Python version: python3 below must resolve to 3.11 or newer. Run +python3 --version to check. If your system default is older, substitute the full +path (e.g. python3.11) or use PYTHON=/path/to/python3.11 ./setup.sh instead of +the manual steps. -> **Python version:** `python3` below must resolve to 3.11 or newer. Run `python3 --version` to check. If your system default is older, substitute the full path (e.g. `python3.11`) or use `PYTHON=/path/to/python3.11 ./setup.sh` instead of the manual steps. - -```bash python3 -m venv venv source venv/bin/activate pip install -r backend/requirements.txt pip install -r backend/requirements-dev.txt python3 -m uvicorn backend.secuscan.main:app --reload --host 127.0.0.1 --port 8000 -``` Frontend: -```bash cd frontend npm install npm run dev -- --host 127.0.0.1 --port 5173 -``` -## Backend Testing Quickstart +Backend Testing Quickstart This section explains how to run the backend test suite from a fresh checkout without touching the main development environment. -### 1. Prerequisites +1. Prerequisites -Make sure your machine has Python 3.11 or newer before running any test commands. +Make sure your machine has Python 3.11 or newer before running any test +commands. -```bash python3 --version -``` -If the version shown is older than 3.11, substitute the full path to a compatible -interpreter (e.g. `python3.11`) wherever `python3` appears below. +If the version shown is older than 3.11, substitute the full path to a +compatible interpreter (e.g. python3.11) wherever python3 appears below. -### 2. Run the Full Backend Test Suite +2. Run the Full Backend Test Suite From the repo root, run: -```bash ./testing/test_python.sh -``` This script handles everything automatically: -- Creates an isolated virtual environment at `venv_tests/` (separate from your - dev environment) -- Installs all required dependencies from `backend/requirements.txt` and - `backend/requirements-dev.txt` -- Runs the full `testing/backend/` suite with pytest in quiet mode + - Creates an isolated virtual environment at venv_tests/ (separate from your + dev environment) + - Installs all required dependencies from backend/requirements.txt and + backend/requirements-dev.txt + - Runs the full testing/backend/ suite with pytest in quiet mode You do not need to activate any virtual environment manually for this command. -### 3. Run a Single Test File +3. Run a Single Test File When you want faster feedback on one specific file, activate the test virtual environment and call pytest directly. Run these commands from the repo root: -```bash source venv_tests/bin/activate python -m pytest testing/backend/unit/test_models.py -v deactivate -``` -Replace `test_models.py` with whichever file you want to target. All unit tests -live under `testing/backend/unit/` and integration tests live under -`testing/backend/integration/`. +Replace test_models.py with whichever file you want to target. All unit tests +live under testing/backend/unit/ and integration tests live under +testing/backend/integration/. -> **Note:** Run `./testing/test_python.sh` at least once before using this -> shortcut so that `venv_tests/` exists and dependencies are installed. +Note: Run ./testing/test_python.sh at least once before using this shortcut so +that venv_tests/ exists and dependencies are installed. -### 4. Where Requirements Files Live +4. Where Requirements Files Live -| File | Purpose | -|---|---| -| `backend/requirements.txt` | Core runtime dependencies | +| File | Purpose | +| ------------------------------ | ------------------------------------------------ | +| `backend/requirements.txt` | Core runtime dependencies | | `backend/requirements-dev.txt` | Test and development dependencies (pytest, etc.) | Both files must be installed for the test suite to run correctly. The -`./testing/test_python.sh` script installs both automatically. - -### 5. Common Dependency Issues - -- **`ModuleNotFoundError` on any import** — the `venv_tests/` environment may - be outdated. Delete it and re-run `./testing/test_python.sh` to rebuild from - scratch. -- **`python3` resolves to an older version** — check with `python3 --version`. - Use `python3.11` or `python3.12` explicitly if needed. -- **Permission denied on `./testing/test_python.sh`** — make it executable - first with `chmod +x testing/test_python.sh`. - -## Project Layout - -- `backend/secuscan`: FastAPI routes, execution logic, workflows, validation, vault, and reporting -- `frontend/src`: React pages, app shell, scan flows, settings, and tests -- `plugins`: plugin metadata, parser code, and tool-specific helpers -- `testing/backend`: backend unit and integration coverage -- `frontend/testing`: frontend unit and Playwright coverage -- `.github`: issue templates, PR template, and CI workflow - -## Development Workflow - -1. Fork the repository and create a branch from `main`. -2. Pick an issue or open one before starting large work. -3. Keep the change focused. Small PRs get reviewed much faster than broad rewrites. -4. Update tests and docs when behavior changes. -5. Open a pull request with a clear description, linked issue, and screenshots for UI changes. +./testing/test_python.sh script installs both automatically. + +5. Common Dependency Issues + + - ModuleNotFoundError on any import — the venv_tests/ environment may be + outdated. Delete it and re-run ./testing/test_python.sh to rebuild from + scratch. + - python3 resolves to an older version — check with python3 --version. Use + python3.11 or python3.12 explicitly if needed. + - Permission denied on ./testing/test_python.sh — make it executable first + with chmod +x testing/test_python.sh. + +Project Layout + + - backend/secuscan: FastAPI routes, execution logic, workflows, validation, + vault, and reporting + - frontend/src: React pages, app shell, scan flows, settings, and tests + - plugins: plugin metadata, parser code, and tool-specific helpers + - testing/backend: backend unit and integration coverage + - frontend/testing: frontend unit and Playwright coverage + - .github: issue templates, PR template, and CI workflow + +Development Workflow + + - Fork the repository and create a branch from main. + - Pick an issue or open one before starting large work. + - Keep the change focused. Small PRs get reviewed much faster than broad + rewrites. + - PR Size Thresholds: To help reviewers, we recommend keeping PRs under 50 + changed files and 1,000 lines of total changes (additions + deletions). A + lightweight, advisory GitHub Actions workflow will log a warning if your PR + exceeds this size to encourage splitting up large blocks of work. This will + not fail your build. + - Update tests and docs when behavior changes. + - Open a pull request with a clear description, linked issue, and screenshots + for UI changes. Branch names can be simple and descriptive, such as: -- `docs/improve-contributing-guide` -- `fix/task-status-api` -- `feat/plugin-validation` + - docs/improve-contributing-guide + - fix/task-status-api + - feat/plugin-validation -## Pull Request Format +Pull Request Format Please follow the repository PR template and keep the submission easy to review. Recommended PR title format: -- `docs: improve contributing guide` -- `fix(api): validate task status input` -- `feat(frontend): add scan empty state` + - docs: improve contributing guide + - fix(api): validate task status input + - feat(frontend): add scan empty state Your PR should include: -- A short description of the problem being solved -- A summary of the approach you took -- Linked issue references such as `Closes #123` or `Related to #123` -- A clear list of tests you ran -- Screenshots or short recordings for visible UI changes -- Notes about documentation, migrations, environment variables, or breaking behavior when relevant + - A short description of the problem being solved + - A summary of the approach you took + - Linked issue references such as Closes #123 or Related to #123 + - A clear list of tests you ran + - Screenshots or short recordings for visible UI changes + - Notes about documentation, migrations, environment variables, or breaking + behavior when relevant -Try to keep one pull request focused on one problem. If a change touches unrelated areas, split it into separate PRs when possible. +Try to keep one pull request focused on one problem. If a change touches +unrelated areas, split it into separate PRs when possible. -## Contribution Scoring +Contribution Scoring -Every merged pull request can be scored for GSSoC using labels applied by the project admin or mentor. The scoring engine reads these labels after the PR is merged, so contributors should focus on clear scope, good implementation, and complete review notes rather than self-assigning score labels. +Every merged pull request can be scored for GSSoC using labels applied by the +project admin or mentor. The scoring engine reads these labels after the PR is +merged, so contributors should focus on clear scope, good implementation, and +complete review notes rather than self-assigning score labels. -### Labels the Admin Applies +Labels the Admin Applies Each merged PR should have one difficulty label: -Each merged PR should have one difficulty label: - -- `level:beginner` -- `level:intermediate` -- `level:advanced` -- `level:critical` + - level:beginner + - level:intermediate + - level:advanced + - level:critical Optional quality labels can increase the contributor score: -- `quality:clean` -- `quality:exceptional` + - quality:clean + - quality:exceptional Optional type bonus labels can describe the work category: -- `type:docs` -- `type:testing` -- `type:accessibility` -- `type:performance` -- `type:security` -- `type:design` -- `type:refactor` -- `type:devops` -- `type:bug` -- `type:feature` + - type:docs, type:testing, type:accessibility, type:performance, + type:security, type:design, type:refactor, type:devops, type:bug, + type:feature Validation labels are decided by the admin: -- `gssoc:approved` -- `gssoc:invalid` -- `gssoc:spam` -- `gssoc:ai-slop` - -Use `mentor:username` to credit the reviewing mentor with points for that PR. - -### Contributor Points per PR - -| Label | Points | -| --- | ---: | -| `level:beginner` | 20 pts | -| `level:intermediate` | 35 pts | -| `level:advanced` | 55 pts | -| `level:critical` | 80 pts | -| `quality:clean` | x 1.2 multiplier | -| `quality:exceptional` | x 1.5 multiplier | - -Contributor score formula: + - gssoc:approved + - gssoc:invalid + - gssoc:spam + - gssoc:ai-slop -```text -((difficulty x quality) + type bonus) -``` +Use mentor:username to credit the reviewing mentor with points for that PR. -### Mentor Points per Reviewed PR +Contributor Points per PR | Label | Points | |-------|--------| | level:beginner +| 20 pts | | level:intermediate | 35 pts | | level:advanced | 55 pts | | +level:critical | 80 pts | | quality:clean | x 1.2 multiplier | | +quality:exceptional | x 1.5 multiplier | -| Label | Points | -| --- | ---: | -| `level:beginner` | 10 pts | -| `level:intermediate` | 20 pts | -| `level:advanced` | 30 pts | -| `level:critical` | 50 pts | -| `quality:clean` | +5 pts bonus | -| `quality:exceptional` | +10 pts bonus | +Contributor score formula: ((difficulty x quality) + type bonus) -Mentor score formula: +Mentor Points per Reviewed PR | Label | Points | |-------|--------| | +level:beginner | 10 pts | | level:intermediate | 20 pts | | level:advanced | 30 +pts | | level:critical | 50 pts | | quality:clean | +5 pts bonus | | +quality:exceptional| +10 pts bonus | -```text -(base points + quality bonus) -``` +Mentor score formula: (base points + quality bonus) -## Commit Message Conventions +Commit Message Conventions -Use clear, imperative commit messages. Keep the first line short and descriptive. +Use clear, imperative commit messages. Keep the first line short and +descriptive. -Preferred format: - -```text -type(scope): short summary -``` +Preferred format: type(scope): short summary Examples: -- `feat(frontend): add task result empty state` -- `fix(backend): reject invalid workflow payloads` -- `docs(readme): clarify local setup steps` - -Recommended commit types: + - feat(frontend): add task result empty state + - fix(backend): reject invalid workflow payloads + - docs(readme): clarify local setup steps -- `feat` -- `fix` -- `docs` -- `test` -- `refactor` -- `chore` +Recommended commit types: feat, fix, docs, test, refactor, chore Guidelines: -- Use the imperative mood, such as `add`, `fix`, `update`, or `remove` -- Keep the subject line around 72 characters or fewer -- Reference the issue number in the commit body when useful -- Avoid vague messages like `changes`, `update code`, or `fix stuff` + - Use the imperative mood, such as add, fix, update, or remove + - Keep the subject line around 72 characters or fewer + - Reference the issue number in the commit body when useful + - Avoid vague messages like changes, update code, or fix stuff -## Licensing Expectations +Licensing Expectations -By submitting a contribution, you agree that your changes can be distributed under the repository's MIT License. +By submitting a contribution, you agree that your changes can be distributed +under the repository's MIT License. Please avoid: -- Copying code from sources with incompatible licenses -- Adding assets, snippets, or templates without checking reuse permissions -- Introducing third-party dependencies without confirming their license is acceptable for this project + - Copying code from sources with incompatible licenses + - Adding assets, snippets, or templates without checking reuse permissions + - Introducing third-party dependencies without confirming their license is + acceptable for this project -If you are unsure about a dependency or asset license, ask in the issue or pull request before merging it into the project. +If you are unsure about a dependency or asset license, ask in the issue or pull +request before merging it into the project. -## Test Expectations +Test Expectations Run the smallest relevant test set for your change, then broaden if needed. -Backend tests: - -```bash -./testing/test_python.sh -``` - -Frontend unit tests: - -```bash -cd frontend -npm run test -``` - -Frontend production build: - -```bash -cd frontend -npm run build -``` - -Backend API smoke tests with the server running: - -```bash -./testing/test_backend.sh -``` - -Optional frontend E2E: - -```bash -cd frontend -npm run e2e -``` + - Backend tests: ./testing/test_python.sh + - Frontend unit tests: cd frontend && npm run test + - Frontend production build: cd frontend && npm run build + - Backend API smoke tests (with the server running): ./testing/test_backend.sh + - Optional frontend E2E: cd frontend && npm run e2e What we expect before review: -- Backend changes should run `./testing/test_python.sh` -- Frontend changes should run `npm run test` and `npm run build` in `frontend/` -- API or behavior changes should include either automated coverage or a short manual verification note -- Docs-only changes usually do not need full test runs, but please say that clearly in the PR -- If you could not run a recommended test, mention what you skipped and why + - Backend changes should run ./testing/test_python.sh + - Frontend changes should run npm run test and npm run build in frontend/ + - API or behavior changes should include either automated coverage or a short + manual verification note + - Docs-only changes usually do not need full test runs, but please say that + clearly in the PR + - If you could not run a recommended test, mention what you skipped and why + +Code Style -## Code Style +Please match the conventions already used in the repo instead of introducing a +new style. -Please match the conventions already used in the repo instead of introducing a new style. +Python: -- Python: - Follow PEP 8 and prefer explicit, readable code - Use type hints where they improve clarity - Keep validation close to request and model boundaries - Prefer small functions over large, multi-purpose blocks -- Frontend: + +Frontend: + - Use TypeScript and functional React components - Keep component logic readable and avoid unnecessary abstraction - Reuse shared UI patterns when they already exist - Include accessible labels, states, and error handling for form changes -- Tests: + +Tests: + - Add or update tests when behavior changes - Keep fixtures focused and easy to understand -- Docs: + +Docs: + - Update contributor-facing docs when setup, workflow, or commands change - Prefer concrete examples over generic instructions -## Review Timeline +Review Timeline Reviews are handled on a best-effort basis. Typical expectations: -- Initial maintainer response: within 3 business days for small, clearly scoped PRs -- Follow-up review after updates: usually within 2 to 4 business days -- Large PRs, release periods, or security-sensitive work may take longer + - Initial maintainer response: within 3 business days for small, clearly + scoped PRs + - Follow-up review after updates: usually within 2 to 4 business days + - Large PRs, release periods, or security-sensitive work may take longer -If a PR has been quiet for more than a week, a polite follow-up comment is completely fine. +If a PR has been quiet for more than a week, a polite follow-up comment is +completely fine. -## Review Etiquette +Review Etiquette -- Be kind, specific, and technical in review comments. -- Assume good intent and focus feedback on the code, docs, or behavior. -- If a maintainer asks for changes, update the PR instead of opening a new one unless requested. -- If you become inactive on a claimed issue, maintainers may reassign it so progress continues. + - Be kind, specific, and technical in review comments. + - Assume good intent and focus feedback on the code, docs, or behavior. + - If a maintainer asks for changes, update the PR instead of opening a new one + unless requested. + - If you become inactive on a claimed issue, maintainers may reassign it so + progress continues. -## Need Help? +Need Help? -- Use GitHub issues for bugs, enhancements, and scoped task discussion. -- Use pull request comments for implementation-specific review discussion. -- For security-sensitive reports, do not use public issues. Follow [SECURITY.md](SECURITY.md). + - Use GitHub issues for bugs, enhancements, and scoped task discussion. + - Use pull request comments for implementation-specific review discussion. + - For security-sensitive reports, do not use public issues. Follow + SECURITY.md. -Thank you for helping make SecuScan more useful, safer, and more welcoming to new contributors. -## Frontend Generated Artifacts +Thank you for helping make SecuScan more useful, safer, and more welcoming to +new contributors. + +Generated Artifacts and CI Warnings + +To maintain a clean commit history, we use a lightweight, advisory GitHub +Actions workflow to check all Pull Requests. This workflow will warn you in the +Actions tab if your PR contains unusually large diffs or accidentally committed +generated testing files. This warning will not fail your CI build. Never commit these auto-generated paths: -- `frontend/dist/` -- `frontend/playwright-report/` -- `frontend/test-results/` -- `frontend/.vite/` -- `.vite/deps/` -If CI fails, run: -```bash -git rm --cached -echo 'frontend/dist/' >> .gitignore \ No newline at end of file + - frontend/dist/ + - frontend/playwright-report/ + - frontend/test-results/ + - frontend/.vite/ + - .vite/deps/ + +If the CI check flags your PR for containing these folders, you can remove them +from your Git history and ensure they are ignored: + +git rm -r --cached frontend/playwright-report/ frontend/test-results/ frontend/dist/ +echo 'frontend/dist/' >> .gitignore +echo 'frontend/playwright-report/' >> .gitignore +echo 'frontend/test-results/' >> .gitignore + From 6c8fc4153a4f7cadb04a736d53d0be71992dac3f Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Thu, 28 May 2026 22:21:28 +0530 Subject: [PATCH 03/12] Update CONTRIBUTING.md --- CONTRIBUTING.md | 476 +++++++++++++++++++++--------------------------- 1 file changed, 203 insertions(+), 273 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d98928f..e91c0746 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,13 +5,15 @@ Thank you for contributing to SecuScan. This project is open to first-time contr SecuScan is built for learning, defensive security workflows, and ethical testing. Please keep all contributions aligned with authorized, consent-based use. ## Before You Start + - Start with a small, reviewable task if this is your first contribution. -- Read `README.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` before opening a pull request. -- Read the repository `LICENSE` so you understand how contributions are distributed. +- Read [README.md](README.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md) before opening a pull request. +- Read the repository [LICENSE](LICENSE) so you understand how contributions are distributed. - If you want to work on a larger feature, open or comment on an issue first so effort does not overlap. - If you are contributing through GSSoC, mention that in the issue or pull request so maintainers can guide scope and review expectations. ## Good First Contribution Areas + - Documentation fixes, setup clarification, and onboarding polish - Frontend UX improvements in `frontend/src` - Backend validation, test coverage, and API consistency in `backend/secuscan` @@ -23,349 +25,277 @@ When issue labels are available, look for tags such as `good first issue`, `docu ## Local Setup ### Prerequisites -- Python 3.11+ -- Node.js 20+ recommended -- npm + +- Python `3.11+` +- Node.js `20+` recommended +- `npm` - Docker optional for plugins that depend on containerized tooling ### Recommended Setup + ```bash ./setup.sh ./start.sh - This starts: - - - Backend: http://127.0.0.1:8000 - - Frontend: http://127.0.0.1:5173 - - API docs: http://127.0.0.1:8000/docs - +Backend: http://127.0.0.1:8000 +Frontend: http://127.0.0.1:5173 +API docs: http://127.0.0.1:8000/docs Manual Setup - -Backend: Python version: python3 below must resolve to 3.11 or newer. Run -python3 --version to check. If your system default is older, substitute the full -path (e.g. python3.11) or use PYTHON=/path/to/python3.11 ./setup.sh instead of -the manual steps. - +Backend: +Python version: python3 below must resolve to 3.11 or newer. Run python3 --version to check. If your system default is older, substitute the full path (e.g. python3.11) or use PYTHON=/path/to/python3.11 ./setup.sh instead of the manual steps. +code +Bash python3 -m venv venv source venv/bin/activate pip install -r backend/requirements.txt pip install -r backend/requirements-dev.txt python3 -m uvicorn backend.secuscan.main:app --reload --host 127.0.0.1 --port 8000 - Frontend: - +code +Bash cd frontend npm install npm run dev -- --host 127.0.0.1 --port 5173 - Backend Testing Quickstart - This section explains how to run the backend test suite from a fresh checkout without touching the main development environment. - 1. Prerequisites - -Make sure your machine has Python 3.11 or newer before running any test -commands. - +Make sure your machine has Python 3.11 or newer before running any test commands. +code +Bash python3 --version - -If the version shown is older than 3.11, substitute the full path to a -compatible interpreter (e.g. python3.11) wherever python3 appears below. - +If the version shown is older than 3.11, substitute the full path to a compatible +interpreter (e.g. python3.11) wherever python3 appears below. 2. Run the Full Backend Test Suite - From the repo root, run: - +code +Bash ./testing/test_python.sh - This script handles everything automatically: - - - Creates an isolated virtual environment at venv_tests/ (separate from your - dev environment) - - Installs all required dependencies from backend/requirements.txt and - backend/requirements-dev.txt - - Runs the full testing/backend/ suite with pytest in quiet mode - +Creates an isolated virtual environment at venv_tests/ (separate from your +dev environment) +Installs all required dependencies from backend/requirements.txt and +backend/requirements-dev.txt +Runs the full testing/backend/ suite with pytest in quiet mode You do not need to activate any virtual environment manually for this command. - 3. Run a Single Test File - When you want faster feedback on one specific file, activate the test virtual environment and call pytest directly. Run these commands from the repo root: - +code +Bash source venv_tests/bin/activate python -m pytest testing/backend/unit/test_models.py -v deactivate - Replace test_models.py with whichever file you want to target. All unit tests live under testing/backend/unit/ and integration tests live under testing/backend/integration/. - -Note: Run ./testing/test_python.sh at least once before using this shortcut so -that venv_tests/ exists and dependencies are installed. - +Note: Run ./testing/test_python.sh at least once before using this +shortcut so that venv_tests/ exists and dependencies are installed. 4. Where Requirements Files Live - -| File | Purpose | -| ------------------------------ | ------------------------------------------------ | -| `backend/requirements.txt` | Core runtime dependencies | -| `backend/requirements-dev.txt` | Test and development dependencies (pytest, etc.) | - +File Purpose +backend/requirements.txt Core runtime dependencies +backend/requirements-dev.txt Test and development dependencies (pytest, etc.) Both files must be installed for the test suite to run correctly. The ./testing/test_python.sh script installs both automatically. - 5. Common Dependency Issues - - - ModuleNotFoundError on any import — the venv_tests/ environment may be - outdated. Delete it and re-run ./testing/test_python.sh to rebuild from - scratch. - - python3 resolves to an older version — check with python3 --version. Use - python3.11 or python3.12 explicitly if needed. - - Permission denied on ./testing/test_python.sh — make it executable first - with chmod +x testing/test_python.sh. - +ModuleNotFoundError on any import — the venv_tests/ environment may +be outdated. Delete it and re-run ./testing/test_python.sh to rebuild from +scratch. +python3 resolves to an older version — check with python3 --version. +Use python3.11 or python3.12 explicitly if needed. +Permission denied on ./testing/test_python.sh — make it executable +first with chmod +x testing/test_python.sh. Project Layout - - - backend/secuscan: FastAPI routes, execution logic, workflows, validation, - vault, and reporting - - frontend/src: React pages, app shell, scan flows, settings, and tests - - plugins: plugin metadata, parser code, and tool-specific helpers - - testing/backend: backend unit and integration coverage - - frontend/testing: frontend unit and Playwright coverage - - .github: issue templates, PR template, and CI workflow - +backend/secuscan: FastAPI routes, execution logic, workflows, validation, vault, and reporting +frontend/src: React pages, app shell, scan flows, settings, and tests +plugins: plugin metadata, parser code, and tool-specific helpers +testing/backend: backend unit and integration coverage +frontend/testing: frontend unit and Playwright coverage +.github: issue templates, PR template, and CI workflow Development Workflow - - - Fork the repository and create a branch from main. - - Pick an issue or open one before starting large work. - - Keep the change focused. Small PRs get reviewed much faster than broad - rewrites. - - PR Size Thresholds: To help reviewers, we recommend keeping PRs under 50 - changed files and 1,000 lines of total changes (additions + deletions). A - lightweight, advisory GitHub Actions workflow will log a warning if your PR - exceeds this size to encourage splitting up large blocks of work. This will - not fail your build. - - Update tests and docs when behavior changes. - - Open a pull request with a clear description, linked issue, and screenshots - for UI changes. - +Fork the repository and create a branch from main. +Pick an issue or open one before starting large work. +Keep the change focused. Small PRs get reviewed much faster than broad rewrites. +Mind your PR size. We recommend keeping PRs under 50 changed files and 1,000 lines of total changes (additions + deletions). An automated GitHub Action will warn you if your PR exceeds this threshold. +Update tests and docs when behavior changes. +Open a pull request with a clear description, linked issue, and screenshots for UI changes. Branch names can be simple and descriptive, such as: - - - docs/improve-contributing-guide - - fix/task-status-api - - feat/plugin-validation - +docs/improve-contributing-guide +fix/task-status-api +feat/plugin-validation Pull Request Format - Please follow the repository PR template and keep the submission easy to review. - Recommended PR title format: - - - docs: improve contributing guide - - fix(api): validate task status input - - feat(frontend): add scan empty state - +docs: improve contributing guide +fix(api): validate task status input +feat(frontend): add scan empty state Your PR should include: - - - A short description of the problem being solved - - A summary of the approach you took - - Linked issue references such as Closes #123 or Related to #123 - - A clear list of tests you ran - - Screenshots or short recordings for visible UI changes - - Notes about documentation, migrations, environment variables, or breaking - behavior when relevant - -Try to keep one pull request focused on one problem. If a change touches -unrelated areas, split it into separate PRs when possible. - +A short description of the problem being solved +A summary of the approach you took +Linked issue references such as Closes #123 or Related to #123 +A clear list of tests you ran +Screenshots or short recordings for visible UI changes +Notes about documentation, migrations, environment variables, or breaking behavior when relevant +Try to keep one pull request focused on one problem. If a change touches unrelated areas, split it into separate PRs when possible. Contribution Scoring - -Every merged pull request can be scored for GSSoC using labels applied by the -project admin or mentor. The scoring engine reads these labels after the PR is -merged, so contributors should focus on clear scope, good implementation, and -complete review notes rather than self-assigning score labels. - -Labels the Admin Applies Each merged PR should have one difficulty label: - - - level:beginner - - level:intermediate - - level:advanced - - level:critical - +Every merged pull request can be scored for GSSoC using labels applied by the project admin or mentor. The scoring engine reads these labels after the PR is merged, so contributors should focus on clear scope, good implementation, and complete review notes rather than self-assigning score labels. +Labels the Admin Applies +Each merged PR should have one difficulty label: +level:beginner +level:intermediate +level:advanced +level:critical Optional quality labels can increase the contributor score: - - - quality:clean - - quality:exceptional - +quality:clean +quality:exceptional Optional type bonus labels can describe the work category: - - - type:docs, type:testing, type:accessibility, type:performance, - type:security, type:design, type:refactor, type:devops, type:bug, - type:feature - +type:docs +type:testing +type:accessibility +type:performance +type:security +type:design +type:refactor +type:devops +type:bug +type:feature Validation labels are decided by the admin: - - - gssoc:approved - - gssoc:invalid - - gssoc:spam - - gssoc:ai-slop - +gssoc:approved +gssoc:invalid +gssoc:spam +gssoc:ai-slop Use mentor:username to credit the reviewing mentor with points for that PR. - -Contributor Points per PR | Label | Points | |-------|--------| | level:beginner -| 20 pts | | level:intermediate | 35 pts | | level:advanced | 55 pts | | -level:critical | 80 pts | | quality:clean | x 1.2 multiplier | | -quality:exceptional | x 1.5 multiplier | - -Contributor score formula: ((difficulty x quality) + type bonus) - -Mentor Points per Reviewed PR | Label | Points | |-------|--------| | -level:beginner | 10 pts | | level:intermediate | 20 pts | | level:advanced | 30 -pts | | level:critical | 50 pts | | quality:clean | +5 pts bonus | | -quality:exceptional| +10 pts bonus | - -Mentor score formula: (base points + quality bonus) - +Contributor Points per PR +Label Points +level:beginner 20 pts +level:intermediate 35 pts +level:advanced 55 pts +level:critical 80 pts +quality:clean x 1.2 multiplier +quality:exceptional x 1.5 multiplier +Contributor score formula: +code +Text +((difficulty x quality) + type bonus) +Mentor Points per Reviewed PR +Label Points +level:beginner 10 pts +level:intermediate 20 pts +level:advanced 30 pts +level:critical 50 pts +quality:clean +5 pts bonus +quality:exceptional +10 pts bonus +Mentor score formula: +code +Text +(base points + quality bonus) Commit Message Conventions - -Use clear, imperative commit messages. Keep the first line short and -descriptive. - -Preferred format: type(scope): short summary - +Use clear, imperative commit messages. Keep the first line short and descriptive. +Preferred format: +code +Text +type(scope): short summary Examples: - - - feat(frontend): add task result empty state - - fix(backend): reject invalid workflow payloads - - docs(readme): clarify local setup steps - -Recommended commit types: feat, fix, docs, test, refactor, chore - +feat(frontend): add task result empty state +fix(backend): reject invalid workflow payloads +docs(readme): clarify local setup steps +Recommended commit types: +feat +fix +docs +test +refactor +chore Guidelines: - - - Use the imperative mood, such as add, fix, update, or remove - - Keep the subject line around 72 characters or fewer - - Reference the issue number in the commit body when useful - - Avoid vague messages like changes, update code, or fix stuff - +Use the imperative mood, such as add, fix, update, or remove +Keep the subject line around 72 characters or fewer +Reference the issue number in the commit body when useful +Avoid vague messages like changes, update code, or fix stuff Licensing Expectations - -By submitting a contribution, you agree that your changes can be distributed -under the repository's MIT License. - +By submitting a contribution, you agree that your changes can be distributed under the repository's MIT License. Please avoid: - - - Copying code from sources with incompatible licenses - - Adding assets, snippets, or templates without checking reuse permissions - - Introducing third-party dependencies without confirming their license is - acceptable for this project - -If you are unsure about a dependency or asset license, ask in the issue or pull -request before merging it into the project. - +Copying code from sources with incompatible licenses +Adding assets, snippets, or templates without checking reuse permissions +Introducing third-party dependencies without confirming their license is acceptable for this project +If you are unsure about a dependency or asset license, ask in the issue or pull request before merging it into the project. Test Expectations - Run the smallest relevant test set for your change, then broaden if needed. - - - Backend tests: ./testing/test_python.sh - - Frontend unit tests: cd frontend && npm run test - - Frontend production build: cd frontend && npm run build - - Backend API smoke tests (with the server running): ./testing/test_backend.sh - - Optional frontend E2E: cd frontend && npm run e2e - +Backend tests: +code +Bash +./testing/test_python.sh +Frontend unit tests: +code +Bash +cd frontend +npm run test +Frontend production build: +code +Bash +cd frontend +npm run build +Backend API smoke tests with the server running: +code +Bash +./testing/test_backend.sh +Optional frontend E2E: +code +Bash +cd frontend +npm run e2e What we expect before review: - - - Backend changes should run ./testing/test_python.sh - - Frontend changes should run npm run test and npm run build in frontend/ - - API or behavior changes should include either automated coverage or a short - manual verification note - - Docs-only changes usually do not need full test runs, but please say that - clearly in the PR - - If you could not run a recommended test, mention what you skipped and why - +Backend changes should run ./testing/test_python.sh +Frontend changes should run npm run test and npm run build in frontend/ +API or behavior changes should include either automated coverage or a short manual verification note +Docs-only changes usually do not need full test runs, but please say that clearly in the PR +If you could not run a recommended test, mention what you skipped and why Code Style - -Please match the conventions already used in the repo instead of introducing a -new style. - +Please match the conventions already used in the repo instead of introducing a new style. Python: - - - Follow PEP 8 and prefer explicit, readable code - - Use type hints where they improve clarity - - Keep validation close to request and model boundaries - - Prefer small functions over large, multi-purpose blocks - +Follow PEP 8 and prefer explicit, readable code +Use type hints where they improve clarity +Keep validation close to request and model boundaries +Prefer small functions over large, multi-purpose blocks Frontend: - - - Use TypeScript and functional React components - - Keep component logic readable and avoid unnecessary abstraction - - Reuse shared UI patterns when they already exist - - Include accessible labels, states, and error handling for form changes - +Use TypeScript and functional React components +Keep component logic readable and avoid unnecessary abstraction +Reuse shared UI patterns when they already exist +Include accessible labels, states, and error handling for form changes Tests: - - - Add or update tests when behavior changes - - Keep fixtures focused and easy to understand - +Add or update tests when behavior changes +Keep fixtures focused and easy to understand Docs: - - - Update contributor-facing docs when setup, workflow, or commands change - - Prefer concrete examples over generic instructions - +Update contributor-facing docs when setup, workflow, or commands change +Prefer concrete examples over generic instructions Review Timeline - Reviews are handled on a best-effort basis. - Typical expectations: - - - Initial maintainer response: within 3 business days for small, clearly - scoped PRs - - Follow-up review after updates: usually within 2 to 4 business days - - Large PRs, release periods, or security-sensitive work may take longer - -If a PR has been quiet for more than a week, a polite follow-up comment is -completely fine. - +Initial maintainer response: within 3 business days for small, clearly scoped PRs +Follow-up review after updates: usually within 2 to 4 business days +Large PRs, release periods, or security-sensitive work may take longer +If a PR has been quiet for more than a week, a polite follow-up comment is completely fine. Review Etiquette - - - Be kind, specific, and technical in review comments. - - Assume good intent and focus feedback on the code, docs, or behavior. - - If a maintainer asks for changes, update the PR instead of opening a new one - unless requested. - - If you become inactive on a claimed issue, maintainers may reassign it so - progress continues. - +Be kind, specific, and technical in review comments. +Assume good intent and focus feedback on the code, docs, or behavior. +If a maintainer asks for changes, update the PR instead of opening a new one unless requested. +If you become inactive on a claimed issue, maintainers may reassign it so progress continues. Need Help? - - - Use GitHub issues for bugs, enhancements, and scoped task discussion. - - Use pull request comments for implementation-specific review discussion. - - For security-sensitive reports, do not use public issues. Follow - SECURITY.md. - -Thank you for helping make SecuScan more useful, safer, and more welcoming to -new contributors. - -Generated Artifacts and CI Warnings - -To maintain a clean commit history, we use a lightweight, advisory GitHub -Actions workflow to check all Pull Requests. This workflow will warn you in the -Actions tab if your PR contains unusually large diffs or accidentally committed -generated testing files. This warning will not fail your CI build. - +Use GitHub issues for bugs, enhancements, and scoped task discussion. +Use pull request comments for implementation-specific review discussion. +For security-sensitive reports, do not use public issues. Follow SECURITY.md. +Thank you for helping make SecuScan more useful, safer, and more welcoming to new contributors. +PR Size & Generated Artifacts +To maintain a clean commit history and make reviews manageable, we use a lightweight, advisory GitHub Actions workflow on all Pull Requests. This workflow will log a warning in the Actions tab but will not fail your CI build. Never commit these auto-generated paths: - - - frontend/dist/ - - frontend/playwright-report/ - - frontend/test-results/ - - frontend/.vite/ - - .vite/deps/ - -If the CI check flags your PR for containing these folders, you can remove them -from your Git history and ensure they are ignored: - +frontend/dist/ +frontend/playwright-report/ +frontend/test-results/ +frontend/.vite/ +.vite/deps/ +If the CI workflow flags your PR for containing these folders, you can remove them from your Git history and ensure they are ignored by running: +code +Bash git rm -r --cached frontend/playwright-report/ frontend/test-results/ frontend/dist/ echo 'frontend/dist/' >> .gitignore echo 'frontend/playwright-report/' >> .gitignore echo 'frontend/test-results/' >> .gitignore - From 935b04c69f47e295d7c3151ca52d73e8e64e1349 Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Thu, 28 May 2026 22:22:29 +0530 Subject: [PATCH 04/12] Update CONTRIBUTING.md --- CONTRIBUTING.md | 702 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 466 insertions(+), 236 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e91c0746..9a19037a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,298 +4,528 @@ Thank you for contributing to SecuScan. This project is open to first-time contr SecuScan is built for learning, defensive security workflows, and ethical testing. Please keep all contributions aligned with authorized, consent-based use. -## Before You Start +--- -- Start with a small, reviewable task if this is your first contribution. -- Read [README.md](README.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md) before opening a pull request. -- Read the repository [LICENSE](LICENSE) so you understand how contributions are distributed. -- If you want to work on a larger feature, open or comment on an issue first so effort does not overlap. -- If you are contributing through GSSoC, mention that in the issue or pull request so maintainers can guide scope and review expectations. +# Before You Start -## Good First Contribution Areas +* Start with a small, reviewable task if this is your first contribution. +* Read `README.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` before opening a pull request. +* Read the repository `LICENSE` so you understand how contributions are distributed. +* If you want to work on a larger feature, open or comment on an issue first so effort does not overlap. +* If you are contributing through GSSoC, mention that in the issue or pull request so maintainers can guide scope and review expectations. -- Documentation fixes, setup clarification, and onboarding polish -- Frontend UX improvements in `frontend/src` -- Backend validation, test coverage, and API consistency in `backend/secuscan` -- Plugin metadata cleanup and parser improvements in `plugins` -- CI, test reliability, and developer experience +--- -When issue labels are available, look for tags such as `good first issue`, `documentation`, `frontend`, `backend`, `plugin`, `help wanted`, or `gssoc`. +# Good First Contribution Areas -## Local Setup +* Documentation fixes, setup clarification, and onboarding polish +* Frontend UX improvements in `frontend/src` +* Backend validation, test coverage, and API consistency in `backend/secuscan` +* Plugin metadata cleanup and parser improvements in `plugins` +* CI, test reliability, and developer experience -### Prerequisites +When issue labels are available, look for tags such as: -- Python `3.11+` -- Node.js `20+` recommended -- `npm` -- Docker optional for plugins that depend on containerized tooling +* `good first issue` +* `documentation` +* `frontend` +* `backend` +* `plugin` +* `help wanted` +* `gssoc` -### Recommended Setup +--- + +# Local Setup + +## Prerequisites + +* Python `3.11+` +* Node.js `20+` recommended +* `npm` +* Docker (optional for plugins that depend on containerized tooling) + +--- + +## Recommended Setup ```bash ./setup.sh ./start.sh +``` + This starts: -Backend: http://127.0.0.1:8000 -Frontend: http://127.0.0.1:5173 -API docs: http://127.0.0.1:8000/docs -Manual Setup -Backend: -Python version: python3 below must resolve to 3.11 or newer. Run python3 --version to check. If your system default is older, substitute the full path (e.g. python3.11) or use PYTHON=/path/to/python3.11 ./setup.sh instead of the manual steps. -code -Bash + +* Backend: `http://127.0.0.1:8000` +* Frontend: `http://127.0.0.1:5173` +* API Docs: `http://127.0.0.1:8000/docs` + +--- + +# Manual Setup + +## Backend + +Python version: `python3` below must resolve to `3.11+`. + +Check version: + +```bash +python3 --version +``` + +If your system default is older, substitute the full path (e.g. `python3.11`) or use: + +```bash +PYTHON=/path/to/python3.11 ./setup.sh +``` + +### Setup Commands + +```bash python3 -m venv venv source venv/bin/activate + pip install -r backend/requirements.txt pip install -r backend/requirements-dev.txt -python3 -m uvicorn backend.secuscan.main:app --reload --host 127.0.0.1 --port 8000 -Frontend: -code -Bash + +python3 -m uvicorn backend.secuscan.main:app \ + --reload \ + --host 127.0.0.1 \ + --port 8000 +``` + +--- + +## Frontend + +```bash cd frontend + npm install npm run dev -- --host 127.0.0.1 --port 5173 -Backend Testing Quickstart -This section explains how to run the backend test suite from a fresh checkout -without touching the main development environment. -1. Prerequisites -Make sure your machine has Python 3.11 or newer before running any test commands. -code -Bash +``` + +--- + +# Backend Testing Quickstart + +This section explains how to run the backend test suite from a fresh checkout without touching the main development environment. + +--- + +## 1. Prerequisites + +Make sure your machine has Python `3.11+`. + +```bash python3 --version -If the version shown is older than 3.11, substitute the full path to a compatible -interpreter (e.g. python3.11) wherever python3 appears below. -2. Run the Full Backend Test Suite -From the repo root, run: -code -Bash +``` + +If the version shown is older than `3.11`, substitute the full path to a compatible interpreter (e.g. `python3.11`) wherever `python3` appears below. + +--- + +## 2. Run the Full Backend Test Suite + +From the repo root: + +```bash ./testing/test_python.sh -This script handles everything automatically: -Creates an isolated virtual environment at venv_tests/ (separate from your -dev environment) -Installs all required dependencies from backend/requirements.txt and -backend/requirements-dev.txt -Runs the full testing/backend/ suite with pytest in quiet mode -You do not need to activate any virtual environment manually for this command. -3. Run a Single Test File -When you want faster feedback on one specific file, activate the test virtual -environment and call pytest directly. Run these commands from the repo root: -code -Bash +``` + +This script automatically: + +* Creates an isolated virtual environment at `venv_tests/` +* Installs dependencies from: + + * `backend/requirements.txt` + * `backend/requirements-dev.txt` +* Runs the full `testing/backend/` suite with `pytest` + +You do not need to activate any virtual environment manually. + +--- + +## 3. Run a Single Test File + +```bash source venv_tests/bin/activate + python -m pytest testing/backend/unit/test_models.py -v + deactivate -Replace test_models.py with whichever file you want to target. All unit tests -live under testing/backend/unit/ and integration tests live under -testing/backend/integration/. -Note: Run ./testing/test_python.sh at least once before using this -shortcut so that venv_tests/ exists and dependencies are installed. -4. Where Requirements Files Live -File Purpose -backend/requirements.txt Core runtime dependencies -backend/requirements-dev.txt Test and development dependencies (pytest, etc.) -Both files must be installed for the test suite to run correctly. The -./testing/test_python.sh script installs both automatically. -5. Common Dependency Issues -ModuleNotFoundError on any import — the venv_tests/ environment may -be outdated. Delete it and re-run ./testing/test_python.sh to rebuild from -scratch. -python3 resolves to an older version — check with python3 --version. -Use python3.11 or python3.12 explicitly if needed. -Permission denied on ./testing/test_python.sh — make it executable -first with chmod +x testing/test_python.sh. -Project Layout -backend/secuscan: FastAPI routes, execution logic, workflows, validation, vault, and reporting -frontend/src: React pages, app shell, scan flows, settings, and tests -plugins: plugin metadata, parser code, and tool-specific helpers -testing/backend: backend unit and integration coverage -frontend/testing: frontend unit and Playwright coverage -.github: issue templates, PR template, and CI workflow -Development Workflow -Fork the repository and create a branch from main. -Pick an issue or open one before starting large work. -Keep the change focused. Small PRs get reviewed much faster than broad rewrites. -Mind your PR size. We recommend keeping PRs under 50 changed files and 1,000 lines of total changes (additions + deletions). An automated GitHub Action will warn you if your PR exceeds this threshold. -Update tests and docs when behavior changes. -Open a pull request with a clear description, linked issue, and screenshots for UI changes. -Branch names can be simple and descriptive, such as: +``` + +Replace `test_models.py` with whichever file you want to target. + +* Unit tests: `testing/backend/unit/` +* Integration tests: `testing/backend/integration/` + +> Run `./testing/test_python.sh` at least once before using this shortcut. + +--- + +## 4. Requirements Files + +| File | Purpose | +| ------------------------------ | --------------------------------- | +| `backend/requirements.txt` | Core runtime dependencies | +| `backend/requirements-dev.txt` | Test and development dependencies | + +Both files must be installed for the test suite to run correctly. + +--- + +## 5. Common Dependency Issues + +### `ModuleNotFoundError` + +The `venv_tests/` environment may be outdated. + +Fix: + +```bash +rm -rf venv_tests +./testing/test_python.sh +``` + +--- + +### `python3` Resolves to an Older Version + +Check: + +```bash +python3 --version +``` + +Use `python3.11` or `python3.12` explicitly if needed. + +--- + +### Permission Denied on Test Script + +```bash +chmod +x testing/test_python.sh +``` + +--- + +# Project Layout + +| Path | Purpose | +| ------------------ | ------------------------------------------------ | +| `backend/secuscan` | FastAPI routes, workflows, validation, reporting | +| `frontend/src` | React pages, scan flows, settings, tests | +| `plugins` | Plugin metadata and parser helpers | +| `testing/backend` | Backend unit and integration coverage | +| `frontend/testing` | Frontend unit and Playwright coverage | +| `.github` | Templates and CI workflows | + +--- + +# Development Workflow + +1. Fork the repository and create a branch from `main` +2. Pick an issue or open one before starting large work +3. Keep changes focused and reviewable +4. Update tests and docs when behavior changes +5. Open a PR with: + + * Clear description + * Linked issue + * Screenshots for UI changes + +### Example Branch Names + +```text docs/improve-contributing-guide fix/task-status-api feat/plugin-validation -Pull Request Format -Please follow the repository PR template and keep the submission easy to review. +``` + +--- + +# Pull Request Format + Recommended PR title format: + +```text docs: improve contributing guide fix(api): validate task status input feat(frontend): add scan empty state +``` + Your PR should include: -A short description of the problem being solved -A summary of the approach you took -Linked issue references such as Closes #123 or Related to #123 -A clear list of tests you ran -Screenshots or short recordings for visible UI changes -Notes about documentation, migrations, environment variables, or breaking behavior when relevant -Try to keep one pull request focused on one problem. If a change touches unrelated areas, split it into separate PRs when possible. -Contribution Scoring -Every merged pull request can be scored for GSSoC using labels applied by the project admin or mentor. The scoring engine reads these labels after the PR is merged, so contributors should focus on clear scope, good implementation, and complete review notes rather than self-assigning score labels. -Labels the Admin Applies -Each merged PR should have one difficulty label: -level:beginner -level:intermediate -level:advanced -level:critical -Optional quality labels can increase the contributor score: -quality:clean -quality:exceptional -Optional type bonus labels can describe the work category: -type:docs -type:testing -type:accessibility -type:performance -type:security -type:design -type:refactor -type:devops -type:bug -type:feature -Validation labels are decided by the admin: -gssoc:approved -gssoc:invalid -gssoc:spam -gssoc:ai-slop -Use mentor:username to credit the reviewing mentor with points for that PR. -Contributor Points per PR -Label Points -level:beginner 20 pts -level:intermediate 35 pts -level:advanced 55 pts -level:critical 80 pts -quality:clean x 1.2 multiplier -quality:exceptional x 1.5 multiplier -Contributor score formula: -code -Text -((difficulty x quality) + type bonus) -Mentor Points per Reviewed PR -Label Points -level:beginner 10 pts -level:intermediate 20 pts -level:advanced 30 pts -level:critical 50 pts -quality:clean +5 pts bonus -quality:exceptional +10 pts bonus -Mentor score formula: -code -Text + +* Problem being solved +* Summary of approach +* Linked issue references +* Tests you ran +* Screenshots/recordings for UI changes +* Notes about docs, migrations, env vars, or breaking behavior + +Try to keep one PR focused on one problem. + +--- + +# Contribution Scoring + +Every merged PR can be scored for GSSoC using labels applied by maintainers. + +--- + +## Difficulty Labels + +* `level:beginner` +* `level:intermediate` +* `level:advanced` +* `level:critical` + +--- + +## Quality Labels + +* `quality:clean` +* `quality:exceptional` + +--- + +## Type Bonus Labels + +* `type:docs` +* `type:testing` +* `type:accessibility` +* `type:performance` +* `type:security` +* `type:design` +* `type:refactor` +* `type:devops` +* `type:bug` +* `type:feature` + +--- + +## Validation Labels + +* `gssoc:approved` +* `gssoc:invalid` +* `gssoc:spam` +* `gssoc:ai-slop` + +--- + +## Contributor Score Formula + +```text +((difficulty × quality) + type bonus) +``` + +--- + +## Mentor Score Formula + +```text (base points + quality bonus) -Commit Message Conventions -Use clear, imperative commit messages. Keep the first line short and descriptive. +``` + +--- + +# Commit Message Conventions + Preferred format: -code -Text + +```text type(scope): short summary -Examples: +``` + +### Examples + +```text feat(frontend): add task result empty state fix(backend): reject invalid workflow payloads docs(readme): clarify local setup steps -Recommended commit types: -feat -fix -docs -test -refactor -chore -Guidelines: -Use the imperative mood, such as add, fix, update, or remove -Keep the subject line around 72 characters or fewer -Reference the issue number in the commit body when useful -Avoid vague messages like changes, update code, or fix stuff -Licensing Expectations +``` + +### Recommended Commit Types + +* `feat` +* `fix` +* `docs` +* `test` +* `refactor` +* `chore` + +### Guidelines + +* Use imperative mood (`add`, `fix`, `update`) +* Keep subject line under ~72 characters +* Avoid vague messages like: + + * `changes` + * `update code` + * `fix stuff` + +--- + +# Licensing Expectations + By submitting a contribution, you agree that your changes can be distributed under the repository's MIT License. + Please avoid: -Copying code from sources with incompatible licenses -Adding assets, snippets, or templates without checking reuse permissions -Introducing third-party dependencies without confirming their license is acceptable for this project -If you are unsure about a dependency or asset license, ask in the issue or pull request before merging it into the project. -Test Expectations -Run the smallest relevant test set for your change, then broaden if needed. -Backend tests: -code -Bash + +* Copying incompatible licensed code +* Adding unverified assets/snippets/templates +* Introducing dependencies without checking license compatibility + +If unsure, ask in the issue or PR before merging. + +--- + +# Test Expectations + +Run the smallest relevant test set for your change. + +--- + +## Backend Tests + +```bash ./testing/test_python.sh -Frontend unit tests: -code -Bash +``` + +--- + +## Frontend Unit Tests + +```bash cd frontend npm run test -Frontend production build: -code -Bash +``` + +--- + +## Frontend Production Build + +```bash cd frontend npm run build -Backend API smoke tests with the server running: -code -Bash +``` + +--- + +## Backend API Smoke Tests + +```bash ./testing/test_backend.sh -Optional frontend E2E: -code -Bash +``` + +--- + +## Optional Frontend E2E + +```bash cd frontend npm run e2e -What we expect before review: -Backend changes should run ./testing/test_python.sh -Frontend changes should run npm run test and npm run build in frontend/ -API or behavior changes should include either automated coverage or a short manual verification note -Docs-only changes usually do not need full test runs, but please say that clearly in the PR -If you could not run a recommended test, mention what you skipped and why -Code Style -Please match the conventions already used in the repo instead of introducing a new style. -Python: -Follow PEP 8 and prefer explicit, readable code -Use type hints where they improve clarity -Keep validation close to request and model boundaries -Prefer small functions over large, multi-purpose blocks -Frontend: -Use TypeScript and functional React components -Keep component logic readable and avoid unnecessary abstraction -Reuse shared UI patterns when they already exist -Include accessible labels, states, and error handling for form changes -Tests: -Add or update tests when behavior changes -Keep fixtures focused and easy to understand -Docs: -Update contributor-facing docs when setup, workflow, or commands change -Prefer concrete examples over generic instructions -Review Timeline -Reviews are handled on a best-effort basis. +``` + +--- + +# Code Style + +## Python + +* Follow PEP 8 +* Prefer explicit, readable code +* Use type hints where useful +* Prefer small focused functions + +--- + +## Frontend + +* Use TypeScript and functional React components +* Keep logic readable +* Reuse shared UI patterns +* Include accessible labels and error handling + +--- + +## Tests + +* Add/update tests when behavior changes +* Keep fixtures focused and understandable + +--- + +## Docs + +* Update contributor-facing docs when setup/workflow changes +* Prefer concrete examples over generic instructions + +--- + +# Review Timeline + Typical expectations: -Initial maintainer response: within 3 business days for small, clearly scoped PRs -Follow-up review after updates: usually within 2 to 4 business days -Large PRs, release periods, or security-sensitive work may take longer -If a PR has been quiet for more than a week, a polite follow-up comment is completely fine. -Review Etiquette -Be kind, specific, and technical in review comments. -Assume good intent and focus feedback on the code, docs, or behavior. -If a maintainer asks for changes, update the PR instead of opening a new one unless requested. -If you become inactive on a claimed issue, maintainers may reassign it so progress continues. -Need Help? -Use GitHub issues for bugs, enhancements, and scoped task discussion. -Use pull request comments for implementation-specific review discussion. -For security-sensitive reports, do not use public issues. Follow SECURITY.md. -Thank you for helping make SecuScan more useful, safer, and more welcoming to new contributors. -PR Size & Generated Artifacts -To maintain a clean commit history and make reviews manageable, we use a lightweight, advisory GitHub Actions workflow on all Pull Requests. This workflow will log a warning in the Actions tab but will not fail your CI build. -Never commit these auto-generated paths: + +* Initial maintainer response: within 3 business days +* Follow-up review: within 2–4 business days + +Large or security-sensitive PRs may take longer. + +If a PR has been inactive for more than a week, a polite follow-up comment is acceptable. + +--- + +# Review Etiquette + +* Be kind, specific, and technical +* Focus feedback on code/docs/behavior +* Update the same PR when changes are requested +* Inactive claimed issues may be reassigned + +--- + +# Need Help? + +* Use GitHub Issues for: + + * Bugs + * Enhancements + * Task discussion + +* Use PR comments for implementation-specific review discussion + +For security-sensitive reports, follow `SECURITY.md`. + +--- + +# PR Size & Generated Artifacts + +We use an advisory GitHub Actions workflow to help maintain manageable PR sizes. + +Never commit these generated paths: + +```text frontend/dist/ frontend/playwright-report/ frontend/test-results/ frontend/.vite/ .vite/deps/ -If the CI workflow flags your PR for containing these folders, you can remove them from your Git history and ensure they are ignored by running: -code -Bash +``` + +If CI flags these folders, remove them using: + +```bash git rm -r --cached frontend/playwright-report/ frontend/test-results/ frontend/dist/ + echo 'frontend/dist/' >> .gitignore echo 'frontend/playwright-report/' >> .gitignore echo 'frontend/test-results/' >> .gitignore +``` + +--- + +Thank you for helping make SecuScan more useful, safer, and more welcoming to contributors. From e537a49ea9adcdf167697a613033e1247c4ee16b Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Thu, 28 May 2026 22:28:55 +0530 Subject: [PATCH 05/12] Update pr-size-warning.yml --- .github/workflows/pr-size-warning.yml | 34 +++++++++------------------ 1 file changed, 11 insertions(+), 23 deletions(-) diff --git a/.github/workflows/pr-size-warning.yml b/.github/workflows/pr-size-warning.yml index fa7f8267..0def544b 100644 --- a/.github/workflows/pr-size-warning.yml +++ b/.github/workflows/pr-size-warning.yml @@ -12,55 +12,43 @@ jobs: runs-on: ubuntu-latest env: GH_TOKEN: ${{ github.token }} - # Define thresholds here so they are easily adjustable MAX_FILES: 50 MAX_LINES: 1000 steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Analyze PR Diffs and Artifacts - id: analyze + - name: Analyze PR Size and Artifacts run: | PR_NUMBER=${{ github.event.pull_request.number }} - - # Extract stats directly from GitHub event payload + CHANGED_FILES=${{ github.event.pull_request.changed_files }} ADDITIONS=${{ github.event.pull_request.additions }} DELETIONS=${{ github.event.pull_request.deletions }} - CHANGED_FILES=${{ github.event.pull_request.changed_files }} TOTAL_LINES=$((ADDITIONS + DELETIONS)) - - echo "PR Stats: $CHANGED_FILES files changed, $ADDITIONS additions, $DELETIONS deletions." - # Fetch changed file paths via GitHub CLI - FILES=$(gh pr view $PR_NUMBER --json files --jq '.files[].path') + echo "PR Stats: $CHANGED_FILES files changed, $ADDITIONS additions, $DELETIONS deletions." WARNINGS="" # 1. Check for oversized diffs if [ "$CHANGED_FILES" -gt "$MAX_FILES" ] || [ "$TOTAL_LINES" -gt "$MAX_LINES" ]; then MSG="PR is unusually large ($CHANGED_FILES files, $TOTAL_LINES lines changed). The advisory threshold is $MAX_FILES files or $MAX_LINES lines." - echo "::warning title=Large PR Detected::$MSG Consider breaking this into smaller PRs to help reviewers." + echo "::warning title=Large PR Detected::$MSG Consider splitting this into smaller PRs." WARNINGS="${WARNINGS}- ⚠️ **Large PR Detected:** $MSG\n" fi - # 2. Check for generated artifact directories - # The regex specifically looks for paths containing these directory names + # 2. Check for generated artifact directories using gh cli + FILES=$(gh pr view $PR_NUMBER --repo ${{ github.repository }} --json files --jq '.files[].path') + if echo "$FILES" | grep -q -E "playwright-report/|test-results/"; then - MSG="PR contains generated testing artifacts (e.g., 'playwright-report/' or 'test-results/')." - echo "::warning title=Generated Artifacts Included::$MSG Please remove them from your commits." + MSG="PR contains generated testing artifacts (playwright-report/ or test-results/). Please remove them from your commits." + echo "::warning title=Generated Artifacts Included::$MSG" WARNINGS="${WARNINGS}- 🚫 **Generated Artifacts Detected:** $MSG\n" fi - # 3. Output to GitHub Step Summary for easy visibility + # 3. Output to GitHub Step Summary if [ -n "$WARNINGS" ]; then echo "### ⚠️ PR Review Advisory" >> $GITHUB_STEP_SUMMARY echo -e "$WARNINGS" >> $GITHUB_STEP_SUMMARY - echo "> _This is an advisory warning to assist reviewers and will not fail your CI build._" >> $GITHUB_STEP_SUMMARY + echo "> _This is an advisory warning to assist reviewers. It will not fail your CI build._" >> $GITHUB_STEP_SUMMARY else echo "### ✅ PR Size and Content Check Passed" >> $GITHUB_STEP_SUMMARY echo "No unusually large diffs or accidentally committed artifacts detected." >> $GITHUB_STEP_SUMMARY fi - - # Force a successful exit (0) so the CI check always stays green (Advisory only) - exit 0 From 7164a86a838ca92126bdbc5981aa257fb129653d Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Thu, 28 May 2026 23:02:14 +0530 Subject: [PATCH 06/12] Update pr-size-warning.yml --- .github/workflows/pr-size-warning.yml | 61 ++++++++++++++++++++------- 1 file changed, 45 insertions(+), 16 deletions(-) diff --git a/.github/workflows/pr-size-warning.yml b/.github/workflows/pr-size-warning.yml index 0def544b..4b696baf 100644 --- a/.github/workflows/pr-size-warning.yml +++ b/.github/workflows/pr-size-warning.yml @@ -1,3 +1,4 @@ +```yaml name: PR Size and Artifact Check on: @@ -10,10 +11,12 @@ permissions: jobs: check-pr-size: runs-on: ubuntu-latest + env: GH_TOKEN: ${{ github.token }} MAX_FILES: 50 MAX_LINES: 1000 + steps: - name: Analyze PR Size and Artifacts run: | @@ -23,32 +26,58 @@ jobs: DELETIONS=${{ github.event.pull_request.deletions }} TOTAL_LINES=$((ADDITIONS + DELETIONS)) - echo "PR Stats: $CHANGED_FILES files changed, $ADDITIONS additions, $DELETIONS deletions." + echo "PR Stats:" + echo "- Files changed: $CHANGED_FILES" + echo "- Additions: $ADDITIONS" + echo "- Deletions: $DELETIONS" + echo "- Total lines changed: $TOTAL_LINES" WARNINGS="" - # 1. Check for oversized diffs + # Check for oversized PRs if [ "$CHANGED_FILES" -gt "$MAX_FILES" ] || [ "$TOTAL_LINES" -gt "$MAX_LINES" ]; then - MSG="PR is unusually large ($CHANGED_FILES files, $TOTAL_LINES lines changed). The advisory threshold is $MAX_FILES files or $MAX_LINES lines." - echo "::warning title=Large PR Detected::$MSG Consider splitting this into smaller PRs." - WARNINGS="${WARNINGS}- ⚠️ **Large PR Detected:** $MSG\n" + MSG="PR is unusually large ($CHANGED_FILES files, $TOTAL_LINES lines changed). Advisory threshold: $MAX_FILES files or $MAX_LINES lines." + + echo "::warning title=Large PR Detected::$MSG" + + WARNINGS="${WARNINGS} +- ⚠️ **Large PR Detected** + - $MSG + - Consider splitting this PR into smaller reviewable changes. +" fi - # 2. Check for generated artifact directories using gh cli - FILES=$(gh pr view $PR_NUMBER --repo ${{ github.repository }} --json files --jq '.files[].path') + # Check for generated artifact directories + FILES=$(gh pr view "$PR_NUMBER" \ + --repo "${{ github.repository }}" \ + --json files \ + --jq '.files[].path') + + if echo "$FILES" | grep -qE 'playwright-report/|test-results/'; then + MSG="Generated testing artifacts detected (playwright-report/ or test-results/). Please remove them from commits." - if echo "$FILES" | grep -q -E "playwright-report/|test-results/"; then - MSG="PR contains generated testing artifacts (playwright-report/ or test-results/). Please remove them from your commits." echo "::warning title=Generated Artifacts Included::$MSG" - WARNINGS="${WARNINGS}- 🚫 **Generated Artifacts Detected:** $MSG\n" + + WARNINGS="${WARNINGS} +- 🚫 **Generated Artifacts Detected** + - $MSG +" fi - # 3. Output to GitHub Step Summary + # Publish GitHub Step Summary if [ -n "$WARNINGS" ]; then - echo "### ⚠️ PR Review Advisory" >> $GITHUB_STEP_SUMMARY - echo -e "$WARNINGS" >> $GITHUB_STEP_SUMMARY - echo "> _This is an advisory warning to assist reviewers. It will not fail your CI build._" >> $GITHUB_STEP_SUMMARY + { + echo "## ⚠️ PR Review Advisory" + echo + echo "$WARNINGS" + echo + echo "> This workflow is advisory only and will not fail CI." + } >> "$GITHUB_STEP_SUMMARY" else - echo "### ✅ PR Size and Content Check Passed" >> $GITHUB_STEP_SUMMARY - echo "No unusually large diffs or accidentally committed artifacts detected." >> $GITHUB_STEP_SUMMARY + { + echo "## ✅ PR Size and Content Check Passed" + echo + echo "No unusually large diffs or generated artifacts detected." + } >> "$GITHUB_STEP_SUMMARY" fi +``` From 990d684791d1e0c15956b4e55e940d208c2cad2c Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Thu, 28 May 2026 23:20:42 +0530 Subject: [PATCH 07/12] docs: revert unrelated formatting churn in CONTRIBUTING.md --- CONTRIBUTING.md | 280 ++++++++++++++++++++++++------------------------ 1 file changed, 138 insertions(+), 142 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a19037a..9c4979cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ SecuScan is built for learning, defensive security workflows, and ethical testin --- -# Before You Start +## Before You Start * Start with a small, reviewable task if this is your first contribution. * Read `README.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` before opening a pull request. @@ -16,7 +16,7 @@ SecuScan is built for learning, defensive security workflows, and ethical testin --- -# Good First Contribution Areas +## Good First Contribution Areas * Documentation fixes, setup clarification, and onboarding polish * Frontend UX improvements in `frontend/src` @@ -58,7 +58,7 @@ This starts: * Backend: `http://127.0.0.1:8000` * Frontend: `http://127.0.0.1:5173` -* API Docs: `http://127.0.0.1:8000/docs` +* API docs: `http://127.0.0.1:8000/docs` --- @@ -66,7 +66,7 @@ This starts: ## Backend -Python version: `python3` below must resolve to `3.11+`. +Python version: `python3` below must resolve to `3.11` or newer. Check version: @@ -80,12 +80,11 @@ If your system default is older, substitute the full path (e.g. `python3.11`) or PYTHON=/path/to/python3.11 ./setup.sh ``` -### Setup Commands +### Backend Commands ```bash python3 -m venv venv source venv/bin/activate - pip install -r backend/requirements.txt pip install -r backend/requirements-dev.txt @@ -101,7 +100,6 @@ python3 -m uvicorn backend.secuscan.main:app \ ```bash cd frontend - npm install npm run dev -- --host 127.0.0.1 --port 5173 ``` @@ -112,8 +110,6 @@ npm run dev -- --host 127.0.0.1 --port 5173 This section explains how to run the backend test suite from a fresh checkout without touching the main development environment. ---- - ## 1. Prerequisites Make sure your machine has Python `3.11+`. @@ -122,7 +118,7 @@ Make sure your machine has Python `3.11+`. python3 --version ``` -If the version shown is older than `3.11`, substitute the full path to a compatible interpreter (e.g. `python3.11`) wherever `python3` appears below. +If older than `3.11`, use `python3.11` or `python3.12` explicitly. --- @@ -136,14 +132,9 @@ From the repo root: This script automatically: -* Creates an isolated virtual environment at `venv_tests/` -* Installs dependencies from: - - * `backend/requirements.txt` - * `backend/requirements-dev.txt` -* Runs the full `testing/backend/` suite with `pytest` - -You do not need to activate any virtual environment manually. +* Creates isolated environment `venv_tests/` +* Installs dependencies +* Runs all tests in `testing/backend/` --- @@ -157,54 +148,60 @@ python -m pytest testing/backend/unit/test_models.py -v deactivate ``` -Replace `test_models.py` with whichever file you want to target. +Replace `test_models.py` with your desired test file. -* Unit tests: `testing/backend/unit/` -* Integration tests: `testing/backend/integration/` +Unit tests: -> Run `./testing/test_python.sh` at least once before using this shortcut. +```text +testing/backend/unit/ +``` + +Integration tests: + +```text +testing/backend/integration/ +``` --- ## 4. Requirements Files -| File | Purpose | -| ------------------------------ | --------------------------------- | -| `backend/requirements.txt` | Core runtime dependencies | -| `backend/requirements-dev.txt` | Test and development dependencies | - -Both files must be installed for the test suite to run correctly. +| File | Purpose | +| ------------------------------ | --------------------- | +| `backend/requirements.txt` | Runtime dependencies | +| `backend/requirements-dev.txt` | Test/dev dependencies | --- ## 5. Common Dependency Issues -### `ModuleNotFoundError` +### ModuleNotFoundError -The `venv_tests/` environment may be outdated. - -Fix: +Delete `venv_tests/` and rerun: ```bash -rm -rf venv_tests ./testing/test_python.sh ``` ---- +### Wrong Python Version -### `python3` Resolves to an Older Version +```bash +python3 --version +``` -Check: +Use: ```bash -python3 --version +python3.11 ``` -Use `python3.11` or `python3.12` explicitly if needed. +or ---- +```bash +python3.12 +``` -### Permission Denied on Test Script +### Permission Denied ```bash chmod +x testing/test_python.sh @@ -214,30 +211,46 @@ chmod +x testing/test_python.sh # Project Layout -| Path | Purpose | -| ------------------ | ------------------------------------------------ | -| `backend/secuscan` | FastAPI routes, workflows, validation, reporting | -| `frontend/src` | React pages, scan flows, settings, tests | -| `plugins` | Plugin metadata and parser helpers | -| `testing/backend` | Backend unit and integration coverage | -| `frontend/testing` | Frontend unit and Playwright coverage | -| `.github` | Templates and CI workflows | +* `backend/secuscan` + + * FastAPI routes, execution logic, workflows, validation, vault, reporting +* `frontend/src` + + * React pages, scan flows, settings, tests +* `plugins` + + * Plugin metadata, parser code, helpers +* `testing/backend` + + * Backend unit/integration tests +* `frontend/testing` + + * Frontend tests +* `.github` + + * Issue templates, PR templates, CI workflows --- # Development Workflow -1. Fork the repository and create a branch from `main` -2. Pick an issue or open one before starting large work -3. Keep changes focused and reviewable -4. Update tests and docs when behavior changes -5. Open a PR with: +1. Fork repository and create a branch from `main` +2. Pick an issue or open one before large work +3. Keep changes focused +4. Recommended PR size: + + * Under 50 files + * Under 1,000 lines changed +5. Update tests/docs when behavior changes +6. Open PR with: * Clear description * Linked issue * Screenshots for UI changes -### Example Branch Names +--- + +## Example Branch Names ```text docs/improve-contributing-guide @@ -249,7 +262,7 @@ feat/plugin-validation # Pull Request Format -Recommended PR title format: +Recommended PR titles: ```text docs: improve contributing guide @@ -259,23 +272,17 @@ feat(frontend): add scan empty state Your PR should include: -* Problem being solved +* Problem description * Summary of approach -* Linked issue references -* Tests you ran -* Screenshots/recordings for UI changes -* Notes about docs, migrations, env vars, or breaking behavior - -Try to keep one PR focused on one problem. +* Linked issues (`Closes #123`) +* Tests run +* Screenshots/recordings for UI +* Docs/migration/environment notes if relevant --- # Contribution Scoring -Every merged PR can be scored for GSSoC using labels applied by maintainers. - ---- - ## Difficulty Labels * `level:beginner` @@ -283,15 +290,11 @@ Every merged PR can be scored for GSSoC using labels applied by maintainers. * `level:advanced` * `level:critical` ---- - ## Quality Labels * `quality:clean` * `quality:exceptional` ---- - ## Type Bonus Labels * `type:docs` @@ -305,8 +308,6 @@ Every merged PR can be scored for GSSoC using labels applied by maintainers. * `type:bug` * `type:feature` ---- - ## Validation Labels * `gssoc:approved` @@ -314,9 +315,26 @@ Every merged PR can be scored for GSSoC using labels applied by maintainers. * `gssoc:spam` * `gssoc:ai-slop` +Mentor credit: + +```text +mentor:username +``` + --- -## Contributor Score Formula +# Contributor Points + +| Label | Points | +| --------------------- | -----: | +| `level:beginner` | 20 pts | +| `level:intermediate` | 35 pts | +| `level:advanced` | 55 pts | +| `level:critical` | 80 pts | +| `quality:clean` | x1.2 | +| `quality:exceptional` | x1.5 | + +Formula: ```text ((difficulty × quality) + type bonus) @@ -324,7 +342,18 @@ Every merged PR can be scored for GSSoC using labels applied by maintainers. --- -## Mentor Score Formula +# Mentor Points + +| Label | Points | +| --------------------- | -----: | +| `level:beginner` | 10 pts | +| `level:intermediate` | 20 pts | +| `level:advanced` | 30 pts | +| `level:critical` | 50 pts | +| `quality:clean` | +5 | +| `quality:exceptional` | +10 | + +Formula: ```text (base points + quality bonus) @@ -340,7 +369,7 @@ Preferred format: type(scope): short summary ``` -### Examples +Examples: ```text feat(frontend): add task result empty state @@ -348,7 +377,7 @@ fix(backend): reject invalid workflow payloads docs(readme): clarify local setup steps ``` -### Recommended Commit Types +Recommended types: * `feat` * `fix` @@ -357,46 +386,34 @@ docs(readme): clarify local setup steps * `refactor` * `chore` -### Guidelines - -* Use imperative mood (`add`, `fix`, `update`) -* Keep subject line under ~72 characters -* Avoid vague messages like: +Guidelines: - * `changes` - * `update code` - * `fix stuff` +* Use imperative mood +* Keep subject under ~72 chars +* Avoid vague messages --- # Licensing Expectations -By submitting a contribution, you agree that your changes can be distributed under the repository's MIT License. +By contributing, you agree changes may be distributed under the MIT License. -Please avoid: +Avoid: * Copying incompatible licensed code -* Adding unverified assets/snippets/templates -* Introducing dependencies without checking license compatibility - -If unsure, ask in the issue or PR before merging. +* Adding assets without permission checks +* Adding dependencies without license validation --- # Test Expectations -Run the smallest relevant test set for your change. - ---- - ## Backend Tests ```bash ./testing/test_python.sh ``` ---- - ## Frontend Unit Tests ```bash @@ -404,8 +421,6 @@ cd frontend npm run test ``` ---- - ## Frontend Production Build ```bash @@ -413,16 +428,12 @@ cd frontend npm run build ``` ---- - ## Backend API Smoke Tests ```bash ./testing/test_backend.sh ``` ---- - ## Optional Frontend E2E ```bash @@ -437,32 +448,26 @@ npm run e2e ## Python * Follow PEP 8 -* Prefer explicit, readable code -* Use type hints where useful -* Prefer small focused functions - ---- +* Prefer readable code +* Use type hints when useful +* Keep validation close to boundaries ## Frontend -* Use TypeScript and functional React components +* Use TypeScript + functional React * Keep logic readable * Reuse shared UI patterns -* Include accessible labels and error handling - ---- +* Include accessibility handling ## Tests * Add/update tests when behavior changes -* Keep fixtures focused and understandable - ---- +* Keep fixtures simple ## Docs -* Update contributor-facing docs when setup/workflow changes -* Prefer concrete examples over generic instructions +* Update contributor docs when setup/workflow changes +* Prefer concrete examples --- @@ -470,43 +475,41 @@ npm run e2e Typical expectations: -* Initial maintainer response: within 3 business days -* Follow-up review: within 2–4 business days +* Initial review: within 3 business days +* Follow-up review: 2–4 business days -Large or security-sensitive PRs may take longer. +Large/security-sensitive PRs may take longer. -If a PR has been inactive for more than a week, a polite follow-up comment is acceptable. +If no response after a week, a polite follow-up is okay. --- # Review Etiquette -* Be kind, specific, and technical -* Focus feedback on code/docs/behavior -* Update the same PR when changes are requested +* Be kind and technical +* Focus on code/docs/behavior +* Update same PR when changes requested * Inactive claimed issues may be reassigned --- # Need Help? -* Use GitHub Issues for: - - * Bugs - * Enhancements - * Task discussion +* Use GitHub issues for bugs/features +* Use PR comments for implementation discussion +* For security reports, follow `SECURITY.md` -* Use PR comments for implementation-specific review discussion +--- -For security-sensitive reports, follow `SECURITY.md`. +Thank you for helping make SecuScan more useful, safer, and more welcoming to contributors. --- -# PR Size & Generated Artifacts +# Frontend Generated Artifacts -We use an advisory GitHub Actions workflow to help maintain manageable PR sizes. +A lightweight GitHub Action warns if generated folders are committed. -Never commit these generated paths: +Never commit: ```text frontend/dist/ @@ -516,16 +519,9 @@ frontend/.vite/ .vite/deps/ ``` -If CI flags these folders, remove them using: +If CI fails: ```bash -git rm -r --cached frontend/playwright-report/ frontend/test-results/ frontend/dist/ - +git rm --cached echo 'frontend/dist/' >> .gitignore -echo 'frontend/playwright-report/' >> .gitignore -echo 'frontend/test-results/' >> .gitignore ``` - ---- - -Thank you for helping make SecuScan more useful, safer, and more welcoming to contributors. From bee1e057e0c3473916f2e7360411ae210bbe972f Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Thu, 28 May 2026 23:33:34 +0530 Subject: [PATCH 08/12] Update pr-size-warning.yml --- .github/workflows/pr-size-warning.yml | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/.github/workflows/pr-size-warning.yml b/.github/workflows/pr-size-warning.yml index 4b696baf..8262b5e2 100644 --- a/.github/workflows/pr-size-warning.yml +++ b/.github/workflows/pr-size-warning.yml @@ -1,4 +1,3 @@ -```yaml name: PR Size and Artifact Check on: @@ -41,10 +40,10 @@ jobs: echo "::warning title=Large PR Detected::$MSG" WARNINGS="${WARNINGS} -- ⚠️ **Large PR Detected** - - $MSG - - Consider splitting this PR into smaller reviewable changes. -" + - ⚠️ **Large PR Detected** + - $MSG + - Consider splitting this PR into smaller reviewable changes. + " fi # Check for generated artifact directories @@ -59,9 +58,9 @@ jobs: echo "::warning title=Generated Artifacts Included::$MSG" WARNINGS="${WARNINGS} -- 🚫 **Generated Artifacts Detected** - - $MSG -" + - 🚫 **Generated Artifacts Detected** + - $MSG + " fi # Publish GitHub Step Summary @@ -80,4 +79,3 @@ jobs: echo "No unusually large diffs or generated artifacts detected." } >> "$GITHUB_STEP_SUMMARY" fi -``` From 90824d605f4d56c950b7c89769d879878bbc6e12 Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Thu, 28 May 2026 23:34:03 +0530 Subject: [PATCH 09/12] Update CONTRIBUTING.md --- CONTRIBUTING.md | 525 ++---------------------------------------------- 1 file changed, 18 insertions(+), 507 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c4979cf..38bed915 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,524 +4,35 @@ Thank you for contributing to SecuScan. This project is open to first-time contr SecuScan is built for learning, defensive security workflows, and ethical testing. Please keep all contributions aligned with authorized, consent-based use. ---- - ## Before You Start -* Start with a small, reviewable task if this is your first contribution. -* Read `README.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` before opening a pull request. -* Read the repository `LICENSE` so you understand how contributions are distributed. -* If you want to work on a larger feature, open or comment on an issue first so effort does not overlap. -* If you are contributing through GSSoC, mention that in the issue or pull request so maintainers can guide scope and review expectations. - ---- +- Start with a small, reviewable task if this is your first contribution. +- Read [README.md](README.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md) before opening a pull request. +- Read the repository [LICENSE](LICENSE) so you understand how contributions are distributed. +- If you want to work on a larger feature, open or comment on an issue first so effort does not overlap. +- If you are contributing through GSSoC, mention that in the issue or pull request so maintainers can guide scope and review expectations. ## Good First Contribution Areas -* Documentation fixes, setup clarification, and onboarding polish -* Frontend UX improvements in `frontend/src` -* Backend validation, test coverage, and API consistency in `backend/secuscan` -* Plugin metadata cleanup and parser improvements in `plugins` -* CI, test reliability, and developer experience - -When issue labels are available, look for tags such as: +- Documentation fixes, setup clarification, and onboarding polish +- Frontend UX improvements in `frontend/src` +- Backend validation, test coverage, and API consistency in `backend/secuscan` +- Plugin metadata cleanup and parser improvements in `plugins` +- CI, test reliability, and developer experience -* `good first issue` -* `documentation` -* `frontend` -* `backend` -* `plugin` -* `help wanted` -* `gssoc` +When issue labels are available, look for tags such as `good first issue`, `documentation`, `frontend`, `backend`, `plugin`, `help wanted`, or `gssoc`. ---- +## Local Setup -# Local Setup +### Prerequisites -## Prerequisites +- Python `3.11+` +- Node.js `20+` recommended +- `npm` +- Docker optional for plugins that depend on containerized tooling -* Python `3.11+` -* Node.js `20+` recommended -* `npm` -* Docker (optional for plugins that depend on containerized tooling) - ---- - -## Recommended Setup +### Recommended Setup ```bash ./setup.sh ./start.sh -``` - -This starts: - -* Backend: `http://127.0.0.1:8000` -* Frontend: `http://127.0.0.1:5173` -* API docs: `http://127.0.0.1:8000/docs` - ---- - -# Manual Setup - -## Backend - -Python version: `python3` below must resolve to `3.11` or newer. - -Check version: - -```bash -python3 --version -``` - -If your system default is older, substitute the full path (e.g. `python3.11`) or use: - -```bash -PYTHON=/path/to/python3.11 ./setup.sh -``` - -### Backend Commands - -```bash -python3 -m venv venv -source venv/bin/activate -pip install -r backend/requirements.txt -pip install -r backend/requirements-dev.txt - -python3 -m uvicorn backend.secuscan.main:app \ - --reload \ - --host 127.0.0.1 \ - --port 8000 -``` - ---- - -## Frontend - -```bash -cd frontend -npm install -npm run dev -- --host 127.0.0.1 --port 5173 -``` - ---- - -# Backend Testing Quickstart - -This section explains how to run the backend test suite from a fresh checkout without touching the main development environment. - -## 1. Prerequisites - -Make sure your machine has Python `3.11+`. - -```bash -python3 --version -``` - -If older than `3.11`, use `python3.11` or `python3.12` explicitly. - ---- - -## 2. Run the Full Backend Test Suite - -From the repo root: - -```bash -./testing/test_python.sh -``` - -This script automatically: - -* Creates isolated environment `venv_tests/` -* Installs dependencies -* Runs all tests in `testing/backend/` - ---- - -## 3. Run a Single Test File - -```bash -source venv_tests/bin/activate - -python -m pytest testing/backend/unit/test_models.py -v - -deactivate -``` - -Replace `test_models.py` with your desired test file. - -Unit tests: - -```text -testing/backend/unit/ -``` - -Integration tests: - -```text -testing/backend/integration/ -``` - ---- - -## 4. Requirements Files - -| File | Purpose | -| ------------------------------ | --------------------- | -| `backend/requirements.txt` | Runtime dependencies | -| `backend/requirements-dev.txt` | Test/dev dependencies | - ---- - -## 5. Common Dependency Issues - -### ModuleNotFoundError - -Delete `venv_tests/` and rerun: - -```bash -./testing/test_python.sh -``` - -### Wrong Python Version - -```bash -python3 --version -``` - -Use: - -```bash -python3.11 -``` - -or - -```bash -python3.12 -``` - -### Permission Denied - -```bash -chmod +x testing/test_python.sh -``` - ---- - -# Project Layout - -* `backend/secuscan` - - * FastAPI routes, execution logic, workflows, validation, vault, reporting -* `frontend/src` - - * React pages, scan flows, settings, tests -* `plugins` - - * Plugin metadata, parser code, helpers -* `testing/backend` - - * Backend unit/integration tests -* `frontend/testing` - - * Frontend tests -* `.github` - - * Issue templates, PR templates, CI workflows - ---- - -# Development Workflow - -1. Fork repository and create a branch from `main` -2. Pick an issue or open one before large work -3. Keep changes focused -4. Recommended PR size: - - * Under 50 files - * Under 1,000 lines changed -5. Update tests/docs when behavior changes -6. Open PR with: - - * Clear description - * Linked issue - * Screenshots for UI changes - ---- - -## Example Branch Names - -```text -docs/improve-contributing-guide -fix/task-status-api -feat/plugin-validation -``` - ---- - -# Pull Request Format - -Recommended PR titles: - -```text -docs: improve contributing guide -fix(api): validate task status input -feat(frontend): add scan empty state -``` - -Your PR should include: - -* Problem description -* Summary of approach -* Linked issues (`Closes #123`) -* Tests run -* Screenshots/recordings for UI -* Docs/migration/environment notes if relevant - ---- - -# Contribution Scoring - -## Difficulty Labels - -* `level:beginner` -* `level:intermediate` -* `level:advanced` -* `level:critical` - -## Quality Labels - -* `quality:clean` -* `quality:exceptional` - -## Type Bonus Labels - -* `type:docs` -* `type:testing` -* `type:accessibility` -* `type:performance` -* `type:security` -* `type:design` -* `type:refactor` -* `type:devops` -* `type:bug` -* `type:feature` - -## Validation Labels - -* `gssoc:approved` -* `gssoc:invalid` -* `gssoc:spam` -* `gssoc:ai-slop` - -Mentor credit: - -```text -mentor:username -``` - ---- - -# Contributor Points - -| Label | Points | -| --------------------- | -----: | -| `level:beginner` | 20 pts | -| `level:intermediate` | 35 pts | -| `level:advanced` | 55 pts | -| `level:critical` | 80 pts | -| `quality:clean` | x1.2 | -| `quality:exceptional` | x1.5 | - -Formula: - -```text -((difficulty × quality) + type bonus) -``` - ---- - -# Mentor Points - -| Label | Points | -| --------------------- | -----: | -| `level:beginner` | 10 pts | -| `level:intermediate` | 20 pts | -| `level:advanced` | 30 pts | -| `level:critical` | 50 pts | -| `quality:clean` | +5 | -| `quality:exceptional` | +10 | - -Formula: - -```text -(base points + quality bonus) -``` - ---- - -# Commit Message Conventions - -Preferred format: - -```text -type(scope): short summary -``` - -Examples: - -```text -feat(frontend): add task result empty state -fix(backend): reject invalid workflow payloads -docs(readme): clarify local setup steps -``` - -Recommended types: - -* `feat` -* `fix` -* `docs` -* `test` -* `refactor` -* `chore` - -Guidelines: - -* Use imperative mood -* Keep subject under ~72 chars -* Avoid vague messages - ---- - -# Licensing Expectations - -By contributing, you agree changes may be distributed under the MIT License. - -Avoid: - -* Copying incompatible licensed code -* Adding assets without permission checks -* Adding dependencies without license validation - ---- - -# Test Expectations - -## Backend Tests - -```bash -./testing/test_python.sh -``` - -## Frontend Unit Tests - -```bash -cd frontend -npm run test -``` - -## Frontend Production Build - -```bash -cd frontend -npm run build -``` - -## Backend API Smoke Tests - -```bash -./testing/test_backend.sh -``` - -## Optional Frontend E2E - -```bash -cd frontend -npm run e2e -``` - ---- - -# Code Style - -## Python - -* Follow PEP 8 -* Prefer readable code -* Use type hints when useful -* Keep validation close to boundaries - -## Frontend - -* Use TypeScript + functional React -* Keep logic readable -* Reuse shared UI patterns -* Include accessibility handling - -## Tests - -* Add/update tests when behavior changes -* Keep fixtures simple - -## Docs - -* Update contributor docs when setup/workflow changes -* Prefer concrete examples - ---- - -# Review Timeline - -Typical expectations: - -* Initial review: within 3 business days -* Follow-up review: 2–4 business days - -Large/security-sensitive PRs may take longer. - -If no response after a week, a polite follow-up is okay. - ---- - -# Review Etiquette - -* Be kind and technical -* Focus on code/docs/behavior -* Update same PR when changes requested -* Inactive claimed issues may be reassigned - ---- - -# Need Help? - -* Use GitHub issues for bugs/features -* Use PR comments for implementation discussion -* For security reports, follow `SECURITY.md` - ---- - -Thank you for helping make SecuScan more useful, safer, and more welcoming to contributors. - ---- - -# Frontend Generated Artifacts - -A lightweight GitHub Action warns if generated folders are committed. - -Never commit: - -```text -frontend/dist/ -frontend/playwright-report/ -frontend/test-results/ -frontend/.vite/ -.vite/deps/ -``` - -If CI fails: - -```bash -git rm --cached -echo 'frontend/dist/' >> .gitignore -``` From fe6d9aec7ce1af0ed422e2adf5682e055d970036 Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Thu, 28 May 2026 23:42:01 +0530 Subject: [PATCH 10/12] Update CONTRIBUTING.md --- CONTRIBUTING.md | 372 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 372 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 38bed915..707ad972 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,3 +36,375 @@ When issue labels are available, look for tags such as `good first issue`, `docu ```bash ./setup.sh ./start.sh +``` + +This starts: + +- Backend: `http://127.0.0.1:8000` +- Frontend: `http://127.0.0.1:5173` +- API docs: `http://127.0.0.1:8000/docs` + +### Manual Setup + +Backend: + +> **Python version:** `python3` below must resolve to 3.11 or newer. Run `python3 --version` to check. If your system default is older, substitute the full path (e.g. `python3.11`) or use `PYTHON=/path/to/python3.11 ./setup.sh` instead of the manual steps. + +```bash +python3 -m venv venv +source venv/bin/activate +pip install -r backend/requirements.txt +pip install -r backend/requirements-dev.txt +python3 -m uvicorn backend.secuscan.main:app --reload --host 127.0.0.1 --port 8000 +``` + +Frontend: + +```bash +cd frontend +npm install +npm run dev -- --host 127.0.0.1 --port 5173 +``` + +## Backend Testing Quickstart + +This section explains how to run the backend test suite from a fresh checkout +without touching the main development environment. + +### 1. Prerequisites + +Make sure your machine has Python 3.11 or newer before running any test commands. + +```bash +python3 --version +``` + +If the version shown is older than 3.11, substitute the full path to a compatible +interpreter (e.g. `python3.11`) wherever `python3` appears below. + +### 2. Run the Full Backend Test Suite + +From the repo root, run: + +```bash +./testing/test_python.sh +``` + +This script handles everything automatically: + +- Creates an isolated virtual environment at `venv_tests/` (separate from your + dev environment) +- Installs all required dependencies from `backend/requirements.txt` and + `backend/requirements-dev.txt` +- Runs the full `testing/backend/` suite with pytest in quiet mode + +You do not need to activate any virtual environment manually for this command. + +### 3. Run a Single Test File + +When you want faster feedback on one specific file, activate the test virtual +environment and call pytest directly. Run these commands from the repo root: + +```bash +source venv_tests/bin/activate +python -m pytest testing/backend/unit/test_models.py -v +deactivate +``` + +Replace `test_models.py` with whichever file you want to target. All unit tests +live under `testing/backend/unit/` and integration tests live under +`testing/backend/integration/`. + +> **Note:** Run `./testing/test_python.sh` at least once before using this +> shortcut so that `venv_tests/` exists and dependencies are installed. + +### 4. Where Requirements Files Live + +| File | Purpose | +|---|---| +| `backend/requirements.txt` | Core runtime dependencies | +| `backend/requirements-dev.txt` | Test and development dependencies (pytest, etc.) | + +Both files must be installed for the test suite to run correctly. The +`./testing/test_python.sh` script installs both automatically. + +### 5. Common Dependency Issues + +- **`ModuleNotFoundError` on any import** — the `venv_tests/` environment may + be outdated. Delete it and re-run `./testing/test_python.sh` to rebuild from + scratch. +- **`python3` resolves to an older version** — check with `python3 --version`. + Use `python3.11` or `python3.12` explicitly if needed. +- **Permission denied on `./testing/test_python.sh`** — make it executable + first with `chmod +x testing/test_python.sh`. + +## Project Layout + +- `backend/secuscan`: FastAPI routes, execution logic, workflows, validation, vault, and reporting +- `frontend/src`: React pages, app shell, scan flows, settings, and tests +- `plugins`: plugin metadata, parser code, and tool-specific helpers +- `testing/backend`: backend unit and integration coverage +- `frontend/testing`: frontend unit and Playwright coverage +- `.github`: issue templates, PR template, and CI workflow + +## Development Workflow + +1. Fork the repository and create a branch from `main`. +2. Pick an issue or open one before starting large work. +3. Keep the change focused. Small PRs get reviewed much faster than broad rewrites. +4. **Mind your PR size.** We recommend keeping PRs under **50 changed files** and **1,000 lines of total changes**. An automated GitHub Action will warn you if your PR exceeds this. +5. Update tests and docs when behavior changes. +6. Open a pull request with a clear description, linked issue, and screenshots for UI changes. + +Branch names can be simple and descriptive, such as: + +- `docs/improve-contributing-guide` +- `fix/task-status-api` +- `feat/plugin-validation` + +## Pull Request Format + +Please follow the repository PR template and keep the submission easy to review. + +Recommended PR title format: + +- `docs: improve contributing guide` +- `fix(api): validate task status input` +- `feat(frontend): add scan empty state` + +Your PR should include: + +- A short description of the problem being solved +- A summary of the approach you took +- Linked issue references such as `Closes #123` or `Related to #123` +- A clear list of tests you ran +- Screenshots or short recordings for visible UI changes +- Notes about documentation, migrations, environment variables, or breaking behavior when relevant + +Try to keep one pull request focused on one problem. If a change touches unrelated areas, split it into separate PRs when possible. + +## Contribution Scoring + +Every merged pull request can be scored for GSSoC using labels applied by the project admin or mentor. The scoring engine reads these labels after the PR is merged, so contributors should focus on clear scope, good implementation, and complete review notes rather than self-assigning score labels. + +### Labels the Admin Applies + +Each merged PR should have one difficulty label: + +- `level:beginner` +- `level:intermediate` +- `level:advanced` +- `level:critical` + +Optional quality labels can increase the contributor score: + +- `quality:clean` +- `quality:exceptional` + +Optional type bonus labels can describe the work category: + +- `type:docs` +- `type:testing` +- `type:accessibility` +- `type:performance` +- `type:security` +- `type:design` +- `type:refactor` +- `type:devops` +- `type:bug` +- `type:feature` + +Validation labels are decided by the admin: + +- `gssoc:approved` +- `gssoc:invalid` +- `gssoc:spam` +- `gssoc:ai-slop` + +Use `mentor:username` to credit the reviewing mentor with points for that PR. + +### Contributor Points per PR + +| Label | Points | +| --- | ---: | +| `level:beginner` | 20 pts | +| `level:intermediate` | 35 pts | +| `level:advanced` | 55 pts | +| `level:critical` | 80 pts | +| `quality:clean` | x 1.2 multiplier | +| `quality:exceptional` | x 1.5 multiplier | + +Contributor score formula: + +```text +((difficulty x quality) + type bonus) +``` + +### Mentor Points per Reviewed PR + +| Label | Points | +| --- | ---: | +| `level:beginner` | 10 pts | +| `level:intermediate` | 20 pts | +| `level:advanced` | 30 pts | +| `level:critical` | 50 pts | +| `quality:clean` | +5 pts bonus | +| `quality:exceptional` | +10 pts bonus | + +Mentor score formula: + +```text +(base points + quality bonus) +``` + +## Commit Message Conventions + +Use clear, imperative commit messages. Keep the first line short and descriptive. + +Preferred format: + +```text +type(scope): short summary +``` + +Examples: + +- `feat(frontend): add task result empty state` +- `fix(backend): reject invalid workflow payloads` +- `docs(readme): clarify local setup steps` + +Recommended commit types: + +- `feat` +- `fix` +- `docs` +- `test` +- `refactor` +- `chore` + +Guidelines: + +- Use the imperative mood, such as `add`, `fix`, `update`, or `remove` +- Keep the subject line around 72 characters or fewer +- Reference the issue number in the commit body when useful +- Avoid vague messages like `changes`, `update code`, or `fix stuff` + +## Licensing Expectations + +By submitting a contribution, you agree that your changes can be distributed under the repository's MIT License. + +Please avoid: + +- Copying code from sources with incompatible licenses +- Adding assets, snippets, or templates without checking reuse permissions +- Introducing third-party dependencies without confirming their license is acceptable for this project + +If you are unsure about a dependency or asset license, ask in the issue or pull request before merging it into the project. + +## Test Expectations + +Run the smallest relevant test set for your change, then broaden if needed. + +Backend tests: + +```bash +./testing/test_python.sh +``` + +Frontend unit tests: + +```bash +cd frontend +npm run test +``` + +Frontend production build: + +```bash +cd frontend +npm run build +``` + +Backend API smoke tests with the server running: + +```bash +./testing/test_backend.sh +``` + +Optional frontend E2E: + +```bash +cd frontend +npm run e2e +``` + +What we expect before review: + +- Backend changes should run `./testing/test_python.sh` +- Frontend changes should run `npm run test` and `npm run build` in `frontend/` +- API or behavior changes should include either automated coverage or a short manual verification note +- Docs-only changes usually do not need full test runs, but please say that clearly in the PR +- If you could not run a recommended test, mention what you skipped and why + +## Code Style + +Please match the conventions already used in the repo instead of introducing a new style. + +- Python: + - Follow PEP 8 and prefer explicit, readable code + - Use type hints where they improve clarity + - Keep validation close to request and model boundaries + - Prefer small functions over large, multi-purpose blocks +- Frontend: + - Use TypeScript and functional React components + - Keep component logic readable and avoid unnecessary abstraction + - Reuse shared UI patterns when they already exist + - Include accessible labels, states, and error handling for form changes +- Tests: + - Add or update tests when behavior changes + - Keep fixtures focused and easy to understand +- Docs: + - Update contributor-facing docs when setup, workflow, or commands change + - Prefer concrete examples over generic instructions + +## Review Timeline + +Reviews are handled on a best-effort basis. + +Typical expectations: + +- Initial maintainer response: within 3 business days for small, clearly scoped PRs +- Follow-up review after updates: usually within 2 to 4 business days +- Large PRs, release periods, or security-sensitive work may take longer + +If a PR has been quiet for more than a week, a polite follow-up comment is completely fine. + +## Review Etiquette + +- Be kind, specific, and technical in review comments. +- Assume good intent and focus feedback on the code, docs, or behavior. +- If a maintainer asks for changes, update the PR instead of opening a new one unless requested. +- If you become inactive on a claimed issue, maintainers may reassign it so progress continues. + +## Need Help? + +- Use GitHub issues for bugs, enhancements, and scoped task discussion. +- Use pull request comments for implementation-specific review discussion. +- For security-sensitive reports, do not use public issues. Follow [SECURITY.md](SECURITY.md). + +Thank you for helping make SecuScan more useful, safer, and more welcoming to new contributors. +## Frontend Generated Artifacts +A lightweight GitHub Action will warn you if your PR contains generated folders. This is advisory and will not fail your CI build. + +Never commit these auto-generated paths: +- `frontend/dist/` +- `frontend/playwright-report/` +- `frontend/test-results/` +- `frontend/.vite/` +- `.vite/deps/` + +If CI fails, run: +```bash +git rm --cached +echo 'frontend/dist/' >> .gitignore +``` From 89a1c61309defa8906583ff99e78cae904864a4b Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Sat, 30 May 2026 12:41:17 +0530 Subject: [PATCH 11/12] Update CONTRIBUTING.md --- CONTRIBUTING.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 707ad972..151a8145 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -152,9 +152,8 @@ Both files must be installed for the test suite to run correctly. The 1. Fork the repository and create a branch from `main`. 2. Pick an issue or open one before starting large work. 3. Keep the change focused. Small PRs get reviewed much faster than broad rewrites. -4. **Mind your PR size.** We recommend keeping PRs under **50 changed files** and **1,000 lines of total changes**. An automated GitHub Action will warn you if your PR exceeds this. -5. Update tests and docs when behavior changes. -6. Open a pull request with a clear description, linked issue, and screenshots for UI changes. +4. Update tests and docs when behavior changes. +5. Open a pull request with a clear description, linked issue, and screenshots for UI changes. Branch names can be simple and descriptive, such as: @@ -183,6 +182,12 @@ Your PR should include: Try to keep one pull request focused on one problem. If a change touches unrelated areas, split it into separate PRs when possible. +### PR Size and Generated Artifacts + +To keep reviews manageable, an automated workflow will post an advisory warning if a PR exceeds **50 changed files** or **1,000 total lines**. We encourage splitting unusually large changes into smaller, focused pull requests. + +Additionally, please ensure you never commit auto-generated artifacts (such as `playwright-report/`, `test-results/`, `dist/`, or `.vite/`). The workflow will flag these if they are accidentally included. If this happens, remove them using `git rm --cached -r `. + ## Contribution Scoring Every merged pull request can be scored for GSSoC using labels applied by the project admin or mentor. The scoring engine reads these labels after the PR is merged, so contributors should focus on clear scope, good implementation, and complete review notes rather than self-assigning score labels. @@ -394,7 +399,6 @@ If a PR has been quiet for more than a week, a polite follow-up comment is compl Thank you for helping make SecuScan more useful, safer, and more welcoming to new contributors. ## Frontend Generated Artifacts -A lightweight GitHub Action will warn you if your PR contains generated folders. This is advisory and will not fail your CI build. Never commit these auto-generated paths: - `frontend/dist/` @@ -407,4 +411,3 @@ If CI fails, run: ```bash git rm --cached echo 'frontend/dist/' >> .gitignore -``` From 9bf8f8f68d73c1b82c2e376ddb7ee078aceb81c5 Mon Sep 17 00:00:00 2001 From: CoderPrateek971 Date: Sat, 30 May 2026 12:42:07 +0530 Subject: [PATCH 12/12] Update pr-size-warning.yml --- .github/workflows/pr-size-warning.yml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.github/workflows/pr-size-warning.yml b/.github/workflows/pr-size-warning.yml index 8262b5e2..138b43bc 100644 --- a/.github/workflows/pr-size-warning.yml +++ b/.github/workflows/pr-size-warning.yml @@ -36,9 +36,7 @@ jobs: # Check for oversized PRs if [ "$CHANGED_FILES" -gt "$MAX_FILES" ] || [ "$TOTAL_LINES" -gt "$MAX_LINES" ]; then MSG="PR is unusually large ($CHANGED_FILES files, $TOTAL_LINES lines changed). Advisory threshold: $MAX_FILES files or $MAX_LINES lines." - echo "::warning title=Large PR Detected::$MSG" - WARNINGS="${WARNINGS} - ⚠️ **Large PR Detected** - $MSG @@ -54,9 +52,7 @@ jobs: if echo "$FILES" | grep -qE 'playwright-report/|test-results/'; then MSG="Generated testing artifacts detected (playwright-report/ or test-results/). Please remove them from commits." - echo "::warning title=Generated Artifacts Included::$MSG" - WARNINGS="${WARNINGS} - 🚫 **Generated Artifacts Detected** - $MSG