Metadata-Version: 2.4
Name: muda-audit
Version: 0.1.0
Summary: A Lean waste audit for your codebase. Walk the gemba, see the seven wastes, improve.
Author: Baris Aydin
License-Expression: MIT
Project-URL: Repository, https://github.com/baris2828/muda-audit
Keywords: lean,muda,code-quality,audit,kaizen,gemba,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.40; extra == "ai"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# muda 無駄

**A Lean waste audit for your codebase. Walk the gemba, see the seven wastes, improve.**

[![ci](https://github.com/baris2828/muda-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/baris2828/muda-audit/actions/workflows/ci.yml)
[![self-audit](https://img.shields.io/badge/self--audit-waste_score_0-brightgreen)](#muda-audits-muda)
[![python](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
[![license](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)

---

Toyota taught the manufacturing world to see seven kinds of waste — *muda* — on the shopfloor:
transport, inventory, motion, waiting, overproduction, overprocessing, defects.
After six years of walking real factory floors as a Lean consultant, I kept seeing the same seven
patterns in every codebase I touched. Nobody had named them there.

`muda` is a CLI that performs a **gemba walk through a repository**: it goes to the real place,
observes without judgment, maps every observation to one of the seven wastes, and then does what
Lean always does next — a **Pareto cut** to show you the vital few wastes worth fixing first.

My consulting principle is *"Weglassen vor Automatisieren"* — eliminate before you automate.
This tool is that principle, executable.

```text
╭─────────────────────────────────────────────────╮
│ muda 無駄 · gemba walk of ./demo-shop           │
│ 6 files observed · 11 findings · waste score 20 │
╰─────────────────────────────────────────────────╯
The seven wastes
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Waste          ┃ Findings ┃ Score ┃ Share ┃ Pareto                     ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Defects        │        3 │     8 │   40% │ ██████████████████ ◀ focus │
│ Inventory      │        3 │     5 │   25% │ ███████████ ◀ focus        │
│ Motion         │        2 │     2 │   10% │ ████ ◀ focus               │
│ Overprocessing │        1 │     2 │   10% │ ████ ◀ focus               │
│ Waiting        │        1 │     2 │   10% │ ████                       │
│ Overproduction │        1 │     1 │    5% │ ██                         │
└────────────────┴──────────┴───────┴───────┴────────────────────────────┘
Pareto: the ◀ focus wastes account for ~80% of the score. Start there.

┃ fix now    ┃ defects   ┃ Debugger left in code      ┃ src/app.py:15    ┃
┃ fix now    ┃ defects   ┃ Possible hardcoded secret  ┃ src/app.py:5     ┃
┃ should fix ┃ inventory ┃ Dependency never imported  ┃ requirements.txt ┃
┃ should fix ┃ waiting   ┃ Stale TODO (waiting 260d)  ┃ src/app.py:4     ┃

╭──────────────── Kaizen — built-in heuristics ────────────────╮
│ 1. Defects: Fix severity-3 items today: remove debuggers,    │
│    rotate anything that looks like a committed secret …      │
│ 2. Inventory: Delete what git already remembers …            │
╰──────────────────────────────────────────────────────────────╯
```

## The mapping: shopfloor → codebase

The core idea of this project is a translation table. Each waste keeps its original
manufacturing meaning and gets a concrete, checkable software equivalent:

| Waste 無駄 | On the shopfloor | In your codebase — what `muda` checks |
|---|---|---|
| **Transport** | Moving parts between stations without adding value | Pass-through modules that only shuttle imports/re-exports |
| **Inventory** | Stock on shelves binding capital and hiding problems | Dependencies declared but never imported; commented-out code blocks |
| **Motion** | Workers walking and reaching for badly placed tools | Oversized files, overlong functions, deeply nested paths |
| **Waiting** | Half-finished work queuing for the next station | TODO/FIXME/HACK comments — aged via `git blame`, the older the worse |
| **Overproduction** | Producing ahead of any real demand | Functions and classes defined but referenced nowhere |
| **Overprocessing** | Machining the same part twice at two stations | Byte-identical duplicate files |
| **Defects** | Scrap and rework escaping downstream | Leftover debuggers, bare `except:`, dynamic eval, hardcoded secrets |

Run `muda wastes` to see this table in your terminal.

## Quickstart

```bash
pipx install git+https://github.com/baris2828/muda-audit   # or: pip install .
muda walk .                          # audit the current repo
muda walk . --top 25                 # show more findings
muda walk . --report audit.md        # Markdown report for the PR / wiki
muda walk . --json audit.json        # machine-readable, for dashboards
muda walk . -x "*.ipynb" -x "docs/*" # exclude globs
```

Repo and package are named `muda-audit`; the command is simply `muda`.

## Try it in 30 seconds

```bash
python examples/build_demo.py    # generates ./demo-shop — a tiny webshop full of deliberate waste
muda walk demo-shop              # watch the walk surface all seven wastes
```

The generated shop gets a git history dated ~8 months back, so `git blame` can
age its markers into *stale* ones. The walk deliberately ignores `.gitignore`,
so a repo-root `muda walk .` will flag the shop too — delete `demo-shop/` when
you are done playing.

## The kaizen layer: an optional sensei

Seeing waste is step one; Lean is about the countermeasure. After each walk, a **sensei**
turns the Pareto profile into prioritized kaizen advice. Two interchangeable advisors sit
behind one interface (Strategy pattern):

- **HeuristicSensei** — curated guidance per waste, ships with the tool, works offline. Default.
- **AISensei** — sends an anonymized summary (scores + top findings, never your source files)
  to the Anthropic API for repo-specific advice.

```bash
pip install "muda-audit[ai]"          # the SDK is an optional extra, never a hard dependency
export ANTHROPIC_API_KEY=sk-ant-...
muda walk . --ai
```

**Graceful degradation is a feature, not a fallback:** no key, no SDK, no network, or a failed
call — the audit still completes with heuristic advice and tells you why. The core tool has
exactly two dependencies (`typer`, `rich`) and never requires the cloud.

| Variable | Purpose | Default |
|---|---|---|
| `ANTHROPIC_API_KEY` | Enables the AI sensei with `--ai` | unset → heuristics |
| `MUDA_MODEL` | Override the model | `claude-haiku-4-5-20251001` ([current models](https://docs.claude.com/en/api/overview)) |

## CI quality gate: stop the line

In the Toyota Production System, any worker can pull the **Andon cord** and stop the line
when they see a defect. `--fail-on-score` is that cord for your pipeline:

```yaml
# .github/workflows/quality.yml
- name: Lean waste gate
  run: |
    pip install git+https://github.com/baris2828/muda-audit
    muda walk . --fail-on-score 25 --report muda-report.md
```

The budget is yours to choose: start where your codebase is today, then ratchet it down —
that is *kaizen*, continuous improvement, encoded in one CI number.

### muda audits muda

This repository holds itself to the strictest setting. [CI](.github/workflows/ci.yml) runs
`muda walk . --fail-on-score 0` on every push: **any** waste in this codebase stops the line.
Building that meant eating the classic scanner problem of self-reference (a waste detector
finds its own detection patterns) — solved by counting markers only inside real code comments
and camouflaging fixture strings in tests, the same techniques security scanners use.

## Architecture

```mermaid
flowchart LR
    A[walker.py<br/>the gemba walk] -->|FileInfo| B{wastes/ registry}
    B --> C1[transport]
    B --> C2[inventory]
    B --> C3[motion]
    B --> C4[waiting]
    B --> C5[overproduction]
    B --> C6[overprocessing]
    B --> C7[defects]
    C1 & C2 & C3 & C4 & C5 & C6 & C7 -->|Findings| D[scoring.py<br/>waste score + Pareto]
    D --> E[sensei.py<br/>Heuristic / AI advice]
    D --> F[report.py]
    E --> F
    F --> G1[terminal · Rich]
    F --> G2[markdown]
    F --> G3[json]
```

Design decisions, in the order I made them:

1. **One walk, many observers.** The repository is traversed exactly once; checks receive
   immutable `FileInfo` records and re-read no text content. The only exceptions are
   deliberate: the duplicate check hashes file bytes, the waiting check consults `git blame`.
2. **A registry, not a framework.** Each waste is one module implementing one `Protocol`.
   An eighth waste is one new file plus one import line — walker, scorer and reporters
   stay untouched (open/closed principle).
3. **Strategy for the sensei.** Heuristic and AI advisors are interchangeable behind
   `get_advice()`; the AI path degrades to the heuristic on any failure, so the audit
   never depends on the network.
4. **Render three times, analyze once.** Terminal, Markdown and JSON views consume the
   same findings and scores. Rendering never re-runs analysis.
5. **stdlib-first.** Parsing uses `ast`, `tomllib`, `hashlib`, `subprocess` from the
   standard library. Two runtime dependencies, both for presentation.

## Honest limitations

`muda` is a gemba walk, not a court ruling. The checks are deliberately conservative
heuristics: unused-dependency detection knows common alias mappings (`scikit-learn` → `sklearn`)
but not every plugin system; dead-code detection counts any textual mention as demand, so it
under-reports rather than over-reports; duplicate detection is byte-exact only. Findings are
severity-graded conversation starters for a kaizen session — verify before you delete.
Currently strongest on Python, with basic JS/TS support. The checks were calibrated by
field-testing against 14 real-world repositories.

## Roadmap

Near-term: near-duplicate detection (normalized-AST hashing), a `--diff` mode that audits
only changed files in a PR, per-repo thresholds via `muda.toml`, and an eighth check for the
"unused talent" waste some Lean schools add — undocumented public APIs.

## About

Built by **Baris Aydin** — Lean Management consultant (M.Eng.) turned Data Scientist,
six years of process consulting across aerospace, steel, automotive and logistics.
This tool exists because the seven wastes turned out to be a portable lens:
they work on a shopfloor in Bremen and in a `src/` directory alike.

*Weglassen vor Automatisieren* — eliminate before you automate.

[LinkedIn](https://www.linkedin.com/in/baris-aydin-engineering/) · [GitHub](https://github.com/baris2828)

## License

[MIT](LICENSE)
