atomic-claim-audit 0.1.0__tar.gz

atomic_claim_audit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 atomic-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.

atomic_claim_audit-0.1.0/MANIFEST.in

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

atomic_claim_audit-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: atomic-claim-audit
+Version: 0.1.0
+Summary: Offline audit of documented atomic-write claims against Python source.
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# atomic-claim-audit
+
+Offline audit of documented atomic-write claims against Python source.
+Version 0.1.0; Python 3.9 or newer; MIT; no runtime dependencies.
+
+The CLI reads documentation and parses Python ASTs. It never executes audited
+code, uses no network, never reads `.env` file contents, and never writes to
+the audited tree. Symlinked files and directories are skipped.
+
+## Usage
+
+```sh
+python3 -m pip install .
+atomic-claim-audit /path/to/project
+python3 -m atomic_claim_audit /path/to/project --json
+atomic-claim-audit . --ignore 'vendor/*' --ignore 'generated.py' --verbose
+atomic-claim-audit tests/fixtures/testonly --fail-on HIGH
+atomic-claim-audit --version
+```
+
+The path defaults to the current directory. `--ignore` is repeatable and matches
+case-sensitive relative-path globs. `--verbose` also shows verified families.
+`--json` returns `findings`, `verified_claims`, and `errors` arrays; findings
+include `rule`, `severity`, `family`, `claims`, and all `evidence` records
+(`path`, `line`, `kind`). Verified records include `family` and `claims`.
+Unreadable, invalid UTF-8, and syntactically invalid input files are reported
+as errors, with exit 1, rather than silently treated as clean scans.
+
+## Rules
+
+| Condition | Rule | Severity |
+| --- | --- | --- |
+| Claim and production direct writes | documented-atomic-claim-false | HIGH |
+| Claim and no production Python source | documented-atomic-claim-false (`no-source`) | HIGH |
+| Claim, production source, only test/fixture writes | documented-atomic-claim-false-test-only | MEDIUM |
+| Claim and no direct-write evidence | verified atomic-write family | PASS |
+| No claim | no finding, regardless of writes | PASS |
+
+One finding contains every relevant evidence item; multiple phrases still form
+one `atomic-write` family. Exit codes are 0 for PASS, 2 for findings at the
+threshold, and 1 for usage/input errors. The default `--fail-on MEDIUM` includes
+both severities. `--fail-on HIGH` retains MEDIUM findings but exits 0 for them.
+
+Claims come only from root `README.md` and `docs/**/*.md`. Fenced code is
+excluded; inline code counts. A sentence containing no, not, never, without,
+doesn't, don't, or isn't suppresses every claim in that sentence.
+The exact case-insensitive phrases are: atomic write(s), atomically writes,
+atomically saves, atomically updates, atomic save(s), atomic update(s),
+crash-safe write(s), crash safe write(s), all-or-nothing write(s), and atomic
+file write(s). Parenthetical `(s)` here means the singular and plural forms.
+
+Direct-write evidence consists of `open`, `io.open`, or any `.open` call with
+a literal mode containing `w`, `a`, `x`, or `+`; any `.write_text` or
+`.write_bytes` call; and `shutil.copy`, `shutil.copy2`, or `shutil.move`.
+Production excludes tests/ and fixtures/ directories, test_*.py, *_test.py,
+docs/, and examples/. Test/fixture evidence is collected separately; docs and
+examples never contribute source evidence.
+
+## Differentiation
+
+| Neighbour | Different question |
+| --- | --- |
+| readonly-claim-audit | Whether writes exist, never their atomicity |
+| determinism-claim-audit | Run-to-run stability, never write safety |
+| security-claim-audit | eval/shell/pickle hazards, never write patterns |
+| bandit / ruff | Code issues, never documentation promises |
+| atomicwrites / filelock | Runtime helpers that perform writes or locking; this tool statically audits promises |
+
+## Honest limitations
+
+Only the exact listed phrases count: bare “atomic”, “atomic operations”,
+“atomic config writes”, and “atomic JSON writes” do not. Sentence splitting
+uses `.`, `!`, and `?`; this is a heuristic, not natural-language understanding.
+Static evidence is not a crash-safety proof. Dead code counts. Receiver types,
+import aliases, dynamic calls, and descriptor provenance are not inferred.
+Variable modes and absent modes are skipped as UNKNOWN, never evidence.
+
+`print(..., file=...)`, `os.replace`, `os.rename`, deletion and directory
+operations (`remove`, `unlink`, `mkdir`, `rmdir`), and `os.write` are excluded.
+Replace/rename are the atomic step themselves; descriptor writes are untracked.
+
+Temp-var tracking is per-file and by variable name, without scope or order
+analysis. Names assigned from `tempfile.NamedTemporaryFile`, `mkstemp`,
+`TemporaryFile`, or `SpooledTemporaryFile` (including with bindings and tuple
+unpacking) are tracked. A write whose target is such a name or an attribute
+based on it is excluded. Other direct writes in the same function still count.
+This can miss writes after reassignment or name reuse. No replace-step proof
+is required: a temp write with no replace can leak a file, but does not corrupt
+a final path, so this deliberate leniency is outside the corruption audit.
+Filesystem durability, fsync, cross-filesystem rename, concurrency, and locking
+are not proven. Copy/move destinations count unless they are tracked temp vars.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+The build produces a wheel and sdist under `dist/`. Fixtures ship in the sdist.
+If isolated builds are unavailable offline, use `python3 -m build --no-isolation`.

atomic_claim_audit-0.1.0/README.md

@@ -0,0 +1,101 @@
+# atomic-claim-audit
+
+Offline audit of documented atomic-write claims against Python source.
+Version 0.1.0; Python 3.9 or newer; MIT; no runtime dependencies.
+
+The CLI reads documentation and parses Python ASTs. It never executes audited
+code, uses no network, never reads `.env` file contents, and never writes to
+the audited tree. Symlinked files and directories are skipped.
+
+## Usage
+
+```sh
+python3 -m pip install .
+atomic-claim-audit /path/to/project
+python3 -m atomic_claim_audit /path/to/project --json
+atomic-claim-audit . --ignore 'vendor/*' --ignore 'generated.py' --verbose
+atomic-claim-audit tests/fixtures/testonly --fail-on HIGH
+atomic-claim-audit --version
+```
+
+The path defaults to the current directory. `--ignore` is repeatable and matches
+case-sensitive relative-path globs. `--verbose` also shows verified families.
+`--json` returns `findings`, `verified_claims`, and `errors` arrays; findings
+include `rule`, `severity`, `family`, `claims`, and all `evidence` records
+(`path`, `line`, `kind`). Verified records include `family` and `claims`.
+Unreadable, invalid UTF-8, and syntactically invalid input files are reported
+as errors, with exit 1, rather than silently treated as clean scans.
+
+## Rules
+
+| Condition | Rule | Severity |
+| --- | --- | --- |
+| Claim and production direct writes | documented-atomic-claim-false | HIGH |
+| Claim and no production Python source | documented-atomic-claim-false (`no-source`) | HIGH |
+| Claim, production source, only test/fixture writes | documented-atomic-claim-false-test-only | MEDIUM |
+| Claim and no direct-write evidence | verified atomic-write family | PASS |
+| No claim | no finding, regardless of writes | PASS |
+
+One finding contains every relevant evidence item; multiple phrases still form
+one `atomic-write` family. Exit codes are 0 for PASS, 2 for findings at the
+threshold, and 1 for usage/input errors. The default `--fail-on MEDIUM` includes
+both severities. `--fail-on HIGH` retains MEDIUM findings but exits 0 for them.
+
+Claims come only from root `README.md` and `docs/**/*.md`. Fenced code is
+excluded; inline code counts. A sentence containing no, not, never, without,
+doesn't, don't, or isn't suppresses every claim in that sentence.
+The exact case-insensitive phrases are: atomic write(s), atomically writes,
+atomically saves, atomically updates, atomic save(s), atomic update(s),
+crash-safe write(s), crash safe write(s), all-or-nothing write(s), and atomic
+file write(s). Parenthetical `(s)` here means the singular and plural forms.
+
+Direct-write evidence consists of `open`, `io.open`, or any `.open` call with
+a literal mode containing `w`, `a`, `x`, or `+`; any `.write_text` or
+`.write_bytes` call; and `shutil.copy`, `shutil.copy2`, or `shutil.move`.
+Production excludes tests/ and fixtures/ directories, test_*.py, *_test.py,
+docs/, and examples/. Test/fixture evidence is collected separately; docs and
+examples never contribute source evidence.
+
+## Differentiation
+
+| Neighbour | Different question |
+| --- | --- |
+| readonly-claim-audit | Whether writes exist, never their atomicity |
+| determinism-claim-audit | Run-to-run stability, never write safety |
+| security-claim-audit | eval/shell/pickle hazards, never write patterns |
+| bandit / ruff | Code issues, never documentation promises |
+| atomicwrites / filelock | Runtime helpers that perform writes or locking; this tool statically audits promises |
+
+## Honest limitations
+
+Only the exact listed phrases count: bare “atomic”, “atomic operations”,
+“atomic config writes”, and “atomic JSON writes” do not. Sentence splitting
+uses `.`, `!`, and `?`; this is a heuristic, not natural-language understanding.
+Static evidence is not a crash-safety proof. Dead code counts. Receiver types,
+import aliases, dynamic calls, and descriptor provenance are not inferred.
+Variable modes and absent modes are skipped as UNKNOWN, never evidence.
+
+`print(..., file=...)`, `os.replace`, `os.rename`, deletion and directory
+operations (`remove`, `unlink`, `mkdir`, `rmdir`), and `os.write` are excluded.
+Replace/rename are the atomic step themselves; descriptor writes are untracked.
+
+Temp-var tracking is per-file and by variable name, without scope or order
+analysis. Names assigned from `tempfile.NamedTemporaryFile`, `mkstemp`,
+`TemporaryFile`, or `SpooledTemporaryFile` (including with bindings and tuple
+unpacking) are tracked. A write whose target is such a name or an attribute
+based on it is excluded. Other direct writes in the same function still count.
+This can miss writes after reassignment or name reuse. No replace-step proof
+is required: a temp write with no replace can leak a file, but does not corrupt
+a final path, so this deliberate leniency is outside the corruption audit.
+Filesystem durability, fsync, cross-filesystem rename, concurrency, and locking
+are not proven. Copy/move destinations count unless they are tracked temp vars.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+The build produces a wheel and sdist under `dist/`. Fixtures ship in the sdist.
+If isolated builds are unavailable offline, use `python3 -m build --no-isolation`.

atomic_claim_audit-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "atomic-claim-audit"
+version = "0.1.0"
+description = "Offline audit of documented atomic-write claims against Python source."
+requires-python = ">=3.9"
+license = {text = "MIT"}
+readme = "README.md"
+dependencies = []
+
+[project.scripts]
+atomic-claim-audit = "atomic_claim_audit.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

atomic_claim_audit-0.1.0/setup.cfg

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

atomic_claim_audit-0.1.0/src/atomic_claim_audit/__init__.py

@@ -0,0 +1,2 @@
+"""Audit documented atomic-write claims against static Python evidence."""
+__version__ = '0.1.0'

atomic_claim_audit-0.1.0/src/atomic_claim_audit/__main__.py

@@ -0,0 +1,50 @@
+import argparse
+import json
+import sys
+from . import __version__
+from .audit import 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(description='Offline audit of documented atomic-write claims.')
+    parser.add_argument('path', nargs='?', default='.')
+    parser.add_argument('--json', action='store_true')
+    parser.add_argument('--verbose', action='store_true')
+    parser.add_argument('--ignore', action='append', default=[], metavar='GLOB')
+    parser.add_argument('--fail-on', choices=['MEDIUM', 'HIGH'], default='MEDIUM')
+    parser.add_argument('--version', action='version', version=__version__)
+    args = parser.parse_args(argv)
+    try:
+        report = audit(args.path, args.ignore)
+    except (ValueError, OSError) as exc:
+        parser.error(str(exc))
+    if report['errors']:
+        if args.json:
+            print(json.dumps(report, indent=2))
+        else:
+            for error in report['errors']:
+                print('%s: %s' % (error['path'], error['message']), file=sys.stderr)
+        return 1
+    failed = any(f['severity'] == 'HIGH' or args.fail_on == 'MEDIUM' for f in report['findings'])
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print('FAIL' if failed else 'PASS')
+        for finding in report['findings']:
+            print('%s %s' % (finding['severity'], finding['rule']))
+            for item in finding['evidence']:
+                print('  %s:%s %s' % (item['path'], item['line'], item['kind']))
+        if args.verbose:
+            for claim in report['verified_claims']:
+                print('Verified: ' + claim['family'])
+    return 2 if failed else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

atomic_claim_audit-0.1.0/src/atomic_claim_audit/audit.py

@@ -0,0 +1,147 @@
+"""Offline static audit of documented atomic-write promises."""
+import ast
+import fnmatch
+import re
+from pathlib import Path
+
+PHRASES = (
+    'atomic write', 'atomic writes', 'atomically writes', 'atomically saves',
+    'atomically updates', 'atomic save', 'atomic saves', 'atomic update',
+    'atomic updates', 'crash-safe write', 'crash-safe writes', 'crash safe write',
+    'crash safe writes', 'all-or-nothing write', 'all-or-nothing writes',
+    'atomic file write', 'atomic file writes',
+)
+CLAIM = re.compile(r'\b(?:' + '|'.join(sorted(PHRASES, key=len, reverse=True)) + r')\b', re.I)
+NEGATION = re.compile(r"\b(?:no|not|never|without|doesn't|don't|isn't)\b", re.I)
+TEMP_CALLS = {'tempfile.NamedTemporaryFile', 'tempfile.mkstemp',
+              'tempfile.TemporaryFile', 'tempfile.SpooledTemporaryFile'}
+
+
+def dotted(node):
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return dotted(node.value) + '.' + node.attr
+    return ''
+
+
+def base_name(node):
+    while isinstance(node, ast.Attribute):
+        node = node.value
+    return node.id if isinstance(node, ast.Name) else None
+
+
+def claims_in(text, path):
+    """Extract one record per claiming sentence, preserving source lines."""
+    lines = []
+    fence = None
+    for line in text.splitlines():
+        marker = re.match(r'^\s{0,3}(`{3,}|~{3,})', line)
+        if fence:
+            if marker and marker.group(1)[0] == fence[0] and len(marker.group(1)) >= len(fence):
+                fence = None
+            lines.append('')
+        elif marker:
+            fence = marker.group(1)
+            lines.append('')
+        else:
+            lines.append(line)
+    prose = '\n'.join(lines)
+    result = []
+    for match in re.finditer(r'[^.!?]+(?:[.!?]|$)', prose):
+        sentence = match.group()
+        phrase = CLAIM.search(sentence)
+        if phrase and not NEGATION.search(sentence):
+            offset = match.start() + phrase.start()
+            result.append({'family': 'atomic-write', 'path': path,
+                           'line': prose.count('\n', 0, offset) + 1,
+                           'phrase': phrase.group()})
+    return result
+
+
+def evidence_in(text, path):
+    tree = ast.parse(text, filename=path)
+    temps = set()
+    for node in ast.walk(tree):
+        value = getattr(node, 'value', None)
+        if isinstance(value, ast.Call) and dotted(value.func) in TEMP_CALLS:
+            targets = node.targets if isinstance(node, ast.Assign) else [getattr(node, 'target', None)]
+            for target in targets:
+                if target:
+                    temps.update(n.id for n in ast.walk(target) if isinstance(n, ast.Name))
+        if isinstance(node, ast.withitem) and isinstance(node.context_expr, ast.Call):
+            if dotted(node.context_expr.func) in TEMP_CALLS and node.optional_vars:
+                temps.update(n.id for n in ast.walk(node.optional_vars) if isinstance(n, ast.Name))
+    found = {}
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        name = dotted(node.func)
+        attr = node.func.attr if isinstance(node.func, ast.Attribute) else ''
+        target = None
+        kind = None
+        if name in {'shutil.copy', 'shutil.copy2', 'shutil.move'}:
+            kind = name
+            target = node.args[1] if len(node.args) > 1 else next((k.value for k in node.keywords if k.arg == 'dst'), None)
+        elif attr in {'write_text', 'write_bytes'}:
+            kind = attr
+            target = node.func.value
+        elif name in {'open', 'io.open'} or attr == 'open':
+            builtin = name in {'open', 'io.open'}
+            index = 1 if builtin else 0
+            mode = node.args[index] if len(node.args) > index else next((k.value for k in node.keywords if k.arg == 'mode'), None)
+            if isinstance(mode, ast.Constant) and isinstance(mode.value, str) and any(c in mode.value for c in 'wax+'):
+                kind = name if builtin else 'Path.open'
+                target = (node.args[0] if node.args else next((k.value for k in node.keywords if k.arg == 'file'), None)) if builtin else node.func.value
+        if kind and base_name(target) not in temps:
+            found[(node.lineno, kind)] = {'path': path, 'line': node.lineno, 'kind': kind}
+    return sorted(found.values(), key=lambda e: (e['line'], e['kind']))
+
+
+def audit(root, ignore=()):
+    root = Path(root)
+    if not root.is_dir():
+        raise ValueError('audit path must be a directory')
+    claims, production, testonly, errors = [], [], [], []
+    source_count = 0
+    for path in sorted(root.rglob('*')):
+        relative = path.relative_to(root).as_posix()
+        if path.is_symlink() or any(p.is_symlink() for p in path.parents if p != root.parent):
+            continue
+        if not path.is_file() or path.name == '.env' or path.name.startswith('.env.'):
+            continue
+        if any(fnmatch.fnmatchcase(relative, pattern) for pattern in ignore):
+            continue
+        parts = path.relative_to(root).parts
+        doc = relative == 'README.md' or (parts[0] == 'docs' and path.suffix == '.md')
+        source = path.suffix == '.py' and not any(p in {'docs', 'examples'} for p in parts[:-1])
+        if not doc and not source:
+            continue
+        is_test = any(p in {'tests', 'fixtures'} for p in parts[:-1]) or path.name.startswith('test_') or path.name.endswith('_test.py')
+        if source and not is_test:
+            source_count += 1
+        try:
+            text = path.read_text(encoding='utf-8')
+            if doc:
+                claims.extend(claims_in(text, relative))
+            if source:
+                (testonly if is_test else production).extend(evidence_in(text, relative))
+        except (OSError, UnicodeError, SyntaxError) as exc:
+            errors.append({'path': relative, 'message': str(exc)})
+    findings, verified = [], []
+    if claims:
+        evidence = production
+        severity = 'HIGH'
+        rule = 'documented-atomic-claim-false'
+        if not source_count:
+            evidence = [{'path': '.', 'line': 0, 'kind': 'no-source'}]
+        elif not production and testonly:
+            evidence = testonly
+            severity = 'MEDIUM'
+            rule += '-test-only'
+        if evidence:
+            findings.append({'rule': rule, 'severity': severity, 'family': 'atomic-write',
+                             'claims': claims, 'evidence': evidence})
+        else:
+            verified = [{'family': 'atomic-write', 'claims': claims}]
+    return {'findings': findings, 'verified_claims': verified, 'errors': errors}

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

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: atomic-claim-audit
+Version: 0.1.0
+Summary: Offline audit of documented atomic-write claims against Python source.
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# atomic-claim-audit
+
+Offline audit of documented atomic-write claims against Python source.
+Version 0.1.0; Python 3.9 or newer; MIT; no runtime dependencies.
+
+The CLI reads documentation and parses Python ASTs. It never executes audited
+code, uses no network, never reads `.env` file contents, and never writes to
+the audited tree. Symlinked files and directories are skipped.
+
+## Usage
+
+```sh
+python3 -m pip install .
+atomic-claim-audit /path/to/project
+python3 -m atomic_claim_audit /path/to/project --json
+atomic-claim-audit . --ignore 'vendor/*' --ignore 'generated.py' --verbose
+atomic-claim-audit tests/fixtures/testonly --fail-on HIGH
+atomic-claim-audit --version
+```
+
+The path defaults to the current directory. `--ignore` is repeatable and matches
+case-sensitive relative-path globs. `--verbose` also shows verified families.
+`--json` returns `findings`, `verified_claims`, and `errors` arrays; findings
+include `rule`, `severity`, `family`, `claims`, and all `evidence` records
+(`path`, `line`, `kind`). Verified records include `family` and `claims`.
+Unreadable, invalid UTF-8, and syntactically invalid input files are reported
+as errors, with exit 1, rather than silently treated as clean scans.
+
+## Rules
+
+| Condition | Rule | Severity |
+| --- | --- | --- |
+| Claim and production direct writes | documented-atomic-claim-false | HIGH |
+| Claim and no production Python source | documented-atomic-claim-false (`no-source`) | HIGH |
+| Claim, production source, only test/fixture writes | documented-atomic-claim-false-test-only | MEDIUM |
+| Claim and no direct-write evidence | verified atomic-write family | PASS |
+| No claim | no finding, regardless of writes | PASS |
+
+One finding contains every relevant evidence item; multiple phrases still form
+one `atomic-write` family. Exit codes are 0 for PASS, 2 for findings at the
+threshold, and 1 for usage/input errors. The default `--fail-on MEDIUM` includes
+both severities. `--fail-on HIGH` retains MEDIUM findings but exits 0 for them.
+
+Claims come only from root `README.md` and `docs/**/*.md`. Fenced code is
+excluded; inline code counts. A sentence containing no, not, never, without,
+doesn't, don't, or isn't suppresses every claim in that sentence.
+The exact case-insensitive phrases are: atomic write(s), atomically writes,
+atomically saves, atomically updates, atomic save(s), atomic update(s),
+crash-safe write(s), crash safe write(s), all-or-nothing write(s), and atomic
+file write(s). Parenthetical `(s)` here means the singular and plural forms.
+
+Direct-write evidence consists of `open`, `io.open`, or any `.open` call with
+a literal mode containing `w`, `a`, `x`, or `+`; any `.write_text` or
+`.write_bytes` call; and `shutil.copy`, `shutil.copy2`, or `shutil.move`.
+Production excludes tests/ and fixtures/ directories, test_*.py, *_test.py,
+docs/, and examples/. Test/fixture evidence is collected separately; docs and
+examples never contribute source evidence.
+
+## Differentiation
+
+| Neighbour | Different question |
+| --- | --- |
+| readonly-claim-audit | Whether writes exist, never their atomicity |
+| determinism-claim-audit | Run-to-run stability, never write safety |
+| security-claim-audit | eval/shell/pickle hazards, never write patterns |
+| bandit / ruff | Code issues, never documentation promises |
+| atomicwrites / filelock | Runtime helpers that perform writes or locking; this tool statically audits promises |
+
+## Honest limitations
+
+Only the exact listed phrases count: bare “atomic”, “atomic operations”,
+“atomic config writes”, and “atomic JSON writes” do not. Sentence splitting
+uses `.`, `!`, and `?`; this is a heuristic, not natural-language understanding.
+Static evidence is not a crash-safety proof. Dead code counts. Receiver types,
+import aliases, dynamic calls, and descriptor provenance are not inferred.
+Variable modes and absent modes are skipped as UNKNOWN, never evidence.
+
+`print(..., file=...)`, `os.replace`, `os.rename`, deletion and directory
+operations (`remove`, `unlink`, `mkdir`, `rmdir`), and `os.write` are excluded.
+Replace/rename are the atomic step themselves; descriptor writes are untracked.
+
+Temp-var tracking is per-file and by variable name, without scope or order
+analysis. Names assigned from `tempfile.NamedTemporaryFile`, `mkstemp`,
+`TemporaryFile`, or `SpooledTemporaryFile` (including with bindings and tuple
+unpacking) are tracked. A write whose target is such a name or an attribute
+based on it is excluded. Other direct writes in the same function still count.
+This can miss writes after reassignment or name reuse. No replace-step proof
+is required: a temp write with no replace can leak a file, but does not corrupt
+a final path, so this deliberate leniency is outside the corruption audit.
+Filesystem durability, fsync, cross-filesystem rename, concurrency, and locking
+are not proven. Copy/move destinations count unless they are tracked temp vars.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+The build produces a wheel and sdist under `dist/`. Fixtures ship in the sdist.
+If isolated builds are unavailable offline, use `python3 -m build --no-isolation`.

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

@@ -0,0 +1,20 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/atomic_claim_audit/__init__.py
+src/atomic_claim_audit/__main__.py
+src/atomic_claim_audit/audit.py
+src/atomic_claim_audit.egg-info/PKG-INFO
+src/atomic_claim_audit.egg-info/SOURCES.txt
+src/atomic_claim_audit.egg-info/dependency_links.txt
+src/atomic_claim_audit.egg-info/entry_points.txt
+src/atomic_claim_audit.egg-info/top_level.txt
+tests/test_audit.py
+tests/fixtures/bad/README.md
+tests/fixtures/bad/main.py
+tests/fixtures/good/README.md
+tests/fixtures/good/main.py
+tests/fixtures/testonly/README.md
+tests/fixtures/testonly/main.py
+tests/fixtures/testonly/tests/test_write.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+[console_scripts]
+atomic-claim-audit = atomic_claim_audit.__main__:main

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

@@ -0,0 +1 @@
+atomic_claim_audit

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

@@ -0,0 +1 @@
+This tool provides atomic writes and crash-safe writes.

atomic_claim_audit-0.1.0/tests/fixtures/bad/main.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+import shutil
+
+
+def save(path, source):
+    Path(path).write_text('data')
+    with open(path, 'w') as stream:
+        stream.write('data')
+    shutil.copy2(source, path)

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

@@ -0,0 +1 @@
+This tool provides atomic writes.

atomic_claim_audit-0.1.0/tests/fixtures/good/main.py

@@ -0,0 +1,8 @@
+import os
+import tempfile
+
+
+def save(path, text):
+    with tempfile.NamedTemporaryFile(mode='w', delete=False) as temp:
+        temp.write(text)
+    os.replace(temp.name, path)

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

@@ -0,0 +1 @@
+This tool provides atomic writes.

atomic_claim_audit-0.1.0/tests/fixtures/testonly/main.py

@@ -0,0 +1,2 @@
+def value():
+    return 42

atomic_claim_audit-0.1.0/tests/fixtures/testonly/tests/test_write.py

@@ -0,0 +1,3 @@
+def write_example(path):
+    with open(path, 'w') as stream:
+        stream.write('data')

atomic_claim_audit-0.1.0/tests/test_audit.py

@@ -0,0 +1,192 @@
+import contextlib
+import io
+import json
+from pathlib import Path
+import tempfile
+import unittest
+
+from atomic_claim_audit.audit import PHRASES, audit, claims_in, evidence_in
+from atomic_claim_audit.__main__ import main
+
+FIXTURES = Path(__file__).parent / 'fixtures'
+
+
+class AuditTests(unittest.TestCase):
+    def project(self, files, ignore=()):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            for name, text in files.items():
+                path = root / name
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(text, encoding='utf-8')
+            return audit(root, ignore)
+
+    def test_good(self):
+        report = audit(FIXTURES / 'good')
+        self.assertEqual(report['findings'], [])
+        self.assertEqual(report['verified_claims'][0]['family'], 'atomic-write')
+
+    def test_bad(self):
+        findings = audit(FIXTURES / 'bad')['findings']
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0]['rule'], 'documented-atomic-claim-false')
+        self.assertEqual(findings[0]['severity'], 'HIGH')
+        self.assertEqual(len(findings[0]['evidence']), 3)
+
+    def test_testonly(self):
+        finding = audit(FIXTURES / 'testonly')['findings'][0]
+        self.assertEqual(finding['severity'], 'MEDIUM')
+        self.assertEqual(finding['rule'], 'documented-atomic-claim-false-test-only')
+        self.assertEqual(len(finding['evidence']), 1)
+
+    def test_no_source(self):
+        r = self.project({'README.md': 'Atomic writes.'})
+        self.assertEqual(r['findings'][0]['evidence'][0]['kind'], 'no-source')
+
+    def test_no_claim(self):
+        self.assertEqual(self.project({'main.py': 'open(p,"w")'})['findings'], [])
+
+    def test_docs_claim(self):
+        r = self.project({'docs/sub/a.md': 'Atomic writes.', 'main.py': 'open(p,"w")'})
+        self.assertEqual(len(r['findings']), 1)
+
+    def test_other_docs_ignored(self):
+        r = self.project({'other.md': 'Atomic writes.', 'main.py': 'open(p,"w")'})
+        self.assertEqual(r['findings'], [])
+
+    def test_ignore(self):
+        r = self.project({'README.md': 'Atomic writes.', 'main.py': 'pass', 'bad.py': 'open(p,"w")'}, ['bad.py'])
+        self.assertTrue(r['verified_claims'])
+
+    def test_ignore_glob(self):
+        r = self.project({'README.md': 'Atomic writes.', 'main.py': 'pass', 'vendor/a.py': 'open(p,"w")'}, ['vendor/*'])
+        self.assertTrue(r['verified_claims'])
+
+    def test_temp_and_direct(self):
+        text = 't = tempfile.NamedTemporaryFile()\nopen(t.name,"w")\nopen(final,"w")'
+        self.assertEqual(len(evidence_in(text, 'a.py')), 1)
+
+    def test_temp_no_replace(self):
+        text = 't = tempfile.NamedTemporaryFile()\nt.write_text("data")'
+        self.assertEqual(evidence_in(text, 'a.py'), [])
+
+    def test_dead_code(self):
+        self.assertEqual(len(evidence_in('if False:\n open(p,"w")', 'a.py')), 1)
+
+    def test_dedupe(self):
+        self.assertEqual(len(evidence_in('open(p,"w"); open(q,"w")', 'a.py')), 1)
+
+    def test_invalid_source(self):
+        r = self.project({'main.py': 'def ('})
+        self.assertEqual(len(r['errors']), 1)
+
+    def test_env_not_read(self):
+        r = self.project({'.env': 'secret', '.env.py': 'invalid syntax!', 'main.py': 'pass'})
+        self.assertEqual(r['errors'], [])
+
+    def test_symlink(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d)
+            (root / 'README.md').write_text('Atomic writes.')
+            (root / 'main.py').write_text('pass')
+            (root / 'link.py').symlink_to(FIXTURES / 'bad' / 'main.py')
+            (root / 'linked').symlink_to(FIXTURES / 'bad', target_is_directory=True)
+            self.assertTrue(audit(root)['verified_claims'])
+
+    def test_json(self):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            code = main([str(FIXTURES / 'good'), '--json'])
+        self.assertEqual(code, 0)
+        self.assertEqual(set(json.loads(output.getvalue())), {'findings', 'verified_claims', 'errors'})
+
+    def test_threshold(self):
+        with contextlib.redirect_stdout(io.StringIO()):
+            self.assertEqual(main([str(FIXTURES / 'testonly')]), 2)
+            self.assertEqual(main([str(FIXTURES / 'testonly'), '--fail-on', 'HIGH']), 0)
+            self.assertEqual(main([str(FIXTURES / 'bad'), '--fail-on', 'HIGH']), 2)
+
+    def test_version(self):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output), self.assertRaises(SystemExit) as exc:
+            main(['--version'])
+        self.assertEqual(exc.exception.code, 0)
+        self.assertEqual(output.getvalue().strip(), '0.1.0')
+
+    def test_usage(self):
+        with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as exc:
+            main(['--unknown'])
+        self.assertEqual(exc.exception.code, 1)
+
+    def test_missing_directory(self):
+        with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as exc:
+            main(['/missing-atomic-claim-audit'])
+        self.assertEqual(exc.exception.code, 1)
+
+    def test_verbose(self):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            main([str(FIXTURES / 'good'), '--verbose'])
+        self.assertIn('Verified: atomic-write', output.getvalue())
+
+
+def claim_case(text, expected):
+    def test(self):
+        self.assertEqual(bool(claims_in(text, 'README.md')), expected)
+    return test
+
+
+for index, phrase in enumerate(PHRASES):
+    setattr(AuditTests, 'test_phrase_%02d' % index, claim_case('Uses ' + phrase.upper() + '.', True))
+for index, text in enumerate([
+    'Atomic operations.', 'Atomic counters.', 'Atomic config writes.',
+    'Atomic JSON writes.', 'Atomically reads.', 'Nonatomic writes.',
+    '```md\nAtomic writes.\n```', '~~~\nAtomic writes.\n~~~',
+    'No atomic writes.', 'Not atomic writes.', 'Never atomic writes.',
+    'Without atomic writes.', "It doesn't support atomic writes.",
+    "Don't promise atomic writes.", "It isn't atomic writes.",
+]):
+    setattr(AuditTests, 'test_nonclaim_%02d' % index, claim_case(text, False))
+setattr(AuditTests, 'test_inline_claim', claim_case('Supports `atomic writes`.', True))
+setattr(AuditTests, 'test_sentence_negation', claim_case('No guarantees. Atomic writes.', True))
+
+
+def evidence_case(source, count):
+    def test(self):
+        self.assertEqual(len(evidence_in(source, 'main.py')), count)
+    return test
+
+
+for index, (source, count) in enumerate([
+    ('open(p,"w")', 1), ('open(p,"wb")', 1), ('open(p,"a+")', 1),
+    ('open(p,"x")', 1), ('open(p,"r+")', 1), ('open(p,"r")', 0),
+    ('open(p)', 0), ('open(p,mode)', 0), ('io.open(p,mode="w")', 1),
+    ('open(file=p,mode="w")', 1), ('p.open("wb")', 1), ('p.open(mode="a")', 1),
+    ('p.open()', 0), ('p.open(mode=m)', 0), ('p.write_text("x")', 1),
+    ('Path(p).write_bytes(b"x")', 1), ('shutil.copy(a,b)', 1),
+    ('shutil.copy2(a,b)', 1), ('shutil.move(a,b)', 1),
+    ('os.replace(a,b)', 0), ('os.rename(a,b)', 0), ('print("x",file=f)', 0),
+    ('os.write(fd,b"x")', 0), ('p.unlink()', 0), ('p.mkdir()', 0),
+    ('t=tempfile.NamedTemporaryFile()\nopen(t.name,"w")', 0),
+    ('fd,t=tempfile.mkstemp()\nopen(t,"wb")', 0),
+    ('t=tempfile.TemporaryFile()\nt.write_bytes(b"x")', 0),
+    ('t=tempfile.SpooledTemporaryFile()\nt.open("w")', 0),
+    ('with tempfile.NamedTemporaryFile() as t:\n open(t.name,"w")', 0),
+    ('t=tempfile.NamedTemporaryFile()\nshutil.copy2(a,t.name)', 0),
+    ('def f():\n t=tempfile.NamedTemporaryFile()\n open(t.name,"w")\n os.replace(t.name,p)\n p.write_text("x")', 1),
+]):
+    setattr(AuditTests, 'test_evidence_%02d' % index, evidence_case(source, count))
+
+for index, path in enumerate(['tests/a.py', 'fixtures/a.py', 'test_a.py', 'a_test.py']):
+    def test(self, path=path):
+        r = self.project({'README.md': 'Atomic writes.', 'main.py': 'pass', path: 'open(p,"w")'})
+        self.assertEqual(r['findings'][0]['severity'], 'MEDIUM')
+    setattr(AuditTests, 'test_test_path_%02d' % index, test)
+for index, path in enumerate(['docs/a.py', 'examples/a.py']):
+    def test(self, path=path):
+        r = self.project({'README.md': 'Atomic writes.', 'main.py': 'pass', path: 'open(p,"w")'})
+        self.assertTrue(r['verified_claims'])
+    setattr(AuditTests, 'test_excluded_path_%02d' % index, test)
+
+if __name__ == '__main__':
+    unittest.main()