If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/vipshop/vjtools shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 16 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 67% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live vipshop/vjtools repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/vipshop/vjtools.

What it runs against: a local clone of vipshop/vjtools — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in vipshop/vjtools | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1005 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of vipshop/vjtools. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/vipshop/vjtools.git
#   cd vjtools
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of vipshop/vjtools and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "vipshop/vjtools(\\.git)?\\b" \\
  && ok "origin remote is vipshop/vjtools" \\
  || miss "origin remote is not vipshop/vjtools (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f "vjkit/pom.xml" \\
  && ok "vjkit/pom.xml" \\
  || miss "missing critical file: vjkit/pom.xml"
test -f "standard/sonar-vj/pom.xml" \\
  && ok "standard/sonar-vj/pom.xml" \\
  || miss "missing critical file: standard/sonar-vj/pom.xml"
test -f "vjkit/src/main/java/com/vip/vjtools/vjkit/base/ExceptionUtil.java" \\
  && ok "vjkit/src/main/java/com/vip/vjtools/vjkit/base/ExceptionUtil.java" \\
  || miss "missing critical file: vjkit/src/main/java/com/vip/vjtools/vjkit/base/ExceptionUtil.java"
test -f "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/SonarPlugin.java" \\
  && ok "standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/SonarPlugin.java" \\
  || miss "missing critical file: standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/SonarPlugin.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1005 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~975d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/vipshop/vjtools"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

VJTools is Vip.com's curated Java standard, core libraries, and production JVM diagnostic tools. It provides code style guides, Sonar rule customizations, utility libraries (vjkit for collections/concurrency, vjstar for performance patterns), and CLI tools (vjtop, vjmap, vjdump, vjmxcli) for observing JVM metrics, heap analysis, and thread profiling without requiring IDE GUI. Multi-module Maven monorepo: /standard contains formatter templates and sonar-vj plugin (Java SonarQube rule implementations); /vjkit and /vjstar are core libraries; /vjtop, /vjmap, /vjdump, /vjmxcli are standalone CLI tools each with their own executable shells. Documentation lives in /docs with separate standard guide chapters in /docs/standard/. Root pom.xml activates modules conditionally by JDK version.

Java backend engineers at Vip.com and other enterprises who need standardized coding practices, production-grade JVM diagnostics tools that work in headless server environments, and reusable utilities for text/collection/concurrency operations. DevOps teams use vjdump and vjtop to troubleshoot live JVM performance issues.

Production-ready and actively maintained. Released v1.0.8 in September 2018 with ongoing snapshot development (v1.0.9-SNAPSHOT). Includes CI/CD via Travis CI, proper Maven release pipeline to Sonatype OSS repository, and a documented developer team. No signs of abandonment, though primary development pace appears measured rather than rapid.

Low risk for established Java shops but moderate dependency on JDK version (separate profiles for JDK 7/8/9 suggest compatibility fragility). Sonar-vj module only builds on JDK 8+, limiting adoption on legacy systems. Open to community contributions but maintained primarily by Vip.com team; small maintainer pool for such a core standardization tool. No visible security audit history.

Last visible activity is v1.0.8 release (Sept 2018) with v1.0.9-SNAPSHOT in active development. Repo accepts Pull Requests and Issues; team mentions WeChat group (viptech128) for community discussion and VIP.com gift card rewards for quality contributions. No specific recent commits visible in provided metadata, suggesting maintenance rather than heavy active development.

git clone https://github.com/vipshop/vjtools.git && cd vjtools && mvn clean install -DskipTests. Builds with Maven 3.x and Java 7+. To use individual tools: cd vjtop && mvn clean package, then run ./vjtop.sh (shell scripts in each tool directory). Documentation is in /docs with docsify served at docs/index.html.

Daily commands: Clone and run mvn clean install. Individual tools are executed via shell: ./vjtop.sh <pid> (observe JVM metrics), ./vjmap.sh <pid> (heap dump analysis), ./vjdump.sh <pid> (collect diagnostics). Each tool directory (/vjtop, /vjmap, etc.) contains README with usage examples and parameters.

• pom.xml — Root Maven POM defining the multi-module project structure, versions, and distribution configuration for all vjtools subprojects
• vjkit/pom.xml — Core library module POM; vjkit is the foundation for text, collection, and concurrency utilities used across tools
• standard/sonar-vj/pom.xml — SonarQube plugin module defining Java coding standard checks; establishes organizational code quality baseline
• vjkit/src/main/java/com/vip/vjtools/vjkit/base/ExceptionUtil.java — Core utility for exception handling patterns; fundamental to vjkit's error handling philosophy across all modules
• standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/SonarPlugin.java — SonarQube plugin entry point; integrates custom VJTools rules into code quality pipeline
• README.md — Project overview documenting all four tool suites (vjtools standards, vjkit, vjstar, vjtop/vjmap/vjdump/vjmxcli) and their relationships
• docs/standard/README.md — Java coding standard documentation hub; defines conventions that sonar-vj, formatters, and all projects enforce

Add a new SonarQube static analysis rule

1. Create new check class extending SonarQube Check API in standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/ (standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/YourNewCheck.java)
2. Register check in rule registry to expose it to SonarQube engine (standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/SonarRulesList.java)
3. Add rule metadata JSON file with description, severity, and examples (standard/sonar-vj/src/main/resources/com/vip/java/rules/SXXX_java.json)
4. Add rule documentation HTML file for SonarQube UI display (standard/sonar-vj/src/main/resources/com/vip/java/rules/SXXX_java.html)

Add a new utility class to VJKit core library

1. Create new utility class in vjkit/src/main/java/com/vip/vjtools/vjkit/base/ following naming convention UtilityNameUtil.java (vjkit/src/main/java/com/vip/vjtools/vjkit/base/NewUtil.java)
2. Add @Nullable and @NotNull annotations from vjkit.base.annotation package to document null-safety contracts (vjkit/src/main/java/com/vip/vjtools/vjkit/base/annotation/NotNull.java)
3. Update vjkit/pom.xml if new external dependencies are required (vjkit/pom.xml)

Extend Java coding standard documentation

1. Add or edit standard documentation chapter in docs/standard/chapter0X.md (chapters 01-12 exist) (docs/standard/chapter01.md)
2. Update main standard README to link new/modified chapters (docs/standard/README.md)
3. Implement corresponding SonarQube check to enforce new standard rule programmatically (standard/sonar-vj/src/main/java/com/vip/vjkit/sonarvj/checks/)

• Maven multi-module POM — Manages four distinct tool suites (standards, vjkit library, vjstar, JVM tools) with shared versioning and consistent build lifecycle
• SonarQube plugin API — Enables organizational enforcement of Java coding standards as automated static analysis rules, integrating into CI/CD pipelines
• IDE formatter XML configs — Distributes formatting conventions to Eclipse and IntelliJ so developers auto-format code matching standards without manual effort
• Shell scripts (vjdump.sh) — Provides low-overhead, production-safe mechanism to collect JVM diagnostics without requiring Java process restart

• SonarQube plugin for standard enforcement vs. embedded build-time checkers

  • Why: SonarQube provides centralized rule management, UI reporting, and trend tracking across organization
  • Consequence: Requires SonarQube server deployment; discovery of violations happens post-build rather than at compile time

• Separate vjkit core library vs. inline utility methods

  • Why: Shared library ensures consistent exception handling, null-safety annotations, and utility implementations across all VIP tools
  • Consequence: Adds dependency management complexity; any vjkit bug affects all dependent projects

• IDE formatter config distribution vs. automated code rewrite tooling

  • Why: Formatters are IDE-native and require zero configuration beyond importing XML; developers see corrections immediately
  • Consequence: Formatters only catch style issues, not logical violations (SonarQube handles semantic rules)

• Does not provide runtime monitoring dashboard—vjtop/vjdump are CLI-only tools for emergency diagnostics, not continuous monitoring UI
• Does not handle Java versions pre-Java 8—targeting modern JVM features and conventions
• Not a replacement for code review—standards and tools support human review, not substitute for it
• Does not include application framework or web serving—vjtools are libraries and standalone utilities, not app containers

JDK version mismatch: sonar-vj only builds with JDK 8+; JDK 9 profile excludes sonar-vj, which can confuse CI/CD. CLI tools (vjtop, vjmap, vjdump) require target JVM process to have JMX enabled (or jmap/jstack available); will silently fail if security manager blocks access. Shell scripts assume Linux/Unix environment; Windows users must use .bat variants in /vjdump. Documentation is in Chinese (Markdown in /docs/standard/); English-language README exists only for vjdump. Sonar rule checks depend on SonarQube AST visitor patterns; adding new checks requires deep SonarSource plugin API knowledge.

• SonarQube Custom Rule Plugin — VJTools sonar-vj demonstrates how to extend SonarQube with enterprise-specific code quality rules; essential for understanding custom check registration and AST visitor patterns in /standard/sonar-vj/
• JMX (Java Management Extensions) — vjtop and vjmxcli rely on JMX to expose JVM metrics (thread count, memory, GC) at runtime; critical for understanding how these diagnostic tools query live JVM state without code instrumentation
• Heap Dump Analysis & Generational GC — vjmap prints heap dumps by generation/age; requires understanding of Java GC regions (young, old, metaspace) to effectively diagnose memory leaks in production
• Code Formatter Templates (Eclipse/IDEA) — VJTools enforces style via IDE plugins (/standard/formatter/); understanding how to distribute and apply formatter profiles ensures team-wide code consistency without manual linting
• Maven Multi-Module Monorepo with Conditional Profiles — VJTools root pom.xml uses profiles to activate different modules per JDK version (jdk7, jdk8, jdk9); essential pattern for managing Java version compatibility across a large codebase
• Thread Profiling & Busy Thread Detection — vjtop identifies which threads consume CPU; core capability for production diagnostics when application is slow, requires understanding of JVM thread state and CPU time sampling
• AST Visitor Pattern (SonarSource Plugin API) — sonar-vj checks (BadConstantNameCheck, HardcodedIpCheck, etc.) walk Java AST using Visitor pattern; core design pattern for static analysis that new rule contributors must understand

• alibaba/druid — Alibaba's Java connection pool and monitoring library; overlaps with vjstar's performance best practices for database connections
• eclipse/eclipse.jdt.core — Eclipse JDT provides formatter configuration; VJTools supplies Sonar rule plugins that integrate with similar AST analysis patterns
• SonarSource/sonarqube — SonarQube is the hosting platform for sonar-vj custom rules; VJTools plugin extends SonarQube's core checking framework
• openjdk/jdk — JDK source; VJTools tools (vjtop, vjmap, vjdump) directly invoke JDK tools (jmap, jstack, jstat) and depend on JVM stability
• google/guava — Google's Java core library; vjkit provides similar utilities for collections, concurrency, and text, positioned as Vip.com's alternative

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for SonarQube rule checks in standard/sonar-vj

The sonar-vj module contains 8 check implementations (BadConstantNameCheck, CatchUsesExceptionWithContextCheck, HardcodedIpCheck, MissingCurlyBracesCheck, NoSonarCheck, OperatorPrecedenceCheck, UnusedMethodParameterCheck, UnusedPrivateFieldCheck) but there's no src/test directory visible. Each check needs unit tests to verify the AST detection logic works correctly before users adopt these rules. This is critical for a code quality tool.

• [ ] Create standard/sonar-vj/src/test/java/com/vip/vjkit/sonarvj/checks/ directory structure
• [ ] Add unit test class for each check (e.g., BadConstantNameCheckTest.java using SonarQube's CheckVerifier)
• [ ] Add positive and negative test case files in src/test/resources/ for rule validation
• [ ] Ensure tests run in CI via .travis.yml Maven build configuration

Add English documentation for vjdump script in vjdump/README_EN.md

The README.md references vjdump/README_EN.md in the table but the file appears incomplete (cut off in the snippet). The vjdump tool is critical for online JVM data collection and non-Chinese speaking users need complete English documentation to use this tool effectively.

• [ ] Complete vjdump/README_EN.md with installation, usage, and example sections
• [ ] Mirror the structure and content from vjdump/README.md (Chinese version)
• [ ] Include command-line options, output explanation, and troubleshooting sections
• [ ] Add real-world usage examples for collecting heap dumps, thread dumps, and GC logs

Migrate from Travis CI to GitHub Actions workflow

The project uses .travis.yml for CI but GitHub Actions provides better integration, faster execution, and no external service dependency. The current .travis.yml only shows a fragment and needs modernization. This improves maintainability and reduces external dependencies.

• [ ] Create .github/workflows/build.yml for Maven builds across JDK 7, 8, and 9 profiles
• [ ] Configure matrix strategy to test all three JDK versions matching the existing pom.xml profiles
• [ ] Add artifact upload for releases and coverage reports if used
• [ ] Keep .travis.yml for backward compatibility but document the migration in CONTRIBUTING.md

• Add English translations for /docs/standard/chapter01.md through chapter12.md; currently only Chinese exists, blocking non-Chinese-speaking teams from adopting the standard. Start by forking and translating one chapter with equivalent code examples.
• Write unit tests for vjkit core utilities in /vjkit/src/test/java (text, collection, concurrency helpers); repo structure has test directory but many utility classes lack coverage. Pick one utility class and add 10+ test cases covering edge cases.
• Add Windows .bat wrapper scripts for vjtop and vjmap in /vjtop and /vjmap directories; currently only .sh scripts exist, limiting Windows developer adoption. Model after existing /vjdump/vjdump.bat pattern.

The vjtools project demonstrates reasonable security hygiene as a code standards and tools repository, but has areas for improvement. Primary concerns include outdated build infrastructure (old parent POM version), use of snapshot versions for what appears to be a published library, and incomplete POM configuration. The project is primarily a standards/documentation repository rather than a runtime application, which reduces exposure to common web vulnerabilities. No hardcoded credentials or obvious injection vulnerabilities were detected in the visible file structure. Recommendations focus on updating build infrastructure, completing POM configuration, and implementing proper version management practices.

• Medium · Outdated Parent POM Version — pom.xml - parent section. The project uses org.sonatype.oss:oss-parent version 7, which is significantly outdated (released around 2012-2013). This parent POM likely contains outdated plugin versions and may not include important security fixes for Maven plugins. Fix: Upgrade to a more recent version of oss-parent or migrate to Maven Central's modern parent POM. Review and update all transitive dependencies.
• Medium · Snapshot Version in Production — pom.xml - version tag. The project version is set to '1.0.9-SNAPSHOT', indicating it's a snapshot/development version. Using snapshot versions in production releases can lead to non-reproducible builds and unpredictable behavior due to continuous updates. Fix: Use release versions for production deployments. Only use SNAPSHOT versions during active development. Implement proper version management and release procedures.
• Low · Incomplete POM Plugin Configuration — pom.xml - release profile, plugins section. The pom.xml appears to be truncated in the release profile's plugin section (ending with '<g'), suggesting incomplete or corrupted configuration. This could lead to unexpected build behavior. Fix: Complete and validate the POM configuration. Ensure all XML is well-formed and all plugin configurations are complete. Run 'mvn validate' to catch configuration errors.
• Low · Missing Security Headers Configuration — docs/ directory - web server configuration. The project structure shows web documentation (docs directory with HTML files) but no visible security configuration for HTTP headers such as Content-Security-Policy, X-Frame-Options, or X-Content-Type-Options. Fix: Configure appropriate security headers in the web server hosting the documentation. For GitHub Pages, verify all content is served over HTTPS and configure appropriate CSP policies if applicable.
• Low · No Explicit Dependency Management — pom.xml - missing dependencyManagement section. The provided POM snippet shows no explicit dependency management section or dependency version pinning strategy. This can lead to version conflicts and unexpected transitive dependency updates. Fix: Add a dependencyManagement section to explicitly manage all dependency versions. Use version ranges carefully and prefer exact versions for security-sensitive dependencies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.