This is an automated email from the ASF dual-hosted git repository. borinquenkid pushed a commit to branch fix/groovydoc-links in repository https://gitbox.apache.org/repos/asf/grails-core.git
commit 978a57123d4f17050d2a54442358c8f4a96f9bfa Author: Walter Duque de Estrada <[email protected]> AuthorDate: Fri Jul 17 16:40:29 2026 -0500 Decouple auditGroovydocLinks from the default docs build and add test coverage jdaugherty flagged that wiring auditGroovydocLinks as an unconditional dependency of the docs task would fail the build the moment any violation is found - and the author's own investigation on this PR noted ~30 residual "phantom" link reports that aren't real errors, so merging as-is would have broken every future docs build. Keep the task registered and runnable on demand (./gradlew :grails-doc:auditGroovydocLinks) without wiring it into docsTask.dependsOn. Also extract the violation-detection logic into a Gradle-API-free GroovydocLinkAuditor so it's unit testable - build-logic/docs-core deliberately keeps Gradle classes off the test compile classpath (see docs-core/build.gradle), so the previous DefaultTask-only implementation had no path to test coverage. Co-Authored-By: Claude Sonnet 5 <[email protected]> --- .../doc/gradle/AuditGroovydocLinksTask.groovy | 42 +---------- .../grails/doc/gradle/GroovydocLinkAuditor.groovy | 85 ++++++++++++++++++++++ .../doc/gradle/GroovydocLinkAuditorSpec.groovy | 82 +++++++++++++++++++++ grails-doc/build.gradle | 2 +- 4 files changed, 169 insertions(+), 42 deletions(-) diff --git a/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/AuditGroovydocLinksTask.groovy b/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/AuditGroovydocLinksTask.groovy index f4a567e925..b809bf81ef 100644 --- a/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/AuditGroovydocLinksTask.groovy +++ b/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/AuditGroovydocLinksTask.groovy @@ -22,9 +22,6 @@ import org.gradle.api.DefaultTask import org.gradle.api.file.DirectoryProperty import org.gradle.api.tasks.InputDirectory import org.gradle.api.tasks.TaskAction -import java.nio.file.* -import java.util.regex.Matcher -import java.util.regex.Pattern /** * A task that audits generated Groovydocs for malformed navigation links. @@ -44,45 +41,8 @@ abstract class AuditGroovydocLinksTask extends DefaultTask { return } - // Patterns common to Groovydoc navigation failures - Map<Pattern, String> replacements = [ - (Pattern.compile(/href='([^']+?)\/deprecated-list\.html'/)): "href='deprecated-list.html'", - (Pattern.compile(/href='([^']+?)\/help-doc\.html'/)): "href='help-doc.html'", - (Pattern.compile(/href='([^']+?)\/index-all\.html'/)): "href='index-all.html'", - (Pattern.compile(/href='([^']+?)\/overview-summary\.html'/)): "href='overview-summary.html'" - ] + List<String> violations = GroovydocLinkAuditor.findViolations(apiDir) - List<String> violations = [] - - apiDir.eachFileRecurse { File file -> - if (file.name.endsWith(".html")) { - String content = file.text - - replacements.each { pattern, replacement -> - Matcher matcher = pattern.matcher(content) - if (matcher.find()) { - violations << "Malformed nav link in ${file.name}: ${matcher.group(0)}" - } - } - - // Check specific inner class path issues like Query/Order.Direction.html -> Query.Order.Direction.html - Pattern innerClassPattern = Pattern.compile(/href='([^']+?)\/([A-Z][A-Za-z0-9_]*?)\/([A-Z][A-Za-z0-9_.]*?\.html)'/) - Matcher innerMatcher = innerClassPattern.matcher(content) - while (innerMatcher.find()) { - String relPath = innerMatcher.group(1) - String outer = innerMatcher.group(2) - String inner = innerMatcher.group(3) - - Path currentPath = file.toPath().parent - Path targetPath = currentPath.resolve(relPath).resolve("${outer}.${inner}").normalize() - - if (Files.exists(targetPath)) { - violations << "Malformed inner class link in ${file.name}: ${innerMatcher.group(0)}" - } - } - } - } - if (!violations.isEmpty()) { violations.take(10).each { logger.error(it) } if (violations.size() > 10) logger.error("... and ${violations.size() - 10} more") diff --git a/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/GroovydocLinkAuditor.groovy b/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/GroovydocLinkAuditor.groovy new file mode 100644 index 0000000000..9a79823be0 --- /dev/null +++ b/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/GroovydocLinkAuditor.groovy @@ -0,0 +1,85 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.grails.doc.gradle + +import java.nio.file.Files +import java.nio.file.Path +import java.util.regex.Matcher +import java.util.regex.Pattern + +/** + * Scans generated Groovydoc HTML for malformed navigation and inner-class + * links. Kept free of the Gradle API so it can be unit tested directly - + * {@code build-logic/docs-core} deliberately keeps Gradle classes off the + * test compile classpath. + */ +class GroovydocLinkAuditor { + + // Patterns common to Groovydoc navigation failures + private static final Map<Pattern, String> NAV_LINK_PATTERNS = [ + (Pattern.compile(/href='([^']+?)\/deprecated-list\.html'/)): "href='deprecated-list.html'", + (Pattern.compile(/href='([^']+?)\/help-doc\.html'/)): "href='help-doc.html'", + (Pattern.compile(/href='([^']+?)\/index-all\.html'/)): "href='index-all.html'", + (Pattern.compile(/href='([^']+?)\/overview-summary\.html'/)): "href='overview-summary.html'" + ].asImmutable() + + // Inner class path issues like Query/Order.Direction.html -> Query.Order.Direction.html + private static final Pattern INNER_CLASS_LINK_PATTERN = + Pattern.compile(/href='([^']+?)\/([A-Z][A-Za-z0-9_]*?)\/([A-Z][A-Za-z0-9_.]*?\.html)'/) + + static List<String> findViolations(File apiDir) { + List<String> violations = [] + + apiDir.eachFileRecurse { File file -> + if (file.name.endsWith('.html')) { + violations.addAll(findViolationsInFile(file)) + } + } + + violations + } + + private static List<String> findViolationsInFile(File file) { + List<String> violations = [] + String content = file.text + + NAV_LINK_PATTERNS.each { Pattern pattern, String replacement -> + Matcher matcher = pattern.matcher(content) + if (matcher.find()) { + violations << "Malformed nav link in ${file.name}: ${matcher.group(0)}".toString() + } + } + + Matcher innerMatcher = INNER_CLASS_LINK_PATTERN.matcher(content) + while (innerMatcher.find()) { + String relPath = innerMatcher.group(1) + String outer = innerMatcher.group(2) + String inner = innerMatcher.group(3) + + Path currentPath = file.toPath().parent + Path targetPath = currentPath.resolve(relPath).resolve("${outer}.${inner}").normalize() + + if (Files.exists(targetPath)) { + violations << "Malformed inner class link in ${file.name}: ${innerMatcher.group(0)}".toString() + } + } + + violations + } +} diff --git a/build-logic/docs-core/src/test/groovy/org/grails/doc/gradle/GroovydocLinkAuditorSpec.groovy b/build-logic/docs-core/src/test/groovy/org/grails/doc/gradle/GroovydocLinkAuditorSpec.groovy new file mode 100644 index 0000000000..1a3cea6584 --- /dev/null +++ b/build-logic/docs-core/src/test/groovy/org/grails/doc/gradle/GroovydocLinkAuditorSpec.groovy @@ -0,0 +1,82 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.grails.doc.gradle + +import spock.lang.Specification +import spock.lang.TempDir + +class GroovydocLinkAuditorSpec extends Specification { + + @TempDir + File apiDir + + void "reports no violations for clean navigation and inner class links"() { + given: + writeHtml('index.html', """ + <a href='deprecated-list.html'>Deprecated</a> + <a href='help-doc.html'>Help</a> + <a href='SomePackage.SomeClass.html'>SomeClass</a> + """) + + expect: + GroovydocLinkAuditor.findViolations(apiDir).empty + } + + void "flags a navigation link that is nested under a relative path prefix"() { + given: + writeHtml('index.html', "<a href='../deprecated-list.html'>Deprecated</a>") + + when: + List<String> violations = GroovydocLinkAuditor.findViolations(apiDir) + + then: + violations.size() == 1 + violations[0].contains('deprecated-list.html') + violations[0].contains('index.html') + } + + void "flags an inner class link using a slash-separated path when the dotted file actually exists"() { + given: 'the real generated file uses the dotted Groovydoc naming convention' + writeHtml('Query.Order.Direction.html', '<p>Direction</p>') + and: 'another page links to it using a malformed slash-separated path' + writeHtml('index.html', "<a href='./Query/Order.Direction.html'>Direction</a>") + + when: + List<String> violations = GroovydocLinkAuditor.findViolations(apiDir) + + then: + violations.size() == 1 + violations[0].contains('Query/Order.Direction.html') + } + + void "does not flag a slash-separated inner class link when no dotted file exists to resolve to"() { + given: 'the referenced target was never generated, so this cannot be the known malformed-path case' + writeHtml('index.html', "<a href='./Query/Order.Direction.html'>Direction</a>") + + expect: + GroovydocLinkAuditor.findViolations(apiDir).empty + } + + private File writeHtml(String relativePath, String content) { + File file = new File(apiDir, relativePath) + file.parentFile.mkdirs() + file.text = content + file + } +} diff --git a/grails-doc/build.gradle b/grails-doc/build.gradle index ddba680a44..8d4991992f 100644 --- a/grails-doc/build.gradle +++ b/grails-doc/build.gradle @@ -660,7 +660,7 @@ createReleaseDropdownTask.configure { def docsTask = tasks.register('docs', Sync) docsTask.configure { Sync it -> - it.dependsOn(combinedGroovydoc, auditGroovydocLinks, createReleaseDropdownTask, ':grails-data-docs-stage:docs', ':grails-data-docs-stage:groovydoc') + it.dependsOn(combinedGroovydoc, createReleaseDropdownTask, ':grails-data-docs-stage:docs', ':grails-data-docs-stage:groovydoc') it.group = 'documentation' def manualDocsDir = project.layout.buildDirectory.dir('modified-guide')
