encoding-claim-audit 0.1.0__py3-none-any.whl

encoding_claim_audit/__init__.py

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

encoding_claim_audit/__main__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+encoding_claim_audit/__init__.py,sha256=BZoVM8SxwB_k43aw_jbMSOogMX3Iumm8-UCRbrR3U8o,74
+encoding_claim_audit/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+encoding_claim_audit/audit.py,sha256=l8UldmDYbMQA22AiV1C47M35z-P2VFhlXSXGikEZGBw,5616
+encoding_claim_audit/cli.py,sha256=5SYPrt-kag0C0OJsqKoqjUSaPUadtVMqbNt_PGkbO7w,1939
+encoding_claim_audit-0.1.0.dist-info/licenses/LICENSE,sha256=0wppIt49xM1AQe-H0_B0TVS6Rm8iRfGPI5p0aebGueM,1090
+encoding_claim_audit-0.1.0.dist-info/METADATA,sha256=IhPzV0WZQUqStXX22yChjUSE4cXHrOvEJud7wXOzpk0,3740
+encoding_claim_audit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+encoding_claim_audit-0.1.0.dist-info/entry_points.txt,sha256=7m523uGzJJP6r-tzJKo2Ieui0kr8KJBKtXtogD6wBxU,71
+encoding_claim_audit-0.1.0.dist-info/top_level.txt,sha256=LaTEuo01-CVUY_i6LwLVEdryNRVvMXmy1APdiRjJqTw,21
+encoding_claim_audit-0.1.0.dist-info/RECORD,,

encoding_claim_audit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

encoding_claim_audit-0.1.0.dist-info/entry_points.txt

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

encoding_claim_audit-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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