Structure & lockfiles¶
Project structure and reproducibility: deep nesting, heavy directories, cross-package duplicate assets, and missing lockfiles/wrappers.
20 checks.
gradle-wrapper-jar-missing¶
Severity: High
gradle-wrapper.jar is what gradlew executes to download and run the pinned Gradle version. If it is missing from the repo, every fresh checkout and CI run fails to build even though it works on a machine where the jar is already on disk.
How to fix: ignored ? 'Force-add the wrapper jar and exclude it from the ignore rule: git add -f gradle/wrapper/gradle-wrapper.jar and add !gradle/wrapper/gradle-wrapper.jar after the *.jar line.' : 'Run gradle wrapper at the Gradle project root and commit the generated gradle/wrapper/gradle-wrapper.jar.'
repo-gradle-jvmargs-no-metaspace¶
Severity: Low
A heap-tuned Gradle daemon with no metaspace bound can grow metaspace unbounded and OOM (java.lang.OutOfMemoryError: Metaspace) on large multi-module builds — an intermittent, machine-dependent build failure that is hard to diagnose.
How to fix: Add an explicit metaspace bound to org.gradle.jvmargs, e.g. -XX:MaxMetaspaceSize=512m alongside your -Xmx value.
repo-gradle-perf-buildcache¶
Severity: Low
Without the build cache, unchanged modules are rebuilt from scratch on every run, and CI cannot reuse task output across jobs — a silent, recurring waste of build time.
How to fix: Add org.gradle.caching=true to the root gradle.properties.
repo-gradle-perf-configcache¶
Severity: Low
Re-running configuration on every invocation is a silent, recurring build-time cost, especially on large multi-module builds. (The configuration cache can surface incompatible tasks — enable it and fix any reported problems, rather than assuming it is free.)
How to fix: Add org.gradle.configuration-cache=true to the root gradle.properties and resolve any incompatible-task problems Gradle reports.
repo-gradle-perf-parallel¶
Severity: Low
Serial task execution leaves cores idle on a multi-module build, silently lengthening every build. (Parallel execution requires decoupled, thread-safe projects — verify before enabling.)
How to fix: Add org.gradle.parallel=true to the root gradle.properties (ensure modules are decoupled).
repo-gradle-toolchain-drift¶
Severity: Low
Mismatched JVM targets across modules can produce class-version errors at runtime and inconsistent desugaring/behavior, and make the build depend on whichever JDK the machine happens to run.
How to fix: Configure a single Java toolchain (e.g. java { toolchain { languageVersion = … } }) in a convention plugin or the root build and apply it everywhere.
repo-gradle-version-catalog-drift¶
Severity: Low
Different versions of the same dependency invite classpath conflicts, duplicated transitive graphs, and runtime errors that depend on resolution order.
How to fix: catalog ? 'Move these versions into the version catalog (libs.versions.toml) and reference the aliases from every module.' : 'Declare shared dependency versions once (a version catalog or platform BOM) and reference them from all modules.'
repo-gradle-wrapper-version-drift¶
Severity: Low
A single, consistent Gradle version across the repository keeps builds reproducible and avoids version-specific behavior differences between modules.
How to fix: Align all gradle-wrapper.properties on the same Gradle version (run ./gradlew wrapper --gradle-version <x> per module).
repo-ios-package-manager-overlap¶
Severity: Low
Splitting dependencies across CocoaPods and SwiftPM increases build complexity, slows resolution, and is a recurring source of version conflicts. Consolidating on one manager is usually preferable.
How to fix: Consider consolidating this module’s iOS dependencies onto a single package manager (SwiftPM or CocoaPods).
repo-kmp-gradle-properties-missing¶
Severity: Low
Without a committed gradle.properties, KMP-specific Gradle flags and JVM tuning are not pinned, producing inconsistent and often slower/flakier multiplatform builds across machines.
How to fix: Add a gradle.properties pinning Kotlin/Gradle settings (e.g. kotlin.code.style, org.gradle.jvmargs) and commit it.
repo-missing-gradle-wrapper¶
Severity: Medium
The Gradle wrapper ensures every developer and CI agent uses the exact same Gradle version, preventing hard-to-debug build failures caused by version mismatches.
How to fix: Run gradle wrapper at the Gradle project root and commit the generated gradle/ directory.
repo-missing-podfile-lock¶
Severity: Medium
A missing Podfile.lock means pod install can resolve different versions on each machine, leading to build failures or runtime regressions that are difficult to diagnose.
How to fix: Run pod install and commit the generated Podfile.lock.
repo-missing-pubspec-lock¶
Severity: Low
A missing lock file causes non-reproducible builds and can introduce subtle bugs when transitive dependency versions drift between machines.
How to fix: Run flutter pub get and commit the generated pubspec.lock.
repo-pub-lock-drift¶
Severity: Medium
A stale pubspec.lock does not reflect declared dependencies, so flutter pub get resolves and rewrites the lock differently on each machine and in CI — builds are not reproducible.
How to fix: Run flutter pub get and commit the regenerated pubspec.lock.
repo-swiftpm-lockfile-missing¶
Severity: Low
Package.resolved pins the exact resolved versions of Swift Package dependencies. Committing it keeps dependency resolution reproducible across developers and CI.
How to fix: Resolve packages (swift package resolve, or build once in Xcode) and commit the generated Package.resolved.
repo-toolchain-pin-missing¶
Severity: Low
An unpinned SDK lets different developers and CI agents build with different Dart/Flutter versions, producing inconsistent analyzer results and hard-to-reproduce build failures.
How to fix: Add an environment: block with an sdk: constraint to pubspec.yaml (and optionally pin Flutter via FVM).
structure-cross-package-duplicates¶
Severity:
Duplicate files across modules increase repository size, lead to inconsistencies when one copy is updated but not others, and waste build resources.
How to fix: Consolidate the duplicates into a shared module or directory and reference the single source from each consuming module.
structure-deep-nesting¶
Severity:
Excessively deep directory structures make navigation difficult, suggest overly complex module hierarchies, and can cause path-length issues on some operating systems.
How to fix: Aim for a maximum depth of … levels. Strategies: (1) flatten feature folders by co-locating related files instead of nesting by type, (2) use barrel exports (index.ts) to allow shorter import paths. Run find . -mindepth … -type d to list all offending directories.
structure-heavy-directory¶
Severity:
Heavy directories increase clone times and CI build durations. They may contain assets or binaries that should be stored externally.
How to fix: This directory exceeds the … threshold. Run ls -lhS "…" to identify the largest files. Consider: track binaries with Git LFS (git lfs track "…/*"), compress images with TinyPNG, or convert raster assets to WebP (cwebp -q 80 input.png -o output.webp).
structure-module-inventory¶
Severity: Info
Understanding the module structure of the repository helps identify build dependencies, potential code sharing opportunities, and structural complexity.
How to fix: No action required. This is an informational finding for visibility into the repository structure.