How azisk/zpace works
Project type and purpose
• Zpace is a command-line disk-space analysis tool written in Python.
• It scans directories, categorizes files by type (videos, docs, code, etc.), detects special directories (node_modules, .venv, .git), and presents actionable insights.
File structure
• Top level:
• main.py – entry point for CLI invocation
• pyproject.toml – build/packaging config for Poetry/UV tools
• ARCHITECTURE.md, README.md, CHANGELOG.md – documentation
• test_.py – unit tests
• .github/workflows/*.yml – CI/CD pipelines
• No frontend/backend split, but internally it likely follows a pipeline pattern:
• CLI parser → Scanner → Categorizer → Reporter/Formatter
• CI workflows (ci.yml, publish-pypi.yml) show automated testing and release.
README for additional insights
• Lists core features (categorization, special-dir detection, sparse file handling).
• Describes usage flags (-n, -m).
• Development instructions reference Ruff (lint/format), pytest, and UV tooling.
a. Main components
1. CLI Interface
• Responsible for parsing arguments (-n, -m, target path).
2. File System Scanner
• Recursively walks directories, gathers file metadata (size, type, permissions).
3. File Categorizer
• Applies rules to group files into categories (Documents, Videos, Code, Special Dirs).
• Handles sparse file detection (Docker images).
4. Data Aggregator / Metrics Engine
• Maintains per-category totals, identifies top-N biggest files.
5. Reporter / Formatter
• Formats results into console tables or JSON (if extended).
6. External Services / OS
• Disk I/O subsystem (POSIX APIs, macOS full-disk-access).
7. Tests & CI
• pytest test suite, pre-commit hooks, GitHub Actions pipelines.
b. Relationships and interactions
• User invokes “zpace” command → CLI Interface
• CLI Interface passes parameters to Scanner
• Scanner issues filesystem calls, streams file entries to Categorizer
• Categorizer tags files, forwards to Data Aggregator
• Data Aggregator computes metrics, then hands results to Reporter
• Tests drive individual components; CI runs entire pipeline on push.
c. Architectural patterns/design principles
• Pipeline pattern: each stage (scan, categorize, aggregate, report) is a separate module.
• Single-Responsibility: CLI vs. scanning vs. reporting each isolated.
• Plugin-style extensibility: categorization rules or reporter formats could be pluggable.
• Lightweight modularity: no heavy frameworks, easy to test each stage.
d. Key technologies/frameworks
• Python 3.x (specified in .python-version)
• uv (CLI tool manager)
• pytest for testing
• Ruff for linting/formatting
• GitHub Actions for CI/CD
• PyPI publishing (publish-pypi.yml)