Merge branch 'master' into pr-4857

This commit is contained in:
Andreas Dangel
2024-03-14 20:24:31 +01:00
1843 changed files with 12965 additions and 16456 deletions

View File

@ -7361,6 +7361,24 @@
"bug",
"code"
]
},
{
"login": "enexusde",
"name": "Peter Rader",
"avatar_url": "https://avatars.githubusercontent.com/u/6880636?v=4",
"profile": "http://www.e-nexus.de./",
"contributions": [
"bug"
]
},
{
"login": "liqingjun123",
"name": "liqingjun123",
"avatar_url": "https://avatars.githubusercontent.com/u/12873992?v=4",
"profile": "https://github.com/liqingjun123",
"contributions": [
"bug"
]
}
],
"contributorsPerLine": 7,

View File

@ -66,6 +66,8 @@ function build() {
# was green before. This is usually checked via a local build, see ./do-release.sh
if pmd_ci_maven_isReleaseBuild; then
PMD_MAVEN_EXTRA_OPTS+=(-DskipTests=true)
# note: skipping pmd in order to avoid failures due to #4757
PMD_MAVEN_EXTRA_OPTS+=(-Dpmd.skip=true -Dcpd.skip=true)
fi
if [ "$(pmd_ci_utils_get_os)" != "linux" ]; then
@ -136,13 +138,9 @@ function build() {
pmd_ci_openjdk_setdefault 17
# Note: Sonar also needs GITHUB_TOKEN (!)
./mvnw \
-Dmaven.javadoc.skip=true \
-Dmaven.source.skip \
-Dcheckstyle.skip \
-Dpmd.skip \
--show-version --errors --batch-mode \
clean package \
sonar:sonar -Dsonar.login="${SONAR_TOKEN}" -Psonar
sonar:sonar -Dsonar.token="${SONAR_TOKEN}" -Psonar,fastSkip
pmd_ci_log_success "New sonar results: https://sonarcloud.io/dashboard?id=net.sourceforge.pmd%3Apmd"
pmd_ci_log_group_end
@ -151,15 +149,22 @@ function build() {
export CI_NAME="github actions"
export CI_BUILD_URL="${PMD_CI_JOB_URL}"
export CI_BRANCH="${PMD_CI_BRANCH}"
# first create jacoco report
./mvnw \
-Dmaven.javadoc.skip=true \
-Dmaven.source.skip \
-Dcheckstyle.skip \
-Dpmd.skip \
-DrepoToken="${COVERALLS_REPO_TOKEN}" \
--show-version --errors --batch-mode \
clean package jacoco:report \
coveralls:report -Pcoveralls
clean package \
jacoco:report -Pcoveralls,fastSkip
# workaround, maybe https://github.com/jacoco/jacoco/issues/654
sed -i 's$Comparisons.kt$ApexTreeBuilder.kt$g' pmd-apex/target/site/jacoco/jacoco.xml
# then create and send coveralls report
# note: generate-sources is needed, so that antlr4 generated directories are on the compileSourceRoots
./mvnw \
--show-version --errors --batch-mode \
generate-sources \
coveralls:report -DrepoToken="${COVERALLS_REPO_TOKEN}" -Pcoveralls,fastSkip
pmd_ci_log_success "New coveralls result: https://coveralls.io/github/pmd/pmd"
pmd_ci_log_group_end
fi
@ -211,8 +216,6 @@ function pmd_ci_deploy_build_artifacts() {
pmd_ci_sourceforge_uploadFile "pmd/${PMD_CI_MAVEN_PROJECT_VERSION}" "pmd-dist/target/pmd-dist-${PMD_CI_MAVEN_PROJECT_VERSION}-bin.zip"
pmd_ci_sourceforge_uploadFile "pmd/${PMD_CI_MAVEN_PROJECT_VERSION}" "pmd-dist/target/pmd-dist-${PMD_CI_MAVEN_PROJECT_VERSION}-src.zip"
# Deploy SBOM
cp pmd-dist/target/bom.xml "pmd-dist/target/pmd-${PMD_CI_MAVEN_PROJECT_VERSION}-cyclonedx.xml"
cp pmd-dist/target/bom.json "pmd-dist/target/pmd-${PMD_CI_MAVEN_PROJECT_VERSION}-cyclonedx.json"
pmd_ci_sourceforge_uploadFile "pmd/${PMD_CI_MAVEN_PROJECT_VERSION}" "pmd-dist/target/pmd-${PMD_CI_MAVEN_PROJECT_VERSION}-cyclonedx.xml"
pmd_ci_sourceforge_uploadFile "pmd/${PMD_CI_MAVEN_PROJECT_VERSION}" "pmd-dist/target/pmd-${PMD_CI_MAVEN_PROJECT_VERSION}-cyclonedx.json"
fi
@ -230,8 +233,6 @@ function pmd_ci_deploy_build_artifacts() {
pmd_ci_sourceforge_uploadFile "pmd/${PMD_CI_MAVEN_PROJECT_VERSION}" "pmd-dist/target/pmd-dist-${PMD_CI_MAVEN_PROJECT_VERSION}-bin.zip"
pmd_ci_sourceforge_uploadFile "pmd/${PMD_CI_MAVEN_PROJECT_VERSION}" "pmd-dist/target/pmd-dist-${PMD_CI_MAVEN_PROJECT_VERSION}-src.zip"
# Deploy SBOM
cp pmd-dist/target/bom.xml "pmd-dist/target/pmd-${PMD_CI_MAVEN_PROJECT_VERSION}-cyclonedx.xml"
cp pmd-dist/target/bom.json "pmd-dist/target/pmd-${PMD_CI_MAVEN_PROJECT_VERSION}-cyclonedx.json"
pmd_ci_sourceforge_uploadFile "pmd/${PMD_CI_MAVEN_PROJECT_VERSION}" "pmd-dist/target/pmd-${PMD_CI_MAVEN_PROJECT_VERSION}-cyclonedx.xml"
pmd_ci_sourceforge_uploadFile "pmd/${PMD_CI_MAVEN_PROJECT_VERSION}" "pmd-dist/target/pmd-${PMD_CI_MAVEN_PROJECT_VERSION}-cyclonedx.json"

View File

@ -14,5 +14,5 @@
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.4/apache-maven-3.9.4-bin.zip
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip
wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.1.0/maven-wrapper-3.1.0.jar

View File

@ -39,7 +39,7 @@ See also [Getting Started](https://docs.pmd-code.org/latest/pmd_userdocs_install
**Demo:**
This shows how PMD can detect for loops, that can be replaced by for-each loops.
This shows how PMD analyses [openjdk](https://github.com/openjdk/jdk):
![Demo](docs/images/userdocs/pmd-demo.gif)

View File

@ -6,7 +6,7 @@
<!-- Input properties:
- lang-name: matches the grammar name (eg "Swift")
- lang-terse-name: uncapitalized package name (eg "swift")
- lang-id: the language id, used in the conventional package name (eg "swift")
- node-prefix: prefix for generated AST nodes (eg "Sw")
- root-node-name: name of the root node without prefix (eg "TopLevel"), will be made to implement RootNode
@ -14,10 +14,10 @@
-->
<property name="target-package-dir" value="${antlr4.outputDirectory}/net/sourceforge/pmd/lang/${lang-terse-name}/ast"/>
<property name="target-package-dir" value="${antlr4.outputDirectory}/net/sourceforge/pmd/lang/${lang-id}/ast"/>
<property name="lang-ast-package" value="net.sourceforge.pmd.lang.${lang-terse-name}.ast" />
<property name="lang-ast-package" value="net.sourceforge.pmd.lang.${lang-id}.ast" />
<property name="ast-api-package" value="net.sourceforge.pmd.lang.ast" />
<property name="ast-impl-package" value="${ast-api-package}.impl.antlr4" />
@ -64,6 +64,8 @@
<include name="${listener-name}.java"/>
<include name="${base-listener-name}.java"/>
<replacefilter token="${lang-name}." value="${parser-name}."/>
<replacefilter token="${lang-name}#" value="${parser-name}#"/>
<replacefilter token="{@link ${lang-name}}" value="{@link ${parser-name}}"/>
</replace>
<move file="${target-package-dir}/${lang-name}.java"
@ -115,6 +117,8 @@
<!-- Transform the visitor to PMD-style. -->
<replace file="${visitor-file}">
<replacefilter token="@param &lt;T> The return type of the visit operation. Use {@link Void} for"
value="@param &lt;P> The parameter type of the visit&#10; * @param &lt;R> The return type of the visit operation. Use {@link Void} for"/>
<replacefilter token="Visitor&lt;T> extends ParseTreeVisitor&lt;T> {"
value="Visitor&lt;P, R> extends net.sourceforge.pmd.lang.ast.AstVisitor&lt;P, R> {&#10;
&#10;
@ -133,6 +137,7 @@
<replacefilter token="T visit" value="default R visit"/>
<replacefilter token="ctx);" value="node, P data) { return visit${node-itf-name}(node, data); }"/>
<replacefilter token="@param ctx the parse tree" value="@param node Node to visit&#10;&#9; * @param data Parameter of the visit"/>
</replace>

View File

@ -117,9 +117,6 @@ echo
echo "* Update **pmd-apex/src/main/resources/rulesets/apex/quickstart.xml** and"
echo " **pmd-java/src/main/resources/rulesets/java/quickstart.xml** with the new rules."
echo
echo "* Update **docs/pages/next_major_development.md** with the API changes for"
echo " the new release based on the release notes. Also add any deprecated rules to the list."
echo
echo "* Update **../pmd.github.io/_config.yml** to mention the new release"
echo
echo "* Update property \`pmd-designer.version\` in **pom.xml** to reference the version, that will be released"
@ -194,7 +191,8 @@ echo "Change version in the POMs to ${RELEASE_VERSION} and update build timestam
echo "Transform the SCM information in the POM"
sed -i "s|<tag>.\+</tag>|<tag>pmd_releases/${RELEASE_VERSION}</tag>|" pom.xml
echo "Run the project tests against the changed POMs to confirm everything is in running order (skipping cli and dist)"
./mvnw clean verify -Dskip-cli-dist -Pgenerate-rule-docs
# note: skipping pmd in order to avoid failures due to #4757
./mvnw clean verify -Dskip-cli-dist -Dpmd.skip=true -Dcpd.skip=true -Pgenerate-rule-docs
echo "Commit and create tag"
git commit -a -m "[release] prepare release pmd_releases/${RELEASE_VERSION}"
git tag -m "[release] copy for tag pmd_releases/${RELEASE_VERSION}" "pmd_releases/${RELEASE_VERSION}"
@ -281,7 +279,7 @@ echo "Then proceed with releasing pmd-designer..."
echo "<https://github.com/pmd/pmd-designer/blob/master/releasing.md>"
echo
echo "Press enter to continue when pmd-designer is available in maven-central..."
echo "<https://repo.maven.apache.org/maven2/net/sourceforge/pmd/pmd-ui/maven-metadata.xml>."
echo "<https://repo.maven.apache.org/maven2/net/sourceforge/pmd/pmd-designer/maven-metadata.xml>."
echo
echo "Note: If there is no new pmd-designer release needed, you can directly proceed."
read -r

View File

@ -70,6 +70,7 @@ kramdown:
syntax_highlighter: rouge
syntax_highlighter_opts:
css_class: 'highlight'
parse_block_html: true
# filter used to process markdown. note that kramdown differs from github-flavored markdown in some subtle ways
collections:

View File

@ -324,10 +324,10 @@ entries:
subfolderitems:
- title: Index
output: web, pdf
url: /pmd_rules_vf.html
url: /pmd_rules_visualforce.html
- title: Security
output: web, pdf
url: /pmd_rules_vf_security.html
url: /pmd_rules_visualforce_security.html
- title: null
output: web, pdf
subfolders:
@ -360,16 +360,16 @@ entries:
subfolderitems:
- title: Index
output: web, pdf
url: /pmd_rules_vm.html
url: /pmd_rules_velocity.html
- title: Best Practices
output: web, pdf
url: /pmd_rules_vm_bestpractices.html
url: /pmd_rules_velocity_bestpractices.html
- title: Design
output: web, pdf
url: /pmd_rules_vm_design.html
url: /pmd_rules_velocity_design.html
- title: Error Prone
output: web, pdf
url: /pmd_rules_vm_errorprone.html
url: /pmd_rules_velocity_errorprone.html
- title: null
output: web, pdf
subfolders:
@ -502,7 +502,7 @@ entries:
url: /pmd_languages_visualforce.html
output: web, pdf
- title: Velocity Template Language (VTL)
url: /pmd_languages_vm.html
url: /pmd_languages_velocity.html
output: web, pdf
- title: XML and XML dialects
url: /pmd_languages_xml.html

View File

@ -104,7 +104,7 @@ class JDocNamespaceDeclaration < Liquid::Tag
'javascript', 'jsp', 'julia',
'kotlin', 'lang-test', 'lua', 'matlab', 'objectivec', 'perl', 'php', 'plsql', 'python', 'ruby', 'scala', 'swift',
'test', 'test-schema', 'tsql', 'ui',
'modelica', 'visualforce', 'vm', 'xml'].flat_map {|m| [m, "pmd-" + m]}
'modelica', 'visualforce', 'velocity', 'xml'].flat_map {|m| [m, "pmd-" + m]}
def self.make_base_namespaces
res = {}

View File

@ -18,7 +18,7 @@ class TocMakerBlock < Liquid::Block
end
def to_internal_link(header)
url = header.downcase.gsub(/\s+/, "-")
url = header.downcase.gsub(/\s+/, "-").gsub(/[:\(\)]+/, "")
"[#{header}](##{url})"
end

View File

@ -0,0 +1,31 @@
## How to create pmd-demo.gif
### Prepare
```shell
mkdir $HOME/pmd-demo
cd $HOME/pmd-demo
curl -L -o jdk-master.zip https://github.com/openjdk/jdk/archive/refs/heads/master.zip
unzip jdk-master.zip
alias pmd=$HOME/PMD/source/pmd/pmd-dist/target/pmd-bin-7.0.0-SNAPSHOT/bin/pmd
clear
pmd --version
pmd check -R rulesets/java/quickstart.xml -d jdk-master/src/java.base -f text --cache pmd.cache --report-file jdk-report.txt
```
Second terminal window: `cd $HOME/pmd-demo; tail -f jdk-report.txt`
### Recording
Record screencast with https://github.com/EasyScreenCast/EasyScreenCast (a gnome3 extension)
The recorded screencast can be found in `$HOME/Videos`.
### Converting
Convert webm to gif: https://engineering.giphy.com/how-to-make-gifs-with-ffmpeg/
```shell
cd $HOME/Videos
ffmpeg -i pmd7-demo.webm -filter_complex "[0:v] fps=12,scale=960:-1,split [a][b];[a] palettegen [p];[b][p] paletteuse" pmd7-demo.gif
```

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.1 MiB

After

Width:  |  Height:  |  Size: 3.0 MiB

View File

@ -119,7 +119,7 @@ against a previously recorded version. If there are differences, the test fails.
This helps to detect anything in the AST structure that changed, maybe unexpectedly.
* Create a test class in the package `net.sourceforge.pmd.lang.$lang.ast` with the name `$langTreeDumpTest`.
* This test class must extend `net.sourceforge.pmd.lang.ast.test.BaseTreeDumpTest`. Note: This class
* This test class must extend `net.sourceforge.pmd.lang.test.ast.BaseTreeDumpTest`. Note: This class
is written in kotlin and is available in the module "lang-test".
* Add a default constructor, that calls the super constructor like so:
@ -131,7 +131,7 @@ This helps to detect anything in the AST structure that changed, maybe unexpecte
Replace "$lang" and "$extension" accordingly.
* Implement the method `getParser()`. It must return a
subclass of `net.sourceforge.pmd.lang.ast.test.BaseParsingHelper`. See
subclass of `net.sourceforge.pmd.lang.test.ast.BaseParsingHelper`. See
`net.sourceforge.pmd.lang.ecmascript.ast.JsParsingHelper` for an example.
With this parser helper you can also specify, where the test files are searched, by using
the method `withResourceContext(Class<?>, String)`.
@ -252,7 +252,7 @@ This can be achieved with Rule Designer:
* Fork and clone the [pmd/pmd-designer](https://github.com/pmd/pmd-designer) repository.
* Add a syntax highlighter implementation to `net.sourceforge.pmd.util.fxdesigner.util.codearea.syntaxhighlighting` (you could use Java as an example).
* Register it in the `AvailableSyntaxHighlighters` enumeration.
* Now build your implementation and place the `target/pmd-ui-<version>-SNAPSHOT.jar` to the `lib` directory inside your `pmd-bin-...` distribution (you have to delete old `pmd-ui-*.jar` from there).
* Now build your implementation and place the `target/pmd-designer-<version>-SNAPSHOT.jar` to the `lib` directory inside your `pmd-bin-...` distribution (you have to delete old `pmd-designer-*.jar` from there).
## Optional features

View File

@ -75,7 +75,7 @@ If your language only supports CPD, then you can subclass {% jdoc core::lang.imp
At this point the new language module should be available in {% jdoc core::lang.LanguageRegistry#CPD %} and usable by CPD like any other language.
4. Update the test that asserts the list of supported languages by updating the `SUPPORTED_LANGUAGES` constant in [BinaryDistributionIT](https://github.com/pmd/pmd/blob/master/pmd-dist/src/test/java/net/sourceforge/pmd/it/BinaryDistributionIT.java).
4. Update the test that asserts the list of supported languages by updating the `SUPPORTED_LANGUAGES` constant in [BinaryDistributionIT](https://github.com/pmd/pmd/blob/master/pmd-dist/src/test/java/net/sourceforge/pmd/dist/BinaryDistributionIT.java).
5. Add some tests for your CpdLexer by following the [section below](#testing-your-implementation).

View File

@ -33,8 +33,10 @@ See [Apex language properties](pmd_languages_configuration.html#apex-language-pr
## Parser
We use Jorje, the Apex parsers that is shipped within the Apex Language Server. This is part of
the [Salesforce Extensions for VS Code](https://github.com/forcedotcom/salesforcedx-vscode).
Since PMD 7.0.0 we use the open source [apex-parser](https://github.com/apex-dev-tools/apex-parser),
together with [Summit AST](https://github.com/google/summit-ast) which translates the ANTLR parse tree
into an AST.
We take the binary from <https://github.com/forcedotcom/salesforcedx-vscode/tree/develop/packages/salesforcedx-vscode-apex/out>
and provide it as a maven dependency (see [pmd-apex-jorje](https://github.com/pmd/pmd/tree/master/pmd-apex-jorje)).
When PMD added Apex support with version 5.5.0, it utilized the Apex Jorje library to parse Apex source
and generate an AST. This library is however a binary-blob provided as part of the
[Salesforce Extensions for VS Code](https://github.com/forcedotcom/salesforcedx-vscode), and it is closed-source.

View File

@ -1,15 +1,13 @@
---
title: HTML support
permalink: pmd_languages_html.html
last_updated: September 2023 (7.0.0)
tags: [languages, PmdCapableLanguage, CpdCapableLanguage, experimental]
last_updated: February 2024 (7.0.0)
tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
summary: "HTML-specific features and guidance"
---
{% include language_info.html name='HTML' id='html' implementation='html::lang.html.HtmlLanguageModule' supports_pmd=true supports_cpd=true since='6.45.0' %}
{% include warning.html content="This language module is experimental and may change any time." %}
The HTML language module uses [jsoup](https://jsoup.org/) for parsing.
XPath rules are supported, but the DOM is not always a typical XML/XPath DOM.

View File

@ -15,9 +15,10 @@ Usually the latest non-preview Java Version is the default version.
| Java Version | Alias | Supported by PMD since |
|--------------|-------|------------------------|
| 22-preview | | 7.0.0 |
| 22 (default) | | 7.0.0 |
| 21-preview | | 7.0.0 |
| 21 (default) | | 7.0.0 |
| 20-preview | | 6.55.0 |
| 21 | | 7.0.0 |
| 20 | | 6.55.0 |
| 19 | | 6.48.0 |
| 18 | | 6.44.0 |
@ -40,10 +41,10 @@ Usually the latest non-preview Java Version is the default version.
## Using Java preview features
In order to analyze a project with PMD that uses preview language features, you'll need to enable
it via the environment variable `PMD_JAVA_OPTS` and select the new language version, e.g. `21-preview`:
it via the environment variable `PMD_JAVA_OPTS` and select the new language version, e.g. `22-preview`:
export PMD_JAVA_OPTS=--enable-preview
pmd check --use-version java-21-preview ...
pmd check --use-version java-22-preview ...
Note: we only support preview language features for the latest two java versions.
@ -80,7 +81,8 @@ in order to resolve Java API references.
The auxiliary classpath (or short "auxClasspath") is configured via the
[Language Property "auxClasspath"](pmd_languages_configuration.html#java-language-properties).
It is a string containing multiple paths separated by either a colon (`:`) under Linux/MacOS
or a semicolon (`;`) under Windows.
or a semicolon (`;`) under Windows. This property can be provided on the CLI with parameter
[`--aux-classpath`](pmd_userdocs_cli_reference.html#-aux-classpath).
In order to resolve the types of the Java API correctly, the Java Runtime must be on the
auxClasspath as well. As the Java API and Runtime evolves from version to version, it is important
@ -99,10 +101,27 @@ needs to be added to the auxClasspath as the first entry. PMD will make sure, to
using the jrt-filesystem.
If neither `${JAVA_HOME}/jre/lib/rt.jar` nor `${JAVA_HOME}/lib/jrt-fs.jar` is added to the auxClasspath, PMD falls
back to load the JAva runtime classes **from the current runtime**, that is the runtime that was used to
back to load the Java runtime classes **from the current runtime**, that is the runtime that was used to
execute PMD. This might not be the correct version, e.g. you might run PMD with Java 8, but analyze code
written for Java 21. In that case, you have to provide "jrt-fs.jar" on the auxClasspath.
Not providing the correct auxClasspath might result in false positives or negatives for some rules,
such as {% rule java/bestpractices/MissingOverride %}.
This rule needs to figure out, whether a method is defined already in the super class or interface. E.g. the method
[Collection#toArray(IntFunction)](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Collection.html#toArray(java.util.function.IntFunction))
has been added in Java 11, and it does not exist yet in Java 8. Given a simple subclass of ArrayList, that overrides
this method without adding `@Override`, then PMD won't be able to detect this missing override annotation, if
it is executed with a Java 8 runtime but without the correct auxClasspath. Providing the correct `jrt-fs.jar` from
Java 11 (or later) for the auxClasspath allows PMD to correctly identify the missing annotation.
Example command line:
```
pmd check -d src/main/java \
--aux-classpath=path/to/java17/lib/jrt-fs.jar:target/classes/ \
-f xml -r pmd-report.xml -R rulesets/java/quickstart.xml
```
## Symbol table APIs
{% jdoc_nspace :ast java::lang.java.ast %}

View File

@ -1,17 +1,13 @@
---
title: Kotlin Support
permalink: pmd_languages_kotlin.html
last_updated: September 2023 (7.0.0)
tags: [languages, PmdCapableLanguage, CpdCapableLanguage, experimental]
last_updated: February 2024 (7.0.0)
tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
summary: "Kotlin-specific features and guidance"
---
[Kotlin](https://kotlinlang.org/) support in PMD is based on the official grammar from <https://github.com/Kotlin/kotlin-spec>.
{% include language_info.html name='Kotlin' id='kotlin' implementation='kotlin::lang.kotlin.JspLanguageModule' supports_pmd=true supports_cpd=true %}
{% include language_info.html name='Kotlin' id='kotlin' implementation='kotlin::lang.kotlin.JspLanguageModule' supports_pmd=true supports_cpd=true since=7.0.0 %}
Java-based rules and XPath-based rules are supported.
{% include note.html content="Kotlin support has **experimental** stability level, meaning no compatibility should
be expected between even incremental releases. Any functionality can be added, removed or changed without
warning." %}

View File

@ -2,7 +2,7 @@
title: Language configuration
permalink: pmd_languages_configuration.html
author: Clément Fournier
last_updated: August 2023 (7.0.0)
last_updated: February 2024 (7.0.0)
tags: [languages]
keywords: [pmd, cpd, options, command, auxclasspath, language, properties]
summary: "Summary of language configuration options and properties"
@ -114,13 +114,13 @@ The Java language can be configured with the following properties:
or relative to the Visualforce directory. Default is `../classes`. Specifying an
empty string will disable data type resolution for Apex Controller properties.
Environment variable: `PMD_VF_APEX_DIRECTORIES`
Environment variable: `PMD_VISUALFORCE_APEX_DIRECTORIES`
- `objectsDirectories`: Comma separated list of directories for Custom Objects.
Absolute or relative to the Visualforce directory. Default is `../objects`.
Specifying an empty string will disable data type resolution for Custom Object fields.
Environment variable: `PMD_VF_OBJECTS_DIRECTORIES`
Environment variable: `PMD_VISUALFORCE_OBJECTS_DIRECTORIES`
## CPP language properties

View File

@ -0,0 +1,18 @@
---
title: Velocity Template Language (VTL) support
permalink: pmd_languages_velocity.html
last_updated: February 2024 (7.0.0)
tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
summary: "VTL-specific features and guidance"
---
> [Velocity](https://velocity.apache.org/engine/devel/vtl-reference.html) is a Java-based template engine.
> It permits web page designers to reference methods defined in Java code.
{% include language_info.html name='Velocity Template Language (VTL)' id='velocity' implementation='velocity::lang.velocity.VmLanguageModule' supports_pmd=true supports_cpd=true since='5.1.0' %}
{% capture id_change_note %}
The language id of the Velocity module was in PMD 6 just "vm". In PMD 7, this has been changed to "velocity". Also the
package name of the classes has been changed from vm to "velocity".
{% endcapture %}
{% include note.html content=id_change_note %}

View File

@ -1,8 +1,8 @@
---
title: Visualforce Support
permalink: pmd_languages_visualforce.html
last_updated: September 2023
tags: [languages, PmdCapableLanguage, CpdCapableLanguage, experimental]
last_updated: February 2024 (7.0.0)
tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
author: Andreas Dangel
summary: "Visualforce-specific features and guidance"
---
@ -10,7 +10,13 @@ summary: "Visualforce-specific features and guidance"
> [Visualforce](https://developer.salesforce.com/docs/atlas.en-us.pages.meta/pages/) consists of a tag-based markup
> language that gives developers way to build applications and customize the Salesforce user interface.
{% include language_info.html name='Salesforce Visualforce' id='vf' implementation='visualforce::lang.vf.VfLanguageModule' supports_pmd=true supports_cpd=true since='5.6.0' %}
{% include language_info.html name='Salesforce Visualforce' id='visualforce' implementation='visualforce::lang.visualforce.VfLanguageModule' supports_pmd=true supports_cpd=true since='5.6.0' %}
{% capture vf_id_note %}
The language id of Visualforce was in PMD 6 just "vf". In PMD 7, this has been changed to "visualforce". Also the
package name of the classes has been changed from vf to "visualforce".
{% endcapture %}
{% include note.html content=vf_id_note %}
## Language Properties
@ -22,40 +28,37 @@ Since PMD 6.30.0 support for type resolution has been added.
The Visualforce AST now can resolve the data type of Visualforce expressions that reference
Apex Controller properties and Custom Object fields. This feature improves the precision of existing rules,
like {% rule vf/security/VfUnescapeEl %}.
like {% rule visualforce/security/VfUnescapeEl %}.
This can be configured using two language properties, which can be set as environment variables:
* `PMD_VF_APEX_DIRECTORIES`: Comma separated list of directories for Apex classes. Absolute or relative
* `PMD_VISUALFORCE_APEX_DIRECTORIES`: Comma separated list of directories for Apex classes. Absolute or relative
to the Visualforce directory. Default is `../classes`. Specifying an empty string will disable data type
resolution for Apex Controller properties.
* `PMD_VF_OBJECTS_DIRECTORIES`: Comma separated list of directories for Custom Objects. Absolute or relative
* `PMD_VISUALFORCE_OBJECTS_DIRECTORIES`: Comma separated list of directories for Custom Objects. Absolute or relative
to the Visualforce directory. Default is `../objects`. Specifying an empty string will disable data type
resolution for Custom Object fields.
{% include warning.html content="
These env vars have changed from PMD 6 to PMD 7:
* `PMD_VF_APEXDIRECTORIES` ➡️ `PMD_VF_APEX_DIRECTORIES`
* `PMD_VF_OBJECTSDIRECTORIES` ➡️ `PMD_VF_OBJECTS_DIRECTORIES`
* `PMD_VF_APEXDIRECTORIES` ➡️ `PMD_VISUALFORCE_APEX_DIRECTORIES`
* `PMD_VF_OBJECTSDIRECTORIES` ➡️ `PMD_VISUALFORCE_OBJECTS_DIRECTORIES`
"%}
This feature is experimental, in particular, expect changes to the way the configuration is specified.
We'll probably extend the CLI instead of relying on environment variables in a future version.
### Sample usage
```
PMD_VF_APEXDIRECTORIES=../classes \
PMD_VF_OBJECTSDIRECTORIES=../objects \
PMD_VISUALFORCE_APEXDIRECTORIES=../classes \
PMD_VISUALFORCE_OBJECTSDIRECTORIES=../objects \
pmd check -d $GITHUB_WORKSPACE/force-app/main/default/pages \
-R category/vf/security.xml/VfUnescapeEl -f text
-R category/visualforce/security.xml/VfUnescapeEl -f text
```
If you run with debug logging turned on, you might see log messages like this:
```
Okt. 14, 2021 11:30:44 AM net.sourceforge.pmd.lang.vf.VfExpressionTypeVisitor visit
Okt. 14, 2021 11:30:44 AM net.sourceforge.pmd.lang.visualforce.VfExpressionTypeVisitor visit
FINE: Unable to determine type for: Account.NotFoundField__c
```

View File

@ -1,12 +0,0 @@
---
title: Velocity Template Language (VTL) support
permalink: pmd_languages_vm.html
last_updated: September 2023 (7.0.0)
tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
summary: "VTL-specific features and guidance"
---
> [Velocity](https://velocity.apache.org/engine/devel/vtl-reference.html) is a Java-based template engine.
> It permits web page designers to reference methods defined in Java code.
{% include language_info.html name='Velocity Template Language (VTL)' id='vm' implementation='vm::lang.vm.VmLanguageModule' supports_pmd=true supports_cpd=true since='5.1.0' %}

File diff suppressed because it is too large Load Diff

View File

@ -63,7 +63,7 @@ However, this also adds additional tasks, and it takes time to write down and do
## Change History
2022-09-30: Status changed to "Accepted".
2022-09-30: Status changed to "Accepted". ([#4072](https://github.com/pmd/pmd/pull/4072))
2022-09-06: Added section "Change History" to the template. Added "Last updated" to "Status" section.

View File

@ -66,6 +66,6 @@ Maintaining a polyglot code base with multiple languages is likely to be more ch
## Change History
2022-09-30: Changed status to "Accepted".
2022-09-30: Changed status to "Accepted". ([#4072](https://github.com/pmd/pmd/pull/4072))
2022-07-28: Proposed initial version.

View File

@ -5,8 +5,8 @@ permalink: pmd_projectdocs_decisions_adr_3.html
sidebaractiveurl: /pmd_projectdocs_decisions.html
adr: true
# Proposed / Accepted / Deprecated / Superseded
adr_status: "Proposed"
last_updated: December 2023
adr_status: "Accepted"
last_updated: February 2024
---
<!-- https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md -->
@ -184,4 +184,6 @@ Non-concrete AST classes (like base classes or common interfaces) should follow
## Change History
2024-02-01: Changed status to "Accepted". ([#4756](https://github.com/pmd/pmd/pull/4756))
2023-12-01: Proposed initial version.

View File

@ -54,7 +54,9 @@ The tool comes with a rather extensive help text, simply running with `--help`!
This is used to resolve types in source files. The platform specific path delimiter
(\":\" on Linux, \";\" on Windows) is used to separate the entries.
Alternatively, a single `file:` URL
to a text file containing path elements on consecutive lines can be specified."
to a text file containing path elements on consecutive lines can be specified.
<p>See also [Providing the auxiliary classpath](pmd_languages_java.html#providing-the-auxiliary-classpath).</p>"
languages="Java"
%}
{% include custom/cli_option_row.html options="--benchmark,-b"
@ -263,8 +265,8 @@ Example:
* [pom](pmd_rules_pom.html) (Maven POM)
* [scala](pmd_rules_scala.html)
* [swift](pmd_rules_swift.html)
* [vf](pmd_rules_vf.html) (Salesforce VisualForce)
* [vm](pmd_rules_vm.html) (Apache Velocity)
* [velocity](pmd_rules_velocity.html) (Apache Velocity Template Language)
* [visualforce](pmd_rules_visualforce.html) (Salesforce VisualForce)
* [xml](pmd_rules_xml.html)
* [xsl](pmd_rules_xsl.html)

View File

@ -4,7 +4,7 @@ short_title: Configuring rules
keywords: [property, properties, message, priority]
tags: [userdocs, getting_started]
summary: "Learn how to configure your rules directly from the ruleset XML."
last_updated: May 2023 (7.0.0)
last_updated: February 2024 (7.0.0)
permalink: pmd_userdocs_configuring_rules.html
author: Hooper Bloob <hooperbloob@users.sourceforge.net>, Romain Pelisse <rpelisse@users.sourceforge.net>, Clément Fournier <clement.fournier76@gmail.com>
---
@ -43,7 +43,10 @@ will cause the rule to be ignored.
## Rule properties
Properties make it easy to customise the behaviour of a rule directly from the xml. They come in several types, which correspond to the type of their values. For example, NPathComplexity declares a property "reportLevel", with an integer value type, and which corresponds to the threshold above which a method will be reported. If you believe that its default value of 200 is too high, you could lower it to e.g. 150 in the following way:
Properties make it easy to customise the behaviour of a rule directly from the xml. They come in several types,
which correspond to the type of their values. For example, NPathComplexity declares a property "reportLevel",
with an integer value type, and which corresponds to the threshold above which a method will be reported.
If you believe that its default value of 200 is too high, you could lower it to e.g. 150 in the following way:
```xml
<rule ref="category/java/design.xml/NPathComplexity">
@ -55,7 +58,9 @@ Properties make it easy to customise the behaviour of a rule directly from the x
</rule>
```
Properties are assigned a value with a `property` element, which should mention the name of a property as an attribute. The value of the property can be specified either in the content of the element, like above, or in the `value` attribute, e.g.
Properties are assigned a value with a `property` element, which should mention the name of a property as an
attribute. The value of the property can be specified either in the content of the element, like above, or
in the `value` attribute, e.g.
```xml
<property name="reportLevel" value="150"/>
@ -63,12 +68,17 @@ Properties are assigned a value with a `property` element, which should mention
All property assignments must be enclosed in a `properties` element, which is itself inside a `rule` element.
{%include tip.html content="The properties of a rule are documented with the rule, e.g. [here](pmd_rules_java_design.html#npathcomplexity) for NPathComplexity. Note that **assigning a value to a property that does not exist throws an error!**" %}
{% capture tip_content %}
The properties of a rule are documented with the rule, e.g. [here](pmd_rules_java_design.html#npathcomplexity)
for NPathComplexity. Note that **assigning a value to a property that does not exist throws an error!**
{% endcapture %}
{%include tip.html content=tip_content %}
Some properties take multiple values (a list), in which case you can provide them all by delimiting them with a delimiter character. It is usually a pipe ('\|'), or a comma (',') for numeric properties, e.g.
Some properties take multiple values (a list), in which case you can provide them all by delimiting them with
a comma (','), e.g.
```xml
<property name="legalCollectionTypes"
value="java.util.ArrayList|java.util.Vector|java.util.HashMap"/>
value="java.util.ArrayList,java.util.Vector,java.util.HashMap"/>
```
These properties are referred to as **multivalued properties** in this documentation.

View File

@ -3,7 +3,7 @@ title: The rule designer
short_title: Rule designer
tags: [extending, userdocs]
summary: "Learn about the usage and features of the rule designer."
last_updated: December 2023 (7.0.0)
last_updated: March 2024 (7.0.0)
permalink: pmd_userdocs_extending_designer_reference.html
author: Clément Fournier <clement.fournier76@gmail.com>
---
@ -13,11 +13,35 @@ author: Clément Fournier <clement.fournier76@gmail.com>
The designer is part of PMD's binary distributions. To **install a distribution**, see the
[documentation page about installing PMD](pmd_userdocs_installation.html).
The app needs JRE 1.8 or above to run. Be aware that on JRE 11+, the JavaFX distribution should be installed
separately. Visit the [JavaFX download page](https://gluonhq.com/products/javafx/) to download a distribution,
extract it, and set the JAVAFX_HOME environment variable.
The designer still works with Java 8 from Oracle, which includes JavaFX. If you use this Java version, then
all is set. However, it is recommended to use OpenJDK along with OpenJFX. The recommended Java Runtime is
Java 11 (or later) with OpenJFX 17 (or later).
If the bin directory of your PMD distribution is on your shell's path, then you can **launch the app** with
You can get OpenJDK from [Adoptium](https://adoptium.net), [Azul](https://www.azul.com/downloads/#zulu),
[Microsoft](https://learn.microsoft.com/en-us/java/openjdk/download), [SAP](https://sap.github.io/SapMachine/),
[Amazon](https://downloads.corretto.aws/#/overview) and other OpenJDK vendors.
Note: Azul provides a JDK which includes JavaFX - this variant is currently not supported. You always need
to install OpenJFX separately.
[OpenJFX](https://openjfx.io/) is available from [JavaFX download page](https://gluonhq.com/products/javafx/).
You need the SDK. Extract the zip file, and set the `JAVAFX_HOME` environment variable to the extracted
directory. It should be the directory, that contain the sub-folder "lib" in it.
Example (for linux x64 only, with Java 21 and OpenJFX 21):
```shell
$ mkdir $HOME/openjdk
$ cd $HOME/openjdk
$ wget https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.2%2B13/OpenJDK21U-jdk_x64_linux_hotspot_21.0.2_13.tar.gz
$ tar xfz OpenJDK21U-jdk_x64_linux_hotspot_21.0.2_13.tar.gz
$ export JAVA_HOME=$HOME/openjdk/jdk-21.0.2+13
$ export PATH=$JAVA_HOME/bin:$PATH
$ wget https://download2.gluonhq.com/openjfx/21.0.2/openjfx-21.0.2_linux-x64_bin-sdk.zip
$ unzip -q openjfx-21.0.2_linux-x64_bin-sdk.zip
$ export JAVAFX_HOME=$HOME/openjdk/javafx-sdk-21.0.2
```
If the bin directory of your PMD distribution is on your shell's path, then you can then **launch the app** with
{% include cli_example.html
id="pmd"
@ -25,7 +49,7 @@ If the bin directory of your PMD distribution is on your shell's path, then you
windows="pmd.bat designer" %}
{% include note.html content="pmd-ui.jar is not a runnable jar, because it doesn't include any PMD language module, or PMD Core. " %}
{% include note.html content="pmd-designer.jar is not a runnable jar, because it doesn't include any PMD language module, or PMD Core. " %}
This is to allow easy updating, and let you choose the dependencies you're interested in.
@ -36,7 +60,7 @@ standard PMD startup scripts, which setups the classpath with the available PMD
### Updating
The latest version of the designer currently **works with PMD 7.0.0 and above**. You can simply replace
pmd-ui-7.X.Y.jar with the [latest build](https://github.com/pmd/pmd-designer/releases) in the installation
pmd-designer-7.X.Y.jar with the [latest build](https://github.com/pmd/pmd-designer/releases) in the installation
folder of your PMD distribution, and run it normally. Note that updating may cause some persisted state
to get lost, for example the code snippet.

View File

@ -25,7 +25,7 @@ Each category-ruleset has a single abstract base test class, from which the indi
We have one test class per rule, which executes all test cases for a single rule. The actual test cases are
stored in separate XML files, for each rule a separate file is used.
All the test classes inherit from {% jdoc test::testframework.PmdRuleTst %},
All the test classes inherit from {% jdoc test::test.PmdRuleTst %},
which provides the seamless integration with JUnit5. This base class determines the language, the category name
and the rule name from the concrete test class. It then searches the test code on its own.
E.g. the individual rule test class
@ -41,7 +41,7 @@ test case and just execute this one.
## Where to place the test code
The {% jdoc test::testframework.PmdRuleTst %} class searches the XML file, that describes the test cases
The {% jdoc test::test.PmdRuleTst %} class searches the XML file, that describes the test cases
for a certain rule using the following convention:
The XML file is a test resource, so it is searched in the tree under `src/test/resources`.
@ -76,13 +76,13 @@ see [Using the test framework externally](#using-the-test-framework-externally).
### Test Class: AbstractClassWithoutAbstractMethodTest
This class inherits from {% jdoc test::testframework.PmdRuleTst %} and is located in the package "bestpractices",
This class inherits from {% jdoc test::test.PmdRuleTst %} and is located in the package "bestpractices",
since the rule belongs to the category "Best Practices":
``` java
package net.sourceforge.pmd.lang.java.rule.bestpractices;
import net.sourceforge.pmd.testframework.PmdRuleTst;
import net.sourceforge.pmd.test.PmdRuleTst;
class AbstractClassWithoutAbstractMethodTest extends PmdRuleTst {
// no additional unit tests
@ -251,7 +251,7 @@ the rule test manually, as SimpleAggregatorTst will fail to determine it correct
``` java
package com.example.pmd.rules;
import net.sourceforge.pmd.testframework.SimpleAggregatorTst;
import net.sourceforge.pmd.test.SimpleAggregatorTst;
class CustomRuleTest extends SimpleAggregatorTst {
@Override
@ -272,19 +272,19 @@ The test data should be placed in an XML file located in "src/test/resources" un
The framework uses the [dynamic test feature](https://junit.org/junit5/docs/current/user-guide/#writing-tests-dynamic-tests)
of JUnit5 under the hood, among a couple of utility classes:
* {% jdoc test::testframework.PmdRuleTst %}: This is the base class for tests in PMD's code base. It is a subclass of
{% jdoc test::testframework.RuleTst %} and just
* {% jdoc test::test.PmdRuleTst %}: This is the base class for tests in PMD's code base. It is a subclass of
{% jdoc test::test.RuleTst %} and just
contains the logic to determine the test resources based on the test class name.
* {% jdoc test::testframework.SimpleAggregatorTst %}: This is a more generic base class for the test classes.
* {% jdoc test::test.SimpleAggregatorTst %}: This is a more generic base class for the test classes.
It doesn't register any test cases on its own. You can register your own rule tests.
It itself is a subclass of {% jdoc test::testframework.RuleTst %}.
It itself is a subclass of {% jdoc test::test.RuleTst %}.
* The maven module "pmd-test-schema" contains the logic to parse the XML files and provides a
{% jdoc test-schema::test.schema.RuleTestCollection %}. This in turn contains a list of
{% jdoc test-schema::test.schema.RuleTestDescriptor %}s. Each rule test descriptor describes a single test case.
* {% jdoc test::testframework.RuleTst %}: uses the {%jdoc test-schema::test.schema.TestSchemaParser %}
* {% jdoc test::test.RuleTst %}: uses the {%jdoc test-schema::test.schema.TestSchemaParser %}
from module "pmd-test-schema" to parse the test cases, executes each
rule test descriptor and asserts the results. It defines a test method `ruleTests()` which is a test factory
and returns one dynamic test per rule test.

Some files were not shown because too many files have changed in this diff Show More