@izhimu/pi-caveman 0.1.0 → 0.2.1

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.
@@ -0,0 +1,408 @@
1
+ #!/usr/bin/env python3
2
+ import re
3
+ from collections import Counter
4
+ from pathlib import Path
5
+
6
+ URL_REGEX = re.compile(r"https?://[^\s)]+")
7
+ FENCE_OPEN_REGEX = re.compile(r"^(\s{0,3})(`{3,}|~{3,})(.*)$")
8
+
9
+ # A line that is nothing but a fence marker plus an optional info string, at ANY
10
+ # indentation. Used ONLY to scrub leaked markers before inline-code pairing (see
11
+ # extract_inline_codes) — never for block extraction.
12
+ #
13
+ # Widening FENCE_OPEN_REGEX itself to `\s*` looks like the obvious fix for #820
14
+ # and is a net regression: a lone indented ``` (the natural way to SHOW a fence
15
+ # inside prose) then opens a block that runs to EOF, swallowing real code blocks
16
+ # and silently removing their inline spans from validation. That turns a
17
+ # false-failure bug into a false-PASS bug, and a false PASS overwrites the
18
+ # user's file with unvalidated output.
19
+ FENCE_MARKER_LINE_REGEX = re.compile(r"^\s*(?:`{3,}|~{3,})[^`~]*$")
20
+
21
+ # Cap on how much of a lost/added span is echoed in an error message. Unpaired
22
+ # backticks can make a "span" hundreds of characters of prose; printing it whole
23
+ # is what made #820's failures undiagnosable.
24
+ MAX_REPORTED_SPAN = 60
25
+ HEADING_REGEX = re.compile(r"^(#{1,6})\s+(.*)", re.MULTILINE)
26
+ BULLET_REGEX = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
27
+ # Any list item, ordered or not. Four spaces inside a list item is the item's
28
+ # content indentation, never an indented code block.
29
+ LIST_ITEM_REGEX = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s")
30
+
31
+ # crude but effective path detection
32
+ # Requires either a path prefix (./ ../ / or drive letter) or a slash/backslash within the match
33
+ PATH_REGEX = re.compile(r"(?:\./|\.\./|/|[A-Za-z]:\\)[\w\-/\\\.]+|[\w\-\.]+[/\\][\w\-/\\\.]+")
34
+
35
+ # PATH_REGEX is crude on purpose and also matches ordinary prose pairs —
36
+ # "pros/cons", "Node/browser", "state/lifecycle". Caveman prose ADDS those
37
+ # constructions freely and dropping one breaks nothing, so only an unambiguous
38
+ # path — a leading ./ ../ / or drive letter, or a dotted filename in the last
39
+ # component — is treated as a hard loss.
40
+ DEFINITE_PATH_REGEX = re.compile(r"^(?:\./|\.\./|/|[A-Za-z]:\\)|[^/\\]*\.[A-Za-z0-9]{1,8}$")
41
+
42
+
43
+ class ValidationResult:
44
+ def __init__(self):
45
+ self.is_valid = True
46
+ self.errors = []
47
+ self.warnings = []
48
+
49
+ def add_error(self, msg):
50
+ self.is_valid = False
51
+ self.errors.append(msg)
52
+
53
+ def add_warning(self, msg):
54
+ self.warnings.append(msg)
55
+
56
+
57
+ def read_file(path: Path) -> str:
58
+ return path.read_text(encoding="utf-8")
59
+
60
+
61
+ # ---------- Extractors ----------
62
+
63
+
64
+ def extract_headings(text):
65
+ return [(level, title.strip()) for level, title in HEADING_REGEX.findall(text)]
66
+
67
+
68
+ def extract_code_blocks(text):
69
+ """Line-based fenced code block extractor.
70
+
71
+ Handles ``` and ~~~ fences with variable length (CommonMark: closing
72
+ fence must use same char and be at least as long as opening). Supports
73
+ nested fences (e.g. an outer 4-backtick block wrapping inner 3-backtick
74
+ content).
75
+ """
76
+ blocks = []
77
+ lines = text.split("\n")
78
+ i = 0
79
+ n = len(lines)
80
+ while i < n:
81
+ m = FENCE_OPEN_REGEX.match(lines[i])
82
+ if not m:
83
+ i += 1
84
+ continue
85
+ fence_char = m.group(2)[0]
86
+ fence_len = len(m.group(2))
87
+ open_line = lines[i]
88
+ block_lines = [open_line]
89
+ i += 1
90
+ closed = False
91
+ while i < n:
92
+ close_m = FENCE_OPEN_REGEX.match(lines[i])
93
+ if (
94
+ close_m
95
+ and close_m.group(2)[0] == fence_char
96
+ and len(close_m.group(2)) >= fence_len
97
+ and close_m.group(3).strip() == ""
98
+ ):
99
+ block_lines.append(lines[i])
100
+ closed = True
101
+ i += 1
102
+ break
103
+ block_lines.append(lines[i])
104
+ i += 1
105
+ if closed:
106
+ blocks.append("\n".join(block_lines))
107
+ # Unclosed fences are silently skipped — they indicate malformed markdown
108
+ # and including them would cause false-positive validation failures.
109
+ return blocks + extract_indented_code_blocks(text)
110
+
111
+
112
+ def extract_indented_code_blocks(text):
113
+ """CommonMark indented code blocks — 4-space-indented runs outside any fence.
114
+
115
+ Without these, ` kubectl delete pod --all -n prod` was prose to the
116
+ validator: "code blocks preserved exactly" compared empty to empty and
117
+ PASSED while the compressor rewrote the command to
118
+ `kubectl delete pod -n dev`. A clean pass on a mutated destructive command
119
+ is the worst failure this tool has, because it overwrites the user's file.
120
+
121
+ Deliberately conservative about lists: inside a list item, four spaces are
122
+ the item's content indentation, not code, and nested bullets are ordinary
123
+ prose the compressor SHOULD rewrite. A run is only treated as code when the
124
+ document is not inside a list and the run is preceded by a blank line — so
125
+ this adds detections, it never turns existing passes into false failures.
126
+ """
127
+ blocks = []
128
+ lines = text.split("\n")
129
+ fenced = set()
130
+ for block in extract_fenced_spans(lines):
131
+ fenced.update(block)
132
+ in_list = False
133
+ previous_blank = True
134
+ i = 0
135
+ n = len(lines)
136
+ while i < n:
137
+ line = lines[i]
138
+ stripped = line.strip()
139
+ if i in fenced:
140
+ in_list, previous_blank = in_list, False
141
+ i += 1
142
+ continue
143
+ if not stripped:
144
+ previous_blank = True
145
+ i += 1
146
+ continue
147
+ indent = len(line) - len(line.lstrip(" \t"))
148
+ if LIST_ITEM_REGEX.match(line):
149
+ in_list = True
150
+ elif indent == 0:
151
+ in_list = False
152
+ if not in_list and previous_blank and indent >= 4:
153
+ run = []
154
+ while i < n and i not in fenced:
155
+ current = lines[i]
156
+ if not current.strip():
157
+ # A blank line continues an indented block only if more
158
+ # indented content follows.
159
+ lookahead = i + 1
160
+ while lookahead < n and not lines[lookahead].strip():
161
+ lookahead += 1
162
+ if lookahead < n and lookahead not in fenced and \
163
+ len(lines[lookahead]) - len(lines[lookahead].lstrip(" \t")) >= 4:
164
+ run.extend(lines[i:lookahead])
165
+ i = lookahead
166
+ continue
167
+ break
168
+ if len(current) - len(current.lstrip(" \t")) < 4:
169
+ break
170
+ run.append(current)
171
+ i += 1
172
+ if run:
173
+ blocks.append("\n".join(run))
174
+ previous_blank = False
175
+ continue
176
+ previous_blank = False
177
+ i += 1
178
+ return blocks
179
+
180
+
181
+ def extract_fenced_spans(lines):
182
+ """Line-index ranges covered by fenced blocks, so indented-code detection
183
+ never reaches inside one."""
184
+ spans = []
185
+ i = 0
186
+ n = len(lines)
187
+ while i < n:
188
+ m = FENCE_OPEN_REGEX.match(lines[i])
189
+ if not m:
190
+ i += 1
191
+ continue
192
+ fence_char = m.group(2)[0]
193
+ fence_len = len(m.group(2))
194
+ start = i
195
+ i += 1
196
+ while i < n:
197
+ close_m = FENCE_OPEN_REGEX.match(lines[i])
198
+ if (
199
+ close_m
200
+ and close_m.group(2)[0] == fence_char
201
+ and len(close_m.group(2)) >= fence_len
202
+ and close_m.group(3).strip() == ""
203
+ ):
204
+ i += 1
205
+ break
206
+ i += 1
207
+ spans.append(range(start, i))
208
+ return spans
209
+
210
+
211
+ def extract_urls(text):
212
+ return set(URL_REGEX.findall(text))
213
+
214
+
215
+ def extract_paths(text):
216
+ return set(PATH_REGEX.findall(text))
217
+
218
+
219
+ def count_bullets(text):
220
+ return len(BULLET_REGEX.findall(text))
221
+
222
+
223
+ def extract_inline_codes(text):
224
+ """Backtick-delimited inline spans, with fenced code blocks stripped first.
225
+
226
+ Previously used a column-0-anchored regex to strip fences, which misses
227
+ fences indented 1-3 spaces (valid CommonMark). Reuse extract_code_blocks
228
+ (FENCE_OPEN_REGEX-based, indentation-aware) instead so an indented fence's
229
+ body backticks don't leak into inline-code pairing.
230
+
231
+ Any fence-marker line that survives that pass is then blanked (#820). A
232
+ fence indented 4+ spaces — what you get from showing an example inside a
233
+ bullet — is not matched by FENCE_OPEN_REGEX, so extract_code_blocks does
234
+ not remove it and its OWN backticks used to leak in and shift the pairing
235
+ of every following span, making the file permanently uncompressible.
236
+ Blanking just the marker lines fixes that without removing any prose, and
237
+ cannot run away the way a widened fence opener does.
238
+
239
+ The span pattern deliberately still spans newlines. CommonMark permits a
240
+ line ending inside a code span and hard-wrapped markdown produces them, so
241
+ a single-line pattern silently drops real spans — which downgrades a
242
+ deleted or mutated span from error to PASS. Long/garbled spans are a
243
+ presentation problem, handled by truncating in the error message instead.
244
+ """
245
+ text_without_fences = text
246
+ for block in extract_code_blocks(text):
247
+ text_without_fences = text_without_fences.replace(block, "", 1)
248
+ text_without_fences = "\n".join(
249
+ "" if FENCE_MARKER_LINE_REGEX.match(line) else line
250
+ for line in text_without_fences.split("\n")
251
+ )
252
+ return re.findall(r"`([^`]+)`", text_without_fences)
253
+
254
+
255
+ # ---------- Validators ----------
256
+
257
+
258
+ def validate_headings(orig, comp, result):
259
+ h1 = extract_headings(orig)
260
+ h2 = extract_headings(comp)
261
+
262
+ # Changed heading TEXT is an error, not a warning. Every in-document anchor
263
+ # link points at a heading's slug, so renaming "# Configuration Options" to
264
+ # "# Config" silently breaks all of them — and SKILL.md and CLAUDE.md both
265
+ # state headings are preserved. Only counts used to gate the overwrite, so
266
+ # a run that renamed every heading reported "Validation passed". A level-only
267
+ # change keeps every slug intact and stays a warning.
268
+ if len(h1) != len(h2):
269
+ result.add_error(f"Heading count mismatch: {len(h1)} vs {len(h2)}")
270
+ return
271
+
272
+ t1 = [text for _, text in h1]
273
+ t2 = [text for _, text in h2]
274
+ if t1 != t2:
275
+ lost = [t for t in t1 if t not in t2]
276
+ added = [t for t in t2 if t not in t1]
277
+ result.add_error(f"Heading text/order changed: lost={lost}, added={added}")
278
+ elif h1 != h2:
279
+ # Same text, different level. The outline moved but no anchor broke —
280
+ # slugs come from the text, so links still resolve.
281
+ result.add_warning("Heading levels changed")
282
+
283
+
284
+ def validate_code_blocks(orig, comp, result):
285
+ c1 = extract_code_blocks(orig)
286
+ c2 = extract_code_blocks(comp)
287
+
288
+ if c1 != c2:
289
+ result.add_error("Code blocks not preserved exactly")
290
+
291
+
292
+ def validate_urls(orig, comp, result):
293
+ u1 = extract_urls(orig)
294
+ u2 = extract_urls(comp)
295
+
296
+ if u1 != u2:
297
+ result.add_error(f"URL mismatch: lost={u1 - u2}, added={u2 - u1}")
298
+
299
+
300
+ def validate_paths(orig, comp, result):
301
+ """File paths are preserved — an error, never a warning.
302
+
303
+ This validator never called add_error at all, so a compressed file that had
304
+ dropped `src/hooks/caveman-config.js` still reported "Validation passed" and
305
+ the in-place overwrite stood. SKILL.md and CLAUDE.md both promise paths
306
+ survive compression; nothing enforced it.
307
+ """
308
+ p1 = extract_paths(orig)
309
+ p2 = extract_paths(comp)
310
+ lost = p1 - p2
311
+ added = p2 - p1
312
+
313
+ definite = {p for p in lost if DEFINITE_PATH_REGEX.search(p)}
314
+ if definite:
315
+ result.add_error(f"File paths lost: {sorted(definite)}")
316
+ if (lost - definite) or added:
317
+ result.add_warning(f"Path mismatch: lost={sorted(lost)}, added={sorted(added)}")
318
+
319
+
320
+ def validate_bullets(orig, comp, result):
321
+ b1 = count_bullets(orig)
322
+ b2 = count_bullets(comp)
323
+
324
+ if b1 == 0:
325
+ return
326
+
327
+ diff = abs(b1 - b2) / b1
328
+
329
+ if diff > 0.15:
330
+ result.add_warning(f"Bullet count changed too much: {b1} -> {b2}")
331
+
332
+
333
+ def validate_inline_codes(orig, comp, result):
334
+ def _render_spans(spans):
335
+ """Render spans for an error message, truncated and newline-escaped.
336
+
337
+ A span may legitimately contain newlines, and an unpaired backtick can
338
+ make one hundreds of characters of prose. Printing those whole is what
339
+ made #820's failures undiagnosable — but the fix belongs here, in
340
+ presentation, not in what counts as a span.
341
+ """
342
+ out = []
343
+ for span in sorted(spans):
344
+ flat = span.replace("\n", "\\n")
345
+ if len(flat) > MAX_REPORTED_SPAN:
346
+ flat = flat[:MAX_REPORTED_SPAN] + "…"
347
+ out.append(repr(flat))
348
+ return "{" + ", ".join(out) + "}"
349
+
350
+ c1 = Counter(extract_inline_codes(orig))
351
+ c2 = Counter(extract_inline_codes(comp))
352
+
353
+ if c1 != c2:
354
+ lost = set(c1.keys()) - set(c2.keys())
355
+ added = set(c2.keys()) - set(c1.keys())
356
+ for code, count in c1.items():
357
+ if code in c2 and c2[code] < count:
358
+ lost.add(f"{code} (lost {count - c2[code]} of {count} occurrences)")
359
+ if lost:
360
+ result.add_error(f"Inline code lost: {_render_spans(lost)}")
361
+ if added:
362
+ result.add_warning(f"Inline code added: {_render_spans(added)}")
363
+
364
+
365
+ # ---------- Main ----------
366
+
367
+
368
+ def validate(original_path: Path, compressed_path: Path) -> ValidationResult:
369
+ result = ValidationResult()
370
+
371
+ orig = read_file(original_path)
372
+ comp = read_file(compressed_path)
373
+
374
+ validate_headings(orig, comp, result)
375
+ validate_code_blocks(orig, comp, result)
376
+ validate_urls(orig, comp, result)
377
+ validate_paths(orig, comp, result)
378
+ validate_bullets(orig, comp, result)
379
+ validate_inline_codes(orig, comp, result)
380
+
381
+ return result
382
+
383
+
384
+ # ---------- CLI ----------
385
+
386
+ if __name__ == "__main__":
387
+ import sys
388
+
389
+ if len(sys.argv) != 3:
390
+ print("Usage: python validate.py <original> <compressed>")
391
+ sys.exit(1)
392
+
393
+ orig = Path(sys.argv[1]).resolve()
394
+ comp = Path(sys.argv[2]).resolve()
395
+
396
+ res = validate(orig, comp)
397
+
398
+ print(f"\nValid: {res.is_valid}")
399
+
400
+ if res.errors:
401
+ print("\nErrors:")
402
+ for e in res.errors:
403
+ print(f" - {e}")
404
+
405
+ if res.warnings:
406
+ print("\nWarnings:")
407
+ for w in res.warnings:
408
+ print(f" - {w}")