Allow controlling what is included in the alignment report.

* Allow controlling what is included in the alignment report.

Amend the `check-align` command so that the contents of the report is
tunable.

For that, the report is now made in two steps:

(1) We collect _all_ unaligned classes. This is unconditional. We do
_not_ identify the top-level classes at this step.

(2) We optionally trim the set of unaligned classes, based on the value
of the `--detail` option:

* ALL: no trimming;
* ROOT: trim everything below the top-level classes;
* BASE-ROOT: trim everything below the highest "in-base" classes.

Author: gouttegd

src/main/java/org/incenp/obofoundry/odk/CheckAlignmentCommand.java

@@ -81,17 +81,22 @@ public CheckAlignmentCommand() {
 
         options.addOption("r", "reasoner", true, "the reasoner to use");
         options.addOption("O", "report-output", true, "write report to the specified file");
+        options.addOption(null, "detail", true, "what to report (ROOT / BASE-ROOT / ALL)");
         options.addOption("x", "fail", true, "if true (default), fail if the ontology is misaligned");
     }
 
     @Override
     public void performOperation(CommandState state, CommandLine line) throws Exception {
         boolean ignoreDangling = CommandLineHelper.getBooleanValue(line, "ignore-dangling", false);
         boolean failOnError = CommandLineHelper.getBooleanValue(line, "fail", true);
+        ReportMode reportMode = ReportMode.fromString(CommandLineHelper.getDefaultValue(line, "detail", "root"));
         if ( line.hasOption("base-iri") ) {
             for ( String iri : line.getOptionValues("base-iri") ) {
                 basePrefixes.add(getIRI(iri, "base-iri").toString());
             }
+        } else if ( reportMode == ReportMode.BASE_ROOT ) {
+            // --detail BASE-ROOT makes no sense without a base IRI
+            reportMode = ReportMode.GLOBAL_ROOT;
         }
         factory = state.getOntology().getOWLOntologyManager().getOWLDataFactory();
 
@@ -130,14 +135,14 @@ public void performOperation(CommandState state, CommandLine line) throws Except
         }
 
         OWLReasoner reasoner = CommandLineHelper.getReasonerFactory(line).createReasoner(ontology);
-        Set<OWLClass> unalignedClasses = getUnalignedClasses(ontology, reasoner, upperClasses, ignoreDangling);
+        Set<OWLClass> unalignedClasses = getAllUnalignedClasses(ontology, reasoner, upperClasses, ignoreDangling);
 
         if ( line.hasOption("report-output") ) {
             // If a report has been requested, we always produce it, even if no unaligned
             // classes were found
             BufferedWriter writer = new BufferedWriter(new FileWriter(line.getOptionValue("report-output")));
             List<String> unalignedIRIs = new ArrayList<>();
-            for ( OWLClass unalignedClass : unalignedClasses ) {
+            for ( OWLClass unalignedClass : trimReport(reasoner, unalignedClasses, reportMode) ) {
                 unalignedIRIs.add(unalignedClass.getIRI().toString());
             }
             unalignedIRIs.sort((a, b) -> a.compareTo(b));
@@ -149,7 +154,7 @@ public void performOperation(CommandState state, CommandLine line) throws Except
         }
 
         if ( !unalignedClasses.isEmpty() ) {
-            logger.error("Ontology contains {} top-level unaligned class(es)", unalignedClasses.size());
+            logger.error("Ontology contains {} unaligned class(es)", unalignedClasses.size());
             if ( failOnError ) {
                 System.exit(1);
             }
@@ -191,10 +196,7 @@ private Set<OWLClass> getPreferredRoots(OWLOntology ontology) {
         return roots;
     }
 
-    /*
-     * Gets all top-level unaligned classes in the ontology.
-     */
-    private Set<OWLClass> getUnalignedClasses(OWLOntology ontology, OWLReasoner reasoner, Set<OWLClass> upperClasses,
+    private Set<OWLClass> getAllUnalignedClasses(OWLOntology ontology, OWLReasoner reasoner, Set<OWLClass> upperClasses,
             boolean ignoreDangling) {
         Set<OWLClass> unalignedClasses = new HashSet<>();
         for ( OWLClass klass : ontology.getClassesInSignature(Imports.INCLUDED) ) {
@@ -205,6 +207,10 @@ private Set<OWLClass> getUnalignedClasses(OWLOntology ontology, OWLReasoner reas
                 if ( Util.isObsolete(ontology, klass) ) {
                     continue;
                 }
+                if ( unalignedClasses.contains(klass) ) {
+                    // Already found, skip
+                    continue;
+                }
 
                 Set<OWLClass> ancestors = reasoner.getSuperClasses(klass, false).getFlattened();
                 boolean aligned = false;
@@ -214,28 +220,49 @@ private Set<OWLClass> getUnalignedClasses(OWLOntology ontology, OWLReasoner reas
                         break;
                     }
                 }
+
                 if ( !aligned ) {
-                    if ( ancestors.size() == 1 ) {
-                        // This is already a top-level class
-                        logger.debug("Unaligned class: {}", klass.getIRI().toQuotedString());
-                        unalignedClasses.add(klass);
-                    } else {
-                        // Find the top-level ancestor(s)
-                        for ( OWLClass ancestor : ancestors ) {
-                            if ( reasoner.getSuperClasses(ancestor, false).isTopSingleton() ) {
-                                logger.debug("Unaligned class: {} (from {})", ancestor.getIRI().toQuotedString(),
-                                        klass.getIRI().toQuotedString());
-                                unalignedClasses.add(ancestor);
-                            }
-                        }
-                    }
+                    logger.debug("Unaligned class: {}", klass.getIRI().toQuotedString());
+                    unalignedClasses.add(klass);
+                    // If this class is unaligned, then all its ancestors necessarily are too
+                    unalignedClasses.addAll(ancestors);
                 }
             }
         }
 
+        unalignedClasses.remove(factory.getOWLThing());
         return unalignedClasses;
     }
 
+    private Set<OWLClass> trimReport(OWLReasoner reasoner, Set<OWLClass> unalignedClasses, ReportMode mode) {
+        Set<OWLClass> trimmedOut = new HashSet<>();
+        Set<OWLClass> reportSet = new HashSet<>();
+
+        if ( mode == ReportMode.GLOBAL_ROOT ) {
+            // Exclude any class that is not a top-level class
+            for ( OWLClass unaligned : unalignedClasses ) {
+                if ( !reasoner.getSuperClasses(unaligned, false).isTopSingleton() ) {
+                    trimmedOut.add(unaligned);
+                }
+            }
+        } else if ( mode == ReportMode.BASE_ROOT ) {
+            // Exclude any class that is a descendant of an in-base class
+            for ( OWLClass unaligned : unalignedClasses ) {
+                if ( isInBase(unaligned.getIRI().toString()) ) {
+                    trimmedOut.addAll(reasoner.getSubClasses(unaligned, false).getFlattened());
+                }
+            }
+        }
+
+        for ( OWLClass unaligned : unalignedClasses ) {
+            if ( !trimmedOut.contains(unaligned) ) {
+                reportSet.add(unaligned);
+            }
+        }
+
+        return reportSet;
+    }
+
     private boolean isInBase(String iri) {
         for ( String base : basePrefixes ) {
             if ( iri.startsWith(base) ) {
@@ -244,4 +271,20 @@ private boolean isInBase(String iri) {
         }
         return basePrefixes.isEmpty();
     }
+
+    private enum ReportMode {
+        GLOBAL_ROOT,
+        BASE_ROOT,
+        ALL;
+
+        static ReportMode fromString(String name) {
+            if ( name.equalsIgnoreCase("all") ) {
+                return ALL;
+            } else if ( name.equalsIgnoreCase("base-root") ) {
+                return BASE_ROOT;
+            } else {
+                return GLOBAL_ROOT;
+            }
+        }
+    }
 }

src/site/markdown/alignment.md

@@ -98,9 +98,17 @@ because `--fail false` was used), the next command in the pipeline
 receives the original, unmodified ontology.
 
 To produce a report from the validation results, use the
-`--report-output <FILE>` option. The file will contain a list of all the
-top-level classes (if any) of the input ontology that are not aligned
-against the upper ontology.
+`--report-output <FILE>` option. What will be included in this report is
+controlled by the `--detail <MODE>` option:
+
+* `--detail ROOT` will report all the top-level classes (if any) of the
+  input ontology that are not aligned against the upper ontology; this is
+  the default behaviour;
+* `--detail BASE-ROOT` will report the highest “in-base” classes that
+  are not aligned and all their ancestors up to the top-level classes;
+  this is only meaningful if `--base-iri` is also used, otherwise this
+  is the same as `--detail ROOT`;
+* `--detail ALL` will report all unaligned classes.
 
 Restricting the scope of the validation
 ---------------------------------------