blinkered 0.0.1__tar.gz

blinkered-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:  # manual run publishes to TestPyPI
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ['3.11', '3.12', '3.13']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e '.[dev]'
+      - run: pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Check tag matches version
+        if: github.event_name == 'release'
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "tag $GITHUB_REF_NAME does not match version $version"
+            exit 1
+          fi
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: ${{ github.event_name == 'release' && 'pypi' || 'testpypi' }}
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ github.event_name == 'release' && 'https://upload.pypi.org/legacy/' || 'https://test.pypi.org/legacy/' }}
+          skip-existing: ${{ github.event_name != 'release' }}  # TestPyPI reruns of the same version

blinkered-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.DS_Store

blinkered-0.0.1/LICENSE

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

blinkered-0.0.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: blinkered
+Version: 0.0.1
+Summary: Work on one node of a repository while the working tree shows only its dependency closure.
+Project-URL: Homepage, https://github.com/louisantonini/blinkered
+Project-URL: Repository, https://github.com/louisantonini/blinkered
+Project-URL: Issues, https://github.com/louisantonini/blinkered/issues
+Author: Louis Antonini
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dependency-graph,git,monorepo,sparse-checkout,workspace
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# blinkered
+
+Work on one node of a repository while the working tree shows only its dependency closure.
+
+Each node is a directory with a `blinkered.toml` manifest declaring free-form tags and edges to other nodes. `blinkered workspace <node>` narrows the working tree, through git's cone-mode sparse checkout, to that node and everything it depends on. The graph can grow arbitrarily large and deep while each piece of work stays small.
+
+## Requirements
+
+Python 3.11 or later and git 2.35 or later. Tested with git 2.50.
+
+## Usage
+
+```toml
+# blinkered.toml at the repository root: configuration
+always = ["lib"]
+
+[plugins]
+python_imports = true
+```
+
+```toml
+# src/nodes/report/blinkered.toml: a node
+tags = ["transform"]
+
+[edges]
+reads = ["selection"]
+joins = ["lookup"]
+```
+
+```sh
+blinkered check               # validate manifests, graph and layout
+blinkered closure report      # report and its transitive dependencies
+blinkered workspace report    # narrow the working tree to that closure
+blinkered status              # compare the view with the closure after pulls or edits
+blinkered workspace           # resync the stored focus
+blinkered workspace --all     # restore the full working tree
+```
+
+See [SPEC.md](https://github.com/louisantonini/blinkered/blob/main/SPEC.md) for the model, layout rules and full behaviour.
+
+## Scope
+
+blinkered manages what the working tree shows. It does not run tests, install git hooks, use worktrees, cache data or execute nodes.
+
+## Caveats
+
+- `workspace --force` deletes ignored files inside nodes leaving the view; git removes them and they cannot be recovered. Without `--force`, blinkered refuses and lists them.
+- Merge conflicts in files outside the view appear on disk; resolve them with `git add --sparse`, commit, then `blinkered workspace`.
+- Package `__init__.py` files must not import sibling nodes, or every import fails in a partial tree.
+- Nodes cannot nest, and directories that group nodes may only hold a `README.md` by default (`grouping_allow`); other files there would be visible in every view.
+
+## Development
+
+```sh
+pip install -e '.[dev]'
+pytest -q
+```

blinkered-0.0.1/README.md

@@ -0,0 +1,57 @@
+# blinkered
+
+Work on one node of a repository while the working tree shows only its dependency closure.
+
+Each node is a directory with a `blinkered.toml` manifest declaring free-form tags and edges to other nodes. `blinkered workspace <node>` narrows the working tree, through git's cone-mode sparse checkout, to that node and everything it depends on. The graph can grow arbitrarily large and deep while each piece of work stays small.
+
+## Requirements
+
+Python 3.11 or later and git 2.35 or later. Tested with git 2.50.
+
+## Usage
+
+```toml
+# blinkered.toml at the repository root: configuration
+always = ["lib"]
+
+[plugins]
+python_imports = true
+```
+
+```toml
+# src/nodes/report/blinkered.toml: a node
+tags = ["transform"]
+
+[edges]
+reads = ["selection"]
+joins = ["lookup"]
+```
+
+```sh
+blinkered check               # validate manifests, graph and layout
+blinkered closure report      # report and its transitive dependencies
+blinkered workspace report    # narrow the working tree to that closure
+blinkered status              # compare the view with the closure after pulls or edits
+blinkered workspace           # resync the stored focus
+blinkered workspace --all     # restore the full working tree
+```
+
+See [SPEC.md](https://github.com/louisantonini/blinkered/blob/main/SPEC.md) for the model, layout rules and full behaviour.
+
+## Scope
+
+blinkered manages what the working tree shows. It does not run tests, install git hooks, use worktrees, cache data or execute nodes.
+
+## Caveats
+
+- `workspace --force` deletes ignored files inside nodes leaving the view; git removes them and they cannot be recovered. Without `--force`, blinkered refuses and lists them.
+- Merge conflicts in files outside the view appear on disk; resolve them with `git add --sparse`, commit, then `blinkered workspace`.
+- Package `__init__.py` files must not import sibling nodes, or every import fails in a partial tree.
+- Nodes cannot nest, and directories that group nodes may only hold a `README.md` by default (`grouping_allow`); other files there would be visible in every view.
+
+## Development
+
+```sh
+pip install -e '.[dev]'
+pytest -q
+```

blinkered-0.0.1/SPEC.md

@@ -0,0 +1,90 @@
+# blinkered
+
+Work on one node of a repository while the working tree shows only its dependency closure. The graph may grow arbitrarily large and deep.
+
+Standalone command-line tool, installed outside the repositories it manages (`pipx install blinkered`, `uv tool install blinkered`). Language-neutral core; language-specific checks are optional plugins.
+
+## Model
+
+- **Node**: a directory other than the repository root containing `blinkered.toml`. Name = directory name, unique across the repository.
+- **Tags**: free labels on a node.
+- **Edges**: directed links to other nodes, with free kinds.
+- No built-in semantics. Tags and edge kinds may appear or disappear as needed; their meaning belongs to the managed repository.
+
+```toml
+# blinkered.toml (in a node directory)
+tags = ["transform"]
+
+[edges]
+reads = ["selection"]
+joins = ["lookup"]
+uses = ["utils"]
+```
+
+- Manifests are read from the working tree when present, otherwise from the index, so nodes outside the view remain part of the graph.
+- Uncommitted manifest edits take effect immediately.
+
+## Layout rules
+
+- **No nesting**: no `blinkered.toml` below another node's directory. Cone mode includes directories recursively, so a parent would pull in its children, and a child would expose its parent's files.
+- **Grouping directories**: strict ancestors of node directories that are not nodes, excluding the repository root. They hold no files except an allowlist (default `README.md`); cone mode checks out files directly inside every ancestor of an included directory, so such files are visible in every view below them.
+- **Root**: files at the repository root are always visible. It holds globally visible files (configuration, README) and should stay small.
+- **Non-node directories**: tracked directories containing no nodes disappear from every view unless they become nodes or are listed in `always`.
+
+## Configuration
+
+`blinkered.toml` at the repository root: repository configuration, not a node manifest. Its presence marks the repository as managed; it is always visible.
+
+```toml
+always = ["lib"]                  # directories included in every view
+grouping_allow = ["README.md"]    # files allowed in grouping directories
+
+[plugins]
+python_imports = true             # code imports must be covered by declared edges
+```
+
+## Commands
+
+| Command | Behaviour |
+| --- | --- |
+| `blinkered closure <node> [--via kinds] [--tag tags]` | Node and its transitive dependencies. |
+| `blinkered workspace [<node>]` | Store focus; set cone-mode sparse checkout to the closure's directories plus `always`. Without `<node>`, resync the stored focus. |
+| `blinkered workspace --all` | Disable sparse checkout; clear focus. |
+| `blinkered status` | Compare view with closure of the stored focus: missing, extra, leaks. Read-only; non-zero exit if out of sync. |
+| `blinkered new <node>` | Create directory and `blinkered.toml`; add it to the current view. Refuses inside a node. |
+| `blinkered tags` | List tags and edge kinds in use, with counts. |
+| `blinkered check` | Report manifest errors, unknown targets, cycles, layout-rule violations and plugin findings. |
+
+## Behaviour
+
+- **Closure**: start at the node, follow outgoing edges to their targets, repeat until no new node is reached. Manifests come from the working tree or the index, so the result is independent of the current view. Output: one node per line. `--via` follows only the listed edge kinds; `--tag` filters the output to nodes with those tags without stopping traversal. Read-only; `workspace` uses the same computation.
+- **State**: the focus node name only, stored under `.git/blinkered/`. Patterns are always recomputed from manifests.
+- **Guard**: `workspace` and `new` run `check` first and refuse on layout violations.
+- **Clean-state rule**: before narrowing, list modified, staged, untracked or ignored paths leaving the view; refuse unless resolved, or `--force` for ignored-only paths.
+- **Leaks**: files git keeps on disk outside the cone (modifications, untracked, conflicts) are reported by `status`, not hidden.
+- **Remote**: pulls update content within the view but not the pattern set; `status` detects drift, `workspace` resyncs.
+
+## Git behaviour (git 2.50.1, Python 3.12, pytest 9)
+
+Observed behaviour the guards are built on.
+
+Narrowing (`git sparse-checkout set`) always exits 0; the tool must do its own checks.
+
+| Path leaving the view | Git behaviour |
+| --- | --- |
+| Tracked, clean | Removed from disk. |
+| Tracked, modified | Kept on disk with a warning; remains visible. |
+| New file, staged | Removed from disk; content kept in the index; returns when widened. |
+| Untracked | Kept on disk with a warning; remains visible. |
+| Ignored, in a directory with no untracked files | Deleted without warning; not recoverable. |
+| Ignored, next to untracked files | Kept. |
+| Ignored, in a directory that never had tracked files | Kept. |
+
+- Manifests outside the view are readable via `git ls-files` and `git show :path` (also `HEAD:path`), with or without sparse index. With sparse index, `ls-files` expands the index and prints hints.
+- Pull: new files in included directories appear; new node directories do not; patterns unchanged.
+- Conflict outside the view: file materialises; plain `git add` refuses; resolve with `git add --sparse`, commit, `git sparse-checkout reapply`.
+- Python: nodes in view import normally; importing a node outside the view raises `ModuleNotFoundError`, including undeclared transitive imports.
+- A package `__init__.py` importing its sibling nodes breaks every import in a partial tree. Node `__init__.py` files must not import siblings.
+- pytest: whole-tree runs collect only tests in view; an explicit path outside the view errors with "file or directory not found".
+
+Consequences for the clean-state rule: refuse narrowing when any modified, staged, untracked or ignored path would leave the view; ignored paths are the only case of silent loss.

blinkered-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "blinkered"
+version = "0.0.1"
+description = "Work on one node of a repository while the working tree shows only its dependency closure."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Louis Antonini" }]
+keywords = ["git", "sparse-checkout", "monorepo", "dependency-graph", "workspace"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/louisantonini/blinkered"
+Repository = "https://github.com/louisantonini/blinkered"
+Issues = "https://github.com/louisantonini/blinkered/issues"
+
+[project.scripts]
+blinkered = "blinkered.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest"]

blinkered-0.0.1/src/blinkered/__init__.py

@@ -0,0 +1 @@
+"""Work on one node of a repository while the working tree shows only its dependency closure."""

blinkered-0.0.1/src/blinkered/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

blinkered-0.0.1/src/blinkered/checks.py

@@ -0,0 +1,91 @@
+"""Validation of manifests, layout and working-tree state."""
+import posixpath
+from pathlib import Path
+
+from . import git
+from .config import Config
+from .findings import Finding
+from .graph import cycles
+from .manifest import Node
+
+
+def ancestors(path: str) -> list[str]:
+    """Strict ancestor directories of `path`, excluding the repository root."""
+    parts = path.strip('/').split('/')
+    return ['/'.join(parts[:i]) for i in range(1, len(parts))]
+
+
+def in_view(path: str, keep: list[str]) -> bool:
+    """Whether cone mode checks out `path` (directories end with `/`) when the view is `keep`."""
+    is_directory = path.endswith('/')
+    path = path.rstrip('/')
+    if any(path == d or path.startswith(d + '/') for d in keep):
+        return True
+    parents = {a for d in keep for a in ancestors(d)}
+    if is_directory:
+        return path in parents
+    parent = posixpath.dirname(path)
+    return parent == '' or parent in parents
+
+
+def check(root: Path, config: Config, nodes: dict[str, Node],
+          errors: list[Finding]) -> list[Finding]:
+    """Manifest errors, unknown targets, cycles, layout-rule violations and plugin findings."""
+    findings = list(errors)
+    for node in nodes.values():
+        for kind, targets in node.edges.items():
+            findings += [Finding('edge', node.directory, f'{kind} → unknown node {target}')
+                         for target in targets if target not in nodes]
+    findings += [Finding('cycle', nodes[cycle[0]].directory, ' → '.join(cycle))
+                 for cycle in cycles(nodes)]
+    findings += layout(root, config, nodes)
+    if config.plugins.get('python_imports'):
+        from .plugins import python_imports
+        findings += python_imports.check(root, nodes)
+    return findings
+
+
+def layout(root: Path, config: Config, nodes: dict[str, Node]) -> list[Finding]:
+    """Nested nodes and files in grouping directories outside `grouping_allow`."""
+    directories = {node.directory for node in nodes.values()}
+    findings = [Finding('layout', node.directory, f'nested inside node {a}')
+                for node in nodes.values() for a in ancestors(node.directory)
+                if a in directories]
+    grouping = {a for d in directories for a in ancestors(d)} - directories
+    files = set(git.tracked_paths(root)) | set(git.untracked_paths(root))
+    findings += [Finding('layout', path, 'file in grouping directory')
+                 for path in sorted(files)
+                 if posixpath.dirname(path) in grouping
+                 and posixpath.basename(path) not in config.grouping_allow]
+    return findings
+
+
+def leaving(root: Path, keep: list[str]) -> tuple[list[Finding], list[Finding]]:
+    """Paths that would leave a view limited to `keep`: (work at risk, ignored files git may delete).
+
+    Ignored files are at risk only inside a directory outside the view that contains tracked files.
+    """
+    tracked = git.tracked_paths(root)
+    work, ignored = [], []
+    for code, path in git.status(root):
+        if in_view(path, keep):
+            continue
+        if code == '!!':
+            outside = [a for a in ancestors(path.rstrip('/') + '/x') if not in_view(a + '/', keep)]
+            if any(t.startswith(a + '/') for a in outside for t in tracked):
+                ignored.append(Finding('ignored', path, 'would be deleted'))
+        elif code == '??':
+            work.append(Finding('untracked', path, 'would stay on disk outside the view'))
+        elif 'U' in code or code in ('AA', 'DD'):
+            work.append(Finding('conflict', path, 'unresolved'))
+        elif code[0] != ' ':
+            work.append(Finding('staged', path, 'staged change outside the view'))
+        else:
+            work.append(Finding('modified', path, 'would stay on disk outside the view'))
+    return work, ignored
+
+
+def leaks(root: Path, keep: list[str]) -> list[Finding]:
+    """Non-ignored paths on disk outside the current view."""
+    return [Finding('leak', path, code.strip() or code) for code, path in git.status(root)
+            if code != '!!' and not in_view(path, keep) and (root / path).exists()]

blinkered-0.0.1/src/blinkered/cli.py

@@ -0,0 +1,174 @@
+"""Command-line entry point."""
+import argparse
+import posixpath
+import sys
+from collections import Counter
+from pathlib import Path
+
+import blinkered
+from . import checks, config as configuration, git, state
+from .config import FILENAME
+from .graph import closure
+
+
+def csv(value: str) -> list[str]:
+    return [item for item in value.split(',') if item]
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog='blinkered', description=blinkered.__doc__)
+    commands = root.add_subparsers(dest='command', required=True)
+
+    closure = commands.add_parser('closure', help='node and its transitive dependencies')
+    closure.add_argument('node')
+    closure.add_argument('--via', type=csv, help='edge kinds to follow, comma-separated')
+    closure.add_argument('--tag', type=csv, help='output only nodes with these tags')
+
+    workspace = commands.add_parser('workspace', help='narrow the working tree to a closure')
+    workspace.add_argument('node', nargs='?', help='new focus; omit to resync the stored focus')
+    workspace.add_argument('--all', action='store_true', help='restore the full working tree')
+    workspace.add_argument('--force', action='store_true', help='allow ignored-only paths to leave the view')
+
+    commands.add_parser('status', help='compare the view with the closure of the focus')
+
+    new = commands.add_parser('new', help='create a node and add it to the view')
+    new.add_argument('directory')
+
+    commands.add_parser('tags', help='tags and edge kinds in use, with counts')
+    commands.add_parser('check', help='manifest, graph and layout validation')
+    return root
+
+
+class Failure(Exception):
+    pass
+
+
+def report(title, findings):
+    print(title, file=sys.stderr)
+    for finding in findings:
+        print(f'  {finding}', file=sys.stderr)
+
+
+def view(nodes, config, focus):
+    if focus not in nodes:
+        raise Failure(f'unknown node: {focus}')
+    return sorted({nodes[name].directory for name in closure(nodes, focus)} | set(config.always))
+
+
+def run_closure(root, config, nodes, errors, args):
+    if args.node not in nodes:
+        raise Failure(f'unknown node: {args.node}')
+    print('\n'.join(closure(nodes, args.node, via=args.via, tags=args.tag)))
+    return 0
+
+
+def run_workspace(root, config, nodes, errors, args):
+    if args.all:
+        if git.sparse_patterns(root) is not None:
+            git.sparse_disable(root)
+        state.write_focus(root, None)
+        print('full working tree')
+        return 0
+    focus = args.node or state.read_focus(root)
+    if focus is None:
+        raise Failure('no focus: give a node')
+    blocking = list(errors) + checks.layout(root, config, nodes)
+    if blocking:
+        report('refusing: fix these first (blinkered check)', blocking)
+        return 1
+    keep = view(nodes, config, focus)
+    work, ignored = checks.leaving(root, keep)
+    if work or (ignored and not args.force):
+        report('refusing: these paths would leave the view', work + ignored)
+        if ignored and not work:
+            print('ignored files only: rerun with --force to delete them', file=sys.stderr)
+        return 1
+    git.sparse_set(root, keep)
+    state.write_focus(root, focus)
+    print(f'focus: {focus}')
+    print('\n'.join(f'  {d}' for d in keep))
+    return 0
+
+
+def run_status(root, config, nodes, errors, args):
+    focus = state.read_focus(root)
+    current = git.sparse_patterns(root)
+    if focus is None:
+        print('focus: none')
+        print('view: full' if current is None else f'view: sparse, {len(current)} directories')
+        return 0 if current is None else 1
+    expected = set(view(nodes, config, focus))
+    current = set(current or [])
+    missing, extra = sorted(expected - current), sorted(current - expected)
+    leaked = checks.leaks(root, sorted(current)) if current else []
+    print(f'focus: {focus}')
+    for label, items in (('missing', missing), ('extra', extra)):
+        for item in items:
+            print(f'{label}: {item}')
+    for finding in leaked:
+        print(f'leak: {finding.path} ({finding.message})')
+    if missing or extra or leaked:
+        print('→ run `blinkered workspace` to resync' if missing or extra else '→ resolve leaks')
+        return 1
+    print('in sync')
+    return 0
+
+
+def run_new(root, config, nodes, errors, args):
+    directory = (Path.cwd() / args.directory).resolve().relative_to(root.resolve()).as_posix()
+    name = posixpath.basename(directory)
+    if directory in ('', '.'):
+        raise Failure('the repository root cannot be a node')
+    if name in nodes:
+        raise Failure(f'node {name} already exists at {nodes[name].directory}')
+    for node in nodes.values():
+        if directory.startswith(node.directory + '/'):
+            raise Failure(f'inside node {node.name}')
+        if node.directory.startswith(directory + '/'):
+            raise Failure(f'would contain node {node.name}')
+    path = root / directory
+    path.mkdir(parents=True, exist_ok=True)
+    (path / FILENAME).write_text('tags = []\n\n[edges]\n')
+    if git.sparse_patterns(root) is not None:
+        git.sparse_add(root, [directory])
+    print(f'created {directory}/{FILENAME}')
+    return 0
+
+
+def run_tags(root, config, nodes, errors, args):
+    tags = Counter(tag for node in nodes.values() for tag in node.tags)
+    kinds = Counter(kind for node in nodes.values() for kind, targets in node.edges.items()
+                    for _ in targets)
+    for title, counts in (('tags', tags), ('edge kinds', kinds)):
+        print(f'{title}:')
+        for item, count in counts.most_common():
+            print(f'  {count:>4}  {item}')
+    return 0
+
+
+def run_check(root, config, nodes, errors, args):
+    findings = checks.check(root, config, nodes, errors)
+    for finding in findings:
+        print(finding)
+    print(f'{len(nodes)} nodes, {len(findings)} findings')
+    return 1 if findings else 0
+
+
+COMMANDS = {'closure': run_closure, 'workspace': run_workspace, 'status': run_status,
+            'new': run_new, 'tags': run_tags, 'check': run_check}
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    if args.command == 'workspace' and args.all and args.node:
+        parser().error('workspace: give a node or --all, not both')
+    try:
+        git.require_version(Path.cwd())
+        root = git.repo_root(Path.cwd())
+        config = configuration.load(root)
+        from .manifest import discover
+        nodes, errors = discover(root)
+        return COMMANDS[args.command](root, config, nodes, errors, args)
+    except (Failure, git.GitError, configuration.NotManaged, ValueError) as error:
+        print(f'blinkered: {error}', file=sys.stderr)
+        return 2

blinkered-0.0.1/src/blinkered/config.py

@@ -0,0 +1,31 @@
+"""Repository configuration: `blinkered.toml` at the repository root."""
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+FILENAME = 'blinkered.toml'
+
+
+class NotManaged(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Config:
+    always: tuple[str, ...] = ()
+    grouping_allow: tuple[str, ...] = ('README.md',)
+    plugins: dict[str, bool] = field(default_factory=dict)
+
+
+def load(root: Path) -> Config:
+    """Read the root configuration; its absence means the repository is not managed."""
+    path = root / FILENAME
+    if not path.is_file():
+        raise NotManaged(f'no {FILENAME} at {root}')
+    data = tomllib.loads(path.read_text())
+    unknown = set(data) - {'always', 'grouping_allow', 'plugins'}
+    if unknown:
+        raise ValueError(f'{FILENAME}: unknown keys {sorted(unknown)}')
+    return Config(always=tuple(item.strip('/') for item in data.get('always', ())),
+                  grouping_allow=tuple(data.get('grouping_allow', Config.grouping_allow)),
+                  plugins=dict(data.get('plugins', {})))

blinkered-0.0.1/src/blinkered/findings.py

@@ -0,0 +1,12 @@
+"""Problems reported by checks."""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Finding:
+    kind: str
+    path: str
+    message: str
+
+    def __str__(self) -> str:
+        return f'{self.kind}: {self.path}: {self.message}'