Draw what a shared map carries, and close two redaction gaps it found (#37)

The README says a map is private by default and then leaves a reader to
take that on trust. This adds the drawing that says it instead: seven
things git or the filesystem hands index, and what each one becomes in
the written file. One row is marked, and it is the setting that puts
real absolute paths in the map.

Writing it meant reading sanitize_credentials closely, and two origins
went through it untouched. A password in an ssh URL survived, because
the userinfo rule was bound to http and https. A parameter named
access_token survived, because a word boundary cannot match between an
underscore and a letter, so a pattern anchored on one sees token and
misses every prefixed spelling of it. Both sit under a module docstring
that calls the redaction always-on. Drawing the gap would have
advertised it, so the code is fixed and ten new cases hold it: three
password-carrying schemes, ten parameter names bare and prefixed, one
ssh username that stays because a username is not a secret, and six
ordinary remotes that must come back byte for byte. Reverting the module
turns six of them red.

The value class after a credential name still runs to the end of the
query. Stopping it at an ampersand would uncover the next parameter,
which may be a secret whose name this pattern does not know, so the
greedy read is the safe one and the reason is now in the code.

The card gate measures every row against its column with the renderer's
own width table, and it checks two failures rather than one. A note that
loses its ending is the obvious case. A single token longer than the
column is the quiet one: greedy wrapping leaves it alone on its line,
the joined text still equals the source, and the drawing runs off the
page with every check green. Both are proved failable by a control card.

Measured against the real Hanken Grotesk face as well as the renderer's
table: 37 text elements, widest right edge 905.8 real and 904.2 by
table, against a rule at 916.

Co-authored-by: Zain Dana Harper <17142659+HarperZ9@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: HarperZ9

README.md

@@ -161,6 +161,8 @@ Everything works with zero configuration. An optional `.index.toml` at the works
 - Self-contained and safe with untrusted docs: one HTML file, no external URLs, markdown escaped as it renders, with hostile-content fixtures in the tests.
 - Private by default: paths are root-relative, the local root reduces to a short hash, and credential-shaped fragments in remote URLs are redacted.
 
+<p align="center"><img src="docs/art/what-leaves.svg" alt="Seven things git or the filesystem hands index, and what each one becomes in the written map. A password in a remote URL is replaced whole, a credential-shaped query parameter keeps its name and loses its value, and an ssh username is left alone because it is not a secret. Paths are measured from the scan root, a repository outside that root reduces to its own directory name, and the root itself reduces to sixteen hex characters. The marked row is the one setting that puts real absolute paths in the file, which the map then records against itself." width="100%"></p>
+
 ## Status
 
 `index-graph` 2.9.0 on PyPI, command `index`, Python 3.11+, Development Status Beta. It is used as the workspace map layer of [Project Telos](https://harperz9.github.io), alongside [gather](https://github.com/HarperZ9/gather), [crucible](https://github.com/HarperZ9/crucible), [forum](https://github.com/HarperZ9/forum), and [telos](https://github.com/HarperZ9/telos).

docs/art/index.art.json

@@ -32,5 +32,25 @@
         {"label": "UNVERIFIABLE", "note": "an endpoint sits outside the scanned workspace", "tone": "none"}
       ]
     }
+  ],
+  "cards": [
+    {
+      "file": "what-leaves.svg",
+      "kicker": "every origin and every path goes through this",
+      "title": "What a shared map carries about the machine that made it",
+      "source": "python -c \"import index_graph.gitmeta as g; print(g.sanitize_credentials.__doc__)\"",
+      "alt": "Seven things git or the filesystem hands index, and what each one becomes in the written map. A password in a remote URL is replaced whole, a credential-shaped query parameter keeps its name and loses its value, and an ssh username is left alone because it is not a secret. Paths are measured from the scan root, a repository outside that root reduces to its own directory name, and the root itself reduces to sixteen hex characters. The marked row is the one setting that puts real absolute paths in the file, which the map then records against itself.",
+      "footnote": "A map is written to be read somewhere else, so an origin is rewritten before it reaches a row and a path is measured from the scan root. Redaction works by pattern, which covers the parameter names listed here and cannot cover one it has never seen. The marked row is the setting that puts real paths in the file, and a map made that way says so in absolute_paths_included.",
+      "heads": ["what index is handed", "what the map carries", "why it lands that way"],
+      "fields": [
+        {"key": "a password in a remote", "value": "scheme, host, path", "note": "The userinfo goes as a unit, under any scheme, once a colon says a password came with the name."},
+        {"key": "a credential parameter", "value": "name kept, value gone", "note": "token, password, secret and api_key, bare or prefixed. The rest of the query goes with it."},
+        {"key": "ssh://git@host", "value": "left as it is", "note": "A username is not a secret, and blanking it costs a reader how the clone was set up."},
+        {"key": "a repo under the root", "value": "path relative to it", "note": "Forward slashes on every platform, and the root itself reads as a single dot."},
+        {"key": "a repo outside it", "value": "its own name only", "note": "relative_to raises and the fallback is the directory name, so no absolute path arrives by that route."},
+        {"key": "the scan root", "value": "16 hex characters", "note": "A sha256 prefix. Two maps under one root agree without either naming it."},
+        {"key": "portable turned off", "value": "absolute paths, flagged", "tone": "drift", "note": "The one setting that writes real paths, recorded in the map as absolute_paths_included."}
+      ]
+    }
   ]
 }

docs/art/what-leaves.svg

@@ -20,6 +20,7 @@
 
 from repo_art import header_svg  # noqa: E402
 from repo_flow import flow_svg  # noqa: E402
+from repo_card import card_svg  # noqa: E402
 
 ART = Path(__file__).resolve().parents[1] / "docs" / "art"
 
@@ -31,6 +32,8 @@ def rendered(spec_path: Path) -> dict[Path, str]:
     out = {spec_path.parent / f"{stem}-header.svg": header_svg(spec["header"])}
     for flow in spec.get("flows", []):
         out[spec_path.parent / flow["file"]] = flow_svg(flow)
+    for card in spec.get("cards", []):
+        out[spec_path.parent / card["file"]] = card_svg(card)
     return out
 
 

scripts/render_repo_art.py

@@ -0,0 +1,176 @@
+"""repo_card.py -- the artifact a tool hands back, drawn field by field.
+
+Every command here writes a receipt, and until now the README said so in a
+sentence. A reader deciding whether to trust the tool wants to see the thing:
+what fields come back, which one carries the verdict, and how they would check
+each field themselves. This draws that from a spec, so the picture is data in
+the repository and a gate can hold it against a receipt the tool actually
+emits.
+
+Color still says one thing. Exactly one row carries the verdict and takes the
+verified green; a row that reports drift takes the drift iris. Every other row
+is ink and a hairline, because a field is structure and structure is not news.
+
+The value column shows a literal only where the literal is stable. A hash or a
+byte count changes with the checkout, so those rows carry the shape of the
+value instead: how many entries, how many keys. A picture that shows a hash is
+a picture that is wrong by the next commit.
+"""
+from __future__ import annotations
+
+from repo_art import GROTESK, MONO, _esc, _num
+
+W = 960
+PAD = 44
+ROW_H = 46
+TOP = 142
+KEY_W = 186
+VAL_W = 258
+GUTTER = 26
+NOTE_X = PAD + KEY_W + GUTTER + VAL_W + GUTTER
+NOTE_W = W - PAD - NOTE_X
+
+# The same two palettes the schematics use, so the whole set reads as one hand.
+STYLE = """
+  :root{ --void:#f4f3ef; --bone:#0b0c0e; --muted:#43474e;
+    --hairline:rgba(11,12,14,.16); --card:rgba(255,255,255,.66);
+    --verified:#1f7a52; --drift:#3a2bd6; }
+  @media (prefers-color-scheme: dark){
+    :root{ --void:#0b0e0f; --bone:#eef1ee; --muted:#9aa39c;
+      --hairline:rgba(238,241,238,.18); --card:rgba(255,255,255,.05);
+      --verified:#5fae93; --drift:#a99cf5; } }
+  .bg{ fill:var(--void); }
+  .row{ fill:var(--card); stroke:var(--hairline); stroke-width:1.2; }
+  .key{ fill:var(--bone); font-size:13px; font-weight:650; }
+  .val{ fill:var(--muted); font-size:12px; }
+  .s{ fill:var(--muted); font-size:11.5px; }
+  .k{ fill:var(--muted); font-size:11px; letter-spacing:.16em; }
+  .h{ fill:var(--bone); font-size:21px; font-weight:700; }
+  .thin{ stroke:var(--hairline); stroke-width:1.2; fill:none; }
+"""
+
+TONE = {"verified": "var(--verified)", "drift": "var(--drift)",
+        "none": "var(--hairline)"}
+
+# The column heads say what a row of this drawing is. A receipt reads as a
+# field and what comes back in it; something else in the repository reads as
+# something else, so a spec may name its own three and these are the default.
+HEADS = ("field", "what comes back", "how you check it")
+
+# What one character draws in the note and footnote columns, in pixels at
+# 11.5px. These are measured off a rendered probe rather than assumed, because
+# a budget counted in characters cannot tell an uppercase line from a
+# lowercase one: capitals run about a quarter wider, so a row of verdict
+# tokens fits a character count and still draws off the edge of the page.
+#
+# The weights round up. The drawing ships to readers whose machine resolves a
+# different face than the one measured, so a line that stops a little short is
+# a smaller defect than one that runs past the rule.
+UPPER, LOWER, DIGIT, SPACE, NARROW = 7.1, 5.75, 6.3, 3.2, 2.7
+_NARROW = frozenset(".,;:'!|")
+
+
+def _advance(char: str) -> float:
+    if char == " ":
+        return SPACE
+    if char.isupper():
+        return UPPER
+    if char.islower():
+        return LOWER
+    if char.isdigit():
+        return DIGIT
+    return NARROW if char in _NARROW else LOWER
+
+
+def text_width(text: str) -> float:
+    """What a line of note or footnote prose draws, in pixels."""
+    return sum(_advance(char) for char in text)
+
+
+# One line of the note column, in pixels. Two lines fit the row.
+NOTE_BUDGET = NOTE_W
+NOTE_LINES = 2
+
+# The footnote runs the width of the page at the same size, so it holds more.
+FOOT_BUDGET = W - PAD * 2
+FOOT_LINES = 3
+
+
+def _wrap(text: str, width: float = NOTE_BUDGET,
+          limit: int = NOTE_LINES) -> list[str]:
+    """Greedy wrap by drawn width, cut to the lines the caller has room for."""
+    lines: list[str] = []
+    line = ""
+    for word in text.split():
+        candidate = f"{line} {word}".strip()
+        if text_width(candidate) > width and line:
+            lines.append(line)
+            line = word
+        else:
+            line = candidate
+    if line:
+        lines.append(line)
+    return lines[:limit]
+
+
+def _row_y(index: int) -> float:
+    return TOP + index * ROW_H
+
+
+def _row(index: int, field: dict) -> str:
+    """One field: its name, what comes back in it, and how to check it."""
+    y = _row_y(index)
+    tone = TONE[field.get("tone", "none")]
+    accent = field.get("tone", "none") != "none"
+    notes = "".join(
+        f'<text class="s" x="{_num(NOTE_X)}" y="{_num(y + 20 + i * 15)}">'
+        f"{_esc(line)}</text>"
+        for i, line in enumerate(_wrap(field["note"])))
+    rule = (f'<rect x="{_num(PAD)}" y="{_num(y)}" width="3" '
+            f'height="{ROW_H - 8}" fill="{tone}"/>') if accent else ""
+    return (f'<g><rect class="row" x="{_num(PAD)}" y="{_num(y)}" '
+            f'width="{W - PAD * 2}" height="{ROW_H - 8}" rx="3"/>{rule}'
+            f'<text class="key" x="{_num(PAD + 16)}" y="{_num(y + 24)}" '
+            f'font-family="{MONO}">{_esc(field["key"])}</text>'
+            f'<text class="val" x="{_num(PAD + KEY_W + GUTTER)}" '
+            f'y="{_num(y + 24)}" font-family="{MONO}"'
+            f'{f" style={chr(34)}fill:{tone}{chr(34)}" if accent else ""}>'
+            f'{_esc(field["value"])}</text>{notes}</g>')
+
+
+def _column_heads(labels: tuple[str, str, str] = HEADS) -> str:
+    columns = (PAD + 16, PAD + KEY_W + GUTTER, NOTE_X)
+    return "".join(
+        f'<text class="k" x="{_num(x)}" y="{_num(TOP - 14)}" '
+        f'font-family="{MONO}">{_esc(label.upper())}</text>'
+        for label, x in zip(labels, columns))
+
+
+def _footnote(text: str, top: float) -> str:
+    return "".join(
+        f'<text class="s" x="{PAD}" y="{_num(top + i * 16)}">{_esc(line)}</text>'
+        for i, line in enumerate(_wrap(text, FOOT_BUDGET, FOOT_LINES)))
+
+
+def card_svg(spec: dict) -> str:
+    """A receipt drawn field by field, with the source that produced it."""
+    fields = spec["fields"]
+    foot = _wrap(spec["footnote"], FOOT_BUDGET, FOOT_LINES)
+    rule = _row_y(len(fields)) + 12
+    height = rule + 22 + len(foot) * 16
+    rows = "".join(_row(i, f) for i, f in enumerate(fields))
+    return (
+        f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {W} {_num(height)}" '
+        f'width="{W}" height="{_num(height)}" font-family="{GROTESK}" role="img" '
+        f'aria-label="{_esc(spec["alt"])}">'
+        f"<style>{STYLE}</style>"
+        f'<rect class="bg" width="{W}" height="{_num(height)}"/>'
+        f'<text class="k" x="{PAD}" y="40" font-family="{MONO}">'
+        f'{_esc(spec["kicker"].upper())}</text>'
+        f'<text class="h" x="{PAD}" y="72">{_esc(spec["title"])}</text>'
+        f'<text class="s" x="{PAD}" y="94" font-family="{MONO}" '
+        f'font-size="11.5">$ {_esc(spec["source"])}</text>'
+        f'{_column_heads(tuple(spec.get("heads", HEADS)))}{rows}'
+        f'<path class="thin" d="M{PAD} {_num(rule)}H{W - PAD}"/>'
+        f'{_footnote(spec["footnote"], rule + 22)}'
+        "</svg>")

scripts/repo_card.py

@@ -7,12 +7,34 @@
 from pathlib import Path
 from typing import Any
 
+# A web remote carries its whole userinfo as a secret. The token often
+# sits in the user slot with no password beside it, so the slot goes as a
+# unit.
 _USERINFO = re.compile(r"(?i)(https?://)[^/@]+@")
-_SECRET_QUERY = re.compile(r"(?i)\b(token|password|secret|api[_-]?key)=([^@\s]+)")
+# Every other scheme keeps its username, because ssh://git@host names a
+# user and nothing more. A colon means a password came with it, and that
+# is a secret whatever the scheme says.
+_PASSWORD_USERINFO = re.compile(
+    r"(?i)([a-z][a-z0-9+.-]*://)[^/@\s]*:[^/@\s]*@")
+# Parameter names arrive prefixed as often as bare, so access_token has to
+# match as readily as token. The value class runs to the end of the query
+# on purpose: swallowing a trailing parameter redacts more than was asked
+# for, and the alternative is publishing a second secret whose name this
+# pattern does not know.
+_SECRET_QUERY = re.compile(
+    r"(?i)(?<![\w-])([\w-]*(?:token|password|secret|api[_-]?key))=([^@\s]+)")
 
 
 def sanitize_credentials(origin: str) -> str:
+    """Strip the parts of a remote URL a reader of the map must not get.
+
+    What survives is the scheme, the host and the path, which is what
+    makes a remote recognisable. Every origin passes through here before
+    it reaches a row, so a map cannot carry a credential even when the
+    clone URL held one.
+    """
     clean = _USERINFO.sub(r"\1<redacted>@", origin)
+    clean = _PASSWORD_USERINFO.sub(r"\1<redacted>@", clean)
     return _SECRET_QUERY.sub(r"\1=<redacted>", clean)