encoding-claim-audit 0.1.0__tar.gz

encoding_claim_audit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 encoding-claim-audit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

encoding_claim_audit-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE
+recursive-include tests *.py *.md .env

encoding_claim_audit-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: encoding-claim-audit
+Version: 0.1.0
+Summary: Offline audit of documented text encoding claims against Python source
+Author: encoding-claim-audit contributors
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# encoding-claim-audit
+
+Version 0.1.0. Offline static audit of documented UTF-8 and Unicode claims
+against Python text file I/O. Python >=3.9; no runtime dependencies.
+Audited code is never executed and no network requests are made.
+
+## Usage
+
+```sh
+python3 -m pip install .
+encoding-claim-audit [path]
+encoding-claim-audit ./project --json --fail-on HIGH
+encoding-claim-audit ./project --ignore documented-encoding-claim-false-test-only
+encoding-claim-audit --version
+```
+
+Path defaults to `.`. `--verbose` prints verified claim notes and source counts.
+`--json` emits findings, verified_claims, and summary. Each finding has a family,
+rule, severity, message, and evidence items with path, line, and kind.
+Exit codes: 0 PASS at the selected threshold, 2 FAIL, 1 usage/input error.
+The default threshold is MEDIUM. `--fail-on HIGH` still prints MEDIUM findings.
+Unknown ignore rules are input errors. `--ignore RULE,...` accepts:
+
+- `documented-encoding-claim-false`: HIGH for production evidence or no source.
+- `documented-encoding-claim-false-test-only`: MEDIUM for test-only evidence.
+
+Each family produces at most one finding. Production evidence takes precedence.
+Ignored findings are omitted, not relabeled as verified.
+
+## Scope and limitations
+
+Claims come from root README.md and docs/**/*.md prose, including inline code.
+Backtick and tilde fenced code is excluded; sentences containing negation are
+suppressed. Positive sentences elsewhere can independently establish a claim.
+UTF-8, utf8, utf_8, and Unicode are recognized case-insensitively.
+
+AST checks cover open/io.open, codecs.open, io.TextIOWrapper, and read_text/
+write_text methods. Missing or non-UTF-8 literal encodings are evidence.
+Standard open positional encoding and codecs.open third positional encoding
+are recognized; Path methods and TextIOWrapper require keyword encoding.
+Binary I/O is excluded. Tests are identified by tests/test/fixtures directory
+components. examples directories and symlinks are skipped. Only Python source
+and Markdown documentation are read; .env contents are never opened.
+No claims yields empty findings and verified claims. No Python source yields
+HIGH per family. No production text I/O makes the claim moot, not falsified.
+
+This is static pattern matching, not semantic judgement. Dead code counts.
+Variable modes/encodings are skipped as unknown. Dynamic file opens are missed.
+Alias tracking is per-file only; shadowing and reassignment are not resolved.
+Text method matching does not infer receiver types and may flag unrelated methods.
+Negation is conservative and sentence based, so unrelated negative words can
+suppress claims. Clean results with unknown encodings are qualified rather than
+proof of runtime behavior. Source must be UTF-8 (optional BOM), docs UTF-8;
+malformed or unreadable input yields exit 1.
+
+## Differentiation
+
+- privacy-claim-audit: network/telemetry evidence, never text encodings.
+- config-claim-audit: documented default values, never encoding arguments.
+- readme-claim-audit: install/flag/link/version, never encoding.
+- bandit/ruff: code issues, never documentation promises.
+- file/chardet: actual bytes on disk, never documentation versus code truth.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+The source distribution includes tests and good/bad/testonly fixtures, including
+a marker-only .env read guard. Licensed under MIT.

encoding_claim_audit-0.1.0/README.md

@@ -0,0 +1,72 @@
+# encoding-claim-audit
+
+Version 0.1.0. Offline static audit of documented UTF-8 and Unicode claims
+against Python text file I/O. Python >=3.9; no runtime dependencies.
+Audited code is never executed and no network requests are made.
+
+## Usage
+
+```sh
+python3 -m pip install .
+encoding-claim-audit [path]
+encoding-claim-audit ./project --json --fail-on HIGH
+encoding-claim-audit ./project --ignore documented-encoding-claim-false-test-only
+encoding-claim-audit --version
+```
+
+Path defaults to `.`. `--verbose` prints verified claim notes and source counts.
+`--json` emits findings, verified_claims, and summary. Each finding has a family,
+rule, severity, message, and evidence items with path, line, and kind.
+Exit codes: 0 PASS at the selected threshold, 2 FAIL, 1 usage/input error.
+The default threshold is MEDIUM. `--fail-on HIGH` still prints MEDIUM findings.
+Unknown ignore rules are input errors. `--ignore RULE,...` accepts:
+
+- `documented-encoding-claim-false`: HIGH for production evidence or no source.
+- `documented-encoding-claim-false-test-only`: MEDIUM for test-only evidence.
+
+Each family produces at most one finding. Production evidence takes precedence.
+Ignored findings are omitted, not relabeled as verified.
+
+## Scope and limitations
+
+Claims come from root README.md and docs/**/*.md prose, including inline code.
+Backtick and tilde fenced code is excluded; sentences containing negation are
+suppressed. Positive sentences elsewhere can independently establish a claim.
+UTF-8, utf8, utf_8, and Unicode are recognized case-insensitively.
+
+AST checks cover open/io.open, codecs.open, io.TextIOWrapper, and read_text/
+write_text methods. Missing or non-UTF-8 literal encodings are evidence.
+Standard open positional encoding and codecs.open third positional encoding
+are recognized; Path methods and TextIOWrapper require keyword encoding.
+Binary I/O is excluded. Tests are identified by tests/test/fixtures directory
+components. examples directories and symlinks are skipped. Only Python source
+and Markdown documentation are read; .env contents are never opened.
+No claims yields empty findings and verified claims. No Python source yields
+HIGH per family. No production text I/O makes the claim moot, not falsified.
+
+This is static pattern matching, not semantic judgement. Dead code counts.
+Variable modes/encodings are skipped as unknown. Dynamic file opens are missed.
+Alias tracking is per-file only; shadowing and reassignment are not resolved.
+Text method matching does not infer receiver types and may flag unrelated methods.
+Negation is conservative and sentence based, so unrelated negative words can
+suppress claims. Clean results with unknown encodings are qualified rather than
+proof of runtime behavior. Source must be UTF-8 (optional BOM), docs UTF-8;
+malformed or unreadable input yields exit 1.
+
+## Differentiation
+
+- privacy-claim-audit: network/telemetry evidence, never text encodings.
+- config-claim-audit: documented default values, never encoding arguments.
+- readme-claim-audit: install/flag/link/version, never encoding.
+- bandit/ruff: code issues, never documentation promises.
+- file/chardet: actual bytes on disk, never documentation versus code truth.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+The source distribution includes tests and good/bad/testonly fixtures, including
+a marker-only .env read guard. Licensed under MIT.

encoding_claim_audit-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "encoding-claim-audit"
+version = "0.1.0"
+description = "Offline audit of documented text encoding claims against Python source"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "encoding-claim-audit contributors"}]
+dependencies = []
+
+[project.scripts]
+encoding-claim-audit = "encoding_claim_audit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

encoding_claim_audit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

encoding_claim_audit-0.1.0/src/encoding_claim_audit/__init__.py

@@ -0,0 +1,2 @@
+"""Audit documented Python text encoding claims."""
+__version__ = '0.1.0'

encoding_claim_audit-0.1.0/src/encoding_claim_audit/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

encoding_claim_audit-0.1.0/src/encoding_claim_audit/audit.py

@@ -0,0 +1,132 @@
+"""Offline documentation and AST encoding audit."""
+import ast
+import re
+from pathlib import Path
+
+RULE = 'documented-encoding-claim-false'
+TEST_RULE = RULE + '-test-only'
+FAMILIES = {'UTF-8': r'\butf[-_]?8\b', 'Unicode': r'\bunicode\b'}
+
+
+def claims_in(text):
+    """Return claim families in unfenced, non-negated prose."""
+    prose = []
+    fence = None
+    for line in text.splitlines():
+        match = re.match(r'^\s{0,3}(`{3,}|~{3,})', line)
+        if match:
+            marker = match.group(1)
+            if fence is None:
+                fence = marker
+            elif marker[0] == fence[0] and len(marker) >= len(fence):
+                fence = None
+            continue
+        if fence is None:
+            prose.append(line)
+    result = set()
+    for sentence in re.split(r'[.!?\n]+', '\n'.join(prose)):
+        if re.search(r"\b(no|not|never|without)\b|\b(?:doesn’t|doesn't|cannot|can't)\b", sentence, re.I):
+            continue
+        for family, pattern in FAMILIES.items():
+            if re.search(pattern, sentence, re.I):
+                result.add(family)
+    return result
+
+
+def _name(node):
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return _name(node.value) + '.' + node.attr
+    return ''
+
+
+def inspect_source(text, path):
+    """Return evidence and number of statically recognized text sites."""
+    tree = ast.parse(text, filename=path)
+    aliases = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for item in node.names:
+                aliases[item.asname or item.name] = item.name
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            for item in node.names:
+                aliases[item.asname or item.name] = node.module + '.' + item.name
+    evidence = []
+    sites = 0
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        name = _name(node.func)
+        first, _, rest = name.partition('.')
+        name = aliases.get(first, first) + ('.' + rest if rest else '')
+        keywords = {k.arg: k.value for k in node.keywords}
+        encoding = keywords.get('encoding')
+        if name in ('open', 'io.open', 'builtins.open', 'codecs.open'):
+            mode = keywords.get('mode', node.args[1] if len(node.args) > 1 else ast.Constant('r'))
+            if not isinstance(mode, ast.Constant) or not isinstance(mode.value, str):
+                continue
+            if 'b' in mode.value:
+                continue
+            position = 2 if name == 'codecs.open' else 3
+            if encoding is None and len(node.args) > position:
+                encoding = node.args[position]
+        elif name == 'io.TextIOWrapper' or (isinstance(node.func, ast.Attribute) and node.func.attr in ('read_text', 'write_text')):
+            pass
+        else:
+            continue
+        sites += 1
+        if encoding is None:
+            kind = 'missing-encoding'
+        elif isinstance(encoding, ast.Constant):
+            if isinstance(encoding.value, str) and encoding.value.lower() in ('utf-8', 'utf8', 'utf_8'):
+                continue
+            kind = 'wrong-encoding'
+        else:
+            continue
+        evidence.append({'path': path, 'line': node.lineno, 'kind': kind})
+    return evidence, sites
+
+
+def audit(root, ignore=()):
+    """Audit a directory without importing or executing its source."""
+    root = Path(root)
+    if not root.is_dir():
+        raise ValueError('input path must be a directory')
+    claims = set()
+    docs = [root / 'README.md']
+    if (root / 'docs').is_dir() and not (root / 'docs').is_symlink():
+        docs.extend((root / 'docs').rglob('*.md'))
+    def safe(path):
+        return not any(p.is_symlink() for p in [path] + list(path.parents) if p != root.parent)
+    for path in docs:
+        if path.is_file() and safe(path):
+            claims.update(claims_in(path.read_text(encoding='utf-8')))
+    if not claims:
+        return {'findings': [], 'verified_claims': [], 'summary': {'claims': 0, 'findings': 0, 'python_files': 0}}
+    production, testonly = [], []
+    sources = sites = 0
+    for path in sorted(root.rglob('*.py')):
+        relative = path.relative_to(root)
+        if not safe(path) or 'examples' in relative.parts:
+            continue
+        sources += 1
+        evidence, count = inspect_source(path.read_text(encoding='utf-8-sig'), relative.as_posix())
+        is_test = bool(set(relative.parts[:-1]) & {'tests', 'test', 'fixtures'})
+        (testonly if is_test else production).extend(evidence)
+        if not is_test:
+            sites += count
+    findings, verified = [], []
+    for family in sorted(claims):
+        if production or not sources:
+            rule, severity, evidence = RULE, 'HIGH', production
+            note = 'Production text I/O contradicts the claim.' if sources else 'No Python source files found.'
+        elif testonly:
+            rule, severity, evidence = TEST_RULE, 'MEDIUM', testonly
+            note = 'Encoding evidence occurs only in tests or fixtures.'
+        else:
+            verified.append({'family': family, 'note': 'All recognized production text I/O carries UTF-8 encoding or an unknown encoding.' if sites else 'No production text I/O; claim is moot, not falsified.'})
+            continue
+        if rule not in ignore:
+            findings.append({'rule': rule, 'severity': severity, 'family': family, 'message': note, 'evidence': evidence})
+    return {'findings': findings, 'verified_claims': verified, 'summary': {'claims': len(claims), 'findings': len(findings), 'python_files': sources}}

encoding_claim_audit-0.1.0/src/encoding_claim_audit/cli.py

@@ -0,0 +1,46 @@
+"""Command line interface."""
+import argparse
+import json
+import sys
+from . import __version__
+from .audit import RULE, TEST_RULE, audit
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        self.exit(1, '%s: error: %s\n' % (self.prog, message))
+
+
+def main(argv=None):
+    parser = Parser(prog='encoding-claim-audit')
+    parser.add_argument('path', nargs='?', default='.')
+    parser.add_argument('--json', action='store_true')
+    parser.add_argument('--fail-on', choices=('HIGH', 'MEDIUM'), default='MEDIUM')
+    parser.add_argument('--ignore', default='', metavar='RULE,...')
+    parser.add_argument('--verbose', action='store_true')
+    parser.add_argument('--version', action='version', version=__version__)
+    args = parser.parse_args(argv)
+    ignored = set(filter(None, args.ignore.split(',')))
+    if ignored - {RULE, TEST_RULE}:
+        parser.error('unknown ignored rule: ' + ', '.join(sorted(ignored - {RULE, TEST_RULE})))
+    try:
+        result = audit(args.path, ignored)
+    except (OSError, ValueError, SyntaxError) as exc:
+        print('encoding-claim-audit: ' + str(exc), file=sys.stderr)
+        return 1
+    failed = any(f['severity'] == 'HIGH' or args.fail_on == 'MEDIUM' for f in result['findings'])
+    result['summary']['status'] = 'FAIL' if failed else 'PASS'
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(result['summary']['status'])
+        for finding in result['findings']:
+            print('{severity} {rule} [{family}]: {message}'.format(**finding))
+            for item in finding['evidence']:
+                print('  {path}:{line}: {kind}'.format(**item))
+        if args.verbose:
+            for claim in result['verified_claims']:
+                print('{family}: {note}'.format(**claim))
+            print('Python files: ' + str(result['summary']['python_files']))
+    return 2 if failed else 0

encoding_claim_audit-0.1.0/src/encoding_claim_audit.egg-info/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: encoding-claim-audit
+Version: 0.1.0
+Summary: Offline audit of documented text encoding claims against Python source
+Author: encoding-claim-audit contributors
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# encoding-claim-audit
+
+Version 0.1.0. Offline static audit of documented UTF-8 and Unicode claims
+against Python text file I/O. Python >=3.9; no runtime dependencies.
+Audited code is never executed and no network requests are made.
+
+## Usage
+
+```sh
+python3 -m pip install .
+encoding-claim-audit [path]
+encoding-claim-audit ./project --json --fail-on HIGH
+encoding-claim-audit ./project --ignore documented-encoding-claim-false-test-only
+encoding-claim-audit --version
+```
+
+Path defaults to `.`. `--verbose` prints verified claim notes and source counts.
+`--json` emits findings, verified_claims, and summary. Each finding has a family,
+rule, severity, message, and evidence items with path, line, and kind.
+Exit codes: 0 PASS at the selected threshold, 2 FAIL, 1 usage/input error.
+The default threshold is MEDIUM. `--fail-on HIGH` still prints MEDIUM findings.
+Unknown ignore rules are input errors. `--ignore RULE,...` accepts:
+
+- `documented-encoding-claim-false`: HIGH for production evidence or no source.
+- `documented-encoding-claim-false-test-only`: MEDIUM for test-only evidence.
+
+Each family produces at most one finding. Production evidence takes precedence.
+Ignored findings are omitted, not relabeled as verified.
+
+## Scope and limitations
+
+Claims come from root README.md and docs/**/*.md prose, including inline code.
+Backtick and tilde fenced code is excluded; sentences containing negation are
+suppressed. Positive sentences elsewhere can independently establish a claim.
+UTF-8, utf8, utf_8, and Unicode are recognized case-insensitively.
+
+AST checks cover open/io.open, codecs.open, io.TextIOWrapper, and read_text/
+write_text methods. Missing or non-UTF-8 literal encodings are evidence.
+Standard open positional encoding and codecs.open third positional encoding
+are recognized; Path methods and TextIOWrapper require keyword encoding.
+Binary I/O is excluded. Tests are identified by tests/test/fixtures directory
+components. examples directories and symlinks are skipped. Only Python source
+and Markdown documentation are read; .env contents are never opened.
+No claims yields empty findings and verified claims. No Python source yields
+HIGH per family. No production text I/O makes the claim moot, not falsified.
+
+This is static pattern matching, not semantic judgement. Dead code counts.
+Variable modes/encodings are skipped as unknown. Dynamic file opens are missed.
+Alias tracking is per-file only; shadowing and reassignment are not resolved.
+Text method matching does not infer receiver types and may flag unrelated methods.
+Negation is conservative and sentence based, so unrelated negative words can
+suppress claims. Clean results with unknown encodings are qualified rather than
+proof of runtime behavior. Source must be UTF-8 (optional BOM), docs UTF-8;
+malformed or unreadable input yields exit 1.
+
+## Differentiation
+
+- privacy-claim-audit: network/telemetry evidence, never text encodings.
+- config-claim-audit: documented default values, never encoding arguments.
+- readme-claim-audit: install/flag/link/version, never encoding.
+- bandit/ruff: code issues, never documentation promises.
+- file/chardet: actual bytes on disk, never documentation versus code truth.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+The source distribution includes tests and good/bad/testonly fixtures, including
+a marker-only .env read guard. Licensed under MIT.

encoding_claim_audit-0.1.0/src/encoding_claim_audit.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/encoding_claim_audit/__init__.py
+src/encoding_claim_audit/__main__.py
+src/encoding_claim_audit/audit.py
+src/encoding_claim_audit/cli.py
+src/encoding_claim_audit.egg-info/PKG-INFO
+src/encoding_claim_audit.egg-info/SOURCES.txt
+src/encoding_claim_audit.egg-info/dependency_links.txt
+src/encoding_claim_audit.egg-info/entry_points.txt
+src/encoding_claim_audit.egg-info/top_level.txt
+tests/test_audit.py
+tests/fixtures/bad/.env
+tests/fixtures/bad/README.md
+tests/fixtures/bad/app.py
+tests/fixtures/good/README.md
+tests/fixtures/good/app.py
+tests/fixtures/testonly/README.md
+tests/fixtures/testonly/app.py
+tests/fixtures/testonly/tests/test_io.py

encoding_claim_audit-0.1.0/src/encoding_claim_audit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

encoding_claim_audit-0.1.0/src/encoding_claim_audit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+encoding-claim-audit = encoding_claim_audit.cli:main

encoding_claim_audit-0.1.0/src/encoding_claim_audit.egg-info/top_level.txt

@@ -0,0 +1 @@
+encoding_claim_audit

encoding_claim_audit-0.1.0/tests/fixtures/bad/.env

@@ -0,0 +1 @@
+ENCODING_AUDIT_ENV_MUST_NEVER_BE_READ_73491

encoding_claim_audit-0.1.0/tests/fixtures/bad/README.md

@@ -0,0 +1 @@
+Supports UTF-8.

encoding_claim_audit-0.1.0/tests/fixtures/bad/app.py

@@ -0,0 +1,3 @@
+from pathlib import Path
+open('text')
+Path('text').write_text('hello', encoding='latin-1')

encoding_claim_audit-0.1.0/tests/fixtures/good/README.md

@@ -0,0 +1 @@
+Supports UTF-8 and Unicode.

encoding_claim_audit-0.1.0/tests/fixtures/good/app.py

@@ -0,0 +1,8 @@
+import codecs
+from pathlib import Path
+import io
+open('text', encoding='utf-8')
+codecs.open('text', 'r', 'utf8')
+open('binary', 'rb')
+Path('text').read_text(encoding='utf_8')
+io.TextIOWrapper(None, encoding='UTF-8')

encoding_claim_audit-0.1.0/tests/fixtures/testonly/README.md

@@ -0,0 +1 @@
+Supports UTF-8 and Unicode.

encoding_claim_audit-0.1.0/tests/fixtures/testonly/app.py

@@ -0,0 +1 @@
+"""No production file I/O."""

encoding_claim_audit-0.1.0/tests/fixtures/testonly/tests/test_io.py

@@ -0,0 +1 @@
+open('text')

encoding_claim_audit-0.1.0/tests/test_audit.py

@@ -0,0 +1,279 @@
+import contextlib
+import io
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from encoding_claim_audit.audit import audit, claims_in, inspect_source, RULE, TEST_RULE
+from encoding_claim_audit.cli import main
+
+FIXTURES = Path(__file__).parent / 'fixtures'
+
+
+class AuditTests(unittest.TestCase):
+    def source(self, code):
+        return inspect_source(code, 'app.py')[0]
+
+    def project(self, readme='UTF-8', source="open('x')", filename='app.py'):
+        temp = tempfile.TemporaryDirectory()
+        self.addCleanup(temp.cleanup)
+        root = Path(temp.name)
+        (root / 'README.md').write_text(readme, encoding='utf-8')
+        if source is not None:
+            path = root / filename
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(source, encoding='utf-8')
+        return root
+
+    def cli(self, *args):
+        output, error = io.StringIO(), io.StringIO()
+        with contextlib.redirect_stdout(output), contextlib.redirect_stderr(error):
+            try:
+                code = main(list(map(str, args)))
+            except SystemExit as exc:
+                code = exc.code
+        return code, output.getvalue(), error.getvalue()
+
+    def test_good(self):
+        result = audit(FIXTURES / 'good')
+        self.assertEqual(result['findings'], [])
+        self.assertEqual(len(result['verified_claims']), 2)
+
+    def test_bad(self):
+        findings = audit(FIXTURES / 'bad')['findings']
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0]['severity'], 'HIGH')
+        self.assertEqual([e['kind'] for e in findings[0]['evidence']], ['missing-encoding', 'wrong-encoding'])
+
+    def test_testonly(self):
+        self.assertEqual({f['severity'] for f in audit(FIXTURES / 'testonly')['findings']}, {'MEDIUM'})
+
+    def test_good_cli(self):
+        self.assertEqual(self.cli(FIXTURES / 'good')[0], 0)
+
+    def test_bad_cli(self):
+        self.assertEqual(self.cli(FIXTURES / 'bad')[0], 2)
+
+    def test_testonly_cli(self):
+        self.assertEqual(self.cli(FIXTURES / 'testonly')[0], 2)
+
+    def test_high_threshold(self):
+        code, output, _ = self.cli(FIXTURES / 'testonly', '--fail-on', 'HIGH')
+        self.assertEqual(code, 0)
+        self.assertIn('MEDIUM', output)
+
+    def test_json(self):
+        code, output, _ = self.cli(FIXTURES / 'bad', '--json')
+        self.assertEqual(code, 2)
+        self.assertEqual(json.loads(output)['summary']['status'], 'FAIL')
+
+    def test_version(self):
+        self.assertEqual(self.cli('--version')[:2], (0, '0.1.0\n'))
+
+    def test_ignore_high(self):
+        self.assertEqual(self.cli(FIXTURES / 'bad', '--ignore', RULE)[0], 0)
+
+    def test_ignore_medium(self):
+        self.assertEqual(self.cli(FIXTURES / 'testonly', '--ignore', TEST_RULE)[0], 0)
+
+    def test_ignore_multiple(self):
+        self.assertEqual(self.cli(FIXTURES / 'bad', '--ignore', RULE + ',' + TEST_RULE)[0], 0)
+
+    def test_unknown_ignore(self):
+        self.assertEqual(self.cli('--ignore', 'typo')[0], 1)
+
+    def test_bad_option(self):
+        self.assertEqual(self.cli('--no-such-option')[0], 1)
+
+    def test_bad_threshold(self):
+        self.assertEqual(self.cli('--fail-on', 'LOW')[0], 1)
+
+    def test_bad_path(self):
+        self.assertEqual(self.cli('/no/such/project')[0], 1)
+
+    def test_verbose(self):
+        self.assertIn('Python files:', self.cli(FIXTURES / 'good', '--verbose')[1])
+
+    def test_default_path(self):
+        previous = os.getcwd()
+        try:
+            os.chdir(FIXTURES / 'good')
+            self.assertEqual(self.cli()[0], 0)
+        finally:
+            os.chdir(previous)
+
+    def test_utf8_variant(self):
+        self.assertEqual(claims_in('utf8'), {'UTF-8'})
+
+    def test_utfunderscore_variant(self):
+        self.assertEqual(claims_in('UTF_8'), {'UTF-8'})
+
+    def test_unicode_case(self):
+        self.assertEqual(claims_in('uNiCoDe'), {'Unicode'})
+
+    def test_family_dedup(self):
+        self.assertEqual(claims_in('UTF-8 utf8 utf_8'), {'UTF-8'})
+
+    def test_inline_code(self):
+        self.assertEqual(claims_in('Supports `UTF-8`'), {'UTF-8'})
+
+    def test_backtick_fence(self):
+        self.assertEqual(claims_in('```python\nUTF-8 Unicode\n```'), set())
+
+    def test_tilde_fence(self):
+        self.assertEqual(claims_in('~~~\nUTF-8\n~~~\nUnicode'), {'Unicode'})
+
+    def test_fence_short_close(self):
+        self.assertEqual(claims_in('````\n```\nUTF-8\n````'), set())
+
+    def test_negated(self):
+        self.assertEqual(claims_in('Does not support UTF-8. No Unicode support.'), set())
+
+    def test_positive_sentence_after_negative(self):
+        self.assertEqual(claims_in('No Unicode support. Supports UTF-8.'), {'UTF-8'})
+
+    def test_no_claim(self):
+        result = audit(self.project('A package.'))
+        self.assertEqual(result['findings'], [])
+        self.assertEqual(result['verified_claims'], [])
+
+    def test_no_source(self):
+        self.assertEqual(len(audit(self.project('UTF-8 and Unicode', None))['findings']), 2)
+
+    def test_unicode_evidence(self):
+        self.assertEqual(audit(self.project('Unicode'))['findings'][0]['family'], 'Unicode')
+
+    def test_moot(self):
+        result = audit(self.project(source='x = 1'))
+        self.assertIn('moot', result['verified_claims'][0]['note'])
+
+    def test_docs_nested(self):
+        root = self.project('A package.')
+        doc = root / 'docs' / 'nested' / 'guide.md'
+        doc.parent.mkdir(parents=True)
+        doc.write_text('Unicode', encoding='utf-8')
+        self.assertEqual(len(audit(root)['findings']), 1)
+
+    def test_open_missing(self):
+        self.assertEqual(self.source("open('x')")[0]['kind'], 'missing-encoding')
+
+    def test_io_open(self):
+        self.assertEqual(len(self.source("import io\nio.open('x')")), 1)
+
+    def test_open_positional_encoding(self):
+        self.assertEqual(self.source("open('x', 'r', -1, 'UTF-8')"), [])
+
+    def test_binary(self):
+        self.assertEqual(self.source("open('x', 'rb'); open('x', mode='wb+')"), [])
+
+    def test_variable_mode(self):
+        self.assertEqual(self.source("open('x', mode=mode)"), [])
+
+    def test_variable_encoding(self):
+        self.assertEqual(self.source("open('x', encoding=encoding)"), [])
+
+    def test_text_modes(self):
+        for mode in ('r', 'w', 'a', 'x', 'r+', 'w+', 'a+', 'x+'):
+            with self.subTest(mode=mode):
+                self.assertEqual(len(self.source("open('x', %r)" % mode)), 1)
+
+    def test_codecs_positional(self):
+        self.assertEqual(self.source("import codecs\ncodecs.open('x', 'r', 'utf8')"), [])
+
+    def test_codecs_wrong_positional(self):
+        self.assertEqual(self.source("import codecs\ncodecs.open('x', 'r', 'latin-1')")[0]['kind'], 'wrong-encoding')
+
+    def test_codecs_missing(self):
+        self.assertEqual(len(self.source("import codecs\ncodecs.open('x')")), 1)
+
+    def test_codecs_keyword(self):
+        self.assertEqual(self.source("import codecs\ncodecs.open('x', encoding='utf_8')"), [])
+
+    def test_wrapper_missing(self):
+        self.assertEqual(len(self.source('import io\nio.TextIOWrapper(stream)')), 1)
+
+    def test_wrapper_wrong(self):
+        self.assertEqual(self.source("import io\nio.TextIOWrapper(stream, encoding='ascii')")[0]['kind'], 'wrong-encoding')
+
+    def test_wrapper_good(self):
+        self.assertEqual(self.source("import io\nio.TextIOWrapper(stream, encoding='utf8')"), [])
+
+    def test_path_methods(self):
+        for method in ('read_text', 'write_text'):
+            self.assertEqual(len(self.source("path.%s()" % method)), 1)
+
+    def test_path_wrong(self):
+        self.assertEqual(self.source("path.write_text('x', encoding='latin-1')")[0]['kind'], 'wrong-encoding')
+
+    def test_path_variable(self):
+        self.assertEqual(self.source('path.read_text(encoding=enc)'), [])
+
+    def test_bytes(self):
+        self.assertEqual(self.source("p.read_bytes(); p.write_bytes(b'x')"), [])
+
+    def test_streams(self):
+        self.assertEqual(self.source("import sys\nsys.stdin.read(); sys.stdout.write('x'); print('x', file=sys.stdout)"), [])
+
+    def test_aliases(self):
+        self.assertEqual(len(self.source('import io as streams\nfrom codecs import open as copen\nstreams.open("x")\ncopen("x")')), 2)
+
+    def test_from_wrapper(self):
+        self.assertEqual(len(self.source('from io import TextIOWrapper as W\nW(stream)')), 1)
+
+    def test_symlink(self):
+        root = self.project(source='x = 1')
+        (root / 'linked.py').symlink_to(FIXTURES.resolve() / 'bad' / 'app.py')
+        self.assertEqual(audit(root)['findings'], [])
+
+    def test_symlink_directory(self):
+        root = self.project(source='x = 1')
+        (root / 'linked').symlink_to(FIXTURES.resolve() / 'bad', target_is_directory=True)
+        self.assertEqual(audit(root)['findings'], [])
+
+    def test_examples(self):
+        self.assertEqual(audit(self.project(filename='examples/demo.py'))['summary']['python_files'], 0)
+
+    def test_test_components(self):
+        for directory in ('tests', 'test', 'fixtures'):
+            self.assertEqual(audit(self.project(filename=directory + '/app.py'))['findings'][0]['severity'], 'MEDIUM')
+
+    def test_production_wins(self):
+        root = self.project()
+        (root / 'tests').mkdir()
+        (root / 'tests' / 'test_x.py').write_text("open('x')", encoding='utf-8')
+        finding = audit(root)['findings'][0]
+        self.assertEqual(finding['severity'], 'HIGH')
+        self.assertEqual(len(finding['evidence']), 1)
+
+    def test_env_never_read(self):
+        original = Path.open
+        def guarded(path, *args, **kwargs):
+            if path.name == '.env':
+                raise AssertionError('.env opened')
+            return original(path, *args, **kwargs)
+        with patch.object(Path, 'open', guarded):
+            code, output, error = self.cli(FIXTURES / 'bad', '--json')
+        self.assertEqual(code, 2)
+        self.assertNotIn('ENCODING_AUDIT_ENV_MUST_NEVER_BE_READ_73491', output + error)
+
+    def test_none_encoding(self):
+        self.assertEqual(self.source("open('x', encoding=None)")[0]['kind'], 'wrong-encoding')
+
+    def test_no_claim_invalid_source(self):
+        self.assertEqual(audit(self.project('No promises.', 'broken('))['findings'], [])
+
+    def test_invalid_python(self):
+        self.assertEqual(self.cli(self.project(source='def broken('))[0], 1)
+
+    def test_module_entrypoint(self):
+        result = subprocess.run([sys.executable, '-m', 'encoding_claim_audit', '--version'], capture_output=True, text=True)
+        self.assertEqual((result.returncode, result.stdout.strip()), (0, '0.1.0'))
+
+
+if __name__ == '__main__':
+    unittest.main()