machinechecked 0.1.17__tar.gz → 0.1.18__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.
Files changed (100) hide show
  1. {machinechecked-0.1.17 → machinechecked-0.1.18}/PKG-INFO +1 -1
  2. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/machinechecked.egg-info/PKG-INFO +1 -1
  3. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/machinechecked.egg-info/SOURCES.txt +20 -2
  4. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/assess.py +191 -30
  5. machinechecked-0.1.18/engine/python/prooflens/authoring.py +312 -0
  6. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/cli.py +623 -35
  7. machinechecked-0.1.18/engine/python/prooflens/compare.py +898 -0
  8. machinechecked-0.1.18/engine/python/prooflens/composition.py +543 -0
  9. machinechecked-0.1.18/engine/python/prooflens/data/ProofLensProbe.lean +1932 -0
  10. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/data/schema/inventory.schema.json +15 -1
  11. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/data/schema/manifest-claim.schema.json +62 -0
  12. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/data/schema/manifest-index.schema.json +7 -1
  13. machinechecked-0.1.18/engine/python/prooflens/data/schema/published-work.schema.json +1420 -0
  14. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/data/statuses.json +39 -0
  15. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/deps.py +57 -59
  16. machinechecked-0.1.18/engine/python/prooflens/estimates.py +1011 -0
  17. machinechecked-0.1.18/engine/python/prooflens/excerpt.py +1041 -0
  18. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/export.py +68 -6
  19. machinechecked-0.1.18/engine/python/prooflens/facts.py +325 -0
  20. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/formalization.py +10 -5
  21. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/manifest.py +100 -8
  22. machinechecked-0.1.18/engine/python/prooflens/moddocs.py +45 -0
  23. machinechecked-0.1.18/engine/python/prooflens/numbering.py +374 -0
  24. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/paper.py +2 -1
  25. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/pipeline.py +39 -4
  26. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/probe.py +107 -13
  27. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/promote.py +117 -24
  28. machinechecked-0.1.18/engine/python/prooflens/proof_facts.py +369 -0
  29. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/published.py +33 -1
  30. machinechecked-0.1.18/engine/python/prooflens/published_work.py +345 -0
  31. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/repin.py +71 -0
  32. machinechecked-0.1.18/engine/python/prooflens/replay.py +274 -0
  33. machinechecked-0.1.18/engine/python/prooflens/requirements.py +865 -0
  34. machinechecked-0.1.18/engine/python/prooflens/retrieval.py +504 -0
  35. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/review_cli.py +114 -85
  36. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/review_queue.py +62 -9
  37. machinechecked-0.1.18/engine/python/prooflens/review_sources.py +307 -0
  38. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/reviews.py +40 -17
  39. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/server.py +53 -23
  40. machinechecked-0.1.18/engine/python/prooflens/simple.py +1858 -0
  41. machinechecked-0.1.18/engine/python/prooflens/steps.py +419 -0
  42. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/symbols.py +7 -2
  43. machinechecked-0.1.18/engine/python/prooflens/targets.py +245 -0
  44. machinechecked-0.1.18/engine/python/prooflens/uses.py +580 -0
  45. machinechecked-0.1.18/engine/python/prooflens/web/assets/index-Buyx92N7.js +279 -0
  46. machinechecked-0.1.18/engine/python/prooflens/web/assets/index-Cf1MUHrg.css +1 -0
  47. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/index.html +2 -2
  48. machinechecked-0.1.18/engine/python/prooflens/workspace.py +1102 -0
  49. {machinechecked-0.1.17 → machinechecked-0.1.18}/pyproject.toml +1 -1
  50. machinechecked-0.1.17/engine/python/prooflens/data/ProofLensProbe.lean +0 -667
  51. machinechecked-0.1.17/engine/python/prooflens/replay.py +0 -99
  52. machinechecked-0.1.17/engine/python/prooflens/simple.py +0 -979
  53. machinechecked-0.1.17/engine/python/prooflens/web/assets/index-B1CkNBtR.js +0 -278
  54. machinechecked-0.1.17/engine/python/prooflens/web/assets/index-DKOP2F1S.css +0 -1
  55. {machinechecked-0.1.17 → machinechecked-0.1.18}/LICENSE +0 -0
  56. {machinechecked-0.1.17 → machinechecked-0.1.18}/README.md +0 -0
  57. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/machinechecked.egg-info/dependency_links.txt +0 -0
  58. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/machinechecked.egg-info/entry_points.txt +0 -0
  59. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/machinechecked.egg-info/requires.txt +0 -0
  60. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/machinechecked.egg-info/top_level.txt +0 -0
  61. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/__init__.py +0 -0
  62. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/__main__.py +0 -0
  63. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/audit.py +0 -0
  64. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/bundle.py +0 -0
  65. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/cache.py +0 -0
  66. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/config.py +0 -0
  67. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/data/prooflens.sty +0 -0
  68. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/data/schema/evidence.schema.json +0 -0
  69. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/evidence.py +0 -0
  70. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/pdfclaims.py +0 -0
  71. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/schemas.py +0 -0
  72. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/source_regions.py +0 -0
  73. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/sources.py +0 -0
  74. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/status.py +0 -0
  75. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/tex.py +0 -0
  76. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/util.py +0 -0
  77. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/versions.py +0 -0
  78. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_AMS-Regular-BQhdFMY1.woff2 +0 -0
  79. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Caligraphic-Bold-Dq_IR9rO.woff2 +0 -0
  80. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Caligraphic-Regular-Di6jR-x-.woff2 +0 -0
  81. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Fraktur-Bold-CL6g_b3V.woff2 +0 -0
  82. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Fraktur-Regular-CTYiF6lA.woff2 +0 -0
  83. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Main-Bold-Cx986IdX.woff2 +0 -0
  84. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Main-BoldItalic-DxDJ3AOS.woff2 +0 -0
  85. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Main-Italic-NWA7e6Wa.woff2 +0 -0
  86. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Main-Regular-B22Nviop.woff2 +0 -0
  87. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Math-BoldItalic-CZnvNsCZ.woff2 +0 -0
  88. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Math-Italic-t53AETM-.woff2 +0 -0
  89. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_SansSerif-Bold-D1sUS0GD.woff2 +0 -0
  90. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_SansSerif-Italic-C3H0VqGB.woff2 +0 -0
  91. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_SansSerif-Regular-DDBCnlJ7.woff2 +0 -0
  92. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Script-Regular-D3wIWfF6.woff2 +0 -0
  93. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Size1-Regular-mCD8mA8B.woff2 +0 -0
  94. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Size2-Regular-Dy4dx90m.woff2 +0 -0
  95. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Size4-Regular-Dl5lxZxV.woff2 +0 -0
  96. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/KaTeX_Typewriter-Regular-CO6r4hn1.woff2 +0 -0
  97. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/cursor-editorTextHighlight-kG3uUOwL.svg +0 -0
  98. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/assets/pdf.worker.min-yatZIOMy.mjs +0 -0
  99. {machinechecked-0.1.17 → machinechecked-0.1.18}/engine/python/prooflens/web/theme.css +0 -0
  100. {machinechecked-0.1.17 → machinechecked-0.1.18}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: machinechecked
3
- Version: 0.1.17
3
+ Version: 0.1.18
4
4
  Summary: Read a mathematical paper beside its Lean formalisation, and see claim by claim what Lean establishes.
5
5
  License: Apache-2.0
6
6
  Project-URL: Homepage, https://machinechecked.org
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: machinechecked
3
- Version: 0.1.17
3
+ Version: 0.1.18
4
4
  Summary: Read a mathematical paper beside its Lean formalisation, and see claim by claim what Lean establishes.
5
5
  License: Apache-2.0
6
6
  Project-URL: Homepage, https://machinechecked.org
@@ -11,25 +11,38 @@ engine/python/prooflens/__init__.py
11
11
  engine/python/prooflens/__main__.py
12
12
  engine/python/prooflens/assess.py
13
13
  engine/python/prooflens/audit.py
14
+ engine/python/prooflens/authoring.py
14
15
  engine/python/prooflens/bundle.py
15
16
  engine/python/prooflens/cache.py
16
17
  engine/python/prooflens/cli.py
18
+ engine/python/prooflens/compare.py
19
+ engine/python/prooflens/composition.py
17
20
  engine/python/prooflens/config.py
18
21
  engine/python/prooflens/deps.py
22
+ engine/python/prooflens/estimates.py
19
23
  engine/python/prooflens/evidence.py
24
+ engine/python/prooflens/excerpt.py
20
25
  engine/python/prooflens/export.py
26
+ engine/python/prooflens/facts.py
21
27
  engine/python/prooflens/formalization.py
22
28
  engine/python/prooflens/manifest.py
29
+ engine/python/prooflens/moddocs.py
30
+ engine/python/prooflens/numbering.py
23
31
  engine/python/prooflens/paper.py
24
32
  engine/python/prooflens/pdfclaims.py
25
33
  engine/python/prooflens/pipeline.py
26
34
  engine/python/prooflens/probe.py
27
35
  engine/python/prooflens/promote.py
36
+ engine/python/prooflens/proof_facts.py
28
37
  engine/python/prooflens/published.py
38
+ engine/python/prooflens/published_work.py
29
39
  engine/python/prooflens/repin.py
30
40
  engine/python/prooflens/replay.py
41
+ engine/python/prooflens/requirements.py
42
+ engine/python/prooflens/retrieval.py
31
43
  engine/python/prooflens/review_cli.py
32
44
  engine/python/prooflens/review_queue.py
45
+ engine/python/prooflens/review_sources.py
33
46
  engine/python/prooflens/reviews.py
34
47
  engine/python/prooflens/schemas.py
35
48
  engine/python/prooflens/server.py
@@ -37,10 +50,14 @@ engine/python/prooflens/simple.py
37
50
  engine/python/prooflens/source_regions.py
38
51
  engine/python/prooflens/sources.py
39
52
  engine/python/prooflens/status.py
53
+ engine/python/prooflens/steps.py
40
54
  engine/python/prooflens/symbols.py
55
+ engine/python/prooflens/targets.py
41
56
  engine/python/prooflens/tex.py
57
+ engine/python/prooflens/uses.py
42
58
  engine/python/prooflens/util.py
43
59
  engine/python/prooflens/versions.py
60
+ engine/python/prooflens/workspace.py
44
61
  engine/python/prooflens/data/ProofLensProbe.lean
45
62
  engine/python/prooflens/data/prooflens.sty
46
63
  engine/python/prooflens/data/statuses.json
@@ -48,6 +65,7 @@ engine/python/prooflens/data/schema/evidence.schema.json
48
65
  engine/python/prooflens/data/schema/inventory.schema.json
49
66
  engine/python/prooflens/data/schema/manifest-claim.schema.json
50
67
  engine/python/prooflens/data/schema/manifest-index.schema.json
68
+ engine/python/prooflens/data/schema/published-work.schema.json
51
69
  engine/python/prooflens/web/index.html
52
70
  engine/python/prooflens/web/theme.css
53
71
  engine/python/prooflens/web/assets/KaTeX_AMS-Regular-BQhdFMY1.woff2
@@ -70,6 +88,6 @@ engine/python/prooflens/web/assets/KaTeX_Size2-Regular-Dy4dx90m.woff2
70
88
  engine/python/prooflens/web/assets/KaTeX_Size4-Regular-Dl5lxZxV.woff2
71
89
  engine/python/prooflens/web/assets/KaTeX_Typewriter-Regular-CO6r4hn1.woff2
72
90
  engine/python/prooflens/web/assets/cursor-editorTextHighlight-kG3uUOwL.svg
73
- engine/python/prooflens/web/assets/index-B1CkNBtR.js
74
- engine/python/prooflens/web/assets/index-DKOP2F1S.css
91
+ engine/python/prooflens/web/assets/index-Buyx92N7.js
92
+ engine/python/prooflens/web/assets/index-Cf1MUHrg.css
75
93
  engine/python/prooflens/web/assets/pdf.worker.min-yatZIOMy.mjs
@@ -10,8 +10,9 @@ Findings come in three tiers:
10
10
  inventory). A violation fails the consistency check; it does not change a status, which
11
11
  records what is proved: a proof that fails its check is not a proof, so its clause is open.
12
12
  * `warning`: a pattern that may change the meaning of a statement (a totalised operation, for
13
- instance). It asks for investigation, may be wrong, and can be dismissed with a recorded
14
- rationale tied to the subject's fingerprint.
13
+ instance), or a name a module docstring lists that nothing declares. It asks for
14
+ investigation, may be wrong, and can be dismissed with a recorded rationale tied to the
15
+ subject's fingerprint.
15
16
  * `obligation`: a judgement only a reviewer can make (a review of a proposition or definition, a
16
17
  witness that the hypotheses can be met, a regime the paper intends to cover).
17
18
 
@@ -24,6 +25,7 @@ from __future__ import annotations
24
25
 
25
26
  from .status import fields
26
27
 
28
+ from . import review_sources
27
29
  from .reviews import Review, history
28
30
  from .source_regions import SCHEME as SOURCE_SCHEME, changed_line, matches as source_matches
29
31
 
@@ -86,6 +88,15 @@ def _hashes(rec):
86
88
  return {h for h in (rec.get("legacy_hash"), rec.get("fingerprint")) if h}
87
89
 
88
90
 
91
+ def unread(rec: dict | None) -> bool:
92
+ """Whether a probe record holds no declaration: none was found under the name, or the probe
93
+ failed on the request. Such a record has only `name` and `errors`."""
94
+ if rec is None:
95
+ return True
96
+ errs = rec.get("errors") or []
97
+ return "missing" in errs or any(str(e).startswith("probe-error") for e in errs)
98
+
99
+
89
100
  class Assessor:
90
101
  def __init__(self, cfg, inventory, lean, tex, reviews: list[Review], dismissals,
91
102
  comparator_log: str | None = None, project_commit: str | None = None):
@@ -95,26 +106,124 @@ class Assessor:
95
106
  self.project_commit = project_commit
96
107
  self.findings: list[dict] = []
97
108
  self.authors = set(cfg.statement_authors)
109
+ self._history = None
110
+ self._unlisted: list[str] | None = None
111
+
112
+ # -- declarations the probe did not find ------------------------------------------------
113
+
114
+ def not_found(self, name: str) -> str:
115
+ """Why the probe has no record of `name`, for a finding: the declaration is not in any
116
+ module the probe loaded. When a project module that is not listed in `modules` declares
117
+ it (as far as its source text shows), that module is named."""
118
+ mods = []
119
+ try:
120
+ if self._unlisted is None:
121
+ from .probe import lib_names
122
+ from .simple import built_modules
123
+ root = self.cfg.lean_root
124
+ built, unbuilt = built_modules(root, lib_names(root))
125
+ listed = set(self.cfg.modules)
126
+ self._unlisted = [m for m in built + unbuilt if m not in listed]
127
+ from .simple import declaring_modules
128
+ mods = declaring_modules(self.cfg.lean_root, self._unlisted, name)
129
+ except (OSError, ValueError, AttributeError):
130
+ mods = []
131
+ if mods:
132
+ return (f"{name}: not found by the probe; it is declared in "
133
+ f"{', '.join(mods)}, which is not listed in `modules`")
134
+ return f"{name}: not found by the probe; is its module listed in `modules`?"
98
135
 
99
136
  # -- reviews --------------------------------------------------------------------------
100
137
 
101
- def review_state(self, target: str, name: str, rec: dict | None) -> dict:
102
- """The state of the last review of `name`: `reviewed` (current, by a reviewer other than
103
- the authors of the statements), `author-reviewed`, `stale` (the declaration changed since)
104
- or `pending` (none)."""
138
+ def review_state(self, target: str, name: str, rec: dict | None,
139
+ claim: str | None = None) -> dict:
140
+ """The state of the review of `name`: `reviewed` (current, by a reviewer other than the
141
+ authors of the statements), `author-reviewed`, `stale` (the declaration, or the paper
142
+ text the review read, changed since; `why` says which) or `pending` (none).
143
+
144
+ A review reads the passages of the claims that state or name the declaration
145
+ (`review_sources.py`). For `claim`, the review must have read that claim's current
146
+ passage; without one, the current passage of every claim it reads. The record is the
147
+ last marker at the declaration's current hash that did, provided the declaration's last
148
+ marker is at that hash. A marker without digests read a passage only while the history
149
+ shows it unchanged since the marker was written."""
105
150
  hist = history(self.reviews, target, name)
106
151
  last = hist[-1] if hist else None
152
+ readers = review_sources.digests(self.inv, target, name)
153
+ need = {claim: readers[claim]} if claim in readers else readers
154
+ why = source_claim = None
155
+ record = last
107
156
  if last is None:
108
157
  state = "pending"
109
158
  elif rec is None or last.hash not in _hashes(rec):
110
- state = "stale"
111
- elif last.by in self.authors:
112
- state = "author-reviewed"
159
+ state, why = "stale", "declaration"
113
160
  else:
114
- state = "reviewed"
115
- return {"state": state, "current": [last.to_json()] if state in (
116
- "reviewed", "author-reviewed") else [],
117
- "stale": [r.to_json() for r in hist if r is not last or state == "stale"]}
161
+ at = [r for r in hist if r.hash in _hashes(rec)]
162
+ record = next((r for r in reversed(at) if self._reads(r, need)), None)
163
+ if record is None:
164
+ why, source_claim = self._unread(last, need)
165
+ state = "stale"
166
+ else:
167
+ state = "author-reviewed" if record.by in self.authors else "reviewed"
168
+ out = {"state": state, "current": [record.to_json()] if state in (
169
+ "reviewed", "author-reviewed") else [],
170
+ "stale": [r.to_json() for r in hist if r is not record or state == "stale"],
171
+ "source_sha256": readers}
172
+ if why:
173
+ out["why"] = why
174
+ if source_claim:
175
+ out["source_claim"] = source_claim
176
+ return out
177
+
178
+ def _read_one(self, review: Review, cid: str, sha: str) -> str:
179
+ """Whether `review` read the current passage `sha` of claim `cid`
180
+ (`review_sources.marker_state`)."""
181
+ if review.source is None and self._history is None:
182
+ self._history = review_sources.History(getattr(self.cfg, "root", None),
183
+ getattr(self.cfg, "inventory", None), self.inv)
184
+ return review_sources.marker_state(review, cid, sha, self._history)
185
+
186
+ def _reads(self, review: Review, need: dict[str, str]) -> bool:
187
+ return all(self._read_one(review, c, s) == "current" for c, s in sorted(need.items()))
188
+
189
+ def _unread(self, review: Review, need: dict[str, str]) -> tuple[str, str]:
190
+ """Why the last marker does not cover the passages `need`, and the first claim
191
+ concerned."""
192
+ for cid, sha in sorted(need.items()):
193
+ st = self._read_one(review, cid, sha)
194
+ if st != "current":
195
+ return {"changed": "source-changed", "unread": "source-unread",
196
+ "unrecorded": "source-unrecorded"}[st], cid
197
+ return "source-changed", sorted(need)[0] # not reached: the last marker read them
198
+
199
+ def _claim_label(self, cid: str | None) -> str:
200
+ c = next((c for c in self.inv["claims"] if c["id"] == cid), None)
201
+ if c is None:
202
+ return "its claims"
203
+ return f"{c['number']} ({cid})" if c.get("number") else cid
204
+
205
+ def _stale_note(self, r: dict) -> str:
206
+ """Why a review is not current, for a finding's message."""
207
+ if r["state"] != "stale":
208
+ return ""
209
+ why = r.get("why")
210
+ if why == "source-changed":
211
+ return (f" (the source text of {self._claim_label(r.get('source_claim'))} changed "
212
+ "since its last reading)")
213
+ if why == "source-unread":
214
+ return (f" (its last review did not read the passage of "
215
+ f"{self._claim_label(r.get('source_claim'))})")
216
+ if why == "source-unrecorded":
217
+ return (" (its last review was made before source pins were recorded, and the "
218
+ f"source text of {self._claim_label(r.get('source_claim'))} cannot be shown "
219
+ "unchanged since)")
220
+ return " (its last review is stale)"
221
+
222
+ @staticmethod
223
+ def _stale_fields(r: dict) -> dict:
224
+ if r["state"] == "stale" and r.get("why", "declaration") != "declaration":
225
+ return {"reason": r["why"], "source_claim": r.get("source_claim")}
226
+ return {}
118
227
 
119
228
  def closure_reviews(self, names: list[str]) -> dict:
120
229
  """The review state of every project declaration in the closures of `names`, other than
@@ -122,8 +231,9 @@ class Assessor:
122
231
  lean = self.lean
123
232
  out = {}
124
233
  for n in names:
125
- clos = lean["specs"][n]["closure"] if n in lean["specs"] else \
126
- lean["defs"].get(n, {}).get("closure", [])
234
+ # A record of a declaration the probe did not find has no closure.
235
+ clos = (lean["specs"][n] if n in lean["specs"] else
236
+ lean["defs"].get(n, {})).get("closure") or []
127
237
  for d in clos:
128
238
  if d in lean["specs"] or d in out:
129
239
  continue
@@ -173,8 +283,15 @@ class Assessor:
173
283
  "detail": f"the Comparator record was made with other {label}"}
174
284
  if thm not in set(rec.get("replayed", [])):
175
285
  return {"state": "not-run", "detail": "the Comparator record does not cover this proof"}
176
- return {"state": "pass", "detail": "Comparator replayed the proof in a fresh kernel ("
177
- + ", ".join(rec.get("kernels", ["lean"])) + ")" + since}
286
+ # A replay without Comparator's sandbox guard still counts; the fact says so.
287
+ how = rec.get("conditions")
288
+ guard = ("unrecorded" if not isinstance(how, dict) else
289
+ "guarded" if how.get("guard") not in (None, "none") else "unguarded")
290
+ note = {"guarded": "", "unguarded": "; replayed without the sandbox guard",
291
+ "unrecorded": "; the record does not say whether the sandbox guard was used"}
292
+ return {"state": "pass", "guard": guard,
293
+ "detail": "Comparator replayed the proof in a fresh kernel ("
294
+ + ", ".join(rec.get("kernels", ["lean"])) + ")" + since + note[guard]}
178
295
 
179
296
  def _environment(self) -> dict:
180
297
  """The audited project's Lean version and Lake manifest hash."""
@@ -205,16 +322,18 @@ class Assessor:
205
322
  errs = (srec or {}).get("errors", ["missing"])
206
323
  res["checks"]["spec"] = {"ok": not errs, "errors": errs}
207
324
  for e in errs:
208
- self.findings.append(_finding("violation", "spec-" + e.split("=")[0], subj,
209
- f"proposition {spec}: {e}"))
210
- sr = self.review_state("spec", spec, srec)
325
+ self.findings.append(_finding(
326
+ "violation", "spec-" + e.split("=")[0], subj,
327
+ "proposition " + self.not_found(spec) if e == "missing" else
328
+ f"proposition {spec}: {e}"))
329
+ sr = self.review_state("spec", spec, srec, claim["id"])
211
330
  dr = self.closure_reviews([spec]) if srec else {}
212
331
  res["spec_review"] = sr
213
332
  if sr["state"] in ("pending", "stale"):
214
333
  self.findings.append(_finding(
215
334
  "obligation", "spec-review", subj,
216
- f"the proposition {spec} has no current review" +
217
- (" (its last review is stale)" if sr["state"] == "stale" else "")))
335
+ f"the proposition {spec} has no current review" + self._stale_note(sr),
336
+ **self._stale_fields(sr)))
218
337
  states = [sr["state"]] + [d["state"] for d in dr.values()]
219
338
  else:
220
339
  srec = None
@@ -222,8 +341,9 @@ class Assessor:
222
341
  missing = [d for d in names if d not in lean["decls"]]
223
342
  for d in missing:
224
343
  self.findings.append(_finding("violation", "def-missing", subj,
225
- f"definition {d} is not in the environment"))
226
- dr = {d: self.review_state("def", d, lean["decls"].get(d)) for d in names}
344
+ "definition " + self.not_found(d)))
345
+ dr = {d: self.review_state("def", d, lean["decls"].get(d), claim["id"])
346
+ for d in names}
227
347
  dr.update({d: r for d, r in self.closure_reviews(names).items() if d not in dr})
228
348
  res["spec_review"] = None
229
349
  states = [d["state"] for d in dr.values()]
@@ -232,8 +352,8 @@ class Assessor:
232
352
  if d["state"] in ("pending", "stale"):
233
353
  self.findings.append(_finding(
234
354
  "obligation", "def-review", subj,
235
- f"the definition {n} has no current review" +
236
- (" (its last review is stale)" if d["state"] == "stale" else ""), trigger=n))
355
+ f"the definition {n} has no current review" + self._stale_note(d),
356
+ trigger=n, **self._stale_fields(d)))
237
357
  if any(s in ("pending", "stale") for s in states):
238
358
  res["review"] = "pending"
239
359
  elif any(s == "author-reviewed" for s in states):
@@ -258,6 +378,7 @@ class Assessor:
258
378
  res["checks"]["replay"] = self.replay(thm)
259
379
  for e in perrs:
260
380
  self.findings.append(_finding("violation", f"{kind}-" + e.split("=")[0], subj,
381
+ self.not_found(thm) if e == "missing" else
261
382
  f"{thm}: {e}"))
262
383
  res["state"] = ("proved" if res.get("accept_ok") else
263
384
  "refuted" if res.get("refute_ok") else
@@ -284,9 +405,11 @@ class Assessor:
284
405
  ok = bool(p) and not p.get("errors")
285
406
  regs.append({**r, "discharged": ok, "type": (p or {}).get("type")})
286
407
  if not ok:
408
+ why = (f" (its witness {self.not_found(w)})"
409
+ if w and "missing" in (p or {}).get("errors", ["missing"]) else "")
287
410
  self.findings.append(_finding(
288
411
  "obligation", "regime", subj,
289
- f"regime not shown to be covered: {r.get('name', '')}",
412
+ f"regime not shown to be covered: {r.get('name', '')}{why}",
290
413
  trigger=r.get("name", "")))
291
414
  res["regimes"] = regs
292
415
  return res
@@ -386,9 +509,18 @@ class Assessor:
386
509
  elif srs == "pending":
387
510
  add("the proposition has no review", c)
388
511
  elif srs == "stale":
389
- add("the proposition changed after its last review", c)
512
+ add({"source-changed": "the paper's text changed after the proposition's "
513
+ "last review",
514
+ "source-unread": "the proposition's last review did not read this "
515
+ "claim's passage",
516
+ "source-unrecorded": "the proposition was reviewed before source pins "
517
+ "were recorded"}.get(
518
+ c["spec_review"].get("why"),
519
+ "the proposition changed after its last review"), c)
390
520
  for d, r in (c.get("def_reviews") or {}).items():
391
- defs[d] = r["state"]
521
+ why = r.get("why")
522
+ defs[d] = why if r["state"] == "stale" and why in (
523
+ "source-changed", "source-unread", "source-unrecorded") else r["state"]
392
524
  if c.get("witness") and not c.get("witness_ok"):
393
525
  add("the witness that the hypotheses can be met fails its check", c)
394
526
  if any(not r["discharged"] for r in c.get("regimes", [])):
@@ -410,6 +542,11 @@ class Assessor:
410
542
  counts[state] = counts.get(state, 0) + 1
411
543
  for state, words in (("pending", "have no review"),
412
544
  ("stale", "changed after their review"),
545
+ ("source-changed", "have a paper text that changed after their "
546
+ "review"),
547
+ ("source-unread", "have a review that did not read their passage"),
548
+ ("source-unrecorded", "were reviewed before source pins were "
549
+ "recorded"),
413
550
  ("author-reviewed", "were reviewed only by the author")):
414
551
  if counts.get(state):
415
552
  out.append(f"{counts[state]} definition{'s' if counts[state] > 1 else ''} its "
@@ -418,22 +555,46 @@ class Assessor:
418
555
  out.append("its definitions are not independently reviewed")
419
556
  return list(dict.fromkeys(out))
420
557
 
558
+ def step_review(self, claim: dict) -> dict:
559
+ """A proof step's own review, from its `step-review` markers: recorded beside its status,
560
+ never an input to it (`steps.py`)."""
561
+ from .steps import is_step, marker_review
562
+ region = ((self.tex or {}).get(claim["paper"], {}).get("regions") or {}).get(claim["id"])
563
+ if not is_step(claim, region):
564
+ return {}
565
+ marks = [r for r in self.reviews if r.target == "step" and r.name == claim["id"]]
566
+ return {"step_review": marker_review(marks, claim["id"], claim.get("source_sha256"),
567
+ self.authors)}
568
+
421
569
  def run(self) -> dict:
422
570
  claims = []
423
571
  for c in self.inv["claims"]:
424
572
  clauses = [self.clause(c, cl, k) for k, cl in enumerate(c.get("clauses", []))]
425
573
  state = fields(self.claim_code(c, clauses))
426
574
  claims.append({"id": c["id"], **state, "clauses": clauses,
427
- "blockers": self.blockers(c, clauses)})
575
+ "blockers": self.blockers(c, clauses), **self.step_review(c)})
428
576
  self.inventory_checks()
429
577
  if self.lean:
430
578
  for v in self.lean.get("layering", []):
431
579
  self.findings.append(_finding(
432
580
  "violation", "layering", v["module"],
433
581
  f"the specification module {v['module']} imports {v['imports']}"))
582
+ self.module_doc_checks()
434
583
  gates = self.gates(claims)
435
584
  return {"claims": claims, "findings": self.findings, "gates": gates}
436
585
 
586
+ def module_doc_checks(self):
587
+ """A warning for each name a module docstring lists that nothing declares: prose that
588
+ advertises a result the project does not contain. It never changes a status, and an
589
+ auditor can dismiss it (code `module-doc-name`, the module as subject, the name as
590
+ trigger)."""
591
+ from .moddocs import stale_doc_fingerprint, stale_doc_message, stale_doc_names
592
+ for d in stale_doc_names(self.lean.get("moddocs", [])):
593
+ self.add_warning("module-doc-name", d["module"], d["module"],
594
+ {"fingerprint": stale_doc_fingerprint(d)},
595
+ stale_doc_message(d), d["name"])
596
+ self.findings[-1].update(file=d["file"], line=d["line"])
597
+
437
598
  # -- gates ----------------------------------------------------------------------------
438
599
 
439
600
  def gates(self, claims: list[dict]) -> dict: