code-standards 7.0.0__py3-none-any.whl

sarj_standards/configs/markdownlint.strict.yaml

@@ -0,0 +1,12 @@
+# Sarj strict Markdown lint configuration for markdownlint / markdownlint-cli2
+default: true
+MD013: false # Line length (handled by text editor / formatter)
+MD033: false # Allow inline HTML when necessary (e.g., details/summary, alerts)
+MD041: false # First line in file does not strictly need to be top-level heading (for snippets/partials)
+MD024:
+  siblings_only: true # Allow duplicate heading names in different sections
+MD029:
+  style: "ordered"
+MD040: true # Require language specified on fenced code blocks
+MD053:
+  ignored_definitions: [] # Treat pseudo-reference comments as removable unused definitions.

sarj_standards/configs/pyright.strict.json

@@ -0,0 +1,96 @@
+{
+  // Maximally-strict pyright / basedpyright config.
+  //
+  // MUST be JSON(C), not TOML: pyright's `extends` silently ignores a bare-key
+  // .toml file (it loads JSON only), so a .toml strict config never actually
+  // applies — the type checker just runs on its defaults. JSONC keeps comments.
+  "typeCheckingMode": "strict",
+  "strictListInference": true,
+  "strictDictionaryInference": true,
+  "strictSetInference": true,
+  "strictParameterNoneValue": true,
+  "deprecateTypingAliases": true,
+  "enableExperimentalFeatures": false,
+
+  "reportUnusedImport": "error",
+  "reportUnusedVariable": "error",
+  "reportDeprecated": "error",
+  // Off: FastAPI/Starlette route handler functions (@router.get, etc.) are called
+  // via framework dispatch, not direct module invocations.
+  "reportUnusedFunction": false,
+  // Off: third-party untyped SDKs (e.g. google.cloud.pubsub_v1, psycopg) cause workspace-wide noise.
+  "reportMissingTypeStubs": false,
+
+  "reportUnknownMemberType": "error",
+  "reportUnknownParameterType": "error",
+  "reportMissingParameterType": "error",
+  "reportUnknownVariableType": "error",
+  "reportUnknownArgumentType": "error",
+  "reportMissingTypeArgument": "error",
+  "reportUnknownLambdaType": "error",
+  "reportUnusedClass": "error",
+  // Fires on every builder/fluent call (argparse.add_argument, query builders, …)
+  // where the returned handle is intentionally discarded — noise, not type safety.
+  "reportUnusedCallResult": false,
+  "reportUnusedCoroutine": "error",
+
+  "reportUnnecessaryIsInstance": "error",
+  // Exhaustive match fallbacks are required by SARJ032 and remain useful to
+  // runtime checkers when a type grows, so they are not unnecessary branches.
+  "reportUnnecessaryComparison": "none",
+  "reportUnnecessaryCast": "error",
+  "reportUnnecessaryContains": "error",
+  "reportConstantRedefinition": "error",
+  "reportCallIssue": "error",
+  "reportMatchNotExhaustive": "error",
+  "reportUntypedFunctionDecorator": "error",
+  "reportUnnecessaryTypeIgnoreComment": "error",
+  "reportReturnType": "error",
+  "reportPropertyTypeMismatch": "error",
+  "reportArgumentType": "error",
+  // reportPrivateUsage stays at error. Pyright resolves the declaring class and
+  // catches private base-class access that syntax-only checks cannot see, but it
+  // cannot distinguish first-party modules from dependency implementation APIs.
+  // A necessary dependency-boundary reach therefore needs a reasoned line-level
+  // suppression; disabling the check would also hide actionable local defects.
+  "reportPrivateUsage": "error",
+  // Pin strict-mode defaults that define module API visibility. Explicit keys
+  // keep upgrades from silently weakening private imports or dynamic exports.
+  "reportPrivateImportUsage": "error",
+  "reportUnsupportedDunderAll": "error",
+  // Off: low value — forcing `@override` on every `ast.NodeVisitor.visit_*` hook
+  // (and similar framework dispatch methods) is noise, not safety.
+  "reportImplicitOverride": false,
+  // Off: ruff owns string-concat style. ruff's ISC003 forbids explicit `+` of
+  // string literals (prefers implicit), which directly contradicts flagging
+  // implicit concatenation here — the two cannot both be satisfied. ruff's ISC001
+  // still catches the dangerous single-line "missing comma" accident.
+  "reportImplicitStringConcatenation": "none",
+  // (reportShadowedImports was removed from pyright upstream — pyright 1.1.411
+  //  AND basedpyright both reject it as unrecognized; basedpyright likewise
+  //  rejects reportInvalidExceptionType — so both are omitted to keep every
+  //  checker's output clean.)
+  "reportMissingSuperCall": "error",
+  "reportUninitializedInstanceVariable": "error",
+  "reportInconsistentConstructor": "error",
+  "reportInvalidStubStatement": "error",
+  "reportSelfClsParameterName": "error",
+  "reportTypeCommentUsage": "error",
+  // basedpyright-only (8 keys): reportInvalidCast, reportUnsafeMultipleInheritance,
+  // reportImplicitRelativeImport, reportExplicitAny, reportIgnoreCommentWithoutRule,
+  // reportPrivateLocalImportUsage, reportAny, reportUnannotatedClassAttribute.
+  // Plain pyright (verified on 1.1.411) prints `Config contains unrecognized
+  // setting "<key>"` once per key and then IGNORES it — the run still exits 0
+  // with "0 errors". The warnings are cosmetic; the keys stay because
+  // basedpyright is the canonical checker and dropping them would silently
+  // weaken it. Consumers on plain pyright lose only these eight checks.
+  "reportInvalidCast": "error",
+  "reportUnsafeMultipleInheritance": "error",
+  "reportImplicitRelativeImport": "error",
+  "reportUnreachable": "error",
+  "reportExplicitAny": "error",
+  "reportIgnoreCommentWithoutRule": "error",
+  "reportPrivateLocalImportUsage": "error",
+  "reportAny": "error",
+  "reportUnannotatedClassAttribute": "error"
+}

sarj_standards/configs/ruff.application.toml

@@ -0,0 +1,363 @@
+# Shared strict Ruff policy. Comments document durable behavior and compatibility
+# constraints; repository-specific evaluation evidence stays outside the package.
+line-length = 120
+extend-exclude = ["sdk"]
+
+[format]
+quote-style              = "double"
+indent-style             = "space"
+skip-magic-trailing-comma = false
+line-ending              = "auto"
+# Markdown has its own canonical linter. Ruff 0.16+ otherwise reformats Python
+# fences in existing prose when a repository runs `ruff format .`.
+exclude                  = ["*.md"]
+
+[lint]
+select = ["ALL"]
+external = ["SARJ"]
+preview = true
+# Let Ruff's native UP037 own quoted annotations, including TYPE_CHECKING-only
+# imports. Its fix is intentionally unsafe when it must change annotation
+# evaluation semantics, so consumer baselines can grandfather existing debt.
+future-annotations = true
+logger-objects = ["loguru.logger"]  # treat loguru as a logger so G004/G010 fire on it (the house logger)
+# TC001/2/3 stay advisory but are never auto-applied: their unsafe fixes can
+# move runtime-evaluated framework annotations into `TYPE_CHECKING`, changing
+# behavior under deferred annotations. Marking them unfixable preserves the
+# warning without applying a potentially breaking rewrite.
+unfixable = ["TC001", "TC002", "TC003"]
+
+extend-select = [
+  "ANN401",
+  "RUF013",
+  "RUF022",
+  "RUF023",
+  "RUF052",
+  "TC001",
+  "TC002",
+  "TC003",
+
+  "UP041",
+  "UP045",
+  "UP046",
+  "UP047",
+  "UP049",
+
+  "FURB101",
+  "FURB103",
+  "FURB113",
+  "FURB118",
+  "FURB148",
+  "FURB152",
+  "FURB154",
+  "FURB163",
+  "FURB166",
+  "FURB171",
+  "FURB177",
+  "FURB180",
+  "FURB192",
+
+  "ASYNC100",
+  "ASYNC105",
+  "ASYNC109",
+
+  "B904",
+  "S112",
+  "TRY400",
+  "TRY401",
+
+  "ASYNC210",
+  "ASYNC220",
+  "ASYNC230",
+  "ASYNC251",
+  "PERF402",
+  "SIM117",
+
+  "PT006",
+  "PT007",
+  "PT009",
+  "PT011",
+  "PT012",
+
+  "FAST001",
+  "FAST002",
+  "FAST003",
+
+  "LOG001",
+  "LOG002",
+  "LOG007",
+  "LOG009",
+  "LOG015",
+  "G010",
+
+  "FBT001",
+  "FBT002",
+  "FBT003",
+]
+
+# The ignore list is derived from rule semantics rather than consumer
+# suppressions. Security, naming, and correctness checks remain enabled unless a
+# narrower authority owns the concern or the rule conflicts with the formatter.
+# The D/DOC block below documents the deliberate docstring policy.
+ignore = [
+  # Every entry below has a durable semantic reason. Builtin-shadowing checks
+  # remain enabled, while assertion and hardcoded-secret checks are scoped to
+  # tests instead of being disabled repository-wide.
+
+  # Sarj owns these comment concerns with narrower, syntax-aware rules and
+  # tracked-reference exemptions. Ruff's generic variants double-report
+  # commented code and reject even ticket-backed TODOs.
+  "ERA001",
+  "FIX002",
+  "TD002",
+  "TD003",
+  "TD004",
+
+  # Complexity thresholds are heuristics rather than correctness rules. These
+  # limits conflict with enforced guard-clause style, penalize branching that is
+  # intrinsic to visitors and dispatchers, and count keyword-only parameters.
+  # Narrower checks still catch deeply nested code and positional-argument
+  # explosion without imposing arbitrary function-size ceilings.
+  "C901",
+  "PLR0911",
+  "PLR0912",
+  "PLR0913",
+  "PLR0915",
+
+  # DOCSTRINGS: the standard is LESS PROSE, NOT MORE. Code documents itself;
+  # a docstring earns its place by saying something the signature cannot.
+  #
+  # The dividing line, applied to every D/DOC rule:
+  #   KEPT     — rules that DELETE prose, or catch a docstring contradicting the code
+  #   IGNORED  — rules that DEMAND prose, or tax the wording of prose already written
+  #
+  # An earlier version of this file enforced the whole family and said so
+  # ("the docstring-punctuation family ... are now ENFORCED"). That put the
+  # config in direct conflict with this repo's own rules: DOC201 REQUIRES a
+  # `Returns:` section restating the return annotation, while SARJ050
+  # `redundant-docstring` and `no-restated-comment` exist to DELETE prose that
+  # restates the signature. The linter was manufacturing the exact noise the
+  # custom rules were written to remove, and every author paid the tax.
+
+  # Missing docstrings are not a defect.
+  "D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107",
+
+  # Mutually-exclusive pairs: ruff requires one of each to be off.
+  "D203",
+  "D213",
+
+  # DEMAND MORE PROSE. These make a machine ask for text that the signature,
+  # the type annotations and the `raise` statements already carry.
+  "D417",    # undocumented-param        — describe every argument
+  "DOC201",  # docstring-missing-returns — describe the return
+  "DOC402",  # docstring-missing-yields  — describe the yield
+  "DOC501",  # docstring-missing-exception
+
+  # WORDING AND SECTION CEREMONY. None of these catch a defect; they tax someone
+  # for writing a short useful sentence, which is the sentence most worth having.
+  "D200",    # one-line docstring should fit on one line
+  "D205",    # blank line required between summary and description
+  "D400",    # first line should end with a period
+  "D401",    # first line should be in imperative mood ("gets" -> "Get")
+  "D403",    # first word should be capitalized
+  "D404",    # first word should not be "This"
+  "D405", "D406", "D407", "D408", "D409",  # section name / underline formatting
+  "D410", "D411", "D412", "D413",          # blank lines around sections
+  "D415",    # first line should end with terminal punctuation
+  "D416",    # section name should end with a colon
+  "D420",    # section order
+  "D421",    # property docstring should not start with a verb
+
+  # DELIBERATELY STILL ENFORCED — every one of these REMOVES text or catches a
+  # docstring that lies about the code, so they pull the same direction as the
+  # rules above rather than against them:
+  #   D402  first line is the function's signature      (pure restatement)
+  #   D414  section has no content                      (empty `Returns:`)
+  #   D418  @overload carrying a docstring
+  #   D419  empty docstring
+  #   DOC102 documented parameter not in the signature  (docstring lies)
+  #   DOC202 `Returns:` on a function that returns nothing
+  #   DOC403 `Yields:` on a function that never yields
+  #   DOC502 documented exception that is never raised
+  # Also kept: D201/D202/D206-D212/D300/D301 — mechanical whitespace and quote
+  # style, formatter-adjacent, no prose implications.
+  # CPY001 requires per-file headers even when licensing is declared at the
+  # package or repository level. The shared policy does not mandate duplicate
+  # copyright prose in every source file.
+  "CPY001",
+
+  # COM812 conflicts with the formatter. Reproduced, not assumed: on
+  # packages/iac/src/sarj_iac_lint/_hcl.py — a file `ruff format --check` calls
+  # already formatted — COM812 reports two sites, and applying its fix makes the
+  # same file format-dirty, because the comma it adds is a magic trailing comma
+  # and the formatter then explodes `_parse_body`'s parameters one per line.
+  # `skip-magic-trailing-comma = false` above is what makes that bite.
+  "COM812",
+
+  # E501 is the formatter's job. Content that remains long after formatting is
+  # generally an unsplittable literal, URL, or message; manually altering it
+  # would not improve code structure.
+  "E501",
+
+  # RUF001 rejects legitimate characters in multilingual user-facing text.
+  # `allowed-confusables` cannot express a whole writing system safely, so this
+  # shared policy does not treat non-ASCII product copy as suspicious by default.
+  "RUF001",
+
+  # PLC2701 is replaced by SARJ048 because lexical underscores cannot
+  # distinguish first-party private imports from dependency implementation
+  # imports. SARJ048 resolves modules against the project tree and reports only
+  # first-party boundaries. Consumers without the Sarj Python hooks should
+  # re-enable PLC2701 rather than leaving this concern unchecked.
+  "PLC2701",
+]
+
+# SLF001 stays enabled, with a documented limitation: Ruff cannot determine
+# whether an underscored attribute belongs to first-party or dependency code.
+# Dependency-boundary access therefore requires an inline, reasoned suppression;
+# projects with adapter layers may scope that exception locally. Pyright's
+# reportPrivateUsage remains independent and may require its own line-level
+# explanation.
+
+[lint.isort]
+force-single-line          = false
+lines-after-imports        = 2
+force-sort-within-sections = true
+
+# Under PEP 649 (py314) plain annotations are lazy, so TC001-003 moving their
+# imports into `TYPE_CHECKING` is safe — EXCEPT for constructs that eagerly read
+# `__annotations__` at class-creation time (pydantic models/settings, dataclasses,
+# NamedTuple, TypedDict) and FastAPI route decorators that resolve body/param
+# models at request time. Listing them stops TC001-003 from flagging (and its
+# unsafe fix from breaking) their field-type imports.
+[lint.flake8-type-checking]
+runtime-evaluated-base-classes = [
+  "pydantic.BaseModel",
+  "pydantic_settings.BaseSettings",
+  "typing.NamedTuple",
+  "typing.TypedDict",
+]
+runtime-evaluated-decorators = [
+  "pydantic.dataclasses.dataclass",
+  "dataclasses.dataclass",
+  "fastapi.APIRouter.post",
+  "fastapi.APIRouter.get",
+  "fastapi.APIRouter.put",
+  "fastapi.APIRouter.delete",
+  "fastapi.APIRouter.patch",
+  "fastapi.APIRouter.head",
+  "fastapi.APIRouter.options",
+  "fastapi.APIRouter.trace",
+  "fastapi.APIRouter.websocket",
+  "fastapi.APIRouter.api_route",
+  "fastapi.FastAPI.post",
+  "fastapi.FastAPI.get",
+  "fastapi.FastAPI.put",
+  "fastapi.FastAPI.delete",
+  "fastapi.FastAPI.patch",
+  "fastapi.FastAPI.head",
+  "fastapi.FastAPI.options",
+  "fastapi.FastAPI.trace",
+  "fastapi.FastAPI.websocket",
+  "fastapi.FastAPI.api_route",
+]
+
+[lint.flake8-pytest-style]
+# PT011's defaults omit RuntimeError even though a broad RuntimeError assertion
+# can pass for the wrong failure. Include it with Ruff's defaults. Protocol
+# exceptions such as AttributeError and TypeError remain excluded because their
+# interpreter-owned messages are version-sensitive.
+raises-require-match-for = [
+  "BaseException",
+  "Exception",
+  "ValueError",
+  "OSError",
+  "IOError",
+  "EnvironmentError",
+  "RuntimeError",
+  "socket.error",
+]
+
+# PT030's defaults cover only Warning, UserWarning, and DeprecationWarning.
+# The remaining broad built-in warning categories have the same false-pass risk:
+# an unrelated warning from the code under test can satisfy pytest.warns(). Keep
+# project-owned warning subclasses exempt because their type is already specific.
+warns-extend-require-match-for = [
+  "BytesWarning",
+  "EncodingWarning",
+  "FutureWarning",
+  "ImportWarning",
+  "PendingDeprecationWarning",
+  "ResourceWarning",
+  "RuntimeWarning",
+  "SyntaxWarning",
+  "UnicodeWarning",
+]
+
+[lint.flake8-tidy-imports.banned-api]
+"unittest.mock.Mock".msg              = "Prefer real fixtures or hand-rolled fakes implementing the relevant ABC. If a mock is genuinely required, import with `# noqa: TID251 — <reason>`."
+"unittest.mock.AsyncMock".msg         = "Same as Mock."
+"unittest.mock.MagicMock".msg         = "Same as Mock."
+"unittest.mock.patch".msg             = "Prefer dependency injection via fixtures over monkey-patching."
+"pytest_mock".msg                     = "pytest-mock's `mocker` fixture is unittest.mock with a different spelling — it bypasses the mock bans above without any noqa trail. Use real fixtures/fakes; for a genuine external boundary use `from unittest import mock` + inline `# noqa: TID251 — <reason>`."
+
+"datetime.datetime.utcnow".msg        = "Deprecated in Python 3.12. Use `datetime.now(UTC)`."
+"pickle.load".msg                     = "Pickle deserializes arbitrary objects and is unsafe on untrusted input. Use JSON via Pydantic, or msgspec/orjson."
+"pickle.loads".msg                    = "Same — pickle is unsafe."
+
+"os.environ".msg                      = "Use a Pydantic Settings class instead. If you genuinely need raw os.environ, add `# noqa: TID251 — <reason>` inline."
+"os.getenv".msg                       = "Same — use a Pydantic Settings class instead of os.getenv."
+
+"fastapi.UploadFile".msg              = "Use a pre-signed URL so the client uploads directly to object storage."
+"pydantic.alias_generators.to_camel".msg = "Don't camelCase API contracts in the backend. Keep snake_case; transform on the frontend with Zod."
+"typing.cast".msg                     = "Prefer discriminated unions or `isinstance` narrowing over `cast`."
+"psycopg.sql.Literal".msg             = "Use parameterized queries (psycopg's `%s` placeholders) instead of sql.Literal."
+"uuid.uuid4".msg                      = "Use uuid.uuid7() — time-ordered, aligns with the DB uuidv7() default. For unguessable secrets use secrets.token_urlsafe(), not a UUID."
+
+# Generated application-profile library policy. Edit the catalog, not this file.
+"aioredis".msg = "LIB020: aioredis was merged into redis-py; use redis.asyncio. Replace with redis.asyncio."
+"argparse".msg = "LIB001: The application profile standardizes command-line interfaces on Typer. Replace with Typer."
+"backports.cached_property".msg = "LIB018: Python 3.14 provides functools.cached_property. Replace with functools.cached_property."
+"backports.zoneinfo".msg = "LIB012: Python 3.14 provides zoneinfo. Replace with zoneinfo."
+"boto".msg = "LIB019: Boto 2 is obsolete; migrate to boto3 and review API differences. Replace with boto3."
+"cerberus".msg = "LIB007: The application profile standardizes validation and serialization on Pydantic. Replace with Pydantic."
+"click".msg = "LIB002: Use Typer for typed command-line interfaces instead of direct Click APIs. Replace with Typer."
+"enum34".msg = "LIB016: Remove the obsolete enum34 backport on Python 3.14. Replace with enum."
+"flask".msg = "LIB006: The application profile standardizes HTTP APIs on FastAPI; this is an architectural migration. Replace with FastAPI."
+"futures".msg = "LIB017: Remove the obsolete futures backport on Python 3.14. Replace with concurrent.futures."
+"importlib_metadata".msg = "LIB013: Python 3.14 provides importlib.metadata. Replace with importlib.metadata."
+"importlib_resources".msg = "LIB014: Python 3.14 provides importlib.resources. Replace with importlib.resources."
+"marshmallow".msg = "LIB007: The application profile standardizes validation and serialization on Pydantic. Replace with Pydantic."
+"mock".msg = "LIB022: Python 3.14 provides unittest.mock. Replace with unittest.mock."
+"nose".msg = "LIB021: Nose is unmaintained; use pytest. Replace with pytest."
+"optparse".msg = "LIB001: The application profile standardizes command-line interfaces on Typer. Replace with Typer."
+"pandas".msg = "LIB003: Use Polars; migration must account for its expressions and lack of a pandas index model. Replace with Polars."
+"pathlib2".msg = "LIB011: Python 3.14 provides pathlib. Replace with pathlib."
+"pkg_resources".msg = "LIB009: Do not use pkg_resources; choose the focused importlib or packaging API. Replace with importlib.metadata/importlib.resources/packaging."
+"pytz".msg = "LIB008: Use zoneinfo; explicitly review DST ambiguity, localization, and fold behavior. Replace with zoneinfo."
+"requests".msg = "LIB004: Use HTTPX; review timeout defaults, exception types, streaming, and client lifetimes. Replace with HTTPX."
+"tomli".msg = "LIB010: Python 3.14 provides tomllib. Replace with tomllib."
+"ujson".msg = "LIB005: Use orjson; its dumps function returns bytes and option semantics differ. Replace with orjson."
+
+[lint.per-file-ignores]
+# Tests legitimately assert, use fixtures and magic values, and invoke the
+# binary under test. Scope those exemptions to test paths so assertion and
+# hardcoded-secret checks remain active in shipped code. Test trees also need
+# not be importable packages, and deterministic test PRNG use is not a secret
+# generation risk.
+"**/tests/**"             = ["S101", "S105", "S106", "S311", "INP001", "FBT001", "FBT002", "FBT003", "PLR2004", "S404", "S603", "S607", "PLR6301"]
+"**/test/**"              = ["S311"]
+"**/integration_tests/**" = ["S311"]
+# A test-named module outside a test tree is still test code.
+"**/test_*.py"            = ["ANN201", "ANN202", "S101", "S105", "S106", "S311", "INP001"]
+"**/*_test.py"            = ["S311"]
+"**/conftest.py"          = ["S101", "S105", "S106", "S311", "INP001"]
+# Standalone scripts are not importable packages, so INP001 does not apply.
+"scripts/**"      = ["T201", "S", "BLE001", "TRY002", "INP001"]
+# CLI entrypoints print to stdout — that's their job, not stray debug output.
+"**/__main__.py"  = ["T201"]
+"**/cli/**/*.py"  = ["T201"]
+# NOTE: `"__init__.py" = []` and `"**/settings.py" = []` used to sit here. Ruff
+# per-file-ignores are additive and an empty list cannot un-ignore anything, so
+# both entries were no-ops; they are removed rather than left as config that
+# reads like an exemption.