How gauge-sh/tach works
Main Components
• CLI Interface – a command layer exposed via commands like “tach init”, “tach check”, “tach show”, and “tach report”. This is visible in both the Python (python/tach/cli.py, __main__.py) and Rust (src/cli.rs) parts.
• Configuration & Setup – configuration files like tach.toml and tach.domain.toml (in various parts of the project), along with modules under src/config and python/tach/parsing/config.py. These control declared dependencies, module boundaries, source roots, public interfaces, and layers.
• Dependency Enforcement Engine – the heart of the project that parses Python code, builds dependency maps, and enforces the “no cycles”, “declared dependencies only”, and “public interface” rules. Note the directories for dependency mapping (src/dep_map in Rust and python/tach/dependencies in Python), processors (src/processors/*), and the error/diagnostics subsystems (src/diagnostics, python/tach/errors, and python/tach/logging).
• Filesystem & Project Discovery – modules handling file system operations, Git interactions, and project layout discovery (e.g., python/tach/filesystem; src/filesystem.rs).
• Reporting & Visualization – components that generate output for the user: the “tach show” command that produces a dependency graph (DOT file or web visualization), and “tach report” for detailed dependency/usage info. These functions are supported by modules like src/commands/report.rs and python/tach/report.py.
• CI/CD & Integration – the GitHub workflows and Makefile indicate that Tach is integrated into automated testing and deployment pipelines. Also, support for pre-commit hooks (see python/tach/hooks and documentation on installing hooks) provides integration points for continuous enforcement.
Relationships and Interactions
• CLI commands (from both Python and Rust entry points) serve as the starting point. They trigger the configuration loader, which reads tach.toml and possibly tach.domain.toml files.
• Once configuration is loaded, the enforcement engine kicks in: it uses the parsing modules (both in Rust and Python) to inspect the project’s dependency structure, consults the configuration regarding allowed dependencies, and then uses filesystem operations to traverse the module files.
• If violations occur, the diagnostics and logging components record and report errors (with error messages including file paths and line numbers).
• In parallel, during commands like “tach show” the dependency engine outputs the graph data – either by creating a DOT file for local GraphViz processing or by sending data to a remote visualization engine (as described in the README).
Architectural Patterns and Design Principles
• The project embraces a layered (or modular) monolith architecture where clear boundaries between modules are enforced.
• Separation of concerns is evident: configuration, parsing, dependency analysis, and reporting/logging are all isolated.
• There is a clear division between the CLI/presentation layer (both in Python and Rust) and the domain logic (dependency enforcement, diagnostics, and graph generation).
• The design supports incremental adoption: not every module needs immediate full conformance and there are options to deprecate or ignore certain dependencies.
Technologies, Frameworks, and Libraries
• Rust is used to build the core of the tool (with files under src/). Look for the usage of Cargo and Rust modules.
• Python is used for the CLI integration and tooling (under python/tach), suggesting use of standard libraries and possibly popular Python CLI libraries.
• GraphViz integration is mentioned for DOT file generation.
• CI/CD configuration via GitHub Actions and pre-commit hooks is set up, indicating a commitment to continuous integration.
• Annotations or labels that reference key principles like “Modular Monolith”, “Enforced Dependencies”, “Public Interfaces”, and “Cycle Prevention”.
• Be as granular as possible by separating modules into their architectural layers (e.g., configuration, processing, reporting) to clearly communicate the design’s complexity and extensibility.