unslop-design 1.10.1 → 1.12.0

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.
package/README.md CHANGED
@@ -29,7 +29,7 @@
29
29
  you accept or reject them one by one.
30
30
  - **A before/after first.** Nothing in your code changes until you approve it.
31
31
  - **A number, not a vibe.** Scripts measure your UI and score it from 0 to 100:
32
- the example dashboard goes from **24 to 100**, and 89 slop hits to none.
32
+ the example dashboard goes from **21 to 100**, and 91 slop hits to none.
33
33
 
34
34
  <p align="center">
35
35
  <img alt="Claude Code skill" src="https://img.shields.io/badge/Claude%20Code-skill-111111">
@@ -185,8 +185,8 @@ On the example above, `web-audit.mjs` goes from 19 spacing values (15 off
185
185
  the scale), 5 weights, 6 radii, 6 shadows, a page that scrolls sideways
186
186
  on a phone and 11 links with no focus style, to 6 spacing values, all on the scale, 2
187
187
  weights, 1 shadow, no sideways scroll and a focus ring on everything.
188
- `slop-scan.py` finds 89 hits in the before and none in the after, and
189
- `unslop-score.py` goes from 24 to 100 on the code alone. Details
188
+ `slop-scan.py` finds 91 hits in the before and none in the after, and
189
+ `unslop-score.py` goes from 21 to 100 on the code alone. Details
190
190
  in [`web.md`](web.md).
191
191
 
192
192
  ## Native apps
@@ -212,6 +212,18 @@ python3 scripts/unslop-score.py examples/swiftui/after # 100/100
212
212
  The SwiftUI folders also hold the HTML mock of each state at iPhone size,
213
213
  the way quick mode shows a native before/after when there's no simulator.
214
214
 
215
+ ## Scores in the wild
216
+
217
+ Ran it on your own app or site? [Share the before/after and the
218
+ score](https://github.com/marcosnovo/unslop-design/issues/new?template=score-report.yml),
219
+ and it goes here with your permission: what the app is, the two numbers,
220
+ one image. What it missed is just as useful: that's how rules get added.
221
+
222
+ | App | Platform | Score | |
223
+ |---|---|---|---|
224
+ | [Refil](https://refil.app) (the author's) | iOS, Android | before/after above | [screens](#one-fix-at-a-time) |
225
+ | *Yours?* | | | [share it](https://github.com/marcosnovo/unslop-design/issues/new?template=score-report.yml) |
226
+
215
227
  ## Use it
216
228
 
217
229
  Type `/unslop-design` (or `$unslop-design` in Codex), or just ask in plain
@@ -260,7 +272,7 @@ python3 scripts/unslop-score.py src/ --audit unslop-audit/report.json # plus th
260
272
 
261
273
  ```text
262
274
  $ python3 scripts/unslop-score.py examples/dashboard-before.html
263
- unslop score: 24/100 — slop (1 source file)
275
+ unslop score: 21/100 — slop (1 source file)
264
276
 
265
277
  Where the points went (fix the top rows first):
266
278
  - 12 [#32] Colored glows (6)
@@ -268,12 +280,12 @@ Where the points went (fix the top rows first):
268
280
  - 8 [#53] Focus outline removed (1)
269
281
  …
270
282
 
271
- Badge: [![unslop score](https://img.shields.io/badge/unslop_score-24%2F100-red)](https://github.com/marcosnovo/unslop-design)
283
+ Badge: [![unslop score](https://img.shields.io/badge/unslop_score-21%2F100-red)](https://github.com/marcosnovo/unslop-design)
272
284
  ```
273
285
 
274
286
  Each kind of slop costs points per hit up to a cap, so the number says how
275
287
  many kinds are left, not how big the codebase is. Paste the badge in your
276
- README, and put "score 24 → 100" at the top of the PR. It's a smoke alarm,
288
+ README, and put "score 21 → 100" at the top of the PR. It's a smoke alarm,
277
289
  not a judge: a 95 can still have a flat hierarchy. `--min 80` makes it exit
278
290
  1 below 80 if you want it in a pre-commit hook, and `--save` keeps every run
279
291
  in `.unslop/history.json` so the score has a trend.
@@ -289,23 +301,35 @@ clean, never changes code itself, and turns off with `UNSLOP_HOOK=off` or
289
301
  `hook: off` in `.unslop/context.md`.
290
302
 
291
303
  **On every pull request (GitHub Actions).** Each hit becomes an annotation
292
- on its line, the score goes to the job summary, and the job fails under your
293
- minimum:
304
+ on its line, and one comment on the PR keeps the score and the change
305
+ against the base branch, updated on every push:
306
+
307
+ > ### unslop score: 88/100 (+7 vs main)
308
+ > **Worse** · [#68] Border and shadow on one card: 0 → 2 (-2)
309
+ > **Better** · [#32] Colored glows: 3 → 0 (+8) · [#33] Emoji in the UI: 4 → 0 (+8)
310
+
311
+ The job fails under your minimum, if you set one:
294
312
 
295
313
  ```yaml
296
314
  # .github/workflows/unslop.yml
297
315
  on: pull_request
316
+ permissions:
317
+ contents: read
318
+ pull-requests: write # for the comment
298
319
  jobs:
299
320
  unslop:
300
321
  runs-on: ubuntu-latest
301
322
  steps:
302
- - uses: actions/checkout@v4
303
- - uses: marcosnovo/unslop-design@v1.10.0
323
+ - uses: actions/checkout@v5
324
+ - uses: marcosnovo/unslop-design@v1.12.0
304
325
  with:
305
326
  paths: src
306
- min: 80 # optional; also: allow, scale, type-scale
327
+ min: 80 # optional; also: allow, scale, type-scale, comment: false
307
328
  ```
308
329
 
330
+ Locally, `unslop-score.py --json > main.json` on one branch and
331
+ `--baseline main.json` on another gives the same comparison.
332
+
309
333
  **Anywhere else.** `python3 scripts/slop-scan.py src --github` prints the
310
334
  same annotations, `--json` every hit for other tools, and `--list-rules`
311
335
  every rule id. All of them read `.unslop/context.md`, so your scale and your
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "unslop-design",
3
- "version": "1.10.1",
3
+ "version": "1.12.0",
4
4
  "description": "Make your app or site stop looking AI-generated: install the agent skill, scan UI code for slop and score it 0-100.",
5
5
  "license": "MIT",
6
6
  "author": "Marcos Novo (https://github.com/marcosnovo)",
@@ -110,6 +110,24 @@ RULES = [
110
110
  r"\bsave \d+\s?%(?!(?:\s|<[^<>]+>)*(?:vs\.?|versus|compared|than)\b))"), "all"),
111
111
  ("plural-hack", "#71", "\"item(s)\" in UI text (let the platform's plural rules pick the form)",
112
112
  re.compile(r"(?:[\"'`]|(?<!=)>)[^\"'<`\n]*(?<=[\s>\"'`])[A-Za-z][a-z]{2,}\(s\)(?=[\s.,:!?<\"'`]|$)"), "all"),
113
+ ("justified-text", "#28", "Justified text (uneven gaps on screens; align left)",
114
+ re.compile(r"text-align\s*:\s*justify\b|\btext-justify\b(?!\s*:)"), "web"),
115
+ ("extreme-tracking", "#29", "Letter-spacing tighter than -0.04em (letters collide; a bit tighter, not crushed)",
116
+ re.compile(r"letter-spacing\s*:\s*-0?\.(?:0[5-9]|[1-9])\d*em|\btracking-\[-0?\.(?:0[5-9]|[1-9])\d*em\]"), "web"),
117
+ ("fixed-width", "#57", "Fixed width of 400px or more (scrolls sideways on a phone: max-width and fluid)",
118
+ re.compile(r"(?<![-\w(])(?:min-)?width\s*:\s*(?:[4-9]\d{2}|\d{4,})px|(?<![\w-])(?:min-)?w-\[(?:[4-9]\d{2}|\d{4,})px\]"), "web"),
119
+ ("lorem", "#48", "Lorem ipsum (real content in every mock)",
120
+ re.compile(r"(?i:\blorem ipsum\b|\bdolor sit amet\b)"), "all"),
121
+ ("placeholder-image", "#35 #48", "Placeholder image service (real images, or none)",
122
+ re.compile(r"(?i:via\.placeholder\.com|placehold\.(?:co|it)\b|picsum\.photos|dummyimage\.com|placekitten\.com|"
123
+ r"loremflickr\.com|source\.unsplash\.com/random|placeimg\.com)"), "all"),
124
+ ("bare-delta", "#52", "A delta with no baseline (\"+12%\" vs what? \"+12% vs September\")",
125
+ re.compile(r"(?:>|[\"'`]|\(\s*\")\s*[+↑▲↓▼−]\s?\d+(?:[.,]\d+)?\s?%(?!(?:[^<\"'`\n]|<[^<>]+>){0,48}?"
126
+ r"(?i:\b(?:vs\.?|versus|than|from|since|compared|over|last|previous|prior|yesterday|week|month|quarter|year|"
127
+ r"yoy|mom|wow|qoq|baseline|target|goal|avg|average)\b))"), "all"),
128
+ ("straight-quotes", "#61", "Straight quote or apostrophe in UI copy (use ’ “ ”)",
129
+ re.compile(r">[^<>{}\n]*[A-Za-z]'[A-Za-z][^<>{}\n]*<|>[^<>{}\n=]*\s\"[A-Za-z][^\"<>{}\n]*\"[^<>{}\n]*<|"
130
+ r"\b(?:Text|Button|Label|navigationTitle)\(\s*(?:text\s*=\s*)?\"[^\"\n]*[A-Za-z]'[A-Za-z]"), "all"),
113
131
  ("no-focus", "#53", "Focus outline removed — is there a :focus-visible style?",
114
132
  re.compile(r"outline\s*:\s*(none|0)\b|\boutline-none\b|focus:outline-none"), "web"),
115
133
  ]
@@ -396,6 +414,12 @@ def file_checks(path, text, kind, hits):
396
414
  # Rule-level checks (#60, #66-#69): what a declaration means depends on its neighbors in the
397
415
  # same rule or class list, so they read whole CSS blocks and whole class attributes.
398
416
  CSS_EXT = {".css", ".scss", ".sass", ".less", ".html", ".htm", ".vue", ".svelte", ".astro"}
417
+ MARKUP_EXT = {".html", ".htm", ".jsx", ".tsx", ".vue", ".svelte", ".astro", ".mdx"}
418
+ PAGE_EXT = {".html", ".htm", ".vue", ".svelte", ".astro"}
419
+ ANY_CLASS = re.compile(r"""\bclass(?:Name)?\s*=\s*["'{`]+([^"'`}]+)""")
420
+ SECTION_NUMBER = re.compile(r">\s*0([1-9])\s*[.·/—–-]?\s*<")
421
+ COUNT_PILL = re.compile(r"""<(?:span|small|b|div|em|i)\b[^<>]*\bclass(?:Name)?\s*=\s*["'{`]+[^"'`}]*(?:\brounded-full\b[^"'`}]*\bbg-[a-z]+-(?:[4-9]00)\b|\bbg-[a-z]+-(?:[4-9]00)\b[^"'`}]*\brounded-full\b|\b(?:badge|pill)\b)[^"'`}]*["'`}]+[^<>]*>\s*\d{1,4}\+?\s*</""")
422
+ ICON_CIRCLE = re.compile(r"(?=.*\brounded-(?:full|xl|2xl)\b)(?=.*\bbg-[a-z]+-(?:50|100|200)\b)(?=.*\b(?:size|w|h)-(?:8|9|10|11|12|14)\b)")
399
423
  CSS_BLOCK = re.compile(r"([^{}]+)\{([^{}]*)\}")
400
424
  SIDE_BORDER = re.compile(r"border-(?:left|right|inline-start|inline-end)(?:-width)?\s*:\s*(\d+(?:\.\d+)?)px\s*(?:solid|[^;]*)", re.I)
401
425
  RADIUS = re.compile(r"border-radius\s*:(?!\s*0(?:px)?\s*(?:[;}]|$))", re.I)
@@ -470,6 +494,23 @@ def block_checks(path, text, ignored, line_of, hits):
470
494
  for m in TW_MONO_HEADING.finditer(text):
471
495
  add(mono, m.start(), f"<{m.group(1)} class=… font-mono>")
472
496
 
497
+ if ext in MARKUP_EXT:
498
+ # #13: one h1 per page; section titles are labels.
499
+ h1s = [m.start() for m in re.finditer(r"<h1\b", text)]
500
+ if len(h1s) >= 2 and ext in PAGE_EXT: # a .tsx file often holds several components
501
+ add(("multiple-h1", "#13", "More than one h1 on the page (section titles are labels, not h1)"), h1s[1], f"{len(h1s)} × <h1>")
502
+ # #60: 01 / 02 / 03 on sections.
503
+ nums = [(m.start(), int(m.group(1))) for m in SECTION_NUMBER.finditer(text)]
504
+ if {1, 2, 3} <= {n for _, n in nums}:
505
+ add(("section-numbers", "#60", "Sections numbered 01 / 02 / 03 (does the order carry information?)"), nums[0][0], "01, 02, 03…")
506
+ # #50: counts in filled pills.
507
+ for m in COUNT_PILL.finditer(text):
508
+ add(("count-pill", "#50", "A count in a filled pill (counts are muted tabular text: \"Inbox 12\")"), m.start(), m.group(0)[-40:])
509
+ # #33: icons in colored circles, row after row.
510
+ circles = [m.start() for m in ANY_CLASS.finditer(text) if ICON_CIRCLE.search(m.group(1))]
511
+ if len(circles) >= 3:
512
+ add(("icon-circle", "#33", "Icons in colored circles on every row (one icon style; shapes only in empty states)"), circles[0], f"{len(circles)} tinted circles")
513
+
473
514
 
474
515
  # Custom properties across the scanned files: a var(--name) nobody defines falls back in
475
516
  # silence (after a rename, a merge, a typo). Only when some token is defined in scope.
@@ -492,6 +533,7 @@ def token_checks(paths, hits):
492
533
  for n, line in enumerate(text.splitlines(), 1):
493
534
  if "unslop-ignore" not in line:
494
535
  uses += [(path, n, m.group(1)) for m in TOKEN_USE.finditer(line)]
536
+ project_checks(paths, hits)
495
537
  if not defined:
496
538
  return # the token file isn't in what was scanned: nothing to compare against
497
539
  key = ("undefined-token", "#1", "Token used but defined nowhere in the scanned files")
@@ -500,6 +542,43 @@ def token_checks(paths, hits):
500
542
  hits.setdefault(key, []).append((path, n, f"var({name})"))
501
543
 
502
544
 
545
+ # Across the scanned web files (#62, #63): a dark theme with no color-scheme anywhere, and
546
+ # keyframe animations with no reduced-motion alternative anywhere.
547
+ DARK_THEME = re.compile(r"prefers-color-scheme\s*:\s*dark|\[data-theme=[\"']?dark|\bdark:[a-z]")
548
+ COLOR_SCHEME = re.compile(r"(?<![-\w])color-scheme\s*:|name=[\"']color-scheme[\"']|\bcolorScheme\s*:")
549
+ ANIMATION = re.compile(r"@keyframes\s+[\w-]+|\banimate-(?:spin|ping|pulse|bounce|\[)")
550
+ REDUCED_MOTION = re.compile(r"prefers-reduced-motion|\bmotion-(?:reduce|safe):|useReducedMotion|reducedMotion")
551
+
552
+
553
+ def project_checks(paths, hits):
554
+ dark = anim = None
555
+ has_scheme = has_reduced = False
556
+ for path in paths:
557
+ if os.path.splitext(path)[1].lower() not in WEB or path.endswith((".min.js", ".min.css")):
558
+ continue
559
+ try:
560
+ text = open(path, encoding="utf-8", errors="replace").read()
561
+ except OSError:
562
+ continue
563
+ if len(text) > 2_000_000:
564
+ continue
565
+ lines = text.splitlines()
566
+
567
+ def first(rx):
568
+ for n, line in enumerate(lines, 1):
569
+ if "unslop-ignore" not in line and rx.search(line):
570
+ return (path, n, rx.search(line).group(0))
571
+ return None
572
+ dark = dark or first(DARK_THEME)
573
+ anim = anim or first(ANIMATION)
574
+ has_scheme = has_scheme or bool(COLOR_SCHEME.search(text))
575
+ has_reduced = has_reduced or bool(REDUCED_MOTION.search(text))
576
+ if dark and not has_scheme:
577
+ hits.setdefault(("no-color-scheme", "#62", "A dark theme with no color-scheme (form controls and scrollbars stay light)"), []).append(dark)
578
+ if anim and not has_reduced:
579
+ hits.setdefault(("no-reduced-motion", "#63", "Animations with no prefers-reduced-motion alternative"), []).append(anim)
580
+
581
+
503
582
  # A written project decision can allow a taste rule (a base-6 grid, tracked caps as the
504
583
  # brand's signature). It can't allow the floors: contrast and visible focus and target size
505
584
  # (accessibility, principle 5) and invented claims (principle 6). Shared with unslop-score.py.
@@ -551,6 +630,25 @@ def files(paths):
551
630
  yield os.path.join(root, n)
552
631
 
553
632
 
633
+ # Code samples and at-rule conditions aren't UI copy or layout (straight-quotes, fixed-width).
634
+ CODE_SPAN = re.compile(r"<(code|pre|kbd|samp)\b[^>]*>.*?</\1>", re.S)
635
+
636
+
637
+ def mask_code(line, in_pre):
638
+ """The line without code: what a multi-line <pre> still holds, inline <code>/<pre>/<kbd>/<samp>
639
+ spans, and an unclosed <pre> to the end of the line. Returns (masked line, inside <pre> after it)."""
640
+ if in_pre:
641
+ end = line.find("</pre>")
642
+ if end == -1:
643
+ return "", True
644
+ line = line[end + len("</pre>"):]
645
+ line = CODE_SPAN.sub("", line)
646
+ start = line.find("<pre")
647
+ if start != -1:
648
+ return line[:start], True
649
+ return line, False
650
+
651
+ AT_RULE_PRELUDE = re.compile(r"@(?:media|container|supports)\b[^{]*")
554
652
  DEFAULT_SCALE = "0,1,2,4,8,12,16,20,24,32,40,48,64,80,96"
555
653
  DEFAULT_TYPE_SCALE = {11, 12, 13, 14, 15, 16, 17, 18, 20, 22, 24, 26, 28, 30, 32, 34, 36, 40, 44, 48, 56, 64, 72, 80, 96}
556
654
  # Colored shadows in CSS, any offset: "0 10px 30px rgba(255,107,107,.45)" is a glow too (#32).
@@ -587,7 +685,9 @@ def scan(path, scale, hits, type_scale=None):
587
685
  has_focus_visible = "focus-visible" in text
588
686
  file_checks(path, text, kind, hits)
589
687
  in_root = False
688
+ in_pre = False
590
689
  for n, line in enumerate(text.splitlines(), 1):
690
+ copy_line, in_pre = mask_code(line, in_pre)
591
691
  if "unslop-ignore" in line:
592
692
  continue
593
693
  stripped = line.strip()
@@ -609,7 +709,12 @@ def scan(path, scale, hits, type_scale=None):
609
709
  continue
610
710
  if rid in ("native-literal", "elevation-literal") and is_token_file:
611
711
  continue # Tokens.kt / Type.kt / Theme.swift: literals belong there
612
- if rx.search(line):
712
+ target = line
713
+ if rid == "straight-quotes":
714
+ target = copy_line # code samples keep their straight quotes
715
+ elif rid == "fixed-width":
716
+ target = AT_RULE_PRELUDE.sub("", line) # @media (min-width: 768px) is a breakpoint, not a width
717
+ if rx.search(target):
613
718
  hits.setdefault((rid, ref, desc), []).append((path, n, stripped[:110]))
614
719
  if kind == "web":
615
720
  glow_key = next((r[0], r[1], r[2]) for r in RULES if r[0] == "glow")
@@ -650,12 +755,19 @@ FILE_RULES = [
650
755
  ("bounce-easing", "#67", "Bouncy or elastic easing (ease out, don't overshoot)"),
651
756
  ("ghost-card", "#68", "1px border and a soft shadow on the same card (pick one separator)"),
652
757
  ("mono-disguise", "#69", "Monospace on headings or the whole page (code faces are for code and data)"),
758
+ ("multiple-h1", "#13", "More than one h1 on the page (section titles are labels, not h1)"),
759
+ ("section-numbers", "#60", "Sections numbered 01 / 02 / 03 (does the order carry information?)"),
760
+ ("count-pill", "#50", "A count in a filled pill (counts are muted tabular text: \"Inbox 12\")"),
761
+ ("icon-circle", "#33", "Icons in colored circles on every row (one icon style; shapes only in empty states)"),
762
+ ("no-color-scheme", "#62", "A dark theme with no color-scheme (form controls and scrollbars stay light)"),
763
+ ("no-reduced-motion", "#63", "Animations with no prefers-reduced-motion alternative"),
653
764
  ]
654
765
 
655
766
 
656
767
  def all_rules():
657
768
  return [(r[0], r[1], r[2], r[4]) for r in RULES] + [(i, ref, d, "web" if i in ("hidden-nav", "side-stripe", "hard-shadow",
658
- "bounce-easing", "ghost-card", "mono-disguise", "off-scale", "undefined-token") else "all") for i, ref, d in FILE_RULES]
769
+ "bounce-easing", "ghost-card", "mono-disguise", "off-scale", "undefined-token", "multiple-h1", "section-numbers",
770
+ "count-pill", "icon-circle", "no-color-scheme", "no-reduced-motion") else "all") for i, ref, d in FILE_RULES]
659
771
 
660
772
 
661
773
  def gh_escape(s):
@@ -3,7 +3,7 @@
3
3
 
4
4
  python3 scripts/unslop-score.py [paths…] [--audit unslop-audit/report.json]
5
5
  [--scale …] [--json | --markdown] [--min 80]
6
- [--save [.unslop]]
6
+ [--save [.unslop]] [--baseline base.json]
7
7
 
8
8
  Scores the source with the same rules as `slop-scan.py` and, if you pass a
9
9
  `web-audit.mjs` report, the rendered page too (scroll, contrast, focus,
@@ -13,7 +13,9 @@ are left more than how big the codebase is. Prints the breakdown and a
13
13
  README badge. With --min it exits 1 below that score (pre-commit hook).
14
14
  With --save it appends the run to .unslop/history.json and prints the
15
15
  trend ("score 41 → 88 → 91"); --markdown prints a table for a PR comment or
16
- a GitHub Actions job summary.
16
+ a GitHub Actions job summary. --baseline compares with an earlier --json
17
+ run (the base branch in a PR): "score 72 → 81 (+9)", what got better and what
18
+ got worse.
17
19
 
18
20
  It is a smoke alarm, not a judge: a 95 can still have a flat hierarchy,
19
21
  and a gradient you chose on purpose costs points anyway (silence that line
@@ -66,6 +68,19 @@ CODE = {
66
68
  "ghost-card": ("Border and shadow on one card", "#68", 1, 4),
67
69
  "mono-disguise": ("Monospace headings or body", "#69", 2, 4),
68
70
  "plural-hack": ("\"item(s)\" plurals", "#71", 1, 3),
71
+ "justified-text": ("Justified text", "#28", 1, 3),
72
+ "extreme-tracking": ("Crushed letter-spacing", "#29", 1, 3),
73
+ "fixed-width": ("Fixed widths of 400px+", "#57", 2, 6),
74
+ "lorem": ("Lorem ipsum", "#48", 3, 6),
75
+ "placeholder-image": ("Placeholder images", "#48", 2, 6),
76
+ "bare-delta": ("Deltas with no baseline", "#52", 1, 4),
77
+ "straight-quotes": ("Straight quotes in copy", "#61", 0.5, 3),
78
+ "multiple-h1": ("More than one h1", "#13", 2, 2),
79
+ "section-numbers": ("Sections numbered 01/02/03", "#60", 1, 1),
80
+ "count-pill": ("Counts in filled pills", "#50", 1, 4),
81
+ "icon-circle": ("Icons in colored circles", "#33", 1, 2),
82
+ "no-color-scheme": ("Dark theme without color-scheme", "#62", 2, 2),
83
+ "no-reduced-motion": ("Animation without reduced motion", "#63", 3, 3),
69
84
  }
70
85
  # Rendered page. "sprawl" = distinct values beyond what a system needs.
71
86
  PAGE = {
@@ -166,6 +181,26 @@ def save_run(folder, run):
166
181
  return [h["score"] for h in history]
167
182
 
168
183
 
184
+ def compare(base, score, lines):
185
+ """Score delta and per-row changes against an earlier --json output."""
186
+ before = {r["rule"]: (r["count"], r["points"]) for r in base.get("penalties", [])}
187
+ now = {r: (n, p) for p, r, n in lines}
188
+ better, worse = [], []
189
+ for rule in sorted(set(before) | set(now)):
190
+ (bn, bp), (nn, np_) = before.get(rule, (0, 0)), now.get(rule, (0, 0))
191
+ if np_ < bp:
192
+ better.append({"rule": rule, "from": bn, "to": nn, "points": round(bp - np_, 1)})
193
+ elif np_ > bp:
194
+ worse.append({"rule": rule, "from": bn, "to": nn, "points": round(np_ - bp, 1)})
195
+ better.sort(key=lambda x: -x["points"])
196
+ worse.sort(key=lambda x: -x["points"])
197
+ return {"score": base["score"], "delta": score - base["score"], "better": better, "worse": worse}
198
+
199
+
200
+ def signed(n):
201
+ return f"+{n:g}" if n > 0 else f"{n:g}" if n < 0 else "±0"
202
+
203
+
169
204
  def main():
170
205
  ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
171
206
  ap.add_argument("paths", nargs="*", help="source to scan (default: . unless only --audit is given)")
@@ -176,6 +211,8 @@ def main():
176
211
  ap.add_argument("--save", nargs="?", const=".unslop", metavar="DIR",
177
212
  help="append this run to DIR/history.json (default .unslop) and show the trend")
178
213
  ap.add_argument("--min", type=float, help="exit 1 below this score")
214
+ ap.add_argument("--baseline", metavar="JSON", help="an earlier --json output to compare with (e.g. the base branch)")
215
+ ap.add_argument("--baseline-label", default="baseline", metavar="NAME", help="what to call it (e.g. main)")
179
216
  ap.add_argument("--type-scale", help="allowed font sizes in px (default: the project context, else slop-scan's)")
180
217
  ap.add_argument("--context", metavar="FILE", help="project context to read (default .unslop/context.md if present)")
181
218
  ap.add_argument("--no-context", action="store_true", help="ignore .unslop/context.md")
@@ -242,12 +279,34 @@ def main():
242
279
  scores = save_run(a.save, {"score": score, "files": files, "audit": bool(a.audit), "allowed": allowed,
243
280
  "penalties": [{"rule": r, "count": n, "points": p} for p, r, n in lines]})
244
281
  trend = " → ".join(str(s) for s in scores[-5:])
282
+ cmp_ = None
283
+ if a.baseline:
284
+ try:
285
+ with open(a.baseline, encoding="utf-8") as fh:
286
+ cmp_ = compare(json.load(fh), score, lines)
287
+ except (OSError, ValueError, KeyError) as e:
288
+ sys.exit(f"can't read the baseline {a.baseline}: {e}. It is the --json output of an earlier run.")
245
289
  if a.markdown:
246
- out = [f"### unslop score: {score}/100 ({word})", ""]
290
+ if cmp_:
291
+ out = [f"### unslop score: {score}/100 ({signed(cmp_['delta'])} vs {a.baseline_label})", "",
292
+ f"{a.baseline_label} {cmp_['score']} → this change {score}", ""]
293
+ for title, rows, sign in (("Worse", cmp_["worse"], "-"), ("Better", cmp_["better"], "+")):
294
+ if rows:
295
+ out.append(f"**{title}**")
296
+ out += [f"- {r['rule']}: {r['from']} → {r['to']} ({sign}{r['points']:g})" for r in rows]
297
+ out.append("")
298
+ if not cmp_["better"] and not cmp_["worse"]:
299
+ out += ["No change in any row.", ""]
300
+ if lines:
301
+ out += ["<details><summary>Every row now</summary>", ""]
302
+ else:
303
+ out = [f"### unslop score: {score}/100 ({word})", ""]
247
304
  if trend and "→" in trend:
248
305
  out += [f"Trend: {trend}", ""]
249
306
  if lines:
250
307
  out += ["| Points | Fix | Hits |", "|---:|---|---:|"] + [f"| -{p:g} | {r} | {n} |" for p, r, n in lines]
308
+ if cmp_:
309
+ out += ["", "</details>"]
251
310
  else:
252
311
  out.append("Nothing found.")
253
312
  if allowed:
@@ -257,7 +316,7 @@ def main():
257
316
  elif a.json:
258
317
  print(json.dumps({"score": score, "verdict": word, "files": files, "audit": bool(a.audit), "badge": badge,
259
318
  "penalties": [{"rule": r, "count": n, "points": p} for p, r, n in lines],
260
- "allowed": allowed, "trend": trend}, indent=2))
319
+ "allowed": allowed, "trend": trend, "baseline": cmp_}, indent=2))
261
320
  else:
262
321
  src = []
263
322
  if paths:
@@ -269,6 +328,11 @@ def main():
269
328
  print(f"unslop score: {score}/100 — {word} ({' + '.join(src)})")
270
329
  if trend and "→" in trend:
271
330
  print(f"trend: {trend} ({os.path.join(a.save, 'history.json')})")
331
+ if cmp_:
332
+ print(f"vs {a.baseline_label}: {cmp_['score']} → {score} ({signed(cmp_['delta'])})")
333
+ for title, rows, sign in (("worse", cmp_["worse"], "-"), ("better", cmp_["better"], "+")):
334
+ for r in rows:
335
+ print(f" {title}: {r['rule']} {r['from']} → {r['to']} ({sign}{r['points']:g})")
272
336
  if allowed:
273
337
  print("allowed by the project (--allow, not scored): " + ", ".join(allowed))
274
338
  if lines: