snap-judgment 0.11.0__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.
- snap_judgment-0.11.0/LICENSE +21 -0
- snap_judgment-0.11.0/PKG-INFO +470 -0
- snap_judgment-0.11.0/README.md +451 -0
- snap_judgment-0.11.0/pyproject.toml +32 -0
- snap_judgment-0.11.0/setup.cfg +4 -0
- snap_judgment-0.11.0/snap_judgment.egg-info/PKG-INFO +470 -0
- snap_judgment-0.11.0/snap_judgment.egg-info/SOURCES.txt +10 -0
- snap_judgment-0.11.0/snap_judgment.egg-info/dependency_links.txt +1 -0
- snap_judgment-0.11.0/snap_judgment.egg-info/entry_points.txt +3 -0
- snap_judgment-0.11.0/snap_judgment.egg-info/top_level.txt +1 -0
- snap_judgment-0.11.0/snap_judgment.py +5690 -0
- snap_judgment-0.11.0/tests/test_snap_judgment.py +4892 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ryan Cotten / Ghost Developer Studio
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,470 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: snap-judgment
|
|
3
|
+
Version: 0.11.0
|
|
4
|
+
Summary: Snap Judgment issues a courtroom-style verdict on your screenshot habits, computed from file metadata only. It never decodes image pixels and never uploads anything.
|
|
5
|
+
Author-email: Ryan Cotten <hello@ghostdeveloperstudio.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/littlestjames82-sys/snap-judgment
|
|
8
|
+
Project-URL: Repository, https://github.com/littlestjames82-sys/snap-judgment
|
|
9
|
+
Keywords: screenshots,cli,fun,report-card,metadata
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Topic :: Utilities
|
|
15
|
+
Requires-Python: >=3.9
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
License-File: LICENSE
|
|
18
|
+
Dynamic: license-file
|
|
19
|
+
|
|
20
|
+
# Snap Judgment
|
|
21
|
+
|
|
22
|
+
[](https://github.com/littlestjames82-sys/snap-judgment/actions/workflows/ci.yml)
|
|
23
|
+
[](https://www.python.org/)
|
|
24
|
+
[](LICENSE)
|
|
25
|
+
|
|
26
|
+
**Your screenshots, reviewed.** Snap Judgment reads a folder of screenshots and issues a courtroom-style verdict on your screenshot habits: a tier, the evidence, awards, and a sentence.
|
|
27
|
+
|
|
28
|
+

|
|
29
|
+
|
|
30
|
+
Meet [the defendants](gallery/README.md): five synthetic screenshot collections, from The Minimalist (35 screenshots, acquitted) to The Hoarder (2,800, Unrepentant Screenshot Felon), judged and entered into the record. New presiding voices live in [judges/](judges/README.md), and the version record is kept in the [changelog](CHANGELOG.md).
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
pip install snap-judgment
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Pure Python standard library. No dependencies, Python 3.9+.
|
|
39
|
+
|
|
40
|
+
## Usage
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
snapjudgment ~/Pictures/Screenshots
|
|
44
|
+
snapjudgment ~/Desktop ~/Pictures --card card.html --out report.md
|
|
45
|
+
snapjudgment ~/Pictures --svg card.svg # SVG share card (1200x630)
|
|
46
|
+
snapjudgment ~/Pictures --png card.png # PNG share card (1200x630), rendered with the stdlib alone
|
|
47
|
+
snapjudgment ~/Pictures --html page.html # full self-contained HTML report
|
|
48
|
+
snapjudgment ~/Downloads --all # judge every image in the folder
|
|
49
|
+
snapjudgment ~/Pictures --since 2024-01-01 # only screenshots on or after a date (a bare year works too)
|
|
50
|
+
snapjudgment ~/Pictures --until 2026-06-30 # only screenshots on or before a date
|
|
51
|
+
snapjudgment ~/Pictures --year 2026 # judge one single year only
|
|
52
|
+
snapjudgment ~/Pictures --vs ~/Phone # co-defendant mode: compare two folders
|
|
53
|
+
snapjudgment ~/Pictures --vs-year 2026 # compare one year against another year in the data
|
|
54
|
+
snapjudgment ~/Pictures --judge strict # strict | fair | lenient presiding judge
|
|
55
|
+
snapjudgment ~/Pictures --judge-file poet.json # a custom judge voice from a JSON pack
|
|
56
|
+
snapjudgment ~/Pictures --intensity roast # court commentary at full roast (0-100 or gentle|kind|honest|spicy|roast)
|
|
57
|
+
snapjudgment ~/Pictures --wrapped-kit ./kit # year-scoped SVG card + ready-to-post drafts
|
|
58
|
+
snapjudgment ~/Downloads --court downloads # the downloads docket: a second court, for the downloads folder
|
|
59
|
+
snapjudgment --grand-jury ~/Pictures/Screenshots ~/Downloads # both courts, one hearing, a combined FULL DOCKET verdict
|
|
60
|
+
snapjudgment ~/Downloads --court downloads --recursive # the docket judges subfolders too
|
|
61
|
+
snapjudgment ~/Pictures --cleanup-list cleanup.txt # the cleanup order: the exact files a plea bargain would remove
|
|
62
|
+
snapjudgment ~/Pictures --plea-bargain # the hypothetical verdict if you deleted the old and the duplicated
|
|
63
|
+
snapjudgment ~/Pictures --rematch # compare this hearing with the last one on record
|
|
64
|
+
snapjudgment ~/Pictures --badge badge.svg # a shields-style verdict badge for your README
|
|
65
|
+
snapjudgment ~/Pictures --fail-above "Repeat Offender" # exit 1 if the verdict ranks above this tier
|
|
66
|
+
snapjudgment ~/Pictures --oneline # print exactly one summary line
|
|
67
|
+
snapjudgment ~/Pictures --csv files.csv # per-file records as CSV
|
|
68
|
+
snapjudgment --history # print the court record of prior hearings
|
|
69
|
+
snapjudgment ~/Pictures --json # machine-readable verdict
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
With no folder argument, Snap Judgment checks the usual places
|
|
73
|
+
(`~/Pictures/Screenshots`, `~/OneDrive/Pictures/Screenshots`, `~/Desktop`,
|
|
74
|
+
`~/Pictures`, `~/Downloads`) and judges the first one that actually
|
|
75
|
+
contains screenshots.
|
|
76
|
+
|
|
77
|
+
The verdict tiers run from **Innocent Bystander** (under 50 screenshots) up
|
|
78
|
+
to **Unrepentant Screenshot Felon** (2,500+). Along the way the court weighs
|
|
79
|
+
the evidence: total count and size, the largest single screenshot, date
|
|
80
|
+
span, busiest day, month and hour, night share, weekend share, evidence
|
|
81
|
+
retention (how much of the collection is over a year old), screenshots per
|
|
82
|
+
day, median per active day, silent months (whole calendar months inside the
|
|
83
|
+
span with zero screenshots), longest daily streak, longest clean stretch,
|
|
84
|
+
biggest 60-second burst, the busiest hour window (the fullest rolling 60
|
|
85
|
+
minutes anywhere in the record), duplicate suspects and the storage they
|
|
86
|
+
waste, the per-format share (PNG, JPG, HEIC...), your busiest screenshot
|
|
87
|
+
season, your screenshot anniversary (the month-day you shoot most, summed
|
|
88
|
+
across years), and the device eras told by your screen resolutions. The
|
|
89
|
+
Markdown and HTML reports also draw a screenshot heatmap: the whole
|
|
90
|
+
collection as an hour-by-weekday grid. `--since` and `--until` narrow the
|
|
91
|
+
record to a date range (inclusive, and they compose with `--year`); the
|
|
92
|
+
active filter is entered into the evidence. Files the court cannot
|
|
93
|
+
read (broken symlinks, locked files) are counted and reported, never fatal.
|
|
94
|
+
|
|
95
|
+
With 5 or more screenshots the report also presents **exhibits**: the five
|
|
96
|
+
oldest screenshots, entered into evidence as Exhibit A through Exhibit E.
|
|
97
|
+
When several folders are judged in one run, an evidence block lists each
|
|
98
|
+
folder with its screenshot count.
|
|
99
|
+
|
|
100
|
+
With 10 or more screenshots the court also reads **the charges**: a census
|
|
101
|
+
of where the screenshots came from, from metadata hints only. Android
|
|
102
|
+
filenames that carry an app package are credited to that app (WhatsApp,
|
|
103
|
+
Telegram, Instagram, and friends); everything else is classified by the
|
|
104
|
+
form factor its dimensions suggest, from Phone (tall) to Desktop /
|
|
105
|
+
landscape.
|
|
106
|
+
|
|
107
|
+
Three judges can preside. The **fair** judge is the default. The **strict**
|
|
108
|
+
judge (The Hanging Judge) words the same verdict severely, and the
|
|
109
|
+
**lenient** judge (The Sympathetic Judge) frames everything kindly, with
|
|
110
|
+
encouragement instead of a sentence. The voice changes the wording only,
|
|
111
|
+
never the math.
|
|
112
|
+
|
|
113
|
+
Add `--intensity` and the court appends a line of commentary after the
|
|
114
|
+
sentence, aimed at your most damning stat: night share first, then sheer
|
|
115
|
+
count, duplicate extras, your longest streak, the oldest evidence. The
|
|
116
|
+
intensity runs 0-100 or by name: gentle, kind, honest, spicy, roast. At
|
|
117
|
+
gentle the court simply notes that the defendant keeps late hours; at
|
|
118
|
+
full roast it finds the sleep schedule guilty too. Commentary is opt-in,
|
|
119
|
+
appears in the terminal report, JSON, and the Markdown and HTML reports,
|
|
120
|
+
and composes with any judge. Like the judge's voice, it changes the
|
|
121
|
+
wording only, never the math. It can also live in the config file as
|
|
122
|
+
`intensity`.
|
|
123
|
+
|
|
124
|
+
### Custom judge packs
|
|
125
|
+
|
|
126
|
+
`--judge-file FILE.json` seats a judge of your own. A pack is a JSON object:
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
{
|
|
130
|
+
"name": "The Poet",
|
|
131
|
+
"intro": "The Poet presides over {count} screenshots.",
|
|
132
|
+
"sentences": {
|
|
133
|
+
"Innocent Bystander": "A short poem of a folder."
|
|
134
|
+
},
|
|
135
|
+
"award_lead": "The court pins these medals:"
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
`name` is required; `intro` (which may use `{tier}` and `{count}`),
|
|
140
|
+
`sentences`, and `award_lead` are optional. Any verdict tier missing from
|
|
141
|
+
`sentences` falls back to the fair judge's sentence for that tier. A
|
|
142
|
+
complete example, **The Poet**, ships at `examples/judge-poet.json`. With
|
|
143
|
+
`--json`, the report's `judge` field carries the pack's name. A malformed
|
|
144
|
+
pack exits with code 2 and a plain message.
|
|
145
|
+
|
|
146
|
+
A pack may also carry an `awards` object that renames awards by their
|
|
147
|
+
stable keys (`night_owl`, `burst_mode`, `screenshot_streak`, and the
|
|
148
|
+
rest; every award in the JSON report now carries its `key`). Each entry
|
|
149
|
+
may override the display `name`, the `evidence` line, or both; the
|
|
150
|
+
evidence is a template filled with the award's own stat values, so
|
|
151
|
+
`"{night_count} hoots at {night_share:.1f}%."` renders with the real
|
|
152
|
+
numbers. Entries keyed by an unknown award are warned about and
|
|
153
|
+
ignored. **The Critic** (`judges/judge-critic.json`) shows the feature
|
|
154
|
+
off: a dry film-critic judge whose Night Owl is entered into the record
|
|
155
|
+
as *Nocturne in a Minor Key*.
|
|
156
|
+
|
|
157
|
+
### Configuration file
|
|
158
|
+
|
|
159
|
+
Options you reach for every time can live in a `.snapjudgment.toml`.
|
|
160
|
+
Snap Judgment looks for one in the current directory first; when exactly
|
|
161
|
+
one folder is given and the current directory has none, a config file
|
|
162
|
+
inside that folder applies. Command-line flags always override the file.
|
|
163
|
+
|
|
164
|
+
```toml
|
|
165
|
+
# .snapjudgment.toml
|
|
166
|
+
folders = ["~/Pictures/Screenshots"]
|
|
167
|
+
judge = "strict"
|
|
168
|
+
plea_years = 3
|
|
169
|
+
fail_above = "Repeat Offender"
|
|
170
|
+
all = false
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
The supported keys are `folders` (a list of paths, used when no folder
|
|
174
|
+
argument is given), `judge` (`strict` | `fair` | `lenient`),
|
|
175
|
+
`judge_file` (a custom judge pack, as with `--judge-file`),
|
|
176
|
+
`plea_years` (an integer), `fail_above` (a verdict tier name),
|
|
177
|
+
`all` (a boolean), `intensity` (an integer 0-100 or a band name,
|
|
178
|
+
as with `--intensity`), and `court` (`screenshots` | `downloads`). Python 3.11+ parses the file with `tomllib`; on
|
|
179
|
+
3.9/3.10 a small built-in parser reads the same flat subset of TOML
|
|
180
|
+
(top-level `key = value` lines). A config file that cannot be parsed,
|
|
181
|
+
names an unknown judge or tier, or points at a judge pack that does not
|
|
182
|
+
load is warned about on stderr and ignored as a whole: a config file
|
|
183
|
+
must never break a run.
|
|
184
|
+
|
|
185
|
+
### Shell completions
|
|
186
|
+
|
|
187
|
+
Completion scripts for bash and zsh live in
|
|
188
|
+
[`completions/`](completions/): they complete every flag, with judge
|
|
189
|
+
voices for `--judge` and verdict tiers for `--fail-above`. For bash,
|
|
190
|
+
copy `completions/snapjudgment.bash` into your bash-completion
|
|
191
|
+
directory (e.g. `~/.local/share/bash-completion/completions/snapjudgment`)
|
|
192
|
+
or source it from `~/.bashrc`. For zsh, copy
|
|
193
|
+
`completions/snapjudgment.zsh` as `_snapjudgment` into a directory on
|
|
194
|
+
your `$fpath` and run `compinit`.
|
|
195
|
+
|
|
196
|
+
### Year over year
|
|
197
|
+
|
|
198
|
+
`--vs-year 2026` compares one year against the most recent year present in
|
|
199
|
+
the data (or, when the target is the most recent year, against the previous
|
|
200
|
+
year present): counts, verdict tiers, night shares, and sizes per year,
|
|
201
|
+
plus a closing line noting improvement, relapse, or no change in behavior.
|
|
202
|
+
|
|
203
|
+
### The plea bargain
|
|
204
|
+
|
|
205
|
+
`--plea-bargain` asks what a cleanup would buy you, without touching a
|
|
206
|
+
single file. The court computes the hypothetical outcome if you deleted
|
|
207
|
+
(a) every duplicate suspect except one keeper per exact size-and-dimension
|
|
208
|
+
group, and (b) every screenshot older than `--plea-years N` years
|
|
209
|
+
(default 2), measured from the newest screenshot in the folder: how many
|
|
210
|
+
files would go, how much space would come back, and what verdict the
|
|
211
|
+
remainder would earn. If the projected tier beats the real one, the court
|
|
212
|
+
would accept the plea; if not, it notes for the record that the plea
|
|
213
|
+
changes nothing. It is a projection, labeled as such - Snap Judgment
|
|
214
|
+
never deletes, moves, or modifies anything it judges.
|
|
215
|
+
|
|
216
|
+
`--cleanup-list FILE` turns the plea into paperwork: it writes the
|
|
217
|
+
exact files the plea bargain would remove (duplicate extras plus
|
|
218
|
+
screenshots older than `--plea-years`), one sorted path per line under
|
|
219
|
+
a `#` header giving the count and bytes, and enters a `cleanup_order`
|
|
220
|
+
object into the JSON report. It needs no `--plea-bargain` flag, and
|
|
221
|
+
when both are given they always agree, because they are the same
|
|
222
|
+
computation. The court issues the order; it does not swing the axe
|
|
223
|
+
itself. What you do with the list is your business.
|
|
224
|
+
|
|
225
|
+
### The downloads docket
|
|
226
|
+
|
|
227
|
+
`--court downloads` convenes a second court for the folder where good
|
|
228
|
+
intentions go to be forgotten. It judges the folder given on the
|
|
229
|
+
command line, or `~/Downloads` when none is given, and it judges
|
|
230
|
+
*every* file on the surface, any type, non-recursively, from names,
|
|
231
|
+
sizes, and dates only. No file is ever opened.
|
|
232
|
+
|
|
233
|
+
The evidence is the downloads folder's own: total files and size,
|
|
234
|
+
installers (`.exe`, `.msi`, `.dmg`, `.pkg`, `.deb`, `.rpm`,
|
|
235
|
+
`.appimage`) and archives, duplicate downloads (the `setup.exe`,
|
|
236
|
+
`setup (1).exe`, `setup (2).exe` chains, counted by extra copies), the
|
|
237
|
+
oldest and largest files, an extension census, and the share of files
|
|
238
|
+
over a year old. The verdict tiers are the docket's own:
|
|
239
|
+
|
|
240
|
+
| Files | Verdict |
|
|
241
|
+
|---|---|
|
|
242
|
+
| 0 | No Evidence |
|
|
243
|
+
| 1-24 | Tidy Desk |
|
|
244
|
+
| 25-99 | Mild Clutter |
|
|
245
|
+
| 100-249 | Digital Junk Drawer |
|
|
246
|
+
| 250-499 | Landfill Adjacent |
|
|
247
|
+
| 500-999 | Hoarding Situation |
|
|
248
|
+
| 1,000+ | Superfund Site |
|
|
249
|
+
|
|
250
|
+
Its awards are its own too: **Installer Archaeologist** (10 or more
|
|
251
|
+
installers), **Zip Hoarder** (15 or more archives), **Double
|
|
252
|
+
Downloader** (5 or more duplicate extra copies), **Ancient Relic**
|
|
253
|
+
(the oldest file is at least 3 years old), **Gigabyte Landfill** (5 GB
|
|
254
|
+
or more in total), **Still Seeding** (a `.torrent` file), **Receipt
|
|
255
|
+
Keeper DX** (an invoice or receipt in a filename), and **Time
|
|
256
|
+
Capsule** (60% or more of the files are over a year old). The
|
|
257
|
+
terminal report, `--json`, `--out`, `--oneline`, `--fail-above`
|
|
258
|
+
(against the docket's tiers), `--judge`, `--intensity` (with
|
|
259
|
+
commentary written for downloads sins), the share cards (`--card`,
|
|
260
|
+
`--svg`, `--png`, headed THE DOWNLOADS DOCKET), `--badge` (colored by
|
|
261
|
+
the docket's own ladder), the full HTML report (`--html`),
|
|
262
|
+
`--rematch` against the last downloads hearing, `--year`,
|
|
263
|
+
`--wrapped-kit`, `--csv` (one row per file, categorized as installer,
|
|
264
|
+
archive, or other), the `--since` / `--until` date filters, and the
|
|
265
|
+
court record all work in this court. The cleanup order works here
|
|
266
|
+
too, listing only the provable waste: the duplicate-download extra
|
|
267
|
+
copies, every group member except the keeper. Only the comparisons
|
|
268
|
+
(`--vs`, `--vs-year`), the plea bargain, and judge packs
|
|
269
|
+
(`--judge-file`) are refused with a plain error, because they belong
|
|
270
|
+
to the screenshots court's evidence. A sample hearing is at
|
|
271
|
+
`examples/downloads-demo-output.txt`. `--court` can also live in the
|
|
272
|
+
config file.
|
|
273
|
+
|
|
274
|
+
`--recursive` lets the docket judge subfolders too, not just the
|
|
275
|
+
surface. The evidence gains a per-folder breakdown (also the
|
|
276
|
+
`folders` list in JSON), and duplicate-download grouping stays
|
|
277
|
+
within each containing folder: a `setup.exe` in two different
|
|
278
|
+
folders is not a duplicate chain.
|
|
279
|
+
|
|
280
|
+
### The grand jury
|
|
281
|
+
|
|
282
|
+
`--grand-jury` convenes both courts in one hearing: the screenshots
|
|
283
|
+
court and the downloads docket, tried together, with a combined
|
|
284
|
+
verdict. Pass both folders (screenshots first, downloads second) or
|
|
285
|
+
pass neither, in which case the screenshots court looks in the usual
|
|
286
|
+
places and the docket sits on `~/Downloads`. One folder alone is a
|
|
287
|
+
plain error; the grand jury needs both defendants or none.
|
|
288
|
+
|
|
289
|
+
Each court issues its compact verdict block, and the hearing closes
|
|
290
|
+
with THE FULL DOCKET: the combined file count and size, both
|
|
291
|
+
verdicts side by side, and a standing line in the presiding judge's
|
|
292
|
+
voice, keyed to the pair of severities. Two tidy folders earn an
|
|
293
|
+
acquittal. Two crime scenes earn the harshest line the judge has.
|
|
294
|
+
Anything in between is a split verdict, and it names the worse
|
|
295
|
+
folder as the problem. A court whose folder is missing or empty
|
|
296
|
+
reports No Evidence, and the combined report still issues for the
|
|
297
|
+
other; the exit code is 2 only when neither court has evidence.
|
|
298
|
+
|
|
299
|
+
`--judge` and `--intensity` apply to both courts at once, and
|
|
300
|
+
`--fail-above` is resolved per court against that court's own
|
|
301
|
+
ladder, tripping if either verdict ranks above the tier. `--json`
|
|
302
|
+
nests each court's usual object under `screenshots` and `downloads`
|
|
303
|
+
keys, with a `combined` summary of files, bytes, and both tiers.
|
|
304
|
+
`--png`, `--svg`, and `--card` render a FULL DOCKET share card (both
|
|
305
|
+
verdicts, the combined size, and the first award from each court),
|
|
306
|
+
and `--out` mirrors the whole hearing in Markdown. Both hearings
|
|
307
|
+
enter the court record as normal entries, so each court's
|
|
308
|
+
`--rematch` keeps working afterward. Single-court procedure (the
|
|
309
|
+
comparisons, the plea bargain, the cleanup order, the wrapped kit,
|
|
310
|
+
date scopes, `--history`, judge packs, `--csv`, the badge, and the
|
|
311
|
+
HTML report) does not combine with a grand jury and is refused with
|
|
312
|
+
a plain error.
|
|
313
|
+
|
|
314
|
+
### Rematch
|
|
315
|
+
|
|
316
|
+
`--rematch` tries this hearing against the last one on record for the
|
|
317
|
+
same folders: the count delta since that hearing and whether the verdict
|
|
318
|
+
has improved, worsened, or held since. With no prior hearing for the
|
|
319
|
+
folders, the court says so. In JSON the comparison rides along as a
|
|
320
|
+
`rematch` object (or `null` when there is nothing to rematch against).
|
|
321
|
+
|
|
322
|
+
### A badge for your README
|
|
323
|
+
|
|
324
|
+
`--badge badge.svg` writes a shields-style verdict badge: a dark
|
|
325
|
+
"snap judgment" segment and the tier on a segment colored by severity,
|
|
326
|
+
green for Innocent Bystander through to dark red for Unrepentant
|
|
327
|
+
Screenshot Felon. Post your card, wear your verdict.
|
|
328
|
+
|
|
329
|
+
The share cards carry the word too: the HTML, SVG, and PNG cards print a
|
|
330
|
+
small `pip install snap-judgment` line under the footer, so anyone who
|
|
331
|
+
sees your verdict knows how to get one of their own.
|
|
332
|
+
|
|
333
|
+
### The wrapped kit
|
|
334
|
+
|
|
335
|
+
`--wrapped-kit DIR` scopes the hearing to the current year (or to `--year`
|
|
336
|
+
when given) and writes two files into DIR: `wrapped-YYYY.svg`, the year's
|
|
337
|
+
share card, and `post.txt` with two ready-to-post drafts built only from
|
|
338
|
+
the review's own numbers: a short post of at most 280 characters and a
|
|
339
|
+
standard post with the verdict, count, size, and top awards. If the year
|
|
340
|
+
has no screenshots, nothing is written and the exit code is 2.
|
|
341
|
+
|
|
342
|
+
### Failing a build on a verdict
|
|
343
|
+
|
|
344
|
+
`--fail-above TIER` exits 1 when the actual verdict ranks above TIER in the
|
|
345
|
+
tier order, and 0 otherwise. Tier names are case-insensitive and accept
|
|
346
|
+
spaces or hyphens (`"Repeat Offender"`, `repeat-offender`). An unknown tier
|
|
347
|
+
exits 2 and prints the valid tier list. The report (or JSON) is still
|
|
348
|
+
printed first, so the flag drops straight into CI.
|
|
349
|
+
|
|
350
|
+
### One line
|
|
351
|
+
|
|
352
|
+
`--oneline` prints exactly one line and nothing else:
|
|
353
|
+
|
|
354
|
+
```
|
|
355
|
+
Repeat Offender · 310 screenshots · 15.1 MB · Jan 2024 - Nov 2026
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Card, CSV, and report files are still written when their flags are given.
|
|
359
|
+
With `--json`, JSON wins and `--oneline` is ignored. An empty folder prints
|
|
360
|
+
`No Evidence · 0 screenshots` and exits 2.
|
|
361
|
+
|
|
362
|
+
## GitHub Action
|
|
363
|
+
|
|
364
|
+
Snap Judgment ships as a composite GitHub Action. It installs the package
|
|
365
|
+
from this repo, judges a folder, and appends the Markdown verdict to the
|
|
366
|
+
workflow step summary:
|
|
367
|
+
|
|
368
|
+
```yaml
|
|
369
|
+
- uses: littlestjames82-sys/snap-judgment@v0.5.0
|
|
370
|
+
with:
|
|
371
|
+
path: ./screenshots
|
|
372
|
+
judge: fair # optional: strict | fair | lenient
|
|
373
|
+
fail-above: "Repeat Offender" # optional: fail the step above this tier
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
Inputs: `path` (required), `judge` (default `fair`), `fail-above`
|
|
377
|
+
(optional). The step's exit code is Snap Judgment's own, so `fail-above`
|
|
378
|
+
can fail the step.
|
|
379
|
+
|
|
380
|
+
Every hearing is entered into the **court record** at
|
|
381
|
+
`~/.snap-judgment/history.jsonl`. The next time a folder is judged, the
|
|
382
|
+
verdict reports the last hearing's count and whether the collection is up
|
|
383
|
+
or down since, and `--rematch` puts the two hearings side by side.
|
|
384
|
+
`snapjudgment --history` prints the full record.
|
|
385
|
+
|
|
386
|
+
## The verdicts
|
|
387
|
+
|
|
388
|
+
| Screenshots | Verdict |
|
|
389
|
+
|---|---|
|
|
390
|
+
| 0 | No Evidence |
|
|
391
|
+
| 1-49 | Innocent Bystander |
|
|
392
|
+
| 50-199 | Petty Offender |
|
|
393
|
+
| 200-499 | Repeat Offender |
|
|
394
|
+
| 500-999 | Habitual Hoarder |
|
|
395
|
+
| 1,000-2,499 | Felony-Level Archivist |
|
|
396
|
+
| 2,500+ | Unrepentant Screenshot Felon |
|
|
397
|
+
|
|
398
|
+
## The awards
|
|
399
|
+
|
|
400
|
+
- **Night Owl** - a quarter or more of your screenshots happen between 10 PM and 5 AM
|
|
401
|
+
- **The 3 AM Club** - 10 or more screenshots taken between 2 AM and 4 AM
|
|
402
|
+
- **Burst Mode** - 8 or more screenshots inside a single 60-second window
|
|
403
|
+
- **The Archivist** - your oldest screenshot is at least 3 years old
|
|
404
|
+
- **Receipt Keeper** - half or more of your shots are weekday 9-to-5 evidence
|
|
405
|
+
- **Repeat Customer** - 10 or more files are exact size-and-dimension duplicates of a sibling
|
|
406
|
+
- **Creature of Habit** - a quarter or more of your screenshots fall in a single hour of the day
|
|
407
|
+
- **Gigabyte Club** - your screenshots total a gigabyte or more of evidence
|
|
408
|
+
- **Time Traveler** - at least one screenshot is dated in the future; the court admits it anyway
|
|
409
|
+
- **The Long Haul** - the collection spans 4 or more years
|
|
410
|
+
- **Lifer** - the collection spans 8 or more years
|
|
411
|
+
- **Ancient Relic** - the oldest screenshot sits 10 or more years before the newest
|
|
412
|
+
- **Anniversary** - one month-day accounts for 15 or more screenshots across the years
|
|
413
|
+
- **Screenshot Streak** - 7 or more consecutive days with at least one screenshot
|
|
414
|
+
- **Clean Stretch** - 30 or more consecutive days without a single screenshot; a recorded moment of restraint
|
|
415
|
+
- **Minimalist** - under 50 screenshots total; the court's rare acquittal
|
|
416
|
+
|
|
417
|
+
## Sample output
|
|
418
|
+
|
|
419
|
+
From a synthetic demo folder of 310 screenshots (see `examples/` for the
|
|
420
|
+
full report, the HTML, SVG, and PNG share cards, a wrapped-kit example, and
|
|
421
|
+
the example judge pack):
|
|
422
|
+
|
|
423
|
+
```
|
|
424
|
+
THE VERDICT
|
|
425
|
+
Repeat Offender
|
|
426
|
+
310 screenshots, 15.1 MB of evidence,
|
|
427
|
+
spanning Jan 5, 2024 to Nov 10, 2026.
|
|
428
|
+
|
|
429
|
+
THE EVIDENCE
|
|
430
|
+
Total screenshots 310
|
|
431
|
+
Total size 15.1 MB (15,799,537 bytes)
|
|
432
|
+
Taken at night (10 PM-5 AM) 91 (29.4%)
|
|
433
|
+
Busiest hour window 12 screenshots in the hour from Aug 14, 2026 21:14
|
|
434
|
+
Formats PNG 100%
|
|
435
|
+
Screenshot season Summer (Jun-Aug) - 31.0%
|
|
436
|
+
Screenshot anniversary Aug 14 - 14 screenshots across 2 years
|
|
437
|
+
|
|
438
|
+
THE CHARGES
|
|
439
|
+
Desktop / landscape 157 (50.6%)
|
|
440
|
+
Phone (tall) 153 (49.4%)
|
|
441
|
+
|
|
442
|
+
EXHIBITS
|
|
443
|
+
Exhibit A - Screenshot 2024-01-05 at 17.59.50.png (Jan 5, 2024)
|
|
444
|
+
Exhibit B - Screenshot 2024-01-12 at 11.46.18.png (Jan 12, 2024)
|
|
445
|
+
Exhibit C - Screenshot 2024-01-17 at 07.08.34.png (Jan 17, 2024)
|
|
446
|
+
Exhibit D - Screenshot 2024-01-21 at 22.29.11.png (Jan 21, 2024)
|
|
447
|
+
Exhibit E - Screenshot 2024-01-22 at 14.04.37.png (Jan 22, 2024)
|
|
448
|
+
|
|
449
|
+
AWARDS
|
|
450
|
+
* Night Owl - 91 screenshots between 10 PM and 5 AM (29.4% of the total).
|
|
451
|
+
* The 3 AM Club - 32 screenshots taken between 2 AM and 4 AM, when nothing on screen can be urgent.
|
|
452
|
+
* Burst Mode - 12 screenshots inside a single 60-second window.
|
|
453
|
+
* Repeat Customer - 12 files share an exact size and dimensions with a sibling. The same screenshot, taken again.
|
|
454
|
+
* Screenshot Streak - 10 consecutive days with at least one screenshot.
|
|
455
|
+
|
|
456
|
+
THE SENTENCE
|
|
457
|
+
Sentence: probation. The screenshots folder gets a check-in once a month.
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
## Privacy
|
|
461
|
+
|
|
462
|
+
Snap Judgment works from **file metadata only**. It reads file names, sizes,
|
|
463
|
+
modification times, and - solely to learn an image's width and height - the
|
|
464
|
+
header bytes of the image file. It never decodes image pixels, never runs
|
|
465
|
+
OCR, and never uploads anything anywhere. What your screenshots show is your
|
|
466
|
+
business; how many there are is the court's.
|
|
467
|
+
|
|
468
|
+
## License
|
|
469
|
+
|
|
470
|
+
MIT. Copyright Ryan Cotten / Ghost Developer Studio.
|