You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@grails.apache.org by bo...@apache.org on 2026/07/17 22:10:06 UTC
(grails-core) branch fix/groovydoc-links created (now 978a57123d)
This is an automated email from the ASF dual-hosted git repository.
borinquenkid pushed a change to branch fix/groovydoc-links
in repository https://gitbox.apache.org/repos/asf/grails-core.git
at 978a57123d Decouple auditGroovydocLinks from the default docs build and add test coverage
This branch includes the following new commits:
new 2c6c661fdd docs: fix broken external and internal links in Groovydocs and add audit mode
new b168d32ffb refactor: rename groovydoc link check to audit task and remove property control
new 978a57123d Decouple auditGroovydocLinks from the default docs build and add test coverage
The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(grails-core) 01/03: docs: fix broken external and internal links in Groovydocs and add audit mode
Posted by bo...@apache.org.
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 2c6c661fddee71dc9258ee749c2dfb27e431536c
Author: Sanjana <sa...@gmail.com>
AuthorDate: Sat Apr 18 11:22:31 2026 +0530
docs: fix broken external and internal links in Groovydocs and add audit mode
---
.../grails/doc/gradle/FixGroovydocLinksTask.groovy | 119 +++++++++++++++++++++
gradle/docs-dependencies.gradle | 37 +++++--
grails-doc/build.gradle | 9 +-
3 files changed, 154 insertions(+), 11 deletions(-)
diff --git a/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/FixGroovydocLinksTask.groovy b/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/FixGroovydocLinksTask.groovy
new file mode 100644
index 0000000000..cc9d959778
--- /dev/null
+++ b/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/FixGroovydocLinksTask.groovy
@@ -0,0 +1,119 @@
+/*
+ * 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 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 repairs malformed navigation links in generated Groovydocs.
+ * Specifically targets 'phantom' links and relative path issues in navigation files
+ * like overview-summary.html, deprecated-list.html, and help-doc.html.
+ */
+abstract class FixGroovydocLinksTask extends DefaultTask {
+
+ /**
+ * If true, the task will fail the build if any malformed links are found.
+ * If false, the task will attempt to repair the links (patching mode).
+ */
+ @org.gradle.api.tasks.Input
+ boolean auditMode = false
+
+ @InputDirectory
+ abstract DirectoryProperty getApiDocsDir()
+
+ @TaskAction
+ void fixLinks() {
+ File apiDir = apiDocsDir.get().asFile
+ if (!apiDir.exists()) {
+ logger.warn "API documentation directory does not exist: ${apiDir.absolutePath}"
+ 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'"
+ ]
+
+ int totalFixes = 0
+ List<String> violations = []
+
+ apiDir.eachFileRecurse { File file ->
+ if (file.name.endsWith(".html")) {
+ String content = file.text
+ boolean changed = false
+
+ replacements.each { pattern, replacement ->
+ Matcher matcher = pattern.matcher(content)
+ if (matcher.find()) {
+ content = matcher.replaceAll(replacement)
+ changed = true
+ violations << "Malformed nav link in ${file.name}"
+ }
+ }
+
+ // Fix 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)) {
+ String newHref = "href='${relPath}/${outer}.${inner}'"
+ content = content.replace(innerMatcher.group(0), newHref)
+ changed = true
+ violations << "Malformed inner class link in ${file.name}: ${innerMatcher.group(0)} -> ${newHref}"
+ }
+ }
+
+ if (changed) {
+ totalFixes++
+ if (!auditMode) {
+ file.text = content
+ }
+ }
+ }
+ }
+
+ if (totalFixes > 0) {
+ if (auditMode) {
+ violations.take(10).each { logger.error(it) }
+ if (violations.size() > 10) logger.error("... and ${violations.size() - 10} more")
+ throw new org.gradle.api.GradleException("Found ${violations.size()} malformed links in Groovydoc. Please fix the source issue rather than patching. See logs for details.")
+ } else {
+ logger.lifecycle "Repaired ${totalFixes} HTML files in ${apiDir.absolutePath}"
+ }
+ } else {
+ logger.lifecycle "No malformed Groovydoc links found in ${apiDir.absolutePath}"
+ }
+ }
+}
diff --git a/gradle/docs-dependencies.gradle b/gradle/docs-dependencies.gradle
index fd33607c98..a032a7cc43 100644
--- a/gradle/docs-dependencies.gradle
+++ b/gradle/docs-dependencies.gradle
@@ -31,16 +31,10 @@ dependencies {
}
String resolveProjectVersion(String artifact) {
- String version = configurations.runtimeClasspath
- .resolvedConfiguration
- .resolvedArtifacts
- .find {
- it.moduleVersion.id.name == artifact
- }?.moduleVersion?.id?.version
- if (!version) {
- return null
+ def component = configurations.runtimeClasspath.incoming.resolutionResult.allComponents.find {
+ it.moduleVersion?.name == artifact
}
- version
+ return component?.moduleVersion?.version
}
def configureGroovyDoc = tasks.register('configureGroovyDoc') {
@@ -56,12 +50,35 @@ def configureGroovyDoc = tasks.register('configureGroovyDoc') {
}
def springVersion = resolveProjectVersion('spring-core')
if (springVersion) {
- links << [packages: 'org.springframework.core.', href: "https://docs.spring.io/spring-framework/docs/${springVersion}/javadoc-api/"]
+ links << [packages: 'org.springframework.', href: "https://docs.spring.io/spring-framework/docs/${springVersion}/javadoc-api/"]
}
def springBootVersion = resolveProjectVersion('spring-boot')
if (springBootVersion) {
links << [packages: 'org.springframework.boot.', href: "https://docs.spring.io/spring-boot/docs/${springBootVersion}/api/"]
}
+ def hibernateVersion = resolveProjectVersion('hibernate-core')
+ if (hibernateVersion) {
+ def shortVersion = hibernateVersion.split('\\.').take(2).join('.')
+ links << [packages: 'org.hibernate.', href: "https://docs.jboss.org/hibernate/orm/${shortVersion}/javadocs/"]
+ }
+ def jakartaValidationVersion = resolveProjectVersion('jakarta.validation-api')
+ if (jakartaValidationVersion) {
+ links << [packages: 'jakarta.validation.', href: "https://jakarta.ee/specifications/bean-validation/3.0/apidocs/"]
+ }
+ def jakartaPersistenceVersion = resolveProjectVersion('jakarta.persistence-api')
+ if (jakartaPersistenceVersion) {
+ links << [packages: 'jakarta.persistence.', href: "https://jakarta.ee/specifications/persistence/3.1/apidocs/"]
+ }
+ def jakartaServletVersion = resolveProjectVersion('jakarta.servlet-api')
+ if (jakartaServletVersion) {
+ links << [packages: 'jakarta.servlet.', href: "https://jakarta.ee/specifications/platform/10/apidocs/"]
+ }
+ links << [packages: 'org.grails.datastore.', href: "https://gorm.grails.org/latest/api/"]
+ links << [packages: 'grails.gorm.', href: "https://gorm.grails.org/latest/api/"]
+ links << [packages: 'org.grails.gorm.', href: "https://gorm.grails.org/latest/api/"]
+ links << [packages: 'groovy.', href: "https://docs.groovy-lang.org/latest/html/gapi/"]
+ links << [packages: 'org.apache.groovy.', href: "https://docs.groovy-lang.org/latest/html/gapi/"]
+ links << [packages: 'org.codehaus.groovy.', href: "https://docs.groovy-lang.org/latest/html/gapi/"]
if (it.ext.has('groovydocLinks')) {
links.addAll(it.ext.groovydocLinks as List<Map<String, String>>)
}
diff --git a/grails-doc/build.gradle b/grails-doc/build.gradle
index d7a5cf71b0..0bb7904fbc 100644
--- a/grails-doc/build.gradle
+++ b/grails-doc/build.gradle
@@ -21,6 +21,7 @@ import grails.doc.git.FetchTagsTask
import grails.doc.dropdown.CreateReleaseDropDownTask
import grails.doc.gradle.PublishGuideTask
import groovy.json.JsonSlurper
+import org.grails.doc.gradle.FixGroovydocLinksTask
import java.util.zip.ZipFile
@@ -125,6 +126,12 @@ combinedGroovydoc.configure { Groovydoc gdoc ->
gdoc.outputs.dir(gdoc.destinationDir)
}
+def fixGroovydocLinks = tasks.register('fixGroovydocLinks', FixGroovydocLinksTask) {
+ dependsOn combinedGroovydoc
+ apiDocsDir = combinedGroovydoc.get().destinationDir
+ auditMode = project.hasProperty('auditGroovydocLinks')
+}
+
String getVersion(String artifact) {
String version = configurations.runtimeClasspath
.resolvedConfiguration
@@ -654,7 +661,7 @@ createReleaseDropdownTask.configure {
def docsTask = tasks.register('docs', Sync)
docsTask.configure { Sync it ->
- it.dependsOn(combinedGroovydoc, createReleaseDropdownTask, ':grails-data-docs-stage:docs', ':grails-data-docs-stage:groovydoc')
+ it.dependsOn(combinedGroovydoc, fixGroovydocLinks, createReleaseDropdownTask, ':grails-data-docs-stage:docs', ':grails-data-docs-stage:groovydoc')
it.group = 'documentation'
def manualDocsDir = project.layout.buildDirectory.dir('modified-guide')
(grails-core) 03/03: Decouple auditGroovydocLinks from the default docs build and add test coverage
Posted by bo...@apache.org.
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 <wb...@mac.com>
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 <no...@anthropic.com>
---
.../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')
(grails-core) 02/03: refactor: rename groovydoc link check to audit task and remove property control
Posted by bo...@apache.org.
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 b168d32ffbf4cd35538c623c2633e8ebdd43a15d
Author: Sanjana <sa...@gmail.com>
AuthorDate: Wed Apr 22 01:39:40 2026 +0530
refactor: rename groovydoc link check to audit task and remove property control
---
...sTask.groovy => AuditGroovydocLinksTask.groovy} | 45 +++++-----------------
grails-doc/build.gradle | 7 ++--
2 files changed, 13 insertions(+), 39 deletions(-)
diff --git a/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/FixGroovydocLinksTask.groovy b/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/AuditGroovydocLinksTask.groovy
similarity index 67%
rename from build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/FixGroovydocLinksTask.groovy
rename to build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/AuditGroovydocLinksTask.groovy
index cc9d959778..f4a567e925 100644
--- a/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/FixGroovydocLinksTask.groovy
+++ b/build-logic/docs-core/src/main/groovy/org/grails/doc/gradle/AuditGroovydocLinksTask.groovy
@@ -27,24 +27,17 @@ import java.util.regex.Matcher
import java.util.regex.Pattern
/**
- * A task that repairs malformed navigation links in generated Groovydocs.
+ * A task that audits generated Groovydocs for malformed navigation links.
* Specifically targets 'phantom' links and relative path issues in navigation files
* like overview-summary.html, deprecated-list.html, and help-doc.html.
*/
-abstract class FixGroovydocLinksTask extends DefaultTask {
-
- /**
- * If true, the task will fail the build if any malformed links are found.
- * If false, the task will attempt to repair the links (patching mode).
- */
- @org.gradle.api.tasks.Input
- boolean auditMode = false
+abstract class AuditGroovydocLinksTask extends DefaultTask {
@InputDirectory
abstract DirectoryProperty getApiDocsDir()
@TaskAction
- void fixLinks() {
+ void auditLinks() {
File apiDir = apiDocsDir.get().asFile
if (!apiDir.exists()) {
logger.warn "API documentation directory does not exist: ${apiDir.absolutePath}"
@@ -59,24 +52,20 @@ abstract class FixGroovydocLinksTask extends DefaultTask {
(Pattern.compile(/href='([^']+?)\/overview-summary\.html'/)): "href='overview-summary.html'"
]
- int totalFixes = 0
List<String> violations = []
apiDir.eachFileRecurse { File file ->
if (file.name.endsWith(".html")) {
String content = file.text
- boolean changed = false
replacements.each { pattern, replacement ->
Matcher matcher = pattern.matcher(content)
if (matcher.find()) {
- content = matcher.replaceAll(replacement)
- changed = true
- violations << "Malformed nav link in ${file.name}"
+ violations << "Malformed nav link in ${file.name}: ${matcher.group(0)}"
}
}
- // Fix specific inner class path issues like Query/Order.Direction.html -> Query.Order.Direction.html
+ // 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()) {
@@ -88,30 +77,16 @@ abstract class FixGroovydocLinksTask extends DefaultTask {
Path targetPath = currentPath.resolve(relPath).resolve("${outer}.${inner}").normalize()
if (Files.exists(targetPath)) {
- String newHref = "href='${relPath}/${outer}.${inner}'"
- content = content.replace(innerMatcher.group(0), newHref)
- changed = true
- violations << "Malformed inner class link in ${file.name}: ${innerMatcher.group(0)} -> ${newHref}"
- }
- }
-
- if (changed) {
- totalFixes++
- if (!auditMode) {
- file.text = content
+ violations << "Malformed inner class link in ${file.name}: ${innerMatcher.group(0)}"
}
}
}
}
- if (totalFixes > 0) {
- if (auditMode) {
- violations.take(10).each { logger.error(it) }
- if (violations.size() > 10) logger.error("... and ${violations.size() - 10} more")
- throw new org.gradle.api.GradleException("Found ${violations.size()} malformed links in Groovydoc. Please fix the source issue rather than patching. See logs for details.")
- } else {
- logger.lifecycle "Repaired ${totalFixes} HTML files in ${apiDir.absolutePath}"
- }
+ if (!violations.isEmpty()) {
+ violations.take(10).each { logger.error(it) }
+ if (violations.size() > 10) logger.error("... and ${violations.size() - 10} more")
+ throw new org.gradle.api.GradleException("Found ${violations.size()} malformed links in Groovydoc. Please fix the source issue rather than patching. See logs for details.")
} else {
logger.lifecycle "No malformed Groovydoc links found in ${apiDir.absolutePath}"
}
diff --git a/grails-doc/build.gradle b/grails-doc/build.gradle
index 0bb7904fbc..ddba680a44 100644
--- a/grails-doc/build.gradle
+++ b/grails-doc/build.gradle
@@ -21,7 +21,7 @@ import grails.doc.git.FetchTagsTask
import grails.doc.dropdown.CreateReleaseDropDownTask
import grails.doc.gradle.PublishGuideTask
import groovy.json.JsonSlurper
-import org.grails.doc.gradle.FixGroovydocLinksTask
+import org.grails.doc.gradle.AuditGroovydocLinksTask
import java.util.zip.ZipFile
@@ -126,10 +126,9 @@ combinedGroovydoc.configure { Groovydoc gdoc ->
gdoc.outputs.dir(gdoc.destinationDir)
}
-def fixGroovydocLinks = tasks.register('fixGroovydocLinks', FixGroovydocLinksTask) {
+def auditGroovydocLinks = tasks.register('auditGroovydocLinks', AuditGroovydocLinksTask) {
dependsOn combinedGroovydoc
apiDocsDir = combinedGroovydoc.get().destinationDir
- auditMode = project.hasProperty('auditGroovydocLinks')
}
String getVersion(String artifact) {
@@ -661,7 +660,7 @@ createReleaseDropdownTask.configure {
def docsTask = tasks.register('docs', Sync)
docsTask.configure { Sync it ->
- it.dependsOn(combinedGroovydoc, fixGroovydocLinks, createReleaseDropdownTask, ':grails-data-docs-stage:docs', ':grails-data-docs-stage:groovydoc')
+ it.dependsOn(combinedGroovydoc, auditGroovydocLinks, createReleaseDropdownTask, ':grails-data-docs-stage:docs', ':grails-data-docs-stage:groovydoc')
it.group = 'documentation'
def manualDocsDir = project.layout.buildDirectory.dir('modified-guide')