brake 0.1.0__tar.gz

brake-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: brake
+Version: 0.1.0
+Summary: Minimalistic yet powerful build tool
+License: MIT
+Author: Balthazar Rouberol
+Author-email: br@imap.cc
+Requires-Python: >=3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: parsimonious (>=0.11.0,<0.12.0)
+Description-Content-Type: text/markdown
+
+# Brake
+
+A minimalistic build system.
+
+
+## Why another build system?
+I've been using `make` for years, and probably use 10% of what it can really do. Over time, I have established patterns that I'm reusing in all (or most) projects:
+
+- [autodocumenting](https://blog.balthazar-rouberol.com/just-enough-makefile-to-be-dangerous#makefile-auto-documentation-as-the-default-step) the public facing targets
+- providing a target in charge of visually rendering the make graph, to help debug dependencies
+
+These patterns rely on a [number](https://git.balthazar-rouberol.com/brouberol/5esheets/src/branch/main/Makefile#L189) of [hacks](https://gitlab.wikimedia.org/repos/data-engineering/airflow-dags/-/merge_requests/2084) that I've been cargo culting in different projetcs, because `make` does not provide me with the level of annotation and introspection capabilities required to implement these features simply.
+
+I've also grown tired about some `make` behaviors over the years:
+
+- the implicitness of whether a target runs a task or builds a file
+
+```bash
+$ cat Makefile
+test:
+        echo "testing"
+$ make test
+echo "testing"
+testing
+$ touch test
+$ make test
+make: `test' is up to date.
+```
+
+- more generally, the sheer amount of implict behavior (run `make -p` and stare into the horizon)
+- the lack of builtin way to publicy document targets
+- the crazy [syntax](https://devhints.io/makefile) that looks like bash but really isn't
+
+I set out to write my own built system that would be based on the following principles:
+- no implicit behavior
+- builtin target introspection and documentation
+- automatic parallel builds
+- heavily tested
+
+
+## How does it work
+
+All targets are defined in a file, called `Brakefile` by default.
+
+TLDR: `brake` itself is built with itself, so have a look at the `Brakefile` in this project to see what features it has (or not).
+
+### Defining a target
+
+The simplest `break` task you can define is
+
+```python
+@task
+test:
+	pytest .
+```
+
+This defines a target of type `task`, that runs `pytest .` when executed.
+
+Commands are assumed to be bash, and are executed _line by line_, instead of in a single go. Although this may change in the future, the design goal is to only have the simplest commands be part of the `Brakefile`. Anything more than a oneliner should go into a script (whether python, bash or anything else) and be called from the `Brakefile`.
+
+### Target inter-dependencies
+
+You can define interdependant targets using the `deps` target argument:
+
+```python
+@task
+test:
+    pytest .
+
+@task
+check:
+    ruff check .
+
+@task(deps=[test, check])
+ci:
+```
+This way, when running `break run ci`, both `test` and `check` tasks will be executed. As the `ci` target has no associated command, it only acts as a dependency placeholder.
+
+### Documenting targets
+
+You can document each target by annotating them with a `description` argument.
+
+```python
+@task(description="Run unit tests")
+test:
+    pytest .
+
+@task(description="Run linter checks")
+check:
+    ruff check .
+
+@task(deps=[test, check], description="Run all tests and linters")
+ci:
+```
+
+You can then get the help for your targets by running `brake help`
+```
+check   Run linter checks
+ci      Run all tests and linters
+test    Run unit tests
+```
+
+### `@task` vs `@file`
+
+`brake` can deal with 2 types of targets:
+
+- `task`: defines what a task does (ex: running tests, formatting the codebase, applying database migrations, etc)
+- `file`: defines how a file gets built (ex: compiling source code, running some codegen script, etc)
+
+The following rules apply:
+
+- A `task` target can depend on both `file` or `task` targets
+- A `file` target can **only depend on other `file` target(s)**
+- A `file` target will be rebuilt if it does not exist on disk, or if any of its `file` dependencis was modified _after_ the file itself.
+- A `file` target name can be composed of `*`, which will be expanded as a simple [glob](https://en.wikipedia.org/wiki/Glob_(programming)) pattern
+
+Take a look at [`example_c/Brakefile`](./example_c/Brakefile) to see an example of a `Brakefile` mixing both `task` and `file` targets, aiming at building a very simple C program.
+
+### Defining a default target
+
+In the same way that `make` lets you define a default targt with `.DEFAULT_GOAL`, you can define which target will be built by default if no argument is provided to `brake run`.
+
+```python
+@task(description="Run unit tests")
+test:
+    pytest .
+
+@task(description="Run linter checks")
+check:
+    ruff check .
+
+@task(deps=[test, check], description="Run all tests and linters", default=true)
+ci:
+```
+
+### Visualizing the target graph
+
+You can use the `brake graph` command to export the target graph into a format that can itself be exported to an image. The default format is [dot](https://graphviz.org/doc/info/lang.html), but [mermaid](https://mermaid.js.org/) is also supported by passing `--syntax=mermaid`.
+
+```bash
+$ brake graph  > brake.dot
+$ dot -Tsvg brake.dot -o brake.svg
+```
+![brake tasks](https://f003.backblazeb2.com/file/brouberol-blog/public/brake.svg)
+
+### Parallel target builds
+
+Looking at the target graph form the previous section, we can see that running the `lint` task would run both the `lint.check` and `lint.format` dependency tasks. As each of these tasks are independant, they are run in parallel, through a process pool of available number of CPUs by default (configurable via the `-j` argument).
+
+```bash
+$ brake run lint
+[task:lint.check] poetry run ruff check .
+[task:lint.format] poetry run ruff format --check .
+11 files already formatted
+All checks passed!
+```
+By setting `-j1`, you can ensure that each task gets executed serially instead.
+
+```bash
+$ brake -j1 run lint
+[task:lint.check] poetry run ruff check .
+All checks passed!
+[task:lint.format] poetry run ruff format --check .
+11 files already formatted
+```
+
+### Usage
+
+```bash
+brake --help
+usage: brake [-h] [-j MAX_JOBS] [-f FILE] {run,help,graph} ...
+
+A minimalistic yet powerful build tool
+
+positional arguments:
+  {run,help,graph}
+    run                 Run a task
+    help                Display the targets help
+    graph               Display the targets as a graph
+
+options:
+  -h, --help            show this help message and exit
+  -j, --max-jobs MAX_JOBS
+                        The maximum number of jobs to run in parallel (default: 10)
+  -f, --file FILE       Path to the file containing the brake targets (default: Brakefile)
+  ```
+
+## Roadmap
+
+- [ ] Defining variables
+- [ ] Adding a `--explain` mode that wouldn't build the targets, but only explain what would get built and what wouldn't
+- [ ] Release publicly
+- [ ] Write some syntax highlighters for the Brake grammar
+
+## Why the name `brake`?
+
+There are at least 3 reasons. Use the one you prefer.
+
+1. So I can be able to say "this is a make-or-break" tool and sound smart
+1. It sounds like `break`, which is the semantic opposite to `make`
+1. Balthazar Rouberol's `make`.
+

brake-0.1.0/README.md

@@ -0,0 +1,201 @@
+# Brake
+
+A minimalistic build system.
+
+
+## Why another build system?
+I've been using `make` for years, and probably use 10% of what it can really do. Over time, I have established patterns that I'm reusing in all (or most) projects:
+
+- [autodocumenting](https://blog.balthazar-rouberol.com/just-enough-makefile-to-be-dangerous#makefile-auto-documentation-as-the-default-step) the public facing targets
+- providing a target in charge of visually rendering the make graph, to help debug dependencies
+
+These patterns rely on a [number](https://git.balthazar-rouberol.com/brouberol/5esheets/src/branch/main/Makefile#L189) of [hacks](https://gitlab.wikimedia.org/repos/data-engineering/airflow-dags/-/merge_requests/2084) that I've been cargo culting in different projetcs, because `make` does not provide me with the level of annotation and introspection capabilities required to implement these features simply.
+
+I've also grown tired about some `make` behaviors over the years:
+
+- the implicitness of whether a target runs a task or builds a file
+
+```bash
+$ cat Makefile
+test:
+        echo "testing"
+$ make test
+echo "testing"
+testing
+$ touch test
+$ make test
+make: `test' is up to date.
+```
+
+- more generally, the sheer amount of implict behavior (run `make -p` and stare into the horizon)
+- the lack of builtin way to publicy document targets
+- the crazy [syntax](https://devhints.io/makefile) that looks like bash but really isn't
+
+I set out to write my own built system that would be based on the following principles:
+- no implicit behavior
+- builtin target introspection and documentation
+- automatic parallel builds
+- heavily tested
+
+
+## How does it work
+
+All targets are defined in a file, called `Brakefile` by default.
+
+TLDR: `brake` itself is built with itself, so have a look at the `Brakefile` in this project to see what features it has (or not).
+
+### Defining a target
+
+The simplest `break` task you can define is
+
+```python
+@task
+test:
+	pytest .
+```
+
+This defines a target of type `task`, that runs `pytest .` when executed.
+
+Commands are assumed to be bash, and are executed _line by line_, instead of in a single go. Although this may change in the future, the design goal is to only have the simplest commands be part of the `Brakefile`. Anything more than a oneliner should go into a script (whether python, bash or anything else) and be called from the `Brakefile`.
+
+### Target inter-dependencies
+
+You can define interdependant targets using the `deps` target argument:
+
+```python
+@task
+test:
+    pytest .
+
+@task
+check:
+    ruff check .
+
+@task(deps=[test, check])
+ci:
+```
+This way, when running `break run ci`, both `test` and `check` tasks will be executed. As the `ci` target has no associated command, it only acts as a dependency placeholder.
+
+### Documenting targets
+
+You can document each target by annotating them with a `description` argument.
+
+```python
+@task(description="Run unit tests")
+test:
+    pytest .
+
+@task(description="Run linter checks")
+check:
+    ruff check .
+
+@task(deps=[test, check], description="Run all tests and linters")
+ci:
+```
+
+You can then get the help for your targets by running `brake help`
+```
+check   Run linter checks
+ci      Run all tests and linters
+test    Run unit tests
+```
+
+### `@task` vs `@file`
+
+`brake` can deal with 2 types of targets:
+
+- `task`: defines what a task does (ex: running tests, formatting the codebase, applying database migrations, etc)
+- `file`: defines how a file gets built (ex: compiling source code, running some codegen script, etc)
+
+The following rules apply:
+
+- A `task` target can depend on both `file` or `task` targets
+- A `file` target can **only depend on other `file` target(s)**
+- A `file` target will be rebuilt if it does not exist on disk, or if any of its `file` dependencis was modified _after_ the file itself.
+- A `file` target name can be composed of `*`, which will be expanded as a simple [glob](https://en.wikipedia.org/wiki/Glob_(programming)) pattern
+
+Take a look at [`example_c/Brakefile`](./example_c/Brakefile) to see an example of a `Brakefile` mixing both `task` and `file` targets, aiming at building a very simple C program.
+
+### Defining a default target
+
+In the same way that `make` lets you define a default targt with `.DEFAULT_GOAL`, you can define which target will be built by default if no argument is provided to `brake run`.
+
+```python
+@task(description="Run unit tests")
+test:
+    pytest .
+
+@task(description="Run linter checks")
+check:
+    ruff check .
+
+@task(deps=[test, check], description="Run all tests and linters", default=true)
+ci:
+```
+
+### Visualizing the target graph
+
+You can use the `brake graph` command to export the target graph into a format that can itself be exported to an image. The default format is [dot](https://graphviz.org/doc/info/lang.html), but [mermaid](https://mermaid.js.org/) is also supported by passing `--syntax=mermaid`.
+
+```bash
+$ brake graph  > brake.dot
+$ dot -Tsvg brake.dot -o brake.svg
+```
+![brake tasks](https://f003.backblazeb2.com/file/brouberol-blog/public/brake.svg)
+
+### Parallel target builds
+
+Looking at the target graph form the previous section, we can see that running the `lint` task would run both the `lint.check` and `lint.format` dependency tasks. As each of these tasks are independant, they are run in parallel, through a process pool of available number of CPUs by default (configurable via the `-j` argument).
+
+```bash
+$ brake run lint
+[task:lint.check] poetry run ruff check .
+[task:lint.format] poetry run ruff format --check .
+11 files already formatted
+All checks passed!
+```
+By setting `-j1`, you can ensure that each task gets executed serially instead.
+
+```bash
+$ brake -j1 run lint
+[task:lint.check] poetry run ruff check .
+All checks passed!
+[task:lint.format] poetry run ruff format --check .
+11 files already formatted
+```
+
+### Usage
+
+```bash
+brake --help
+usage: brake [-h] [-j MAX_JOBS] [-f FILE] {run,help,graph} ...
+
+A minimalistic yet powerful build tool
+
+positional arguments:
+  {run,help,graph}
+    run                 Run a task
+    help                Display the targets help
+    graph               Display the targets as a graph
+
+options:
+  -h, --help            show this help message and exit
+  -j, --max-jobs MAX_JOBS
+                        The maximum number of jobs to run in parallel (default: 10)
+  -f, --file FILE       Path to the file containing the brake targets (default: Brakefile)
+  ```
+
+## Roadmap
+
+- [ ] Defining variables
+- [ ] Adding a `--explain` mode that wouldn't build the targets, but only explain what would get built and what wouldn't
+- [ ] Release publicly
+- [ ] Write some syntax highlighters for the Brake grammar
+
+## Why the name `brake`?
+
+There are at least 3 reasons. Use the one you prefer.
+
+1. So I can be able to say "this is a make-or-break" tool and sound smart
+1. It sounds like `break`, which is the semantic opposite to `make`
+1. Balthazar Rouberol's `make`.

brake-0.1.0/brake/cli.py

@@ -0,0 +1,87 @@
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from brake.colors import Color, colorize
+from brake.graph import TargetGraph
+from brake.runner import TargetGraphRunner
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="A minimalistic yet powerful build tool",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "-j",
+        "--max-jobs",
+        type=int,
+        default=os.cpu_count(),
+        help="The maximum number of jobs to run in parallel",
+    )
+    parser.add_argument(
+        "-f",
+        "--file",
+        help="Path to the file containing the brake targets",
+        type=Path,
+        default="Brakefile",
+    )
+    subparsers = parser.add_subparsers()
+    run_parser = subparsers.add_parser("run", help="Run a task")
+    run_parser.add_argument("target", help="The target to run", nargs="?", default=None)
+    run_parser.set_defaults(func=run_target)
+
+    help_parser = subparsers.add_parser("help", help="Display the targets help")
+    help_parser.set_defaults(func=show_targets_help)
+
+    mermaid_parser = subparsers.add_parser("graph", help="Display the targets as a graph")
+    mermaid_parser.add_argument(
+        "--syntax",
+        help="The graph syntax to display the graph in",
+        choices=("dot", "mermaid"),
+        default="dot",
+    )
+    mermaid_parser.set_defaults(func=show_targets_graph)
+    args = parser.parse_args()
+    if not hasattr(args, "func") or not args.func:
+        print(parser.format_help())
+        sys.exit(0)
+    return args
+
+
+def run_target(graph: TargetGraph, args: argparse.Namespace):
+    runner = TargetGraphRunner(target_graph=graph)
+    try:
+        runner.run(args.target, max_workers=args.max_jobs)
+    except Exception as exc:
+        print(colorize(str(exc), color=Color.RED))
+        sys.exit(1)
+
+
+def show_targets_help(graph: TargetGraph, args: argparse.Namespace):
+    print("\n".join(graph.help()))
+
+
+def show_targets_graph(graph: TargetGraph, args: argparse.Namespace):
+    if args.syntax == "dot":
+        lines = graph.as_dot()
+    else:
+        lines = graph.as_mermaid()
+    print("\n".join(lines))
+
+
+def run():
+    args = parse_args()
+    graph_str = args.file.read_text()
+    graph = TargetGraph.from_str(graph_str)
+    os.chdir(args.file.parent)
+    if errors := graph.validate():
+        for error in errors:
+            print(colorize(str(error), color=Color.RED))
+        sys.exit(1)
+    args.func(graph, args)
+
+
+if __name__ == "__main__":
+    run()

brake-0.1.0/brake/colors.py

@@ -0,0 +1,16 @@
+from enum import StrEnum
+
+
+class Color(StrEnum):
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    BROWN = "\033[0;33m"
+    BLUE = "\033[0;34m"
+    PURPLE = "\033[0;35m"
+    CYAN = "\033[0;36m"
+    YELLOW = "\033[1;33m"
+    RESET = "\x1b[0m"
+
+
+def colorize(s: str, color: Color) -> str:
+    return f"{color}{s}{Color.RESET}"

brake-0.1.0/brake/exceptions.py

@@ -0,0 +1,19 @@
+class BaseBrakeException(Exception):
+    def __eq__(self, other) -> bool:
+        return type(self) is type(other) and self.args == other.args
+
+
+class CyclicGraph(BaseBrakeException):
+    pass
+
+
+class InvalidDependency(BaseBrakeException):
+    pass
+
+
+class DuplicatedTarget(BaseBrakeException):
+    pass
+
+
+class MultipleDefaultTargets(BaseBrakeException):
+    pass

brake-0.1.0/brake/graph.py

@@ -0,0 +1,233 @@
+import operator as op
+from collections import Counter, defaultdict
+
+from brake.colors import Color, colorize
+from brake.exceptions import CyclicGraph, DuplicatedTarget, InvalidDependency, MultipleDefaultTargets
+from brake.model import Target
+from brake.parser import TargetVisitor, grammar
+
+
+class TargetGraph:
+    """Core object representing the graph of targets to run"""
+
+    def __init__(self, targets: list[Target]):
+        self.targets = targets
+        self.target_maps = {t.name: t for t in self.targets}
+
+    def __getitem__(self, target_name: str):
+        return self.target_maps[target_name]
+
+    @classmethod
+    def from_str(cls, target_str: str):
+        """Parse the argument target graph string into a Graph object"""
+        tree = grammar.parse(target_str)
+        return cls(targets=TargetVisitor().visit(tree))
+
+    @property
+    def default_target(self) -> Target | None:
+        for target in self.targets:
+            if target.default:
+                return target
+        return None
+
+    def validate(self) -> list[Exception]:
+        """Return a list of validation errors when the target file is invalid"""
+        errors, defaults = [], []
+        target_names = Counter([target.name for target in self.targets])
+        duplicated_targets = {
+            target_name: count for target_name, count in target_names.items() if count > 1
+        }
+        for duplicated_target, count in duplicated_targets.items():
+            errors.append(DuplicatedTarget(f"Target {duplicated_target} is defined {count} times"))
+
+        for target in self.targets:
+            if target.default:
+                defaults.append(defaults)
+            if target.type == "file" and not target.exists() and not target.commands:
+                errors.append(
+                    InvalidDependency(f"{target.name} has no build command and does not exist")
+                )
+            for dep in target.deps:
+                try:
+                    dep_task = self.target_maps[dep]
+                except KeyError:
+                    errors.append(InvalidDependency(f"{target.name} depends on unknown target {dep}"))
+                    continue
+                if dep == target.name:
+                    errors.append(CyclicGraph(f"{target.name} depends on itself"))
+                elif target.type == "file" and dep_task.type == "task":
+                    errors.append(
+                        InvalidDependency(
+                            f"{target.name}->{dep_task.name}: a file target cannot depend on a task"
+                        )
+                    )
+        if len(defaults) > 1:
+            errors.append(
+                MultipleDefaultTargets(
+                    f"Multiple tasks ({', '.join(defaults)}) are defined as defaults"
+                )
+            )
+        return errors
+
+    def target_subgraph(self, root_target_name: str):
+        """Return a set of target names that belong to the depdency subgraph of a given target.
+
+        For example, if we had a graph like this:
+            A
+            B -> A
+            C -> B
+            D -> A
+            D -> E
+            E
+
+        target_subgraph("A") returns {"A"}
+        target_subgraph("B") returns {"A", "B"}
+        target_subgraph("C") returns {"A", "B", "C"}
+        target_subgraph("D") returns {"A", "E", "D"}
+        target_subgraph("E") returns {"E"}
+
+        This allows to us select the subset of targets to execute for a given
+        target root.
+
+        """
+        needed = set()
+
+        def visit(target_name: str):
+            if target_name in needed:
+                return
+            target = self.target_maps[target_name]
+
+            if not target.deps and target.commands:
+                needed.add(target_name)
+
+            for dep in target.deps:
+                dep_task = self.target_maps[dep]
+                if dep_task.should_rebuild(target):
+                    needed.add(target_name)
+                    visit(dep)
+
+        visit(root_target_name)
+        return needed
+
+    def target_subgraph_dependency_counters(self, root_target_name: str) -> dict[str, int]:
+        """Returns a dependency counter for each target in the subgraph of argument root target.
+
+        For example, if we had a graph like this:
+            A
+            B -> A
+            C -> B
+            D -> A
+            D -> E
+            E
+
+        target_subgraph_dependency_counters("A") returns {"A": 0}
+        -> when A is the root target, the subgraph is just {"A"}, which means
+           0 dependencies on A itself.
+
+        target_subgraph_dependency_counters("B") returns {"A": 0, "B": 1}
+        -> when B is the root target, the subgraph is B -> A, which means
+          - B has one dependency
+          - A has no dependency
+
+        target_subgraph_dependency_counters("C") returns {"A": 0, "B": 1, "C": 1}
+        -> when B is the root target, the subgraph is C -> B -> A, which means
+          - C has one dependency
+          - B has one dependency
+          - A has no dependency
+
+        target_subgraph_dependency_counters("D") returns {"A": 0, "E": 0, "D": 2}
+        -> when B is the root target, the subgraph is
+            D -> A;
+            D -> E;
+        which means
+          - D has 2 dependencies
+          - A has no dependency
+          - E has no dependency
+
+        target_subgraph_dependency_counters("E") returns {"E": 0}
+        -> same as A
+
+        """
+        remaining_deps = {}
+        subgraph = self.target_subgraph(root_target_name)
+        for subgraph_target_name in subgraph:
+            subgraph_target = self.target_maps[subgraph_target_name]
+            remaining_deps[subgraph_target_name] = sum(
+                1 for d in subgraph_target.deps if d in subgraph
+            )
+        return remaining_deps
+
+    def target_dependency_graph(self, target_name: str) -> dict[str, set[str]]:
+        """Return a dependency set for each target in the subgraph of argument root target
+
+        Note that this returns the dependency for all nodes in the subgraph to a given target,
+        not the depdendencies a target has onto others.
+
+        For example, if we had a graph like this:
+            A
+            B -> A
+            C -> B
+            D -> A
+            D -> E
+            E
+
+        target_dependency_graph("A") == {"A": set()}
+        target_dependency_graph("A") == {"A": {"B"}, "B": set()}
+        -> A has a depoendency FROM B
+
+        """
+        target = self.target_maps[target_name]
+        dependents = defaultdict(set)
+
+        # build dependency info only for needed targets
+        subgraph = self.target_subgraph(target_name)
+        for subgraph_target_name in subgraph:
+            subgraph_target = self.target_maps[subgraph_target_name]
+            for dep in subgraph_target.deps:
+                if dep in subgraph:
+                    dependents[dep].add(subgraph_target_name)
+
+        dependents[target.name] = set()
+        for dep in target.deps:
+            dependents[dep].add(target.name)
+
+        return dict(dependents)
+
+    def help(self) -> list[str]:
+        """Return the sorted list of targets along with their description"""
+        lines = []
+        sorted_targets = sorted(self.targets, key=op.attrgetter("name"))
+        longest_target_name = max([len(target.name) for target in sorted_targets])
+        for target in sorted_targets:
+            padded_target_name = f"{target.name:<{longest_target_name + 3}}"
+            line = f"{colorize(padded_target_name, color=Color.YELLOW)}{target.description}"
+            if target.default:
+                line = f"{line} {colorize('[default]', color=Color.GREEN)}"
+            lines.append(line)
+        return lines
+
+    def as_mermaid(self) -> list[str]:
+        """Return the target graph formatted in mermaid syntax"""
+        lines = ["graph LR"]
+        for target in self.targets:
+            target_node = f"{target.type}:{target.name}"
+            if not target.deps:
+                lines.append(target_node)
+            else:
+                for dep in target.deps:
+                    dep_task = self.target_maps[dep]
+                    lines.append(f"{target_node} --> {dep_task.type}:{dep_task.name}")
+        return lines
+
+    def as_dot(self):
+        """Return the target graph formatted in dot syntax"""
+        lines = ["digraph targets {"]
+        for target in self.targets:
+            target_node = f"{target.type}:{target.name}"
+            if not target.deps:
+                lines.append(f'    "{target_node}";')
+            for dep in target.deps:
+                dep_task = self.target_maps[dep]
+                lines.append(f'    "{dep_task.type}:{dep_task.name}" -> "{target_node}";')
+        lines.append("}")
+        return lines

brake-0.1.0/brake/model.py

@@ -0,0 +1,51 @@
+from dataclasses import dataclass, field
+from glob import glob
+from pathlib import Path
+from typing import Any, Literal
+
+
+@dataclass
+class TargetDecorator:
+    type: Literal["task", "file"]
+    args: dict[str, Any]
+
+
+@dataclass
+class Target:
+    name: str
+    type: Literal["task", "file"]
+    commands: list[str]
+    deps: list[str] = field(default_factory=list)
+    description: str = field(default_factory=str)
+    default: bool = field(default_factory=bool)
+
+    @property
+    def file(self) -> Path:
+        if self.type == "task":
+            raise TypeError("A task Target has no file")
+        return Path(self.name)
+
+    def exists(self) -> bool:
+        if self.type == "task":
+            return True
+        if "*" in self.file.name:  # glob pattern:
+            return all([Path(p).exists() for p in glob(self.file.name)])
+        return self.file.exists()
+
+    @property
+    def last_build_timestamp(self) -> float:
+        return self.file.stat().st_mtime
+
+    def should_rebuild(self, target_depending_on_self: "Target") -> bool:
+        if target_depending_on_self.type == "task":
+            return True
+        elif not target_depending_on_self.exists():
+            return True
+        elif "*" in self.name:
+            return any(
+                [
+                    target_depending_on_self.last_build_timestamp < Path(p).stat().st_mtime
+                    for p in glob(self.file.name)
+                ]
+            )
+        return target_depending_on_self.last_build_timestamp < self.last_build_timestamp

brake-0.1.0/brake/parser.py

@@ -0,0 +1,90 @@
+from parsimonious.grammar import Grammar
+from parsimonious.nodes import NodeVisitor
+
+from brake.model import Target, TargetDecorator
+
+grammar = Grammar("""
+    start         = target+
+    target        = target_decorator name ":" NEWLINE command_block NEWLINE*
+    target_decorator     = "@" ("task"/"file") target_args* NEWLINE
+    target_args   = "(" kv* ")"
+    kv            =  name "=" (list / string / bool) ","? " "? NEWLINE?
+    command_block = command*
+    command       = INDENT LINE NEWLINE
+
+    NEWLINE = ~r"\\n"
+    string = ~'"[^\"]*"'
+    list   =  "[" list_member* "]"
+    list_member = (" "* name " "* ","?)
+    bool   = ("true"/"false")
+    LINE   = ~"[^\\n]+"  # Match any line not containing a newline
+    name   = ~r"[a-zA-Z*][a-zA-Z0-9_\\-./*]*"
+    INDENT = ~r"\\s{4}"  # 4 spaces for indentation
+    DEDENT = ~r"\\s{0,3}"  # Allow variable indentation sizes after a block
+
+""")
+
+
+class TargetVisitor(NodeVisitor):
+    def visit_start(self, node, visited_children):
+        return visited_children
+
+    def visit_target(self, node, visited_children):
+        decorator, target_name, *_, command_block, _ = visited_children
+        kwargs = decorator.args.copy()
+        if kwargs.get("default"):
+            kwargs["default"] = True
+        return Target(
+            name=target_name,
+            type=decorator.type,
+            commands=command_block,
+            **kwargs,
+        )
+
+    def visit_target_decorator(self, node, visited_children):
+        _, target_type, task_args, _ = visited_children
+        task_args = task_args[0] if (isinstance(task_args, list) and task_args) else {}
+        return TargetDecorator(type=target_type[0].text, args=task_args)
+
+    def visit_target_args(self, node, visited_children):
+        args = {}
+        openinig_bracket, kvs, closing_bracket = visited_children
+        for kv in kvs:
+            args.update(kv)
+        return args
+
+    def visit_kv(self, node, visited_children):
+        kv = {}
+        key, _, val, *_ = visited_children
+        kv[key] = val[0]  # not sure why I have to index here
+        return kv
+
+    def visit_command_block(self, node, visited_children):
+        return visited_children
+
+    def visit_command(self, node, visited_children):
+        indent, cmd, newline = node.children
+        return cmd.text
+
+    def visit_list(self, node, visited_children):
+        opening_bracket, members, closing_bracket = visited_children
+        if isinstance(members, list):
+            return members
+        return members.children
+
+    def visit_string(self, node, visited_children):
+        return node.text.strip('"')
+
+    def visit_bool(self, node, visited_children):
+        return eval(node.text.capitalize())
+
+    def visit_list_member(self, node, visited_children):
+        _, member, *_ = visited_children
+        return member
+
+    def visit_name(self, node, visited_children):
+        return node.text
+
+    def generic_visit(self, node, visited_children):
+        # For any node we don't explicitly handle
+        return visited_children or node

brake-0.1.0/brake/runner.py

@@ -0,0 +1,65 @@
+import subprocess
+from collections import deque
+from concurrent.futures import Future, ProcessPoolExecutor
+
+from brake.graph import TargetGraph
+from brake.model import Target
+
+
+class TargetGraphRunner:
+    def __init__(self, target_graph: TargetGraph):
+        self.target_graph = target_graph
+        self.pool: ProcessPoolExecutor | None = None
+
+    def submit_target(self, target_name: str) -> Future:
+        """Submit a target by name to the worker pool"""
+        if self.pool:
+            return self.pool.submit(self.run_target, self.target_graph[target_name])
+        raise RuntimeError("The process pool has not yet been initialized")
+
+    @staticmethod
+    def run_target(target: Target):
+        for cmd in target.commands:
+            print(f"[{target.type}:{target.name}] {cmd}")
+            subprocess.run(cmd, shell=True, check=True)
+
+    @staticmethod
+    def wait_for_one_command_to_complete(commands: dict[Future, str]) -> str | None:
+        try:
+            done = next(f for f in commands if f.done())
+        except StopIteration:
+            return
+        else:
+            return commands.pop(done)
+
+    def run(self, target_name: str | None, max_workers: int):
+        if not target_name:
+            if default_target := self.target_graph.default_target:
+                target_name = default_target.name
+            else:
+                raise ValueError("A target is required to run as the graph has no default target")
+
+        dependents = self.target_graph.target_dependency_graph(target_name)
+        remaining_deps = self.target_graph.target_subgraph_dependency_counters(target_name)
+
+        # targets ready to run
+        ready = deque(name for name, n in remaining_deps.items() if n == 0)
+
+        running, completed = {}, set()
+
+        with ProcessPoolExecutor(max_workers=max_workers) as self.pool:
+            while ready or running:
+                # schedule new targets
+                while ready and len(running) < max_workers:
+                    name = ready.popleft()
+                    future = self.submit_target(name)
+                    running[future] = name
+
+                if completed_target_name := self.wait_for_one_command_to_complete(running):
+                    completed.add(completed_target_name)
+
+                    # unlock dependents
+                    for dep in dependents[completed_target_name]:
+                        remaining_deps[dep] -= 1
+                        if remaining_deps[dep] == 0:
+                            ready.append(dep)

brake-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "brake"
+version = "0.1.0"
+description = "Minimalistic yet powerful build tool"
+authors = [
+    {name = "Balthazar Rouberol",email = "br@imap.cc"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "parsimonious (>=0.11.0,<0.12.0)"
+]
+[dependency-groups]
+dev = [
+    "pytest (>=9.0.2,<10.0.0)",
+    "pytest-cov (>=7.0.0,<8.0.0)",
+    "ruff (>=0.15.6,<0.16.0)"
+]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.scripts]
+brake = 'brake.cli:run'
+
+[tool.pytest.ini_options]
+addopts = "-vv --cov=brake"
+testpaths = [
+    "tests"
+]
+
+[tool.ruff]
+line-length = 102
+
+[tool.coverage.run]
+omit = [
+    "brake/cli.py"
+]