diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..428053c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,29 @@ +name: Bug report +description: Report a reproducible defect +title: "bug: " +body: + - type: textarea + id: reproduction + attributes: + label: Reproduction steps + description: Include the smallest reproducible example using synthetic data. + validations: + required: true + - type: textarea + id: behavior + attributes: + label: Expected and actual behavior + validations: + required: true + - type: input + id: environment + attributes: + label: Environment + description: Commit, Python version, OS and relevant deployment mode. + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Sanitized logs or failing test + description: Remove credentials and private data before posting. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..1134eb0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,21 @@ +name: Feature request +description: Propose an improvement grounded in a user need +title: "feature: " +body: + - type: textarea + id: problem + attributes: + label: User problem + description: Who needs this and what can they not do today? + validations: + required: true + - type: textarea + id: outcome + attributes: + label: Proposed outcome and acceptance criteria + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives and tradeoffs diff --git a/.github/REPOSITORY_SETTINGS.md b/.github/REPOSITORY_SETTINGS.md new file mode 100644 index 0000000..a97c3c7 --- /dev/null +++ b/.github/REPOSITORY_SETTINGS.md @@ -0,0 +1,9 @@ +# Suggested repository About settings + +These are prepared values, not a claim that GitHub account settings have been updated. The connected GitHub tools cannot edit these fields. + +- Description: Jayden Mapasure: Python and JavaScript software engineering projects and experience. +- Topics: portfolio, python, javascript, software-engineer +- Homepage: https://jemade.github.io/portfolio/ + +For hosted applications, disclose account requirements and storage limitations in the README. Do not link a development server as a public demo. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..0f8012a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,19 @@ +## Problem and resulting behavior + +Describe the concrete trigger, previous behavior and new behavior. + +Closes # + +## Implementation and tradeoffs + +Explain the smallest useful change and any compatibility or operational risks. + +## Validation + +- Regression demonstrated before the fix: +- Checks run and results: +- Checks skipped and reason: + +## Review focus + +Identify the edge cases or decisions that need another engineer's attention. diff --git a/.github/workflows/repository-hygiene.yml b/.github/workflows/repository-hygiene.yml new file mode 100644 index 0000000..beebbf1 --- /dev/null +++ b/.github/workflows/repository-hygiene.yml @@ -0,0 +1,13 @@ +name: Repository hygiene +on: [push, pull_request] +permissions: + contents: read +jobs: + documentation-and-tracked-files: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - run: python scripts/repository_check.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..60c8d64 --- /dev/null +++ b/.gitignore @@ -0,0 +1,18 @@ + + +# Local runtime and private configuration +.venv/ +venv/ +__pycache__/ +*.py[cod] +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ +node_modules/ +.env +.env.local +.env.*.local +*.db +*.sqlite +*.sqlite3 +.DS_Store diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ec13665 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,18 @@ +# Contributing to portfolio + +Start with a reproducible defect or a concrete user need. Search existing issues and keep changes focused. + +## Development checks + +Use a Python virtual environment. From `.`, run: + +```sh +python scripts/repository_check.py +python -m http.server 8000 +``` + +Read the README for runtime versions and service prerequisites. Additional CI jobs are defined in `.github/workflows/`; do not describe a skipped check as passed. + +For a behavior fix, add a regression that fails before the fix and passes afterward. Explain expected and actual behavior, link the issue from the PR, and document tradeoffs. Use synthetic fixtures and never publish credentials or private data. + +A review should check correctness, boundaries, failure handling and tests. Independent review is distinct from automated checks. Follow [SECURITY.md](SECURITY.md) for vulnerability reports and [engineering notes](docs/ENGINEERING.md) for product boundaries. diff --git a/README.md b/README.md index 2176803..e7d55a3 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Personal portfolio for my Python and JavaScript work: backend services, APIs, web applications, automation, and practical AI integrations. -[View portfolio](https://jemade.github.io/portfolio/) · [GitHub](https://github.com/Jemade) · [LinkedIn](https://www.linkedin.com/in/jayden-mapasure) +[View portfolio](https://jemade.github.io/portfolio/) · [GitHub](https://github.com/Jemade) · [LinkedIn](https://www.linkedin.com/in/jayden-mapasure-013410323/) ## Featured work @@ -10,6 +10,8 @@ Personal portfolio for my Python and JavaScript work: backend services, APIs, we | --- | --- | | [BridgeSync](https://github.com/Jemade/BridgeSync) | Order delivery, durable jobs, and payment reconciliation | | [AgentBench](https://github.com/Jemade/AgentBench) | Python coding-agent evaluation and inspectable evidence | +| [RAG System](https://github.com/Jemade/RAG-SYSTEM) | Retrieval telemetry, evidence checks and evaluation | +| [Personal Workspace MCP](https://github.com/Jemade/MCP-SERVER) | Tasks, read-only SQLite analytics and weather tools | | [Relay](https://github.com/Jemade/Relay) | Conversation evaluation and streaming progress | | [FlowOps](https://github.com/Jemade/flowOPS) | Data pipeline orchestration | | [LLM API Gateway](https://github.com/Jemade/API-WRAPPER) | Provider integration, authentication, and rate limiting | @@ -38,3 +40,9 @@ Open http://localhost:8000. - `.github/workflows/`: GitHub Pages deployment. Google Fonts, Devicon, and Lucide load from external providers. The site can be served by any static web host. + +## Engineering and contribution guide + +Read the [engineering notes](docs/ENGINEERING.md) for implementation boundaries and verification commands, the [review checklist](docs/REVIEW_CHECKLIST.md) for evidence still required, and [CONTRIBUTING.md](CONTRIBUTING.md) to propose changes. Report vulnerabilities through [SECURITY.md](SECURITY.md). + +[![Repository hygiene](https://github.com/Jemade/portfolio/actions/workflows/repository-hygiene.yml/badge.svg)](https://github.com/Jemade/portfolio/actions/workflows/repository-hygiene.yml) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..8ba3f74 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,9 @@ +# Security reporting and deployment boundaries + +Report a suspected vulnerability privately to mapasurejayden@gmail.com with the repository, affected commit, reproduction steps and expected impact. Do not post credentials, customer data or exploit details in a public issue. Use GitHub private vulnerability reporting if it is enabled for this repository. + +No response-time or security certification is promised. The maintainer will assess the report and coordinate a fix when possible. + +Before public deployment, review authentication, authorization, data ownership, network exposure, secret handling, dependency advisories, logs and persistence for the intended environment. Local demos, mock providers and development Compose configurations are not proof of a secure production deployment. + +The repository hygiene check scans tracked files for selected credential patterns and runtime artifacts. It does not audit Git history or establish that every vulnerability or secret has been found. If an exposed credential is found, revoke or rotate it before addressing repository history. diff --git a/docs/ENGINEERING.md b/docs/ENGINEERING.md new file mode 100644 index 0000000..82e971b --- /dev/null +++ b/docs/ENGINEERING.md @@ -0,0 +1,38 @@ +# Engineering notes: portfolio + +## Purpose and scope + +Python and JavaScript engineering portfolio. This repository is an independently inspectable project; customer adoption, production scale and commercial readiness are not claimed without evidence. + +## Request and data flow + +Static HTML content and assets → CSS layout and browser behavior → GitHub Pages deployment. + +## Implementation map + +Primary implementation and review locations: `index.html`, `style.css`, `script.js`, `assets`. Dependency manifests and `.github/workflows/` specify installation and automated checks. Read the source for exact contracts and data models. + +## Local verification + +From `.` in a configured virtual environment: + +```sh +python scripts/repository_check.py +python -m http.server 8000 +``` + +From the repository root, run `python scripts/repository_check.py` for documentation and tracked-file checks. CI evidence is available in [GitHub Actions](https://github.com/Jemade/portfolio/actions). Green hygiene checks alone do not mean application tests passed. + +## Decisions and boundaries + +Static presentation rather than a backend product. Fonts and icons depend on external providers. Experience claims are owner-supplied; engineering projects should link to verifiable source and limitations. + +Use the README's current run instructions and configuration examples. Keep provider credentials outside Git. Test changes against controlled fixtures before enabling external services. Health checks indicate process/service state, not end-to-end correctness. + +## Review and operational evidence + +[Review checklist](REVIEW_CHECKLIST.md) distinguishes repository evidence from outstanding human and deployment validation. Report measured workload, environment and method with any performance claim. Document incident fixes through reproducible issues and regression tests; do not invent user counts or peer reviews. + +## Reuse and licensing + +No repository-wide reuse license has been selected. Public visibility alone does not grant an open-source reuse license. Ownership and third-party asset rights must be confirmed before licensing this project. diff --git a/docs/PROFILE_README.md b/docs/PROFILE_README.md new file mode 100644 index 0000000..746e30e --- /dev/null +++ b/docs/PROFILE_README.md @@ -0,0 +1,19 @@ +# Jayden Takudzwa Mapasure + +Software Engineer based in Harare, Zimbabwe. I build backend services, APIs, web applications, automation and practical AI integrations with Python and JavaScript. + +[Portfolio](https://jemade.github.io/portfolio/) · [LinkedIn](https://www.linkedin.com/in/jayden-mapasure-013410323/) · [Contact](mailto:mapasurejayden@gmail.com) + +## Selected engineering work + +| Project | What to inspect | +| --- | --- | +| [BridgeSync](https://github.com/Jemade/BridgeSync) | Durable delivery, reconciliation, isolation and regression tests | +| [AgentBench](https://github.com/Jemade/AgentBench) | Sandbox execution, verifier correctness and evaluation evidence | +| [RAG System](https://github.com/Jemade/RAG-SYSTEM) | Retrieval telemetry, grounding checks and evaluation harness | +| [Personal Workspace MCP](https://github.com/Jemade/MCP-SERVER) | Safe local tools, SQLite access and weather integration | +| [LLM API Gateway](https://github.com/Jemade/API-WRAPPER) | Provider abstraction, authentication, rate limiting and webhooks | + +Each repository documents its setup and current limitations. Read the implementation and test evidence rather than treating demo output as a production claim. + +University of Zimbabwe, B.S. Artificial Intelligence and Machine Learning, 2024–2028. Open to remote software engineering opportunities. diff --git a/docs/PROJECT_REVIEW.md b/docs/PROJECT_REVIEW.md new file mode 100644 index 0000000..ece349b --- /dev/null +++ b/docs/PROJECT_REVIEW.md @@ -0,0 +1,53 @@ +# Public project review + +Baseline prepared on 4 October 2026. The repository links below provide source code, setup instructions, CI and documented limitations. This review does not certify production security, customer adoption or engineering ownership. + +## Project index + +| Repository | Automated evidence | Implementation notes | Licensing status | Inspected source base | +| --- | --- | --- | --- | --- | +| [API-WRAPPER](https://github.com/Jemade/API-WRAPPER) | [Checks](https://github.com/Jemade/API-WRAPPER/actions) | [Engineering](https://github.com/Jemade/API-WRAPPER/blob/main/docs/ENGINEERING.md) | MIT present | `76f199e` | +| [AgentBench](https://github.com/Jemade/AgentBench) | [Checks](https://github.com/Jemade/AgentBench/actions) | [Engineering](https://github.com/Jemade/AgentBench/blob/main/docs/ENGINEERING.md) | MIT present | `798dae6` | +| [Avantis-support](https://github.com/Jemade/Avantis-support) | [Checks](https://github.com/Jemade/Avantis-support/actions) | [Engineering](https://github.com/Jemade/Avantis-support/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `82319c4` | +| [BridgeSync](https://github.com/Jemade/BridgeSync) | [Checks](https://github.com/Jemade/BridgeSync/actions) | [Engineering](https://github.com/Jemade/BridgeSync/blob/main/docs/ENGINEERING.md) | MIT present | `3001aa7` | +| [Human-in-the-loop](https://github.com/Jemade/Human-in-the-loop) | [Checks](https://github.com/Jemade/Human-in-the-loop/actions) | [Engineering](https://github.com/Jemade/Human-in-the-loop/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `5f495ce` | +| [MCP-SERVER](https://github.com/Jemade/MCP-SERVER) | [Checks](https://github.com/Jemade/MCP-SERVER/actions) | [Engineering](https://github.com/Jemade/MCP-SERVER/blob/main/docs/ENGINEERING.md) | MIT present | `6747293` | +| [RAG-SYSTEM](https://github.com/Jemade/RAG-SYSTEM) | [Checks](https://github.com/Jemade/RAG-SYSTEM/actions) | [Engineering](https://github.com/Jemade/RAG-SYSTEM/blob/main/docs/ENGINEERING.md) | MIT present | `20c2965` | +| [Relay](https://github.com/Jemade/Relay) | [Checks](https://github.com/Jemade/Relay/actions) | [Engineering](https://github.com/Jemade/Relay/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `04d2c59` | +| [Streaming-Copilot-Ui](https://github.com/Jemade/Streaming-Copilot-Ui) | [Checks](https://github.com/Jemade/Streaming-Copilot-Ui/actions) | [Engineering](https://github.com/Jemade/Streaming-Copilot-Ui/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `6817041` | +| [Vetta](https://github.com/Jemade/Vetta) | [Checks](https://github.com/Jemade/Vetta/actions) | [Engineering](https://github.com/Jemade/Vetta/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `af71b77` | +| [cited-RAG-BOT](https://github.com/Jemade/cited-RAG-BOT) | [Checks](https://github.com/Jemade/cited-RAG-BOT/actions) | [Engineering](https://github.com/Jemade/cited-RAG-BOT/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `2a4c01e` | +| [flowOPS](https://github.com/Jemade/flowOPS) | [Checks](https://github.com/Jemade/flowOPS/actions) | [Engineering](https://github.com/Jemade/flowOPS/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `ede42c6` | +| [llm-cost-guard](https://github.com/Jemade/llm-cost-guard) | [Checks](https://github.com/Jemade/llm-cost-guard/actions) | [Engineering](https://github.com/Jemade/llm-cost-guard/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `dcf4173` | +| [portfolio](https://github.com/Jemade/portfolio) | [Checks](https://github.com/Jemade/portfolio/actions) | [Engineering](https://github.com/Jemade/portfolio/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `4517911` | +| [valid_json_Agent](https://github.com/Jemade/valid_json_Agent) | [Checks](https://github.com/Jemade/valid_json_Agent/actions) | [Engineering](https://github.com/Jemade/valid_json_Agent/blob/main/docs/ENGINEERING.md) | Owner must select reuse terms | `19fe8a9` | + +## Work completed in this review + +- Merged the five previously tested fixes for BridgeSync, AgentBench, RAG System, MCP Server and the LLM API Gateway. +- Added contributor instructions, issue forms, PR templates, security reporting, engineering notes, tracked-file checks and review checklists across all public repositories. +- Fixed existing lint/type/dependency issues in LLM Cost Guard and the async dependency in Relay. +- Added VETTA application CI and PC Assist backend/frontend CI with deterministic cache and platform-fallback checks. +- Updated portfolio links and added the four missing flagship project cards. + +Follow the actual Actions run for the commit being assessed. A green documentation check does not replace application tests, browser checks or deployment verification. + +## Profile settings prepared for the account owner + +The GitHub connector used for this review cannot edit account profile fields, pins, repository About fields or create the special profile repository. + +- Suggested bio: Software Engineer | Python & JavaScript | Backend systems, APIs, automation and practical AI integrations | Harare, Zimbabwe +- Website: https://jemade.github.io/portfolio/ +- LinkedIn: https://www.linkedin.com/in/jayden-mapasure-013410323/ +- Suggested pins: BridgeSync, AgentBench, RAG-SYSTEM, MCP-SERVER, API-WRAPPER and portfolio. +- [Profile README draft](PROFILE_README.md): publish as README.md in a public repository named Jemade/Jemade when that repository exists. + +## Evidence still requiring real validation + +- Independent peer review and contribution discussions cannot be created by marking an automated review as a human review. +- The owner must demonstrate code understanding and verify resume claims. +- Real users, feedback, adoption and performance measurements must be earned and recorded, not fabricated. +- Licenses cannot be selected for code or assets without confirming the owner's rights and intended reuse terms. +- A private SSH key found in LLM Cost Guard was removed from the current files. It remains in prior Git history and must be revoked wherever it was authorized. Current-file scanning does not resolve that historical exposure. +- Public demos that require account access need a safe reviewer-access workflow. Production persistence, backups and recovery require deployment-specific checks. +- Windows installation and hardware behavior need actual target-device testing; mocked helper tests are insufficient. diff --git a/docs/REVIEW_CHECKLIST.md b/docs/REVIEW_CHECKLIST.md new file mode 100644 index 0000000..d179177 --- /dev/null +++ b/docs/REVIEW_CHECKLIST.md @@ -0,0 +1,34 @@ +# Repository review checklist + +Reviewed baseline: 4 October 2026. This is an evidence checklist, not a hiring score or security certification. + +## Repository evidence + +- [x] README identifies the purpose, implementation and local run path. +- [x] Engineering notes describe data flow, implementation locations and product boundaries. +- [x] Contributor instructions and bug/feature forms exist. +- [x] Pull-request template asks for the problem, tradeoffs and actual validation. +- [x] Security reporting and deployment boundaries are documented. +- [x] A repeatable tracked-file and documentation check is included in CI. +- [x] Current scope and limitations are stated without invented adoption or performance claims. +- [ ] Repository-wide reuse license selected; confirm third-party rights independently. + +## Evidence to check for a specific release + +- [ ] Application tests, builds and required integrations pass at the release commit. Follow the Actions link in engineering notes; a past successful run is not proof of a new release. +- [ ] A clean installation and the main user workflow have been demonstrated in the target environment. +- [ ] Authentication and authorization are reviewed for the intended deployment, where applicable. +- [ ] Dependency advisories and all applicable secrets are reviewed; the bounded pattern scan is not sufficient on its own. +- [ ] Persistence, backup/recovery and failure behavior are verified in the intended environment, where applicable. +- [ ] Performance statements include an actual workload, measurement and environment. +- [ ] Screenshot or walkthrough reflects the current release. + +## Human and external evidence + +- [ ] An independent engineer has reviewed relevant code and the review is recorded. +- [ ] The owner can explain and modify the implementation independently. +- [ ] Actual user feedback is recorded when real users exist; synthetic fixtures are identified. +- [ ] Resume claims match work the owner personally performed and can substantiate. +- [ ] Third-party contributions, attribution and asset rights have been checked. + +Unchecked items require actual evidence. Items genuinely irrelevant to a project should be marked not applicable with a reason during release review. diff --git a/index.html b/index.html index 07f3c50..a2fcae3 100644 --- a/index.html +++ b/index.html @@ -26,7 +26,7 @@
- +
@@ -34,6 +34,7 @@

Software Engineer / Python + JavaScript

+

Harare, Zimbabwe · Open to remote engineering opportunities

Jayden Takudzwa Mapasure

I build reliable backend systems, APIs, web applications, and automation with Python and JavaScript, including practical AI integrations.

@@ -100,15 +101,19 @@

Jayden Takudzwa Mapasure

03 / Selected work

Projects with a
practical point of view.

-
Relay project preview
01

Relay

Real time multi agent evaluation engine with streaming communication, structured outputs, and persistent execution state.

View project
-
VETTA project loading screen
02

VETTA

Autonomous interview assessment and intelligence platform using FastAPI, PostgreSQL, Celery, Redis, S3 compatible storage, and Kubernetes oriented architecture.

View project
-
FlowOps workspace preview
03

FlowOps

Cloud native pipeline orchestration engine for multi stage data and ML workflows.

View project
-
04

LLM API Gateway

Production oriented FastAPI gateway standardizing access to multiple LLM providers with authentication, Redis controls, persistence, testing, and CI/CD.

View project
-
05

LLM Cost Guard

Token estimation, provider pricing, usage tracking, daily, weekly, and monthly budget enforcement, analytics, and threshold alerts.

View project
-
06

Structured Output Agent

Schema enforced LLM extraction system using Pydantic, validation aware retries, typed errors, provider abstraction, and deterministic test fixtures.

View project
-
07

CiteRAG

Citation grounded RAG for PDF question answering with page aware ingestion, hybrid retrieval, cross encoder reranking, and source level citations.

View project
-
08

ApprovalFlow Agent

Human in the loop workflow engine with persistent state, approval checkpoints, risk based tool classification, audit logging, and failure recovery.

View project
-
09

StreamCopilot

Real time AI assistant built with React, TypeScript, FastAPI, and SSE streaming with cancellation, retries, structured events, and observability.

View project
+
01

BridgeSync

Order delivery with durable jobs, retries, tenant isolation and payment reconciliation.

View project
+
02

AgentBench

Coding-agent evaluation with isolated execution, deterministic verifiers and inspectable case results.

View project
+
03

RAG System

Hybrid document retrieval with query traces, evidence checks and an automated evaluation harness.

View project
+
04

Personal Workspace MCP

Local task management, read-only SQLite analytics and weather tools through MCP.

View project
+
Relay project preview
05

Relay

Real time multi agent evaluation engine with streaming communication, structured outputs, and persistent execution state.

View project
+
VETTA project loading screen
06

VETTA

Interview review workspace with technical and communication scorecards, heuristic or model-backed assessment, and optional Celery processing.

View project
+
FlowOps workspace preview
07

FlowOps

Data pipeline workbench with inspectable processing stages, validation and optional cloud storage.

View project
+
08

LLM API Gateway

Production oriented FastAPI gateway standardizing access to multiple LLM providers with authentication, Redis controls, persistence, testing, and CI/CD.

View project
+
09

LLM Cost Guard

Token estimation, provider pricing, usage tracking, daily, weekly, and monthly budget enforcement, analytics, and threshold alerts.

View project
+
10

Structured Output Agent

Schema enforced LLM extraction system using Pydantic, validation aware retries, typed errors, provider abstraction, and deterministic test fixtures.

View project
+
11

CiteRAG

Citation grounded RAG for PDF question answering with page aware ingestion, hybrid retrieval, cross encoder reranking, and source level citations.

View project
+
12

ApprovalFlow Agent

Human in the loop workflow engine with persistent state, approval checkpoints, risk based tool classification, audit logging, and failure recovery.

View project
+
13

StreamCopilot

Real time AI assistant built with React, TypeScript, FastAPI, and SSE streaming with cancellation, retries, structured events, and observability.

View project
@@ -144,7 +149,7 @@

Jayden Takudzwa Mapasure

mapasurejayden@gmail.com +263 780 787 214 GitHub / Jemade - LinkedIn profile + LinkedIn profile
diff --git a/scripts/repository_check.py b/scripts/repository_check.py new file mode 100644 index 0000000..2af54f7 --- /dev/null +++ b/scripts/repository_check.py @@ -0,0 +1,69 @@ +"""Check tracked repository hygiene and required contributor documentation. + +This is a bounded pattern scan, not a security certification or history scan. +""" + +import re +import subprocess +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +REQUIRED = ( + "README.md", + "CONTRIBUTING.md", + "SECURITY.md", + "docs/ENGINEERING.md", + "docs/REVIEW_CHECKLIST.md", + ".gitignore", + ".github/pull_request_template.md", + ".github/ISSUE_TEMPLATE/bug_report.yml", + ".github/ISSUE_TEMPLATE/feature_request.yml", +) +SECRET_PATTERNS = ( + re.compile(r"gh[pousr]_[A-Za-z0-9]{30,}"), + re.compile(r"github_pat_[A-Za-z0-9_]{50,}"), + re.compile(r"AKIA[0-9A-Z]{16}"), + re.compile(r"AIza[0-9A-Za-z_-]{35}"), + re.compile(r"(?m)^-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----$"), +) + + +def main(): + errors = ["Missing " + name for name in REQUIRED if not (ROOT / name).is_file()] + tracked = ( + subprocess.check_output(["git", "ls-files", "-z"], cwd=ROOT) + .decode() + .split("\0") + ) + for name in filter(None, tracked): + path = Path(name) + if ( + any( + part in {".venv", "venv", "node_modules", "__pycache__"} + for part in path.parts + ) + or path.name == ".env" + or path.suffix in {".pyc", ".db", ".sqlite", ".sqlite3"} + ): + errors.append("Runtime or private file tracked: " + name) + file = ROOT / name + if not file.is_file() or file.stat().st_size > 1_000_000: + continue + try: + content = file.read_text(encoding="utf-8") + except UnicodeDecodeError: + continue + if any(pattern.search(content) for pattern in SECRET_PATTERNS): + errors.append("Possible credential in " + name + "; inspect privately") + if errors: + print("\n".join(errors)) + raise SystemExit(1) + print( + "Required documentation and tracked-file checks passed. " + "Pattern scan found no matching credentials; " + "history and other credential formats are outside this check." + ) + + +if __name__ == "__main__": + main()