🕵️ SourceAudit

A lightweight Python source auditor with a "code review clerk" aesthetic — paste in a .py file, get it graded, and actually run it, all in one place.

---

✨ Features

• 🧾 Checks source code for syntax errors, unused variables, naming convention violations, and TODO/FIXME comments
• 🔢 Turns the results into a quality score out of 10 with a rating (Excellent / Good / Fair / Needs Improvement)
• ✅ / 🚩 Gives a clear CLEARED / FLAGGED verdict — code has to actually run before quality even gets considered
• ▶️ Runs your code and shows real output, like a mini online Python editor
• 🐍 Genuine input() support — the CLI prompts your real terminal, the web app opens a synchronous browser prompt, either way your program actually gets to ask questions
• ⏱️ An infinite-loop watchdog — while True: pass and friends get stopped after a few seconds instead of freezing your terminal or the browser tab
• 🖥️ Available as both a CLI and a browser app — same logic, same results, either way
• 🌐 The web app runs entirely client-side via Pyodide (real CPython compiled to WebAssembly) — nothing is sent to a server
• 🎨 Syntax-highlighted editor, REPL-style console output, and a vintage "audit report" look
• 🌗 Light/dark mode toggle, remembers your choice and respects your system preference on first visit
• 📱 Fully responsive — phone, tablet, laptop, and large-screen layouts

---

🛠️ Technologies Used

• Python (checkers, CLI, scoring logic)
• HTML / CSS / JavaScript (web app UI)
• Pyodide (CPython in the browser via WebAssembly)
• pytest (test suite)

---

📐 How Scoring & the Verdict Work

Score starts at 10 and points are deducted:

Issue	Penalty
Syntax error	−2.5
Each unused variable	−1
Each naming convention miss	−0.5

If the file has a syntax error, none of the other checks run — there's nothing meaningful to audit in code that doesn't parse. Those sections show as Skipped rather than a misleading "Pass".

The final verdict cares about execution first, score second:

• 🚩 Code doesn't run (syntax error or it crashes) → FLAGGED, always
• ✅ Code runs successfully and scores 8/10 or higher → CLEARED
• 🚩 Code runs successfully but scores below 8/10 → FLAGGED

---

📂 Project Structure

SourceAudit/
│── index.html                              GitHub Pages redirect → web/sourceaudit.html
│── .nojekyll                                tells GitHub Pages to skip Jekyll processing
│── main.py                                CLI entry point
│── assets/
│   └── icons/
│       └── favicon.png                    site favicon
│── samples/
│   └── sample.py                          demo file with a few intentional issues
│── sourceaudit/
│   ├── file_reader.py                     read a file / basic file stats
│   ├── syntax_checker.py                  ast.parse-based syntax check
│   ├── unused_variable_checker.py         assigned-but-never-read variables
│   ├── todo_checker.py                    TODO / FIXME comment scanner
│   ├── naming_checker.py                  snake_case / CONSTANT_CASE checker
│   └── report_builder.py                  combines the checkers, scores the file,
│                                           and runs submitted code
│── web/
│   ├── template.html                      the app's HTML/CSS/JS source
│   ├── build_app.py                       generates web/sourceaudit.html
│   └── sourceaudit.html                   the ready-to-open web app
│── tests/
│   └── test_checkers.py                   pytest suite
└── README.md

---

▶️ How to Run

CLI

1. Clone or download the repository
2. Run it against a file:

python main.py                         # audits samples/sample.py
python main.py path/to/file.py         # audit any file
python main.py path/to/file.py --run   # also execute it and print its output

Web App

1. Open web/sourceaudit.html in your browser
2. Ensure an active internet connection (Pyodide loads from a CDN on first run)
3. Paste in code, hit Run Review, and check the Console Output and Audit Findings tabs

---

🧪 Running the Tests

pip install pytest
pytest tests/

---

⚠️ Known Limitations

• 🌀 A program that's CPU-bound but not stuck in a Python-level loop (e.g. one giant C-level call inside a library) won't be interrupted by the watchdog, since it only fires on Python line events
• ⌨️ The web app's input() uses a single-line browser prompt() dialog, so it can't do anything fancier than "ask a question, get a line back" (no raw terminal control, no reading from a pasted file, etc.)

---

📌 About

SourceAudit started as a way to combine a linter, a quality scorer, and a runnable code sandbox into one clean tool. The CLI and web app share the exact same Python checking logic, so they never disagree on a score or a verdict.

---

👨‍💻 Author

Priyam Prabhat
Computer Science Student | Web Development | Cybersecurity

---

⭐

If you find this project useful, consider giving it a ⭐ on GitHub!