From b94f83dd75eb11c42f82de565e1de0ae8b913423 Mon Sep 17 00:00:00 2001 From: DataDave-Dev <153755137+DataDave-Dev@users.noreply.github.com> Date: Mon, 29 Jun 2026 23:58:36 -0600 Subject: [PATCH 1/2] docs: add CONTRIBUTING, issue templates and PR template --- .github/ISSUE_TEMPLATE/bec_proposal.md | 17 ++++++++ .github/ISSUE_TEMPLATE/bug_report.md | 24 ++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 15 +++++++ .github/pull_request_template.md | 14 ++++++ CONTRIBUTING.md | 53 +++++++++++++++++++++++ 5 files changed, 123 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bec_proposal.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bec_proposal.md b/.github/ISSUE_TEMPLATE/bec_proposal.md new file mode 100644 index 0000000..6a869f2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bec_proposal.md @@ -0,0 +1,17 @@ +--- +name: New BEC proposal +about: Propose a BEC (rule + check) for the catalog +title: "BEC: " +labels: enhancement +--- + +**Intent** — what should this rule enforce? + +**Why it matters** — what breaks if it is violated? + +**Check** — how would it be detected? (a `forbid` regex, a built-in check, or a +custom script) + +**Language(s)** — Python, JS/TS, any, ... + +**Severity** — `blocking` or `warning`, and why. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..3fe76cd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,24 @@ +--- +name: Bug report +about: Report something that does not work as expected +title: "" +labels: bug +--- + +**What happened** +A clear description of the bug. + +**Steps to reproduce** +1. ... +2. ... + +**Expected behavior** +What you expected to happen instead. + +**Environment** +- becwright version (`becwright --version`): +- Python version: +- OS: + +**Rule / check involved** (if any) +The `.bec/rules.yaml` rule or the `check` command, if relevant. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..5cad6d5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,15 @@ +--- +name: Feature request +about: Suggest an idea or improvement +title: "" +labels: enhancement +--- + +**Problem** +What problem would this solve, and who hits it? + +**Proposed solution** +What you would like to happen. + +**Alternatives considered** +Other approaches you thought about. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..9b45ce7 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,14 @@ +## What + +Briefly describe the change. + +## Why + +The problem it solves or the need it addresses. + +## Checklist + +- [ ] Tests pass (`pytest`) +- [ ] New behavior is covered by tests +- [ ] Commits are atomic (one logical change each) +- [ ] Docs updated if needed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b32e8c5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,53 @@ +# Contributing to becwright + +Thanks for your interest. becwright aims to be a small, sharp standard, so +contributions favor simplicity and clarity over feature count. + +## Development setup + +```bash +git clone https://github.com/DataDave-Dev/becwright.git +cd becwright +pip install -e ".[dev]" +pytest +``` + +## Workflow + +`main` is protected: changes land via pull request with CI green. + +1. Fork the repo and create a branch. +2. Make your change, with tests. +3. Run `pytest` (CI also enforces 80% coverage and runs becwright on itself). +4. Open a pull request. + +## Conventions + +- **Language:** code, comments and the repo are in English. The human-facing + README has a Spanish variant (`README.es.md`). +- **Comments:** only for complex code; no comments that restate the obvious. +- **Dependencies:** the runtime depends only on `pyyaml`. Do not add others + without discussing it first. +- **Atomic commits:** one complete logical change per commit, leaving the tests + green. Don't mix unrelated changes. +- **Python:** target 3.12. +- Do not change the `rules.yaml` format or the existing `checks/` logic without + discussing it first. + +## Adding a check + +A check is an executable that: + +- reads a newline-separated file list from **stdin**, +- prints violations to stdout, +- exits **0** (pass) or **non-zero** (fail). + +Built-in checks live in `src/becwright/checks/` and follow the shared skeleton +(see `dangerous_eval.py`). For language-agnostic rules, prefer the generic +`forbid` check (just a regex) over writing a new module. + +## Adding a catalog BEC + +Catalog bundles live in `becs/` as `.bec.yaml`. Always include `intent` and +`why_it_matters` — the *why* is the whole point of a BEC. See the existing +bundles for the format. From f4c96408d6c0dab7f54f2ab96805654619951d63 Mon Sep 17 00:00:00 2001 From: DataDave-Dev <153755137+DataDave-Dev@users.noreply.github.com> Date: Tue, 30 Jun 2026 00:08:32 -0600 Subject: [PATCH 2/2] chore: dogfood becwright with blocking self-rules Adds blocking rules so becwright enforces itself: no debug remnants and no eval/exec in the engine modules (src/becwright/*.py, scoping out checks/ to avoid the self-reference trap), and no wildcard imports across src and tests. CI already runs 'becwright check --all', so these gate every PR. --- .bec/rules.yaml | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/.bec/rules.yaml b/.bec/rules.yaml index bc49e86..ed79270 100644 --- a/.bec/rules.yaml +++ b/.bec/rules.yaml @@ -15,3 +15,40 @@ rules: - "tests/**/*.py" check: "python3 -m becwright.checks.redundant_comments" severity: warning + + - id: no-debug-remnants + intent: > + The engine code must never ship a debugger or pdb statement. + why_it_matters: > + A forgotten breakpoint would hang becwright itself, in CI or for users. + # Scoped to top-level modules (src/becwright/*.py): the checks/ directory is + # excluded on purpose, since debug_remnants would match its own pattern + # definition (a check that searches for a string can't run over its own source). + paths: + - "src/becwright/*.py" + check: "python3 -m becwright.checks.debug_remnants" + severity: blocking + + - id: no-wildcard-imports + intent: > + No 'from x import *' anywhere in the codebase. + why_it_matters: > + Wildcard imports hide where each name comes from and break static analysis. + paths: + - "src/becwright/**/*.py" + - "tests/**/*.py" + check: "python3 -m becwright.checks.wildcard_imports" + severity: blocking + + - id: no-dangerous-eval + intent: > + The engine must not use eval() / exec(). + why_it_matters: > + becwright runs inside other people's repos; arbitrary code execution in + the tool itself would be a serious risk. + # Same scoping note as no-debug-remnants: checks/ excluded (dangerous_eval + # matches its own pattern definition). + paths: + - "src/becwright/*.py" + check: "python3 -m becwright.checks.dangerous_eval" + severity: blocking