dotslot 0.2.1__py3-none-any.whl

dotslot/__init__.py

@@ -0,0 +1,3 @@
+from .core import scan_text, fill_text, SlotError  # noqa
+from .verify import verify  # noqa
+__version__ = "0.2.1"

dotslot/__main__.py

@@ -0,0 +1,3 @@
+import sys
+from .cli import main
+sys.exit(main())

dotslot/cli.py

@@ -0,0 +1,204 @@
+"""dotslot scan | fill | check | fit"""
+from __future__ import annotations
+import argparse, json, subprocess, sys
+from .core import scan_text, fill_text, SlotError
+from .verify import verify
+from .width import layout, preview, legacy_ends, display_width
+
+def read(p): return sys.stdin.read() if p == '-' else open(p, encoding='utf-8').read()
+
+def parse_sets(items):
+    out = {}
+    for it in items or []:
+        k, sep, v = it.partition('=')
+        if not sep: raise SystemExit(f'--set needs name=value, got {it!r}')
+        out[k] = v
+    return out
+
+def cmd_scan(a):
+    rows = []
+    for p in a.files:
+        slots, issues = scan_text(read(p), p, a.mode)
+        for s in slots:
+            rows.append(dict(file=p, line=s.line + 1, col=s.col, index=s.index, name=s.name, role=s.role,
+                             width=s.width, lines=1 + len(s.conts), capacity=s.capacity + sum(c.capacity for c in s.conts),
+                             filled=s.filled, value=(s.block_value() if s.conts else s.value) if s.filled else None,
+                             policy=s.policy, in_comment=s.in_comment))
+        for sev, l, c, m in issues: print(f'{p}:{l+1}:{c}: {sev}: {m}', file=sys.stderr)
+    if a.json: print(json.dumps(rows, ensure_ascii=False, indent=1)); return 0
+    for r in rows:
+        v = '' if r['value'] is None else repr(r['value'])
+        print(f"{r['file']}:{r['line']}:{r['col']}  @{r['index']} {r['name'] or '-':12} {r['role']:6} "
+              f"w={r['width']:<3} x{r['lines']} cap={r['capacity']:<3} {'filled' if r['filled'] else 'empty ':6} "
+              f"{r['policy'] or '':8} {'#' if r['in_comment'] else ' '} {v}")
+    return 0
+
+def cmd_fill(a):
+    vals = parse_sets(a.set)
+    if a.json_values: vals.update(json.load(open(a.json_values)))
+    rc = 0
+    allow = set(a.allow.split(',')) if a.allow else None
+    for p in a.files:
+        try:
+            out = fill_text(read(p), vals, p, a.mode, a.overflow, tuple(a.clear or ()), allow)
+        except SlotError as e:
+            print(f'{p}: error: {e}', file=sys.stderr); rc = 2; continue
+        if a.in_place and p != '-':
+            open(p, 'w', encoding='utf-8').write(out)
+        else:
+            sys.stdout.write(out)
+    return rc
+
+def fit_report(text, path, mode, targets, tab, show_preview):
+    slots, _ = scan_text(text, path, mode)
+    lines = text.split('\n'); out = []; bad = {t: 0 for t in targets}
+    by_line = {}
+    for s in slots:
+        for x in [s] + s.conts: by_line.setdefault(x.line, []).append((s, x))
+    for li in sorted(by_line):
+        ln = lines[li]
+        cl = layout([(ln, 'line')], tab)
+        lw = cl[-1].col + cl[-1].width if cl else 0
+        leg = legacy_ends([(ln, 'line')], tab)[-1]
+        grows = any(h.policy == 'grow' for h, _ in by_line[li])
+        for head, x in by_line[li]:
+            end = display_width(ln[:x.end], 0, tab)
+            st = {}
+            for t in targets:
+                s_ = 'over' if end > t else 'pushes' if lw > t else 'maybe' if leg > t else 'ok'
+                st[t] = s_
+                if s_ != 'ok': bad[t] += 1
+            label = (head.name or f'@{head.index}') + ('' if x is head else f'[+{x.line - head.line}]')
+            out.append(f"{path}:{li+1}: slot {label} col {x.col}..{end} (line {lw}{'' if leg == lw else f', per-codepoint {leg}'})"
+                       f" {'grow' if grows else 'static'}  " + '  '.join(f'{t}:{v}' for t, v in st.items()))
+            if show_preview:
+                for t in targets:
+                    if st[t] in ('over', 'pushes') and (p := preview(cl, t)):
+                        out.append(f"    @{t}: {p['note']}" + (' (2-cell glyph straddles edge)' if p['straddle'] else ''))
+                        out.append(f"      word │{p['word'][0]}\n           │{p['word'][1]}")
+    return out, bad
+
+def cmd_fit(a):
+    targets = sorted(int(t) for t in a.targets.split(','))
+    rc = 0
+    for p in a.files:
+        text = read(p)
+        if a.set:
+            try: text = fill_text(text, parse_sets(a.set), p, a.mode, a.overflow)
+            except SlotError as e: print(f'{p}: error: {e}', file=sys.stderr); rc = 2; continue
+        out, bad = fit_report(text, p, a.mode, targets, a.tab, a.preview)
+        print('\n'.join(out)) if out else None
+        if bad.get(a.fail_at or targets[0]): rc = max(rc, 1)
+    return rc
+
+def base_text(a, p):
+    if a.base: return read(a.base)
+    if a.git_base:
+        r = subprocess.run(['git', 'show', f'{a.git_base}:./{p}'], capture_output=True, text=True,
+                           cwd=None)
+        return r.stdout if r.returncode == 0 else None   # new file: nothing to compare
+    return None
+
+def cmd_new(a):
+    pol = a.policy or ''
+    head = f'{a.name}{pol}:' if a.name else (f'{pol}:' if pol else '')
+    if a.width < len(head) + 1: raise SystemExit(f'width {a.width} leaves no room after {head!r}')
+    pre, post = a.comment, (' ' + CLOSE[a.comment.strip()] if a.comment.strip() in CLOSE else '')
+    lines = [pre + '<./' + head + a.pad * (a.width - len(head)) + '>' + post]
+    for _ in range(a.lines - 1):
+        lines.append(pre + '<./|' + a.pad * (a.width - 1) + '>' + post)
+    if a.md: lines = ['`' + l + '`' for l in lines]
+    print('\n'.join(lines)); return 0
+
+CLOSE = {'<!--': '-->', '/*': '*/'}
+
+def cmd_repad(a):
+    from .core import scan_text as sc, render
+    base, text = read(a.base), read(a.files[0])
+    bs, _ = sc(base, a.files[0], a.mode); ns, _ = sc(text, a.files[0], a.mode)
+    if len(bs) != len(ns): print('slot count differs; cannot repad', file=sys.stderr); return 2
+    lines = text.split('\n'); fixed = 0
+    for b, n in sorted(zip(bs, ns), key=lambda p: (p[1].line, -p[1].start)):
+        if b.width != n.width and not n.conts and b.policy != 'grow' and b.header == n.header:
+            if len(n.raw_value) and __import__('dotslot.width', fromlist=['cells']).cells(n.header + n.raw_value) <= b.width:
+                ln = lines[n.line]
+                lines[n.line] = ln[:n.start] + '<./' + render(n.header, n.raw_value, b.width, b.pad) + '>' + ln[n.end:]
+                fixed += 1
+    out = '\n'.join(lines)
+    if a.in_place: open(a.files[0], 'w', encoding='utf-8').write(out)
+    else: sys.stdout.write(out)
+    print(f'repadded {fixed} slot(s)', file=sys.stderr); return 0
+
+def cmd_check(a):
+    rc = 0
+    req = set((a.require or '').split(',')) - {''}
+    allow = set(a.allow.split(',')) if a.allow else None
+    reports = []
+    for p in a.files:
+        text = read(p)
+        b = base_text(a, p)
+        if b is not None:
+            r = verify(b, text, p, a.mode, allow); r['file'] = p; reports.append(r)
+            if not a.json:
+                for c in r['changed']: print(f"{p}:{c['line']}: filled {c['slot']}: {c['before']!r} -> {c['after']!r}")
+                for x in r['violations']: print(f'{p}: VIOLATION: {x}')
+                print(f"{p}: {'fill-safe' if r['ok'] else 'NOT fill-safe'} ({len(r['changed'])} slot(s) changed)")
+            if not r['ok']: rc = 1
+            continue
+        slots, issues = scan_text(text, p, a.mode)
+        probs = [(sev, l, c, m) for sev, l, c, m in issues]
+        for s in slots:
+            if (a.require_filled or (s.name in req)) and not s.filled:
+                probs.append(('E', s.line, s.col, f'{s.name or "@%d" % s.index} is empty'))
+        names = {s.name for s in slots}
+        for n in req - names: probs.append(('E', 0, 0, f'required slot {n!r} not found'))
+        if a.fit:
+            out, bad = fit_report(text, p, a.mode, [a.fit], a.tab, False)
+            for o in out:
+                if f'{a.fit}:ok' not in o: probs.append(('E', 0, 0, 'fit: ' + o.split(': ', 1)[1]))
+        for sev, l, c, m in probs:
+            if not a.json: print(f'{p}:{l+1}:{c}: {sev}: {m}')
+            if sev == 'E' or (a.strict and sev == 'W'): rc = 1
+        if not probs and not a.json: print(f'{p}: ok ({len(slots)} slots)')
+    if a.json: print(json.dumps(reports, ensure_ascii=False, indent=1))
+    return rc
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog='dotslot', description='fixed-width <./____> slots (v0.2)')
+    sub = ap.add_subparsers(dest='cmd', required=True)
+    def common(sp):
+        sp.add_argument('files', nargs='+')
+        sp.add_argument('--mode', choices=['auto', 'prose', 'comments'], default='auto',
+                        help='auto: bare slots only in prose files (.md .txt …); everything else comment-only')
+    s = sub.add_parser('scan'); common(s); s.add_argument('--json', action='store_true')
+    for name in ('fill', 'fit'):
+        f = sub.add_parser(name); common(f)
+        f.add_argument('--set', action='append', help='name=value or @N=value')
+        f.add_argument('--overflow', choices=['error', 'ellipsis', 'truncate', 'grow'], default='error',
+                       help='policy for slots without a !/~/+ marker')
+        f.add_argument('--allow', help='comma list of slot names/@N that may be filled')
+        if name == 'fill':
+            f.add_argument('--json-values'); f.add_argument('-i', '--in-place', action='store_true')
+            f.add_argument('--clear', action='append', help='empty a slot again (name or @N)')
+        else:
+            f.add_argument('--targets', default='80,100,120'); f.add_argument('--tab', type=int, default=8)
+            f.add_argument('--preview', action='store_true'); f.add_argument('--fail-at', type=int)
+    n = sub.add_parser('new', help='print a correctly sized slot or block')
+    n.add_argument('name', nargs='?'); n.add_argument('--width', type=int, required=True)
+    n.add_argument('--lines', type=int, default=1); n.add_argument('--policy', choices=['!', '~', '+'])
+    n.add_argument('--comment', default='', help="prefix such as '# ' or '<!-- '"); n.add_argument('--pad', default='_')
+    n.add_argument('--md', action='store_true', help='wrap in backticks (Markdown code span)')
+    n.set_defaults(indent_only=False)
+    r = sub.add_parser('repad', help='restore slot widths from a base file (fixes agents that drop padding)')
+    r.add_argument('files', nargs=1); r.add_argument('--base', required=True); r.add_argument('-i', '--in-place', action='store_true')
+    r.add_argument('--mode', choices=['auto', 'prose', 'comments'], default='auto')
+    c = sub.add_parser('check'); common(c)
+    c.add_argument('--require', help='comma list of names that must be filled')
+    c.add_argument('--require-filled', action='store_true'); c.add_argument('--strict', action='store_true')
+    c.add_argument('--fit', type=int, help='also fail lines wider than N cells'); c.add_argument('--tab', type=int, default=8)
+    c.add_argument('--base', help='fill-safe check: compare against this earlier version of the file')
+    c.add_argument('--git-base', help='fill-safe check against a git revision (e.g. HEAD, origin/main)')
+    c.add_argument('--allow', help='with --base: only these slots may change')
+    c.add_argument('--json', action='store_true')
+    a = ap.parse_args(argv)
+    return dict(scan=cmd_scan, fill=cmd_fill, check=cmd_check, fit=cmd_fit, new=cmd_new, repad=cmd_repad)[a.cmd](a)

dotslot/core.py

@@ -0,0 +1,284 @@
+r"""dotslot v0.2 — fixed-width fill-in slots `<./________>`.
+
+Interior (between `<./` and `>`), width W = its display cells in the file:
+    empty      <./________>           padding only ('_' or ' ')
+    named      <./status:____>        IDENT [policy] ':' padding
+    filled     <./status:done__>      header + value + padding
+               <./done_____>          unnamed value: no header, no cost
+    policy     <./~:______>           unnamed slot with a policy
+    cont       <./|more text___>      block continuation
+    policy     !  error (default)   ~  ellipsis   +  grow
+Escapes inside a value: \\  \<  \>  \_  \:  \|   (the tool writes them for you)
+"""
+from __future__ import annotations
+import os, re
+from dataclasses import dataclass, field
+from .width import cells, cut, display_width
+
+SLOT = re.compile(r'<\./((?:\\.|[^<>\\\n])*)>')
+OPEN = re.compile(r'<\./')
+IDENT = r'[A-Za-z_][\w-]*'
+HEADER = re.compile(rf'(?:({IDENT})([!~+]?)|([!~+])):')
+PAD = ' _'
+POLICY = {'!': 'error', '~': 'ellipsis', '+': 'grow', '': None}
+MARK = {v: k for k, v in POLICY.items() if v}
+PROSE = {'.md', '.markdown', '.txt', '.text', '.rst', '.adoc', '.org', '.slot'}
+COMMENT = {
+    **{e: ('#',) for e in '.py .sh .bash .zsh .yaml .yml .toml .rb .pl .r .mk .cfg .conf .dockerfile'.split()},
+    **{e: ('//', '/*') for e in '.js .mjs .cjs .ts .tsx .jsx .c .h .cc .cpp .go .rs .java .kt .swift .cs .css .scss .json5'.split()},
+    **{e: ('--',) for e in '.sql .lua .hs .elm'.split()},
+    **{e: (';',) for e in '.ini .el .lisp .clj .scm .asm'.split()},
+    **{e: ('<!--',) for e in '.html .htm .xml .svg .vue'.split()},
+}
+ALL_MARKERS = ('#', '//', '/*', '--', ';', '<!--')
+CLOSERS = ('-->', '*/')
+
+class SlotError(Exception):
+    pass
+
+def unescape(s): return re.sub(r'\\(.)', r'\1', s)
+
+def escape(v: str, unnamed: bool) -> str:
+    v = v.replace('\\', '\\\\').replace('<', '\\<').replace('>', '\\>')
+    if unnamed:
+        if v[:1] == '|': v = '\\' + v
+        m = HEADER.match(v)
+        if m: v = v[:m.end() - 1] + '\\:' + v[m.end():]
+    if v and v[-1] in PAD: v = v[:-1] + '\\' + v[-1]
+    return v
+
+def split_pad(s):
+    """-> (body, padding) where padding is the trailing run of unescaped ' '/'_'."""
+    i = len(s)
+    while i > 0 and s[i - 1] in PAD:
+        # stop if this pad char is escaped (odd number of backslashes before it)
+        j, bs = i - 2, 0
+        while j >= 0 and s[j] == '\\': bs += 1; j -= 1
+        if bs % 2: break
+        i -= 1
+    return s[:i], s[i:]
+
+@dataclass
+class Slot:
+    line: int; start: int; end: int; col: int; interior: str
+    kind: str                       # empty | named | filled | cont
+    name: str | None = None
+    policy: str | None = None
+    header: str = ''                # raw header incl ':' (or '|' for cont)
+    raw_value: str = ''             # escaped form as in the file
+    pad: str = '_'
+    in_comment: bool = False
+    role: str = 'inline'
+    conts: list = field(default_factory=list)
+    index: int = 0
+
+    @property
+    def width(self): return cells(self.interior)
+    @property
+    def capacity(self): return self.width - cells(self.header)
+    @property
+    def value(self): return unescape(self.raw_value) if self.raw_value else None
+    @property
+    def filled(self): return bool(self.raw_value)
+    def block_value(self):
+        return ' '.join(p for p in [self.value or ''] + [c.value or '' for c in self.conts] if p)
+
+def parse_interior(s: str):
+    if '\t' in s: return None
+    body, padding = split_pad(s)
+    pad = '_' if '_' in padding else (' ' if padding else '_')
+    if body.startswith('|'):
+        return dict(kind='cont', header='|', raw_value=body[1:], pad=pad)
+    m = HEADER.match(body)
+    if m:
+        name, pol = m.group(1), POLICY[m.group(2) or m.group(3) or '']
+        rest = body[m.end():]
+        return dict(kind='filled' if rest else ('named' if name else 'empty'), name=name, policy=pol,
+                    header=m.group(0), raw_value=rest, pad=pad)
+    if not body:
+        return dict(kind='empty', pad=pad) if padding else None
+    return dict(kind='filled', raw_value=body, pad=pad)
+
+def comment_start(line: str, markers) -> int:
+    """Index of the first comment marker outside '…' "…" `…` strings, or -1."""
+    q, i, n = None, 0, len(line)
+    while i < n:
+        c = line[i]
+        if q:
+            if c == '\\': i += 2; continue
+            if c == q: q = None
+        elif c in '"\'`':
+            # treat ' as a quote only when it pairs later on the line (Rust lifetimes, prose)
+            if c != "'" or line.find("'", i + 1) != -1: q = c
+        else:
+            for mk in markers:
+                if line.startswith(mk, i): return i
+        i += 1
+    return -1
+
+def markers_for(path, mode):
+    ext = os.path.splitext(path or '')[1].lower()
+    base = os.path.basename(path or '').lower()
+    if mode == 'prose': return None
+    if mode == 'auto' and (ext in PROSE or path in ('-', '/dev/stdin')): return None
+    if base in ('dockerfile', 'makefile'): return ('#',)
+    return COMMENT.get(ext, ALL_MARKERS)
+
+def scan_text(text: str, path: str = '-', mode: str = 'auto'):
+    lines = text.split('\n')
+    markers = markers_for(path, mode)
+    slots, issues = [], []
+    for i, ln in enumerate(lines):
+        taken = set()
+        cpos = comment_start(ln, markers) if markers else -1
+        for m in SLOT.finditer(ln):
+            taken.add(m.start())
+            col = display_width(ln[:m.start()])
+            if m.group(1) == '':
+                issues.append(('E', i, col, 'zero-width slot <./>')); continue
+            p = parse_interior(m.group(1))
+            if p is None:
+                issues.append(('W', i, col, f'slot-like text {m.group(0)!r} is not a valid slot (ignored)')); continue
+            if markers is not None and not (0 <= cpos < m.start()):
+                issues.append(('W', i, col, f'{m.group(0)!r} is outside a comment (ignored; use --mode prose)')); continue
+            s = Slot(i, m.start(), m.end(), col, m.group(1), in_comment=markers is not None, **p)
+            if (os.path.splitext(path)[1].lower() in ('.md', '.markdown') and '_' in m.group(1)
+                    and ln[:m.start()].count('`') % 2 == 0):
+                issues.append(('W', i, col, f"{m.group(0)!r}: '_' outside a code span can render as emphasis in Markdown; wrap it in backticks"))
+            if s.kind == 'cont': s.role = 'cont'
+            slots.append(s)
+        for m in OPEN.finditer(ln):
+            if m.start() not in taken and (markers is None or 0 <= cpos < m.start()):
+                issues.append(('E', i, display_width(ln[:m.start()]), "unterminated slot: '<./' without '>' on the same line"))
+    by_line = {}
+    for s in slots: by_line.setdefault(s.line, []).append(s)
+    owned = set()
+    for s in slots:
+        if s.kind in ('named', 'filled') and s.name:
+            j = s.line + 1
+            while True:
+                c = next((x for x in by_line.get(j, []) if x.kind == 'cont' and x.col == s.col), None)
+                if not c: break
+                if c.width != s.width:
+                    issues.append(('E', j, c.col, f'block {s.name}: continuation width {c.width} != head width {s.width}')); break
+                owned.add(id(c)); s.conts.append(c); j += 1
+            if s.conts: s.role = 'head'
+    for s in slots:
+        if s.kind == 'cont' and id(s) not in owned:
+            issues.append(('E', s.line, s.col, 'continuation <./|…> with no named slot directly above at the same column'))
+    top = [s for s in slots if s.role != 'cont']
+    widths = {}
+    for k, s in enumerate(top):
+        s.index = k + 1
+        if s.name: widths.setdefault(s.name, set()).add(s.width)
+        if s.capacity < 1 and s.policy != 'grow':
+            issues.append(('E', s.line, s.col, f'{s.name or "slot"}: header leaves {s.capacity} cells for a value (width {s.width})'))
+    for n, ws in widths.items():
+        if len(ws) > 1: issues.append(('W', 0, 0, f'name {n!r} used with different widths {sorted(ws)}'))
+    return top, issues
+
+# ---------------------------------------------------------------- fill
+def clean(v: str, block: bool):
+    v = str(v)
+    if block: v = re.sub(r'\s*\n\s*', ' ', v)
+    if '\t' in v or '\n' in v:
+        raise SlotError('value contains a tab or newline; inline slots hold one line')
+    return v.rstrip(' ')
+
+def render(header, raw, width, pad):
+    body = header + raw
+    return body + pad * max(width - cells(body), 0)
+
+def cut_escaped(v, cap, unnamed, ellipsis):
+    """Cut the *unescaped* value so its escaped form fits cap; prefer a word boundary for ellipsis."""
+    lo, best = 0, ''
+    for k in range(len(v), -1, -1):
+        head = v[:k].rstrip(' ') if ellipsis else v[:k]
+        e = escape(head, unnamed) + ('…' if ellipsis else '')
+        if cells(e) <= cap:
+            best = head; break
+    if ellipsis and ' ' in best:
+        wb = best[:best.rfind(' ')].rstrip(' ')
+        if wb and cells(wb) >= (cap * 2) // 3: best = wb
+    return escape(best, unnamed) + ('…' if ellipsis else '')
+
+def fit_value(v, cap, policy, what, unnamed):
+    e = escape(v, unnamed)
+    if cells(e) <= cap: return e
+    if policy == 'ellipsis':
+        if cap < 2: raise SlotError(f'{what}: no room for an ellipsis')
+        return cut_escaped(v, cap, unnamed, True)
+    if policy == 'truncate': return cut_escaped(v, cap, unnamed, False)
+    if policy == 'grow': return e
+    raise SlotError(f'{what}: value is {cells(e)} cells, slot holds {cap} (overflow policy: error)')
+
+def wrap_words(v, caps):
+    words, lines, k = [w for w in v.split(' ') if w], [], 0
+    for cap in caps:
+        cur = ''
+        while k < len(words):
+            w = words[k]; cand = (cur + ' ' + w) if cur else w
+            if cells(escape(cand, False)) <= cap: cur, k = cand, k + 1
+            elif not cur and cells(escape(w, False)) > cap:
+                head, _ = cut(w, max(cap - 1, 1))
+                if not head: break
+                cur, words[k] = head, w[len(head):]; break
+            else: break
+        lines.append(cur)
+    return lines, ' '.join(words[k:])
+
+def fill_text(text, values, path='-', mode='auto', default_policy='error', clear=(), allow=None):
+    slots, issues = scan_text(text, path, mode)
+    errs = [x for x in issues if x[0] == 'E']
+    if errs: raise SlotError('; '.join(f'line {l+1}: {m}' for _, l, _, m in errs))
+    lines = text.split('\n'); edits, inserts, used = [], [], set()
+    for s in slots:
+        key = f'@{s.index}'
+        target = key if key in values or key in clear else s.name
+        if target is None or (target not in values and target not in clear): continue
+        if allow is not None and target not in allow:
+            raise SlotError(f'{target}: not in the allowed slot list')
+        if target in clear:
+            used.add(target)
+            for x in [s] + s.conts:
+                h = x.header
+                edits.append((x.line, x.start, x.end, '<./' + render(h, '', x.width, x.pad) + '>'))
+            continue
+        used.add(target)
+        pol = s.policy or default_policy; what = s.name or key; unnamed = not s.header
+        v = clean(values[target], bool(s.conts))
+        if not s.conts:
+            raw = fit_value(v, s.capacity, pol, what, unnamed)
+            edits.append((s.line, s.start, s.end, '<./' + render(s.header, raw, s.width, s.pad) + '>'))
+            continue
+        rows = [s] + s.conts; caps = [r.capacity for r in rows]
+        got, left = wrap_words(v, caps); extra = []
+        if left:
+            if pol == 'grow':
+                while left:
+                    more, left2 = wrap_words(left, [s.width - 1])
+                    if left2 == left: raise SlotError(f'{what}: cannot wrap {left!r}')
+                    extra.append(more[0]); left = left2
+            elif pol == 'ellipsis':
+                last = (got[-1] + ' ' + left).strip()
+                got[-1] = None; edits_last = cut_escaped(last, caps[-1], False, True)
+            elif pol == 'truncate': pass
+            else:
+                raise SlotError(f'{what}: block holds {sum(caps)} cells in {len(caps)} lines; '
+                                f'{cells(left)} cells left over (overflow policy: error)')
+        for r, g in zip(rows, got):
+            raw = edits_last if g is None else escape(g, False)
+            edits.append((r.line, r.start, r.end, '<./' + render(r.header, raw, r.width, r.pad) + '>'))
+        if extra:
+            last = rows[-1]; ln = lines[last.line]
+            before, after = ln[:last.start], ln[last.end:]
+            lead = before if not before.strip(' \t#/;*-!<') else ' ' * display_width(before)
+            tail = after if after.strip() in CLOSERS or not after.strip() else ''
+            inserts.append((last.line, [lead + '<./' + render('|', escape(e, False), s.width, last.pad) + '>' + tail for e in extra]))
+    missing = [k for k in list(values) + list(clear) if k not in used]
+    if missing: raise SlotError(f'no slot named {", ".join(missing)}')
+    for li, st, en, new in sorted(edits, key=lambda e: (e[0], -e[1])):
+        lines[li] = lines[li][:st] + new + lines[li][en:]
+    for after, new in sorted(inserts, reverse=True):
+        lines[after + 1:after + 1] = new
+    return '\n'.join(lines)

dotslot/mcp.py

@@ -0,0 +1,77 @@
+"""Minimal MCP server (stdio, JSON-RPC 2.0, newline-delimited) exposing dotslot.
+Run:  python -m dotslot.mcp --root /path/to/repo
+The only write path is `dotslot_fill`, which changes slot interiors and re-verifies the result."""
+from __future__ import annotations
+import argparse, difflib, json, os, sys
+from .core import scan_text, fill_text, SlotError
+from .verify import verify
+from . import __version__
+
+TOOLS = [
+    dict(name='dotslot_scan', description='List the fill-in slots in a file (name, width, capacity, current value).',
+         inputSchema=dict(type='object', properties=dict(path=dict(type='string')), required=['path'])),
+    dict(name='dotslot_fill', description='Fill named or @N slots in a file. Only slot interiors change; '
+         'the result is verified fill-safe before it is written. Use dry_run to preview the diff.',
+         inputSchema=dict(type='object', properties=dict(
+             path=dict(type='string'), values=dict(type='object', additionalProperties=dict(type='string')),
+             overflow=dict(type='string', enum=['error', 'ellipsis', 'truncate', 'grow']),
+             dry_run=dict(type='boolean')), required=['path', 'values'])),
+    dict(name='dotslot_check', description='Prove a file differs from a base version only inside slots.',
+         inputSchema=dict(type='object', properties=dict(path=dict(type='string'), base_text=dict(type='string'),
+             allow=dict(type='array', items=dict(type='string'))), required=['path', 'base_text'])),
+]
+
+class Server:
+    def __init__(self, root): self.root = os.path.realpath(root)
+    def _path(self, p):
+        full = os.path.realpath(os.path.join(self.root, p))
+        if os.path.commonpath([full, self.root]) != self.root: raise SlotError(f'{p}: outside the server root')
+        return full
+    def scan(self, path):
+        slots, issues = scan_text(open(self._path(path), encoding='utf-8').read(), path)
+        return dict(slots=[dict(index=s.index, name=s.name, line=s.line + 1, width=s.width, lines=1 + len(s.conts),
+                                capacity=s.capacity + sum(c.capacity for c in s.conts), policy=s.policy,
+                                value=(s.block_value() if s.conts else s.value)) for s in slots],
+                    issues=[f'{sev} line {l+1}: {m}' for sev, l, _, m in issues])
+    def fill(self, path, values, overflow='error', dry_run=False):
+        full = self._path(path); old = open(full, encoding='utf-8').read()
+        new = fill_text(old, values, path, 'auto', overflow or 'error')
+        r = verify(old, new, path)
+        if not r['ok']: raise SlotError('refusing to write: ' + '; '.join(r['violations']))
+        diff = ''.join(difflib.unified_diff(old.splitlines(True), new.splitlines(True), path, path))
+        if not dry_run: open(full, 'w', encoding='utf-8').write(new)
+        return dict(written=not dry_run, changed=r['changed'], diff=diff)
+    def check(self, path, base_text, allow=None):
+        new = open(self._path(path), encoding='utf-8').read()
+        return verify(base_text, new, path, 'auto', set(allow) if allow else None)
+
+    def handle(self, msg):
+        m, mid, p = msg.get('method'), msg.get('id'), msg.get('params') or {}
+        if m == 'initialize':
+            res = dict(protocolVersion=p.get('protocolVersion', '2025-06-18'), capabilities=dict(tools={}),
+                       serverInfo=dict(name='dotslot', version=__version__))
+        elif m == 'tools/list': res = dict(tools=TOOLS)
+        elif m == 'tools/call':
+            name, args = p.get('name'), p.get('arguments') or {}
+            fn = dict(dotslot_scan=self.scan, dotslot_fill=self.fill, dotslot_check=self.check).get(name)
+            try:
+                if not fn: raise SlotError(f'unknown tool {name}')
+                out, err = fn(**args), False
+            except (SlotError, OSError, TypeError) as e:
+                out, err = dict(error=str(e)), True
+            res = dict(content=[dict(type='text', text=json.dumps(out, ensure_ascii=False))], isError=err)
+        elif mid is None: return None            # notification
+        elif m == 'ping': res = {}
+        else: return dict(jsonrpc='2.0', id=mid, error=dict(code=-32601, message=f'unknown method {m}'))
+        return None if mid is None else dict(jsonrpc='2.0', id=mid, result=res)
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog='dotslot-mcp'); ap.add_argument('--root', default='.')
+    a = ap.parse_args(argv); srv = Server(a.root)
+    for line in sys.stdin:
+        if not line.strip(): continue
+        out = srv.handle(json.loads(line))
+        if out is not None: sys.stdout.write(json.dumps(out, ensure_ascii=False) + '\n'); sys.stdout.flush()
+
+if __name__ == '__main__':
+    main()

dotslot/verify.py

@@ -0,0 +1,58 @@
+"""Fill-safe verification: prove that only slot interiors changed between two texts."""
+from __future__ import annotations
+import difflib
+from .core import scan_text
+
+def _skeleton(text, slots):
+    lines = text.split('\n')
+    spans = {}
+    for s in slots:
+        key = s.name or f'@{s.index}'
+        spans.setdefault(s.line, []).append((s.start, s.end, f'⟦{key}⟧'))
+        for c in s.conts:
+            spans.setdefault(c.line, []).append((c.start, c.end, f'⟦{key}|⟧'))
+    out = []
+    for i, ln in enumerate(lines):
+        for st, en, tok in sorted(spans.get(i, []), reverse=True):
+            ln = ln[:st] + tok + ln[en:]
+        out.append(ln)
+    grow = {f'⟦{s.name}|⟧' for s in slots if s.policy == 'grow' and s.name}
+    col = []  # collapse repeated continuation lines of grow blocks (grow may add lines)
+    for ln in out:
+        if col and ln == col[-1] and any(g in ln for g in grow): continue
+        col.append(ln)
+    return col
+
+def verify(base, new, path='-', mode='auto', allow=None):
+    bs, bi = scan_text(base, path, mode)
+    ns, ni = scan_text(new, path, mode)
+    v, changed = [], []
+    nlines = new.split('\n')
+    for sev, l, c, m in ni:
+        if sev == 'E': v.append(f'line {l+1}: {m}')
+    sb, sn = _skeleton(base, bs), _skeleton(new, ns)
+    if sb != sn:
+        d = [x for x in difflib.unified_diff(sb, sn, 'base', 'new', lineterm='', n=0)][2:]
+        v.append('text outside slots changed:\n    ' + '\n    '.join(d[:12]))
+    if len(bs) != len(ns):
+        v.append(f'slot count changed: {len(bs)} -> {len(ns)}')
+    for a, b in zip(bs, ns):
+        key = a.name or f'@{a.index}'
+        if (a.name, a.policy) != (b.name, b.policy):
+            v.append(f'{key}: header changed {a.header!r} -> {b.header!r}')
+            continue
+        if a.policy != 'grow':
+            if a.width != b.width:
+                v.append(f'{key}: width changed {a.width} -> {b.width} (closing > moved)')
+                if b.width < a.width and '>' in nlines[b.line][b.end:]:
+                    v.append(f"{key}: hint: a raw '>' in the value closed the slot early; "
+                             f"escape it as '\\>' or fill with `dotslot fill`, which escapes for you")
+            if len(a.conts) != len(b.conts):
+                v.append(f'{key}: block height changed {1+len(a.conts)} -> {1+len(b.conts)}')
+        va = a.block_value() if a.conts else (a.value or '')
+        vb = b.block_value() if b.conts else (b.value or '')
+        if va != vb:
+            changed.append(dict(slot=key, line=b.line + 1, before=va, after=vb))
+            if allow is not None and key not in allow:
+                v.append(f'{key}: changed but not in the allowed list')
+    return dict(ok=not v, changed=changed, violations=v, slots=len(ns))

dotslot/width.py

@@ -0,0 +1,120 @@
+"""Display-width model, vendored from /workspace/artifacts/slotfit/slotfit.py (experiment g).
+wcwidth>=0.9 grapheme widths; tabs from the absolute column; ANSI = 0 cells."""
+from __future__ import annotations
+import re, unicodedata
+from dataclasses import dataclass
+from wcwidth import wcswidth, wcwidth
+
+ANSI = re.compile(r'\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]')
+ZWJ = '\u200d'
+
+def _extends(c: str) -> bool:
+    """True if c attaches to the previous cluster (zero-width joiners/marks/modifiers)."""
+    o = ord(c)
+    return (c == ZWJ or unicodedata.combining(c) or unicodedata.category(c) in ('Mn', 'Me')
+            or 0xFE00 <= o <= 0xFE0F or 0x1F3FB <= o <= 0x1F3FF or 0xE0020 <= o <= 0xE007F)
+
+def clusters(s: str):
+    """Yield display units: ANSI escapes, tabs, and grapheme-ish clusters."""
+    i, n = 0, len(s)
+    while i < n:
+        m = ANSI.match(s, i)
+        if m:
+            yield m.group(0); i = m.end(); continue
+        j = i + 1
+        while j < n and (_extends(s[j]) or s[j - 1] == ZWJ):
+            j += 1
+        # regional-indicator pair = one flag
+        if 0x1F1E6 <= ord(s[i]) <= 0x1F1FF and j < n and 0x1F1E6 <= ord(s[j]) <= 0x1F1FF:
+            j += 1
+        yield s[i:j]; i = j
+
+def unit_width(u: str, col: int, tab: int) -> int:
+    if u == '\t':
+        return tab - (col % tab)
+    if u.startswith('\x1b'):
+        return 0
+    w = wcswidth(u)
+    if w < 0:  # contains a control char: count printable parts only
+        w = sum(max(wcwidth(c), 0) for c in u)
+    return w
+
+def legacy_ends(parts, tab=8):
+    """Per-part end columns under per-codepoint wcwidth (pyte, older xterm, many
+    TUI libs): a ZWJ family, skin-tone emoji or flag counts 4-6 cells, VS16 adds 0."""
+    col, ends = 0, []
+    for text, _ in parts:
+        i = 0
+        while i < len(text):
+            m = ANSI.match(text, i)
+            if m:
+                i = m.end(); continue
+            c = text[i]
+            col += tab - (col % tab) if c == '\t' else max(wcwidth(c), 0)
+            i += 1
+        ends.append(col)
+    return ends
+
+@dataclass
+class Cell:
+    text: str; col: int; width: int; src: str   # src: 'line' | slot name
+
+def layout(parts, tab=8):
+    """parts: [(text, src)] -> list[Cell] with absolute columns."""
+    cells, col = [], 0
+    for text, src in parts:
+        for u in clusters(text):
+            w = unit_width(u, col, tab)
+            cells.append(Cell(u, col, w, src)); col += w
+    return cells
+
+def _end(_c, start, s, tab):
+    col = start
+    for u in clusters(s):
+        col += unit_width(u, col, tab)
+    return col - start
+
+def display_width(s: str, start: int = 0, tab: int = 8) -> int:
+    """Cells s occupies when it starts at column `start` (tabs depend on start)."""
+    return _end(None, start, s, tab)
+
+def wrap_point(cells, target):
+    """Index of first cell that does not fit in `target` columns, or None."""
+    for i, c in enumerate(cells):
+        if c.col + c.width > target:
+            return i
+    return None
+
+def preview(cells, target):
+    k = wrap_point(cells, target)
+    if k is None:
+        return None
+    straddle = cells[k].width == 2 and cells[k].col == target - 1
+    vis = lambda cs: ''.join(' ' * c.width if c.text == '\t' else c.text for c in cs)
+    hard = (vis(cells[:k]), vis(cells[k:]))
+    # word wrap: last whitespace at or before k
+    b = next((i for i in range(k, -1, -1) if cells[i].text in (' ', '\t')), None)
+    if b is None or b == 0:
+        word = hard; moved = None; how = 'no space before the edge: falls back to a hard break'
+    else:
+        line1 = vis(cells[:b]).rstrip(' ')
+        rest = cells[b + 1:]
+        line2 = vis(rest)
+        moved = line2.split(' ')[0] if line2 else ''
+        word = (line1, line2); how = f'word "{moved}" moves to the next line'
+    return dict(target=target, hard_break_col=cells[k].col, hard=hard,
+                straddle=straddle, word=word, moved_word=moved, note=how)
+
+
+def cells(s: str) -> int:
+    """Cells of s at column 0 ignoring tab-stop position (slot interiors forbid tabs)."""
+    return display_width(s, 0)
+
+def cut(s: str, n: int):
+    """Longest prefix of s that fits in n cells -> (prefix, its cells)."""
+    out, w = [], 0
+    for u in clusters(s):
+        uw = unit_width(u, w, 8)
+        if w + uw > n: break
+        out.append(u); w += uw
+    return ''.join(out), w

dotslot-0.2.1.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: dotslot
+Version: 0.2.1
+Summary: Let agents fill the blanks in a file, and prove they touched nothing else.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ao3575911/dotslot
+Project-URL: Changelog, https://github.com/ao3575911/dotslot/blob/main/CHANGELOG.md
+Keywords: templates,fixed-width,ai-agents,mcp,pre-commit,lint
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: wcwidth>=0.2.6
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+[![M8ven Score](https://m8ven.ai/badge/mcp/ao3575911-dotslot-ia87ds?v=c3035f8aeacd04053e6285ac74d5eccb)](https://m8ven.ai/mcp/ao3575911-dotslot-ia87ds?s=readme)
+
+```
+dotslot: let agents fill the blanks, and prove they touched nothing else.
+
+Owner: `<./owner:____________>`   Status: `<./status~:____________>`
+
+$ dotslot fill release.md --set owner=Adam --set status="ready for tag" -i
+$ dotslot check release.md --git-base HEAD
+release.md: fill-safe (2 slot(s) changed)
+
+CLI · pre-commit · GitHub Action · MCP server (Claude Code, Cursor, aider)
+```
+
+[![ci](https://github.com/ao3575911/dotslot/actions/workflows/ci.yml/badge.svg)](https://github.com/ao3575911/dotslot/actions/workflows/ci.yml) · MIT · v0.2.1 · [Spec](SPEC.md) · [Experiments](EXPERIMENTS.md) · [Changelog](CHANGELOG.md)
+
+## What it is
+
+Mark the parts of a file that may change with `<./________>`. An agent or script fills those blanks and nothing else. `dotslot check` proves the diff touched only the blanks, and that each blank kept its width, so columns and line wraps stay put. It works in docs, configs and code comments.
+
+A file with slots is **fill-only**. That turns "don't touch the rest" into a rule a machine can check.
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install dotslot
+dotslot --help
+```
+
+Requires Python 3.10+ and `wcwidth`.
+
+## Use
+
+```bash
+dotslot new notes --width 26 --lines 3 --comment '# '   # generate a slot or block
+dotslot scan FILE                                         # list slots, widths, capacity
+dotslot fill FILE --set name=value -i                     # fill in place, width kept
+dotslot check FILE --git-base HEAD [--allow a,b]          # prove only slots changed
+dotslot repad FILE --base OLD -i                          # restore padding after a hand edit
+dotslot fit FILE --targets 80,100,120                     # where will lines wrap?
+```
+
+Slot forms: `<./______>` (unnamed), `<./owner:____>` (named), `<./status~:____>` (ellipsis on overflow). In Markdown, put slots in backticks. Full grammar: [SPEC.md](SPEC.md).
+
+## Integrations
+
+| tool | files | what it does |
+|---|---|---|
+| MCP server | `dotslot-mcp --root .` | `dotslot_scan`, `dotslot_fill`, `dotslot_check` over stdio; fill verifies before writing; paths confined to root |
+| Claude Code | [`integrations/claude-code/`](integrations/claude-code) | `.mcp.json`, a `PostToolUse` hook that exits 2 on a violation, and a skill |
+| Cursor | [`integrations/cursor/.cursor/`](integrations/cursor/.cursor) | `mcp.json` and a fill-only rule |
+| aider | [`integrations/aider/`](integrations/aider) | `lint-cmd: dotslot check --git-base HEAD` with auto-lint |
+| any agent | [`integrations/AGENTS.md`](integrations/AGENTS.md) | snippet to paste into your `AGENTS.md` |
+| pre-commit | [`.pre-commit-hooks.yaml`](.pre-commit-hooks.yaml) | `dotslot-check`, `dotslot-lint` |
+| GitHub Action | [`action.yml`](action.yml) | checks PR files against the base SHA, writes a JSON report to the step summary |
+
+pre-commit:
+
+```yaml
+- repo: https://github.com/ao3575911/dotslot
+  rev: v0.2.1
+  hooks: [{ id: dotslot-check }]
+```
+
+GitHub Action:
+
+```yaml
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 }
+- uses: ao3575911/dotslot@v0.2.1
+  with: { files: "docs/**/*.md config/*.yaml", allow: "status,owner" }
+```
+
+## Limits
+
+dotslot is a check, not a sandbox. The comment finder is a heuristic until tree-sitter lands; formatters such as gofmt can move columns, so run dotslot after them; trailing whitespace counts as a change. See [CHANGELOG.md](CHANGELOG.md) for open items and [PLAN.md](PLAN.md) for the roadmap.
+
+## Repository layout
+
+- `dotslot/`: the v0.2 package (CLI, MCP server).
+- `slot/`, `bin/slot`: the v0.1 reference, kept only so `experiments/run.sh` reproduces findings (a)–(g). Not installed.
+- `tests/`: 45 tests (12 v0.1, 33 v0.2). Run `pip install -e ".[test]" && pytest -q`.
+- `experiments/`: `run.sh` (a–g) and `run_v02.sh` (v02, h, i), with recorded output in `out/`.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE). Releases are GPG-signed in CI and carry SHA256SUMS and build provenance; see [RELEASING.md](RELEASING.md).

dotslot-0.2.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+dotslot/__init__.py,sha256=2ZSUkgTgIxw8nSPXRv_Uopskmg11Q9xJPdU6l8eyqNA,115
+dotslot/__main__.py,sha256=81Ek5TDGfhRLYb38ohIwEISYL8FAiiMV84Jhf6pukg8,50
+dotslot/cli.py,sha256=AT7qZV1t4Bf42B1k_9ssAiK_wRJitjezaPGdVGjxnFs,11064
+dotslot/core.py,sha256=ZXwNS6hhDQE_0CLxgGWhAqX2PPNSEIfU8NTcF0tgEPQ,13204
+dotslot/mcp.py,sha256=da6G3j8AZv6oAC4mLDOemSdjs0x-XyW0EziN647N6Ps,4726
+dotslot/verify.py,sha256=xlQUvFWjjY262dtp4xIDzddOR88r1Vrn-9JFCC0XERY,2769
+dotslot/width.py,sha256=rVgqDJv_bVu4r6hCAqvfdnHWY3UC5cp5QTgm46za_3g,4367
+dotslot-0.2.1.dist-info/licenses/LICENSE,sha256=42pO6DNxO2putX_18oSeOATK_LiOL9hvFHu_9LalqfQ,1066
+dotslot-0.2.1.dist-info/METADATA,sha256=eIqjNx_psPF56r03VcE_FiXzW3FSXNHdM2kOhkGPxRc,4828
+dotslot-0.2.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+dotslot-0.2.1.dist-info/entry_points.txt,sha256=WCOmATg-oO8C8Z7jIGHkNoP0Jc47K646UEn4KfNSxYM,76
+dotslot-0.2.1.dist-info/top_level.txt,sha256=zVvev3A5wUo5G5qrsM7VcAUXP4q3Jrsa9G8n-7cKVto,8
+dotslot-0.2.1.dist-info/RECORD,,

dotslot-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dotslot-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dotslot = dotslot.cli:main
+dotslot-mcp = dotslot.mcp:main

dotslot-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ao3575911
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dotslot-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+dotslot