{ "title": "Code Commandments", "start": "overview", "pages": { "overview": { "title": "Overview", "view": { "type": "stack", "gap": 16, "children": [ { "type": "row", "gap": 12, "children": [ { "type": "stat", "label": "Sins", "value": "99", "tone": "danger", "note": "24 different rules" }, { "type": "stat", "label": "Files", "value": "40", "tone": "warn" }, { "type": "stat", "label": "Skills", "value": "16", "note": "the skills that teach the fixes" } ] }, { "type": "bars", "title": "Most common sins", "unit": "sins", "items": [ { "label": "python-dict-bag", "value": 27, "note": "5 files", "tone": "danger", "open": "sin/python-dict-bag" }, { "label": "python-member-out-of-order", "value": 20, "note": "2 files", "tone": "danger", "open": "sin/python-member-out-of-order" }, { "label": "python-repeated-named-call", "value": 6, "note": "2 files", "tone": "danger", "open": "sin/python-repeated-named-call" }, { "label": "python-blank-string-default", "value": 5, "note": "4 files", "tone": "danger", "open": "sin/python-blank-string-default" }, { "label": "python-conditional-statement", "value": 4, "note": "4 files", "tone": "danger", "open": "sin/python-conditional-statement" }, { "label": "python-converted-argument", "value": 4, "note": "1 file", "tone": "danger", "open": "sin/python-converted-argument" }, { "label": "python-namespace-dependency", "value": 4, "note": "4 files", "tone": "danger", "open": "sin/python-namespace-dependency" }, { "label": "row-outside-repository", "value": 4, "note": "3 files", "tone": "danger", "open": "sin/row-outside-repository" }, { "label": "python-placeholder-filled-data", "value": 3, "note": "2 files", "tone": "danger", "open": "sin/python-placeholder-filled-data" }, { "label": "python-mutable-static-state", "value": 3, "note": "2 files", "tone": "danger", "open": "sin/python-mutable-static-state" }, { "label": "python-invented-default", "value": 3, "note": "3 files", "tone": "danger", "open": "sin/python-invented-default" }, { "label": "python-namespace-cycle", "value": 2, "note": "2 files", "tone": "danger", "open": "sin/python-namespace-cycle" }, { "label": "python-loop-wrapped-in-if", "value": 2, "note": "2 files", "tone": "danger", "open": "sin/python-loop-wrapped-in-if" }, { "label": "python-dict-return-bag", "value": 2, "note": "2 files", "tone": "danger", "open": "sin/python-dict-return-bag" }, { "label": "control-flow-on-element", "value": 1, "note": "1 file", "tone": "danger", "open": "sin/control-flow-on-element" }, { "label": "inline-case-views", "value": 1, "note": "1 file", "tone": "danger", "open": "sin/inline-case-views" }, { "label": "python-bare-state-predicate", "value": 1, "note": "1 file", "tone": "danger", "open": "sin/python-bare-state-predicate" }, { "label": "python-phantom-nullable", "value": 1, "note": "1 file", "tone": "danger", "open": "sin/python-phantom-nullable" }, { "label": "plain-server-text", "value": 1, "note": "1 file", "tone": "danger", "open": "sin/plain-server-text" }, { "label": "python-mutable-value-object", "value": 1, "note": "1 file", "tone": "danger", "open": "sin/python-mutable-value-object" } ] } ] } }, "sin/python-dict-bag": { "title": "python-dict-bag", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-dict-bag", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "A parameter typed as a dict read by string keys — `row[\"sku\"]`, `row.get(\"quantity\")` — a record nobody declared" }, { "type": "fact", "label": "The rule", "body": "Give a record a type — a frozen dataclass — instead of a dict read by string keys." }, { "type": "fact", "label": "How to fix it", "body": "Declare the keys as fields of a frozen dataclass, build it where the data enters (a `from_payload` classmethod), and take that type as the parameter." } ] }, { "type": "code", "text": "commandments info python-dict-bag" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/resources/base.py", "8" ], "open": "sin/python-dict-bag/src/resources/base.py" }, { "cells": [ "src/features/phone/chat_view.py", "6" ], "open": "sin/python-dict-bag/src/features/phone/chat_view.py" }, { "cells": [ "src/surfaces/listing.py", "5" ], "open": "sin/python-dict-bag/src/surfaces/listing.py" }, { "cells": [ "src/overview/counts.py", "4" ], "open": "sin/python-dict-bag/src/overview/counts.py" }, { "cells": [ "src/controllers/stored.py", "4" ], "open": "sin/python-dict-bag/src/controllers/stored.py" } ] } ] } }, "sin/python-dict-bag/src/surfaces/listing.py": { "title": "python-dict-bag in listing.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-dict-bag in src/surfaces/listing.py", "level": 1 }, { "type": "card", "title": "5 places", "children": [ { "type": "file", "path": "src/surfaces/listing.py", "line": 83, "label": "line 83 — starred" }, { "type": "file", "path": "src/surfaces/listing.py", "line": 83, "label": "line 83 — subscript" }, { "type": "file", "path": "src/surfaces/listing.py", "line": 83, "label": "line 83 — subscript" }, { "type": "file", "path": "src/surfaces/listing.py", "line": 83, "label": "line 83 — subscript" }, { "type": "file", "path": "src/surfaces/listing.py", "line": 93, "label": "line 93 — subscript" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "A parameter typed as a dict read by string keys — `row[\"sku\"]`, `row.get(\"quantity\")` — a record nobody declared" }, { "type": "fact", "label": "The rule", "body": "Give a record a type — a frozen dataclass — instead of a dict read by string keys." }, { "type": "fact", "label": "How to fix it", "body": "Declare the keys as fields of a frozen dataclass, build it where the data enters (a `from_payload` classmethod), and take that type as the parameter." } ] }, { "type": "code", "text": "commandments info python-dict-bag" } ] } }, "sin/python-dict-bag/src/overview/counts.py": { "title": "python-dict-bag in counts.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-dict-bag in src/overview/counts.py", "level": 1 }, { "type": "card", "title": "4 places", "children": [ { "type": "file", "path": "src/overview/counts.py", "line": 6, "label": "line 6 — subscript" }, { "type": "file", "path": "src/overview/counts.py", "line": 6, "label": "line 6 — call" }, { "type": "file", "path": "src/overview/counts.py", "line": 8, "label": "line 8 — subscript" }, { "type": "file", "path": "src/overview/counts.py", "line": 9, "label": "line 9 — call" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "A parameter typed as a dict read by string keys — `row[\"sku\"]`, `row.get(\"quantity\")` — a record nobody declared" }, { "type": "fact", "label": "The rule", "body": "Give a record a type — a frozen dataclass — instead of a dict read by string keys." }, { "type": "fact", "label": "How to fix it", "body": "Declare the keys as fields of a frozen dataclass, build it where the data enters (a `from_payload` classmethod), and take that type as the parameter." } ] }, { "type": "code", "text": "commandments info python-dict-bag" } ] } }, "sin/python-dict-bag/src/resources/base.py": { "title": "python-dict-bag in base.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-dict-bag in src/resources/base.py", "level": 1 }, { "type": "card", "title": "8 places", "children": [ { "type": "file", "path": "src/resources/base.py", "line": 168, "label": "line 168 — subscript" }, { "type": "file", "path": "src/resources/base.py", "line": 168, "label": "line 168 — call" }, { "type": "file", "path": "src/resources/base.py", "line": 170, "label": "line 170 — subscript" }, { "type": "file", "path": "src/resources/base.py", "line": 171, "label": "line 171 — call" }, { "type": "file", "path": "src/resources/base.py", "line": 177, "label": "line 177 — subscript" }, { "type": "file", "path": "src/resources/base.py", "line": 177, "label": "line 177 — call" }, { "type": "file", "path": "src/resources/base.py", "line": 177, "label": "line 177 — subscript" }, { "type": "file", "path": "src/resources/base.py", "line": 178, "label": "line 178 — subscript" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "A parameter typed as a dict read by string keys — `row[\"sku\"]`, `row.get(\"quantity\")` — a record nobody declared" }, { "type": "fact", "label": "The rule", "body": "Give a record a type — a frozen dataclass — instead of a dict read by string keys." }, { "type": "fact", "label": "How to fix it", "body": "Declare the keys as fields of a frozen dataclass, build it where the data enters (a `from_payload` classmethod), and take that type as the parameter." } ] }, { "type": "code", "text": "commandments info python-dict-bag" } ] } }, "sin/python-dict-bag/src/controllers/stored.py": { "title": "python-dict-bag in stored.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-dict-bag in src/controllers/stored.py", "level": 1 }, { "type": "card", "title": "4 places", "children": [ { "type": "file", "path": "src/controllers/stored.py", "line": 251, "label": "line 251 — call" }, { "type": "file", "path": "src/controllers/stored.py", "line": 251, "label": "line 251 — subscript" }, { "type": "file", "path": "src/controllers/stored.py", "line": 459, "label": "line 459 — subscript" }, { "type": "file", "path": "src/controllers/stored.py", "line": 633, "label": "line 633 — subscript" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "A parameter typed as a dict read by string keys — `row[\"sku\"]`, `row.get(\"quantity\")` — a record nobody declared" }, { "type": "fact", "label": "The rule", "body": "Give a record a type — a frozen dataclass — instead of a dict read by string keys." }, { "type": "fact", "label": "How to fix it", "body": "Declare the keys as fields of a frozen dataclass, build it where the data enters (a `from_payload` classmethod), and take that type as the parameter." } ] }, { "type": "code", "text": "commandments info python-dict-bag" } ] } }, "sin/python-dict-bag/src/features/phone/chat_view.py": { "title": "python-dict-bag in chat_view.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-dict-bag in src/features/phone/chat_view.py", "level": 1 }, { "type": "card", "title": "6 places", "children": [ { "type": "file", "path": "src/features/phone/chat_view.py", "line": 18, "label": "line 18 — call" }, { "type": "file", "path": "src/features/phone/chat_view.py", "line": 19, "label": "line 19 — subscript" }, { "type": "file", "path": "src/features/phone/chat_view.py", "line": 20, "label": "line 20 — call" }, { "type": "file", "path": "src/features/phone/chat_view.py", "line": 24, "label": "line 24 — subscript" }, { "type": "file", "path": "src/features/phone/chat_view.py", "line": 29, "label": "line 29 — call" }, { "type": "file", "path": "src/features/phone/chat_view.py", "line": 30, "label": "line 30 — call" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "A parameter typed as a dict read by string keys — `row[\"sku\"]`, `row.get(\"quantity\")` — a record nobody declared" }, { "type": "fact", "label": "The rule", "body": "Give a record a type — a frozen dataclass — instead of a dict read by string keys." }, { "type": "fact", "label": "How to fix it", "body": "Declare the keys as fields of a frozen dataclass, build it where the data enters (a `from_payload` classmethod), and take that type as the parameter." } ] }, { "type": "code", "text": "commandments info python-dict-bag" } ] } }, "sin/python-member-out-of-order": { "title": "python-member-out-of-order", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-member-out-of-order", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a constant declared below a field in the head of a class — the inventory read in an ad-hoc order" }, { "type": "fact", "label": "The rule", "body": "Read a class's head in one fixed order: constants (`UPPER_CASE`, `Final`, `ClassVar`) first, then fields." }, { "type": "fact", "label": "How to fix it", "body": "Move the constant above the first field." } ] }, { "type": "code", "text": "commandments info python-member-out-of-order" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/providers/claude_driver.py", "19" ], "open": "sin/python-member-out-of-order/src/providers/claude_driver.py" }, { "cells": [ "src/serve.py", "1" ], "open": "sin/python-member-out-of-order/src/serve.py" } ] } ] } }, "sin/python-member-out-of-order/src/providers/claude_driver.py": { "title": "python-member-out-of-order in claude_driver.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-member-out-of-order in src/providers/claude_driver.py", "level": 1 }, { "type": "card", "title": "19 places", "children": [ { "type": "file", "path": "src/providers/claude_driver.py", "line": 59, "label": "line 59 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 60, "label": "line 60 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 61, "label": "line 61 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 62, "label": "line 62 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 63, "label": "line 63 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 64, "label": "line 64 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 65, "label": "line 65 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 66, "label": "line 66 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 67, "label": "line 67 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 68, "label": "line 68 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 69, "label": "line 69 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 70, "label": "line 70 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 71, "label": "line 71 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 72, "label": "line 72 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 73, "label": "line 73 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 74, "label": "line 74 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 75, "label": "line 75 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 76, "label": "line 76 — Assign" }, { "type": "file", "path": "src/providers/claude_driver.py", "line": 77, "label": "line 77 — Assign" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a constant declared below a field in the head of a class — the inventory read in an ad-hoc order" }, { "type": "fact", "label": "The rule", "body": "Read a class's head in one fixed order: constants (`UPPER_CASE`, `Final`, `ClassVar`) first, then fields." }, { "type": "fact", "label": "How to fix it", "body": "Move the constant above the first field." } ] }, { "type": "code", "text": "commandments info python-member-out-of-order" } ] } }, "sin/python-member-out-of-order/src/serve.py": { "title": "python-member-out-of-order in serve.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-member-out-of-order in src/serve.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/serve.py", "line": 211, "label": "line 211 — AnnAssign" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a constant declared below a field in the head of a class — the inventory read in an ad-hoc order" }, { "type": "fact", "label": "The rule", "body": "Read a class's head in one fixed order: constants (`UPPER_CASE`, `Final`, `ClassVar`) first, then fields." }, { "type": "fact", "label": "How to fix it", "body": "Move the constant above the first field." } ] }, { "type": "code", "text": "commandments info python-member-out-of-order" } ] } }, "sin/python-repeated-named-call": { "title": "python-repeated-named-call", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-repeated-named-call", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "the same `**changes` call is built the same way with the same keyword at 2+ sites — an operation that has no name on the type it belongs to." }, { "type": "fact", "label": "The rule", "body": "Name a keyword call you keep writing the same way: a method on the type — `node.with_meta(payload)` — that hides the call and the construction." }, { "type": "fact", "label": "How to fix it", "body": "Add a method to the receiver's class that makes the call, and call that at every site." } ] }, { "type": "code", "text": "commandments info python-repeated-named-call" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/features/status_bar/test.py", "4" ], "open": "sin/python-repeated-named-call/src/features/status_bar/test.py" }, { "cells": [ "src/features/plugins/test.py", "2" ], "open": "sin/python-repeated-named-call/src/features/plugins/test.py" } ] } ] } }, "sin/python-repeated-named-call/src/features/plugins/test.py": { "title": "python-repeated-named-call in test.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-repeated-named-call in src/features/plugins/test.py", "level": 1 }, { "type": "card", "title": "2 places", "children": [ { "type": "file", "path": "src/features/plugins/test.py", "line": 747, "label": "line 747 — call" }, { "type": "file", "path": "src/features/plugins/test.py", "line": 771, "label": "line 771 — call" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "the same `**changes` call is built the same way with the same keyword at 2+ sites — an operation that has no name on the type it belongs to." }, { "type": "fact", "label": "The rule", "body": "Name a keyword call you keep writing the same way: a method on the type — `node.with_meta(payload)` — that hides the call and the construction." }, { "type": "fact", "label": "How to fix it", "body": "Add a method to the receiver's class that makes the call, and call that at every site." } ] }, { "type": "code", "text": "commandments info python-repeated-named-call" } ] } }, "sin/python-repeated-named-call/src/features/status_bar/test.py": { "title": "python-repeated-named-call in test.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-repeated-named-call in src/features/status_bar/test.py", "level": 1 }, { "type": "card", "title": "4 places", "children": [ { "type": "file", "path": "src/features/status_bar/test.py", "line": 89, "label": "line 89 — call" }, { "type": "file", "path": "src/features/status_bar/test.py", "line": 89, "label": "line 89 — call" }, { "type": "file", "path": "src/features/status_bar/test.py", "line": 91, "label": "line 91 — call" }, { "type": "file", "path": "src/features/status_bar/test.py", "line": 91, "label": "line 91 — call" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "the same `**changes` call is built the same way with the same keyword at 2+ sites — an operation that has no name on the type it belongs to." }, { "type": "fact", "label": "The rule", "body": "Name a keyword call you keep writing the same way: a method on the type — `node.with_meta(payload)` — that hides the call and the construction." }, { "type": "fact", "label": "How to fix it", "body": "Add a method to the receiver's class that makes the call, and call that at every site." } ] }, { "type": "code", "text": "commandments info python-repeated-named-call" } ] } }, "sin/python-blank-string-default": { "title": "python-blank-string-default", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-blank-string-default", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`x: str = \"\"` standing in for absence — then asked `x == \"\"`, `not x` or `if x:` in its own scope" }, { "type": "fact", "label": "The rule", "body": "Say a value may be missing in its type; never default a `str` to `\"\"` and read that blank back as \"missing\"." }, { "type": "fact", "label": "How to fix it", "body": "`x: str | None = None`, asked `x is None` — so the blank is not a value every reader has to decode." } ] }, { "type": "code", "text": "commandments info python-blank-string-default" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/features/journal_laws/controller.py", "2" ], "open": "sin/python-blank-string-default/src/features/journal_laws/controller.py" }, { "cells": [ "src/controllers/base.py", "1" ], "open": "sin/python-blank-string-default/src/controllers/base.py" }, { "cells": [ "src/features/plans/controller.py", "1" ], "open": "sin/python-blank-string-default/src/features/plans/controller.py" }, { "cells": [ "src/features/tickets/controller.py", "1" ], "open": "sin/python-blank-string-default/src/features/tickets/controller.py" } ] } ] } }, "sin/python-blank-string-default/src/controllers/base.py": { "title": "python-blank-string-default in base.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-blank-string-default in src/controllers/base.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/controllers/base.py", "line": 39, "label": "line 39 — AnnAssign" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`x: str = \"\"` standing in for absence — then asked `x == \"\"`, `not x` or `if x:` in its own scope" }, { "type": "fact", "label": "The rule", "body": "Say a value may be missing in its type; never default a `str` to `\"\"` and read that blank back as \"missing\"." }, { "type": "fact", "label": "How to fix it", "body": "`x: str | None = None`, asked `x is None` — so the blank is not a value every reader has to decode." } ] }, { "type": "code", "text": "commandments info python-blank-string-default" } ] } }, "sin/python-blank-string-default/src/features/plans/controller.py": { "title": "python-blank-string-default in controller.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-blank-string-default in src/features/plans/controller.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/plans/controller.py", "line": 223, "label": "line 223 — Param why" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`x: str = \"\"` standing in for absence — then asked `x == \"\"`, `not x` or `if x:` in its own scope" }, { "type": "fact", "label": "The rule", "body": "Say a value may be missing in its type; never default a `str` to `\"\"` and read that blank back as \"missing\"." }, { "type": "fact", "label": "How to fix it", "body": "`x: str | None = None`, asked `x is None` — so the blank is not a value every reader has to decode." } ] }, { "type": "code", "text": "commandments info python-blank-string-default" } ] } }, "sin/python-blank-string-default/src/features/tickets/controller.py": { "title": "python-blank-string-default in controller.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-blank-string-default in src/features/tickets/controller.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/tickets/controller.py", "line": 488, "label": "line 488 — Param only" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`x: str = \"\"` standing in for absence — then asked `x == \"\"`, `not x` or `if x:` in its own scope" }, { "type": "fact", "label": "The rule", "body": "Say a value may be missing in its type; never default a `str` to `\"\"` and read that blank back as \"missing\"." }, { "type": "fact", "label": "How to fix it", "body": "`x: str | None = None`, asked `x is None` — so the blank is not a value every reader has to decode." } ] }, { "type": "code", "text": "commandments info python-blank-string-default" } ] } }, "sin/python-blank-string-default/src/features/journal_laws/controller.py": { "title": "python-blank-string-default in controller.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-blank-string-default in src/features/journal_laws/controller.py", "level": 1 }, { "type": "card", "title": "2 places", "children": [ { "type": "file", "path": "src/features/journal_laws/controller.py", "line": 19, "label": "line 19 — Param provider" }, { "type": "file", "path": "src/features/journal_laws/controller.py", "line": 19, "label": "line 19 — Param session_id" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`x: str = \"\"` standing in for absence — then asked `x == \"\"`, `not x` or `if x:` in its own scope" }, { "type": "fact", "label": "The rule", "body": "Say a value may be missing in its type; never default a `str` to `\"\"` and read that blank back as \"missing\"." }, { "type": "fact", "label": "How to fix it", "body": "`x: str | None = None`, asked `x is None` — so the blank is not a value every reader has to decode." } ] }, { "type": "code", "text": "commandments info python-blank-string-default" } ] } }, "sin/python-conditional-statement": { "title": "python-conditional-statement", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-conditional-statement", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a bare `a() if x else b()` statement — a conditional expression whose value nothing reads, so it chooses an action, not a value." }, { "type": "fact", "label": "The rule", "body": "Choose an action with `if`/`else`; a conditional expression chooses a value, so never write one whose value nothing reads." }, { "type": "fact", "label": "How to fix it", "body": "An `if x:` with each side as its own body — and no `else` at all when one side was `None`." } ] }, { "type": "code", "text": "commandments info python-conditional-statement" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/features/agent_sessions/test.py", "1" ], "open": "sin/python-conditional-statement/src/features/agent_sessions/test.py" }, { "cells": [ "src/providers/drivers.py", "1" ], "open": "sin/python-conditional-statement/src/providers/drivers.py" }, { "cells": [ "src/install.py", "1" ], "open": "sin/python-conditional-statement/src/install.py" }, { "cells": [ "src/features/tickets/controller.py", "1" ], "open": "sin/python-conditional-statement/src/features/tickets/controller.py" } ] } ] } }, "sin/python-conditional-statement/src/features/agent_sessions/test.py": { "title": "python-conditional-statement in test.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-conditional-statement in src/features/agent_sessions/test.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/agent_sessions/test.py", "line": 89, "label": "line 89 — conditional" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a bare `a() if x else b()` statement — a conditional expression whose value nothing reads, so it chooses an action, not a value." }, { "type": "fact", "label": "The rule", "body": "Choose an action with `if`/`else`; a conditional expression chooses a value, so never write one whose value nothing reads." }, { "type": "fact", "label": "How to fix it", "body": "An `if x:` with each side as its own body — and no `else` at all when one side was `None`." } ] }, { "type": "code", "text": "commandments info python-conditional-statement" } ] } }, "sin/python-conditional-statement/src/providers/drivers.py": { "title": "python-conditional-statement in drivers.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-conditional-statement in src/providers/drivers.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/providers/drivers.py", "line": 229, "label": "line 229 — conditional" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a bare `a() if x else b()` statement — a conditional expression whose value nothing reads, so it chooses an action, not a value." }, { "type": "fact", "label": "The rule", "body": "Choose an action with `if`/`else`; a conditional expression chooses a value, so never write one whose value nothing reads." }, { "type": "fact", "label": "How to fix it", "body": "An `if x:` with each side as its own body — and no `else` at all when one side was `None`." } ] }, { "type": "code", "text": "commandments info python-conditional-statement" } ] } }, "sin/python-conditional-statement/src/install.py": { "title": "python-conditional-statement in install.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-conditional-statement in src/install.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/install.py", "line": 820, "label": "line 820 — conditional" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a bare `a() if x else b()` statement — a conditional expression whose value nothing reads, so it chooses an action, not a value." }, { "type": "fact", "label": "The rule", "body": "Choose an action with `if`/`else`; a conditional expression chooses a value, so never write one whose value nothing reads." }, { "type": "fact", "label": "How to fix it", "body": "An `if x:` with each side as its own body — and no `else` at all when one side was `None`." } ] }, { "type": "code", "text": "commandments info python-conditional-statement" } ] } }, "sin/python-conditional-statement/src/features/tickets/controller.py": { "title": "python-conditional-statement in controller.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-conditional-statement in src/features/tickets/controller.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/tickets/controller.py", "line": 389, "label": "line 389 — conditional" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a bare `a() if x else b()` statement — a conditional expression whose value nothing reads, so it chooses an action, not a value." }, { "type": "fact", "label": "The rule", "body": "Choose an action with `if`/`else`; a conditional expression chooses a value, so never write one whose value nothing reads." }, { "type": "fact", "label": "How to fix it", "body": "An `if x:` with each side as its own body — and no `else` at all when one side was `None`." } ] }, { "type": "code", "text": "commandments info python-conditional-statement" } ] } }, "sin/python-converted-argument": { "title": "python-converted-argument", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-converted-argument", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a scalar parameter its callers keep filling with the same conversion — `receipt_for(str(order.id))` call after call — because it asks for the converted form instead of the value" }, { "type": "fact", "label": "The rule", "body": "Declare the parameter in the type callers actually hold and convert inside — one rule about the conversion, in one place." }, { "type": "fact", "label": "How to fix it", "body": "Move the conversion into the function and take what the callers had (`receipt_for(order)` or `receipt_for(order_id: int)`); a caller that forgets the conversion can no longer pass the wrong thing." } ] }, { "type": "code", "text": "commandments info python-converted-argument" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/features/status_bar/test.py", "4" ], "open": "sin/python-converted-argument/src/features/status_bar/test.py" } ] } ] } }, "sin/python-converted-argument/src/features/status_bar/test.py": { "title": "python-converted-argument in test.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-converted-argument in src/features/status_bar/test.py", "level": 1 }, { "type": "card", "title": "4 places", "children": [ { "type": "file", "path": "src/features/status_bar/test.py", "line": 207, "label": "line 207 — call" }, { "type": "file", "path": "src/features/status_bar/test.py", "line": 209, "label": "line 209 — call" }, { "type": "file", "path": "src/features/status_bar/test.py", "line": 210, "label": "line 210 — call" }, { "type": "file", "path": "src/features/status_bar/test.py", "line": 210, "label": "line 210 — call" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a scalar parameter its callers keep filling with the same conversion — `receipt_for(str(order.id))` call after call — because it asks for the converted form instead of the value" }, { "type": "fact", "label": "The rule", "body": "Declare the parameter in the type callers actually hold and convert inside — one rule about the conversion, in one place." }, { "type": "fact", "label": "How to fix it", "body": "Move the conversion into the function and take what the callers had (`receipt_for(order)` or `receipt_for(order_id: int)`); a caller that forgets the conversion can no longer pass the wrong thing." } ] }, { "type": "code", "text": "commandments info python-converted-argument" } ] } }, "sin/python-namespace-dependency": { "title": "python-namespace-dependency", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-namespace-dependency", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "an import out of a declared layer into a package that layer did not declare it may use" }, { "type": "fact", "label": "The rule", "body": "A declared layer may only import the packages it declared in its `mayUse` — down the stack, never back up or sideways." }, { "type": "fact", "label": "How to fix it", "body": "Move what both need down into the lower layer, pass it in from above, or invert it behind a protocol the lower layer owns — and if the declaration is what is wrong, say so rather than editing it quietly." } ] }, { "type": "code", "text": "commandments info python-namespace-dependency" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/resources/types.py", "1" ], "open": "sin/python-namespace-dependency/src/resources/types.py" }, { "cells": [ "src/features/auto_update/check.py", "1" ], "open": "sin/python-namespace-dependency/src/features/auto_update/check.py" }, { "cells": [ "src/features/auto_update/announcing.py", "1" ], "open": "sin/python-namespace-dependency/src/features/auto_update/announcing.py" }, { "cells": [ "src/features/auto_update/routes.py", "1" ], "open": "sin/python-namespace-dependency/src/features/auto_update/routes.py" } ] } ] } }, "sin/python-namespace-dependency/src/resources/types.py": { "title": "python-namespace-dependency in types.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-namespace-dependency in src/resources/types.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/resources/types.py", "line": 6, "label": "line 6 — Import Loaded" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "an import out of a declared layer into a package that layer did not declare it may use" }, { "type": "fact", "label": "The rule", "body": "A declared layer may only import the packages it declared in its `mayUse` — down the stack, never back up or sideways." }, { "type": "fact", "label": "How to fix it", "body": "Move what both need down into the lower layer, pass it in from above, or invert it behind a protocol the lower layer owns — and if the declaration is what is wrong, say so rather than editing it quietly." } ] }, { "type": "code", "text": "commandments info python-namespace-dependency" } ] } }, "sin/python-namespace-dependency/src/features/auto_update/check.py": { "title": "python-namespace-dependency in check.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-namespace-dependency in src/features/auto_update/check.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/auto_update/check.py", "line": 18, "label": "line 18 — Import changed_managed" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "an import out of a declared layer into a package that layer did not declare it may use" }, { "type": "fact", "label": "The rule", "body": "A declared layer may only import the packages it declared in its `mayUse` — down the stack, never back up or sideways." }, { "type": "fact", "label": "How to fix it", "body": "Move what both need down into the lower layer, pass it in from above, or invert it behind a protocol the lower layer owns — and if the declaration is what is wrong, say so rather than editing it quietly." } ] }, { "type": "code", "text": "commandments info python-namespace-dependency" } ] } }, "sin/python-namespace-dependency/src/features/auto_update/announcing.py": { "title": "python-namespace-dependency in announcing.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-namespace-dependency in src/features/auto_update/announcing.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/auto_update/announcing.py", "line": 10, "label": "line 10 — Import LEGACY_COPY_MARKER" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "an import out of a declared layer into a package that layer did not declare it may use" }, { "type": "fact", "label": "The rule", "body": "A declared layer may only import the packages it declared in its `mayUse` — down the stack, never back up or sideways." }, { "type": "fact", "label": "How to fix it", "body": "Move what both need down into the lower layer, pass it in from above, or invert it behind a protocol the lower layer owns — and if the declaration is what is wrong, say so rather than editing it quietly." } ] }, { "type": "code", "text": "commandments info python-namespace-dependency" } ] } }, "sin/python-namespace-dependency/src/features/auto_update/routes.py": { "title": "python-namespace-dependency in routes.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-namespace-dependency in src/features/auto_update/routes.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/auto_update/routes.py", "line": 10, "label": "line 10 — Import changed_managed" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "an import out of a declared layer into a package that layer did not declare it may use" }, { "type": "fact", "label": "The rule", "body": "A declared layer may only import the packages it declared in its `mayUse` — down the stack, never back up or sideways." }, { "type": "fact", "label": "How to fix it", "body": "Move what both need down into the lower layer, pass it in from above, or invert it behind a protocol the lower layer owns — and if the declaration is what is wrong, say so rather than editing it quietly." } ] }, { "type": "code", "text": "commandments info python-namespace-dependency" } ] } }, "sin/row-outside-repository": { "title": "row-outside-repository", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "row-outside-repository", "level": 1 }, { "type": "text", "body": "A rule of this project's own — its description lives in `.commandments/custom/`." }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/engine/runtime.py", "2" ], "open": "sin/row-outside-repository/src/engine/runtime.py" }, { "cells": [ "src/engine/sessions.py", "1" ], "open": "sin/row-outside-repository/src/engine/sessions.py" }, { "cells": [ "src/controllers/environments.py", "1" ], "open": "sin/row-outside-repository/src/controllers/environments.py" } ] } ] } }, "sin/row-outside-repository/src/engine/sessions.py": { "title": "row-outside-repository in sessions.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "row-outside-repository in src/engine/sessions.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/engine/sessions.py", "line": 217, "label": "line 217 — call" } ] }, { "type": "text", "body": "A rule of this project's own — its description lives in `.commandments/custom/`." } ] } }, "sin/row-outside-repository/src/controllers/environments.py": { "title": "row-outside-repository in environments.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "row-outside-repository in src/controllers/environments.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/controllers/environments.py", "line": 196, "label": "line 196 — call" } ] }, { "type": "text", "body": "A rule of this project's own — its description lives in `.commandments/custom/`." } ] } }, "sin/row-outside-repository/src/engine/runtime.py": { "title": "row-outside-repository in runtime.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "row-outside-repository in src/engine/runtime.py", "level": 1 }, { "type": "card", "title": "2 places", "children": [ { "type": "file", "path": "src/engine/runtime.py", "line": 43, "label": "line 43 — call" }, { "type": "file", "path": "src/engine/runtime.py", "line": 47, "label": "line 47 — call" } ] }, { "type": "text", "body": "A rule of this project's own — its description lives in `.commandments/custom/`." } ] } }, "sin/python-placeholder-filled-data": { "title": "python-placeholder-filled-data", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-placeholder-filled-data", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`Card(title=…, body=\"\")` — a dataclass field required as `str` handed the blank to satisfy the signature, a value the type cannot catch" }, { "type": "fact", "label": "The rule", "body": "A required field means the caller has the value; never fill one with `\"\"` to satisfy the signature." }, { "type": "fact", "label": "How to fix it", "body": "Fetch the real value — or split a narrower dataclass that only promises what this caller knows." } ] }, { "type": "code", "text": "commandments info python-placeholder-filled-data" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/features/status_bar/test.py", "2" ], "open": "sin/python-placeholder-filled-data/src/features/status_bar/test.py" }, { "cells": [ "src/features/family_tree/test.py", "1" ], "open": "sin/python-placeholder-filled-data/src/features/family_tree/test.py" } ] } ] } }, "sin/python-placeholder-filled-data/src/features/family_tree/test.py": { "title": "python-placeholder-filled-data in test.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-placeholder-filled-data in src/features/family_tree/test.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/family_tree/test.py", "line": 36, "label": "line 36 — call" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`Card(title=…, body=\"\")` — a dataclass field required as `str` handed the blank to satisfy the signature, a value the type cannot catch" }, { "type": "fact", "label": "The rule", "body": "A required field means the caller has the value; never fill one with `\"\"` to satisfy the signature." }, { "type": "fact", "label": "How to fix it", "body": "Fetch the real value — or split a narrower dataclass that only promises what this caller knows." } ] }, { "type": "code", "text": "commandments info python-placeholder-filled-data" } ] } }, "sin/python-placeholder-filled-data/src/features/status_bar/test.py": { "title": "python-placeholder-filled-data in test.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-placeholder-filled-data in src/features/status_bar/test.py", "level": 1 }, { "type": "card", "title": "2 places", "children": [ { "type": "file", "path": "src/features/status_bar/test.py", "line": 330, "label": "line 330 — call" }, { "type": "file", "path": "src/features/status_bar/test.py", "line": 330, "label": "line 330 — call" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`Card(title=…, body=\"\")` — a dataclass field required as `str` handed the blank to satisfy the signature, a value the type cannot catch" }, { "type": "fact", "label": "The rule", "body": "A required field means the caller has the value; never fill one with `\"\"` to satisfy the signature." }, { "type": "fact", "label": "How to fix it", "body": "Fetch the real value — or split a narrower dataclass that only promises what this caller knows." } ] }, { "type": "code", "text": "commandments info python-placeholder-filled-data" } ] } }, "sin/python-mutable-static-state": { "title": "python-mutable-static-state", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-mutable-static-state", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a `global` written from a function, or a class attribute set from a method — state no instance owns, changed by whoever ran last" }, { "type": "fact", "label": "The rule", "body": "Hold changing state on an instance someone owns and passes; never write a `global` or a class attribute from a function." }, { "type": "fact", "label": "How to fix it", "body": "Move the state onto an object, and hand that object to the code that reads and changes it." } ] }, { "type": "code", "text": "commandments info python-mutable-static-state" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/providers/turns.py", "2" ], "open": "sin/python-mutable-static-state/src/providers/turns.py" }, { "cells": [ "src/engine/bus.py", "1" ], "open": "sin/python-mutable-static-state/src/engine/bus.py" } ] } ] } }, "sin/python-mutable-static-state/src/providers/turns.py": { "title": "python-mutable-static-state in turns.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-mutable-static-state in src/providers/turns.py", "level": 1 }, { "type": "card", "title": "2 places", "children": [ { "type": "file", "path": "src/providers/turns.py", "line": 101, "label": "line 101 — Assign" }, { "type": "file", "path": "src/providers/turns.py", "line": 137, "label": "line 137 — Assign" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a `global` written from a function, or a class attribute set from a method — state no instance owns, changed by whoever ran last" }, { "type": "fact", "label": "The rule", "body": "Hold changing state on an instance someone owns and passes; never write a `global` or a class attribute from a function." }, { "type": "fact", "label": "How to fix it", "body": "Move the state onto an object, and hand that object to the code that reads and changes it." } ] }, { "type": "code", "text": "commandments info python-mutable-static-state" } ] } }, "sin/python-mutable-static-state/src/engine/bus.py": { "title": "python-mutable-static-state in bus.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-mutable-static-state in src/engine/bus.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/engine/bus.py", "line": 191, "label": "line 191 — Assign" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "a `global` written from a function, or a class attribute set from a method — state no instance owns, changed by whoever ran last" }, { "type": "fact", "label": "The rule", "body": "Hold changing state on an instance someone owns and passes; never write a `global` or a class attribute from a function." }, { "type": "fact", "label": "How to fix it", "body": "Move the state onto an object, and hand that object to the code that reads and changes it." } ] }, { "type": "code", "text": "commandments info python-mutable-static-state" } ] } }, "sin/python-invented-default": { "title": "python-invented-default", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-invented-default", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`f(x or \"\")` — an empty string, `0` or `False` invented to fill an argument when the value is missing, a stand-in the callee cannot tell from real data" }, { "type": "fact", "label": "The rule", "body": "Never fill an argument with an invented `\"\"`, `0` or `False` on absence — handle the missing case, or make the value certain where it is born." }, { "type": "fact", "label": "How to fix it", "body": "Decide at the source: raise when the value must be there, or pass `None` on to a parameter that admits it. A real default (`or \"EUR\"`) is a choice, not an invention." } ] }, { "type": "code", "text": "commandments info python-invented-default" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/features/kanban/board.py", "1" ], "open": "sin/python-invented-default/src/features/kanban/board.py" }, { "cells": [ "src/features/tickets/cards.py", "1" ], "open": "sin/python-invented-default/src/features/tickets/cards.py" }, { "cells": [ "src/runner/hook_report.py", "1" ], "open": "sin/python-invented-default/src/runner/hook_report.py" } ] } ] } }, "sin/python-invented-default/src/features/kanban/board.py": { "title": "python-invented-default in board.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-invented-default in src/features/kanban/board.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/kanban/board.py", "line": 49, "label": "line 49 — binary" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`f(x or \"\")` — an empty string, `0` or `False` invented to fill an argument when the value is missing, a stand-in the callee cannot tell from real data" }, { "type": "fact", "label": "The rule", "body": "Never fill an argument with an invented `\"\"`, `0` or `False` on absence — handle the missing case, or make the value certain where it is born." }, { "type": "fact", "label": "How to fix it", "body": "Decide at the source: raise when the value must be there, or pass `None` on to a parameter that admits it. A real default (`or \"EUR\"`) is a choice, not an invention." } ] }, { "type": "code", "text": "commandments info python-invented-default" } ] } }, "sin/python-invented-default/src/features/tickets/cards.py": { "title": "python-invented-default in cards.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-invented-default in src/features/tickets/cards.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/tickets/cards.py", "line": 80, "label": "line 80 — binary" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`f(x or \"\")` — an empty string, `0` or `False` invented to fill an argument when the value is missing, a stand-in the callee cannot tell from real data" }, { "type": "fact", "label": "The rule", "body": "Never fill an argument with an invented `\"\"`, `0` or `False` on absence — handle the missing case, or make the value certain where it is born." }, { "type": "fact", "label": "How to fix it", "body": "Decide at the source: raise when the value must be there, or pass `None` on to a parameter that admits it. A real default (`or \"EUR\"`) is a choice, not an invention." } ] }, { "type": "code", "text": "commandments info python-invented-default" } ] } }, "sin/python-invented-default/src/runner/hook_report.py": { "title": "python-invented-default in hook_report.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-invented-default in src/runner/hook_report.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/runner/hook_report.py", "line": 19, "label": "line 19 — binary" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`f(x or \"\")` — an empty string, `0` or `False` invented to fill an argument when the value is missing, a stand-in the callee cannot tell from real data" }, { "type": "fact", "label": "The rule", "body": "Never fill an argument with an invented `\"\"`, `0` or `False` on absence — handle the missing case, or make the value certain where it is born." }, { "type": "fact", "label": "How to fix it", "body": "Decide at the source: raise when the value must be there, or pass `None` on to a parameter that admits it. A real default (`or \"EUR\"`) is a choice, not an invention." } ] }, { "type": "code", "text": "commandments info python-invented-default" } ] } }, "sin/python-namespace-cycle": { "title": "python-namespace-cycle", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-namespace-cycle", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "two of the project's packages import each other — a cycle that makes them one package split under two names." }, { "type": "fact", "label": "The rule", "body": "Keep imports between the project's packages pointing one way; two packages that import each other are a cycle." }, { "type": "fact", "label": "How to fix it", "body": "Move what both need into the lower package, pass it in from above, or invert it behind a protocol the lower one owns." } ] }, { "type": "code", "text": "commandments info python-namespace-cycle" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/resources/types.py", "1" ], "open": "sin/python-namespace-cycle/src/resources/types.py" }, { "cells": [ "src/features/triggers/controller.py", "1" ], "open": "sin/python-namespace-cycle/src/features/triggers/controller.py" } ] } ] } }, "sin/python-namespace-cycle/src/resources/types.py": { "title": "python-namespace-cycle in types.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-namespace-cycle in src/resources/types.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/resources/types.py", "line": 6, "label": "line 6 — Import Loaded" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "two of the project's packages import each other — a cycle that makes them one package split under two names." }, { "type": "fact", "label": "The rule", "body": "Keep imports between the project's packages pointing one way; two packages that import each other are a cycle." }, { "type": "fact", "label": "How to fix it", "body": "Move what both need into the lower package, pass it in from above, or invert it behind a protocol the lower one owns." } ] }, { "type": "code", "text": "commandments info python-namespace-cycle" } ] } }, "sin/python-namespace-cycle/src/features/triggers/controller.py": { "title": "python-namespace-cycle in controller.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-namespace-cycle in src/features/triggers/controller.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/triggers/controller.py", "line": 30, "label": "line 30 — Import Sequences" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "two of the project's packages import each other — a cycle that makes them one package split under two names." }, { "type": "fact", "label": "The rule", "body": "Keep imports between the project's packages pointing one way; two packages that import each other are a cycle." }, { "type": "fact", "label": "How to fix it", "body": "Move what both need into the lower package, pass it in from above, or invert it behind a protocol the lower one owns." } ] }, { "type": "code", "text": "commandments info python-namespace-cycle" } ] } }, "sin/python-loop-wrapped-in-if": { "title": "python-loop-wrapped-in-if", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-loop-wrapped-in-if", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "A `for` or `while` whose whole body is one `if` (no `else`) around real work — the iteration pushed a level deep behind a condition" }, { "type": "fact", "label": "The rule", "body": "Invert a loop body wrapped in one `if` into a `continue` guard so the work sits at the loop's own level." }, { "type": "fact", "label": "How to fix it", "body": "Write `if not : continue` as the first line of the loop and dedent the body under it." } ] }, { "type": "code", "text": "commandments info python-loop-wrapped-in-if" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/features/sharing/page_data.py", "1" ], "open": "sin/python-loop-wrapped-in-if/src/features/sharing/page_data.py" }, { "cells": [ "src/controllers/environments.py", "1" ], "open": "sin/python-loop-wrapped-in-if/src/controllers/environments.py" } ] } ] } }, "sin/python-loop-wrapped-in-if/src/features/sharing/page_data.py": { "title": "python-loop-wrapped-in-if in page_data.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-loop-wrapped-in-if in src/features/sharing/page_data.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/sharing/page_data.py", "line": 74, "label": "line 74 — IfStmt" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "A `for` or `while` whose whole body is one `if` (no `else`) around real work — the iteration pushed a level deep behind a condition" }, { "type": "fact", "label": "The rule", "body": "Invert a loop body wrapped in one `if` into a `continue` guard so the work sits at the loop's own level." }, { "type": "fact", "label": "How to fix it", "body": "Write `if not : continue` as the first line of the loop and dedent the body under it." } ] }, { "type": "code", "text": "commandments info python-loop-wrapped-in-if" } ] } }, "sin/python-loop-wrapped-in-if/src/controllers/environments.py": { "title": "python-loop-wrapped-in-if in environments.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-loop-wrapped-in-if in src/controllers/environments.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/controllers/environments.py", "line": 58, "label": "line 58 — IfStmt" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "A `for` or `while` whose whole body is one `if` (no `else`) around real work — the iteration pushed a level deep behind a condition" }, { "type": "fact", "label": "The rule", "body": "Invert a loop body wrapped in one `if` into a `continue` guard so the work sits at the loop's own level." }, { "type": "fact", "label": "How to fix it", "body": "Write `if not : continue` as the first line of the loop and dedent the body under it." } ] }, { "type": "code", "text": "commandments info python-loop-wrapped-in-if" } ] } }, "sin/python-dict-return-bag": { "title": "python-dict-return-bag", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-dict-return-bag", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`return {\"total\": …, \"tax\": …}` — a record of several fields handed back as a dict its callers read by string key" }, { "type": "fact", "label": "The rule", "body": "Return a typed value — a frozen dataclass — not a dict of several named fields." }, { "type": "fact", "label": "How to fix it", "body": "A `@dataclass(frozen=True)` for the result, built where it is returned — or a `TypedDict` when a dict must cross a boundary." } ] }, { "type": "code", "text": "commandments info python-dict-return-bag" }, { "type": "table", "columns": [ "File", "Sins" ], "rows": [ { "cells": [ "src/overview/counts.py", "1" ], "open": "sin/python-dict-return-bag/src/overview/counts.py" }, { "cells": [ "src/features/tickets/controller.py", "1" ], "open": "sin/python-dict-return-bag/src/features/tickets/controller.py" } ] } ] } }, "sin/python-dict-return-bag/src/overview/counts.py": { "title": "python-dict-return-bag in counts.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-dict-return-bag in src/overview/counts.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/overview/counts.py", "line": 14, "label": "line 14 — dict" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`return {\"total\": …, \"tax\": …}` — a record of several fields handed back as a dict its callers read by string key" }, { "type": "fact", "label": "The rule", "body": "Return a typed value — a frozen dataclass — not a dict of several named fields." }, { "type": "fact", "label": "How to fix it", "body": "A `@dataclass(frozen=True)` for the result, built where it is returned — or a `TypedDict` when a dict must cross a boundary." } ] }, { "type": "code", "text": "commandments info python-dict-return-bag" } ] } }, "sin/python-dict-return-bag/src/features/tickets/controller.py": { "title": "python-dict-return-bag in controller.py", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "python-dict-return-bag in src/features/tickets/controller.py", "level": 1 }, { "type": "card", "title": "Where", "children": [ { "type": "file", "path": "src/features/tickets/controller.py", "line": 726, "label": "line 726 — dict" } ] }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`return {\"total\": …, \"tax\": …}` — a record of several fields handed back as a dict its callers read by string key" }, { "type": "fact", "label": "The rule", "body": "Return a typed value — a frozen dataclass — not a dict of several named fields." }, { "type": "fact", "label": "How to fix it", "body": "A `@dataclass(frozen=True)` for the result, built where it is returned — or a `TypedDict` when a dict must cross a boundary." } ] }, { "type": "code", "text": "commandments info python-dict-return-bag" } ] } }, "sin/control-flow-on-element": { "title": "control-flow-on-element", "view": { "type": "stack", "gap": 16, "children": [ { "type": "heading", "text": "control-flow-on-element", "level": 1 }, { "type": "card", "title": "About this rule", "children": [ { "type": "fact", "label": "What it is", "body": "`v-if`/`v-for`/`v-else`/`v-else-if` on an HTML/component tag instead of a `