Bỏ qua

Developer Guide

Tài liệu này dành cho contributor của Playground, Gateway, VS Code extension, GitLab integrations, Confluence app, Java core và rendering runtime.

1. Toolchain

Công cụ Version hoặc nguồn
JDK 21
Maven Maven Wrapper trong repository
Node.js 24
Docker Multi-stage build và Compose
VS Code ^1.95.0 cho extension
Forge CLI Bản tương thích runtime nodejs24.x cho Confluence PoC
uv Môi trường build tài liệu từ requirements-docs.txt

Trên Windows dùng mvnw.cmd; trên Linux và macOS dùng ./mvnw.

2. Bản đồ mã nguồn

Khu vực Trách nhiệm
server/src/main/resources/web/playground.html Playground UI và browser state
gateway/ Public API, auth, rate limit, cache và ETag
vscode-extension/ Commands, parser, preview và export
deploy/gitlab-krokup/ GitLab fence params và custom image
browser-extension/ GitLab MR Markdown preview và diagram diff
confluence-code-to-uml-poc/ Forge event, ADF transformer, resolver, macro editor và viewer Custom UI
server/ Java core, route, renderer profile và integration customizations
mermaid/, bpmn/, excalidraw/, diagrams.net/ Browser renderer companions
pydia/, Dockerfile.pydia Isolated Pydia sidecar
deploy/, Compose, Dockerfile.render Rendering runtime và deployment
mkdocs.yml, requirements-docs.txt Cấu hình và dependencies của website tài liệu
docs/ Markdown, stylesheet, JavaScript, font và OpenAPI contract

3. Playground

Playground được Java core phục vụ tại /playground. Khi sửa giao diện:

  1. Giữ token trong sessionStorage và source theo renderer trong localStorage.
  2. Hủy preview cũ và chỉ hiển thị kết quả request mới nhất.
  3. Giữ Fenced block và %%krokup tương đương về request gửi đi.
  4. Đồng bộ controls với renderer catalog và universal option schema.
  5. Hiển thị X-Diagram-Warnings mà không biến warning thành lỗi.
  6. Kiểm tra desktop, mobile, keyboard và trạng thái lỗi.

server/pom.xml loại web/** khỏi resource filtering rồi copy lại nguyên trạng. Không bật Maven filtering cho Playground vì JavaScript template literal có thể bị thay đổi trong artifact.

4. VS Code extension

Set-Location vscode-extension
npm ci
npm test
npm run package

Khi thêm setting hoặc command, cập nhật contributes, behavior, unit test và smoke test bằng Extension Development Host hoặc VSIX. Parser Markdown phải giữ các invariant:

  • chỉ {...} sau language được coi là params;
  • title="..." không trở thành render option;
  • fence params thắng directive trong preamble;
  • fence không có params giữ source directive;
  • source gửi đi chỉ có một dòng %%krokup;
  • Mermaid init directive %%{...}%% được giữ nguyên.

Áp dụng cùng parser cho Live Preview và Markdown Preview. Webview phải sanitize Markdown và SVG, đồng thời giữ CSP giới hạn.

5. Gateway

Set-Location gateway
npm ci
npm test
npm start

Các invariant của auth, cache và rate limit:

  • không log token và dùng constant-time token comparison;
  • cache byte accounting không âm;
  • entry quá lớn không được lưu;
  • TTL và LRU cùng thỏa max bytes/max entries;
  • export background không phân mảnh upstream cache;
  • ETag được tính từ output cuối;
  • hủy upstream khi subscriber cuối disconnect;
  • metrics callback không làm thay đổi request correctness.

Thay đổi cache key cần test chứng minh request nào dùng chung và request nào tách cache identity.

6. GitLab integrations

Kiểm tra ba lớp độc lập:

  1. Encoded GET: URL, source confidentiality, rate limit và Markdown/AsciiDoc.
  2. Fence params: rewriter, fail-open, renderer allow-list và custom image trên GitLab version đích.
  3. MR review: Markdown Before/After, parser, GitLab API adapter, pairing, vị trí diagram action, lazy render, queue, cache và browser package.

Fence params của GitLab document hiện không được browser extension chuyển đổi; MR review dùng %%krokup trong body. Hostname và permission của self-managed GitLab phải khớp manifest/package được phát hành.

Browser extension:

Set-Location browser-extension
npm install
npm test
npm run package:zip

GitLab fence pre-filter:

ruby deploy/gitlab-krokup/test/krokup_fence_rewriter_test.rb
docker build --file deploy/gitlab-krokup/Dockerfile `
  --tag gitlab-ce-kroki:test deploy/gitlab-krokup

Docker build kiểm tra patch target trong GitLab image và chạy lại unit test bằng Ruby được đóng gói trong image. Integration smoke dùng deploy/gitlab-krokup/test/run_gitlab_smoke.sh trên GitLab instance thử nghiệm.

7. Confluence

Set-Location confluence-code-to-uml-poc
npm.cmd install
npm.cmd --prefix static/code-to-uml install
npm.cmd test
npm.cmd run build
forge.cmd lint

Giữ các invariant sau:

  • page event không tạo vòng lặp update;
  • publish source không đổi giữ macro identity;
  • macro được tạo từ code block có khối Diagram source có thể chỉnh sửa ngay sau nó;
  • macro được tạo từ editor không bị page event chuyển đổi lại;
  • prose, heading và non-diagram fence giữ đúng thứ tự;
  • token chỉ nằm trong encrypted Forge variable và backend resolver;
  • resolver kiểm tra source hash, renderer, Pydia policy, timeout, MIME, kích thước và active SVG content;
  • live preview áp dụng renderer allow-list, giới hạn source và Pydia policy trước khi gọi Gateway;
  • Pydia cần global opt-in và numeric space allow-list.

Đổi Gateway host cần cập nhật cả RENDER_BASE_URL và backend fetch allow-list trong manifest.yml.

8. Java core và renderer

.\mvnw.cmd -pl server test
.\mvnw.cmd -pl server -DskipTests package

Thay đổi core hoặc renderer cần giữ route/format compatibility, cập nhật renderer profile, capability và adapter liên quan, rồi test source/options/output đại diện. Thay đổi runtime binary hoặc companion cần smoke test production image.

Thêm renderer mới tác động đồng thời tới service, metadata, image dependency, Gateway allow-list, VS Code mapping, OpenAPI và tests. Pydia còn cần opt-in, Unix socket delegation, sandbox limits và kiểm tra network/token isolation.

9. API, params và runtime

Khi thêm universal option hoặc theme, cập nhật schema/registry, capability, adapter hoặc output processor, tests và các UI đọc catalog.

Khi thay đổi API:

  1. Cập nhật docs/api-docs.yaml.
  2. Cập nhật source và tests theo contract.
  3. Chạy request mẫu qua Local Gateway.
  4. Cập nhật API Integration và OpenAPI.

Build topology local:

docker build --file Dockerfile.render --tag code-to-uml-render:dev .
docker build --file Dockerfile.pydia --tag code-to-uml-pydia:dev .
Copy-Item .env.example .env
docker compose -f compose.code-to-uml.yml up -d --build

ci/scripts/smoke-production.sh kiểm tra Gateway, core và renderer đại diện trong production image.

10. Website tài liệu

Chỉnh sửa tài liệu và giao diện trong docs/; không chỉnh trực tiếp file sinh ra trong site/. CSS nguồn nằm tại docs/stylesheets/, JavaScript tại docs/javascripts/ và font tại docs/assets/fonts/.

Chạy preview local:

$env:KROKI_SERVER_URL = "https://kroki-render-vsf.duckdns.org"
uv run --with-requirements requirements-docs.txt mkdocs serve

Trước khi hoàn tất thay đổi, tạo lại toàn bộ website và bật strict validation:

$env:KROKI_SERVER_URL = "https://kroki-render-vsf.duckdns.org"
uv run --with-requirements requirements-docs.txt mkdocs build --clean --strict

Build phải tạo lại HTML, search index, stylesheet, JavaScript và font trong site/. Sau khi có URL chính thức, đặt site_url trong mkdocs.yml rồi build lại để canonical URL và sitemap dùng đúng địa chỉ. Kiểm tra navigation, mục lục, search, liên kết OpenAPI và ít nhất một diagram trên website đã phát hành; diagram chỉ hiển thị khi browser truy cập được public Gateway qua HTTPS.

11. Test matrix

Lớp Vị trí
Java unit/integration server/src/test/java
Gateway gateway/test
VS Code extension vscode-extension/test-*.js
GitLab MR extension browser-extension/test
GitLab fence params deploy/gitlab-krokup/test
Confluence PoC confluence-code-to-uml-poc/test, Vite build, Forge lint
Pydia pydia/test_render.py, gateway/test/pydia-sandbox.test.js
Production image ci/scripts/smoke-production.sh
Website tài liệu mkdocs build --clean --strict, navigation, search và diagram smoke test
Benchmark ci/scripts/render-benchmark.mjs
Manual UI Playground, VSIX, GitLab MR extension và Confluence Custom UI

12. Hoàn tất thay đổi

  • Test liên quan pass và ghi lại test chưa chạy trong pull request.
  • UI change có runtime hoặc snapshot check phù hợp.
  • Runtime change có production image smoke test.
  • Thay đổi Markdown, navigation hoặc giao diện tài liệu có strict build và kiểm tra website tương ứng.
  • Token và source nhạy cảm không xuất hiện trong log.
  • API, params, settings và deployment docs phản ánh behavior mới.
  • GitLab và Confluence change được test trên môi trường tích hợp tương ứng trước khi phát hành.