pywrit 0.2.11__tar.gz → 0.2.13__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pywrit
3
- Version: 0.2.11
3
+ Version: 0.2.13
4
4
  Summary: Python client + CLI for Writ — the gate before the write
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://github.com/withwrit/pywrit
@@ -54,6 +54,14 @@ first run it installs `pywrit[polyglot]` from PyPI using your Python 3.9+
54
54
  environment overrides (`WRIT_PYTHON`, `WRIT_SCAN_NO_INSTALL`), and the
55
55
  install test.
56
56
 
57
+ ## Language coverage
58
+
59
+ | Language | `writ scan` | `writ scan --apply` | Notes |
60
+ | --- | --- | --- | --- |
61
+ | Python | Yes | Yes, inserts `_writ_check` gates | Parsed with the stdlib `ast`, no extra needed |
62
+ | TypeScript / JavaScript | Yes, with `pywrit[polyglot]` | No, scan only | Needs the extra: `pip install 'pywrit[polyglot]'`. Without it, the report says so loudly: a warning block names the unscanned files instead of reporting zero findings |
63
+ | Go | No | No | On the roadmap |
64
+
57
65
  ## 60-second quickstart: scan → wrap → gate
58
66
 
59
67
  **1. Scan.** See which functions write, and how many of them are gated.
@@ -148,8 +156,8 @@ optional extra (tree-sitter based):
148
156
  pip install 'pywrit[polyglot]'
149
157
  writ scan .
150
158
 
151
- Without the extra, the scanner prints a one-line hint and keeps going —
152
- Python scanning never needs it.
159
+ Without the extra, the scanner prints a prominent warning block naming the
160
+ unscanned TS/JS files and keeps going — Python scanning never needs it.
153
161
 
154
162
  Findings from non-product paths (docs/, scripts/, sandbox/, examples/,
155
163
  benchmark/, demo/, and build-tooling files such as gulpfile.js or
@@ -32,6 +32,14 @@ first run it installs `pywrit[polyglot]` from PyPI using your Python 3.9+
32
32
  environment overrides (`WRIT_PYTHON`, `WRIT_SCAN_NO_INSTALL`), and the
33
33
  install test.
34
34
 
35
+ ## Language coverage
36
+
37
+ | Language | `writ scan` | `writ scan --apply` | Notes |
38
+ | --- | --- | --- | --- |
39
+ | Python | Yes | Yes, inserts `_writ_check` gates | Parsed with the stdlib `ast`, no extra needed |
40
+ | TypeScript / JavaScript | Yes, with `pywrit[polyglot]` | No, scan only | Needs the extra: `pip install 'pywrit[polyglot]'`. Without it, the report says so loudly: a warning block names the unscanned files instead of reporting zero findings |
41
+ | Go | No | No | On the roadmap |
42
+
35
43
  ## 60-second quickstart: scan → wrap → gate
36
44
 
37
45
  **1. Scan.** See which functions write, and how many of them are gated.
@@ -126,8 +134,8 @@ optional extra (tree-sitter based):
126
134
  pip install 'pywrit[polyglot]'
127
135
  writ scan .
128
136
 
129
- Without the extra, the scanner prints a one-line hint and keeps going —
130
- Python scanning never needs it.
137
+ Without the extra, the scanner prints a prominent warning block naming the
138
+ unscanned TS/JS files and keeps going — Python scanning never needs it.
131
139
 
132
140
  Findings from non-product paths (docs/, scripts/, sandbox/, examples/,
133
141
  benchmark/, demo/, and build-tooling files such as gulpfile.js or
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pywrit"
7
- version = "0.2.11"
7
+ version = "0.2.13"
8
8
  description = "Python client + CLI for Writ — the gate before the write"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -27,7 +27,7 @@ from .errors import (
27
27
  WritError,
28
28
  )
29
29
 
30
- __version__ = "0.2.11"
30
+ __version__ = "0.2.13"
31
31
 
32
32
  __all__ = [
33
33
  "WritClient",
@@ -660,8 +660,15 @@ def _writ_score(rows):
660
660
  return max(0, 100 - penalty)
661
661
 
662
662
 
663
- def print_score_report(root, sites, gated_funcs):
664
- """Print the risk report and Writ Score. Pure read-only: no files written."""
663
+ def print_score_report(root, sites, gated_funcs, unscanned_tsjs=0):
664
+ """Print the risk report and Writ Score. Pure read-only: no files written.
665
+
666
+ unscanned_tsjs counts TS/JS files that were collected but never
667
+ scanned (polyglot extra missing). When it is nonzero and no Python
668
+ write was found, the verdict says so: "No write operations
669
+ discovered" on its own would read as a clean result for a repo the
670
+ scanner only half saw.
671
+ """
665
672
  rows = _score_report_rows(root, sites, gated_funcs)
666
673
  total = len(rows)
667
674
  score = _writ_score(rows)
@@ -677,7 +684,10 @@ def print_score_report(root, sites, gated_funcs):
677
684
  print("Writ Score: %d/100" % score)
678
685
  print()
679
686
  if not total:
680
- print("No write operations discovered.")
687
+ if unscanned_tsjs:
688
+ print("No write operations discovered in the files that were scanned.")
689
+ else:
690
+ print("No write operations discovered.")
681
691
  print()
682
692
  else:
683
693
  print("%d write operations discovered" % total)
@@ -887,8 +897,25 @@ def _tsjs_non_product_class(path, root):
887
897
  def _tsjs_suppressed_total(suppressed):
888
898
  """Total suppressed sites across all non-product classes."""
889
899
  return sum(b["sites"] for b in (suppressed or {}).values())
890
- _TSJS_HINT = ("hint: %d TS/JS file(s) not scanned; install the extra: "
891
- "pip install 'pywrit[polyglot]'")
900
+ _TSJS_INSTALL_CMD = "pip install 'pywrit[polyglot]'"
901
+
902
+
903
+ def _tsjs_missing_extra_block(n_files):
904
+ """Prominent block for the no-polyglot-extra state: TS/JS files were
905
+ collected but none were scanned, so zero TS/JS findings is a coverage
906
+ gap, not a clean result. Printed in both the normal and --score paths,
907
+ always before the GitHub App line (which stays last)."""
908
+ bar = " " + "-" * 64
909
+ return [
910
+ bar,
911
+ " WARNING: %d TS/JS file(s) were seen but none were scanned."
912
+ % n_files,
913
+ " The polyglot extra is not installed, so this report covers",
914
+ " Python only. Zero TS/JS findings is a coverage gap, not a",
915
+ " clean result.",
916
+ " Install it with: " + _TSJS_INSTALL_CMD,
917
+ bar,
918
+ ]
892
919
  _TSJS_WRITE_METHODS = {"post", "put", "patch", "delete"}
893
920
  _TSJS_SQL_WRITE = _re.compile(
894
921
  r"^\s*\(*\s*(insert|update|delete|drop|alter|truncate|create|replace|"
@@ -1456,6 +1483,16 @@ def print_scan_json(root, files, skipped, sites, gated_funcs, tsjs, ts_sites):
1456
1483
  }
1457
1484
  ts_suppressed = tsjs.get("suppressed") or {}
1458
1485
  ts_sup_total = _tsjs_suppressed_total(ts_suppressed)
1486
+ if tsjs.get("missing_extra") and tsjs.get("files"):
1487
+ # The extra is missing: TS/JS files were collected but none were
1488
+ # scanned. Machine consumers get the same state the text report
1489
+ # shouts about, instead of a bare tsjs_hint flag.
1490
+ doc["tsjs_not_scanned"] = {
1491
+ "reason": "missing_extra",
1492
+ "extra": "pywrit[polyglot]",
1493
+ "files": len(tsjs["files"]),
1494
+ "install_command": _TSJS_INSTALL_CMD,
1495
+ }
1459
1496
  if ts_sup_total:
1460
1497
  # Non-product findings held back by default: never dropped
1461
1498
  # silently — the report names every suppressed path.
@@ -1633,7 +1670,12 @@ def scan_cmd(args):
1633
1670
  return 0
1634
1671
 
1635
1672
  if args.score:
1636
- print_score_report(root, sites, gated_funcs)
1673
+ unscanned = len(tsjs["files"]) if tsjs["missing_extra"] else 0
1674
+ print_score_report(root, sites, gated_funcs,
1675
+ unscanned_tsjs=unscanned)
1676
+ if tsjs["missing_extra"]:
1677
+ for line in _tsjs_missing_extra_block(len(tsjs["files"])):
1678
+ print(line)
1637
1679
  print(_GITHUB_APP_LINE)
1638
1680
  return 0
1639
1681
 
@@ -1642,7 +1684,8 @@ def scan_cmd(args):
1642
1684
  print(" write sites: %d in %d function(s)" % (total, len(by_func)))
1643
1685
  print(" gated: %d/%d (%d%%)" % (gated_site_count, total, pct))
1644
1686
  if tsjs["missing_extra"]:
1645
- print(" " + _TSJS_HINT % len(tsjs["files"]))
1687
+ for line in _tsjs_missing_extra_block(len(tsjs["files"])):
1688
+ print(line)
1646
1689
  elif tsjs["files"]:
1647
1690
  ts_total = len(ts_sites)
1648
1691
  print(" ts/js files scanned: %d skipped: %d (scan only, no --apply)"
@@ -1675,7 +1718,9 @@ def scan_cmd(args):
1675
1718
  for vname in sorted(verbs):
1676
1719
  print(" %s" % vname)
1677
1720
 
1678
- print_score_report(root, sites, gated_funcs)
1721
+ print_score_report(root, sites, gated_funcs,
1722
+ unscanned_tsjs=len(tsjs["files"])
1723
+ if tsjs["missing_extra"] else 0)
1679
1724
 
1680
1725
  if verbs:
1681
1726
  ppath = _pathlib.Path(args.policy_out)
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pywrit
3
- Version: 0.2.11
3
+ Version: 0.2.13
4
4
  Summary: Python client + CLI for Writ — the gate before the write
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://github.com/withwrit/pywrit
@@ -54,6 +54,14 @@ first run it installs `pywrit[polyglot]` from PyPI using your Python 3.9+
54
54
  environment overrides (`WRIT_PYTHON`, `WRIT_SCAN_NO_INSTALL`), and the
55
55
  install test.
56
56
 
57
+ ## Language coverage
58
+
59
+ | Language | `writ scan` | `writ scan --apply` | Notes |
60
+ | --- | --- | --- | --- |
61
+ | Python | Yes | Yes, inserts `_writ_check` gates | Parsed with the stdlib `ast`, no extra needed |
62
+ | TypeScript / JavaScript | Yes, with `pywrit[polyglot]` | No, scan only | Needs the extra: `pip install 'pywrit[polyglot]'`. Without it, the report says so loudly: a warning block names the unscanned files instead of reporting zero findings |
63
+ | Go | No | No | On the roadmap |
64
+
57
65
  ## 60-second quickstart: scan → wrap → gate
58
66
 
59
67
  **1. Scan.** See which functions write, and how many of them are gated.
@@ -148,8 +156,8 @@ optional extra (tree-sitter based):
148
156
  pip install 'pywrit[polyglot]'
149
157
  writ scan .
150
158
 
151
- Without the extra, the scanner prints a one-line hint and keeps going —
152
- Python scanning never needs it.
159
+ Without the extra, the scanner prints a prominent warning block naming the
160
+ unscanned TS/JS files and keeps going — Python scanning never needs it.
153
161
 
154
162
  Findings from non-product paths (docs/, scripts/, sandbox/, examples/,
155
163
  benchmark/, demo/, and build-tooling files such as gulpfile.js or
@@ -302,24 +302,94 @@ class ResourceWriteTest(unittest.TestCase):
302
302
 
303
303
 
304
304
  class MissingExtraTest(unittest.TestCase):
305
- def test_hint_once_and_python_still_scanned(self):
306
- with tempfile.TemporaryDirectory() as td:
307
- root = pathlib.Path(td)
308
- (root / "web").mkdir()
309
- (root / "web" / "a.ts").write_text(FileWalkTest.WRITE)
310
- (root / "web" / "b.js").write_text(FileWalkTest.WRITE)
305
+ BLOCK = [
306
+ " " + "-" * 64,
307
+ " WARNING: 2 TS/JS file(s) were seen but none were scanned.",
308
+ " The polyglot extra is not installed, so this report covers",
309
+ " Python only. Zero TS/JS findings is a coverage gap, not a",
310
+ " clean result.",
311
+ " Install it with: pip install 'pywrit[polyglot]'",
312
+ " " + "-" * 64,
313
+ ]
314
+
315
+ def _repo(self, root, with_python=True):
316
+ (root / "web").mkdir()
317
+ (root / "web" / "a.ts").write_text(FileWalkTest.WRITE)
318
+ (root / "web" / "b.js").write_text(FileWalkTest.WRITE)
319
+ if with_python:
311
320
  (root / "orders.py").write_text(
312
321
  'def create_order(db):\n db.execute("INSERT INTO o VALUES (1)")\n')
322
+
323
+ def _last_line(self, out):
324
+ lines = [ln for ln in out.splitlines() if ln.strip()]
325
+ return lines[-1] if lines else ""
326
+
327
+ def test_prominent_block_once_and_python_still_scanned(self):
328
+ with tempfile.TemporaryDirectory() as td:
329
+ root = pathlib.Path(td)
330
+ self._repo(root)
313
331
  with mock.patch.dict(sys.modules, _BLOCK_EXTRA):
314
332
  self.assertEqual(cli._tsjs_parsers(), {})
315
333
  code, out = _run_scan(root)
316
334
  self.assertEqual(code, 0)
317
- hints = [l for l in out.splitlines() if "hint:" in l]
318
- self.assertEqual(hints, [" hint: 2 TS/JS file(s) not scanned; install "
319
- "the extra: pip install 'pywrit[polyglot]'"])
335
+ for line in self.BLOCK:
336
+ self.assertIn(line, out)
337
+ self.assertEqual(
338
+ out.count("WARNING: 2 TS/JS file(s) were seen but none were "
339
+ "scanned."), 1)
340
+ self.assertNotIn("hint:", out)
320
341
  self.assertIn("write sites: 1 in 1 function(s)", out)
321
342
  self.assertIn("orders.create", out)
322
343
  self.assertNotIn("ts/js files scanned", out)
344
+ self.assertEqual(self._last_line(out), GitHubAppLineTest.LINE)
345
+
346
+ def test_normal_path_qualified_verdict_on_ts_only_repo(self):
347
+ with tempfile.TemporaryDirectory() as td:
348
+ root = pathlib.Path(td)
349
+ self._repo(root, with_python=False)
350
+ with mock.patch.dict(sys.modules, _BLOCK_EXTRA):
351
+ code, out = _run_scan(root)
352
+ self.assertEqual(code, 0)
353
+ for line in self.BLOCK:
354
+ self.assertIn(line, out)
355
+ # the bare verdict must not stand while TS/JS went unscanned
356
+ self.assertIn("No write operations discovered in the files that "
357
+ "were scanned.", out)
358
+ self.assertNotIn("\nNo write operations discovered.\n", out)
359
+ self.assertEqual(self._last_line(out), GitHubAppLineTest.LINE)
360
+
361
+ def test_score_path_block_and_qualified_verdict(self):
362
+ with tempfile.TemporaryDirectory() as td:
363
+ root = pathlib.Path(td)
364
+ self._repo(root, with_python=False)
365
+ with mock.patch.dict(sys.modules, _BLOCK_EXTRA):
366
+ code, out = _run_scan(root, score=True)
367
+ self.assertEqual(code, 0)
368
+ for line in self.BLOCK:
369
+ self.assertIn(line, out)
370
+ self.assertIn("No write operations discovered in the files that "
371
+ "were scanned.", out)
372
+ self.assertNotIn("\nNo write operations discovered.\n", out)
373
+ self.assertEqual(self._last_line(out), GitHubAppLineTest.LINE)
374
+
375
+ def test_json_report_records_unscanned_tsjs(self):
376
+ import json as j
377
+ with tempfile.TemporaryDirectory() as td:
378
+ root = pathlib.Path(td)
379
+ self._repo(root, with_python=False)
380
+ with mock.patch.dict(sys.modules, _BLOCK_EXTRA):
381
+ code, out = _run_scan(root, format="json")
382
+ self.assertEqual(code, 0, out)
383
+ doc = j.loads(out)
384
+ self.assertTrue(doc["tsjs_hint"])
385
+ self.assertEqual(doc["tsjs_not_scanned"], {
386
+ "reason": "missing_extra",
387
+ "extra": "pywrit[polyglot]",
388
+ "files": 2,
389
+ "install_command": "pip install 'pywrit[polyglot]'",
390
+ })
391
+ self.assertEqual(doc["findings"], [])
392
+ self.assertIn("github_app", doc)
323
393
 
324
394
  def test_python_only_repo_output_unchanged(self):
325
395
  with tempfile.TemporaryDirectory() as td:
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes