Skip to content

Update README for 0.44.0 #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ClankerGuru merged 1 commit into from
Apr 13, 2026
Merged

Update README for 0.44.0 #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 112 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,66 +1,140 @@
# srcx

[![GitHub release](https://img.shields.io/github/v/release/ClankerGuru/srcx)](https://github.com/ClankerGuru/srcx/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Kotlin](https://img.shields.io/badge/Kotlin-2.1.20-7F52FF.svg)](https://kotlinlang.org)
[![Gradle](https://img.shields.io/badge/Gradle-9.x-02303A.svg)](https://gradle.org)
[![Build](https://github.com/ClankerGuru/srcx/actions/workflows/build.yml/badge.svg)](https://github.com/ClankerGuru/srcx/actions/workflows/build.yml)
[![Maven Central](https://img.shields.io/maven-central/v/zone.clanker/plugin-srcx?label=Maven%20Central)](https://central.sonatype.com/artifact/zone.clanker/plugin-srcx)
[![Kotlin](https://img.shields.io/badge/Kotlin-2.3.0-purple)](https://kotlinlang.org)
[![Gradle](https://img.shields.io/badge/Gradle-9.4.1-green)](https://gradle.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](https://opensource.org/licenses/MIT)

Source symbol extraction, architecture analysis, and LLM-ready context generation for Gradle projects.
**Source symbol extraction, architecture analysis, and LLM-ready context generation for Gradle projects.**

## Package Structure
Scans your codebase — including all included builds in a workspace — and generates structured Markdown reports: hub classes, entry points, anti-patterns, interfaces, and cross-build dependencies. Designed for AI agents that need codebase context.

## Quick start

```kotlin
// settings.gradle.kts
plugins {
id("zone.clanker.gradle.srcx") version "latest"
}

srcx {
outputDir.set(".srcx")
forbiddenPackages("legacy", "compat")
forbiddenClassPatterns("Base", "Impl")
}
```

```bash
./gradlew srcx-context # generate context report
./gradlew srcx-clean # delete all .srcx output
```

## Generated reports

| File | Description |
|------|-------------|
| `context.md` | Dashboard: symbol counts, warnings, links to included builds |
| `hub-classes.md` | Most-depended-on classes with dependency trees across all builds |
| `entry-points.md` | App, test, and mock entry points classified by kind |
| `anti-patterns.md` | Code smells: god classes, circular deps, forbidden names, DI violations |
| `interfaces.md` | Interface coverage: implementations, missing mocks |
| `cross-build.md` | Shared classes referenced across build boundaries |

Reports are aggregated from per-build analysis — works reliably on large repos with many included builds.

## DSL reference

```kotlin
srcx {
outputDir.set(".srcx") // output directory (default: .srcx)
autoGenerate.set(true) // regenerate on every compile
excludeDepScopes.add("kotlinScriptDef") // dependency scopes to skip
forbiddenPackages("utils", "helpers") // additional forbidden package names
forbiddenClassPatterns("Helper", "Mgr") // additional forbidden class suffixes
}
```

**Default forbidden packages:** `util`, `utils`, `helper`, `helpers`, `manager`, `managers`, `misc`, `base`

**Default forbidden class patterns:** `Helper`, `Manager`, `Utils`, `Util`

## Package structure

### `model/`

All data types used across srcx. Contains value classes with validation (`SymbolName`, `PackageName`, `FilePath`, `ArtifactGroup`, `ArtifactName`, `ArtifactVersion`, `ProjectPath`), basic extraction types (`SymbolEntry`, `SymbolKind`, `DependencyEntry`, `ProjectSummary`), and PSI-level types for deep source analysis (`Symbol`, `SymbolDetailKind`, `Reference`, `ReferenceKind`, `MethodCall`, `VerifyAssertion`).
Data types: value classes with validation (`SymbolName`, `PackageName`, `FilePath`, `ProjectPath`), extraction types (`SymbolEntry`, `DependencyEntry`, `ProjectSummary`), and analysis summaries (`AnalysisSummary`, `HubClass`, `Finding`).

### `parse/`

Source parsing and symbol indexing using the Kotlin compiler PSI. Handles `.kt`, `.java`, and `.gradle.kts` files.
PSI-based source parsing using the Kotlin compiler embeddable.

- **PsiEnvironment** -- manages the `KotlinCoreEnvironment` lifecycle for PSI parsing outside IntelliJ.
- **PsiParser** -- extracts declarations and references from Kotlin, Java, and Gradle script files using PSI AST traversal.
- **SourceScanner** -- discovers source directories across Java, Kotlin JVM, and KMP projects.
- **SymbolIndex** -- cross-referenced index of all symbols and references. Powers find-usages, call-graph construction, and usage counting.
- **PsiEnvironment** — manages a shared `KotlinCoreEnvironment` instance. Thread-safe singleton — the IntelliJ platform is initialized exactly once and reused across all analysis calls.
- **PsiParser** — extracts declarations and references from `.kt`, `.java`, and `.gradle.kts` files.
- **SourceScanner** — discovers source directories across Java, Kotlin JVM, and KMP projects.
- **SymbolIndex** — cross-referenced index of all symbols and references.

### `analysis/`

Architecture analysis operating on parsed source metadata. Classifies components by role, builds dependency graphs, detects anti-patterns, and generates Mermaid diagrams.
Architecture analysis on parsed source metadata.

- **ComponentClassifier** -- classifies source files by architectural role (Controller, Service, Repository, Entity, etc.) using annotations and naming conventions.
- **DependencyAnalyzer** -- builds a directed dependency graph between components using import analysis and supertype resolution. Finds hub classes and detects circular dependencies.
- **AntiPatternDetector** -- detects code smells (Manager/Helper/Util classes), god classes, deep inheritance, single-implementation interfaces, circular dependencies, and missing tests.
- **DiagramGenerator** -- generates Mermaid flowchart and sequence diagrams from the dependency graph.
- **SourceFileMetadata** -- lightweight source file parser for structural metadata extraction.
- **ComponentClassifier** — classifies source files by role (Controller, Service, Repository, Entity) using annotations and naming conventions.
- **DependencyAnalyzer** — builds dependency graphs, finds hub classes, detects circular dependencies.
- **AntiPatternDetector** — detects god classes, forbidden names, DI violations, missing tests, circular deps.
- **DiagramGenerator** — generates Mermaid diagrams from the dependency graph.
- **SourceFileMetadata** — lightweight structural metadata extraction.

### `report/`

Markdown report generators.

- **DashboardRenderer** -- renders the comprehensive context report with overview, build dependency graph, symbols, and problems.
- **ProjectReportRenderer** -- renders per-project symbol and dependency tables.
- **IncludedBuildRenderer** -- renders per-build context for included builds.
- **DashboardRenderer** — workspace-level overview with included build table and split file links.
- **HotClassesRenderer** — hub classes ranked by dependent count with dependency trees.
- **EntryPointsRenderer** — app/test/mock entry point classification.
- **AntiPatternsRenderer** — per-build anti-pattern findings grouped by severity.
- **CrossBuildRenderer** — shared hub classes and cycles across build boundaries.
- **InterfacesRenderer** — interface coverage with implementation counts (excludes mocks).
- **ProjectReportRenderer** — per-project symbol and dependency tables.
- **IncludedBuildRenderer** — per-build context for included builds.

## Usage
### `scan/`

```kotlin
// settings.gradle.kts
plugins {
id("zone.clanker.gradle.srcx") version "0.1.0"
}
Gradle model integration.

srcx {
outputDir = ".srcx"
autoGenerate = true // regenerate on every compile
}
```
- **ProjectScanner** — discovers source sets and projects using the Gradle API.
- **SymbolExtractor** — extracts symbols and dependencies from Gradle project data. Runs `analyzeProject()` per build with OOM error handling.

### `task/`

- **ContextTask** — generates all reports. Aggregates hub classes and entry points from per-build analysis (no monolithic cross-build parse). Cleans up PSI environment when done.
- **CleanTask** — deletes all `.srcx` output directories.

## How it works

1. Plugin reads DSL configuration at settings evaluation time
2. `ContextTask` runs symbol extraction per project in parallel
3. Per-build analysis runs `analyzeProject()` (PSI parsing → component classification → dependency graph → anti-patterns → hub classes)
4. Results aggregated at workspace level — hub classes merged and ranked across all builds
5. Split detail files written alongside the dashboard
6. PSI environment shared as a thread-safe singleton (one init, reused, closed at end)

Analysis failures (OOM, classpath conflicts) log actionable errors instead of silently returning empty results.

## Dependencies

- `org.jetbrains.kotlin:kotlin-compiler-embeddable` — PSI parsing for Kotlin, Java, and Gradle scripts
- Kotest 5.9.1 + Konsist 0.17.3 — testing and architecture enforcement
- Kover — 95% minimum line coverage enforcement

## Contributing

```bash
./gradlew srcx-context # generate context report (symbols + analysis + diagrams)
./gradlew srcx-clean # delete all .srcx output
git clone git@github.com:ClankerGuru/srcx.git
cd srcx
git config core.hooksPath config/hooks
./gradlew build # compile + test + detekt + ktlint + coverage
```

## Dependencies
## License

- `org.jetbrains.kotlin:kotlin-compiler-embeddable` (compileOnly) -- PSI parsing for Kotlin, Java, and Gradle scripts
- Kotest 5.9.1 + Konsist 0.17.3 -- testing and architecture enforcement
- Kover -- 95% minimum line coverage enforcement
[MIT](LICENSE)
Loading