punchlist 0.6.0__tar.gz

punchlist-0.6.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.coverage
+
+# Scratch output
+temp/
+
+# Virtual environment
+.venv/
+
+# IDE / Tools
+.idea/
+.claude/*
+!.claude/skills/

punchlist-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steven Moret
+
+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.

punchlist-0.6.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: punchlist
+Version: 0.6.0
+Summary: A file-based issue tracker: one markdown file per issue, in the project's own git repo
+Project-URL: Homepage, https://github.com/smoret/punchlist
+Project-URL: Source, https://github.com/smoret/punchlist
+Project-URL: Issues, https://github.com/smoret/punchlist/tree/main/issues
+Author-email: Steven Moret <smoret@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cli,git,issue tracker,markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Bug Tracking
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pylint; extra == 'dev'
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# punchlist
+
+A small, file-based issue tracker for projects worked on by one developer and a crew of agents. Each issue is a markdown file with a short header, stored in the project's own git repo, so closing an issue lands in the same commit as the work that closed it. The `punch` CLI creates, lists, filters, and checks them.
+
+Status: early, and tracking its own work: planned work is in [issues/](https://github.com/smoret/punchlist/tree/main/issues) (`punch list`).
+
+## Install
+
+Needs Python 3.11 or later. `punch history` and `punch changed` read the repo's log, so they also need `git` on the PATH.
+
+```bash
+pipx install punchlist            # or: pip install punchlist
+```
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate            # Windows (bash); .venv\Scripts\activate in cmd
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+punch --version                   # the installed version
+punch init --prefix pl            # write punchlist.json in the current directory
+punch init --prefix pl --line-endings lf   # write every file LF (default: the platform's)
+punch new "Title" --type task --category tooling   # prints the new id
+punch new "Title" --type task --priority high --rank 2.5   # rank orders within a priority
+punch new "Title" --type bug --body-file -         # body from stdin
+punch list                        # every status but closed: id status type priority category title
+punch list --all --label cli --json
+punch list --ready                # open issues whose depends-on issues are all closed
+punch set 7k3 depends-on+=2x9     # 7k3 also waits on 2x9; --blocked lists what's waiting
+punch set 7k3 related+=9qp        # add a non-blocking link, written into both issues
+punch set 7k3 related-=9qp        # remove one link, from both issues
+punch search 'retry|backoff'      # title or body, case-insensitive; takes list's filters
+punch search retry --context 1    # plus each hit's matching lines (file line numbers), 1 line either side
+punch show pl-7k3qx                # or any unique start: pl-7k, 7k3
+punch show 7k3 --json             # header fields plus body
+punch close pl-7k3qx
+punch close 7k3 --comment "Fixed by the retry change." --author claude
+punch comment 7k3 --author claude --body "Tried X; blocked on Y."   # author: flag, $PUNCH_AUTHOR, git
+punch show 7k3 --comments         # the issue, then its comments oldest first
+punch history 7k3                 # from git: each commit that changed it or mentions it
+punch history 7k3 --since 2026-03-01 --json   # or --since <rev>: only what's newer
+punch history 2x9 --tree --diff   # an epic and everything under it; body changes as diffs
+punch changed 2026-03-01 --type bug   # created/closed/reopened/rescoped since; takes list's filters
+punch set 7k3 priority=high labels=cli,docs   # a list's = replaces the WHOLE list; field= removes
+punch set 7k3 labels+=api rank=2               # += adds to a list, -= removes; one op per field per call
+punch serve                       # kanban board at http://127.0.0.1:8314/, a lane per status
+punch serve --author alex --port 0 --no-browser    # any free port; comments signed alex
+punch check                       # validate every issue file
+punch check --references          # also flag ids mentioned in bodies that don't exist
+punch import-md ROADMAP.md --dry-run   # what a markdown checklist would become
+punch import-md ROADMAP.md --add-categories
+```
+
+## Issue format
+
+```markdown
+---
+id: pl-7k3qx
+title: An example issue
+type: task
+status: open
+created: 2026-10-18
+---
+
+Markdown body.
+```
+
+The header is `key: value` lines, values taken verbatim -- no quoting, no YAML. See [docs/design.md](https://github.com/smoret/punchlist/blob/main/docs/design.md) for the full rules.
+
+## Documentation
+
+Links are absolute so they also work on the PyPI page.
+
+| File | Purpose |
+|---|---|
+| [CLAUDE.md](https://github.com/smoret/punchlist/blob/main/CLAUDE.md) | Conventions for agents working in this repo |
+| [issues/](https://github.com/smoret/punchlist/tree/main/issues) | Planned work, as punchlist issues |
+| [docs/design.md](https://github.com/smoret/punchlist/blob/main/docs/design.md) | What was decided and why |
+| [ARCHITECTURE.md](https://github.com/smoret/punchlist/blob/main/ARCHITECTURE.md) | The module map |
+
+## License
+
+MIT; see [LICENSE](https://github.com/smoret/punchlist/blob/main/LICENSE).

punchlist-0.6.0/README.md

@@ -0,0 +1,89 @@
+# punchlist
+
+A small, file-based issue tracker for projects worked on by one developer and a crew of agents. Each issue is a markdown file with a short header, stored in the project's own git repo, so closing an issue lands in the same commit as the work that closed it. The `punch` CLI creates, lists, filters, and checks them.
+
+Status: early, and tracking its own work: planned work is in [issues/](https://github.com/smoret/punchlist/tree/main/issues) (`punch list`).
+
+## Install
+
+Needs Python 3.11 or later. `punch history` and `punch changed` read the repo's log, so they also need `git` on the PATH.
+
+```bash
+pipx install punchlist            # or: pip install punchlist
+```
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate            # Windows (bash); .venv\Scripts\activate in cmd
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+punch --version                   # the installed version
+punch init --prefix pl            # write punchlist.json in the current directory
+punch init --prefix pl --line-endings lf   # write every file LF (default: the platform's)
+punch new "Title" --type task --category tooling   # prints the new id
+punch new "Title" --type task --priority high --rank 2.5   # rank orders within a priority
+punch new "Title" --type bug --body-file -         # body from stdin
+punch list                        # every status but closed: id status type priority category title
+punch list --all --label cli --json
+punch list --ready                # open issues whose depends-on issues are all closed
+punch set 7k3 depends-on+=2x9     # 7k3 also waits on 2x9; --blocked lists what's waiting
+punch set 7k3 related+=9qp        # add a non-blocking link, written into both issues
+punch set 7k3 related-=9qp        # remove one link, from both issues
+punch search 'retry|backoff'      # title or body, case-insensitive; takes list's filters
+punch search retry --context 1    # plus each hit's matching lines (file line numbers), 1 line either side
+punch show pl-7k3qx                # or any unique start: pl-7k, 7k3
+punch show 7k3 --json             # header fields plus body
+punch close pl-7k3qx
+punch close 7k3 --comment "Fixed by the retry change." --author claude
+punch comment 7k3 --author claude --body "Tried X; blocked on Y."   # author: flag, $PUNCH_AUTHOR, git
+punch show 7k3 --comments         # the issue, then its comments oldest first
+punch history 7k3                 # from git: each commit that changed it or mentions it
+punch history 7k3 --since 2026-03-01 --json   # or --since <rev>: only what's newer
+punch history 2x9 --tree --diff   # an epic and everything under it; body changes as diffs
+punch changed 2026-03-01 --type bug   # created/closed/reopened/rescoped since; takes list's filters
+punch set 7k3 priority=high labels=cli,docs   # a list's = replaces the WHOLE list; field= removes
+punch set 7k3 labels+=api rank=2               # += adds to a list, -= removes; one op per field per call
+punch serve                       # kanban board at http://127.0.0.1:8314/, a lane per status
+punch serve --author alex --port 0 --no-browser    # any free port; comments signed alex
+punch check                       # validate every issue file
+punch check --references          # also flag ids mentioned in bodies that don't exist
+punch import-md ROADMAP.md --dry-run   # what a markdown checklist would become
+punch import-md ROADMAP.md --add-categories
+```
+
+## Issue format
+
+```markdown
+---
+id: pl-7k3qx
+title: An example issue
+type: task
+status: open
+created: 2026-10-18
+---
+
+Markdown body.
+```
+
+The header is `key: value` lines, values taken verbatim -- no quoting, no YAML. See [docs/design.md](https://github.com/smoret/punchlist/blob/main/docs/design.md) for the full rules.
+
+## Documentation
+
+Links are absolute so they also work on the PyPI page.
+
+| File | Purpose |
+|---|---|
+| [CLAUDE.md](https://github.com/smoret/punchlist/blob/main/CLAUDE.md) | Conventions for agents working in this repo |
+| [issues/](https://github.com/smoret/punchlist/tree/main/issues) | Planned work, as punchlist issues |
+| [docs/design.md](https://github.com/smoret/punchlist/blob/main/docs/design.md) | What was decided and why |
+| [ARCHITECTURE.md](https://github.com/smoret/punchlist/blob/main/ARCHITECTURE.md) | The module map |
+
+## License
+
+MIT; see [LICENSE](https://github.com/smoret/punchlist/blob/main/LICENSE).

punchlist-0.6.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+# 1.27 is the first hatchling to write the PEP 639 license fields below.
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "punchlist"
+version = "0.6.0"
+description = "A file-based issue tracker: one markdown file per issue, in the project's own git repo"
+authors = [
+    { name = "Steven Moret", email = "smoret@gmail.com" },
+]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+keywords = ["issue tracker", "git", "markdown", "cli", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Bug Tracking",
+]
+
+[project.urls]
+Homepage = "https://github.com/smoret/punchlist"
+Source = "https://github.com/smoret/punchlist"
+Issues = "https://github.com/smoret/punchlist/tree/main/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pylint",
+    "pyright",
+]
+
+[project.scripts]
+punch = "punchlist.cli:main"
+punchlist = "punchlist.cli:main"
+
+[tool.hatch.build.targets.wheel]
+# Everything under the package ships, including static/board.html for `punch serve`.
+packages = ["src/punchlist"]
+
+[tool.hatch.build.targets.sdist]
+# The sdist is for building and testing the package, not the project's issues or docs.
+include = ["src", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Tests import shared helpers as `from helpers import ...`.
+pythonpath = ["tests"]
+
+[tool.pyright]
+extraPaths = ["tests"]
+
+[tool.pylint.basic]
+# http.server dispatches a request to the handler method named do_<METHOD>.
+good-names-rgxs = ["^do_[A-Z]+$"]
+
+[tool.pylint."messages control"]
+# Complexity metrics are refactor-time signals, not defects.
+disable = [
+    "too-many-arguments",
+    "too-many-branches",
+    "too-many-instance-attributes",
+    "too-many-locals",
+    "too-many-positional-arguments",
+    "too-many-return-statements",
+    "too-many-statements",
+    "too-few-public-methods",
+]

punchlist-0.6.0/src/punchlist/__init__.py

@@ -0,0 +1 @@
+"""punchlist: a file-based issue tracker, one markdown file per issue in the project's own repo."""

punchlist-0.6.0/src/punchlist/check.py

@@ -0,0 +1,324 @@
+"""`punch check`: validate every issue file and report every problem, not just the first.
+
+Per file it reports a file outside its bucket and the first parse error (the
+parser stops there), then checks across files: each `id:` matches its
+filename, which with correct buckets also makes ids unique; each `parent`
+names an existing issue file; and no chain of parents loops back on itself.
+With a `depends-on` field: each dependency names an existing issue file, and
+no group of issues depends on each other in a cycle. With a `related` field:
+each related id names another existing issue, which lists this one back.
+Opt-in (config `check_references`, or `punch check --references`): each id
+of this tracker's shape mentioned in a body names an existing issue file.
+Comments: every folder beside an issue file belongs to an existing issue, and
+every file in a `comments/` folder is a valid comment matching its name.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .comment import read_comment
+from .config import DEPENDS_ON, RELATED, Config
+from .errors import PunchError
+from .ids import ALPHABET
+from .issue import Issue, issue_files, placement_error, read_issue
+
+
+def parent_loop(config: Config, issue_id: str, parent: str) -> list[str] | None:
+    """The loop that giving `issue_id` this `parent` would close, as `[a, b, a]`; else None.
+
+    Walks up from `parent` through each ancestor's file. A dangling parent or
+    a loop elsewhere ends the walk; `punch check` reports those.
+    """
+    chain: list[str] = [issue_id]
+    node: str | None = parent
+    while node is not None and node not in chain[1:]:
+        chain.append(node)
+        if node == issue_id:
+            return chain
+        path: Path = config.issue_path(node)
+        if not path.is_file():
+            return None
+        node = read_issue(path, config).text("parent")
+    return None
+
+
+def dependency_loop(config: Config, issue_id: str,
+                    dependencies: list[str]) -> list[str] | None:
+    """The loop giving `issue_id` these dependencies would close, as `[a, b, a]`; else None.
+
+    Searches breadth-first from each dependency through the `depends-on` of
+    each issue file it reaches, so the loop reported is a shortest one. A
+    missing file ends that branch; `punch check` reports it.
+    """
+    previous: dict[str, str] = {}
+    queue: list[str] = []
+    for dependency in dependencies:
+        if dependency == issue_id:
+            return [issue_id, issue_id]
+        if dependency not in previous:
+            previous[dependency] = issue_id
+            queue.append(dependency)
+    while queue:
+        node: str = queue.pop(0)
+        path: Path = config.issue_path(node)
+        if not path.is_file():
+            continue
+        for successor in read_issue(path, config).items(DEPENDS_ON):
+            if successor == issue_id:
+                return _loop_path(previous, issue_id, node)
+            if successor not in previous:
+                previous[successor] = node
+                queue.append(successor)
+    return None
+
+
+def _loop_path(previous: dict[str, str], start: str, last: str) -> list[str]:
+    """`[start, ..., last, start]` from the breadth-first `previous` links."""
+    path: list[str] = [last]
+    while path[0] != start:
+        path.insert(0, previous[path[0]])
+    return [*path, start]
+
+
+def check_issues(config: Config,
+                 references: bool | None = None) -> tuple[int, list[PunchError]]:
+    """The number of issue files, and every problem found in them, in file and line order.
+
+    `references` turns the body reference check on or off; None follows the
+    config's `check_references`.
+    """
+    if references is None:
+        references = config.check_references
+    paths: list[Path] = issue_files(config)
+    # Parents are checked against filenames, so a corrupt parent file is one
+    # problem rather than one per child.
+    stems: set[str] = {path.stem for path in paths}
+    problems: list[PunchError] = []
+    parsed: dict[str, Issue] = {}
+    for path in paths:
+        placement: PunchError | None = placement_error(path, config)
+        if placement is not None:
+            problems.append(placement)
+        try:
+            issue: Issue = read_issue(path, config)
+        except PunchError as exc:
+            problems.append(exc)
+            continue
+        parsed[path.stem] = issue
+        if issue.id != path.stem:
+            problems.append(PunchError(
+                f"id {issue.id!r} does not match the filename", path, issue.lines["id"]
+            ))
+        parent: str | None = issue.text("parent")
+        if parent is not None and parent not in stems:
+            problems.append(PunchError(
+                f"parent {parent!r} does not exist", path, issue.lines["parent"]
+            ))
+        if config.has_links:
+            for dependency in issue.items(DEPENDS_ON):
+                if dependency not in stems:
+                    problems.append(PunchError(
+                        f"{DEPENDS_ON} {dependency!r} does not exist", path,
+                        issue.lines[DEPENDS_ON],
+                    ))
+        if config.has_related:
+            for other in issue.items(RELATED):
+                if other == issue.id:
+                    problems.append(PunchError(
+                        f"{RELATED} lists the issue itself", path, issue.lines[RELATED]
+                    ))
+                elif other not in stems:
+                    problems.append(PunchError(
+                        f"{RELATED} {other!r} does not exist", path, issue.lines[RELATED]
+                    ))
+        if references:
+            problems.extend(_dangling_references(config, issue, stems))
+    problems.extend(_parent_loops(parsed))
+    if config.has_links:
+        problems.extend(_dependency_loops(parsed))
+    if config.has_related:
+        problems.extend(_one_sided_related(parsed))
+    problems.extend(_comment_problems(config))
+    problems.sort(key=lambda p: (p.path or Path(), p.line or 0))
+    return len(paths), problems
+
+
+def _comment_problems(config: Config) -> list[PunchError]:
+    """Problems with comment folders and files.
+
+    A folder beside an issue file (`issues/<bucket>/<id>/`) must belong to an
+    existing, correctly placed issue; every entry of its `comments/` folder
+    must be a comment file whose header parses and matches its name.
+    """
+    problems: list[PunchError] = []
+    if not config.issues_path.is_dir():
+        return problems
+    for folder in sorted(config.issues_path.glob("*/*/")):
+        try:
+            expected: Path = config.issue_path(folder.name).with_suffix("")
+        except PunchError:
+            expected = Path()
+        if folder != expected or not (folder.parent / f"{folder.name}.md").is_file():
+            problems.append(PunchError(
+                f"folder for issue {folder.name!r}, which does not exist here", folder
+            ))
+            continue
+        comments: Path = folder / "comments"
+        if not comments.is_dir():
+            continue
+        for path in sorted(comments.iterdir()):
+            if not path.is_file() or path.suffix != ".md":
+                problems.append(PunchError(
+                    "not a comment file (expected <time>-<author>.md)", path
+                ))
+                continue
+            try:
+                read_comment(path)
+            except PunchError as exc:
+                problems.append(exc)
+    return problems
+
+
+def _dangling_references(config: Config, issue: Issue, stems: set[str]) -> list[PunchError]:
+    """Each body mention of this tracker's id shape that names no issue file, once per line.
+
+    Only `<prefix>-` plus `id_length` id-alphabet characters, on word
+    boundaries, counts, so another tracker's ids (another prefix) never match.
+    """
+    pattern: re.Pattern[str] = re.compile(
+        rf"\b{re.escape(config.prefix)}-[{ALPHABET}]{{{config.id_length}}}\b"
+    )
+    problems: list[PunchError] = []
+    for offset, line in enumerate(issue.body.split("\n")):
+        for mention in dict.fromkeys(pattern.findall(line)):
+            if mention not in stems:
+                problems.append(PunchError(
+                    f"reference to {mention}, which does not exist",
+                    issue.path, issue.body_line + offset,
+                ))
+    return problems
+
+
+def _parent_loops(issues: dict[str, Issue]) -> list[PunchError]:
+    """One problem per parent loop, at the `parent:` line of the loop's lowest id."""
+    parents: dict[str, str] = {}
+    for stem, issue in issues.items():
+        parent: str | None = issue.text("parent")
+        if parent is not None:
+            parents[stem] = parent
+    problems: list[PunchError] = []
+    done: set[str] = set()
+    for start in sorted(parents):
+        chain: list[str] = []
+        node: str | None = start
+        while node is not None and node not in done and node not in chain:
+            chain.append(node)
+            node = parents.get(node)
+        if node is not None and node in chain:
+            loop: list[str] = chain[chain.index(node):]
+            first: int = loop.index(min(loop))
+            loop = loop[first:] + loop[:first]
+            head: Issue = issues[loop[0]]
+            problems.append(PunchError(
+                f"parent loop: {' -> '.join([*loop, loop[0]])}", head.path, head.lines["parent"]
+            ))
+        done.update(chain)
+    return problems
+
+
+def _one_sided_related(issues: dict[str, Issue]) -> list[PunchError]:
+    """A related link the other issue doesn't list back, on the side that has it.
+
+    `set` and `new` write both sides, so this comes from a hand edit or a merge
+    that kept one file's side. A partner that didn't parse is skipped; its own
+    problem is already reported.
+    """
+    problems: list[PunchError] = []
+    for stem, issue in issues.items():
+        for other in issue.items(RELATED):
+            if other != stem and other in issues and stem not in issues[other].items(RELATED):
+                problems.append(PunchError(
+                    f"{RELATED} {other!r} does not list {stem!r} back", issue.path,
+                    issue.lines[RELATED],
+                ))
+    return problems
+
+
+def _dependency_loops(issues: dict[str, Issue]) -> list[PunchError]:
+    """One problem per group of issues that depend on each other in a cycle.
+
+    Each strongly connected component with a cycle is reported once, at the
+    `depends-on` line of its lowest id, naming a shortest loop through it.
+    """
+    graph: dict[str, list[str]] = {
+        stem: [d for d in issue.items(DEPENDS_ON) if d in issues]
+        for stem, issue in issues.items()
+    }
+    problems: list[PunchError] = []
+    for component in _components(graph):
+        start: str = min(component)
+        if len(component) == 1 and start not in graph[start]:
+            continue
+        members: set[str] = set(component)
+        previous: dict[str, str] = {}
+        queue: list[str] = [start]
+        last: str | None = None
+        while queue and last is None:
+            node: str = queue.pop(0)
+            for successor in sorted(graph[node]):
+                if successor == start:
+                    last = node
+                    break
+                if successor in members and successor not in previous:
+                    previous[successor] = node
+                    queue.append(successor)
+        assert last is not None  # a component with a cycle has a loop through any member
+        head: Issue = issues[start]
+        loop: list[str] = _loop_path(previous, start, last)
+        problems.append(PunchError(
+            f"dependency loop: {' -> '.join(loop)}", head.path, head.lines[DEPENDS_ON]
+        ))
+    return problems
+
+
+def _components(graph: dict[str, list[str]]) -> list[list[str]]:
+    """Strongly connected components of `graph` (Tarjan's algorithm, iterative)."""
+    index: dict[str, int] = {}
+    low: dict[str, int] = {}
+    stack: list[str] = []
+    on_stack: set[str] = set()
+    components: list[list[str]] = []
+    for root in sorted(graph):
+        if root in index:
+            continue
+        work: list[tuple[str, int]] = [(root, 0)]
+        while work:
+            node, position = work[-1]
+            if position == 0:
+                index[node] = low[node] = len(index)
+                stack.append(node)
+                on_stack.add(node)
+            successors: list[str] = graph[node]
+            if position < len(successors):
+                work[-1] = (node, position + 1)
+                successor: str = successors[position]
+                if successor not in index:
+                    work.append((successor, 0))
+                elif successor in on_stack:
+                    low[node] = min(low[node], index[successor])
+                continue
+            work.pop()
+            if work:
+                low[work[-1][0]] = min(low[work[-1][0]], low[node])
+            if low[node] == index[node]:
+                component: list[str] = []
+                while True:
+                    member: str = stack.pop()
+                    on_stack.discard(member)
+                    component.append(member)
+                    if member == node:
+                        break
+                components.append(component)
+    return components