Laporan Generator

Universal Academic Document & Thesis Engine for AI Agents and Engineers
Otomatisasi dokumen akademik dan teknis dari Markdown ke PDF berstandar publikasi dan Microsoft Word (DOCX) dalam hitungan detik.
Mendukung pedoman resmi format penulisan kampus Indonesia (UI, ITB, UGM, ITS, UNPAD) dan standar internasional.

Panduan Cepat • Panduan Preset Kampus • Cheatsheet Sintaks • Skema Metadata • Penyelesaian Masalah • Catatan Perubahan

Ikhtisar

Laporan Generator adalah kompilator otomatisasi dokumen akademik berevolusi ganda (dual-engine) sekaligus kapabilitas terpadu untuk agen kecerdasan buatan (AI Agent Skill). Alat ini dirancang untuk menjembatani alur kerja rekayasa perangkat lunak modern dengan standar ketat format penulisan karya ilmiah perguruan tinggi.

Penyusunan makalah, laporan magang/praktik kerja lapangan (PKL), laporan proyek, hingga skripsi dan tesis kerap menguras waktu akibat proses penataan format manual di pengolah kata seperti Microsoft Word. Laporan Generator menuntaskan permasalahan ini secara menyeluruh langsung dari berkas sumber Markdown modular, yang dapat dikompilasi secara paralel menjadi:

1. PDF Kualitas Publikasi: Tipografi presisi tinggi berbasis mesin typesetting modern Typst.
2. Microsoft Word Standar (.docx): Dokumen murni berbasis OpenXML dengan penataan hierarki heading yang rapi, bidang dinamis Daftar Isi (TOC Field Codes), serta penomoran halaman ganda (Romawi kecil untuk bagian awal dan angka Arab untuk batang tubuh bab).

Proyek ini juga memuat paket AI Agent Skill yang kompatibel dengan 10+ platform agen AI, memungkinkan agen cerdas menyusun draf, mengaudit sitasi, memindai pedoman kampus, dan membangun dokumen secara otonom.

Sorotan Arsitektur

Alur Kerja Pipeline Dual-Engine

[ Berkas Sumber Markdown ]
├── cover.md (Kata Pengantar & Lembar Depan)
├── chapters/bab*.md (BAB I s.d. BAB V)
├── metadata.yml (Preset Kampus, Penulis, Dosen, Lembar Pengesahan)
└── references.bib (Basis Data Sitasi BibTeX)
          │
          ├──> [ Pipeline Mesin Typst ]
          │     ├── template.typ (Tata letak tipografi & margin dinamis)
          │     ├── ImageMagick (Normalisasi kanal alfa citra)
          │     └── typst compile ──> [ Laporan.pdf ]
          │
          └──> [ Pipeline Mesin Word/DOCX ]
                ├── Pandoc + docx.lua (Transformasi AST untuk heading BAB)
                ├── reference.docx (Gaya tipografi dasar TNR 12pt A4)
                ├── scripts/finalize-docx.py (Injeksi kode bidang TOC dinamis)
                └── scripts/docx-pagenum.py (Manipulasi OpenXML penomoran ganda) ──> [ Laporan.docx ]

Fitur Rekayasa Unggulan

• Penomoran Halaman Ganda Otomatis:
  • Bagian Awal (Kata Pengantar, Daftar Isi, Daftar Gambar/Tabel, Abstrak): Penomoran angka Romawi kecil di tengah bawah (i, ii, iii...), dengan nomor pada halaman cover disembunyikan secara otomatis.
  • Bagian Utama (BAB I hingga Penutup dan Daftar Pustaka): Penomoran angka Arab (1, 2, 3...) yang diatur ulang dimulai dari halaman 1.
• Daftar Isi Dinamis Microsoft Word Asli:
  • Menggunakan kode bidang murni OpenXML (w:fldSimple / w:instrText TOC \o "1-3" \h \z \u).
  • Hierarki judul bab (BAB I, 1.1, 1.1.1) terdaftar dengan sempurna pada panel navigasi Word tanpa tumpang tindih teks atau kesalahan indentasi.
  • Kompatibel penuh dengan Microsoft Office 365, Word 2016-2021, LibreOffice Writer, dan WPS Office.
• Penomoran Otomatis Bab, Gambar, dan Tabel:
  • Penomoran gambar, tabel, dan persamaan matematika secara otomatis mengikat pada indeks bab aktif (contoh: Gambar 1.1, Tabel 2.3, Persamaan (3.1)).
  • Variabel counter di-reset secara otomatis pada setiap batas pergantian bab.
• Keterampilan Agen AI Lintas Platform (Multi-Host AI Skill):
  • Terstruktur sesuai spesifikasi Agent Skill Standard lengkap dengan protokol wawancara interaktif 3 tahap di SKILL.md.
  • Dapat dideteksi dan dieksekusi langsung oleh Antigravity CLI, Claude Code, Grok, Codex/OpenAI, GitHub Copilot, Cursor, Roo-Code/Cline, OpenCode, dan Kiro-CLI.
• Peralatan Audit & Penjaminan Mutu:
  • doctor: Audit integritas dokumen untuk mendeteksi sitasi rusak/yatim, gambar yang tidak ditemukan di disk, struktur heading yang salah, dan kesalahan skema metadata.
  • stats: Analisis komprehensif jumlah kata, karakter, perkiraan durasi membaca, estimasi total halaman, dan inventaris media.
  • bundle: Pengemasan arsip rilis zip yang bersih dari berkas sementara untuk pengumpulan ke institusi.
  • preset scan: Pemindai otomatis dokumen PDF pedoman kampus untuk mengekstrak margin dan gaya heading ke konfigurasi YAML baru.

Dukungan Host AI Agent

Laporan Generator mendistribusikan skill agen ke direktori global maupun lokal repositori:

Untuk menyinkronkan seluruh skill ke seluruh host yang terpasang di sistem dalam satu perintah:

npx laporan-generator sync-hosts

Alur Penggunaan Cepat

Opsi A: Alur Otonom AI Agent via NPX (Direkomendasikan)

Anda dapat membuat atau menginisialisasi dokumen baru di folder mana pun tanpa perlu melakukan kloning repositori:

# 1. Daftarkan kapabilitas Laporan Generator ke seluruh agen AI Anda
npx laporan-generator sync-hosts

# 2. Pasang dependensi sistem yang diperlukan (Typst, Pandoc, ImageMagick)
npx laporan-generator setup

# 3. Inisialisasi struktur dokumen akademik lengkap di direktori saat ini
npx laporan-generator init

Setelah inisialisasi selesai, buka antarmuka obrolan AI Agent Anda (Antigravity CLI, Claude Code, atau OpenCode), lalu berikan instruksi:

"Tolong buatkan draf Skripsi lengkap BAB 1 sampai BAB 3 dengan format ITB (preset itb-ta) berdasarkan topik sistem deteksi intrusi jaringan menggunakan eBPF."

Agen AI akan membaca SKILL.md, menjalankan protokol wawancara interaktif 3 tahap, menerapkan preset kampus, menyusun konten bab, memvalidasi sitasi pada references.bib, menjalankan audit kesehatan doctor, dan membangun dokumen PDF serta Word secara otomatis.

Opsi B: Alur Baris Perintah (CLI) Mandiri / Manual

Jika Anda ingin menulis dokumen secara manual dan mengompilasinya langsung via terminal:

Linux / macOS:

# Kloning repositori
git clone https://github.com/muadzhdz/laporan-generator.git tugas-akhir
cd tugas-akhir

# Periksa kelengkapan dependensi dan integritas berkas
./laporan check

# Bangun dokumen PDF dan DOCX
./laporan build

# Buka dokumen PDF hasil kompilasi
./laporan view

Windows (Native PowerShell 5.1+ / 7+ tanpa WSL):

# Kloning repositori
git clone https://github.com/muadzhdz/laporan-generator.git tugas-akhir
cd tugas-akhir

# Periksa kelengkapan dependensi dan integritas berkas
.\laporan.ps1 check

# Bangun dokumen PDF dan DOCX
.\laporan.ps1 build

# Buka dokumen PDF hasil kompilasi
.\laporan.ps1 view

Lingkungan Nix Flake (Hermetik & Reproducible):

# Masuk ke isolated devShell dengan versi toolchain identik
nix develop

# Kompilasi dokumen di dalam lingkungan devShell
./laporan build

Lingkungan Docker (Tanpa Dependensi Sistem Host):

docker compose run --rm laporan-generator

Matriks Perintah CLI

Seluruh perintah didukung secara konsisten di NPX, Linux/macOS Bash (./laporan), dan Windows PowerShell (.\laporan.ps1):

Preset Kampus Resmi

Konfigurasi tata letak bawaan yang disesuaikan dengan pedoman penulisan universitas di Indonesia:

Cara Mengaktifkan Preset

./laporan preset apply itb-ta
# atau
npx laporan-generator preset apply itb-ta

Memindai Pedoman PDF Kampus Lain

Apabila universitas Anda belum terdaftar di atas, jalankan pemindai dokumen:

./laporan preset scan /path/ke/pedoman-skripsi.pdf

Pemindai akan menganalisis parameter margin, ukuran font, dan penomoran bab dari teks dokumen pedoman, lalu menghasilkan berkas preset berekstensi .yml yang siap digunakan di direktori presets/.

Konfigurasi Dokumen (metadata.yml)

Seluruh struktur dokumen, judul, informasi kepenulisan, tanda tangan lembar pengesahan, dan abstrak bilingual dikendalikan terpusat melalui metadata.yml:

title: "Analisis dan Implementasi Sistem Deteksi Intrusi Jaringan Berbasis eBPF"
document_type: "Skripsi"
margin_preset: "itb-ta"

author:
  - name: "Mu'adz Hudzaifah"
    nim: "13522001"

institution: "Institut Teknologi Bandung"
faculty: "Sekolah Teknik Elektro dan Informatika"
department: "Teknik Informatika"
city: "Bandung"
year: "2026"
date: "14 September 2026"

course: "Tugas Akhir II"
lecturer: "Dr. Ir. Pembimbing Utama, M.T."

# Lembar Pengesahan
approval:
  city: "Bandung"
  date: "14 September 2026"
  supervisors:
    - name: "Dr. Ir. Pembimbing Utama, M.T."
      nip: "197501012000031001"
      role: "Pembimbing I"
    - name: "Dr. Eng. Pembimbing Pendamping, S.T."
      nip: "198002022005011002"
      role: "Pembimbing II"
  dean:
    name: "Prof. Dr. Dekan Fakultas, M.Sc."
    nip: "196803031992031003"
    role: "Dekan STEI"

# Abstrak Bahasa Indonesia
abstract_id: >
  Deteksi intrusi jaringan konvensional seringkali menimbulkan overhead performa yang signifikan...
keywords_id: ["eBPF", "Deteksi Intrusi", "Linux Kernel", "Keamanan Jaringan"]

# Abstrak Bahasa Inggris
abstract_en: >
  Conventional network intrusion detection systems frequently introduce notable performance overhead...
keywords_en: ["eBPF", "Intrusion Detection", "Linux Kernel", "Network Security"]

Struktur Direktori

laporan-generator/
├── bin/
│   └── laporan-generator.js       # Router CLI global untuk Node.js / NPX
├── lib/
│   ├── init.js                    # Modul inisialisasi dokumen baru
│   ├── setup.js                   # Wrapper instalasi dependensi sistem
│   ├── sync-hosts.js              # Distributor skill agen AI multi-host
│   └── uninstall.js               # Pembersih skill agen AI dari sistem
├── .agents/
│   ├── skills/laporan-generator/  # Standar Universal Agent Skill
│   │   ├── SKILL.md               # Instruksi dan protokol wawancara agen AI
│   │   ├── agents/                # Skema konfigurasi spesifik agen
│   │   ├── references/            # Rujukan skema YAML dan panduan teknis
│   │   ├── resources/             # Salinan berkas template dan utilitas
│   │   └── scripts/               # Skrip bantu audit dan kalkulasi dokumen
│   └── workflows/
│       └── laporan-generator.md   # Definisi perintah alur kerja slash command
├── chapters/
│   ├── bab1-pendahuluan.md        # Latar belakang, rumusan masalah, dan tujuan
│   ├── bab2-tinjauan-pustaka.md   # Landasan teori dan kajian literatur
│   ├── bab3-metodologi.md         # Desain arsitektur dan metodologi riset
│   ├── bab4-hasil-dan-pembahasan.md # Implementasi, pengujian, dan pembahasan
│   └── bab5-penutup.md            # Kesimpulan dan saran pengembangan
├── docs/                          # Dokumentasi teknis terperinci
├── presets/                       # Koleksi preset format resmi universitas
├── scripts/
│   ├── finalize-docx.py           # Injeksi kode bidang TOC murni pada Word
│   ├── docx-pagenum.py            # Penerapan sistem nomor halaman ganda Word
│   ├── make-reference-docx.py     # Pembangun berkas gaya reference.docx
│   ├── report-doctor.py           # Pemeriksa kesehatan & integritas berkas
│   ├── report-stats.py            # Kalkulator statistik kata dan halaman
│   ├── bundle.py                  # Utilitas pengemasan berkas rilis
│   ├── scan-preset.py             # Pemindai otomatis PDF pedoman kampus
│   ├── validate-preset.py         # Validator skema berkas preset YAML
│   ├── setup-deps.sh              # Skrip instalasi dependensi Unix
│   └── setup-deps.ps1             # Skrip instalasi dependensi PowerShell Windows
├── apa.csl                        # Format sitasi dan daftar pustaka standar APA 7th
├── build.sh                       # Skrip kompilasi utama Linux/macOS
├── build-docx.sh                  # Skrip kompilasi khusus dokumen Word
├── cover.md                       # Kata Pengantar dan halaman depan
├── docx.lua                       # Filter Pandoc Lua untuk transformasi AST Word
├── flake.nix                      # Konfigurasi lingkungan kerja Nix reproducible
├── laporan                        # Wrapper CLI interaktif Bash
├── laporan.ps1                    # Wrapper CLI native PowerShell Windows
├── Makefile                       # Target otomatisasi pengembang
├── metadata.yml                   # Konfigurasi aktif berkas dokumen
├── reference.docx                 # Dokumen template acuan gaya Microsoft Word
├── references.bib                 # Basis data pustaka format BibTeX
├── template.typ                   # Mesin typesetting dan tata letak Typst
└── test.sh                        # Rangkaian pengujian otomatis (101 assertions)

Penjaminan Mutu & Pengujian

Laporan Generator dilengkapi rangkaian pengujian otomatis (automated test suite) yang memvalidasi pipeline Unix dan Windows, filter Lua, skrip manipulasi OpenXML, validasi preset, serta fungsionalitas CLI:

# Menjalankan pengujian
./test.sh
# atau
npm test

Cakupan Pengujian (24 Test Suite / 101 Assertions)

• Integritas Berkas: Memverifikasi keberadaan seluruh template utama, skrip, dan skema acuan.
• Pipeline Typst: Memvalidasi rendering ukuran font, margin dinamis, logika penomoran bab, dan reset counter gambar/tabel.
• Pipeline DOCX: Memvalidasi transformasi AST Pandoc, filter Lua, field codes TOC OpenXML, dan nomor halaman ganda.
• Validasi Preset: Menguji seluruh preset bawaan terhadap skema spesifikasi YAML.
• Perintah CLI: Memverifikasi alur eksekusi init, check, build, stats, doctor, bundle, preset, dan uninstall.
• Kebersihan & Keamanan: Memastikan tidak ada berkas sampah biner, cache Python (.pyc), atau berkas temporer yang tertinggal.

Pusat Dokumentasi

• Panduan Pemula (Zero to PDF): Panduan langkah demi langkah dari instalasi hingga kompilasi pertama.
• Panduan Preset Kampus: Rincian margin, tipografi, dan format penulisan antar universitas.
• Cheatsheet Sintaks Markdown: Panduan lengkap penulisan sitasi, rumus matematika, tabel, dan gambar.
• Skema Metadata: Referensi lengkap seluruh parameter pada metadata.yml.
• Skema Preset: Spesifikasi format untuk membuat preset kampus baru.
• Panduan Template Typst: Arsitektur tipografi, font Libertinus Serif, dan aturan halaman.
• Penyelesaian Masalah (Troubleshooting): Panduan penanganan kendala umum dependensi, font, dan izin sistem.
• Panduan Kontribusi: Pedoman pengembangan fitur baru dan penambahan preset.
• Catatan Perubahan (Changelog): Riwayat pembaruan dan rilis versi.

Lisensi

Didistribusikan di bawah lisensi MIT. Silakan baca berkas LICENSE untuk informasi lebih lanjut.