LazyGophers Utils - Project Knowledge Base

Generated: 2026-03-09 Scope: repo root

OVERVIEW

Go 1.25 utility library with 20+ public root-level packages.
Flat layout: no cmd/, pkg/, or internal/; packages live directly under repo root.
Main themes: generics, performance helpers, multilingual data/validation, concurrency, cache algorithms.

Read this file first for repo-wide rules.
Read cache/AGENTS.md for cache algorithm selection and trade-offs.
Read atexit/AGENTS.md for shutdown callback behavior and platform-specific exit handling.
Read xtime/AGENTS.md for lunar calendar, solar term, and work-schedule time logic.
Packages without a local AGENTS.md inherit this root guidance.

Root files: must.go, orm.go, validate.go.
Data + conversion: candy/, json/, stringx/, anyx/, defaults/.
Time + schedules: xtime/.
System + lifecycle: runtime/, atexit/, app/, osx/, config/.
Reliability + concurrency: cache/, routine/, wait/, hystrix/, singledo/, event/.
Security + network: cryptox/, pgp/, network/, urlx/.
Test/support data: fake/, randx/, pyroscope/, validator/.

Task	Location	Notes
fail-fast helpers	`must.go`	`Must`, `MustSuccess`, `MustOk`
DB JSON scan/value	`orm.go`	wraps JSON encode/decode for DB fields
root validation entry	`validate.go`, `validator/`	root helper delegates to validator package
cache policy choice	`cache/`	algorithm-heavy; use child doc
graceful shutdown	`atexit/`	build-tagged platform implementations
advanced time logic	`xtime/`	lunar calendar, solar terms, 007/955/996 subpackages
fake data generation	`fake/`	locale-specific embedded datasets and faker defaults
runtime helpers	`runtime/`	panic capture, stack dumping, executable/user dir helpers
i18n validation engine	`validator/`	locale files + custom validation engine

Prefer existing root-level package structure; do not introduce deep hierarchy casually.
Code is primarily English; docs should support English and Simplified Chinese.
Many packages keep llms.txt; treat them as hints, not source of truth.
Use generics where the package already does.
Library code should return errors explicitly; only Must* helpers are expected to panic.
This repo prefers github.com/lazygophers/log for logging.
Tests are typically English-named and often split into normal tests plus *_coverage_test.go edge coverage files.

cache/: multiple algorithms with different eviction semantics; avoid generic advice here.
fake/: heavy locale/embed surface area; verify actual dataset loaders before changing behavior.
validator/: custom engine + per-locale messages; check field-name strategy before editing messages.
runtime/: includes OS-specific signal/path helpers; distinguish generic helpers from platform files.
atexit/: callback execution semantics vary by OS family.
xtime/: domain rules are calendar-specific, not generic date helpers.

Do not add child AGENTS.md files just because a package is large; add them only when local rules diverge materially.
Do not trust generated or stale llms.txt content over source.
Do not use panic() in ordinary library paths outside the Must* model.
Do not ignore returned errors in non-Must code.
Do not introduce circular dependencies between root packages.

make fmt
make lint
make test
make check

Coverage badge in README.md currently shows overall coverage below the aspirational threshold; preserve existing test style instead of inventing new structure.
human/ is excluded from some coverage flows.
Multi-platform behavior is real in this repo: build tags and cross-platform files are common enough to inspect before editing.