traceback-id 0.1.0__tar.gz

traceback_id-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 traceback_id contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

traceback_id-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: traceback-id
+Version: 0.1.0
+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
+
+Penjelasan error/traceback pemrograman dalam **Bahasa Indonesia**, untuk
+pemula — dimulai dari Python.
+
+
+## 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 -e ".[color]"
+```
+
+`rich` (untuk output berwarna) sifatnya opsional — tanpa `[color]`,
+traceback_id tetap berfungsi penuh dengan output teks polos.
+
+## 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`.
+
+## Menjalankan Test
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## 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).

traceback_id-0.1.0/README.md

@@ -0,0 +1,160 @@
+# traceback_id
+
+Penjelasan error/traceback pemrograman dalam **Bahasa Indonesia**, untuk
+pemula — dimulai dari Python.
+
+
+## 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 -e ".[color]"
+```
+
+`rich` (untuk output berwarna) sifatnya opsional — tanpa `[color]`,
+traceback_id tetap berfungsi penuh dengan output teks polos.
+
+## 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`.
+
+## Menjalankan Test
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## 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).

traceback_id-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "traceback-id"
+version = "0.1.0"
+description = "Penjelasan error/traceback pemrograman dalam Bahasa Indonesia, untuk pemula."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "traceback_id contributors" }]
+keywords = ["error", "traceback", "bahasa indonesia", "belajar coding", "education", "debugging"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Intended Audience :: Education",
+    "Natural Language :: Indonesian",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: Education",
+]
+dependencies = [
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+color = ["rich>=13.0"]
+dev = ["pytest>=7.0", "rich>=13.0"]
+
+[project.urls]
+Homepage = "https://github.com/traceback-id/traceback_id"
+Issues = "https://github.com/traceback-id/traceback_id/issues"
+
+[project.scripts]
+traceback_id = "traceback_id.cli:main"
+
+# Community plugins register themselves here from their own package's
+# pyproject.toml, e.g.:
+#
+#   [project.entry-points."traceback_id.adapters"]
+#   javascript = "traceback_id_javascript.adapter:JavaScriptAdapter"
+#
+# See ARCHITECTURE.md §1 and §3 (core/registry.py).
+
+[tool.setuptools.packages.find]
+include = ["traceback_id*"]
+
+[tool.setuptools.package-data]
+traceback_id = ["rules/*.yaml", "adapters/*/rules.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

traceback_id-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

traceback_id-0.1.0/tests/test_contract.py

@@ -0,0 +1,58 @@
+"""Test kontrak (ARCHITECTURE.md §11): dijalankan terhadap *setiap* adapter
+yang terdaftar di registry (built-in maupun plugin komunitas) untuk
+memastikan capture() dan parse() selalu menghasilkan StructuredError yang
+valid. Ini pengaman utama supaya adapter baru tidak diam-diam melanggar
+kontrak `LanguageAdapter`.
+"""
+from __future__ import annotations
+
+import pytest
+
+from traceback_id.adapters.base import LanguageAdapter
+from traceback_id.core.models import ErrorCategory, StructuredError
+from traceback_id.core.registry import get_registry
+
+# Setiap adapter builtin yang punya contoh error otomatis untuk dites di sini.
+# Adapter baru (mis. javascript, java) tinggal menambah entri: nama adapter
+# -> (isi file contoh yang pasti error, argumen tambahan untuk capture()).
+_KNOWN_ERROR_SOURCES = {
+    "python": "nilai_yang_tidak_pernah_didefinisikan\n",
+}
+
+
+def _all_adapters() -> list:
+    registry = get_registry()
+    return [registry.get_by_name(name) for name in registry.available_languages()]
+
+
+@pytest.mark.parametrize("adapter", _all_adapters(), ids=lambda a: a.name)
+def test_adapter_declares_name_and_extensions(adapter: LanguageAdapter):
+    assert adapter.name
+    assert adapter.file_extensions
+    assert all(ext.startswith(".") for ext in adapter.file_extensions)
+
+
+@pytest.mark.parametrize("adapter", _all_adapters(), ids=lambda a: a.name)
+def test_adapter_rules_path_exists(adapter: LanguageAdapter):
+    assert adapter.rules_path.exists(), f"rules_path {adapter.rules_path} tidak ditemukan"
+
+
+@pytest.mark.parametrize("adapter", _all_adapters(), ids=lambda a: a.name)
+def test_adapter_capture_and_parse_produce_valid_structured_error(adapter: LanguageAdapter, tmp_path):
+    source = _KNOWN_ERROR_SOURCES.get(adapter.name)
+    if source is None:
+        pytest.skip(f"belum ada contoh error otomatis untuk adapter '{adapter.name}' di tests/test_contract.py")
+
+    script = tmp_path / f"contoh_error{adapter.file_extensions[0]}"
+    script.write_text(source)
+
+    raw_output = adapter.capture([str(script)])
+    assert raw_output.strip(), "capture() harus menghasilkan output saat program error"
+
+    structured = adapter.parse(raw_output)
+
+    assert isinstance(structured, StructuredError)
+    assert structured.language == adapter.name
+    assert structured.error_type
+    assert isinstance(structured.category, ErrorCategory)
+    assert structured.raw_output == raw_output

traceback_id-0.1.0/traceback_id/__init__.py

@@ -0,0 +1,19 @@
+"""traceback_id — penjelasan error/traceback pemrograman dalam Bahasa
+Indonesia, dimulai dari Python (lihat PRD.md).
+
+Mode in-process (khusus Python, DX terbaik untuk kasus ini)::
+
+    import traceback_id
+    traceback_id.activate()
+
+Mode CLI (universal, dipakai bahasa apa pun yang punya adapter)::
+
+    traceback_id run script.py
+    traceback_id run script.js
+"""
+from __future__ import annotations
+
+from traceback_id.hook import activate, deactivate, is_active
+
+__all__ = ["activate", "deactivate", "is_active", "__version__"]
+__version__ = "0.1.0"

traceback_id-0.1.0/traceback_id/__main__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+
+from traceback_id.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

traceback_id-0.1.0/traceback_id/adapters/__init__.py

@@ -0,0 +1 @@
+"""Paket adapter bahasa. Lihat adapters/base.py untuk kontraknya."""

traceback_id-0.1.0/traceback_id/adapters/base.py

@@ -0,0 +1,36 @@
+"""Kontrak adapter bahasa (ARCHITECTURE.md §4).
+
+Setiap adapter — built-in maupun plugin komunitas yang didaftarkan lewat
+entry_points `traceback_id.adapters` — wajib mengimplementasikan interface
+ini. `core/` hanya bergantung pada `LanguageAdapter` + `StructuredError`,
+tidak pernah mengimpor adapter bahasa tertentu secara langsung.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from traceback_id.core.models import StructuredError
+
+
+class LanguageAdapter(ABC):
+    """Interface yang wajib dipenuhi setiap adapter bahasa."""
+
+    name: str
+    file_extensions: list[str]
+
+    @abstractmethod
+    def capture(self, command: list[str]) -> str:
+        """Jalankan command, kembalikan raw stderr/output sebagai teks."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def parse(self, raw_output: str) -> StructuredError:
+        """Ubah teks error mentah jadi StructuredError."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def rules_path(self) -> Path:
+        """Lokasi file rule khusus bahasa ini."""
+        raise NotImplementedError

traceback_id-0.1.0/traceback_id/adapters/python/__init__.py

@@ -0,0 +1 @@
+"""Adapter Python. Lihat adapter.py untuk implementasi, rules.yaml untuk rule."""