Metadata-Version: 2.4
Name: traceback-id
Version: 0.1.1
Summary: Penjelasan error/traceback pemrograman dalam Bahasa Indonesia, untuk pemula.
Author: traceback_id contributors
License: MIT
Project-URL: Homepage, https://github.com/traceback-id/traceback_id
Project-URL: Issues, https://github.com/traceback-id/traceback_id/issues
Keywords: error,traceback,bahasa indonesia,belajar coding,education,debugging
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Education
Classifier: Natural Language :: Indonesian
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Education
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Provides-Extra: color
Requires-Dist: rich>=13.0; extra == "color"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: rich>=13.0; extra == "dev"
Dynamic: license-file

# traceback_id

[![PyPI version](https://img.shields.io/pypi/v/traceback-id.svg)](https://pypi.org/project/traceback-id/)
[![Python versions](https://img.shields.io/pypi/pyversions/traceback-id.svg)](https://pypi.org/project/traceback-id/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Penjelasan error/traceback pemrograman dalam **Bahasa Indonesia**, untuk
pemula — dimulai dari Python. **Tersedia di PyPI:**
[pypi.org/project/traceback-id](https://pypi.org/project/traceback-id/)

> Latar belakang & keputusan produk ada di [`PRD.md`](PRD.md).
> Desain teknis lengkap ada di [`ARCHITECTURE.md`](ARCHITECTURE.md).

## Kenapa traceback_id?

Traceback Python (atau stack trace/compiler error di bahasa lain) ditulis
dalam bahasa Inggris teknis yang sering bikin pemula mentok. traceback_id
tetap menampilkan error aslinya (developer berpengalaman tetap butuh itu),
lalu menambahkan penjelasan singkat dalam Bahasa Indonesia: **kenapa** error
ini terjadi, dan **apa** yang bisa dicoba untuk memperbaikinya.

## Instalasi

```bash
pip install traceback-id
```

Untuk output berwarna (opsional, lewat `rich`):

```bash
pip install "traceback-id[color]"
```

Tanpa `[color]`, traceback_id tetap berfungsi penuh dengan output teks
polos — `rich` bukan dependency wajib.

> Mau pasang dari source langsung (bukan dari PyPI)? Lihat bagian
> [Development](#development--kontribusi-kode) di bawah.

## Pemakaian

### Mode in-process (khusus Python — DX terbaik)

```python
import traceback_id
traceback_id.activate()

print(nilai_yang_tidak_ada)
```

```
Traceback (most recent call last):
  File "contoh.py", line 4, in <module>
    print(nilai_yang_tidak_ada)
NameError: name 'nilai_yang_tidak_ada' is not defined
------------------------------------------------------------
penjelasan traceback_id (Bahasa Indonesia):
Kode kamu mencoba memakai nama `nilai_yang_tidak_ada`, tapi Python belum
pernah melihat nama itu didefinisikan sebelumnya di titik ini.

Saran: Periksa apakah `nilai_yang_tidak_ada` sudah kamu isi nilainya
sebelum baris ini, atau cek kemungkinan salah ketik nama variabel/fungsi.
```

Nonaktifkan kapan saja dengan `traceback_id.deactivate()` — traceback
kembali ke behavior default Python, dan exit code program tidak berubah.

### Mode CLI (universal — dipakai bahasa apa pun yang punya adapter)

```bash
traceback_id run script.py
```

Ekstensi file (`.py`, nanti `.js`, `.java`, dst) dipakai untuk memilih
adapter secara otomatis, atau paksa lewat `--lang`:

```bash
traceback_id run script.mjs --lang javascript
```

### Contoh untuk dicoba

```bash
traceback_id run examples/demo_errors.py name_error
traceback_id run examples/syntax_error_demo.py
traceback_id run examples/indentation_error_demo.py
```

Lihat `examples/demo_errors.py` untuk daftar lengkap 15 jenis error yang
di-cover di v0.1 (`name_error`, `type_error`, `index_error`, `key_error`,
`attribute_error`, `zero_division_error`, `import_error`,
`module_not_found_error`, `value_error`, `file_not_found_error`,
`recursion_error`, `stop_iteration`, `unbound_local_error`, plus
`syntax_error_demo.py` & `indentation_error_demo.py` yang terpisah).

## Struktur Proyek

```
traceback_id/
├── traceback_id/              # package yang diinstall
│   ├── __init__.py            # activate() / deactivate() publik
│   ├── hook.py                # sys.excepthook, mode in-process
│   ├── cli.py                 # `traceback_id run <file>`
│   ├── core/                  # mesin inti — language-agnostic
│   │   ├── models.py          # StructuredError, ErrorCategory
│   │   ├── explainer.py       # cocokkan rule, render template
│   │   ├── formatter.py       # gabung traceback asli + penjelasan
│   │   └── registry.py        # daftar adapter (built-in + plugin)
│   ├── adapters/
│   │   ├── base.py            # LanguageAdapter (kontrak)
│   │   └── python/
│   │       ├── adapter.py     # capture (hook + subprocess), parser
│   │       └── rules.yaml     # 15 error type Python v0.1
│   └── rules/
│       └── universal_categories.yaml   # fallback lintas bahasa
├── tests/
│   ├── test_core/
│   ├── test_adapters/
│   └── test_contract.py       # semua adapter wajib lolos test ini
├── examples/
│   └── demo_errors.py
├── pyproject.toml
└── README.md
```

Menambah bahasa baru = buat folder `traceback_id/adapters/<bahasa>/` berisi
`adapter.py` (implementasi `LanguageAdapter`) + `rules.yaml` — `core/` tidak
perlu disentuh sama sekali (lihat `ARCHITECTURE.md` §7).

## Menambah Rule Baru (Python)

Rule ada di `traceback_id/adapters/python/rules.yaml`, key-nya = nama
error native (mis. `NameError`). Tidak perlu ubah kode inti:

```yaml
NamaErrorBaru:
  category: KATEGORI_UNIVERSAL_YANG_SESUAI   # lihat ErrorCategory di core/models.py
  pattern: "regex opsional dengan (?P<nama_variabel>...)"
  penjelasan: >
    Penjelasan kenapa error ini terjadi. Bisa pakai {nama_variabel} yang
    diambil dari `pattern` di atas.
  saran: >
    Saran konkret cara memperbaikinya.
```

## Kontribusi Adapter Bahasa Baru (fase komunitas)

Setelah kontrak `LanguageAdapter` dibuka untuk plugin (roadmap Fase 3 —
lihat `PRD.md` §10), adapter bahasa baru bisa didistribusikan sebagai
package Python terpisah dan otomatis terdeteksi lewat `entry_points`:

```toml
# pyproject.toml package plugin kamu, mis. traceback-id-javascript
[project.entry-points."traceback_id.adapters"]
javascript = "traceback_id_javascript.adapter:JavaScriptAdapter"
```

Semua adapter — built-in maupun plugin — wajib lolos `tests/test_contract.py`.

## Development & Kontribusi Kode

Untuk kerja di source langsung (bukan lewat PyPI) — mis. mau nambah rule,
adapter bahasa baru, atau perbaikan bug:

```bash
git clone <url-repo-github-kamu>
cd traceback_id

python3 -m venv .venv && source .venv/bin/activate   # opsional tapi disarankan
pip install -e ".[dev]"

pytest
```

`pip install -e` memasang traceback_id dalam mode *editable* — perubahan
di source langsung kepakai tanpa perlu install ulang. `tests/test_contract.py`
wajib tetap lolos untuk adapter apa pun (built-in maupun plugin).

## Status & Roadmap

Draft v0.1 (MVP): arsitektur core + adapter diterapkan, adapter Python
matang (15 jenis error, mode in-process & CLI). Roadmap lengkap
(JavaScript di v0.3, Java + `entry_points` publik di v0.4, dst) ada di
`PRD.md` §10 dan `ARCHITECTURE.md` §10.

## Lisensi

MIT — lihat [`LICENSE`](LICENSE).
