blinkered 0.0.1__py3-none-any.whl

blinkered/__init__.py

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

blinkered/__main__.py

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

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/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/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/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}'

blinkered/git.py

@@ -0,0 +1,99 @@
+"""Thin wrappers around the git commands blinkered relies on."""
+import subprocess
+from pathlib import Path
+
+
+MINIMUM_VERSION = (2, 35)
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def run(root: Path, *args: str, check: bool = True) -> str:
+    result = subprocess.run(['git', '-C', str(root), '-c', 'advice.sparseIndexExpanded=false',
+                             *args], capture_output=True, text=True)
+    if check and result.returncode:
+        raise GitError(result.stderr.strip() or f'git {args[0]} failed')
+    return result.stdout
+
+
+def parse_version(text: str) -> tuple[int, ...]:
+    """(major, minor, patch) from `git version` output, e.g. `git version 2.50.1 (Apple Git-155)`."""
+    number = text.split()[2]
+    return tuple(int(part) for part in number.split('.')[:3] if part.isdigit())
+
+
+def require_version(root: Path) -> None:
+    version = parse_version(run(root, 'version'))
+    if version < MINIMUM_VERSION:
+        found = '.'.join(map(str, version))
+        needed = '.'.join(map(str, MINIMUM_VERSION))
+        raise GitError(f'git {needed} or later required, found {found}')
+
+
+def repo_root(start: Path) -> Path:
+    """Top-level directory of the repository containing `start`."""
+    return Path(run(start, 'rev-parse', '--show-toplevel').strip())
+
+
+def git_dir(root: Path) -> Path:
+    """The repository's `.git` directory."""
+    return Path(run(root, 'rev-parse', '--absolute-git-dir').strip())
+
+
+def tracked_paths(root: Path) -> list[str]:
+    """All paths in the index, including those outside the sparse view."""
+    return [path for path in run(root, 'ls-files', '-z').split('\0') if path]
+
+
+def untracked_paths(root: Path) -> list[str]:
+    """Untracked, non-ignored files present in the working tree."""
+    return [path for path in run(root, 'ls-files', '-z', '--others', '--exclude-standard')
+            .split('\0') if path]
+
+
+def read_file(root: Path, path: str) -> str:
+    """Working-tree content when present, otherwise the index version."""
+    file = root / path
+    if file.is_file():
+        return file.read_text()
+    return run(root, 'show', f':{path}')
+
+
+def status(root: Path) -> list[tuple[str, str]]:
+    """(code, path) pairs from `git status --porcelain --ignored`; directories end with `/`."""
+    fields = run(root, 'status', '--porcelain=v1', '-z', '--ignored',
+                 '--untracked-files=all').split('\0')
+    entries, i = [], 0
+    while i < len(fields):
+        field = fields[i]
+        i += 1
+        if not field:
+            continue
+        code, path = field[:2], field[3:]
+        entries.append((code, path))
+        if code[0] in 'RC':
+            i += 1  # the original path of a rename or copy follows
+    return entries
+
+
+def sparse_patterns(root: Path) -> list[str] | None:
+    """Current cone-mode directories, or None when sparse checkout is disabled."""
+    if run(root, 'config', '--bool', 'core.sparseCheckout', check=False).strip() != 'true':
+        return None
+    return run(root, 'sparse-checkout', 'list').splitlines()
+
+
+def sparse_set(root: Path, directories: list[str]) -> None:
+    """Apply a cone-mode sparse checkout of `directories`."""
+    run(root, 'sparse-checkout', 'set', '--cone', '--', *directories)
+
+
+def sparse_add(root: Path, directories: list[str]) -> None:
+    run(root, 'sparse-checkout', 'add', '--', *directories)
+
+
+def sparse_disable(root: Path) -> None:
+    """Restore the full working tree."""
+    run(root, 'sparse-checkout', 'disable')

blinkered/graph.py

@@ -0,0 +1,49 @@
+"""Traversal over the node graph."""
+from collections.abc import Iterable
+
+from .manifest import Node
+
+
+def closure(nodes: dict[str, Node], start: str, *, via: Iterable[str] | None = None,
+            tags: Iterable[str] | None = None) -> list[str]:
+    """`start` and its transitive dependencies.
+
+    `via` restricts the edge kinds followed; `tags` filters the output without stopping traversal.
+    Unknown targets are skipped; `check` reports them.
+    """
+    if start not in nodes:
+        raise KeyError(start)
+    via = None if via is None else set(via)
+    seen, queue = [start], [start]
+    while queue:
+        for target in nodes[queue.pop(0)].targets(via):
+            if target in nodes and target not in seen:
+                seen.append(target)
+                queue.append(target)
+    if tags is None:
+        return seen
+    tags = set(tags)
+    return [name for name in seen if tags & set(nodes[name].tags)]
+
+
+def cycles(nodes: dict[str, Node]) -> list[list[str]]:
+    """Dependency cycles, each as a list of node names."""
+    state, stack, found = {}, [], []
+
+    def visit(name):
+        state[name] = 'open'
+        stack.append(name)
+        for target in nodes[name].targets():
+            if target not in nodes:
+                continue
+            if state.get(target) == 'open':
+                found.append(stack[stack.index(target):] + [target])
+            elif target not in state:
+                visit(target)
+        stack.pop()
+        state[name] = 'done'
+
+    for name in nodes:
+        if name not in state:
+            visit(name)
+    return found

blinkered/manifest.py

@@ -0,0 +1,61 @@
+"""Node manifests: `blinkered.toml` in any directory other than the repository root."""
+import posixpath
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import git
+from .config import FILENAME
+from .findings import Finding
+
+
+@dataclass(frozen=True)
+class Node:
+    name: str
+    directory: str
+    tags: tuple[str, ...] = ()
+    edges: dict[str, tuple[str, ...]] = field(default_factory=dict)
+
+    def targets(self, via=None) -> list[str]:
+        return [target for kind, targets in self.edges.items()
+                if via is None or kind in via for target in targets]
+
+
+def discover(root: Path) -> tuple[dict[str, Node], list[Finding]]:
+    """All nodes by name, read from the working tree or the index, independent of the view."""
+    paths = sorted(set(git.tracked_paths(root)) | set(git.untracked_paths(root)))
+    nodes, errors = {}, []
+    for path in paths:
+        directory, name = posixpath.split(path)
+        if name != FILENAME or not directory:
+            continue
+        try:
+            node = parse(directory, git.read_file(root, path))
+        except (ValueError, tomllib.TOMLDecodeError) as error:
+            errors.append(Finding('manifest', path, str(error)))
+            continue
+        if node.name in nodes:
+            errors.append(Finding('manifest', path,
+                                  f'duplicate node name, also {nodes[node.name].directory}'))
+            continue
+        nodes[node.name] = node
+    return nodes, errors
+
+
+def parse(directory: str, text: str) -> Node:
+    """Build a node from its manifest text."""
+    data = tomllib.loads(text)
+    unknown = set(data) - {'tags', 'edges'}
+    if unknown:
+        raise ValueError(f'unknown keys {sorted(unknown)}')
+    tags = data.get('tags', [])
+    if not isinstance(tags, list) or not all(isinstance(tag, str) for tag in tags):
+        raise ValueError('tags must be a list of strings')
+    edges = data.get('edges', {})
+    if not isinstance(edges, dict):
+        raise ValueError('edges must be a table')
+    for kind, targets in edges.items():
+        if not isinstance(targets, list) or not all(isinstance(t, str) for t in targets):
+            raise ValueError(f'edges.{kind} must be a list of node names')
+    return Node(name=posixpath.basename(directory), directory=directory, tags=tuple(tags),
+                edges={kind: tuple(targets) for kind, targets in edges.items()})

blinkered/plugins/__init__.py

@@ -0,0 +1 @@
+"""Optional language-specific checks, enabled under `[plugins]` in the root configuration."""

blinkered/plugins/python_imports.py

@@ -0,0 +1,48 @@
+"""Python code imports must be covered by declared edges.
+
+Only files present in the working tree are inspected, so nodes outside the view are not checked.
+"""
+import ast
+from pathlib import Path
+
+from ..findings import Finding
+from ..manifest import Node
+
+
+def owner(path: str, nodes: dict[str, Node]) -> Node | None:
+    for node in nodes.values():
+        if path == node.directory or path.startswith(node.directory + '/'):
+            return node
+    return None
+
+
+def imported_paths(file: Path, relative: str) -> list[str]:
+    """Repository-relative module paths imported by `file`."""
+    package = relative.split('/')[:-1]
+    result = []
+    for statement in ast.walk(ast.parse(file.read_text(), filename=str(file))):
+        if isinstance(statement, ast.Import):
+            result += [alias.name.replace('.', '/') for alias in statement.names]
+        elif isinstance(statement, ast.ImportFrom):
+            if statement.level:
+                base = package[:len(package) - statement.level + 1]
+            else:
+                base = []
+            module = statement.module.split('.') if statement.module else []
+            result.append('/'.join(base + module))
+    return result
+
+
+def check(root: Path, nodes: dict[str, Node]) -> list[Finding]:
+    """Imports of another node's directory that the importing node does not declare as an edge."""
+    findings = []
+    for node in nodes.values():
+        allowed = set(node.targets())
+        for file in sorted((root / node.directory).rglob('*.py')):
+            relative = file.relative_to(root).as_posix()
+            for path in imported_paths(file, relative):
+                target = owner(path, nodes)
+                if target and target.name != node.name and target.name not in allowed:
+                    findings.append(Finding('import', relative,
+                                            f'imports {target.name} without a declared edge'))
+    return findings

blinkered/state.py

@@ -0,0 +1,23 @@
+"""Focus state, stored under `.git/blinkered/`."""
+from pathlib import Path
+
+from . import git
+
+
+def _file(root: Path) -> Path:
+    return git.git_dir(root) / 'blinkered' / 'focus'
+
+
+def read_focus(root: Path) -> str | None:
+    file = _file(root)
+    return file.read_text().strip() or None if file.is_file() else None
+
+
+def write_focus(root: Path, node: str | None) -> None:
+    """Store the focus node name; None clears it."""
+    file = _file(root)
+    if node is None:
+        file.unlink(missing_ok=True)
+        return
+    file.parent.mkdir(parents=True, exist_ok=True)
+    file.write_text(node + '\n')

blinkered-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+blinkered/__init__.py,sha256=i8RlyfQunni31mxYnb4VOWzeLf2KEj1CngtcilVZYpQ,97
+blinkered/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+blinkered/checks.py,sha256=zQY_6NUVsobQhMnmHaUBvZanmH-IuN5vN-4ybaltwVA,4100
+blinkered/cli.py,sha256=5efCTmmCr5pGgOWeBUIne0WNntHoTaWENqxy2cc16jU,6684
+blinkered/config.py,sha256=TGisk2zXuO6THU--i2WBlA-cfDjxvrMaynqGxXVhPlM,1069
+blinkered/findings.py,sha256=VZFeiLiwWBPKVx0qSq3cVRywgj-_0ItyzxXvJTgQ4nw,245
+blinkered/git.py,sha256=j9wxs8gO_QHPVB873pAdm_DjbQhortojUFD-HdnvFVQ,3453
+blinkered/graph.py,sha256=kNdn1TytdXJad8e2rbDrjBvc3oxPOu4c2SPaC2aAzLI,1589
+blinkered/manifest.py,sha256=k1pHb72Cx33iLRh-HLfDRSg9OjUh7hCN9vWBHmzXWSA,2422
+blinkered/state.py,sha256=kcxxKxaeGYCFs1OKNDDDvuHXGYHMfVp2_DqcBB8E1U0,610
+blinkered/plugins/__init__.py,sha256=DW9NnNTaZuo53jt1XJ_vmSNr3JXInAYXxxo87A7C4yE,94
+blinkered/plugins/python_imports.py,sha256=_-nyM8Q0Tl6y-rufOZ21uIviZvs652tmPaf8paeV9OM,1940
+blinkered-0.0.1.dist-info/METADATA,sha256=J8RGAZ_IQfzVqfjfFnwzYhDuofquObiZnbleOgzxxH0,3031
+blinkered-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+blinkered-0.0.1.dist-info/entry_points.txt,sha256=tbSj_LdIkduNsdZa9rz2l0n4OFNdrj-Ul2ZJmCKQ_lg,49
+blinkered-0.0.1.dist-info/licenses/LICENSE,sha256=icg8SgJcFlSwf0Kl5Cb_YFQU2y3zb-JdklS1_apol7E,1071
+blinkered-0.0.1.dist-info/RECORD,,

blinkered-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

blinkered-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+blinkered = blinkered.cli:main

blinkered-0.0.1.dist-info/licenses/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.