Merge origin/main into the documentation branch

The pull request had gone conflicting against main, and a conflicting pull
request has no merge ref, so GitHub could not schedule any `pull_request`
workflow. Only the labeler ran, on `pull_request_target`. The last two pushes
therefore had no continuous integration at all, which is why this merge is here
rather than later.

One conflict, in the test-case factory manual. Main rewrote the scanning section
when the scanner stopped matching regular expressions and started reading the
syntax tree with the imports resolved. This branch still carried the regex
description, `CLASS_PATTERN` and the rest. Main's text describes what the code
does, so it wins; git had already followed the rename from
`docs/securitytest/TestCaseFactoryAndBuilderManual.md`.

The version bump survives the merge: the pom reads 2.1.3 and nothing below it
refers to Ares. The two remaining mentions of 2.1.2 are in
`ReleasedCreatorContractTest` and `ReleasedConstructorCompatibilityTest`, which
say what the 2.1.2 release published and are kept callable. Those are statements
about a release that happened, not coordinates, and 2.1.3 has published nothing.

The prose gate found one enforced violation in the text main brought over, an
"actually" the sentence does not need, now gone. Three advisory counts rose with
that text: active-voice from 760 to 772, long-sentence from 111 to 115, and
prefer-must from 150 to 151. Those numbers are recorded rather than fixed. A
merge that carries in a page written before these rules existed is the one case
where a ceiling rises honestly, and both `cli.mjs` and the writing-rules page now
say so, along with the expectation that the next pass over that page lowers them.

Verified on the merge: 77 scanner fixtures, lint:prose at 0 enforced, eslint,
tsc, a strict build, 15 browser tests, and 644 documentation structure tests
compiled against main's production code.

Author: Markus Paulsen

.github/PULL_REQUEST_TEMPLATE.md

@@ -174,6 +174,19 @@
   should read. If a claim cannot be observed anywhere, either add the diagnostic that
   makes it observable, or do not ask for it.
 
+  Have the reviewer look at the result, not at an exit code. A command that exits zero
+  says the command ran. It does not say that what it produced is right, and a manual made
+  of green commands asks a reviewer to review your exit codes rather than your change.
+  Every claim in section 2 needs a step where the thing itself is in front of them: the
+  page as a reader gets it, the message a student is shown, the generated file, the row in
+  the report. Name what they must see there, and name what would be wrong.
+
+  This matters most where a build cannot see the defect. A site builds cleanly while a box
+  renders as plain text, a policy is read without complaint while the rule it was meant to
+  express is not enforced, and a test passes while asserting nothing. Where a suite in this
+  repository already looks at such a result for you, run it as a step and say what it
+  covers, rather than leaving a reviewer to assume the build covered it.
+
   Negative case: equally important for a security tool. State what must still be
   rejected, and how a reviewer confirms that Ares has not become more permissive.
 

.github/scripts/CheckPullRequestTemplate.java

@@ -39,7 +39,7 @@ jobs:
           cache: "maven"
 
       - name: Initialise CodeQL
-        uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
         with:
           languages: java
           build-mode: manual
@@ -48,4 +48,4 @@ jobs:
         run: mvn -B -DskipTests package
 
       - name: Perform CodeQL analysis
-        uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7

.github/workflows/codeql.yml

@@ -105,13 +105,16 @@ rule is an approximation in the other direction too, since four columns under a
 continue that paragraph in Markdown; the Javadoc of the checker says why the line is drawn
 where it is.
 
-Two shapes pay for that four-column rule, and both were accepted knowingly. An indented
-example showing the template's own skeleton, a bare `1.` inside a comment, is read as a
-blank somebody forgot. And a literal comment marker inside code, above a genuine comment
-further down, can leave the genuine one unhidden, so a heading inside it is counted and the
-author is told they wrote a section twice. Both are wrong about a body written in good
-faith, and both are the accepted cost of the rule that closes a hole where text hid from
-the length count. It deliberately does not require checklist boxes to be ticked. It
+One shape pays for that four-column rule, knowingly: an indented example showing the
+template's own skeleton, a bare `1.` inside a comment, is read as a blank somebody forgot.
+That is wrong about a body written in good faith, and is the accepted cost of closing a
+hole where text hid from the length count.
+
+What is not prose is found in one left-to-right walk rather than by searching for comments,
+fenced blocks and code spans separately. That walk is what settles the overlaps between the
+three: a fence opening a line beats a code span left open above it because Markdown decides
+blocks first, and a span covers what it holds, so a comment marker inside one is text rather
+than the start of a comment. It deliberately does not require checklist boxes to be ticked. It
 re-runs when the description is edited, so a failure is fixed by editing the body rather
 than by pushing a commit.
 
@@ -128,6 +131,21 @@ PR_BODY="$(cat body.md)" java .github/scripts/CheckPullRequestTemplate.java
 The checker is a single-file Java program, run through the source-code launcher of JDK 11 or
 newer, so it needs no build step and adds no language to the repository. CI runs it on 21.
 
+**Only the template's own headings.** The check reports every line it reads as a heading that
+the template does not define, sub-headings included. A section of your own is never checked: the
+checker cuts out the required headings only, so whatever sits under an invented one is measured
+as part of the section above it, and what its title promises is never looked for. Put the text
+in the section it belongs to, or in a comment on the pull request, which is where anything
+outside the template's shape goes.
+
+What it reads as a heading is a line of up to three spaces, then one to six hashes, then a
+space, a tab or the end of the line, outside comments, fenced blocks and code between backticks.
+`#hashtag` and seven hashes are therefore not headings to it. It does not find a heading
+underlined with equals signs, nor one indented into a quotation or a list; those pass. It does
+not recognise raw HTML blocks either, so such a line inside `<pre>` or `<details>` is reported.
+Put a line you do not mean as a heading in a fenced code block, where the checker does not treat
+it as one.
+
 **Changing the template is two edits, not one.** The required headings, the character
 limits and the phrases that answer a section live in one ordered map, `SECTIONS`, at the
 top of `.github/scripts/CheckPullRequestTemplate.java`, in the order the template puts them

AGENTS.md

@@ -459,7 +459,7 @@ Defines five scanning methods that auto-detect project metadata:
 |---|---|---|
 | `scanForBuildMode()` | `BuildMode` | Whether the project uses Maven (`pom.xml`) or Gradle (`build.gradle`) |
 | `scanForTestClasses()` | `String[]` | Fully qualified names of all classes in the **test source directory** containing `@Test` or `@Property` annotations, or extending JUnit 3's `TestCase` |
-| `scanForPackageName()` | `String` | The most frequently used non-reserved package declaration across all `.java` files |
+| `scanForPackageName()` | `String` | The most frequently used non-reserved package: taken from the production sources, otherwise from the compiled production output, otherwise the configured default |
 | `scanForMainClassInPackage()` | `String` | The class containing `public static void main(String[])` |
 | `scanForTestPath()` | `Path` | The file system path to the test source directory |
 
@@ -468,33 +468,65 @@ Defines five scanning methods that auto-detect project metadata:
 | Aspect | Detail |
 |---|---|
 | **Implements** | `ProjectScanner` |
-| **Technique** | Regex-based source code analysis. Walks all `.java` files under the project root and applies four compiled regex patterns. |
+| **Technique** | JavaParser-backed source analysis. Walks the `.java` files under the discovered source roots and reads the parsed syntax tree; the compiled output is read with ArchUnit's `ClassFileImporter` where the sources yield nothing. |
 
-**Regex patterns:**
+**What is read from the syntax tree:**
 
-| Pattern | Matches | Used by |
+| Fact | Read from | Used by |
 |---|---|---|
-| `CLASS_PATTERN` | `public [final\|abstract\|strictfp] class ClassName` | `extractClassName()` |
-| `PACKAGE_PATTERN` | `package com.example.foo;` | `extractPackageName()` |
-| `MAIN_METHOD_PATTERN` | `public static void main(String[] args)` (including varargs) | `extractMainClass()` |
-| `TEST_ANNOTATION_PATTERN` | `@Test` or `@Property` | `extractTestClass()` (which treats classes containing `extends TestCase` as test classes) |
+| Package declaration | the compilation unit's `PackageDeclaration` | `scanForPackageName()` |
+| Type declarations | the top-level `TypeDeclaration`s, nested types included | `scanForMainClassInPackage()`, `scanForTestClasses()` |
+| `main` method | a `public static void main(String[])` declaration, varargs included | `scanForMainClassInPackage()` |
+| Test classes | a `@Test` or `@Property` annotation, or a JUnit 3 `TestCase` supertype resolved through the imports of the file | `scanForTestClasses()` |
+
+Resolving the supertype through the imports is why this is not a regex: `extends TestCase` names a type, and which type it names depends on what the file imported.
 
 **Scanning pipeline:**
 
 ```
-ProjectSourcesFinder.findProjectSourcesPath()
-  → Files.find(sourcePath, MAX_VALUE, isJavaFile)
-    → Files.readString(file)
-      → extractor.apply(content)
+ProjectSourcesFinder.discover(projectRoot, mode)      → BuildToolConfiguration
+  → configuration.productionSourceRoots() / testSourceRoots()
+    → Files.walk(root), filtered to *.java and sorted
+      → JavaParser.parse(file) → CompilationUnit
+  and, where the sources answer nothing:
+  → ClassFileImporter().importPath(productionOutputRoot)
 ```
 
-**`scanForPackageName()` algorithm:** First filters out reserved infrastructure prefixes (via `ReservedPackageGuard.reservedPrefixOf(...)`) so a student cannot flood the project with files in a trusted namespace to make it the derived enforcement scope → counts the frequency of every remaining `package` declaration across all files → returns the most common one. This heuristic works because in a typical student project, the main source package appears in the majority of files.
+The sort is not cosmetic: it is what makes two runs over one project agree.
+The legacy `findProjectSourcesPath()` route still exists for callers that
+predate `BuildToolConfiguration`, and differs in kind: it returns the
+descriptor's own string, relative and unvalidated, where `discover(...)`
+canonicalises every root and refuses one that escapes the project.
+
+**`scanForPackageName()` algorithm:** Resolution runs in three steps, each reached only when the previous one finds nothing at all.
+
+1. **Production sources.** Reserved infrastructure prefixes are filtered out first (via `ReservedPackageGuard.reservedPrefixOf(...)`), so a package inside a trusted namespace cannot become the derived enforcement scope. The frequency of every remaining `package` declaration is counted and the most common one wins. This heuristic works because in a typical student project the main source package appears in the majority of files.
+2. **Compiled production output.** Only top-level classes are counted, so a package is not weighted by how many nested or anonymous classes it happens to contain; nesting is read from the class file rather than from the `$` in the binary name, which is a legal identifier character. This step covers a project whose build descriptor the source-root discovery cannot parse, because the build tool writes its output to the conventional directory the scanner reads.
+3. **The configured default** (see [Section 10.3](#103-javaprogrammingexerciseprojectscanner)), with a warning naming the roots that were searched.
+
+Step 1 is skipped entirely when the discovered source roots are not known to be the whole of the main source set. A Gradle descriptor can declare a root this reader cannot resolve, such as a computed list, and `BuildToolConfiguration.productionRootsComplete()` reports that. Counting declarations across part of a project produces an answer indistinguishable from one taken across all of it, so a partial set is not counted at all and the compiled output is read instead.
+
+> **The derived package is a heuristic. What turns it into a boundary is the check that follows it.**
+>
+> Before enforcement is armed, `requireDerivedScopeToCoverTheProject()` reads the compiled production output and refuses the run unless **every** executable top-level class declares a non-blank, non-reserved package that is the derived scope or lies below it, compared on segment boundaries so that `de.tum.cit.aet` does not swallow `de.tum.cit.aetevil`. A class the scope leaves out, a class in the default package, a class in a reserved package, and an output root that exists but cannot be read are each refused by name. This runs on the policy-free path only: a pinned policy may deliberately supervise part of the output, and narrowing it is then the instructor's decision.
+>
+> **An output root holding nothing passes, with a warning, and so does one holding only `package-info` or `module-info`.** There is then no supervisable class, so enforcement is vacuous rather than mis-scoped, and an exercise whose supervised package is still empty must not fail for being empty. The generated test does the same: `JavaArchunitSupervisedClasses` warns and analyses an empty set rather than refusing. In both places that log line is the only signal, and a suite that analyses nothing reports success.
+>
+> That closes the case where a decoy package is voted the scope while the assignment runs beside it. Three things it still does not establish.
+>
+> The **vote is influenceable by whoever can add files to the project**, and in an Artemis exercise that includes the student. The check above refuses a scope that leaves compiled classes out, but not one drawn *around* them: a scope that covers everything passes by construction. The package-import allow-list no longer follows the scope for that reason, and names the packages the validated output declares instead.
+>
+> The **output directory is assumed, not read**. Step 2 and the check both look in `target/classes` or `build/classes/java/main`, so a build that writes its output elsewhere is not followed there. Together with the vacuous pass above, that is the sharp edge of this section: a project whose output goes somewhere else looks exactly like a project that compiled nothing, and both pass with the same warning. An exercise configured with a custom output destination is therefore not enforced by the derived path at all, and nothing fails to say so. Such an exercise must declare its scope in a policy.
+>
+> **The last-resort default guarantees nothing by itself.** If the project does not contain it, the analysis path resolves to a directory that does not exist. Where anything at all is compiled, the check above catches it: those classes lie outside the default, so the run is refused by name. Where nothing is compiled it does not, and the warning is again all a reader gets. During generation, before anything is compiled, the same is true.
+>
+> An exercise that needs a scope it can rely on declares its package in the security policy. The scanner is then not consulted at all, which is the only version of this that cannot be steered from the submission.
 
 **`scanForTestClasses()` algorithm:** Scans only the **test source directory** (see `scanForTestPath()`) and returns every class whose file contains a `@Test` / `@Property` annotation or `extends TestCase`.
 
 **`scanForMainClassInPackage()` algorithm:** Collects all classes with a `main` method → prefers a class named `Main` or `Application` → otherwise returns the first match → defaults to `"Main"`.
 
-**`scanForTestPath()` algorithm:** Checks for Gradle's custom `srcDir 'test'` → falls back to `src/test/java`.
+**`scanForTestPath()` algorithm:** Answers the first discovered test source root; without a build configuration it accepts the conventional `src/test/java`, or a bare `test/` directory for the Artemis Gradle layout, and otherwise falls back to the literal `src/test/java` **whether or not it exists**. That fall-back is a placeholder forced by the non-null return type rather than a claim, and no production code currently consults this method.
 
 ### 10.3 `JavaProgrammingExerciseProjectScanner`
 
@@ -505,7 +537,7 @@ ProjectSourcesFinder.findProjectSourcesPath()
 
 | Override | Default in `JavaProjectScanner` | Override in `JavaProgrammingExerciseProjectScanner` |
 |---|---|---|
-| Default package | `""` (empty string) | `"de.tum.cit.ase"` |
+| Default package | `""` (empty string) | `"de.tum.cit.aet"` |
 | Default main class | `"Main"` | `"Main"` (unchanged) |
 
 When the base scanner finds no package or main class, these TUM-specific defaults ensure reasonable behaviour for Artemis-hosted exercises.

documentation/docs/contributor/subsystems/securitytest/test-case-factory-and-builder.md

@@ -112,6 +112,11 @@ it cannot rise without somebody writing the higher number down in a commit. A ru
 entry has a ceiling of zero, so adding a rule and leaving it unrecorded fails rather than
 passing unnoticed.
 
+One case raises a number honestly: a merge that brings in a page written before these rules
+existed. The text arrives already over the line, and holding the merge hostage to an editorial
+pass on somebody else's page helps nobody. Record the higher number in the merge commit, say
+which merge raised it, and let the next pass over that page bring it down again.
+
 That is what stops 1,192 advisory findings quietly becoming 1,500. The counts are not a target to
 drive to zero. `active-voice` in particular never reaches it, because a security reference
 describes what happens to code and some of that is genuinely agentless. They are a direction.

documentation/docs/contributor/writing-rules.md

@@ -1,12 +1,12 @@
 {
-  "why": "The advisory findings each rule is allowed. These numbers may only fall; see scripts/prose/cli.mjs. Lower one by improving the prose, never by editing it here.",
+  "why": "The advisory findings each rule is allowed. Lower one by improving the prose, never by editing it here. A number rises only where a merge brings in text written before these rules existed, and only in the commit that brings it; see scripts/prose/cli.mjs.",
   "ceiling": {
-    "active-voice": 760,
+    "active-voice": 772,
     "address-the-reader": 45,
     "context-filler": 19,
-    "long-sentence": 111,
+    "long-sentence": 115,
     "no-intensifiers": 24,
-    "prefer-must": 150,
+    "prefer-must": 151,
     "present-tense": 83
   }
 }

documentation/scripts/prose/advisory-ceiling.json

@@ -249,8 +249,9 @@ async function accept() {
 
     const counts = [...advisoryCounts(findings)].sort((left, right) => left[0].localeCompare(right[0]));
     await writeFile(CEILING, `${JSON.stringify({
-        why: 'The advisory findings each rule is allowed. These numbers may only fall; see '
-            + 'scripts/prose/cli.mjs. Lower one by improving the prose, never by editing it here.',
+        why: 'The advisory findings each rule is allowed. Lower one by improving the prose, never '
+            + 'by editing it here. A number rises only where a merge brings in text written before '
+            + 'these rules existed, and only in the commit that brings it; see scripts/prose/cli.mjs.',
         ceiling: Object.fromEntries(counts),
     }, null, 2)}\n`, 'utf8');
 

documentation/scripts/prose/cli.mjs

@@ -45,7 +45,7 @@
 			${user.home}${file.separator}.m2${file.separator}repository${file.separator}org${file.separator}aspectj${file.separator}aspectjrt${file.separator}${aspectj-version}${file.separator}aspectjrt-${aspectj-version}.jar
 		</aspectj-path>
 		<!-- 3. AOP: 3.2 Byte Buddy -->
-		<byte-buddy-version>1.18.11</byte-buddy-version>
+		<byte-buddy-version>1.18.12</byte-buddy-version>
 		<byte-buddy-path>
 			${project.build.directory}${file.separator}${project.artifactId}-${project.version}-agent.jar
 		</byte-buddy-path>
@@ -62,18 +62,18 @@
 		<!-- 4. AST: 4.1 JavaParser -->
 		<java-parser-version>3.28.2</java-parser-version>
 		<!-- 5. Formats: YAML and XML (JSON handled via Jackson) -->
-		<yaml-version>2.22.1</yaml-version>
+		<yaml-version>2.22.2</yaml-version>
 		<!-- 6. Large Tooling Libraries -->
 		<commons-io-version>2.22.0</commons-io-version>
 		<jaxb-api-version>2.3.1</jaxb-api-version>
 		<!-- 7. Small Tooling Libraries -->
 		<jgrapht-core-version>1.5.3</jgrapht-core-version>
 		<!-- 8. Logging  -->
-		<logback-version>1.6.1</logback-version>
+		<logback-version>1.6.3</logback-version>
 		<!-- 8. API  -->
 		<apiguardian-api-version>1.1.2</apiguardian-api-version>
 		<!-- Others -->
-		<spotless.version>3.9.0</spotless.version>
+		<spotless.version>3.10.0</spotless.version>
 		<!-- if JaCoCo is not executed -->
 		<argLine></argLine>
 		<!-- Isolate test classes so WALA state and test-created threads cannot accumulate
@@ -874,7 +874,7 @@
 			<plugin>
 				<groupId>com.github.spotbugs</groupId>
 				<artifactId>spotbugs-maven-plugin</artifactId>
-				<version>4.10.3.0</version>
+				<version>4.10.4.0</version>
 				<configuration>
 					<excludeFilterFile>${basedir}${file.separator}.settings${file.separator}spotbugs-exclude.xml</excludeFilterFile>
 					<failOnError>true</failOnError>