atlan-application-sdk-conformance 0.2.0__py3-none-any.whl

atlan_application_sdk_conformance-0.2.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: atlan-application-sdk-conformance
+Version: 0.2.0
+Summary: Conformance suite, remediation programs, and CLI for the Atlan Application SDK
+Author-email: Atlan App Team <connect@atlan.com>
+License-Expression: Apache-2.0
+Keywords: atlan,conformance,linting,remediation,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: jsonschema<5.0.0,>=4.23.0
+Requires-Dist: pydantic<3.0.0,>=2.10.6
+Provides-Extra: test
+Requires-Dist: atlan-application-sdk; extra == 'test'
+Requires-Dist: pytest-asyncio<2.0.0,>=1.4.0; extra == 'test'
+Requires-Dist: pytest<10.0.0,>=8.3.3; extra == 'test'
+Description-Content-Type: text/markdown
+
+# atlan-application-sdk-conformance
+
+Dev-only conformance suite, remediation programs, and CLI for the
+[Atlan Application SDK](https://pypi.org/project/atlan-application-sdk/).
+
+**Do not add this as a production dependency.** It is intended for developer
+machines and CI only.
+
+## Installation
+
+```bash
+uv add --dev atlan-application-sdk-conformance
+```
+
+## Usage
+
+```bash
+# Run the conformance suite
+uv run atlan-application-sdk-conformance detect --repo . --series E,L,C --output report.sarif
+
+# Get the path to bundled remediation programs (for SKILL.md / reactor)
+uv run atlan-application-sdk-conformance programs-dir
+
+# Regenerate rule docs
+uv run atlan-application-sdk-conformance gen-rule-docs
+```
+
+## In CI
+
+Consumer repos should reference this package via the reusable workflow in
+`atlanhq/application-sdk`:
+
+```yaml
+uses: atlanhq/application-sdk/.github/workflows/conformance-reusable.yaml@main
+# No inputs required — the published PyPI package is used by default.
+```
+
+See `conformance/programs/conformance-remediation.prose.md` for the
+`/remediate` skill entry contract.

atlan_application_sdk_conformance-0.2.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+conformance/__init__.py,sha256=f5ihJyNJuyw1MkpgTuPWdcf1jsksR2lpGnE3FJg1S7Y,199
+conformance/cli.py,sha256=ZaQ2CUbHhHo19S9T0tx6YD7NHOpihZDsItQ6_X9fs_U,4013
+conformance/package-lock.json,sha256=F8EwDEjecgD82OM19F1YGdtrVvPOzIVAaJI5JdeMKtw,58365
+conformance/package.json,sha256=egDs4ZNoIpfJiGKlOD95egYFDoc53fGcEqDxOp8VBa8,463
+conformance/docs/schema-contract.md,sha256=v8g3hDvzH_yNgbZ3t9ZXY483wkI8JnnWuWQK_uQbpa4,11859
+conformance/docs/rules/ci.md,sha256=PlEiRfDNaybMzbvDEepCmrbS4yy1XPfahhg3jCeqngw,1229
+conformance/docs/rules/error-handling.md,sha256=Z40cuoBPXZD2UNK0qoJeme5Xg1xUCihClUyECuNdomM,12648
+conformance/docs/rules/logging.md,sha256=fqnpi_bhgyFzWlimGUND8WanqKsVN0IhkexL3bGtjZA,11301
+conformance/programs/conformance-remediation.prose.md,sha256=eYCuS_I5iUAr34UjdbvHPUBoSva5m1Eva_Lz9lZK1Mg,2812
+conformance/programs/areas/ci.prose.md,sha256=08LhyngT5KbG1SMLNnddRs5v3qz0uaeJbZ9GVb5pa1w,1390
+conformance/programs/areas/error-handling.prose.md,sha256=xPoDR7uvmtqoAFLfLLrA6JbryjnK5B1rCTHERrwV1FA,1792
+conformance/programs/areas/logging.prose.md,sha256=6-6NtipMJYm4m7zaoUKD4YLnipenUfnzMRbyBWCeVhI,1407
+conformance/programs/functions/detect-violations.prose.md,sha256=VEYLrb4GetCOllUgnO7Nv48Mt14EkrX0ZCGyrU3tfjk,4544
+conformance/programs/functions/orthogonal-gate.prose.md,sha256=t55UmBgQazvkEBj-w4krZ5PISYKLMVG_9wBg6mu2QgQ,1298
+conformance/programs/functions/recheck-narrowest.prose.md,sha256=T2AKpo0t8a91i8RXKFd_1k5L8V242Vn7LEMo-MsDRdg,1895
+conformance/programs/functions/remediate-finding.prose.md,sha256=MG_m_PImjSJLrbhvuQr6rQaki6X8FXoHq3EK5v61xrQ,5376
+conformance/programs/patterns/detect-fix-recheck.prose.md,sha256=IM_dSjpY-9bHz9Fn0p2mA-lRiiGzrU5JIcBNK4opj4U,3795
+conformance/suite/__init__.py,sha256=Xi1PgHR4r2UpvFwCaHXLbzumDWm8mv6sLp_thsDHutk,885
+conformance/suite/runner.py,sha256=Pm7aC2jW-2WxrnK6nb0xFyDSgbIinx_NnukM5LKZ2hI,8502
+conformance/suite/checks/__init__.py,sha256=yTctRyi-506ulQ-KXjYBuJ7Z_rl7alyaZm_07XF2rzk,69
+conformance/suite/checks/actions_pinning.py,sha256=zeQbbX30AuU0eGQV0i2bsju7oKHgTWhFwQeOvZvwtAE,6233
+conformance/suite/checks/error_handling/__init__.py,sha256=5bjyvqdWlG1BNpGpUKhtvueje_B62KHtqi7afWG4TkU,6628
+conformance/suite/checks/error_handling/_checker.py,sha256=rWUAOWfleKZIcp1LS7hyYrspB4kc8hzYhDVNIyuUOKA,5884
+conformance/suite/checks/error_handling/_collect.py,sha256=pwlG2cpOakvtQzZuAjDxyHuQKBW1wPj00ClWcOLmFrk,1420
+conformance/suite/checks/error_handling/_constants.py,sha256=3rCAoaS2gT8DY0HUkgXtDr-xB9qYs5TJQdWb8rGF08I,3462
+conformance/suite/checks/error_handling/_directives.py,sha256=Vam0noPsaxUZS6UBT6kN74-RaLMoTIAiBvwJfrYEMkQ,5452
+conformance/suite/checks/error_handling/_helpers.py,sha256=crgvWd0HCg7eMnC3FfvHvuGLE88qFSltrIa_7gQDyAE,7101
+conformance/suite/checks/error_handling/exception_chaining.py,sha256=GR56sA2vnk5Ke4u6Gv16dd6aouzhPZz79pxQdoNrWWU,2385
+conformance/suite/checks/error_handling/security.py,sha256=HCLvFBo63W8N4K4qouc6TLDX5Buy1ismvMlQpD5waWc,2066
+conformance/suite/checks/error_handling/silent_swallow.py,sha256=ywvst6fcKOuCbfBC8umH25WMgVG1Nm3AIcZSkZ093VU,13969
+conformance/suite/checks/error_handling/untyped_raise.py,sha256=93mTp2MYMKwTmvEk7QOLxLQ5jF7HIBRyj006XgmQJdU,4611
+conformance/suite/rules/__init__.py,sha256=BUpntBeRsAVXRC1fyHhrxjjZmVp1KNXOGkDj1vcaWYg,1582
+conformance/suite/rules/ci.py,sha256=YoDDR2a26kGxZRYIeiE6yMza_DWxxu301Hp1EfJSxb8,1159
+conformance/suite/rules/error_handling.py,sha256=dwCWFdRp4ZE5iKqU-WUgWzFzd4IziVzA4u49mkbr-G0,18091
+conformance/suite/rules/logging.py,sha256=KjW4tM5P1uFdtbdq5XL8b9HONcENt31e_-bxNrjPgwM,15925
+conformance/suite/schema/__init__.py,sha256=hlr9LDcKxxChzADqdET8EOYFXgklqE0ewjP6hvOqEmQ,2048
+conformance/suite/schema/builder.py,sha256=DCGPa_3hy_C6JXCGiMg7A49lPAHvuYcdH4FC8PDyV78,11323
+conformance/suite/schema/catalog.py,sha256=8Yj_96zE0U8ORYTjlq9sLN-7T8K5-0SwTRl79NEDX9Q,4046
+conformance/suite/schema/disposition.py,sha256=YMlzNwnrWp4BaMUI6V4IiOogPoVdK-hWWeZLZLyA9C0,5770
+conformance/suite/schema/extensions.py,sha256=dEXl2ZM-UDIxtMQF258duYx8iQrtJpPfIepEdi_l0dY,6547
+conformance/suite/schema/findings.py,sha256=AJaN3S7I3MKPmJ8nGHK6qlpqXhOuPJJtH9Yg7g8wQjA,2330
+conformance/suite/schema/sarif-schema-2.1.0.json,sha256=fJaI8KHEpOFknsx4UhCH5mRynB3_Vu6CEv8ZXHsWEyo,111720
+conformance/suite/schema/sarif.py,sha256=gokZ_e-N2VK_rJRWAYdhjW75vPuLtyrJ9Sct8mFnrW4,11276
+conformance/suite/schema/validate.py,sha256=GpiJG-mdeisIc6nOqMBef6xrvWqTtoiEmiZz32N56xw,2112
+conformance/tools/generate_rule_docs.py,sha256=lJpAcjzQEQiCLkWU6KXHHiblzok0nHLWgTpk2vFxDuI,9717
+atlan_application_sdk_conformance-0.2.0.dist-info/METADATA,sha256=Sd-evkrO9bxMShgdSgOlzNOAqgzQeaT-DFththjZuQw,2166
+atlan_application_sdk_conformance-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+atlan_application_sdk_conformance-0.2.0.dist-info/entry_points.txt,sha256=qpEna_KV_1dF4C4Gdsv4ysCYT33OR8KuVS18PMBTJZ8,75
+atlan_application_sdk_conformance-0.2.0.dist-info/RECORD,,

atlan_application_sdk_conformance-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

atlan_application_sdk_conformance-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+atlan-application-sdk-conformance = conformance.cli:main

conformance/__init__.py

@@ -0,0 +1,7 @@
+"""Atlan Application SDK Conformance Suite.
+
+Dev-only package.  Provides the conformance validators, remediation programs,
+and CLI for the atlan-application-sdk ecosystem.
+"""
+
+__version__ = "0.2.0"

conformance/cli.py

@@ -0,0 +1,126 @@
+"""Entry point for the atlan-application-sdk-conformance CLI."""
+
+from __future__ import annotations
+
+import sys
+
+
+def _cmd_detect(argv: list[str]) -> int:
+    from conformance.suite.runner import main
+
+    return main(argv)
+
+
+def _cmd_programs_dir(_argv: list[str]) -> int:
+    import importlib.resources as _ir
+    import pathlib
+
+    programs = _ir.files("conformance") / "programs"
+    # Resolve to a real filesystem path (works for both installed wheels and
+    # editable installs where the files are already on disk).
+    try:
+        ctx = _ir.as_file(programs)
+        with ctx as p:
+            print(str(p))
+    except (FileNotFoundError, ModuleNotFoundError):
+        # Fallback: direct path (editable installs)
+        here = pathlib.Path(__file__).parent
+        print(str(here / "programs"))
+    return 0
+
+
+def _cmd_gen_rule_docs(argv: list[str]) -> int:
+    from conformance.tools.generate_rule_docs import main
+
+    try:
+        main(argv)
+        return 0
+    except SystemExit as e:
+        return int(e.code) if e.code is not None else 0
+
+
+def _cmd_remediate(argv: list[str]) -> int:
+    """Print the resolved programs path + version, then exit.
+
+    The actual remediation loop is driven by the SKILL.md shim which reads
+    the .prose.md contracts from the printed programs directory.
+    """
+    import pathlib
+
+    from conformance import __version__
+
+    here = pathlib.Path(__file__).parent
+    programs = here / "programs"
+    print(f"atlan-application-sdk-conformance {__version__}")
+    print(f"programs: {programs}")
+    print(f"entry:    {programs / 'conformance-remediation.prose.md'}")
+    return 0
+
+
+# The SKILL.md written by `bootstrap`. Keep it minimal and stable — the real
+# logic lives in the package; this shim just locates and invokes it.
+_SKILL_MD = """\
+---
+name: remediate
+description: Drive the conformance remediation loop (validators + OpenProse programs from the atlan-application-sdk-conformance package)
+argument-hint: "[--area error-handling|logging|ci] [--strict] [path]"
+---
+
+1. Resolve programs dir:
+   - Inside a connector repo: `PROGRAMS=$(uv run atlan-application-sdk-conformance programs-dir)`
+   - Anywhere else: `PROGRAMS=$(uvx atlan-application-sdk-conformance@latest programs-dir)`
+2. Read `$PROGRAMS/conformance-remediation.prose.md` and execute it as the entry contract.
+3. All gated re-checks call `atlan-application-sdk-conformance detect` — follow the .prose.md exactly.
+"""
+
+
+def _cmd_bootstrap(argv: list[str]) -> int:
+    """Write .claude/skills/remediate/SKILL.md in the current repo (or --force to overwrite)."""
+    import pathlib
+
+    force = "--force" in argv
+    dest = pathlib.Path.cwd() / ".claude" / "skills" / "remediate" / "SKILL.md"
+
+    if dest.exists() and not force:
+        print(f"already installed: {dest}  (pass --force to overwrite)")
+        return 0
+
+    existed = dest.exists()
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(_SKILL_MD)
+    action = "updated" if existed else "installed"
+    print(f"{action}: {dest}")
+    return 0
+
+
+_COMMANDS = {
+    "detect": _cmd_detect,
+    "programs-dir": _cmd_programs_dir,
+    "gen-rule-docs": _cmd_gen_rule_docs,
+    "remediate": _cmd_remediate,
+    "bootstrap": _cmd_bootstrap,
+}
+
+_USAGE = """\
+usage: atlan-application-sdk-conformance <command> [args]
+
+commands:
+  detect         Run the conformance suite and emit SARIF
+  programs-dir   Print the absolute path to the bundled .prose.md programs
+  gen-rule-docs  Regenerate rule docs from Python rule definitions
+  remediate      Print programs path + version banner (SKILL.md drives execution)
+  bootstrap      Write ~/.claude/skills/remediate/SKILL.md  (--force to overwrite)
+"""
+
+
+def main() -> None:
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
+        print(_USAGE)
+        sys.exit(0)
+
+    cmd = sys.argv[1]
+    if cmd not in _COMMANDS:
+        print(f"error: unknown command '{cmd}'\n{_USAGE}", file=sys.stderr)
+        sys.exit(1)
+
+    sys.exit(_COMMANDS[cmd](sys.argv[2:]))

conformance/docs/rules/ci.md

@@ -0,0 +1,33 @@
+<!-- AUTO-GENERATED — do not edit this file directly.
+     Source of truth: conformance/suite/rules/ci.py
+     To regenerate:  uv run poe generate-rule-docs
+     To check CI staleness: uv run poe generate-rule-docs --check -->
+
+# CI/Workflow Supply-Chain Rules (C-series)
+
+**1 rule** · Checker: `suite.checks.actions_pinning` and related workflow checks (static)
+
+Suppress a finding on the violating line or the line directly above it:
+
+```python
+# conformance: ignore[C001] intentional: org-internal action
+```
+
+| ID | Name | Tier | Category | Autofixable | Since |
+|---|---|---|---|---|---|
+| [C001](#c001) | `UnpinnedActionReference` | `block` | `supply-chain` | yes | 3.16.0 |
+
+---
+
+## C001 — `UnpinnedActionReference` {#c001}
+
+**Tier:** `block` · **Category:** `supply-chain` · **Autofixable:** yes · **Since:** 3.16.0
+
+> External GitHub Action not pinned to a full commit digest
+
+External actions reused via `uses:` must be pinned to a full-length commit SHA (digest),
+never a mutable tag (@v4) or branch (@main). A tag can be re-pointed to malicious code
+after review. Actions in the `atlanhq/` org are exempt (they intentionally track @main);
+local `./` composite-action refs are exempt (no version to pin).
+
+---

conformance/docs/rules/error-handling.md

@@ -0,0 +1,283 @@
+<!-- AUTO-GENERATED — do not edit this file directly.
+     Source of truth: conformance/suite/rules/error_handling.py
+     To regenerate:  uv run poe generate-rule-docs
+     To check CI staleness: uv run poe generate-rule-docs --check -->
+
+# Error-Handling Rules (E-series)
+
+**18 rules** · Checker: `suite.checks.error_handling` (AST-based)
+
+Suppress a finding on the violating line or the line directly above it:
+
+```python
+# conformance: ignore[E012] intentional: stdlib interop
+```
+
+| ID | Name | Tier | Category | Autofixable | Since |
+|---|---|---|---|---|---|
+| [E001](#e001) | `BareExceptPass` | `block` | `silent-swallow` | — | 3.16.0 |
+| [E002](#e002) | `TypedExceptPass` | `block` | `silent-swallow` | — | 3.16.0 |
+| [E003](#e003) | `BroadContextlibSuppress` | `warn` | `silent-swallow` | — | 3.16.0 |
+| [E004](#e004) | `BroadExceptClause` | `warn` | `overly-broad-catch` | — | 3.16.0 |
+| [E005](#e005) | `ExceptBlockMissingExcInfo` | `warn` | `missing-traceback` | yes | 3.16.0 |
+| [E006](#e006) | `BareExceptWithBody` | `block` | `silent-swallow` | — | 3.16.0 |
+| [E007](#e007) | `ErrorToReturnValue` | `warn` | `error-to-return-value` | — | 3.16.0 |
+| [E008](#e008) | `ImportErrorWithoutLogging` | `warn` | `optional-import` | — | 3.16.0 |
+| [E009](#e009) | `ExceptBlockOnlyAssigns` | `warn` | `error-to-return-value` | — | 3.16.0 |
+| [E010](#e010) | `AsyncioGatherExceptionsUnexamined` | `warn` | `asyncio-unexamined` | — | 3.16.0 |
+| [E011](#e011) | `LoggingFilterUnsafeBody` | `warn` | `filter-safety` | — | 3.17.0 |
+| [E012](#e012) | `UntypedBuiltinRaise` | `warn` | `untyped-raise` | — | 3.16.0 |
+| [E013](#e013) | `LegacyAtlanErrorRaise` | `block` | `legacy-raise` | — | 3.16.0 |
+| [E014](#e014) | `ExceptLoopControlSwallow` | `warn` | `silent-swallow` | — | 3.17.0 |
+| [E015](#e015) | `ExceptionTextInErrorMessage` | `warn` | `error-message-hygiene` | — | 3.17.0 |
+| [E016](#e016) | `MissingExceptionChaining` | `warn` | `exception-chaining` | yes | 3.17.0 |
+| [E017](#e017) | `SecretNamedEvidenceKey` | `block` | `security` | — | 3.17.0 |
+| [E018](#e018) | `BareParentLeafRaise` | `warn` | `untyped-raise` | — | 3.17.0 |
+
+---
+
+## E001 — `BareExceptPass` {#e001}
+
+**Tier:** `block` · **Category:** `silent-swallow` · **Autofixable:** — · **Since:** 3.16.0
+
+> Bare 'except: pass' silently discards every exception
+
+A bare `except: pass` catches KeyboardInterrupt, SystemExit, and GeneratorExit and
+discards them with no trace.  This is the hardest class of bugs to debug.  Replace with
+a typed catch that at minimum logs the error with `exc_info=True`.  Never acceptable —
+even cleanup paths should log at DEBUG.
+
+---
+
+## E002 — `TypedExceptPass` {#e002}
+
+**Tier:** `block` · **Category:** `silent-swallow` · **Autofixable:** — · **Since:** 3.16.0
+
+> Typed 'except SomeError: pass' discards exception silently
+
+A typed catch that still discards silently loses the stack trace entirely. Acceptable
+only for truly trivial best-effort operations where failure is 100% expected AND the
+surrounding code handles the missing result, AND there is a comment explaining the
+reasoning.
+
+---
+
+## E003 — `BroadContextlibSuppress` {#e003}
+
+**Tier:** `warn` · **Category:** `silent-swallow` · **Autofixable:** — · **Since:** 3.16.0
+
+> contextlib.suppress() — check whether scope is too broad
+
+`contextlib.suppress(Exception)` or `suppress(BaseException)` is HIGH severity; narrow
+`suppress(FileNotFoundError)` on a cleanup path is acceptable.  The checker must inspect
+the suppressed exception type before classifying.
+
+---
+
+## E004 — `BroadExceptClause` {#e004}
+
+**Tier:** `warn` · **Category:** `overly-broad-catch` · **Autofixable:** — · **Since:** 3.16.0
+
+> Overly broad 'except Exception/BaseException' without exc_info
+
+Catches everything but the specific type is unknown.  HIGH severity when not logged;
+MEDIUM when logged but missing `exc_info=True`.  Acceptable only at top-level handlers
+(worker loops, HTTP handlers) when properly logged with `exc_info=True`.
+
+---
+
+## E005 — `ExceptBlockMissingExcInfo` {#e005}
+
+**Tier:** `warn` · **Category:** `missing-traceback` · **Autofixable:** yes · **Since:** 3.16.0
+
+> except block logs without exc_info=True — stack trace discarded
+
+The message is logged but the stack trace is lost.  Add `exc_info=True` to every
+`logger.warning()` / `logger.error()` call inside an except block.  `logger.exception()`
+is exempt (it implies `exc_info=True`).
+
+---
+
+## E006 — `BareExceptWithBody` {#e006}
+
+**Tier:** `block` · **Category:** `silent-swallow` · **Autofixable:** — · **Since:** 3.16.0
+
+> Bare 'except:' (no type) — catches SystemExit and KeyboardInterrupt
+
+Like P001 but the block may have a body.  Still catches KeyboardInterrupt and
+SystemExit.  Always specify at least `except Exception:`.
+
+---
+
+## E007 — `ErrorToReturnValue` {#e007}
+
+**Tier:** `warn` · **Category:** `error-to-return-value` · **Autofixable:** — · **Since:** 3.16.0
+
+> except block returns a value without logging — error hidden
+
+Exception is converted to a return value (None, {}, [], False) with no trace.  Callers
+see a wrong result with no idea why.  At minimum log before returning; prefer raising a
+domain-specific exception instead.
+
+---
+
+## E008 — `ImportErrorWithoutLogging` {#e008}
+
+**Tier:** `warn` · **Category:** `optional-import` · **Autofixable:** — · **Since:** 3.16.0
+
+> except ImportError without logging — environment issues hidden
+
+Optional-dependency guard.  Acceptable when the import is genuinely optional AND the
+fallback path is correct AND there is a comment.  Log at DEBUG if the module is
+preferred but not required.  Flag if the module is expected to be present (will fail
+later with a confusing AttributeError).
+
+---
+
+## E009 — `ExceptBlockOnlyAssigns` {#e009}
+
+**Tier:** `warn` · **Category:** `error-to-return-value` · **Autofixable:** — · **Since:** 3.16.0
+
+> except block only assigns a variable — error hidden with no log
+
+Exception sets a flag or default value with no trace.  Combines P007's error-hiding with
+no logging.  Add a `logger.warning(..., exc_info=True)` before the assignment.
+
+---
+
+## E010 — `AsyncioGatherExceptionsUnexamined` {#e010}
+
+**Tier:** `warn` · **Category:** `asyncio-unexamined` · **Autofixable:** — · **Since:** 3.16.0
+
+> asyncio.gather(return_exceptions=True) results not checked for exceptions
+
+`return_exceptions=True` returns exception instances as values in the result list.  If
+the list is not subsequently inspected for `Exception` instances, errors vanish
+silently.  The pattern is only a bug when results are not checked;
+`return_exceptions=True` itself is acceptable.
+
+---
+
+## E011 — `LoggingFilterUnsafeBody` {#e011}
+
+**Tier:** `warn` · **Category:** `filter-safety` · **Autofixable:** — · **Since:** 3.17.0
+
+> logging.Filter.filter() body not wrapped in try/except — can crash caller
+
+`Logger.handle()` calls `self.filter(record)` with no surrounding try/except — unlike
+handler errors, filter exceptions are NOT caught by `handleError()`.  An unguarded
+attribute access (`record.custom_field`) or any external call that can raise will
+propagate directly to the code that called `logger.info()` (or similar), crashing the
+caller.  Wrap the entire `filter()` body in try/except with a safe fallback (return True
+to pass-through, False to drop).  Use `getattr(record, 'field', default)` for optional
+record attributes. Never acceptable — filter methods must never let exceptions
+propagate.
+
+---
+
+## E012 — `UntypedBuiltinRaise` {#e012}
+
+**Tier:** `warn` · **Category:** `untyped-raise` · **Autofixable:** — · **Since:** 3.16.0
+
+> raise ValueError/RuntimeError/... where a typed AppError applies
+
+SDK code raises a bare Python builtin.  The Automation Engine receives an opaque string
+— no category, code, audience, or retryable field. Dashboards are blind; on-call routing
+is impossible.  Use the typed error leaf from `application_sdk.errors`.  Acceptable only
+inside dataclass `__post_init__` / stdlib validator methods where Python semantics
+require `TypeError`/`ValueError` for stdlib interoperability.
+
+---
+
+## E013 — `LegacyAtlanErrorRaise` {#e013}
+
+**Tier:** `block` · **Category:** `legacy-raise` · **Autofixable:** — · **Since:** 3.16.0
+
+> raise ClientError/ApiError/... (deprecated AtlanError stack)
+
+`AtlanError` and its subclasses emit a `DeprecationWarning` at construction time and
+reach AE as opaque strings.  They produce no typed wire envelope.  Scheduled for removal
+in v4.0.  Replace with the appropriate leaf from `application_sdk.errors`.
+
+---
+
+## E014 — `ExceptLoopControlSwallow` {#e014}
+
+**Tier:** `warn` · **Category:** `silent-swallow` · **Autofixable:** — · **Since:** 3.17.0
+
+> except block exits loop silently (continue/break) without logging
+
+An `except` block inside a loop whose body is only `continue`, `break`, or `pass` — with
+no logging call — silently swallows the exception and resumes or exits the iteration.
+This is the loop-body twin of P001/P002 (ruff S112 family).  At minimum log at DEBUG
+before the loop control statement; if the exception signals a genuine error, re-raise or
+log at WARNING/ERROR with `exc_info=True`.
+
+---
+
+## E015 — `ExceptionTextInErrorMessage` {#e015}
+
+**Tier:** `warn` · **Category:** `error-message-hygiene` · **Autofixable:** — · **Since:** 3.17.0
+
+> Caught exception text interpolated into typed error message= — leaks unsanitised text
+
+A typed `AppError` raise whose `message=` keyword value embeds the caught exception via
+an f-string (`f'…{exc}…'`), `str(exc)`, or `repr(exc)` — see typed-error-prescription.md
+§6.  This leaks unsanitised, potentially user-facing text from an upstream library into
+a field that is displayed to operators and indexed in dashboards.  It also breaks
+aggregation by collapsing distinct failure modes into one variable-text bucket.  Place
+the exception context in a typed evidence field (`cause=exc`, `network_error=str(exc)`)
+and keep `message=` a stable human summary.
+
+---
+
+## E016 — `MissingExceptionChaining` {#e016}
+
+**Tier:** `warn` · **Category:** `exception-chaining` · **Autofixable:** yes · **Since:** 3.17.0
+
+> raise inside except block missing 'from exc' cause — breaks exception chain
+
+A non-bare `raise` inside an `except … as e:` block that does not include `from e` (or
+`from None`).  Without explicit chaining, Python attaches the original as `__context__`
+with `__suppress_context__=False` — the chain is preserved at the interpreter level but
+AE's wire serialiser only follows the `__cause__` chain, so the original exception is
+lost in dashboards.  Fix: `raise NewError(...) from e`.  Use `from None` only when
+intentionally hiding the original (requires a comment explaining why). Acceptable
+patterns: bare `raise` (re-raise), `raise X() from e` (already chained), `raise X() from
+None` (intentional suppression).
+
+---
+
+## E017 — `SecretNamedEvidenceKey` {#e017}
+
+**Tier:** `block` · **Category:** `security` · **Autofixable:** — · **Since:** 3.17.0
+
+> Error evidence kwarg ending in _secret/_password/_token — rejected by wire layer at runtime
+
+An error construction call that passes a keyword argument whose name ends in `_secret`,
+`_password`, or `_token` — see `application_sdk.errors.wire` §6.  The wire layer
+actively rejects these suffixes at runtime (`ValueError`) to prevent credential leakage
+into logs, dashboards, and SARIF reports.  Static detection means the bug is caught
+before any code runs.  Rename the evidence field to a safe key (e.g. `credential_name`,
+`token_type`) or pass the value via `cause=exc`.
+
+---
+
+## E018 — `BareParentLeafRaise` {#e018}
+
+**Tier:** `warn` · **Category:** `untyped-raise` · **Autofixable:** — · **Since:** 3.17.0
+
+> Raising a bare AppError leaf class without a domain subclass overriding code
+
+Raising a parent leaf directly (`InternalError(...)`, `InvalidInputError(...)`) without
+a domain-specific subclass that overrides `code` collapses all failure modes for a given
+category into one dashboard bucket — impossible to route, alert on, or triage
+individually.  See typed-error-prescription.md §4.  Only sanctioned bare-parent form:
+`InternalError(classification_pending=True)` — used exclusively as a temporary
+placeholder during migration, never in production-stable code.  For all other sites:
+define a domain subclass that overrides `code` with a specific constant (e.g.
+`ENGINE_NOT_INITIALIZED`). Note: this rule is WARN tier because some bare-parent raises
+may be legitimate in small apps or during active migration.  Review findings before
+suppressing.
+
+---