# nvuillam/npm-groovy-lint architecture

> Architecture diagram of the GitHub repository nvuillam/npm-groovy-lint, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvuillam/npm-groovy-lint
- Repository: https://github.com/nvuillam/npm-groovy-lint

## Overview

##### Project type and purpose
- This is an open‐source CLI/NPM package (“npm-groovy-lint”) that provides Groovy/Jenkinsfile linting, formatting and auto-fix capabilities by wrapping the CodeNarc engine in a Node.js interface and a lightweight Java/Groovy microservice.
- Key use cases: local CLI tool, CI/CD integration (Jenkins, CircleCI, GitHub Actions/Mega-Linter), VSCode extension, Docker image.

##### File structure
- Top-level:
- package.json, index.d.ts, lib/ – Node.js code (CLI, module API, filters, rules loader, Java launcher)
- groovy/src/main/com/nvuillam – Groovy microservice code (CodeNarcServer, filters, request/response handlers)
- lib/java – All JAR dependencies used by the microservice (CodeNarc, Groovy, logging, etc.)
- scripts/ – Build/deploy helper scripts (assemble server, update jars, VSCode integration)
- test/ – Jest/Mocha tests for the Node.js API and CLI behaviors
- docs/ – MkDocs documentation, images and assets
- CI config: .github/workflows, .dockerignore, Dockerfile
- Patterns & architectural choices:
- “Client/server” within one package: Node.js acts as CLI “client,” Groovy/Java as microservice “server”
- NPM module exposes both CLI and programmatic API
- CodeNarcServer (Groovy HTTP server with Gzip, Logging and Tracing filters)
- Java-caller module to spawn/manage the Java process

##### README for additional insights
- Describes workflow: Node CLI invokes Java microservice (unless --noserver) to improve performance by reusing one JVM.
- Explains configuration, rule sets, auto-fix, format, logging, output formats.
- Shows various integration points: VSCode extension, Docker, Mega-Linter, CI pipelines.

##### Elements
- Orange parallelograms for external systems (CI, Docker, IDE)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    UserCI["User / CI / IDE"]:::external

    %% Node.js Layer
    subgraph "Node.js Layer"
        CLI["Node.js CLI"]:::node
        API["NPM Module API"]:::node
        Config["Configuration Loader"]:::node
        Options["Command-line Options Parser"]:::node
        Caller["Java Caller / Process Manager"]:::node
        Rules["Rule Definitions & Plugin Loader"]:::node
        FSscan["File System Scanner & Core Logic"]:::node
        Fix["Auto-fix & Formatter Engine"]:::node
        OutputFormatter["Output Formatter & Writers"]:::node
        Types["TypeScript Definitions"]:::node
    end

    %% Java/Groovy Layer
    subgraph "Groovy/Java Layer"
        Server["Groovy HTTP Microservice Server"]:::java
        GzipFilter["Gzip Filter"]:::java
        GzipExchange["HTTP Exchange & Compression Handler"]:::java
        LoggingFilter["Logging Filter"]:::java
        TracingFilter["Tracing Filter"]:::java
        ReqResp["Request & Response Models"]:::java
        CapWriter["Captured Report Writer"]:::java
        CapturePlugin["Capture Plugin"]:::java
        Jars["JAR Dependencies"]:::java
    end

    %% File System & Config
    subgraph "File System & Config"
        FS["File System"]:::fs
        ConfigFile[".groovylintrc / Other Config"]:::fs
    end

    %% Output Layer
    Reports["Reports (Console / JSON / SARIF / HTML / XML)"]:::output

    %% Connections
    UserCI -->|"invoke CLI"| CLI
    CLI -->|"load options"| Options
    CLI -->|"load config"| Config
    CLI -->|"expose API"| API
    CLI -->|"spawn/connect"| Caller
    Caller -->|"HTTP calls"| Server
    CLI -->|"scan files"| FSscan
    FSscan -->|"reads"| FS
    Server -->|"loads plugins & rules"| Jars
    Server -->|"GzipHttpExchange pipeline"| GzipExchange
    GzipExchange --> GzipFilter
    GzipExchange --> LoggingFilter
    GzipExchange --> TracingFilter
    Server -->|"uses filters"| GzipFilter
    Server -->|"uses filters"| LoggingFilter
    Server -->|"uses filters"| TracingFilter
    Server -->|"process requests"| ReqResp
    Server -->|"writes reports"| CapWriter
    Server -->|"extends CodeNarc"| CapturePlugin
    Server -->|"responses"| CLI
    CLI -->|"process results"| Fix
    Fix -->|"apply patches"| FS
    CLI -->|"format/write output"| OutputFormatter
    OutputFormatter --> Reports
    Reports --> UserCI

    %% Click Events
    click CLI "https://github.com/nvuillam/npm-groovy-lint/blob/main/lib/groovy-lint.js"
    click API "https://github.com/nvuillam/npm-groovy-lint/blob/main/lib/index.js"
    click Config "https://github.com/nvuillam/npm-groovy-lint/blob/main/lib/config.js"
    click Options "https://github.com/nvuillam/npm-groovy-lint/blob/main/lib/options.js"
    click Caller "https://github.com/nvuillam/npm-groovy-lint/blob/main/lib/codenarc-caller.js"
    click Caller "https://github.com/nvuillam/npm-groovy-lint/blob/main/lib/codenarc-factory.js"
    click Rules "https://github.com/nvuillam/npm-groovy-lint/tree/main/lib/rules/"
    click FSscan "https://github.com/nvuillam/npm-groovy-lint/blob/main/lib/groovy-lint-rules.js"
    click Fix "https://github.com/nvuillam/npm-groovy-lint/blob/main/lib/groovy-lint-fix.js"
    click OutputFormatter "https://github.com/nvuillam/npm-groovy-lint/blob/main/lib/output.js"
    click Types "https://github.com/nvuillam/npm-groovy-lint/blob/main/index.d.ts"
    click Server "https://github.com/nvuillam/npm-groovy-lint/blob/main/groovy/src/main/com/nvuillam/CodeNarcServer.groovy"
    click GzipFilter "https://github.com/nvuillam/npm-groovy-lint/blob/main/groovy/src/main/com/nvuillam/GzipFilter.groovy"
    click GzipExchange "https://github.com/nvuillam/npm-groovy-lint/blob/main/groovy/src/main/com/nvuillam/GzipHttpExchange.groovy"
    click LoggingFilter "https://github.com/nvuillam/npm-groovy-lint/blob/main/groovy/src/main/com/nvuillam/LoggingFilter.groovy"
    click TracingFilter "https://github.com/nvuillam/npm-groovy-lint/blob/main/groovy/src/main/com/nvuillam/TracingFilter.groovy"
    click ReqResp "https://github.com/nvuillam/npm-groovy-lint/blob/main/groovy/src/main/com/nvuillam/Request.groovy"
    click ReqResp "https://github.com/nvuillam/npm-groovy-lint/blob/main/groovy/src/main/com/nvuillam/Response.groovy"
    click CapWriter "https://github.com/nvuillam/npm-groovy-lint/blob/main/groovy/src/main/com/nvuillam/CapturedReportWriter.groovy"
    click CapturePlugin "https://github.com/nvuillam/npm-groovy-lint/blob/main/groovy/src/main/com/nvuillam/CapturePlugin.groovy"
    click Jars "https://github.com/nvuillam/npm-groovy-lint/tree/main/lib/java/"

    %% Styles
    classDef node fill:#D6EAF8,stroke:#1B4F72
    classDef java fill:#D5F5E3,stroke:#186A3B
    classDef fs fill:#F4F6F6,stroke:#7B7D7D
    classDef external fill:#FADBD8,stroke:#922B21
    classDef output fill:#FCF3CF,stroke:#B7950B
```
