Arsitektur Repository

Repository fians/Waves bukan satu paket monolitik. Isinya beberapa kelompok berkas dengan peran berbeda: kode efek di src/js, sumber gaya di src/less, src/scss, dan src/sass, orkestrasi build di Gruntfile.js, serta situs dokumentasi di docs. package.json menetapkan main ke src/js/waves.js dan types ke src/typings/waves.d.ts, sehingga hanya dua berkas itu yang menjadi permukaan paket (package.json:7-8¹).

Peta dependensi antar modul

graph TD
  LESS["src/less/waves.less"] --> LESSBUILD["less:build"]
  LESSBUILD --> DISTCSS["dist/waves.css"]
  LESS --> L2SCSS["execute:less2scss"]
  L2SCSS --> SCSS["src/scss/waves.scss"]
  SCSS --> SASSCONV["sass-convert"]
  SASSCONV --> SASS["src/sass/waves.sass"]
  SCSS --> SASSTEST["sass:test"]
  SASS --> SASSTEST
  LESS --> LESSTEST["less:test"]
  JS["src/js/waves.js"] --> JSHINT["jshint"]
  JS --> UGLIFY["uglify"]
  UGLIFY --> DISTMINJS["dist/waves.min.js"]
  JS --> COPYJS["copy:js"]
  COPYJS --> DISTJS["dist/waves.js"]
  DISTCSS --> CSSMIN["cssmin"]
  CSSMIN --> DISTMINCSS["dist/waves.min.css"]
  DISTMINJS --> COPYDOCS["copy:docs"]
  DISTMINCSS --> COPYDOCS
  COPYDOCS --> DOCSSTATIC["docs/static"]
  DOCSSTATIC --> DOCSINDEX["docs/index.html"]
  DOCSINDEX --> SITUSCFG["situs.json"]
  style LESS fill:#336791,color:#fff
  style JS fill:#336791,color:#fff
  style SCSS fill:#8b5cf6,color:#fff
  style SASS fill:#8b5cf6,color:#fff
  style DISTCSS fill:#2d7d46,color:#fff
  style DISTJS fill:#2d7d46,color:#fff
  style DISTMINCSS fill:#2d7d46,color:#fff
  style DISTMINJS fill:#2d7d46,color:#fff
  style DOCSSTATIC fill:#2d7d46,color:#fff
  style DOCSINDEX fill:#2d7d46,color:#fff
  style SITUSCFG fill:#f59e0b,color:#000
%% fig: Arah dependensi antar modul repository
%% desc: Sumber LESS dan JavaScript masuk ke task Grunt, keluar sebagai artefak dist, lalu disalin ke docs/static yang dibaca situs Situs.

Panah bergerak dari sumber menuju keluaran. Tidak ada jalur balik: satu-satunya panah yang keluar dari dist menuju docs/static lewat task copy (Gruntfile.js:73-86²).

Peran tiap modul

Satu berkas JavaScript dengan tiga pembungkus

src/js/waves.js dibungkus satu IIFE yang mendeteksi tiga lingkungan sekaligus: AMD lewat define.amd, CommonJS lewat typeof exports === 'object', dan global browser lewat window.Waves (src/js/waves.js:10-32³). Tidak ada graf dependensi antarmodul di dalam repository, karena hanya ada satu berkas JavaScript sumber; yang berlapis hanyalah pembungkus keluarannya.

Rantai gaya searah: less ke scss ke sass

execute:less2scss membaca src/less/waves.less, mengganti @ menjadi $, mengubah definisi mixin menjadi @mixin, lalu menulis hasilnya ke src/scss/waves.scss (Gruntfile.js:132-151⁴). Sesudah itu sass-convert dengan from: 'scss', to: 'sass', dan indent: 2 mengubah src/scss/*.scss menjadi src/sass (Gruntfile.js:88-99⁵).

Artinya hanya src/less/waves.less yang disunting manusia. less:build memetakan berkas itu ke dist/waves.css sekaligus ke tests/less/waves.css untuk pembanding (Gruntfile.js:6-17⁶), sedangkan sass:test mengompilasi semua **/*.sass dan **/*.scss di bawah src ke tests/ dengan ekstensi .css (Gruntfile.js:101-111⁷). Perbandingan hasil ketiganya dibahas di Verifikasi Kesetaraan CSS, dan sintaks masing-masing bahasa di Sistem Gaya Less, SCSS, dan SASS.

Grunt sebagai satu-satunya orkestrator

Tidak ada tool build lain di repository. Seluruh isi devDependencies adalah plugin Grunt beserta grunt-sass-convert (package.json:9-21⁸). jshint memeriksa gruntfile.js dan src/js/*.js (Gruntfile.js:33-46⁹). uglify memetakan src/js/waves.js ke dist/waves.min.js dengan source map dist/waves.min.js.map (Gruntfile.js:48-70). cssmin memampatkan dist/waves.css menjadi dist/waves.min.css (Gruntfile.js:19-31). copy menyalin waves.js ke dist/ dan menyalin waves.min.css serta waves.min.js ke docs/static (Gruntfile.js:73-86).

Task build merangkai sebelas langkah berurutan, dari less:build sampai clean:test (Gruntfile.js:193-205¹²). Task default menjalankan build lalu watch (Gruntfile.js:207-208¹³), dan watch hanya memantau src/**/*.js serta src/**/*.less (Gruntfile.js:117-129¹⁴). Direktori src/scss dan src/sass sengaja tidak dipantau karena keduanya turunan. Langkah terakhir sebelum pembersihan adalah execute:test, yang mencetak ERROR: sass failed test. ketika hasil konversi tidak seragam (Gruntfile.js:153-178¹⁵). Urutan lengkap task ada di Pipeline Build Grunt.

Berkas hasil build tidak masuk repository

Berkas .gitignore mengabaikan direktori situs, semua docs/static/waves*, dan direktori tests/ (.gitignore:32-38). Jadi dist/ bukan satu-satunya tempat artefak: salinan yang dipakai situs dan hasil uji konversi juga dihasilkan ulang pada setiap build. Daftar berkas yang benar-benar dikirim ke konsumen ada di Artefak Distribusi.

⚠️ clean:test menghapus seluruh isi tests/* (Gruntfile.js:113-115¹⁶). Jangan menaruh berkas uji manual di tests/, karena build menghapusnya pada langkah terakhir.

Situs dokumentasi menutup rantai

situs.json hanya menetapkan source ke ./docs dan mengabaikan _pages/**/* (situs.json:1-4¹⁷). Halaman docs/index.html merakit enam fragmen dari docs/_pages/ lewat direktif @situs-include(...): home.html, examples.html, source.html, getting-started.html, api.html, dan faq.html (docs/index.html:50-60¹⁸). Posisi docs adalah konsumen hilir dari dist, bukan sumber. Cara menjalankan servernya dibahas di Situs Dokumentasi dengan Situs.

Titik masuk paket

bower.json menetapkan main ke berkas dist/waves.js dan dist/waves.css (bower.json:8¹⁹), sedangkan package.json menunjuk berkas sumber (package.json:7-8¹). Dua jalur distribusi itu menjelaskan mengapa src dan dist sama-sama harus ada di repository. Deklarasi tipenya berada di src/typings/waves.d.ts, yang mengekspor init, attach, ripple, dan calm dengan tipe ElementSelector (src/typings/waves.d.ts:1-9²⁰); pembahasannya ada di API Publik dan Tipings TypeScript.