thread-safety-claim-audit 0.1.0__tar.gz

thread_safety_claim_audit-0.1.0/LICENSE

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

thread_safety_claim_audit-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+recursive-include tests *.py *.md
+recursive-include tests/fixtures *

thread_safety_claim_audit-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: thread-safety-claim-audit
+Version: 0.1.0
+Summary: Offline audit of documented thread-safety claims against Python source.
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# thread-safety-claim-audit
+
+Offline audit of documented thread-safety claims against Python source.
+
+Version 0.1.0. A standard-library-only CLI for comparing documentation promises
+about concurrent safety with static synchronisation evidence. No audited code
+is executed, no network is used, and `.env` contents are never opened.
+
+## Usage
+
+Requires Python 3.9 or later. Install and run:
+
+```sh
+python3 -m pip install .
+thread-safety-claim-audit path/to/project
+python3 -m thread_safety_claim_audit path/to/project --json
+thread-safety-claim-audit . --verbose --ignore 'vendor/*' --fail-on HIGH
+python3 -m thread_safety_claim_audit --version
+```
+
+The path defaults to the current directory. `--ignore GLOB` is repeatable and
+matches relative paths. `--verbose` includes evidence and verified families.
+`--json` emits an object with `findings` and `verified_claims` arrays. Findings
+contain `rule`, `severity`, `family`, `claims`, and `evidence`; claim records
+contain a path, line, sentence, and family. Evidence records contain a path,
+line, and kind, except the `no-source` sentinel. Verified records contain a
+family, claims, and evidence. Exit 0 means PASS; exit 2 means findings at or
+above the selected threshold; exit 1 means a usage, reading, or parsing error.
+The default threshold is MEDIUM. HIGH leaves MEDIUM findings visible while
+allowing exit 0.
+
+## Claims
+
+Only root `README.md` and `docs/**/*.md` supply claims. Fenced code blocks are
+excluded; inline code counts as prose. Sentences are lowercased, `n't` becomes
+` not`, hyphens become spaces, and whitespace collapses. Exact phrases, with
+word boundaries, are matched; there is no optional-word expansion.
+
+The complete normalized phrase vocabulary is below:
+
+```text
+THREADSAFE:
+thread safe
+safe for concurrent use
+safe to call from multiple threads
+safe to use from multiple threads
+safe to use concurrently
+safe across threads
+safe for multithreaded use
+safe for multi threaded use
+thread safe by design
+
+NOTSAFE:
+not thread safe
+not safe for concurrent use
+not safe to call from multiple threads
+not safe to use from multiple threads
+not safe to use concurrently
+not safe across threads
+not safe for multithreaded use
+not safe for multi threaded use
+no thread safety
+must not be called from multiple threads
+must not be used from multiple threads
+```
+
+NOTSAFE spans are matched and masked first to prevent substring overlap.
+Negation words (`no`, `not`, `never`, `without`, including normalized
+contractions) suppress THREADSAFE for the whole sentence; listed NOTSAFE
+phrases still count. This asymmetry means the following examples behave as
+shown:
+
+```text
+is not thread-safe       => notsafe only
+isn't thread-safe        => notsafe only
+never thread safe       => no claim
+does not claim to be thread safe => no claim
+thread safety           => no claim (bare noun)
+threadsafe              => no claim (one word)
+```
+
+## Rules
+
+Each family is evaluated independently, including contradictory documentation.
+Each finding lists all family claim sentences and all applicable evidence.
+
+```text
+| Rule | Severity | Trigger |
+| --- | --- | --- |
+| `documented-thread-safe-claim-false` | HIGH | THREADSAFE with no production evidence |
+| `documented-thread-safe-claim-false-test-only` | MEDIUM | THREADSAFE with evidence only in tests/fixtures |
+| `documented-not-thread-safe-claim-false` | HIGH | NOTSAFE with production evidence |
+| `documented-not-thread-safe-claim-false-test-only` | MEDIUM | NOTSAFE with evidence only in tests/fixtures |
+
+```
+
+No production Python source produces one HIGH finding per claimed family with
+`no-source` evidence. THREADSAFE with production evidence is verified; NOTSAFE
+with no evidence anywhere is verified. No claim yields PASS regardless of
+source evidence. There are no other reverse rules.
+
+## Named evidence
+
+| Kind | Recognized syntax |
+| --- | --- |
+| `lock-constructor` | Calls to threading Lock, RLock, Semaphore, BoundedSemaphore, Condition; multiprocessing Lock or RLock |
+| `thread-local` | Call to threading.local |
+| `acquire` | Attribute call `.acquire(...)` on any receiver |
+| `with-lock` | With context Name or Attribute whose name contains `lock`, case-insensitively |
+
+Module and from-import aliases are tracked per file. Bare constructor calls
+need a matching import from threading or multiprocessing (multiprocessing
+bare imports count only for Lock and RLock, matching the attribute form).
+Evidence is deduplicated by file, line, and kind.
+Production excludes tests directories, test filename patterns, fixtures,
+docs, examples, and symlinked files. Test filename patterns and tests/fixtures
+are collected separately; docs and examples never supply evidence. Symlinked
+directories are not traversed. Build outputs, virtual environments, and Git
+metadata are skipped. Ignored files supply neither claims nor evidence.
+
+## Differentiation
+
+- concurrency-claim-audit checks existence of parallel execution, not synchronisation.
+- determinism-claim-audit checks run-to-run stability, not concurrent safety.
+- security-claim-audit checks eval, shell, and pickle hazards, not locks.
+- bandit and ruff inspect code issues without comparing documentation promises.
+- The two PyPI neighbours named below are multi-language concurrency issue
+  linters. This tool compares docs promises with source evidence.
+
+```text
+thread-safety / thread-safe-check
+```
+- Python threading documentation describes primitives rather than auditing
+  documentation against implementation.
+
+## Honest limitations
+
+This is a static heuristic, not a race detector or proof. Dead code counts:
+constructors in uncalled code still supply evidence. Receiver types, import
+shadowing, guard coverage, correct lock use, and actual shared-state mutation
+are not inferred. Even `.acquire` on a clearly unrelated object counts.
+A constructor does not prove that every shared access is guarded.
+
+Bare threading imports and Thread imports provide no evidence. Thread, Pool,
+Executor creation and concurrent.futures use concern execution, not protection.
+asyncio.Lock is excluded because it is a single-threaded coroutine primitive.
+queue.Queue is excluded because its internal protection says nothing about the
+surrounding object. A bare Lock name, import, annotation, or attribute access
+without a call does not count. threading.Barrier and threading.Event are
+coordination primitives rather than mutual exclusion and are excluded.
+Dynamic imports and custom guard wrappers may be missed. Exact-phrase claims
+miss paraphrases. Markdown and sentence parsing are deliberately lightweight;
+claim line numbers identify the start of the containing prose paragraph.
+Invalid source or unreadable input results in exit 1 rather than a silent PASS.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+The sdist includes the regression fixtures. Runtime dependencies: none.

thread_safety_claim_audit-0.1.0/README.md

@@ -0,0 +1,163 @@
+# thread-safety-claim-audit
+
+Offline audit of documented thread-safety claims against Python source.
+
+Version 0.1.0. A standard-library-only CLI for comparing documentation promises
+about concurrent safety with static synchronisation evidence. No audited code
+is executed, no network is used, and `.env` contents are never opened.
+
+## Usage
+
+Requires Python 3.9 or later. Install and run:
+
+```sh
+python3 -m pip install .
+thread-safety-claim-audit path/to/project
+python3 -m thread_safety_claim_audit path/to/project --json
+thread-safety-claim-audit . --verbose --ignore 'vendor/*' --fail-on HIGH
+python3 -m thread_safety_claim_audit --version
+```
+
+The path defaults to the current directory. `--ignore GLOB` is repeatable and
+matches relative paths. `--verbose` includes evidence and verified families.
+`--json` emits an object with `findings` and `verified_claims` arrays. Findings
+contain `rule`, `severity`, `family`, `claims`, and `evidence`; claim records
+contain a path, line, sentence, and family. Evidence records contain a path,
+line, and kind, except the `no-source` sentinel. Verified records contain a
+family, claims, and evidence. Exit 0 means PASS; exit 2 means findings at or
+above the selected threshold; exit 1 means a usage, reading, or parsing error.
+The default threshold is MEDIUM. HIGH leaves MEDIUM findings visible while
+allowing exit 0.
+
+## Claims
+
+Only root `README.md` and `docs/**/*.md` supply claims. Fenced code blocks are
+excluded; inline code counts as prose. Sentences are lowercased, `n't` becomes
+` not`, hyphens become spaces, and whitespace collapses. Exact phrases, with
+word boundaries, are matched; there is no optional-word expansion.
+
+The complete normalized phrase vocabulary is below:
+
+```text
+THREADSAFE:
+thread safe
+safe for concurrent use
+safe to call from multiple threads
+safe to use from multiple threads
+safe to use concurrently
+safe across threads
+safe for multithreaded use
+safe for multi threaded use
+thread safe by design
+
+NOTSAFE:
+not thread safe
+not safe for concurrent use
+not safe to call from multiple threads
+not safe to use from multiple threads
+not safe to use concurrently
+not safe across threads
+not safe for multithreaded use
+not safe for multi threaded use
+no thread safety
+must not be called from multiple threads
+must not be used from multiple threads
+```
+
+NOTSAFE spans are matched and masked first to prevent substring overlap.
+Negation words (`no`, `not`, `never`, `without`, including normalized
+contractions) suppress THREADSAFE for the whole sentence; listed NOTSAFE
+phrases still count. This asymmetry means the following examples behave as
+shown:
+
+```text
+is not thread-safe       => notsafe only
+isn't thread-safe        => notsafe only
+never thread safe       => no claim
+does not claim to be thread safe => no claim
+thread safety           => no claim (bare noun)
+threadsafe              => no claim (one word)
+```
+
+## Rules
+
+Each family is evaluated independently, including contradictory documentation.
+Each finding lists all family claim sentences and all applicable evidence.
+
+```text
+| Rule | Severity | Trigger |
+| --- | --- | --- |
+| `documented-thread-safe-claim-false` | HIGH | THREADSAFE with no production evidence |
+| `documented-thread-safe-claim-false-test-only` | MEDIUM | THREADSAFE with evidence only in tests/fixtures |
+| `documented-not-thread-safe-claim-false` | HIGH | NOTSAFE with production evidence |
+| `documented-not-thread-safe-claim-false-test-only` | MEDIUM | NOTSAFE with evidence only in tests/fixtures |
+
+```
+
+No production Python source produces one HIGH finding per claimed family with
+`no-source` evidence. THREADSAFE with production evidence is verified; NOTSAFE
+with no evidence anywhere is verified. No claim yields PASS regardless of
+source evidence. There are no other reverse rules.
+
+## Named evidence
+
+| Kind | Recognized syntax |
+| --- | --- |
+| `lock-constructor` | Calls to threading Lock, RLock, Semaphore, BoundedSemaphore, Condition; multiprocessing Lock or RLock |
+| `thread-local` | Call to threading.local |
+| `acquire` | Attribute call `.acquire(...)` on any receiver |
+| `with-lock` | With context Name or Attribute whose name contains `lock`, case-insensitively |
+
+Module and from-import aliases are tracked per file. Bare constructor calls
+need a matching import from threading or multiprocessing (multiprocessing
+bare imports count only for Lock and RLock, matching the attribute form).
+Evidence is deduplicated by file, line, and kind.
+Production excludes tests directories, test filename patterns, fixtures,
+docs, examples, and symlinked files. Test filename patterns and tests/fixtures
+are collected separately; docs and examples never supply evidence. Symlinked
+directories are not traversed. Build outputs, virtual environments, and Git
+metadata are skipped. Ignored files supply neither claims nor evidence.
+
+## Differentiation
+
+- concurrency-claim-audit checks existence of parallel execution, not synchronisation.
+- determinism-claim-audit checks run-to-run stability, not concurrent safety.
+- security-claim-audit checks eval, shell, and pickle hazards, not locks.
+- bandit and ruff inspect code issues without comparing documentation promises.
+- The two PyPI neighbours named below are multi-language concurrency issue
+  linters. This tool compares docs promises with source evidence.
+
+```text
+thread-safety / thread-safe-check
+```
+- Python threading documentation describes primitives rather than auditing
+  documentation against implementation.
+
+## Honest limitations
+
+This is a static heuristic, not a race detector or proof. Dead code counts:
+constructors in uncalled code still supply evidence. Receiver types, import
+shadowing, guard coverage, correct lock use, and actual shared-state mutation
+are not inferred. Even `.acquire` on a clearly unrelated object counts.
+A constructor does not prove that every shared access is guarded.
+
+Bare threading imports and Thread imports provide no evidence. Thread, Pool,
+Executor creation and concurrent.futures use concern execution, not protection.
+asyncio.Lock is excluded because it is a single-threaded coroutine primitive.
+queue.Queue is excluded because its internal protection says nothing about the
+surrounding object. A bare Lock name, import, annotation, or attribute access
+without a call does not count. threading.Barrier and threading.Event are
+coordination primitives rather than mutual exclusion and are excluded.
+Dynamic imports and custom guard wrappers may be missed. Exact-phrase claims
+miss paraphrases. Markdown and sentence parsing are deliberately lightweight;
+claim line numbers identify the start of the containing prose paragraph.
+Invalid source or unreadable input results in exit 1 rather than a silent PASS.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+The sdist includes the regression fixtures. Runtime dependencies: none.

thread_safety_claim_audit-0.1.0/pyproject.toml

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

thread_safety_claim_audit-0.1.0/setup.cfg

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

thread_safety_claim_audit-0.1.0/src/thread_safety_claim_audit/__init__.py

@@ -0,0 +1,2 @@
+"""Documentation contract auditing."""
+__version__ = '0.1.0'

thread_safety_claim_audit-0.1.0/src/thread_safety_claim_audit/__main__.py

@@ -0,0 +1,4 @@
+from .audit import main
+
+if __name__ == '__main__':
+    raise SystemExit(main())

thread_safety_claim_audit-0.1.0/src/thread_safety_claim_audit/audit.py

@@ -0,0 +1,208 @@
+"""Offline documentation contract checks using static syntax only."""
+import argparse
+import ast
+import fnmatch
+import json
+import os
+from pathlib import Path
+import re
+import sys
+
+THREADSAFE = (
+    'thread safe', 'safe for concurrent use',
+    'safe to call from multiple threads', 'safe to use from multiple threads',
+    'safe to use concurrently', 'safe across threads',
+    'safe for multithreaded use', 'safe for multi threaded use',
+    'thread safe by design',
+)
+NOTSAFE = (
+    'not thread safe', 'not safe for concurrent use',
+    'not safe to call from multiple threads', 'not safe to use from multiple threads',
+    'not safe to use concurrently', 'not safe across threads',
+    'not safe for multithreaded use', 'not safe for multi threaded use',
+    'no thread safety', 'must not be called from multiple threads',
+    'must not be used from multiple threads',
+)
+
+
+def normalize(text):
+    return re.sub(r'\s+', ' ', text.lower().replace("n't", ' not').replace('-', ' ')).strip()
+
+
+def extract_claims(text, path='README.md'):
+    claims = []
+    fence = None
+    pending = []
+
+    def flush():
+        if not pending:
+            return
+        start = pending[0][0]
+        prose = ' '.join(value for _, value in pending)
+        for sentence in re.split(r'(?<=[.!?])\s+', prose):
+            normalized = normalize(sentence)
+            masked = normalized
+            found_not = False
+            for phrase in sorted(NOTSAFE, key=len, reverse=True):
+                pattern = r'\b' + re.escape(phrase) + r'\b'
+                if re.search(pattern, masked):
+                    found_not = True
+                    masked = re.sub(pattern, lambda m: ' ' * len(m.group()), masked)
+            families = ['notsafe'] if found_not else []
+            if not re.search(r'\b(no|not|never|without)\b', normalized):
+                if any(re.search(r'\b' + re.escape(p) + r'\b', masked) for p in THREADSAFE):
+                    families.append('threadsafe')
+            for family in families:
+                claims.append(dict(family=family, path=path, line=start, sentence=sentence.strip()))
+        pending.clear()
+
+    for number, line in enumerate(text.splitlines(), 1):
+        marker = re.match(r'^\s{0,3}(`{3,}|~{3,})', line)
+        if marker:
+            token = marker.group(1)
+            if fence is None:
+                flush()
+                fence = token
+            elif token[0] == fence[0] and len(token) >= len(fence):
+                fence = None
+            continue
+        if fence:
+            continue
+        if not line.strip():
+            flush()
+        else:
+            pending.append((number, line.strip()))
+    flush()
+    return claims
+
+
+def extract_evidence(text, path):
+    tree = ast.parse(text, filename=path)
+    modules = {}
+    imported = {}
+    constructors = {'Lock', 'RLock', 'Semaphore', 'BoundedSemaphore', 'Condition'}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name in ('threading', 'multiprocessing'):
+                    modules[alias.asname or alias.name] = alias.name
+        elif isinstance(node, ast.ImportFrom) and node.level == 0:
+            if node.module in ('threading', 'multiprocessing'):
+                for alias in node.names:
+                    imported[alias.asname or alias.name] = (node.module, alias.name)
+
+    def kind_for(module, name):
+        if module == 'threading' and name == 'local':
+            return 'thread-local'
+        allowed = constructors if module == 'threading' else {'Lock', 'RLock'}
+        return 'lock-constructor' if name in allowed else None
+
+    items = set()
+    for node in ast.walk(tree):
+        kind = None
+        if isinstance(node, ast.Call):
+            func = node.func
+            if isinstance(func, ast.Attribute):
+                if func.attr == 'acquire':
+                    kind = 'acquire'
+                elif isinstance(func.value, ast.Name) and func.value.id in modules:
+                    kind = kind_for(modules[func.value.id], func.attr)
+            elif isinstance(func, ast.Name) and func.id in imported:
+                kind = kind_for(*imported[func.id])
+        if kind:
+            items.add((node.lineno, kind))
+        if isinstance(node, ast.With):
+            for item in node.items:
+                context = item.context_expr
+                name = context.id if isinstance(context, ast.Name) else context.attr if isinstance(context, ast.Attribute) else ''
+                if 'lock' in name.lower():
+                    items.add((node.lineno, 'with-lock'))
+    return [dict(path=path, line=line, kind=kind) for line, kind in sorted(items)]
+
+
+def audit(root, ignore=()):
+    root = Path(root)
+    if not root.is_dir():
+        raise ValueError('audit path must be a directory')
+    claims, production, test_only = [], [], []
+    source_count = 0
+    for directory, directories, files in os.walk(root, followlinks=False):
+        directories[:] = sorted(d for d in directories if not (Path(directory) / d).is_symlink() and d not in {'.git', '__pycache__', '.venv', 'venv', 'build', 'dist'} and not d.endswith('.egg-info'))
+        for filename in sorted(files):
+            path = Path(directory) / filename
+            relative = path.relative_to(root).as_posix()
+            if path.is_symlink() or filename == '.env' or any(fnmatch.fnmatchcase(relative, p) for p in ignore):
+                continue
+            parts = Path(relative).parts
+            is_doc = relative == 'README.md' or (parts[0] == 'docs' and path.suffix == '.md')
+            is_source = path.suffix == '.py' and 'docs' not in parts[:-1] and 'examples' not in parts[:-1]
+            if not is_doc and not is_source:
+                continue
+            text = path.read_text(encoding='utf-8')
+            if is_doc:
+                claims.extend(extract_claims(text, relative))
+            if is_source:
+                testing = 'tests' in parts[:-1] or 'fixtures' in parts[:-1] or filename.startswith('test_') or filename.endswith('_test.py')
+                evidence = extract_evidence(text, relative)
+                if testing:
+                    test_only.extend(evidence)
+                else:
+                    source_count += 1
+                    production.extend(evidence)
+    findings, verified = [], []
+    for family in ('threadsafe', 'notsafe'):
+        family_claims = [c for c in claims if c['family'] == family]
+        if not family_claims:
+            continue
+        rule = 'documented-' + ('thread-safe' if family == 'threadsafe' else 'not-thread-safe') + '-claim-false'
+        evidence = production
+        severity = 'HIGH'
+        if source_count == 0:
+            evidence = [dict(kind='no-source')]
+        elif not production and test_only:
+            rule += '-test-only'
+            severity = 'MEDIUM'
+            evidence = test_only
+        elif (family == 'threadsafe' and production) or (family == 'notsafe' and not production):
+            verified.append(dict(family=family, claims=family_claims, evidence=production))
+            continue
+        findings.append(dict(rule=rule, severity=severity, family=family, claims=family_claims, evidence=evidence))
+    return dict(findings=findings, verified_claims=verified)
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        self.exit(1, self.prog + ': error: ' + message + '\n')
+
+
+def main(argv=None):
+    parser = Parser(prog='thread-safety-claim-audit', description='Offline audit of documented thread-safety claims against Python source.')
+    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='0.1.0')
+    args = parser.parse_args(argv)
+    try:
+        result = audit(args.path, args.ignore)
+    except (OSError, UnicodeError, SyntaxError, ValueError) as exc:
+        print('thread-safety-claim-audit: ' + str(exc), file=sys.stderr)
+        return 1
+    failed = any(f['severity'] == 'HIGH' or args.fail_on == 'MEDIUM' for f in result['findings'])
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print('FAIL' if failed else 'PASS')
+        for finding in result['findings']:
+            print(finding['severity'] + ' ' + finding['rule'])
+            for claim in finding['claims']:
+                print('  {path}:{line}: {sentence}'.format(**claim))
+            if args.verbose:
+                for evidence in finding['evidence']:
+                    print('  ' + json.dumps(evidence, sort_keys=True))
+        if args.verbose:
+            for claim in result['verified_claims']:
+                print('verified: ' + claim['family'])
+    return 2 if failed else 0

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

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: thread-safety-claim-audit
+Version: 0.1.0
+Summary: Offline audit of documented thread-safety claims against Python source.
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# thread-safety-claim-audit
+
+Offline audit of documented thread-safety claims against Python source.
+
+Version 0.1.0. A standard-library-only CLI for comparing documentation promises
+about concurrent safety with static synchronisation evidence. No audited code
+is executed, no network is used, and `.env` contents are never opened.
+
+## Usage
+
+Requires Python 3.9 or later. Install and run:
+
+```sh
+python3 -m pip install .
+thread-safety-claim-audit path/to/project
+python3 -m thread_safety_claim_audit path/to/project --json
+thread-safety-claim-audit . --verbose --ignore 'vendor/*' --fail-on HIGH
+python3 -m thread_safety_claim_audit --version
+```
+
+The path defaults to the current directory. `--ignore GLOB` is repeatable and
+matches relative paths. `--verbose` includes evidence and verified families.
+`--json` emits an object with `findings` and `verified_claims` arrays. Findings
+contain `rule`, `severity`, `family`, `claims`, and `evidence`; claim records
+contain a path, line, sentence, and family. Evidence records contain a path,
+line, and kind, except the `no-source` sentinel. Verified records contain a
+family, claims, and evidence. Exit 0 means PASS; exit 2 means findings at or
+above the selected threshold; exit 1 means a usage, reading, or parsing error.
+The default threshold is MEDIUM. HIGH leaves MEDIUM findings visible while
+allowing exit 0.
+
+## Claims
+
+Only root `README.md` and `docs/**/*.md` supply claims. Fenced code blocks are
+excluded; inline code counts as prose. Sentences are lowercased, `n't` becomes
+` not`, hyphens become spaces, and whitespace collapses. Exact phrases, with
+word boundaries, are matched; there is no optional-word expansion.
+
+The complete normalized phrase vocabulary is below:
+
+```text
+THREADSAFE:
+thread safe
+safe for concurrent use
+safe to call from multiple threads
+safe to use from multiple threads
+safe to use concurrently
+safe across threads
+safe for multithreaded use
+safe for multi threaded use
+thread safe by design
+
+NOTSAFE:
+not thread safe
+not safe for concurrent use
+not safe to call from multiple threads
+not safe to use from multiple threads
+not safe to use concurrently
+not safe across threads
+not safe for multithreaded use
+not safe for multi threaded use
+no thread safety
+must not be called from multiple threads
+must not be used from multiple threads
+```
+
+NOTSAFE spans are matched and masked first to prevent substring overlap.
+Negation words (`no`, `not`, `never`, `without`, including normalized
+contractions) suppress THREADSAFE for the whole sentence; listed NOTSAFE
+phrases still count. This asymmetry means the following examples behave as
+shown:
+
+```text
+is not thread-safe       => notsafe only
+isn't thread-safe        => notsafe only
+never thread safe       => no claim
+does not claim to be thread safe => no claim
+thread safety           => no claim (bare noun)
+threadsafe              => no claim (one word)
+```
+
+## Rules
+
+Each family is evaluated independently, including contradictory documentation.
+Each finding lists all family claim sentences and all applicable evidence.
+
+```text
+| Rule | Severity | Trigger |
+| --- | --- | --- |
+| `documented-thread-safe-claim-false` | HIGH | THREADSAFE with no production evidence |
+| `documented-thread-safe-claim-false-test-only` | MEDIUM | THREADSAFE with evidence only in tests/fixtures |
+| `documented-not-thread-safe-claim-false` | HIGH | NOTSAFE with production evidence |
+| `documented-not-thread-safe-claim-false-test-only` | MEDIUM | NOTSAFE with evidence only in tests/fixtures |
+
+```
+
+No production Python source produces one HIGH finding per claimed family with
+`no-source` evidence. THREADSAFE with production evidence is verified; NOTSAFE
+with no evidence anywhere is verified. No claim yields PASS regardless of
+source evidence. There are no other reverse rules.
+
+## Named evidence
+
+| Kind | Recognized syntax |
+| --- | --- |
+| `lock-constructor` | Calls to threading Lock, RLock, Semaphore, BoundedSemaphore, Condition; multiprocessing Lock or RLock |
+| `thread-local` | Call to threading.local |
+| `acquire` | Attribute call `.acquire(...)` on any receiver |
+| `with-lock` | With context Name or Attribute whose name contains `lock`, case-insensitively |
+
+Module and from-import aliases are tracked per file. Bare constructor calls
+need a matching import from threading or multiprocessing (multiprocessing
+bare imports count only for Lock and RLock, matching the attribute form).
+Evidence is deduplicated by file, line, and kind.
+Production excludes tests directories, test filename patterns, fixtures,
+docs, examples, and symlinked files. Test filename patterns and tests/fixtures
+are collected separately; docs and examples never supply evidence. Symlinked
+directories are not traversed. Build outputs, virtual environments, and Git
+metadata are skipped. Ignored files supply neither claims nor evidence.
+
+## Differentiation
+
+- concurrency-claim-audit checks existence of parallel execution, not synchronisation.
+- determinism-claim-audit checks run-to-run stability, not concurrent safety.
+- security-claim-audit checks eval, shell, and pickle hazards, not locks.
+- bandit and ruff inspect code issues without comparing documentation promises.
+- The two PyPI neighbours named below are multi-language concurrency issue
+  linters. This tool compares docs promises with source evidence.
+
+```text
+thread-safety / thread-safe-check
+```
+- Python threading documentation describes primitives rather than auditing
+  documentation against implementation.
+
+## Honest limitations
+
+This is a static heuristic, not a race detector or proof. Dead code counts:
+constructors in uncalled code still supply evidence. Receiver types, import
+shadowing, guard coverage, correct lock use, and actual shared-state mutation
+are not inferred. Even `.acquire` on a clearly unrelated object counts.
+A constructor does not prove that every shared access is guarded.
+
+Bare threading imports and Thread imports provide no evidence. Thread, Pool,
+Executor creation and concurrent.futures use concern execution, not protection.
+asyncio.Lock is excluded because it is a single-threaded coroutine primitive.
+queue.Queue is excluded because its internal protection says nothing about the
+surrounding object. A bare Lock name, import, annotation, or attribute access
+without a call does not count. threading.Barrier and threading.Event are
+coordination primitives rather than mutual exclusion and are excluded.
+Dynamic imports and custom guard wrappers may be missed. Exact-phrase claims
+miss paraphrases. Markdown and sentence parsing are deliberately lightweight;
+claim line numbers identify the start of the containing prose paragraph.
+Invalid source or unreadable input results in exit 1 rather than a silent PASS.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+The sdist includes the regression fixtures. Runtime dependencies: none.

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

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

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+[console_scripts]
+thread-safety-claim-audit = thread_safety_claim_audit.__main__:main

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

@@ -0,0 +1 @@
+thread_safety_claim_audit

thread_safety_claim_audit-0.1.0/tests/fixtures/bad/notsafe/README.md

@@ -0,0 +1 @@
+This library is not thread-safe.

thread_safety_claim_audit-0.1.0/tests/fixtures/bad/notsafe/main.py

@@ -0,0 +1,4 @@
+import threading
+lock = threading.Lock()
+with lock:
+    value = 1

thread_safety_claim_audit-0.1.0/tests/fixtures/bad/threadsafe/README.md

@@ -0,0 +1 @@
+This library is thread-safe.

thread_safety_claim_audit-0.1.0/tests/fixtures/bad/threadsafe/main.py

@@ -0,0 +1,3 @@
+value = []
+def add(x):
+    value.append(x)

thread_safety_claim_audit-0.1.0/tests/fixtures/good/notsafe/README.md

@@ -0,0 +1 @@
+This library is not thread-safe.

thread_safety_claim_audit-0.1.0/tests/fixtures/good/notsafe/main.py

@@ -0,0 +1,3 @@
+value = []
+def add(x):
+    value.append(x)

thread_safety_claim_audit-0.1.0/tests/fixtures/good/threadsafe/README.md

@@ -0,0 +1 @@
+This library is thread-safe.

thread_safety_claim_audit-0.1.0/tests/fixtures/good/threadsafe/main.py

@@ -0,0 +1,4 @@
+import threading
+lock = threading.Lock()
+with lock:
+    value = 1

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

@@ -0,0 +1 @@
+This library is thread-safe.

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

@@ -0,0 +1 @@
+value = []

thread_safety_claim_audit-0.1.0/tests/fixtures/testonly/tests/test_work.py

@@ -0,0 +1,2 @@
+import threading
+lock = threading.Lock()

thread_safety_claim_audit-0.1.0/tests/test_audit.py

@@ -0,0 +1,266 @@
+import contextlib
+import io
+import json
+from pathlib import Path
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from thread_safety_claim_audit.audit import (
+    THREADSAFE, NOTSAFE, audit, extract_claims, extract_evidence, main, normalize,
+)
+
+FIXTURES = Path(__file__).parent / 'fixtures'
+
+
+class Claims(unittest.TestCase):
+    def test_normalize(self):
+        self.assertEqual(normalize(" ISN'T thread-safe  "), 'is not thread safe')
+
+    def test_fences(self):
+        self.assertEqual(extract_claims('```text\nis thread-safe\n```'), [])
+
+    def test_tilde_fences(self):
+        self.assertEqual(extract_claims('~~~text\nis thread-safe\n~~~'), [])
+
+    def test_inline(self):
+        self.assertEqual(extract_claims('This is `thread-safe`.')[0]['family'], 'threadsafe')
+
+    def test_overlap(self):
+        self.assertEqual([c['family'] for c in extract_claims('is not thread-safe')], ['notsafe'])
+
+    def test_contraction(self):
+        self.assertEqual([c['family'] for c in extract_claims("isn't thread-safe")], ['notsafe'])
+
+    def test_multiple_sentences(self):
+        self.assertEqual(len(extract_claims('is thread safe. It is not thread safe.')), 2)
+
+    def test_boundaries(self):
+        self.assertEqual(extract_claims('unthread safeish'), [])
+
+    def test_self_audit(self):
+        self.assertEqual(audit(Path(__file__).parents[1])['findings'], [])
+        self.assertEqual(extract_claims((Path(__file__).parents[1] / 'README.md').read_text()), [])
+
+
+for index, phrase in enumerate(THREADSAFE):
+    def check(self, phrase=phrase):
+        self.assertEqual([c['family'] for c in extract_claims(phrase)], ['threadsafe'])
+        self.assertEqual([c['family'] for c in extract_claims(phrase.replace(' ', '-'))], ['threadsafe'])
+    setattr(Claims, 'test_positive_phrase_%02d' % index, check)
+for index, phrase in enumerate(NOTSAFE):
+    def check(self, phrase=phrase):
+        self.assertEqual([c['family'] for c in extract_claims(phrase)], ['notsafe'])
+    setattr(Claims, 'test_negative_phrase_%02d' % index, check)
+for index, phrase in enumerate(('thread safety', 'threadsafe', 'never thread safe', 'does not claim to be thread safe', 'without being thread safe', 'no promise of thread safe', 'safe to call concurrently')):
+    def check(self, phrase=phrase):
+        self.assertEqual(extract_claims(phrase), [])
+    setattr(Claims, 'test_nonclaim_%02d' % index, check)
+
+
+class Evidence(unittest.TestCase):
+    pass
+
+
+CASES = [
+ ('import threading\nx = threading.Lock()', ['lock-constructor']),
+ ('import threading as t\nx = t.RLock()', ['lock-constructor']),
+ ('from threading import Lock\nx = Lock()', ['lock-constructor']),
+ ('from threading import Lock as L\nx = L()', ['lock-constructor']),
+ ('x = Lock()', []),
+ ('threading.Lock()', []),
+ ('# threading.Lock()\ns = \"lock.acquire()\"', []),
+ ('import multiprocessing\nx = multiprocessing.Lock()', ['lock-constructor']),
+ ('from multiprocessing import RLock as R\nx = R()', ['lock-constructor']),
+ ('from multiprocessing import Semaphore as S\nx = S()', []),
+ ('thing.acquire()', ['acquire']),
+ ('with lock:\n pass', ['with-lock']),
+ ('with self.myLOCK:\n pass', ['with-lock']),
+ ('with open("a"):\n pass', []),
+ ('with resource:\n pass', []),
+ ('import threading\nx = threading.local()', ['thread-local']),
+ ('from threading import local as L\nx = L()', ['thread-local']),
+ ('import threading', []),
+ ('from threading import Thread\nt = Thread()', []),
+ ('import asyncio\nx = asyncio.Lock()', []),
+ ('import queue\nx = queue.Queue()', []),
+ ('from threading import Lock\nx: Lock', []),
+ ('import threading\nx = threading.Lock', []),
+ ('import threading\nx = threading.Barrier(2)\ny = threading.Event()', []),
+ ('import multiprocessing\nx = multiprocessing.Semaphore()', []),
+ ('def unused():\n import threading\n return threading.Lock()', ['lock-constructor']),
+ ('with lock, another_lock:\n pass', ['with-lock']),
+]
+for index, (source, kinds) in enumerate(CASES):
+    def check(self, source=source, kinds=kinds):
+        self.assertEqual([e['kind'] for e in extract_evidence(source, 'main.py')], kinds)
+    setattr(Evidence, 'test_evidence_%02d' % index, check)
+for name in ('Semaphore', 'BoundedSemaphore', 'Condition', 'RLock'):
+    def check(self, name=name):
+        self.assertEqual(len(extract_evidence('import threading\nx = threading.' + name + '()', 'main.py')), 1)
+    setattr(Evidence, 'test_constructor_' + name, check)
+
+
+class Integration(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+
+    def write(self, path, text):
+        p = self.root / path
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(text)
+
+    def run_cli(self, *args):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            code = main(list(args))
+        return code, output.getvalue()
+
+    def test_fixtures(self):
+        for name, code, rule in (
+            ('good/threadsafe', 0, None), ('good/notsafe', 0, None),
+            ('bad/threadsafe', 2, 'documented-thread-safe-claim-false'),
+            ('bad/notsafe', 2, 'documented-not-thread-safe-claim-false'),
+            ('testonly', 2, 'documented-thread-safe-claim-false-test-only'),
+        ):
+            with self.subTest(name=name):
+                actual, output = self.run_cli(str(FIXTURES / name), '--json')
+                self.assertEqual(actual, code)
+                result = json.loads(output)
+                self.assertEqual(set(result), {'findings', 'verified_claims'})
+                self.assertEqual(len(result['findings']), int(rule is not None))
+                if rule:
+                    self.assertEqual(result['findings'][0]['rule'], rule)
+                    self.assertEqual(result['findings'][0]['severity'], 'MEDIUM' if name == 'testonly' else 'HIGH')
+                else:
+                    self.assertEqual(len(result['verified_claims']), 1)
+
+    def test_threshold(self):
+        code, output = self.run_cli(str(FIXTURES / 'testonly'), '--fail-on', 'HIGH', '--json')
+        self.assertEqual(code, 0)
+        self.assertEqual(json.loads(output)['findings'][0]['severity'], 'MEDIUM')
+
+    def test_ignore(self):
+        self.assertEqual(len(audit(FIXTURES / 'bad/notsafe', ['main.py'])['findings']), 1)
+        self.write('README.md', 'is thread safe')
+        self.write('main.py', 'x = 1')
+        self.write('guard.py', 'x.acquire()')
+        self.assertEqual(audit(self.root)['findings'], [])
+        self.assertEqual(audit(self.root, ['guard.py'])['findings'][0]['rule'], 'documented-thread-safe-claim-false')
+
+    def test_no_source_both(self):
+        self.write('README.md', 'is thread safe. It is not thread safe.')
+        findings = audit(self.root)['findings']
+        self.assertEqual(len(findings), 2)
+        self.assertTrue(all(f['severity'] == 'HIGH' and f['evidence'] == [{'kind': 'no-source'}] for f in findings))
+
+    def test_both_independent_testonly(self):
+        self.write('README.md', 'is thread safe. It is not thread safe.')
+        self.write('main.py', 'x=1')
+        self.write('tests/test_guard.py', 'lock.acquire()')
+        findings = audit(self.root)['findings']
+        self.assertEqual(len(findings), 2)
+        self.assertTrue(all(f['severity'] == 'MEDIUM' for f in findings))
+
+    def test_notsafe_testonly(self):
+        self.write('README.md', 'is not thread safe')
+        self.write('main.py', 'x=1')
+        self.write('fixtures/a.py', 'lock.acquire()')
+        self.assertEqual(audit(self.root)['findings'][0]['rule'], 'documented-not-thread-safe-claim-false-test-only')
+
+    def test_no_claim(self):
+        self.write('main.py', 'lock.acquire()')
+        self.assertEqual(audit(self.root), {'findings': [], 'verified_claims': []})
+
+    def test_docs_only_sources(self):
+        self.write('README.md', 'No promises.')
+        self.write('docs/nested/guide.md', 'is thread-safe')
+        self.write('OTHER.md', 'is not thread-safe')
+        self.write('main.py', 'x=1')
+        result = audit(self.root)
+        self.assertEqual(len(result['findings']), 1)
+        self.assertEqual(result['findings'][0]['claims'][0]['path'], 'docs/nested/guide.md')
+
+    def test_exclusions(self):
+        self.write('README.md', 'is thread safe')
+        self.write('main.py', 'x=1')
+        for path in ('docs/guard.py', 'examples/guard.py'):
+            self.write(path, 'lock.acquire()')
+        self.assertEqual(audit(self.root)['findings'][0]['severity'], 'HIGH')
+
+    def test_test_patterns(self):
+        for path in ('test_guard.py', 'guard_test.py', 'nested/tests/guard.py', 'fixtures/guard.py'):
+            with self.subTest(path=path):
+                self.write(path, 'lock.acquire()')
+                self.write('main.py', 'x=1')
+                self.write('README.md', 'is thread safe')
+                self.assertEqual(audit(self.root)['findings'][0]['severity'], 'MEDIUM')
+                (self.root / path).unlink()
+
+    def test_symlinks(self):
+        self.write('README.md', 'is thread safe')
+        self.write('main.py', 'x=1')
+        with tempfile.TemporaryDirectory() as other:
+            outside = Path(other)
+            (outside / 'guard.py').write_text('lock.acquire()')
+            (self.root / 'guard.py').symlink_to(outside / 'guard.py')
+            (self.root / 'linked').symlink_to(outside, target_is_directory=True)
+            self.assertEqual(audit(self.root)['findings'][0]['severity'], 'HIGH')
+
+    def test_env_never_opened(self):
+        marker = 'ENV_MARKER_MUST_NOT_LEAK'
+        self.write('.env', marker)
+        self.write('README.md', 'is thread safe')
+        self.write('main.py', 'x=1')
+        original = Path.open
+        opened = []
+        def guarded(path, *args, **kwargs):
+            opened.append(path.name)
+            if path.name == '.env':
+                raise AssertionError('opened .env')
+            return original(path, *args, **kwargs)
+        with patch.object(Path, 'open', guarded):
+            code, output = self.run_cli(str(self.root), '--json')
+        self.assertEqual(code, 2)
+        self.assertNotIn('.env', opened)
+        self.assertNotIn(marker, output)
+
+    def test_all_evidence(self):
+        self.write('README.md', 'is not thread safe. It is not thread safe.')
+        self.write('main.py', 'import threading\nlock=threading.Lock()\nwith lock:\n lock.acquire()')
+        result = audit(self.root)['findings']
+        self.assertEqual(len(result), 1)
+        self.assertEqual(len(result[0]['evidence']), 3)
+        self.assertEqual(len(result[0]['claims']), 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_error(self):
+        with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as exc:
+            main(['--unknown'])
+        self.assertEqual(exc.exception.code, 1)
+
+    def test_invalid_tree(self):
+        with contextlib.redirect_stderr(io.StringIO()):
+            self.assertEqual(main([str(self.root / 'missing')]), 1)
+
+    def test_bad_source(self):
+        self.write('main.py', 'def !!!')
+        with contextlib.redirect_stderr(io.StringIO()):
+            self.assertEqual(main([str(self.root)]), 1)
+
+    def test_verbose(self):
+        code, output = self.run_cli(str(FIXTURES / 'good/threadsafe'), '--verbose')
+        self.assertEqual(code, 0)
+        self.assertIn('verified: threadsafe', output)
+
+
+if __name__ == '__main__':
+    unittest.main()