napkinstack 0.19.4__tar.gz → 0.20.0__tar.gz

{napkinstack-0.19.4 → napkinstack-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: napkinstack
-Version: 0.19.4
+Version: 0.20.0
 Summary: Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI.
 License-Expression: MIT
 License-File: LICENSE
@@ -21,7 +21,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
 the project, which then receives new versions on demand; no application stack is imposed.
 Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 
-> **Status: v0.19.4, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.20.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
 > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
 > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
@@ -85,8 +85,8 @@ To try it without installing anything, or to install it from this repository ins
 registry — always pinned to a release tag:
 
 ```bash
-uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.19.4" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.19.4"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.20.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.20.0"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a

{napkinstack-0.19.4 → napkinstack-0.20.0}/README.md

@@ -5,7 +5,7 @@ modules, contracts, guardrails in CI. On the Django or Rails model, one command
 the project, which then receives new versions on demand; no application stack is imposed.
 Positioning and vocabulary: [`PRODUCT.md`](PRODUCT.md) §1.
 
-> **Status: v0.19.4, published** on [PyPI](https://pypi.org/project/napkinstack/).
+> **Status: v0.20.0, published** on [PyPI](https://pypi.org/project/napkinstack/).
 > What each version changes, engine and project apart: [`CHANGELOG.md`](CHANGELOG.md).
 > What is open: [`docs/governance/workstreams.md`](docs/governance/workstreams.md).
 
@@ -69,8 +69,8 @@ To try it without installing anything, or to install it from this repository ins
 registry — always pinned to a release tag:
 
 ```bash
-uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.19.4" nstack init my-project
-uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.19.4"
+uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.20.0" nstack init my-project
+uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.20.0"
 ```
 
 **Two channels, one published artefact.** The registry publishes: the PyPI artefact of a

{napkinstack-0.19.4 → napkinstack-0.20.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.19.4"
+version = "0.20.0"
 description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
 requires-python = ">=3.12"
 license = "MIT"

{napkinstack-0.19.4 → napkinstack-0.20.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "napkinstack"
-version = "0.19.4"
+version = "0.20.0"
 description = "Engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI."
 requires-python = ">=3.12"
 license = "MIT"

{napkinstack-0.19.4 → napkinstack-0.20.0}/src/napkinstack/doctor.py

@@ -415,10 +415,18 @@ def _kept_for_a_human(root: Path, shown: str, text: str) -> tuple[str, str]:
 
 
 def _agent_identities(root: Path) -> list[str]:
-    """The bot identities the recent history's commits name, as GitHub's noreply addresses say them."""
-    shown = subprocess.run(["git", "log", "-n", "500", "--format=%ae%n%ce"], cwd=root, capture_output=True, text=True)
-    found = [address.lower() for address in shown.stdout.split()
-             if address.lower().endswith("[bot]@users.noreply.github.com")]
+    """The bot identities of the recent history's commits that name a session, as GitHub's noreply
+    addresses say them. The line is what the kernel asks of an agent's commit: a forge's own bot,
+    Dependabot's, carries none and neither verifies nor approves (#310)."""
+    shown = subprocess.run(["git", "log", "-n", "500", "--format=%ae%x1f%ce%x1f%B%x1e"],
+                           cwd=root, capture_output=True, text=True)
+    found = []
+    for record in shown.stdout.split("\x1e"):
+        author, committer, message = (record.strip().split("\x1f") + ["", ""])[:3]
+        # In the whole message: a squash keeps it above a last paragraph of co-authors.
+        if re.search(r"^Agent-Session:[ \t]*\S", message, re.M | re.I):
+            found += [address.lower() for address in (author, committer)
+                      if address.lower().endswith("[bot]@users.noreply.github.com")]
     return list(dict.fromkeys(found))
 
 

{napkinstack-0.19.4 → napkinstack-0.20.0}/src/napkinstack/fitness/boundaries.py

@@ -211,7 +211,8 @@ def check_contracts(root: Path, modules: dict[str, dict]) -> dict[str, dict[str,
             offered = ", ".join(f"{k[0]} {k[1]} by {v}" for k, v in sorted(provided.items(), key=str)) or "none"
             if producer is None:
                 fail("B6", name, f"consumes {key[0]} {key[1]}, which no module provides (provided: {offered}).\n"
-                                 "      Action: consume a provided version, or have its producer declare it.")
+                                 "      Action: consume a provided version, or have its producer declare it first, "
+                                 "in a pull request of its own (.nstack/handbook/03-contracts.md §4).")
             elif c.get("module") not in (None, producer):
                 fail("B6", name, f"consumes {key[0]} {key[1]} from '{c.get('module')}', which is "
                                  f"provided by '{producer}'.\n      Action: name the producer.")

{napkinstack-0.19.4 → napkinstack-0.20.0}/src/napkinstack/fitness/manifests.py

@@ -130,7 +130,8 @@ def unfilled(value) -> bool:
 def is_description(path: str) -> bool:
     """A module's description — its manifest, AGENTS.md, README.md, docs/ — or an empty
     placeholder, `path` relative to the module's folder. Changing it changes no behaviour
-    (D24); a module holding nothing else has nothing to check yet (D33)."""
+    (D24); a module holding nothing else has nothing to check yet (D33). The one exception is read
+    from the manifests' values, not their path: pull_request.touched_modules (D184)."""
     # A page at any depth describes; it runs nothing. A contract's own page —
     # contracts/<name>/v1/README.md — is the case that asked: the module that holds it must
     # stay green until the contract gains a schema or a test (PDR-0012). Once a module consumes

{napkinstack-0.19.4 → napkinstack-0.20.0}/src/napkinstack/fitness/pr_scope.py

@@ -6,7 +6,8 @@ Fitness function 3 — Pull request scope and size.
 
 A module is touched when the pull request changes it beyond its description — the same
 count as `nstack pr-check`'s (D34): editing a manifest, an AGENTS.md, a README or docs/
-changes no module, and contracts/ is a module like any other.
+changes no module, unless the manifest moves its criticality or its user-facing surface (D184),
+and contracts/ is a module like any other.
 
 The `cross-module` label lifts P1, the `over-budget` label documents P2: both are visible,
 so the exceptions are countable (.nstack/handbook/10-measurement.md §3).

{napkinstack-0.19.4 → napkinstack-0.20.0}/src/napkinstack/hold.py

@@ -10,6 +10,10 @@ from it: the refusal is git's, on any forge. A hold is never merged; its work is
 Usage :  nstack claim D<n> [--session S] [--person P] [--take-over]
          nstack unclaim D<n> [--session S] [--person P]
 Output:  0 when the hold is taken, renewed or released; 1 when refused — saying who holds it.
+
+Two sessions of one person are two holders (D181, D185): a session renews only a hold it is on; a
+person's other session takes it with --take-over, on that person's word. A person with no session
+has nothing to tell apart, and their name answers.
 """
 
 from __future__ import annotations
@@ -360,7 +364,7 @@ def _show(root: Path, name: str | None, ident: str, title: str, person: str, bra
     said: list[str] = []
     try:
         if branch is None:
-            since = (f" from {previous.person}, on whose work nobody had worked since {when(previous.worked)}"
+            since = (f" from {previous.person}, last worked on {when(previous.worked)}"
                      if previous is not None else "")
             for number in _open_pulls(root, forge, ident):
                 _call(forge, "POST", f"/issues/{number}/comments", {"body": (
@@ -387,7 +391,7 @@ def claim(root: Path, ident: str, session: str | None = None, person: str | None
         print(f"FAIL [hold] {found}")
         return 1
     cycle, title = found
-    person = _person(root, person)
+    person, session = _person(root, person), (session or "").strip() or None
     if any(not value.isprintable() for value in (person, session or "")):
         print("FAIL [hold] a person or a session holds a line break or a control character: it would "
               "write the record's lines.\n      Action: name them on one line.")
@@ -402,11 +406,13 @@ def claim(root: Path, ident: str, session: str | None = None, person: str | None
     days = limit(root)
     stale_at = current.worked + days * DAY
     previous = None
+    mine = same(current.person, person)
+    other_session = _another_session(current, session)
     if not current.held:
         event = "claim"
-    elif same(current.person, person):
+    elif mine and not other_session:
         event = "renew"
-    elif take_over and time.time() >= stale_at:
+    elif take_over and (mine or time.time() >= stale_at):  # a person moves their own hold on their word
         event, previous = "take-over", current
     elif take_over:
         print(f"FAIL [hold] {ident} is {said(current)}: it is not stale — work on it is younger than "
@@ -419,7 +425,9 @@ def claim(root: Path, ident: str, session: str | None = None, person: str | None
         print(f"FAIL [hold] {ident} is {said(current)}" + (f" — stale, no work for {days} days." if stale else ".")
               + (f"\n      Action: {again} — recorded, with its previous holder."
                  if stale else "\n      Action: take another ready deliverable — nstack plan lists them; "
-                               "or ask its holder to give it back (nstack unclaim)."))
+                               "or ask its holder to give it back (nstack unclaim)."
+                               + (f"\n      Another session of the same person holds it: only if that person asks, "
+                                  f"{again} — recorded, with the session it leaves." if mine else "")))
         return 1
     sha = _event(root, current.tip, ident, event, person, session, previous)
     ok, where = _record(root, name, cycle, ident, sha)
@@ -436,7 +444,9 @@ def claim(root: Path, ident: str, session: str | None = None, person: str | None
         else:
             print(f"FAIL [hold] {ident}: the remote refused the hold.\n      {where}")
         return 1
-    done = {"claim": "taken", "renew": "renewed", "take-over": f"taken over from {previous.person if previous else ''}"}
+    left = f"{previous.person}, session {', '.join(previous.sessions)}" if previous and previous.sessions \
+        else (previous.person if previous else "")
+    done = {"claim": "taken", "renew": "renewed", "take-over": f"taken over from {left}"}
     print(f"{ident} {done[event]}: held by {person}" + (f", session {session}" if session else "") + f"; {where}.")
     if event != "renew":
         made, branch = _work_branch(root, name, ident, title, session)
@@ -445,6 +455,12 @@ def claim(root: Path, ident: str, session: str | None = None, person: str | None
     return 0
 
 
+def _another_session(current: Hold, session: str | None) -> bool:
+    """Named, and on none of the hold's events. A person with no session has nothing to tell apart."""
+    named = (session or "").strip().casefold()
+    return bool(named and current.sessions and named not in {held.casefold() for held in current.sessions})
+
+
 def _ended(root: Path, ident: str, current: str | None) -> str | None:
     """Where a hold of an ended cycle is still open: a hold lasts its cycle (#280). Nothing it
     guarded can be delivered any more, and a new cycle's hold is a branch of its own."""
@@ -459,7 +475,7 @@ def _ended(root: Path, ident: str, current: str | None) -> str | None:
 def release(root: Path, ident: str, session: str | None = None, person: str | None = None) -> int:
     cycle = plan.accepted_cycle(root)
     stem = cycle[0].stem if cycle else None
-    person = _person(root, person)
+    person, session = _person(root, person), (session or "").strip() or None
     if any(not value.isprintable() for value in (person, session or "")):
         print("FAIL [hold] a person or a session holds a line break or a control character.\n"
               "      Action: name them on one line.")
@@ -481,7 +497,13 @@ def release(root: Path, ident: str, session: str | None = None, person: str | No
     charter = plan.read_front_matter(root / plan.CHARTER)[0] if (root / plan.CHARTER).is_file() else None
     decider = str((charter or {}).get("decider") or "")
     stale = time.time() >= current.worked + limit(root) * DAY
-    if not (same(current.person, person) or (decider and same(decider, person)) or stale):
+    is_decider = bool(decider and same(decider, person))
+    if same(current.person, person) and _another_session(current, session) and not stale and not is_decider:
+        print(f"FAIL [hold] {ident} is {said(current)}: another session of the same person does not give it "
+              f"back.\n      Action: only if that person asks, nstack claim {ident} --take-over --person {person} "
+              f"--session {session}.")
+        return 1
+    if not (same(current.person, person) or is_decider or stale):
         print(f"FAIL [hold] {ident} is {said(current)}: only its holder or the decider ({decider or 'none named'}) "
               "releases a hold that is not stale.\n      Action: ask them.")
         return 1
@@ -529,9 +551,66 @@ def show(root: Path) -> int:
     where = f"from {name}" if name else "local only: no remote"
     print(f"\nHolds in {path.stem}: {held} held, of which {stale} stale ({where}; stale after {days} days without work):")
     print("\n".join(lines) or "  no ready deliverable")
+    left = _empty_starts(root, name, items if isinstance(items, list) else [])
+    if left:
+        print("\nEmpty start branches left — one empty commit each, nothing to lose, and git branch -d refuses them:")
+        print("\n".join(left))
     return 0
 
 
+def _empty_starts(root: Path, name: str | None, items: list) -> list[str]:
+    """What to run for each branch `claim` started that its deliverable no longer needs (#316): its
+    state moved on, or its work landed from other branches — the default branch names it since —
+    or it belongs to another cycle. An id no cycle here knows may be newer than this checkout, and
+    is left alone. Only such a branch: the claim's own subject, one empty commit on the default
+    branch, here or on the remote."""
+    states = {str(item.get("id")).lower(): item.get("state") for item in items if isinstance(item, dict)}
+    known = set()
+    for path in plan.cycle_files(root):
+        listed = (plan.read_front_matter(path)[0] or {}).get("deliverables")
+        known |= {str(item.get("id")).lower() for item in (listed if isinstance(listed, list) else []) if isinstance(item, dict)}
+    base = f"{MIRROR}/base" if name else "refs/heads/main"
+    branches: dict[str, set[str]] = {}
+    for where, prefix, strip in (("remote", f"{MIRROR}/work", 3), ("local", "refs/heads", 2)):
+        if where == "remote" and not name:
+            continue
+        shown = _git(root, "for-each-ref", f"--format=%(refname:lstrip={strip})%09%(refname)%09%(subject)", f"{prefix}/d*").stdout
+        for line in shown.splitlines():
+            branch, ref, subject = (line.split("\t", 2) + ["", ""])[:3]
+            ident = branch.split("-")[0]
+            if (ident not in known or not subject.startswith(f"Start {ident.upper()} — ")
+                    or _git(root, "rev-list", "--count", f"{base}..{ref}").stdout.strip() != "1"
+                    or _git(root, "rev-parse", f"{ref}^{{tree}}").stdout != _git(root, "rev-parse", f"{ref}~1^{{tree}}").stdout):
+                continue
+            if ident in states and plan.one_of(states[ident], TAKEABLE) and not _landed(root, ident, ref, base):
+                continue
+            if ident not in states and _held_in_a_live_cycle(root, ident.upper()):
+                continue
+            branches.setdefault(branch, set()).add(where)
+    return [f"  {branch}  " + "; ".join(([f"git push {name} --delete {branch}"] if "remote" in places else [])
+                                        + ([f"git branch -D {branch}"] if "local" in places else []))
+            for branch, places in sorted(branches.items())]
+
+
+def _landed(root: Path, ident: str, ref: str, base: str) -> bool:
+    """The default branch records the deliverable's delivery since the start branch left it: the
+    `Deliverable:` line of a pull request, or its id in parentheses or opening a subject — a commit
+    merely speaking of it is no delivery, and a live hold's branch is not named for it."""
+    name = ident.upper()
+    pattern = rf"\({name}\)|^Deliverable:[ \t]*{name}([^0-9]|$)|^{name} [—–-]"
+    return bool(_git(root, "log", "-1", "--format=%H", "--extended-regexp", f"--grep={pattern}", f"{ref}~1..{base}").stdout.strip())
+
+
+def _held_in_a_live_cycle(root: Path, ident: str) -> bool:
+    """A hold on the remote this checkout's cycle files do not explain: its id moved on a commit not
+    pulled here. A hold of a closed cycle ended with it."""
+    prefix = f"{MIRROR}/hold" if remote(root) else f"refs/heads/{PREFIX}"
+    closed = {path.stem for path in plan.cycle_files(root)
+              if plan.one_of((plan.read_front_matter(path)[0] or {}).get("status"), plan.OUTCOMES)}
+    cycles = _git(root, "for-each-ref", "--format=%(refname)", f"{prefix}/*/{ident}").stdout.split()
+    return any(ref.split("/")[-2] not in closed and read(root, ref.split("/")[-2], ident).held for ref in cycles)
+
+
 def judge(root: Path, ident: str) -> Hold | str | None:
     """The hold of a deliverable of the accepted cycle for `pr-check`: None when nobody holds
     it, the reason when it cannot be read."""

{napkinstack-0.19.4 → napkinstack-0.20.0}/src/napkinstack/pull_request.py

@@ -8,7 +8,7 @@ Rules:
       head, the stricter
   T2  a verifier named who is not an author of the change, and every scenario row filled
       in: id, given · when · then, a kind (automated, explored, human only — reason), a
-      result (passed, failed, not verified)
+      result (passed, failed, not verified); a | that splits a row is said (D187)
   T3  no scenario passed without its evidence and the commit it was verified on
   T4  evidence at the head commit: an automated scenario is run again, one explored by hand
       is confirmed at the head instead — and at criticality critical, run again like the rest
@@ -22,7 +22,8 @@ Rules:
       sessions, or its person's account (`nstack claim`)
 
 Delivery work: a pull request that changes a module — a folder holding a MANIFEST.yaml —
-beyond its description: its manifest, AGENTS.md, README.md and docs/ (D24). A NapkinStack
+beyond its description: its manifest, AGENTS.md, README.md and docs/ (D24) — or whose manifest
+moves its criticality or its user-facing surface, which is the decider's call (D184). A NapkinStack
 update or a documentation fix is neither delivery work nor a reason for a sheet.
 The out-of-cycle label lifts K1 to K3 and K5, visibly and countably (.nstack/handbook/10-measurement.md).
 
@@ -66,6 +67,8 @@ COLUMNS = ("#", "given · when · then", "kind", "result", "evidence", "commit")
 # Optional seventh column, read only when a scenario needs it: the head commit and what
 # changed since. A sheet no fix has disturbed never has to carry it (T4, D71).
 CONFIRMED = "confirmed"
+CELLS = "cells read"  # how many a row held
+PIPED = "a pipe in a code span"  # a bare |: the table ends the cell there, as GitHub does
 KINDS = {"automated", "explored"}
 RESULTS = {"passed", "failed", "not verified"}
 SECTION = re.compile(r"^##[ \t]+Test sheet[ \t]*$", re.I | re.M)
@@ -99,7 +102,8 @@ def _manifest(text: str) -> dict:
 
 def touched_modules(root: Path, base: str, files: list[str]) -> dict[str, list[dict]]:
     """Folder, relative to the root, to its manifests — at the head and at the base — for
-    every module whose behaviour the files may change, a deleted module included."""
+    every module whose behaviour the files may change, a deleted module included, or whose
+    manifest moved what it owes."""
     manifests = {path.relative_to(root).as_posix(): [_manifest(path.read_text(encoding="utf-8"))]
                  for path in find_manifests(root)}
     listed = _git(root, "ls-tree", "-r", "--name-only", base).stdout.split()
@@ -112,11 +116,19 @@ def touched_modules(root: Path, base: str, files: list[str]) -> dict[str, list[d
     for path, found in sorted(manifests.items()):
         folder = path.removesuffix("/MANIFEST.yaml")
         if any(file.startswith(f"{folder}/") and (not is_description(file[len(folder) + 1:]) or file in relied)
-               for file in files):
+               for file in files) or _owes_differently(found):
             touched[folder] = found
     return touched
 
 
+def _owes_differently(manifests: list[dict]) -> bool:
+    """True when the manifest moved what its module owes (.nstack/handbook/05-workflow.md §7): the
+    rest of a manifest is a description, these two say which checks the module answers to (D184)."""
+    owed = [(module.get("criticality"), module.get("user_facing") is True)
+            for module in (data.get("module") for data in manifests) if isinstance(module, dict)]
+    return len(set(owed)) > 1
+
+
 CONTRACT_PAGE = re.compile(r"(?P<path>.+/(?P<contract>[^/]+)/(?P<version>v\d+))/README\.md")
 
 
@@ -193,7 +205,8 @@ def read_sheet(body: str) -> tuple[str, list[str], list[dict[str, str]]]:
         values = _cells(line)
         if all(value in EMPTY or PLACEHOLDER.fullmatch(value) for value in values[1:]):
             continue  # the template's example row
-        rows.append(dict(zip(header, values + [""] * (len(header) - len(values)))))
+        piped = any("|" in span for span in re.findall(r"`[^`]*`", line.replace("\\|", "")))
+        rows.append({**dict(zip(header, values + [""] * (len(header) - len(values)))), CELLS: len(values), PIPED: piped})
     return verifier, header, rows
 
 
@@ -272,6 +285,18 @@ def _result(cell: str) -> str:
     return re.split(r"[ \t]+[—–-][ \t]+", cell.replace("*", "").strip(), maxsplit=1)[0].lower()
 
 
+def _split(row: dict, width: int) -> bool:
+    """A bare | moved the row's columns. A row that reads well has not moved, whatever it holds:
+    cells beyond the header are ignored, as GitHub ignores them, and backticks prove nothing."""
+    result = _result(row["result"])
+    commit = SHA.fullmatch(row["commit"].strip().strip("`").lower())
+    kind = row["kind"].lower() in KINDS or HUMAN_ONLY.fullmatch(row["kind"])
+    if kind and result in RESULTS and (commit or result == "not verified"):
+        return False
+    late = SHA.fullmatch(row.get(CONFIRMED, "").strip().strip("`").lower())  # one cell after the commit's
+    return bool(row[PIPED] or late or row[CELLS] > width)
+
+
 def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
                 authorship: tuple[set[str], set[str], list[str]] = (set(), set(), []),
                 strict: bool = False, unchanged: Callable[[str], bool] = lambda commit: False) -> list[str]:
@@ -299,6 +324,11 @@ def check_sheet(body: str, head: str, reasons: list[str], fail: Fail,
     human_only, rerun, unconfirmed = [], [], []
     for row in rows:
         ident = row["#"] or "?"
+        if _split(row, len(header)):
+            fail("T2", f"scenario {ident}: a | splits its row ({row[CELLS]} cells, the header {len(header)}): its "
+                       "columns cannot be read.\n      Action: a | in a cell ends it, in a code span too: "
+                       "write it \\|.")
+            continue
         kind = row["kind"]
         reason = HUMAN_ONLY.fullmatch(kind)
         result = _result(row["result"])
@@ -445,8 +475,8 @@ def check_hold(root: Path, body: str, labels: set[str], authorship: tuple[set[st
         return
     fail("K5", f"{ident} is {hold.said(found)}: this pull request comes from none of its sessions "
                f"and not from its person.\n      Action: the holder gives it back (nstack unclaim {ident}), "
-               f"or once stale nstack claim {ident} --take-over. The holder working from another session "
-               f"names it on the hold first: nstack claim {ident} --session <it>.")
+               f"or once stale nstack claim {ident} --take-over. The holder's person moves it to another "
+               f"session on their word: nstack claim {ident} --take-over --person {found.person} --session <it>.")
 
 
 def charter_without_pdr(root: Path, base: str, files: list[str]) -> list[str]: