How valdecircarvalho/contalinha works
This repo is a single-machine Python utility (not a distributed system) that analyzes a directory on disk and produces:
• Aggregated statistics (files, total lines, blank/comment/code/billable lines, sizes, per-extension breakdown)
• A CSV report (summary + per-extension + per-file details)
It has two entrypoints:
• Primary: contalinha-ui.py — Tkinter GUI (directory picker, tables, sort/scroll, progress bar, save button)
• Legacy: contalinha.py — CLI output (uses rich), still generates CSV
Read the repo as “components” (from the file tree)
Top-level “modules” to represent:
• contalinha-ui.py
• Presentation layer (Tkinter widgets)
• User interactions: select directory, start analysis, sort table, save CSV
• Progress reporting
• contalinha.py
• CLI presentation (console)
• Argument parsing / interactive prompt
• Pretty output via rich
• (Shared domain logic is not explicit from the tree; it may be duplicated in both files.)
• Directory traversal
• File-type detection / extension grouping
• Line classification (blank/comment/code/billable)
• Stats aggregation
• CSV report generation
• requirements.txt
• External dependency: rich (CLI only)
• build.py
• Build/packaging workflow (e.g., creating contalinha.exe or bundling)
• C4 Level 1 (Context): who uses it and what external resources it touches (filesystem)
• C4 Level 2 (Container-ish): GUI app vs CLI app (two executables/scripts) and their dependencies
• C4 Level 3 (Component): the internal pipeline steps (scan → parse → aggregate → present → export)
Actors / External systems
• User
• Local File System (the directory being analyzed; files read)
• Local Output Directory (where CSV is written)
Optional but accurate:
• OS / Python Runtime
• Tkinter (GUI framework) as a library dependency
• rich (CLI rendering library) as a dependency
Application entrypoints (two “containers”)
• GUI App (contalinha-ui.py)
• CLI App (contalinha.py) (legacy)
Directory Selection / Input
• GUI: file dialog + validation + “clear existing results” warning
• CLI: argv parsing or prompt
File Discovery / Traversal
• Walk directory tree
• Filter/ignore rules (if any exist in code; if not, keep generic: “enumerates files”)
File Reader
• Open/read file content (handle encoding/errors if implemented)
Line Classifier
• Counts:
• total lines
• blank lines
• comment lines (language-dependent heuristics)
• code lines
• billable lines (= total - blank)
Aggregator / Reducer
• Per-file stats
• Per-extension stats
• Overall totals + percentages
Report Generator (CSV)
• Produces result_YYYY-MM-DD-HH-MM.csv
• Contains:
• statistics by extension
• per-file detailed list
CLI App → CSV Writer → File System: “Write result_*.csv”
• Developer → build.py → “packager” (if used) → outputs: contalinha.exe (legacy per README)
• requirements.txt influences CLI runtime dependency installation
Internal components: pipeline steps + CSV writer + renderers
This makes it obvious this is a desktop utility, not a service.
Even if implemented in one script file, separate conceptual responsibilities:
• Traversal vs parsing vs aggregation vs presentation vs export
This project benefits from that separation because it has two UIs that rely on the same underlying computation.