001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2026 the original author or authors.
004//
005// This library is free software; you can redistribute it and/or
006// modify it under the terms of the GNU Lesser General Public
007// License as published by the Free Software Foundation; either
008// version 2.1 of the License, or (at your option) any later version.
009//
010// This library is distributed in the hope that it will be useful,
011// but WITHOUT ANY WARRANTY; without even the implied warranty of
012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013// Lesser General Public License for more details.
014//
015// You should have received a copy of the GNU Lesser General Public
016// License along with this library; if not, write to the Free Software
017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
018///////////////////////////////////////////////////////////////////////////////////////////////
019
020package com.puppycrawl.tools.checkstyle.site;
021
022import java.nio.file.Path;
023import java.util.Locale;
024
025import org.apache.maven.doxia.macro.AbstractMacro;
026import org.apache.maven.doxia.macro.Macro;
027import org.apache.maven.doxia.macro.MacroExecutionException;
028import org.apache.maven.doxia.macro.MacroRequest;
029import org.apache.maven.doxia.module.xdoc.XdocSink;
030import org.apache.maven.doxia.sink.Sink;
031import org.codehaus.plexus.component.annotations.Component;
032
033/**
034 * A macro that inserts a link to the parent module.
035 */
036@Component(role = Macro.class, hint = "parent-module")
037public class ParentModuleMacro extends AbstractMacro {
038
039    /**
040     * Creates a new {@code ParentModuleMacro} instance.
041     */
042    public ParentModuleMacro() {
043        // no code by default
044    }
045
046    @Override
047    public void execute(Sink sink, MacroRequest request) throws MacroExecutionException {
048        // until https://github.com/checkstyle/checkstyle/issues/13426
049        if (!(sink instanceof XdocSink xdocSink)) {
050            throw new MacroExecutionException("Expected Sink to be an XdocSink.");
051        }
052        final String moduleName = (String) request.getParameter("moduleName");
053        final Object instance = SiteUtil.getModuleInstance(moduleName);
054        final Class<?> clss = instance.getClass();
055        createParentModuleParagraph(xdocSink, clss, moduleName);
056    }
057
058    /**
059     * Creates a paragraph with a link to the parent module.
060     *
061     * @param sink the sink to write to.
062     * @param clss the class of the module.
063     * @param moduleName the module name.
064     * @throws MacroExecutionException if the parent module cannot be found.
065     */
066    private static void createParentModuleParagraph(XdocSink sink, Class<?> clss, String moduleName)
067            throws MacroExecutionException {
068        final String parentModule = SiteUtil.getParentModule(clss);
069        final String linkToParentModule = getLinkToParentModule(parentModule, moduleName);
070
071        sink.setInsertNewline(false);
072        sink.paragraph();
073        sink.setInsertNewline(true);
074        sink.rawText(ModuleJavadocParsingUtil.INDENT_LEVEL_10);
075        sink.link(linkToParentModule);
076        sink.text(parentModule);
077        sink.link_();
078        sink.rawText(ModuleJavadocParsingUtil.INDENT_LEVEL_8);
079        sink.paragraph_();
080    }
081
082    /**
083     * Returns relative link to the parent module for the given module class.
084     *
085     * @param parentModule parent module name.
086     * @param moduleName the module name we are looking for the parent of.
087     * @return relative link to the parent module.
088     * @throws MacroExecutionException if link to the parent module cannot be constructed.
089     */
090    private static String getLinkToParentModule(String parentModule, String moduleName)
091            throws MacroExecutionException {
092        final Path templatePath = SiteUtil.getTemplatePath(moduleName);
093        if (templatePath == null) {
094            throw new MacroExecutionException(
095                    String.format(Locale.ROOT, "Could not find template for %s", moduleName));
096        }
097        final Path templatePathParent = templatePath.getParent();
098        if (templatePathParent == null) {
099            throw new MacroExecutionException("Failed to get parent path for " + templatePath);
100        }
101        return templatePathParent
102                .relativize(Path.of("src", "site/xdoc", "config.xml"))
103                .toString()
104                .replace(".xml", ".html")
105                .replace('\\', '/')
106                + "#" + parentModule;
107    }
108
109}