fix: fail closed on incomplete CLI imports

Author: TristanKruse

CHANGELOG.md

@@ -5,6 +5,13 @@ uses semantic versioning for public releases.
 
 ## [Unreleased]
 
+### Fixed
+
+- accept documented dotted CLI rule IDs while still rejecting unknown rule fields;
+- retain input and parser failures in CLI/direct `CliAnalyzer` results so corrupt archives or
+  malformed classes cannot silently produce passing partial checks; and
+- reject incomplete graph imports by default before writing graph output.
+
 ### Changed
 
 - align the project license with the ArchUnitEverything family by adopting the MIT License.

docs/CLI_REFERENCE.md

@@ -25,6 +25,13 @@ archunitjava <check|graph|explain|validate-config>
 Command-line format flags override the corresponding configuration value. Other unknown options
 are rejected.
 
+Both `check` and `graph` reject incomplete imports by default, including corrupt JARs,
+malformed class files, and exceeded input limits. `check` retains import diagnostics in its
+results and returns exit code `4`; `graph` returns `4` without emitting a partial graph.
+Set `allowIncompleteAnalysis=true` only when partial results are acceptable. In that mode,
+`check` retains the import failures as warnings. A graph command does not enforce the configured
+architecture policies: violations alone do not prevent graph export.
+
 ## Root keys
 
 | Key | Required | Values and default |

docs/MAINTAINER_HANDOVER.md

@@ -0,0 +1,74 @@
+# Maintainer handover
+
+Review date: 2026-09-14. Proposed recipient: [Lukas Niessen](https://github.com/LukasNiessen).
+This document prepares a transfer; it does not record a completed ownership change.
+
+## Before transferring
+
+1. Resolve the destination name. `LukasNiessen/ArchUnitJava` already exists as a separate,
+   non-fork repository with `README.md`, `AGENTS.md`, and `CLA.md`. Its owner should preserve any
+   relevant guidance and rename it before accepting this repository under that name. Transferring
+   under a different unused name is another option. Do not overwrite or delete the existing repo.
+2. Decide whether the independent `ArchUnitJava-TestRepo-RAG` should move too. The library's CI
+   checks it out explicitly, and its standalone CI tests the published Maven artifact.
+3. Arrange Maven Central publishing access separately. The existing artifact is
+   `io.github.tristankruse:archunitjava:0.1.0`; a GitHub transfer does not change that coordinate or
+   automatically grant namespace access. Prefer retaining the coordinates for consumer continuity.
+   Use Central Portal organization membership and namespace permissions, or Central Support if the
+   necessary organization controls are unavailable. Lukas should use his own publisher account.
+4. Review release credentials and approval. The `maven-central` environment currently requires
+   TristanKruse approval and contains the five secret names listed in [RELEASE.md](RELEASE.md).
+   GitHub keeps secrets associated with a transferred repository. Agree on replacing the Central
+   token, signing-key custody, and the release approver before running any release under new
+   ownership. Never copy secret values into repository files or handover notes.
+5. Verify analytics access. Publisher Insights was enabled for `io.github.tristankruse`. Access to
+   the correct Maven package in Scarf and its public badge still needs independent verification.
+   The README currently links to the analytics sources but contains no live download-count badge.
+   Repository transfer alone does not transfer external analytics accounts.
+
+## Repository quality and release follow-up
+
+- Dependabot PRs #76 and #77 were reviewed and merged: Maven Surefire 3.6.0 and Compiler 3.16.0.
+- The focused CLI audit reproduced and corrected dotted rule-ID rejection and successful partial
+  analysis after corrupt input. Regression tests cover strict checks, all six graph renderers,
+  explicit partial-analysis opt-in, retained violations, and harmless input duplication.
+- These fixes are on the development line. Maven Central `0.1.0` remains immutable and does not
+  contain them. Plan a subsequent beta release after choosing publisher access and ownership.
+- The current source uses MIT; the already published `0.1.0` artifact retains its original Apache
+  2.0 metadata. Keep that distinction explicit until a subsequent release is published.
+- CodeQL is active. At the review date, Dependabot security alerts/security updates and secret
+  scanning/push protection were disabled. Enable the appropriate GitHub security features and
+  review any resulting alerts. Scheduled dependency-version PRs are already enabled.
+- No repository rulesets were present at the review date. A protected default branch is an
+  optional next step when more maintainers contribute; it should fit the team's merge workflow.
+- The public API remains provisional and JDK 25 remains required. A repository transfer is not
+  a reason to claim 1.0 stability or change the runtime requirement.
+
+## Transfer choices
+
+The recommended option for the current family layout is GitHub's native transfer to
+`LukasNiessen`, after resolving the name conflict. It preserves history, issues, PRs, stars, and
+release records. Lukas must accept the personal-account transfer invitation within one day.
+The original owner remains a collaborator. No transfer invitation has been sent during this review.
+
+A shared GitHub organization is an alternative if the whole ArchUnitEverything family should have
+multiple administrators. It requires a separately agreed organization and repository-creation
+permission. Copying code into the existing repository would not preserve this repository's issue,
+PR, and release continuity in the same way.
+
+## After acceptance
+
+- Update local Git remotes, README badges/links, the repository homepage, POM project/SCM metadata,
+  issue-template links, support links, and the documentation site's social-preview URL.
+- Deploy and verify Pages at the recipient's site URL. Repository URLs redirect after transfer;
+  GitHub Pages URLs do not. Decide whether to keep a separate redirect site at the old Pages URL.
+- Update the RAG repository links and the explicit checkout in `.github/workflows/ci.yml` if the
+  fixture also moves. Test both the development candidate and the published artifact.
+- Review `.github/workflows/prepare-release.yml`, which currently sets Tristan's tagger identity,
+  and the release environment's approver. Preserve attribution on existing commits and tags.
+- Confirm CI, documentation deployment, CodeQL, Central permissions, signing, and analytics from
+  the new maintainer's account before the next release. Use a staging/dry-run first.
+
+References: [GitHub repository transfers](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository),
+[Central Portal organizations and namespace permissions](https://central.sonatype.org/publish/publish-portal-organizations/),
+and [Scarf's Maven integration](https://docs.scarf.sh/package-registry-integrations-maven-central/).

docs/RELEASE.md

@@ -106,6 +106,9 @@ replaced or deleted.
 
 ## Local review commands
 
+For ownership changes, see the [maintainer handover](MAINTAINER_HANDOVER.md) for repository,
+publishing, signing, documentation, and analytics dependencies.
+
 ```shell
 ./mvnw --batch-mode --no-transfer-progress verify
 ./mvnw --batch-mode --no-transfer-progress -Prelease-candidate verify

src/main/java/dev/archunitjava/cli/CliAnalyzer.java

@@ -2,8 +2,17 @@
 
 import dev.archunitjava.importer.ClassFileInput;
 import dev.archunitjava.importer.ClassPathImportResolver;
+import dev.archunitjava.importer.ImportResolutionResult;
+import dev.archunitjava.importer.InputDiagnosticCode;
 import dev.archunitjava.report.ResultReport;
+import dev.archunitjava.result.Diagnostic;
+import dev.archunitjava.result.RuleResult;
+import dev.archunitjava.result.Severity;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
 import java.util.Objects;
+import java.util.TreeMap;
 
 /** Direct Java API for the same bounded import and rule evaluation performed by the CLI. */
 public final class CliAnalyzer {
@@ -12,9 +21,63 @@ public CliAnalysisResult analyze(CliConfiguration configuration) {
         var imports = new ClassPathImportResolver().resolve(config.inputs().stream()
                 .map(ClassFileInput::path).toList());
         var graph = CliGraphBuilder.build(imports.model());
+        var failures = importFailures(imports);
         var results = CliRuleFactory.createRules(config, imports.model(), graph).stream()
                 .map(rule -> rule.check(config.checkOptions()))
+                .map(result -> withImportDiagnostics(result, failures,
+                        config.checkOptions().allowIncompleteAnalysis()))
                 .toList();
         return new CliAnalysisResult(imports, graph, ResultReport.of(results));
     }
+
+    static List<Diagnostic> importFailures(ImportResolutionResult imports) {
+        List<Diagnostic> failures = new ArrayList<>();
+        imports.assembly().diagnostics().stream()
+                .filter(value -> incompleteInput(value.code()))
+                .forEach(value -> failures.add(importDiagnostic(
+                        "cli.input." + value.code().name(), value.input(), value.context())));
+        imports.model().classFileDiagnostics().forEach(value -> failures.add(importDiagnostic(
+                "cli.classfile." + value.code().name(), value.resourceName(), value.context())));
+        imports.model().diagnostics().forEach(value -> failures.add(importDiagnostic(
+                "cli.model." + value.code().name(), value.resourceName(), value.context())));
+        return failures.stream().distinct().sorted().toList();
+    }
+
+    private static boolean incompleteInput(InputDiagnosticCode code) {
+        return switch (code) {
+            case ARCHIVE_RESOURCE_REJECTED, DIAGNOSTIC_LIMIT_REACHED, INVALID_IGNORE_RULE,
+                    INVALID_RESOURCE_NAME, IO_FAILURE, MISSING_INPUT, RESOURCE_LIMIT_EXCEEDED,
+                    UNREADABLE_INPUT, UNSUPPORTED_INPUT -> true;
+            // These record the documented classpath selection and exclusion policy.
+            case DUPLICATE_INPUT, DUPLICATE_RESOURCE, MANIFEST_CLASS_PATH_REJECTED,
+                    MULTI_RELEASE_ENTRY_IGNORED, NESTED_ARCHIVE_REJECTED, RESOURCE_EXCLUDED,
+                    SYMLINK_SKIPPED -> false;
+        };
+    }
+
+    private static Diagnostic importDiagnostic(
+            String code, String resource, Map<String, String> context) {
+        Map<String, String> details = new TreeMap<>(context);
+        details.put("resource", resource);
+        return new Diagnostic(code, Severity.ERROR, details);
+    }
+
+    private static RuleResult withImportDiagnostics(
+            RuleResult result, List<Diagnostic> failures, boolean allowIncomplete) {
+        if (failures.isEmpty()) return result;
+        List<Diagnostic> diagnostics = new ArrayList<>(result.diagnostics());
+        for (Diagnostic failure : failures) {
+            diagnostics.add(allowIncomplete
+                    ? new Diagnostic(failure.code(), Severity.WARNING, failure.context()) : failure);
+        }
+        if (!allowIncomplete) {
+            return RuleResult.incomplete(result.metadata(), result.violations(), diagnostics);
+        }
+        return switch (result.status()) {
+            case PASSED -> RuleResult.passed(result.metadata(), diagnostics);
+            case FAILED -> RuleResult.failed(result.metadata(), result.violations(), diagnostics);
+            case SKIPPED -> RuleResult.skipped(result.metadata(), diagnostics);
+            case INCOMPLETE -> RuleResult.incomplete(result.metadata(), result.violations(), diagnostics);
+        };
+    }
 }

src/main/java/dev/archunitjava/cli/CliConfigurationLoader.java

@@ -168,7 +168,7 @@ private static void validateKeys(Set<String> keys, Set<String> ruleIds) {
                 throw new CliConfigurationException("Unknown configuration key: " + key);
             }
             String remainder = key.substring("rule.".length());
-            int separator = remainder.indexOf('.');
+            int separator = remainder.lastIndexOf('.');
             if (separator < 1 || !ruleIds.contains(remainder.substring(0, separator))
                     || !RULE_FIELDS.contains(remainder.substring(separator + 1))) {
                 throw new CliConfigurationException("Unknown rule configuration key: " + key);

src/main/java/dev/archunitjava/cli/CliRunner.java

@@ -107,6 +107,11 @@ private static int check(CliConfiguration configuration, Appendable out) {
 
     private static int graph(CliConfiguration configuration, Appendable out) {
         CliAnalysisResult analysis = new CliAnalyzer().analyze(configuration);
+        if (!configuration.checkOptions().allowIncompleteAnalysis()
+                && !CliAnalyzer.importFailures(analysis.imports()).isEmpty()) {
+            throw new IllegalStateException("Graph import is incomplete; repair the inputs or "
+                    + "explicitly set allowIncompleteAnalysis=true to render a partial graph");
+        }
         GraphSnapshot snapshot = switch (configuration.graphDomain()) {
             case TYPES -> GraphSnapshotQuery.types(analysis.graph()).snapshot();
             case PACKAGES -> GraphSnapshotQuery.packages(analysis.graph()).snapshot();

src/test/java/dev/archunitjava/cli/CliRunnerTest.java

@@ -67,6 +67,91 @@ void checkUsesTheSameResultsAsThePublicJavaApi() {
         assertTrue(error.isEmpty());
     }
 
+    @Test
+    void dottedRuleIdsAreAcceptedAndUnknownFieldsAreRejected() throws IOException {
+        String base = Files.readString(configuration);
+        String dotted = base.replace("boundary", "api.boundary");
+        configuration = writeConfiguration(dotted);
+        assertEquals(CliExitCode.SUCCESS.code(), run("validate-config").exit());
+        assertEquals(CliExitCode.POLICY_VIOLATION.code(), run("check").exit());
+
+        configuration = writeConfiguration(dotted + "rule.api.boundary.unknown=true\n");
+        assertEquals(CliExitCode.INVALID_CONFIGURATION.code(), run("validate-config").exit());
+
+        configuration = writeConfiguration(dotted + "rule.api.other.domain=types\n");
+        assertEquals(CliExitCode.INVALID_CONFIGURATION.code(), run("validate-config").exit());
+    }
+
+    @Test
+    void graphRejectsIncompleteBytecodeUnlessExplicitlyAllowed() throws IOException {
+        Files.write(classes.resolve("Broken.class"), new byte[] {0, 1, 2, 3});
+        for (String format : new String[] {"dot", "mermaid", "json", "csv", "d2", "html"}) {
+            Invocation graph = run("graph", "--graph-format", format);
+            assertEquals(CliExitCode.ANALYSIS_ERROR.code(), graph.exit(), format);
+            assertTrue(graph.out().isEmpty(), format);
+            assertTrue(graph.error().contains("incomplete"), format);
+        }
+        configuration = writeConfiguration(Files.readString(configuration)
+                .replace("allowIncompleteAnalysis=false", "allowIncompleteAnalysis=true"));
+        Invocation allowed = run("graph", "--graph-format", "json");
+        assertEquals(CliExitCode.SUCCESS.code(), allowed.exit());
+        assertTrue(allowed.out().contains("api.A"));
+    }
+
+    @Test
+    void corruptInputArchiveCannotProduceAPassingPartialAnalysis() throws IOException {
+        Files.write(root.resolve("broken.jar"), new byte[] {0, 1, 2, 3});
+        configuration = writeConfiguration(Files.readString(configuration)
+                .replace("inputs=classes", "inputs=classes,broken.jar")
+                .replace("origins=exact:api.A", "origins=exact:internal.B"));
+        Invocation check = run("check", "--result-format", "json");
+        assertEquals(CliExitCode.ANALYSIS_ERROR.code(), check.exit());
+        assertTrue(check.out().contains("INCOMPLETE"));
+        assertEquals(CliExitCode.ANALYSIS_ERROR.code(), run("graph").exit());
+        assertEquals(dev.archunitjava.result.RuleStatus.INCOMPLETE,
+                new CliAnalyzer().analyze(CliConfigurationLoader.load(configuration, root))
+                        .results().results().getFirst().status());
+        configuration = writeConfiguration(Files.readString(configuration)
+                .replace("allowIncompleteAnalysis=false", "allowIncompleteAnalysis=true"));
+        Invocation allowed = run("check", "--result-format", "json");
+        assertEquals(CliExitCode.SUCCESS.code(), allowed.exit());
+        assertTrue(allowed.out().contains("cli.input.IO_FAILURE"));
+        assertTrue(allowed.out().contains("WARNING"));
+    }
+
+    @Test
+    void malformedClassCannotProduceAPassingPartialAnalysis() throws IOException {
+        Files.write(classes.resolve("Broken.class"), new byte[] {0, 1, 2, 3});
+        configuration = writeConfiguration(Files.readString(configuration)
+                .replace("origins=exact:api.A", "origins=exact:internal.B"));
+        Invocation check = run("check", "--result-format", "json");
+        assertEquals(CliExitCode.ANALYSIS_ERROR.code(), check.exit());
+        assertTrue(check.out().contains("cli.classfile."));
+        assertTrue(check.out().contains("INCOMPLETE"));
+    }
+
+    @Test
+    void incompleteChecksRetainObservedViolations() throws IOException {
+        Files.write(classes.resolve("Broken.class"), new byte[] {0, 1, 2, 3});
+        var result = new CliAnalyzer().analyze(CliConfigurationLoader.load(configuration, root))
+                .results().results().getFirst();
+        assertEquals(dev.archunitjava.result.RuleStatus.INCOMPLETE, result.status());
+        assertFalse(result.violations().isEmpty());
+        assertTrue(result.diagnostics().stream()
+                .anyMatch(value -> value.code().startsWith("cli.classfile.")));
+    }
+
+    @Test
+    void graphIgnoresRuleSelectionFailuresAndHarmlessDuplicateInputs() throws IOException {
+        configuration = writeConfiguration(Files.readString(configuration)
+                .replace("inputs=classes", "inputs=classes,./classes")
+                .replace("targets=exact:internal.B", "targets=exact:absent.C"));
+        Invocation graph = run("graph", "--graph-format", "json");
+        assertEquals(CliExitCode.SUCCESS.code(), graph.exit());
+        assertTrue(graph.out().contains("api.A"));
+        assertTrue(graph.error().isEmpty());
+    }
+
     @Test
     void graphExplainAndValidationCommandsAreStableAndBounded() {
         Invocation validation = run("validate-config");