Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,23 @@ releases; any change that moves scores is called out here.
(implicit members) and cargo-fuzz `fuzz/` crates are understood.
- Score effect: tokio 66 → 65 (9.4 unsafe/kloc), hugo 80 → 78 (15 any/kloc), zap types 100 → 95,
ripgrep 62 → 63 (workspace check passes); ollama, cobra, hyper and codex are unchanged overall.
- Basic Java/Kotlin support:
- Detection: a root `pom.xml`/`build.gradle(.kts)`/`settings.gradle(.kts)` with `.java`/`.kt`
files, or a significant share of JVM code. An `android/` folder in a JS app does not count.
- The existing checks now score the JVM side:
- `feedback.test`: tests under `src/test/` or `*Test`/`*IT`/`*Spec`, run via
`./mvnw test`/`mvn test`/`./gradlew test`.
- `feedback.lint`: checkstyle, spotless, PMD, SpotBugs, Error Prone, ktlint or detekt in the
build or config files (1.0), otherwise compiler warnings only (0.6).
- `feedback.typecheck`: compile. With `--run`, `feedback.typecheck-passes` runs
`mvn compile` / `./gradlew classes` (and `feedback.speed` runs the Maven/Gradle tests).
- `types.static`: Java/Kotlin count as compiler-checked.
- `--fix` generates Maven/Gradle build and test commands, and docs that list `./mvnw` commands
are recognized.
- `target/` (Maven, Cargo) is suggested for `.gitignore` when it is present, untracked and
not ignored.
- Score effect: Java repos used to be scored on CI alone, with type safety n/a. Now, for
example: gson 61 → 67, spring-petclinic 63 → 69, timber 58 → 64. No non-JVM repo moved.

### Changed

Expand Down
20 changes: 10 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ npx @mintwork/agent-ready # no install
npm i -D @mintwork/agent-ready # or pin it in your project
```

Node 22+. Zero runtime dependencies. Works on JS/TS and Python repos, with basic Go and Rust support. Read-only unless you pass `--fix`.
Node 22+. Zero runtime dependencies. Works on JS/TS and Python repos, with basic Go, Rust and Java/Kotlin support. Read-only unless you pass `--fix`.

## Usage

Expand Down Expand Up @@ -140,17 +140,17 @@ It also:

## What it checks

| Category | Weight | Checks |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Context docs** | 30% | `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` / Copilot / Gemini instructions exist · they list exact build, test and lint commands · they describe architecture and key directories · **not stale**: every referenced path and `npm run` script actually exists · **not drifting** (git history): a doc untouched for 90+ days while 25+ later commits changed the files it names or added/removed files in the dirs it describes · not too long (or too thin) · both `AGENTS.md` and `CLAUDE.md` so every agent is covered · `.cursor/rules/*.mdc` actually apply (frontmatter, globs that match files) · monorepos: large workspace packages have a nested `AGENTS.md` or are mentioned in the root docs |
| **Feedback loops** | 25% | A discoverable test command (package.json `test`, pytest config, `make test`, `cargo test`, `go test`) · linter configured (eslint, biome, oxlint, ruff, flake8, clippy, golangci-lint) · typecheck command (`tsc`, mypy, pyright) · CI config · MCP server configs (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`) and Claude Code hooks are valid · Rust: one cargo workspace reaches every crate (nested workspaces and orphan crates flagged; path deps and `fuzz/` understood) · `--run`: test suite passes and is fast, lint and typecheck pass, `--flaky` flags tests that change result between two runs |
| **Navigability** | 20% | `node_modules`, `.venv`, `dist`, caches ignored (and not committed) · no source files over 1000 lines · no minified/vendored/generated blobs in agent view · shallow directory tree · README |
| **Type safety** | 15% | TypeScript `strict` across root and package tsconfigs (follows `extends`, incl. workspace packages), `any` / `@ts-ignore` / `@ts-nocheck` density · plain JS penalized · Python type-hint coverage of product code + mypy/pyright config · Go/Rust count as compiler-checked · Go `interface{}`/`any` density and Rust `unsafe` density |
| **Safety** | 10% | Committed `.env` / keys / credentials files · AWS, GitHub, Slack, Stripe, OpenAI, Anthropic, Google, npm token patterns · dangerous scripts: `rm -rf ~`, `curl \| sh`, force-push, `npm publish` hidden in `build`/`test`, network calls in install hooks · committed agent permissions (`Bash(*)` allow rules, `bypassPermissions`, Codex `danger-full-access`) |
| Category | Weight | Checks |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Context docs** | 30% | `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` / Copilot / Gemini instructions exist · they list exact build, test and lint commands · they describe architecture and key directories · **not stale**: every referenced path and `npm run` script actually exists · **not drifting** (git history): a doc untouched for 90+ days while 25+ later commits changed the files it names or added/removed files in the dirs it describes · not too long (or too thin) · both `AGENTS.md` and `CLAUDE.md` so every agent is covered · `.cursor/rules/*.mdc` actually apply (frontmatter, globs that match files) · monorepos: large workspace packages have a nested `AGENTS.md` or are mentioned in the root docs |
| **Feedback loops** | 25% | A discoverable test command (package.json `test`, pytest config, `make test`, `cargo test`, `go test`, `mvn test` / `./gradlew test`) · linter configured (eslint, biome, oxlint, ruff, flake8, clippy, golangci-lint, checkstyle/spotless/PMD/SpotBugs/Error Prone/ktlint/detekt) · typecheck command (`tsc`, mypy, pyright, Maven/Gradle compile) · CI config · MCP server configs (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`) and Claude Code hooks are valid · Rust: one cargo workspace reaches every crate (nested workspaces and orphan crates flagged; path deps and `fuzz/` understood) · `--run`: test suite passes and is fast, lint and typecheck pass, `--flaky` flags tests that change result between two runs |
| **Navigability** | 20% | `node_modules`, `.venv`, `dist`, caches ignored (and not committed) · no source files over 1000 lines · no minified/vendored/generated blobs in agent view · shallow directory tree · README |
| **Type safety** | 15% | TypeScript `strict` across root and package tsconfigs (follows `extends`, incl. workspace packages), `any` / `@ts-ignore` / `@ts-nocheck` density · plain JS penalized · Python type-hint coverage of product code + mypy/pyright config · Go/Rust/Java/Kotlin count as compiler-checked · Go `interface{}`/`any` density and Rust `unsafe` density |
| **Safety** | 10% | Committed `.env` / keys / credentials files · AWS, GitHub, Slack, Stripe, OpenAI, Anthropic, Google, npm token patterns · dangerous scripts: `rm -rf ~`, `curl \| sh`, force-push, `npm publish` hidden in `build`/`test`, network calls in install hooks · committed agent permissions (`Bash(*)` allow rules, `bypassPermissions`, Codex `danger-full-access`) |

**`--run` executes project code**, so it is opt-in. It runs the test command (timed), the lint
command and the typecheck command the report detected (package.json scripts, `make` targets,
ruff/mypy, `go vet`/`go build`, `cargo clippy`/`cargo check`). Scripts that publish or delete are
ruff/mypy, `go vet`/`go build`, `cargo clippy`/`cargo check`, `mvn compile`/`./gradlew classes`). Scripts that publish or delete are
never run. `--flaky` runs the test suite a second time and compares the results, including which
tests failed for vitest/jest, pytest, `go test`, `cargo test` and TAP output. Each command gets a
timeout (`--timeout`, default 300s), and on timeout the whole process tree is killed. Only use
Expand Down Expand Up @@ -280,7 +280,7 @@ whatever `npm run build` does.

## Roadmap

- [ ] Deeper Go and Rust checks (unsafe/`interface{}` density, nested `Cargo.toml` workspaces) and Java/Kotlin support (Go/Rust done)
- [x] Deeper Go and Rust checks (unsafe/`interface{}` density, nested `Cargo.toml` workspaces) and Java/Kotlin support
- [x] `--run` for lint/typecheck too, and flaky-test detection (run twice, compare)
- [x] Monorepo awareness: score each workspace package, check nested `AGENTS.md`
- [x] Doc staleness via git history (doc untouched while referenced code churned)
Expand Down
4 changes: 2 additions & 2 deletions src/checks/context-docs.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ export function codeText(md: string): string {
}

const RUNNERS =
'(?:npm|pnpm|yarn|bun|npx|bunx|nub|vp|make|just|task|mise|moon|uv|uvx|poetry|pdm|hatch|tox|nox|python3?|pip|cargo|go|deno|turbo|nx|bazel|bazelisk|gradlew|gradle|mvn|dotnet|rake|bundle|mix)';
'(?:npm|pnpm|yarn|bun|npx|bunx|nub|vp|make|just|task|mise|moon|uv|uvx|poetry|pdm|hatch|tox|nox|python3?|pip|cargo|go|deno|turbo|nx|bazel|bazelisk|gradlew|gradle|mvnw|mvn|dotnet|rake|bundle|mix)';
/** Any tool invoked as `<tool> run|exec <task>` (e.g. `mise run test`, `nub exec vitest`). */
const GENERIC_RUN = '(?:\\b[\\w.-]+\\s+(?:run|exec)\\b)';

Expand All @@ -41,7 +41,7 @@ const COMMAND_KINDS: Record<string, RegExp> = {
'im',
),
build: new RegExp(
`(?:(?:\\b${RUNNERS}\\b|${GENERIC_RUN})[^\\n]*\\b(?:build|compile|bundle|install|sync|dev|start)\\b)|^\\s*(?:tsc|vite|webpack|esbuild)\\b|^\\s*(?:make|just)\\s*$`,
`(?:(?:\\b${RUNNERS}\\b|${GENERIC_RUN})[^\\n]*\\b(?:build|compile|bundle|install|sync|dev|start|package|assemble)\\b)|^\\s*(?:tsc|vite|webpack|esbuild)\\b|^\\s*(?:make|just)\\s*$`,
'im',
),
};
Expand Down
84 changes: 82 additions & 2 deletions src/checks/feedback.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { type Language, type RepoContext, runScriptCmd } from '../context.js';
import { JVM_BUILD, type Language, type RepoContext, runScriptCmd } from '../context.js';
import type { Check, CheckResult, RunOptions } from '../types.js';
import { isFixturePath } from '../util/paths.js';
import { type RunResult, runCommand } from '../util/run.js';
import { isDangerousScript } from './safety.js';
import { projectTsconfigs } from './type-safety.js';
Expand Down Expand Up @@ -67,9 +68,49 @@ export function testCommand(ctx: RepoContext): string | null {
}
if (hasRust(ctx) && ctx.has('Cargo.toml')) return 'cargo test';
if (hasGo(ctx) && ctx.has('go.mod')) return 'go test ./...';
const jvm = jvmBuildTool(ctx);
if (hasJvm(ctx) && jvm) return `${jvm.run} test`;
return null;
}

function hasJvm(ctx: RepoContext): boolean {
return ctx.languages.includes('java') || ctx.languages.includes('kotlin');
}

/** The root Maven/Gradle build, with the wrapper when one is committed. */
export function jvmBuildTool(ctx: RepoContext): { tool: 'maven' | 'gradle'; run: string } | null {
if (
['build.gradle', 'build.gradle.kts', 'settings.gradle', 'settings.gradle.kts'].some((f) =>
ctx.has(f),
)
) {
return { tool: 'gradle', run: ctx.has('gradlew') ? './gradlew' : 'gradle' };
}
if (ctx.has('pom.xml')) return { tool: 'maven', run: ctx.has('mvnw') ? './mvnw' : 'mvn' };
return null;
}

/** All Maven/Gradle build files, for plugins that are configured by being applied (checkstyle, spotless). */
function jvmBuildText(ctx: RepoContext): string {
return ctx.files
.filter((f) => JVM_BUILD.test(f) && !isFixturePath(f))
.slice(0, 200)
.map((f) => ctx.read(f) ?? '')
.join('\n');
}

const JVM_LINTERS =
/\b(checkstyle|spotless|pmd|spotbugs|errorprone|error_prone|error-prone|ktlint|detekt|ktfmt|google-java-format|palantir-java-format|diktat)\b/i;

function jvmTestFiles(ctx: RepoContext): number {
return ctx.files.filter(
(f) =>
/\.(?:java|kt|groovy|scala)$/.test(f) &&
(/(^|\/)src\/(?:test|androidTest|integrationTest|[\w]*[Tt]est)\/|(^|\/)test\//.test(f) ||
/(?:Tests?|IT|Spec)\.(?:java|kt|groovy)$/.test(f)),
).length;
}

/** `uv run ` / `poetry run ` prefix for Python tools, matching the project's environment manager. */
function pyRun(ctx: RepoContext): string {
if (ctx.has('uv.lock')) return 'uv run ';
Expand Down Expand Up @@ -121,6 +162,8 @@ export function typecheckCommand(ctx: RepoContext): string | null {
}
if (hasRust(ctx) && ctx.has('Cargo.toml')) return 'cargo check --quiet --all-targets';
if (hasGo(ctx) && ctx.has('go.mod')) return 'go build ./...';
const jvm = jvmBuildTool(ctx);
if (hasJvm(ctx) && jvm) return `${jvm.run} ${jvm.tool === 'maven' ? 'compile' : 'classes'}`;
return null;
}

Expand Down Expand Up @@ -249,6 +292,19 @@ export const feedbackChecks: Check[] = [
parts.push(part(ctx, tests ? 1 : 0, 'go'));
notes.push(tests ? '`go test ./...`' : 'no Go tests');
}
if (hasJvm(ctx)) {
const build = jvmBuildTool(ctx);
const tests = jvmTestFiles(ctx);
const score = tests && build ? 1 : tests ? 0.5 : 0;
parts.push(part(ctx, score, 'java', 'kotlin'));
notes.push(
tests && build
? `\`${build.run} test\` (${tests} test files)`
: tests
? `${tests} JVM test files but no root Maven/Gradle build`
: 'no Java/Kotlin tests',
);
}
const score = avg(parts);
if (score === null) return { score: null, summary: 'No supported language detected' };
return {
Expand Down Expand Up @@ -336,14 +392,29 @@ export const feedbackChecks: Check[] = [
);
}
}
if (hasJvm(ctx)) {
const configured =
JVM_LINTERS.test(jvmBuildText(ctx)) ||
ctx.files.some((f) =>
/(^|\/)(?:checkstyle[\w-]*\.xml|detekt[\w-]*\.ya?ml|pmd[\w-]*\.xml|\.?ktlint[\w-]*)$/.test(
f,
),
);
parts.push(part(ctx, configured ? 1 : 0.6, 'java', 'kotlin'));
notes.push(
configured
? 'JVM linter (checkstyle/spotless/detekt/...)'
: 'only compiler warnings (no checkstyle/spotless/ktlint/detekt)',
);
}
const score = avg(parts);
if (score === null) return { score: null, summary: 'No supported language detected' };
return {
score,
summary: `Lint: ${notes.join('; ')}`,
suggestion:
score < 1
? 'Configure a fast linter (eslint/biome for JS, ruff for Python, clippy for Rust, golangci-lint for Go) and run it in CI.'
? 'Configure a fast linter (eslint/biome for JS, ruff for Python, clippy for Rust, golangci-lint for Go, checkstyle/spotless/detekt for the JVM) and run it in CI.'
: undefined,
};
},
Expand Down Expand Up @@ -403,6 +474,15 @@ export const feedbackChecks: Check[] = [
parts.push(part(ctx, 1, 'go'));
notes.push('`go build ./...`');
}
if (hasJvm(ctx)) {
const build = jvmBuildTool(ctx);
parts.push(part(ctx, build ? 1 : 0.5, 'java', 'kotlin'));
notes.push(
build
? `\`${build.run} ${build.tool === 'maven' ? 'compile' : 'classes'}\``
: 'no root Maven/Gradle build to compile with',
);
}
const score = avg(parts);
if (score === null) return { score: null, summary: 'No typed language detected' };
return {
Expand Down
Loading
Loading