@gspothq/cli 0.0.0-stage → 0.1.0

package/configurations/language/python/manifest.toml

@@ -0,0 +1,621 @@
+allowed_words = ["Python", "Ruff"]
+
+ignored_folders = [".venv", "venv"]
+
+[configuration]
+title = "Python"
+suggests = []
+description = "Python sources: Ruff for lint and layout, basedpyright for types, import contracts, docstrings that match signatures, unused dependencies, and dead code."
+
+[detect]
+extensions = [".py"]
+project_files = ["pyproject.toml", "requirements*.txt", "Pipfile"]
+shebangs = ["python", "python3"]
+
+[files]
+extensions = [".py", ".pyi"]
+filenames = ["pyproject.toml", "setup.cfg", ".importlinter"]
+
+[[tool]]
+name = "uv"
+version = "0.12.22"
+mise = "uv"
+
+[[tool]]
+name = "ruff"
+rule_url = "https://docs.astral.sh/ruff/rules/{rule}/"
+suppression = { inline_marker = "#\\s*[nN][oO][qQ][aA](?=\\s|:|$)", marker = "#\\s*(?:(?:ruff|flake8):\\s*)?[nN][oO][qQ][aA](?=\\s|:|$)", reason = "#\\s*(?:(?:ruff|flake8):\\s*)?[nN][oO][qQ][aA](?=\\s|:|$)[^#]*# ?(?<reason>\\S.*)" }
+version = "0.16.8"
+min_version = "0.9.0"
+mise = "ruff"
+pypi = "ruff"
+brew = "ruff"
+[[tool.replace]]
+file = "ruff.toml"
+shared = false
+
+[[tool.replace]]
+file = ".ruff.toml"
+shared = false
+
+[[tool.replace]]
+file = "pyproject.toml"
+table = "tool.ruff"
+shared = true
+
+[[tool]]
+name = "basedpyright"
+suppression = { marker = "\\b(?:type|pyright): ?ignore\\b", reason = "#[^#]*# ?(?<reason>\\S.*)" }
+version = "1.40.1"
+min_version = "1.20.0"
+npm = "basedpyright"
+[[tool.replace]]
+file = "pyrightconfig.json"
+shared = false
+
+[[tool.replace]]
+file = "pyproject.toml"
+table = "tool.basedpyright"
+shared = true
+
+[[tool.replace]]
+file = "pyproject.toml"
+table = "tool.pyright"
+shared = true
+
+[[tool]]
+name = "lint-imports"
+version = "2.15"
+mise = "pipx:import-linter"
+pypi = "import-linter"
+version_pattern = "v?(\\d+\\.\\d+(?:\\.\\d+)?)"
+
+[[tool]]
+name = "pydoclint"
+version = "0.9.1"
+mise = "pipx:pydoclint"
+pypi = "pydoclint"
+
+[[tool]]
+name = "deptry"
+version = "0.25.1"
+min_version = "0.20.0"
+mise = "pipx:deptry"
+pypi = "deptry"
+
+[[tool]]
+name = "validate-pyproject"
+version = "0.26"
+mise = "pipx:validate-pyproject"
+pypi = "validate-pyproject"
+version_pattern = "(\\d+\\.\\d+(?:\\.\\d+)?)"
+
+[[tool_file]]
+target = ".gspot/config/ruff.toml"
+tool = "ruff"
+pointer = { path = "ruff.toml", body = 'extend = "{target}"' }
+per_scope = true
+rule_keys = ["lint.select", "lint.ignore", "lint.per-file-ignores"]
+
+[[tool_file]]
+target = ".gspot/config/basedpyrightconfig.json"
+tool = "basedpyright"
+pointer = { path = "pyrightconfig.json", body = "{\n    \"extends\": \"{target}\"\n}" }
+per_scope = true
+
+[[check]]
+name = "ruff"
+example = "The expression `eval(user_input)` reports S307 when that rule is selected. Replace dynamic evaluation with parsing and explicit operations appropriate to the input contract."
+level = "recommended"
+stage = "commit"
+command = ["ruff", "check", "--no-cache", "--output-format", "json", "{files}"]
+exit_codes = [1]
+fix = ["ruff", "check", "--no-cache", "--fix", "--quiet", "{files}"]
+files = { extensions = [".py", ".pyi"] }
+output = { format = "json", fields = { file = "filename", line = "location.row", column = "location.column", rule = "code", message = "message" } }
+summary = "Lints every Python file with the Ruff rules for the level, security rules included."
+why = "Ruff holds the rules of a dozen older tools in one pass fast enough to run at every commit."
+help = "Run gspot check --fix for the rules that fix themselves. Turn one rule off with gspot ignore python/ruff --rule `<code>` --reason \"`<why>`\", and add --paths to limit it."
+
+[[check]]
+name = "ruff-format"
+example = "The Python assignment `value=1` differs from Ruff formatting. Format the file so the assignment becomes `value = 1`, then rerun."
+level = "recommended"
+stage = "commit"
+command = [
+    "ruff",
+    "format",
+    "--no-cache",
+    "--check",
+    "--output-format",
+    "concise",
+    "{files}",
+]
+exit_codes = [1]
+fix = ["ruff", "format", "--no-cache", "--quiet", "{files}"]
+files = { extensions = [".py", ".pyi"] }
+output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+):(?<column>\\d+): unformatted: ", message = "This file is not formatted the way Ruff formats it." }
+summary = "Checks the layout of every Python file against the Ruff formatter."
+why = "One layout everywhere keeps a diff about the change."
+help = "Run gspot check --fix."
+
+[[check]]
+name = "basedpyright"
+example = "The annotated assignment `count: int = \"one\"` reports an incompatible value type. Use `count: int = 1` when the value is a number, or correct the annotation if the contract requires text."
+level = "recommended"
+stage = "push"
+runs = "scope"
+cwd = "scope"
+command = ["basedpyright", "--outputjson"]
+exit_codes = [1]
+files = { extensions = [".py", ".pyi"] }
+output = { format = "json", items = "generalDiagnostics", line_base = 0, fields = { file = "file", line = "range.start.line", column = "range.start.character", rule = "rule", message = "message" } }
+summary = "Type checks the project. At level `all`, it also requires annotations."
+why = "A type error found here is a crash that never reaches a user."
+help = "Fix the type, or narrow it where the value arrives. Accept a file that needs another dependency set with gspot ignore python/basedpyright --paths `<path>` --reason \"`<why>`\"."
+
+[[check]]
+name = "import-linter"
+example = "A module importing from a layer forbidden by the configured import contract reports that dependency. Move the shared behavior to an allowed owner and update the import, then rerun against the same contract."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+cwd = "scope"
+tool = ["uv", "lint-imports"]
+env = { PYTHONDONTWRITEBYTECODE = "1" }
+files = { extensions = [
+    ".py",
+], filenames = [
+    "pyproject.toml",
+    "setup.cfg",
+    ".importlinter",
+] }
+summary = "Runs project import contracts from setup.cfg, .importlinter, or pyproject.toml."
+why = "A layer that imports the layer above it turns an architecture into a diagram nobody follows."
+help = "Move the import to the side the contract allows, or change the contract."
+
+[[check]]
+name = "pydoclint"
+example = "A function docstring describing parameter `name` when its signature accepts `path` reports a signature mismatch. Document `path` and its actual meaning, removing the obsolete parameter entry."
+level = "recommended"
+stage = "commit"
+cwd = "scope"
+tool = "pydoclint"
+files = { extensions = [".py"] }
+output = { format = "grouped", file_pattern = "^(?<file>\\S.*\\.py)$", pattern = "^\\s+(?<line>\\d+): (?<rule>DOC\\d+): (?<message>.*)$" }
+summary = "Checks that every docstring names the arguments, the return, and the exceptions its function really has."
+why = "A docstring that disagrees with the signature is worse than none, because people trust it."
+help = "Bring the docstring in line with the signature."
+
+[[check]]
+name = "deptry"
+example = "A module importing a third-party package absent from the project dependencies reports an undeclared dependency. Declare that dependency and update its lockfile with the project package manager, or remove the unused import."
+level = "recommended"
+stage = "push"
+runs = "scope"
+cwd = "scope"
+tool = ["uv", "deptry"]
+env = { PYTHONDONTWRITEBYTECODE = "1" }
+files = { extensions = [".py"], filenames = ["pyproject.toml"] }
+output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+):(?<column>\\d+): (?<rule>DEP\\d+) (?<message>.*)$" }
+summary = "Compares the imports of the project with the dependencies it declares: missing, unused, and transitive ones."
+why = "An import that works through somebody else's dependency breaks the day they drop it."
+help = "Declare the dependency, or remove the one nothing imports. Turn one rule off with gspot ignore python/deptry --rule `<code>` --reason \"`<why>`\"."
+
+[[check]]
+name = "pyproject"
+example = "The project metadata `version = 7` in `pyproject.toml` reports an invalid version value. Use a valid version string, such as `version = \"1.0.0\"`, and rerun before updating the lockfile."
+level = "recommended"
+stage = "commit"
+command = ["validate-pyproject", "{file}"]
+exit_codes = [1]
+files = { filenames = ["pyproject.toml"] }
+tool = "validate-pyproject"
+output = { format = "regex", pattern = "^\\[ERROR\\] (?<message>.*)$" }
+summary = "Validates every pyproject.toml against the packaging schemas."
+why = "A key the build backend does not know is ignored without a word."
+help = "Correct the key the message names."
+
+[[check]]
+name = "pip-installs"
+example = "A `requirements.txt` written by hand beside a locked Python project creates a second dependency owner. Export that file from the lockfile, declare it generated, and use the locked installation command."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { filenames = [
+    "uv.lock",
+    "poetry.lock",
+    "pdm.lock",
+], kinds = [
+    "source",
+    "generated",
+] }
+summary = "Checks that pyproject.toml lists every dependency: no hand-kept requirements file and no pip install. To accept one file, ignore its finding with gspot ignore."
+why = "Two owners of the dependency list drift apart, and the image installs what the lockfile never saw."
+help = "Export the requirements file from the lockfile and declare it generated, and replace pip install with the locked install. Accept a reviewed path with gspot ignore python/pip-installs --paths `<glob>` --reason \"`<why>`\"."
+
+[[check]]
+name = "function-size"
+example = "A Python function exceeding the configured code-line ceiling reports a length finding. Extract a distinct operation with its own responsibility and verify the remaining function and extracted operation."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".py"] }
+summary = "Checks that no Python function has more code lines than the ceiling."
+why = "A function that fills a screen does several things, and a reader has to hold all of them."
+help = "Move one job of the function into a function of its own."
+
+[[check]]
+name = "placeholder-docstrings"
+example = "A function whose docstring merely repeats its name reports a placeholder description. Replace the docstring with the behavior, inputs, and consequential effects that the name does not explain."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".py"] }
+summary = "Finds docstrings that hold a placeholder word, or the name of the function again."
+why = "A docstring that says nothing passes the docstring rule and wastes the line."
+help = "Say what the function does that its name does not, or for whom it exists."
+
+[[check]]
+name = "private-prefix"
+example = "A file-local function with no leading underscore and no public export reports a naming finding. Add the underscore and update its local callers, or declare the actual public contract in the export list."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".py"] }
+summary = "In a module with an export list, checks that every other definition starts with an underscore, and that the list holds no such name."
+why = "A name that is public by accident gets imported, and then it cannot change."
+help = "Add the underscore, or list the name in the export list."
+
+[[check]]
+name = "exports-at-bottom"
+example = "A module with `__all__` before later declarations reports an export-list position finding. Move the export list after those declarations."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".py"] }
+summary = "Checks that the export list is the last statement of its module."
+why = "A reader looks for the public surface in one place."
+help = "Move the export list to the end of the module."
+
+[[check]]
+name = "module-getattr"
+example = "A package exposing names through module-level `__getattr__` reports lazy exports. Import the intended public names explicitly and list them in `__all__`."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".py"] }
+summary = "Finds a module-level `__getattr__`."
+why = "A name that appears only at run time hides from the type checker, the editor, and the reader."
+help = "Import the names and list them."
+
+[[check]]
+name = "package-exports"
+example = "A package export list larger than its configured limit reports the export count. Split unrelated public responsibilities into separate packages or remove unnecessary exports and update consumers."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".py"] }
+summary = "Checks that a package exports no more names than the ceiling."
+why = "A package that exports everything has no surface, so every change to it is a breaking one."
+help = "Split the package, or export fewer names."
+
+[[check]]
+name = "export-order"
+example = "An `__all__` list whose names are not ordered shortest first reports the sorted order. Reorder the list."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".py"] }
+summary = "Checks that the names in the export list go shortest first, alphabetically among names of one length."
+why = "Ruff RUF022 sorts alphabetically; gspot turns it off and sorts shortest first, then alphabetically among names of one length."
+help = "Reorder the names shortest first."
+
+[[check]]
+name = "singletons"
+example = "A module-level service instance created during import reports a singleton finding when settings do not allow it. Construct it in the application entry point and pass the instance to consumers."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".py"] }
+summary = "Finds objects built at import time and kept in a module variable."
+why = "Every importer shares the one instance, and no test gets a fresh one."
+help = "Build the object where the program starts, and pass it in. Accept a reviewed composition file with gspot ignore python/singletons --paths `<glob>` --reason \"`<why>`\"."
+
+[ruff_rules]
+recommended = [
+    "A",
+    "ARG",
+    "ASYNC",
+    "B002",
+    "B003",
+    "B004",
+    "B005",
+    "B006",
+    "B007",
+    "B011",
+    "B012",
+    "B013",
+    "B014",
+    "B015",
+    "B016",
+    "B017",
+    "B019",
+    "B020",
+    "B021",
+    "B022",
+    "B023",
+    "B024",
+    "B025",
+    "B026",
+    "B027",
+    "B029",
+    "B03",
+    "B904",
+    "B91",
+    "BLE",
+    "C4",
+    "COM",
+    "DTZ",
+    "E1",
+    "E4",
+    "E70",
+    "E71",
+    "E72",
+    "E73",
+    "E9",
+    "EXE",
+    "F",
+    "FA",
+    "FLY",
+    "FURB",
+    "G",
+    "ISC",
+    "LOG",
+    "PERF",
+    "PGH",
+    "PIE",
+    "PLE",
+    "PLR01",
+    "PLR02",
+    "PLR04",
+    "PLR1708",
+    "PLR1714",
+    "PLR1716",
+    "PLR204",
+    "PLW01",
+    "PLW02",
+    "PLW04",
+    "PLW0604",
+    "PLW064",
+    "PLW07",
+    "PLW15",
+    "PLW21",
+    "PLW3",
+    "PYI",
+    "Q",
+    "RET501",
+    "RET502",
+    "RSE",
+    "RUF005",
+    "RUF006",
+    "RUF007",
+    "RUF008",
+    "RUF009",
+    "RUF010",
+    "RUF013",
+    "RUF015",
+    "RUF016",
+    "RUF017",
+    "RUF018",
+    "RUF019",
+    "RUF02",
+    "RUF03",
+    "RUF040",
+    "RUF041",
+    "RUF043",
+    "RUF048",
+    "RUF049",
+    "RUF051",
+    "RUF053",
+    "RUF057",
+    "RUF058",
+    "RUF06",
+    "RUF1",
+    "RUF2",
+    "S102",
+    "S103",
+    "S104",
+    "S105",
+    "S106",
+    "S107",
+    "S108",
+    "S11",
+    "S2",
+    "S30",
+    "S310",
+    "S312",
+    "S313",
+    "S314",
+    "S315",
+    "S316",
+    "S317",
+    "S318",
+    "S319",
+    "S32",
+    "S5",
+    "S6",
+    "S7",
+    "SIM101",
+    "SIM102",
+    "SIM103",
+    "SIM105",
+    "SIM107",
+    "SIM109",
+    "SIM110",
+    "SIM112",
+    "SIM113",
+    "SIM115",
+    "SIM118",
+    "SIM2",
+    "SIM4",
+    "SIM9",
+    "T1",
+    "UP",
+    "W",
+    "YTT",
+]
+all = [
+    "ANN",
+    "B008",
+    "B009",
+    "B010",
+    "B018",
+    "B028",
+    "B905",
+    "C9",
+    "D",
+    "D107",
+    "D204",
+    "D212",
+    "D214",
+    "D215",
+    "D400",
+    "D401",
+    "D402",
+    "D404",
+    "D405",
+    "D406",
+    "D407",
+    "D408",
+    "D409",
+    "D410",
+    "D411",
+    "D413",
+    "D415",
+    "D416",
+    "D417",
+    "E5",
+    "E74",
+    "EM",
+    "ERA",
+    "FBT",
+    "FIX",
+    "I",
+    "ICN",
+    "INP",
+    "N",
+    "PLC",
+    "PLR09",
+    "PLR1704",
+    "PLR1711",
+    "PLR172",
+    "PLR173",
+    "PLR200",
+    "PLR5",
+    "PLW0602",
+    "PLW0603",
+    "PLW16",
+    "PLW29",
+    "PTH",
+    "RET503",
+    "RET504",
+    "RET505",
+    "RET506",
+    "RET507",
+    "RET508",
+    "RUF001",
+    "RUF002",
+    "RUF003",
+    "RUF012",
+    "RUF046",
+    "RUF059",
+    "S101",
+    "S311",
+    "SIM108",
+    "SIM114",
+    "SIM116",
+    "SIM117",
+    "SIM3",
+    "SLF",
+    "SLOT",
+    "T2",
+    "TC",
+    "TD",
+    "TRY",
+]
+
+[[naming.override]]
+paths = ["**/__init__.py", "**/__main__.py"]
+categories = ["files"]
+allowed_names = ["__init__", "__main__"]
+reason = "Python names these files."
+languages = ["python"]
+
+[[naming.override]]
+paths = ["**"]
+languages = ["python"]
+categories = ["methods"]
+allowed_names = ["setUp", "setUpClass", "tearDown", "tearDownClass"]
+reason = "unittest discovers its lifecycle methods by these names."
+
+[[naming.override]]
+paths = ["**"]
+languages = ["python"]
+categories = ["functions", "methods", "variables", "constants", "attributes"]
+allowed_names = [
+    "__init__",
+    "__main__",
+    "__all__",
+    "__name__",
+    "__file__",
+    "__dict__",
+    "__slots__",
+    "__repr__",
+    "__str__",
+    "__eq__",
+    "__hash__",
+    "__len__",
+    "__iter__",
+    "__next__",
+    "__enter__",
+    "__exit__",
+    "__call__",
+    "__getitem__",
+    "__setitem__",
+    "__delitem__",
+    "__contains__",
+    "__lt__",
+    "__le__",
+    "__gt__",
+    "__ge__",
+    "__ne__",
+    "__bool__",
+    "__post_init__",
+    "__class_getitem__",
+    "__aenter__",
+    "__aexit__",
+    "__await__",
+    "__aiter__",
+    "__anext__",
+    "__new__",
+    "__spec__",
+    "__package__",
+    "__loader__",
+    "__cached__",
+    "__doc__",
+    "__annotations__",
+    "__path__",
+    "__class__",
+    "__classcell__",
+    "__qualname__",
+    "__builtins__",
+]
+reason = "Python defines these special methods and attributes."
+
+[[naming.override]]
+paths = ["**"]
+languages = ["python"]
+categories = ["functions", "variables", "constants", "methods", "attributes"]
+ignored_prefix = "^_+"
+reason = "A leading underscore marks a private Python declaration."