chore: configure linting for the project

Author: dmcilvaney

.editorconfig

@@ -0,0 +1,8 @@
+# https://EditorConfig.org
+
+root = true
+
+[*]
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true

.github/instructions/python.instructions.md

@@ -0,0 +1,36 @@
+---
+applyTo: "**/*.py"
+description: "ALWAYS read these when reading or modifying Python files. Covers ruff lint/format and pyright type-checking expectations, scope, and the pre-commit workflow."
+---
+
+# Python Files
+
+This repo uses [`ruff`](https://docs.astral.sh/ruff/) for linting/formatting and [`pyright`](https://microsoft.github.io/pyright/) for type checking. Config: [`ruff.toml`](../../ruff.toml), [`pyrightconfig.json`](../../pyrightconfig.json).
+
+## Before committing
+
+After editing any `.py` file, run both checks on the files you touched:
+
+```bash
+ruff check <file>            # add --fix to auto-apply safe fixes
+ruff format <file>            # formatting
+pyright <file>                # type checking
+```
+
+Or check everything at once:
+
+```bash
+ruff check
+pyright
+```
+
+## Expectations
+
+- **Don't introduce new violations.** If `ruff check` or `pyright` reports new errors against files you modified, fix them before committing.
+- **Pre-existing violations** in files you didn't touch are out of scope — leave them for whoever next edits that file.
+- **Auto-fixes** (`ruff check --fix`) are safe to apply on files you're already editing. Review the diff before committing.
+- **`# noqa` and `# type: ignore` comments** require a justification comment on the same line (e.g. `# noqa: F401 — re-exported`) and should be used extremely sparingly.
+
+## Scope
+
+Both tools currently scan: `.github/`, `base/`, `scripts/`. Generated/vendored paths (`base/build`, `base/out`, `specs`, `**/__pycache__`, `**/.venv`, `**/venv`, `**/node_modules`) are excluded.

.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+    "recommendations": [
+        "charliermarsh.ruff",
+        "editorconfig.editorconfig",
+        "DavidAnson.vscode-markdownlint",
+        "timonwong.shellcheck",
+        "ms-python.vscode-pylance"
+    ]
+}

.vscode/settings.json

@@ -3,7 +3,8 @@
     // These files should not be manually edited — modify the TOML sources instead.
     // Prevent accidental edits to rendered specs.
     "files.readonlyInclude": {
-        "specs/**": true
+        "specs/**": true,
+        "locks/**": true
     },
     // Suppress diagnostics from rendered specs — they are not source files.
     // Unfortunately, vscode does not provide a way to exclude all problem
@@ -13,16 +14,45 @@
     "shellcheck.ignorePatterns": {
         "specs/**": true
     },
-    "python.analysis.exclude": [
-        "specs",
-        "**/node_modules",
-        "**/__pycache__",
-        "**/.*"
-    ],
     // Using Azure Pipelines schema for validation of ADO YAMLs.
     "azure-pipelines.1ESPipelineTemplatesSchemaFile": true,
     // Associate ADO pipelines with the "azure-pipelines" type instead of GitHub Actions.
     "files.associations": {
         "**/.github/workflows/ado/**/*.yml": "azure-pipelines"
-    }
+    },
+    // General lint rules
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+        "source.fixAll.markdownlint": "explicit",
+        "source.fixAll.shellcheck": "explicit"
+    },
+    "shellcheck.enable": true,
+    "shellcheck.enableQuickFix": true,
+    // Lint rules for python
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "explicit",
+            "source.organizeImports.ruff": "explicit",
+            "source.fixAll": "explicit",
+            "source.fixAll.pylance": "explicit"
+        }
+    },
+    "python.analysis.diagnosticsSource": "Pylance",
+    "python.missingPackage.severity": "Error",
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "python.analysis.exclude": [
+        "**/node_modules",
+        "**/__pycache__",
+        "**/.*",
+        "specs",
+        "base/build"
+    ],
+    "python.analysis.include": [
+        ".github"
+    ],
+    "ruff.configuration": "${workspaceFolder}/ruff.toml",
+    "ruff.lint.enable": true
 }

pyrightconfig.json

@@ -0,0 +1,19 @@
+{
+    "exclude": [
+        "**/node_modules",
+        "**/__pycache__",
+        "**/.venv",
+        "**/venv",
+        "base/build",
+        "base/out",
+        "specs"
+    ],
+    "typeCheckingMode": "standard",
+    "pythonVersion": "3.12",
+    "pythonPlatform": "Linux",
+    "reportUntypedFunctionDecorator": "error",
+    "reportMissingTypeStubs": "warning",
+    "reportMissingParameterType": "error",
+    "reportMissingTypeArgument": "error",
+    "reportUnknownParameterType": "error"
+}

ruff.toml

@@ -0,0 +1,26 @@
+extend-exclude = ["base/build", "base/out", "specs"]
+
+line-length = 120
+
+target-version = "py312"
+
+[lint]
+select = ["ALL"] # Everything
+ignore = [
+    "COM812", # Conflicts with formatter.
+    "S603",   # Check for validation of input to subprocess calls, almost always a false positive
+    "S607",   # Requiring abspath for all binaries used is very restrictive
+    "T201",   # These scripts are fine to use `print` for output
+]
+
+# We want D401 still, even though google style omits it.
+extend-select = ["D401"]
+
+fixable = ["ALL"]
+
+[lint.isort]
+# Just force this, its better than dealing with a mishmash of modules that have annotations and those that don't
+required-imports = ["from __future__ import annotations"]
+
+[lint.pydocstyle]
+convention = "google"