@aacombarro89/praxis 0.1.9 → 0.1.11

package/packages/layer2/python-backend-recipes/rules.md

@@ -12,26 +12,22 @@ Layer 1 rules (think before coding, simplicity first, surgical changes,
 goal-driven execution) apply unchanged — this file adds only what is
 Python-specific.
 
-- **Mirror the nearest module.** Before adding a feature, open the closest
-  existing file that already does the same kind of thing (a sibling in the same
-  directory, an adjacent route/handler/service). Copy its structure — imports,
-  class/function layout, error handling, naming — rather than inventing a new
-  shape. The prior art is the template; matching it is verifiable, following
-  prose is not.
-- **One module, one responsibility.** A new `.py` file exports the smallest
-  coherent unit. Keep pure logic separate from I/O (filesystem, network, database)
-  so the logic is testable without mocks — mirror how the existing modules here
-  already split the two.
-- **Use the stdlib and installed deps before adding one.** Python stdlib
-  (`pathlib`, `dataclasses`, `typing`, `json`, `os`) and a dependency already in
-  `pyproject.toml` / `requirements*.txt` cover most needs. A new dependency for
-  what a few lines do is debt; justify it against what is already imported in
-  neighbouring files.
-- **Type hints are the contract.** Annotate inputs and outputs at module
-  boundaries; validate external/untrusted input where it enters (a schema
-  validator if the repo already uses one, e.g. pydantic). Don't re-validate data
-  already typed and checked upstream.
 - **Follow the repo's packaging conventions.** Match the module layout, import
-  style (absolute vs relative), and packaging already in use — don't introduce a
-  second convention. If the project uses `src/` layout, honour it; if it uses
-  flat packages, honour that.
+  style (absolute vs relative), and `src/` vs flat packaging already in use —
+  don't introduce a second convention.
+- **No mutable default arguments.** A `[]` or `{}` default is shared across
+  every call; use a `None` sentinel and build the value inside the function
+  body.
+- **Never swallow exceptions.** No bare `except:`; catch the narrowest
+  exception type and either handle it or re-raise with `raise ... from e` to
+  keep the chain.
+- **Timezone-aware datetimes.** Use `datetime.now(timezone.utc)`, not naive
+  `datetime.now()` — a naive datetime is a latent bug at every boundary it
+  crosses.
+- **No blocking calls inside `async def`.** `requests`, `time.sleep`, and sync
+  DB drivers stall the event loop; use the async equivalent or run it in an
+  executor.
+- **Parameterized queries only.** Pass values as query parameters; never build
+  SQL with f-strings or `%` interpolation.
+- **Context managers for resources.** Open files, connections, and locks with
+  `with` so they close on every path, including exceptions.

package/packages/layer2/python-testing/rules.md

@@ -4,34 +4,28 @@ paths: ["**/*.py", "**/test_*.py", "**/*_test.py"]
 
 ## Python test-layer recipe (Layer 2)
 
-Choosing *where* a test belongs matters as much as writing it. Pick the layer
-that fails for the right reason, and mirror the repo's existing tests of that
-kind for structure and fixtures.
+Choosing *where* a test belongs matters as much as writing it: pick unit,
+integration, or end-to-end by what could actually break — unit for a single
+module's logic, integration for real seams (filesystem, a spawned process, a
+database), end-to-end for an invariant the whole application must honour.
+Then mirror the nearest existing test of that same layer for its location
+(`tests/` or alongside), `test_*.py` naming, and `conftest.py` fixtures rather
+than inventing a new shape.
 
 Layer 1 rules (think before coding, simplicity first, surgical changes,
 goal-driven execution) apply unchanged — this file adds only what is
 Python-testing-specific.
 
-- **Harness before features.** A rule that matters has a test. Write (or extend)
-  the test that pins the new behaviour *before or with* the code that satisfies
-  it — never land logic whose only check is "it looked right". Make the failing
-  test the prompt: it states what is missing.
-- **Pick the layer by what could break.**
-  - *Unit* — pure logic, branches, parsing, a single module's contract. Fast, no
-    I/O, no fixtures. Default here; most logic belongs at this layer.
-  - *Integration* — two or more modules composed, or real I/O (filesystem, a
-    spawned process, a database). Use when the bug would live in the seam between
-    units, not inside one.
-  - *End-to-end* — an invariant the whole application must honour, or a contract
-    a future change must not break. Use for the rails, not for every feature.
-- **Mirror the existing suite.** Find the nearest test of the same layer and copy
-  its setup — `pytest` is the default, its file location (`tests/` or alongside
-  source), naming convention (`test_*.py`), how it builds fixtures (`conftest.py`,
-  `@pytest.fixture`) and asserts. Don't introduce a second runner or a new fixture
-  style.
-- **Assert behaviour, not implementation.** Test observable inputs→outputs and
-  error cases at the boundary; avoid asserting private internals that refactors
-  will churn. One clear failing assertion beats five brittle ones.
-- **No new framework for one test.** The repo's installed runner and plain
-  `assert` statements cover almost everything. Reach for a new testing dependency
-  only when the existing one demonstrably cannot express the check.
+- **Plain `assert` with pytest.** Let pytest's assertion rewriting report the
+  values; don't wrap checks in `unittest` assert methods or add a second
+  runner.
+- **Prefer builtin fixtures.** Reach for `tmp_path`, `monkeypatch`, `capsys`
+  over hand-rolled setup/teardown code — they clean up after themselves.
+- **Parametrize instead of copy-paste.** Use `@pytest.mark.parametrize` for
+  the same body run over many inputs, not duplicated test functions.
+- **Default fixtures to function scope.** Widen to `module`/`session` scope
+  only for an expensive read-only resource; a wider scope shares mutable
+  state across tests that expect isolation.
+- **Assert error paths with `pytest.raises`.** Use
+  `with pytest.raises(Err, match=...)` and assert on the message so the wrong
+  error can't pass silently.

package/packages/layer2/react-components/rules.md

@@ -13,32 +13,37 @@ Layer 1 rules (think before coding, simplicity first, surgical changes,
 goal-driven execution) apply unchanged — this file adds only what is
 React-specific.
 
-- **Mirror the nearest component.** Before adding a component, open the closest
-  existing one that does the same kind of thing (a sibling in the same directory
-  or feature folder). Copy its structure — file layout, how it exports, how it
-  receives and passes props, where state lives — rather than inventing a new
-  shape. The prior art is the template; matching it is verifiable, following
-  prose is not.
 - **Props typed at the boundary.** Every component declares an explicit props
-  interface or type at the top of its file. Accept the minimum props needed; no
-  catch-all `[key: string]: unknown`. Children are explicit when the component
-  uses them.
+  interface or type at the top of its file. Accept the minimum props needed;
+  no catch-all `[key: string]: unknown`.
 - **Composition over configuration.** Prefer a small focused component used in
   multiple arrangements over a large one with a boolean-flag API. When a
-  component's props grow into a switch statement, split into two components that
-  share a common primitive.
-- **Native HTML elements before a component library.** A `<button>`, `<label>`,
-  or `<ul>` is always the first option. Reach for a library component only when
-  the native element demonstrably cannot satisfy the requirement — and then use
-  whichever library the repo already imports, not a new one.
-- **Accessibility is non-negotiable.** Every interactive element is reachable by
-  keyboard and has a visible focus style. Form inputs have associated `<label>`
-  elements (via `htmlFor`/`id` or wrapping). Non-decorative images have
-  descriptive `alt` text. Custom interactive elements carry the correct ARIA
-  `role` and `aria-*` attributes. These are not optional polish; ship them with
-  the component.
-- **Follow the repo's hooks and state conventions.** Use `useState`/`useReducer`
-  at the level state is first needed, and lift only when a sibling needs it.
-  Match whatever custom-hook patterns the repo already uses; don't introduce a
-  new global-state solution for a single component's needs. Mirror how the
-  existing components here manage side effects and data fetching.
+  component's props grow into a switch statement, split into two components
+  that share a common primitive.
+- **Native HTML elements before a component library.** A `<button>`,
+  `<label>`, or `<ul>` is always the first option. Reach for a library
+  component only when the native element demonstrably cannot satisfy the
+  requirement — and then use whichever library the repo already imports.
+- **Accessibility is non-negotiable.** Every interactive element is reachable
+  by keyboard and has a visible focus style. Form inputs have associated
+  `<label>` elements. Non-decorative images have descriptive `alt` text.
+  Custom interactive elements carry the correct ARIA `role` and `aria-*`
+  attributes.
+- **Follow the repo's hooks and state conventions.** Use
+  `useState`/`useReducer` at the level state is first needed, and lift only
+  when a sibling needs it. Don't introduce a new global-state library for a
+  single component's needs.
+- **You might not need an effect.** Derive values during render instead of
+  mirroring props/state into state; an effect is for synchronizing with an
+  external system, not for computing from existing state.
+- **Name the effect callback.** `useEffect(function syncScrollPosition() { … },
+  [deps])` — a named function makes the effect's intent legible and gives it a
+  real name in stack traces and React DevTools instead of an anonymous arrow.
+- **Every subscription effect returns its cleanup.** A listener, timer, or
+  subscription set up in an effect is torn down in the function the effect
+  returns.
+- **`key` is stable identity, not the array index.** Keys must survive
+  reordering; index keys corrupt state on insert or remove.
+- **No `memo`/`useMemo`/`useCallback` by default.** Add memoization only
+  against a measured problem; premature memoization is complexity with no
+  payoff.

package/packages/layer2/react-testing/rules.md

@@ -4,36 +4,27 @@ paths: ["**/*.test.tsx", "**/*.test.jsx", "**/*.spec.tsx", "**/*.spec.jsx"]
 
 ## React test-layer recipe (Layer 2)
 
-Choosing *where* a test belongs matters as much as writing it. Pick the layer
-that fails for the right reason, and mirror the repo's existing tests of that
-kind for structure and setup.
+Choosing *where* a test belongs matters as much as writing it: pick unit
+render, integration, or end-to-end by what could actually break — a single
+component in isolation, two or more components (or a component wired to a
+real hook/context/store), or a full user journey in a real browser reserved
+for critical paths. Then mirror the nearest existing test's RTL setup,
+provider wrapping, runner, and naming rather than inventing a new shape.
 
 Layer 1 rules (think before coding, simplicity first, surgical changes,
 goal-driven execution) apply unchanged — this file adds only what is
 React-testing-specific.
 
-- **Test behaviour, not implementation.** Query by roles and user-visible text
-  (`getByRole`, `getByLabelText`, `getByText`) — not by CSS class, component
-  display name, or internal state. A test that breaks on a classname rename
-  without catching a real regression is noise; a test that catches a missing
-  label is signal.
-- **Pick the layer by what could break.**
-  - *Unit render* — a single component in isolation: does it render the right
-    output for a given set of props, show/hide the right elements, respond to
-    user events? Default here for most component logic.
-  - *Integration* — two or more components composed, or a component wired to a
-    real hook/context/store. Use when the bug would live in the seam between
-    components, not inside one.
-  - *End-to-end* — a full user journey in a real browser. Use only for the
-    critical paths that no unit or integration test can protect; reserve for the
-    rails, not for every feature.
-- **Use React Testing Library.** The repo's RTL setup (`render`, `screen`,
-  `userEvent`, `fireEvent`) covers almost everything. Mirror the nearest
-  existing test file for setup, cleanup, and how it wraps providers. Don't
-  introduce a second render helper or a separate component-testing framework.
-- **Mirror the existing suite.** Copy the nearest test file's structure —
-  runner, file naming, directory location, how it imports the component under
-  test, how it sets up providers or mocks. Consistency beats cleverness.
-- **No new framework for one test.** RTL and the repo's installed runner (e.g.
-  vitest/jest) cover almost every component test need. Reach for a new dependency
-  only when the existing tooling demonstrably cannot express the check.
+- **Query by role, label, or text.** Use `getByRole`, `getByLabelText`,
+  `getByText` — never CSS class, a test id where a role exists, or internal
+  component state. A test that breaks on a classname rename without catching
+  a regression is noise.
+- **Interactions go through `userEvent`.** Await it
+  (`await userEvent.click(...)`); prefer it over `fireEvent`, which skips the
+  events real users trigger.
+- **Await async UI with `findBy*`.** Use `findByRole`/`findByText` (or
+  `waitFor`) for content that appears after an effect; never put a
+  side-effecting call inside `waitFor`.
+- **Wrap renders with the repo's provider helper.** Mirror how the nearest
+  test supplies context, store, or router rather than rendering the bare
+  component.