Refactor code structure for improved readability and maintainability; remove redundant code blocks and optimize function calls.

docs/trest-onboarding.md

@@ -0,0 +1,256 @@
+# TREST Onboarding Guide (Private Repo)
+
+This guide is designed for a new joiner to quickly set up access, install, and understand usage of the private `trest` package hosted at:
+
+- https://gitea.jig.com.hk/jig-software/trest
+
+Because the repository is private, this guide uses a secure workflow that works in most teams.
+
+## 1) Access Prerequisites
+
+Make sure you have:
+
+- A working company VPN connection (if required by network policy).
+- A Gitea account with access to `jig-software/trest`.
+- A Personal Access Token (PAT) in Gitea with at least repository read scope.
+- Git installed locally.
+
+Quick checks:
+
+```bash
+git --version
+ssh -T git@gitea.jig.com.hk
+```
+
+If SSH is not configured yet, follow section 2.
+
+## 2) Set Up Git Access
+
+Choose one method.
+
+### Option A: SSH (recommended)
+
+1. Generate a key if you do not already have one:
+
+```bash
+ssh-keygen -t ed25519 -C "your.name@company.com"
+```
+
+2. Start agent and add key:
+
+```bash
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+```
+
+3. Copy and add your public key to Gitea:
+
+```bash
+cat ~/.ssh/id_ed25519.pub
+```
+
+4. Test auth:
+
+```bash
+ssh -T git@gitea.jig.com.hk
+```
+
+### Option B: HTTPS + PAT
+
+Use HTTPS clone and enter your username + PAT when prompted.
+
+```bash
+git clone https://gitea.jig.com.hk/jig-software/trest.git
+```
+
+## 3) Clone and Inspect the Repository
+
+```bash
+git clone git@gitea.jig.com.hk:jig-software/trest.git
+cd trest
+```
+
+Collect quick project facts:
+
+```bash
+ls -la
+find . -maxdepth 2 -type f | head -50
+```
+
+Identify the ecosystem from marker files:
+
+- `package.json` -> Node.js package
+- `pyproject.toml` or `setup.py` -> Python package
+- `Cargo.toml` -> Rust crate
+- `go.mod` -> Go module
+
+## 4) Install Runtime and Dependencies
+
+Use the matching path below.
+
+### If `trest` is Node.js
+
+If your team distributes `trest` through Gitea Packages (npm registry), configure Yarn auth first.
+
+If Yarn is new to you, read `docs/yarn-basics-cheatsheet.md` first.
+
+#### Yarn 4 + Gitea Registry Setup
+
+This workspace already uses a scoped registry in `.yarnrc.yml`.
+
+Required scope assumptions:
+
+- Scope: `@jig-software`
+- Registry URL: `https://gitea.jig.com.hk/api/packages/jig-software/npm/`
+
+Set your token in the current shell:
+
+```bash
+export JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN="<your-gitea-token>"
+```
+
+Verify package access (recommended):
+
+```bash
+yarn npm info @jig-software/trest
+```
+
+Optional identity check (only if your Gitea npm endpoint supports whoami):
+
+```bash
+yarn npm whoami --scope jig-software
+```
+
+If package info is returned, install `trest`:
+
+```bash
+yarn add @jig-software/trest
+```
+
+If package naming differs, discover the exact name from your team or the Gitea Packages page, then run `yarn add <exact-package-name>`.
+
+#### Fallback: Install Directly From Gitea Git
+
+Use this when `trest` exists as a private repository but is not published in Gitea Packages npm.
+
+SSH form:
+
+```bash
+yarn add trest@git+ssh://git@gitea.jig.com.hk/jig-software/trest.git
+```
+
+HTTPS form:
+
+```bash
+yarn add trest@git+https://gitea.jig.com.hk/jig-software/trest.git
+```
+
+Pin to a branch, tag, or commit for reproducibility:
+
+```bash
+yarn add trest@git+ssh://git@gitea.jig.com.hk/jig-software/trest.git#main
+```
+
+```bash
+node -v
+npm -v
+npm ci
+npm test
+```
+
+Yarn note:
+
+- This repo uses Plug'n'Play (`nodeLinker: pnp`). If a tool expects `node_modules`, you can switch linker mode for that project.
+
+### If `trest` is Python
+
+```bash
+python3 --version
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -r requirements.txt
+pytest -q
+```
+
+### If `trest` is Rust
+
+```bash
+rustc --version
+cargo --version
+cargo test
+```
+
+### If `trest` is Go
+
+```bash
+go version
+go test ./...
+```
+
+## 5) Understand Package Usage Quickly
+
+Work top-down with this sequence:
+
+1. Read `README.md` and `docs/` first.
+2. Find entry points:
+   - Node: `main`, `exports`, `src/index.*`
+   - Python: package `__init__.py`, public modules
+   - Rust: `src/lib.rs`, `src/main.rs`
+   - Go: exported symbols in key package files
+3. Locate examples/tests to learn intended behavior.
+4. Build a tiny local consumer project and call the simplest public API.
+
+Search commands:
+
+```bash
+rg "example|usage|quick start|getting started|test" -n .
+rg "export|public|def |class |func " -n src tests .
+```
+
+## 6) Create a Minimal Consumer Sandbox
+
+In a separate directory, create a tiny app that imports `trest` and performs one happy-path call.
+
+Suggested structure:
+
+```text
+sandbox/
+  README.md
+  <language standard files>
+  smoke_test.*
+```
+
+Your first smoke test should validate:
+
+- Package can be installed or linked.
+- Import works.
+- One primary API call returns expected output.
+- Error handling behavior for invalid input is understood.
+
+## 7) Team Questions to Ask Early
+
+Ask these within your first day to avoid drift:
+
+- Which branch/tag/version should new projects consume?
+- Is there a compatibility matrix (runtime versions, OS, architecture)?
+- What APIs are stable vs experimental?
+- Any required env vars, secrets, or service dependencies?
+- Preferred testing strategy for downstream consumers?
+
+## 8) Troubleshooting
+
+- `404`/auth failures: confirm VPN, permissions, token scope, and clone URL.
+- SSL/cert issues: check corporate certificate installation and git SSL settings.
+- Install failures: pin runtime version from project config files (`.nvmrc`, `pyproject`, etc.).
+- Test failures: run a single test first, then expand scope.
+
+## 9) Onboarding Completion Checklist
+
+You are done when all are true:
+
+- [ ] Can clone `jig-software/trest` locally.
+- [ ] Can install dependencies successfully.
+- [ ] Can run test suite (or at least smoke tests).
+- [ ] Can explain top 3 public APIs in your own words.
+- [ ] Have written notes on setup steps and pitfalls for the team.