Improve prose linting

.vale/output.tmpl

@@ -0,0 +1,16 @@
+{{- range .Files -}}
+{{- $path := .Path -}}
+{{- if .Alerts }}
+{{ $path }}
+{{ range .Alerts -}}
+{{- if eq .Severity "error"      }}  error  {{ end -}}
+{{- if eq .Severity "warning"    }}  warn   {{ end -}}
+{{- if eq .Severity "suggestion" }}  sugg   {{ end -}}
+{{ printf "%s:%d:%d  [%s]  %s" $path .Line (index .Span 0) .Check .Message }}
+{{ end }}
+{{- end -}}
+{{- end }}
+{{ .LintedTotal }} file(s) linted.
+
+Suppress a rule inline:  <!-- vale RuleName = NO --> ... <!-- vale RuleName = YES -->
+Scope a rule by path:    edit .vale.ini (see the [docs/tutorials/*.md] block)

.vale/styles/DependencyTrack/AIBuzzwords.yml

@@ -17,7 +17,7 @@
 extends: existence
 message: "Avoid overused term '%s'. Use a more specific word."
 ignorecase: true
-level: warning
+level: error
 tokens:
 - leverage
 - leveraging

.vale/styles/DependencyTrack/AIFillerPhrases.yml

@@ -17,7 +17,7 @@
 extends: existence
 message: "Avoid filler phrase '%s'. Be direct."
 ignorecase: true
-level: warning
+level: error
 tokens:
 - it is important to note
 - it is worth noting

.vale/styles/DependencyTrack/AITransitions.yml

@@ -17,7 +17,7 @@
 extends: existence
 message: "Avoid weak transition '%s' at the start of a sentence. Restructure or remove."
 ignorecase: false
-level: warning
+level: error
 scope: sentence
 tokens:
 - Additionally

.vale/styles/DependencyTrack/EmDash.yml

@@ -17,6 +17,6 @@
 extends: existence
 message: "Avoid em-dashes ('—'). Use commas, parentheses, or separate sentences instead."
 nonword: true
-level: warning
+level: error
 tokens:
 - '—'

AGENTS.md

@@ -36,7 +36,7 @@ Always use `make` targets for building, serving, and linting. Do not run `docker
 Run the relevant linter after modifying files:
 
 - **Markdown files** (`docs/**/*.md`, `context/**/*.md`): `make lint-markdown`
-- **Prose quality** (`docs/**/*.md`): `make lint-prose`
+- **Prose quality** (`docs/**/*.md`): `make lint-prose`. For fast local iteration on a feature branch, `make lint-prose-changed` lints only files changed vs. the branch's upstream. Scope a full-tree run with `VALE_PATHS=...`; surface lower-severity hints with `VALE_MIN_LEVEL=suggestion`.
 - **YAML files** (`mkdocs.yml`, `.github/**/*.yml`, etc.): `make lint-yaml`
 - **Python files** (`scripts/**/*.py`): `make lint-python`
 - **All at once**: `make lint`

Makefile

@@ -17,81 +17,97 @@
 
 MARKDOWNLINT_IMAGE := davidanson/markdownlint-cli2:v0.18.1
 PROTOC_GEN_DOC_IMAGE := pseudomuto/protoc-gen-doc:1.5
+VALE_BASE_REF ?= $(shell git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null || echo origin/main)
 VALE_IMAGE := jdkato/vale:v3.14.1
+VALE_MIN_LEVEL ?= warning
+VALE_PATHS ?= docs/
 VALE_SYNC_STAMP := .vale/styles/.synced
 YAMLLINT_IMAGE := pipelinecomponents/yamllint:0.35.1
 
 build:
-	uv run mkdocs build --strict
+	@uv run mkdocs build --strict
 .PHONY: build
 
 clean:
-	rm -rf site/
+	@rm -rf site/
 .PHONY: clean
 
 lint: lint-markdown lint-yaml lint-prose lint-python
 .PHONY: lint
 
 lint-markdown:
-	docker run --rm \
+	@docker run --rm \
 	  -v "$(shell pwd)":/workdir \
 	  "$(MARKDOWNLINT_IMAGE)" \
 	  "context/**/*.md" \
 	  "docs/**/*.md"
 .PHONY: lint-markdown
 
 lint-yaml:
-	docker run --rm \
+	@docker run --rm \
 	  -v "$(shell pwd)":/workdir \
 	  -w /workdir \
 	  "$(YAMLLINT_IMAGE)" \
 	  yamllint .
 .PHONY: lint-yaml
 
 lint-python:
-	uvx ruff check scripts/
-	uvx ruff format --check scripts/
+	@uvx ruff check scripts/
+	@uvx ruff format --check scripts/
 .PHONY: lint-python
 
 # Only sync vale when .vale.ini has changed since last sync.
 # https://www.technovelty.org/tips/the-stamp-idiom-with-make.html
 $(VALE_SYNC_STAMP): .vale.ini
-	docker run --rm \
+	@docker run --rm \
 	  -v "$(shell pwd)":/workdir \
 	  -w /workdir \
 	  "$(VALE_IMAGE)" \
-	  sync
+	  sync >/dev/null
 	@mkdir -p $(dir $@) && touch $@
 
 lint-prose: $(VALE_SYNC_STAMP)
-	docker run --rm \
+	@docker run --rm \
 	  -v "$(shell pwd)":/workdir \
 	  -w /workdir \
 	  "$(VALE_IMAGE)" \
-	  --output=line \
-	  docs/
+	  --minAlertLevel=$(VALE_MIN_LEVEL) \
+	  --output=.vale/output.tmpl \
+	  $(VALE_PATHS)
 .PHONY: lint-prose
 
+lint-prose-changed: $(VALE_SYNC_STAMP)
+	@files=$$(git diff --name-only --diff-filter=ACMR $(VALE_BASE_REF) -- 'docs/**/*.md' 'context/**/*.md'); \
+	if [ -z "$$files" ]; then echo "No changed Markdown files vs. $(VALE_BASE_REF)."; exit 0; fi; \
+	docker run --rm \
+	  -v "$(shell pwd)":/workdir \
+	  -w /workdir \
+	  "$(VALE_IMAGE)" \
+	  --minAlertLevel=$(VALE_MIN_LEVEL) \
+	  --output=.vale/output.tmpl \
+	  $$files
+.PHONY: lint-prose-changed
+
 generate-config-docs:
-	uv run --only-group generate scripts/generate_config_docs.py \
+	@uv run --only-group generate scripts/generate_config_docs.py \
 	  --template scripts/templates/config-docs.md.j2 \
 	  --output docs/reference/configuration/properties.md \
 	  $(APISERVER_PROPERTIES)
 .PHONY: generate-config-docs
 
 generate-proto-docs:
-	docker run -i --rm -u "$$(id -u):$$(id -g)" \
+	@docker run -i --rm -u "$$(id -u):$$(id -g)" \
 	  -v "$$(pwd)/docs/reference/schemas:/out" \
 	  -v "$$(pwd)/$(APISERVER_DIR)/notification/api/src/main/proto/org/dependencytrack/notification/v1:/protos" \
 	  "$(PROTOC_GEN_DOC_IMAGE)" \
 	  --doc_opt=/out/notification.md.tmpl,notification.md
-	docker run -i --rm -u "$$(id -u):$$(id -g)" \
+	@docker run -i --rm -u "$$(id -u):$$(id -g)" \
 	  -v "$$(pwd)/docs/reference/schemas:/out" \
 	  -v "$$(pwd)/$(APISERVER_DIR)/proto/src/main/proto/org/dependencytrack/policy/v1:/protos" \
 	  "$(PROTOC_GEN_DOC_IMAGE)" \
 	  --doc_opt=/out/policy.md.tmpl,policy.md
 .PHONY: generate-proto-docs
 
 serve:
-	uv run mkdocs serve --livereload
+	@uv run mkdocs serve --livereload
 .PHONY: serve

README.md

@@ -36,11 +36,12 @@ Navigation is managed via `.pages` files in each section directory.
 ## Linting
 
 ```sh
-make lint              # Run all linters
-make lint-markdown     # Markdown (markdownlint)
-make lint-prose        # Prose quality (Vale)
-make lint-yaml         # YAML (yamllint)
-make lint-python       # Python (Ruff)
+make lint                  # Run all linters
+make lint-markdown         # Markdown (markdownlint)
+make lint-prose            # Prose quality (Vale, full docs/ tree)
+make lint-prose-changed    # Vale, only files changed vs. the upstream branch
+make lint-yaml             # YAML (yamllint)
+make lint-python           # Python (Ruff)
 ```
 
 Linters run in Docker, except for Python which uses [Ruff](https://docs.astral.sh/ruff/) via `uvx`. Fix all errors before submitting changes.

docs/concepts/architecture/design/durable-execution.md

@@ -272,8 +272,8 @@ has expired.
 Nodes that fail to attempt lease acquisition, for example due to timeouts,
 will assume their lease to be *lost*. This is to prevent the likelihood
 of [split-brain](https://en.wikipedia.org/wiki/Split-brain_(computing)).
-It should be noted though that the worst symptom of split-brain for the engine
-is an increase is potentially expensive operations. Correctness is not affected.
+For the engine, the worst symptom of split-brain is an increase in
+potentially expensive operations. Correctness is not affected.
 
 During graceful shutdown, nodes simply release their leadership lease:
 
@@ -333,7 +333,7 @@ processed in creation order.
 ### Task processing
 
 !!! note
-    The engine leverages Java's [virtual threads] for task execution, enabling high degrees
+    The engine uses Java's [virtual threads] for task execution, enabling high degrees
     of concurrency while maintaining a slim resource footprint.
 
 #### Workflow tasks
@@ -446,7 +446,7 @@ the engine has to assume that the action itself has never happened. No mechanism
 This is one reason why actions should be [idempotent], making them safe to execute multiple times.
 The engine takes advantage of this inherent risk, and utilises buffering in exactly that time window.
 
-When flushing buffers, the engine leverages
+When flushing buffers, the engine applies
 [Postgres-specific optimizations](https://www.tigerdata.com/blog/boosting-postgres-insert-performance)
 to further reduce the amount of time spent *in the database*.
 
@@ -534,7 +534,7 @@ Instead, the engine entirely relies on polling.
 
 ### Protobuf Serialization
 
-Workflow events, as well as workflow and activity arguments and results, leverage Protobuf for serialization.
+Workflow events, as well as workflow and activity arguments and results, use Protobuf for serialization.
 Protobuf is fast and efficient, and serialized messages are smaller than their JSON counterparts.
 
 The tooling around Protobuf is excellent. With [`buf`](https://buf.build/), we have linting and breaking

docs/concepts/architecture/design/vulnerability-analysis.md

@@ -7,7 +7,7 @@ by coordinating multiple vulnerability analyzers via a [durable workflow](durabl
 
 ## Granularity
 
-Vulnerability analysis happens at the project level. This means that analysis of individual
+Vulnerability analysis happens at the project level. Analysis of individual
 components is not supported.
 
 The reason for this design choice is that analysis can be contextual. Some scanners,
@@ -423,7 +423,7 @@ applied analysis state is reset to defaults.
 
 !!! tip
     Policy analyses are applied atomically with finding reconciliation.
-    This means that a newly identified finding can be immediately suppressed,
+    A newly identified finding can therefore be immediately suppressed,
     without ever showing up in time series metrics, or triggering a `NEW_VULNERABILITY` notification.
 
 ### Notifications

docs/guides/administration/configuring-database.md

@@ -47,7 +47,7 @@ See for example:
 * [Using PostgreSQL with Red Hat Enterprise Linux](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/configuring_and_using_database_servers/using-postgresql_configuring-and-using-database-servers)
 
 To get the most out of your Dependency-Track installation, we recommend to run PostgreSQL on a separate machine
-than the application containers. You want PostgreSQL to be able to leverage the entire machine's resources,
+than the application containers. You want PostgreSQL to be able to use the entire machine's resources,
 without being impacted by other applications.
 
 For smaller and non-critical deployments, it is totally fine to run everything on a single machine.
@@ -160,7 +160,7 @@ ALTER SYSTEM SET (WAL_COMPRESSION = 'zstd');
 ## Centralised connection pooling
 
 For large deployments (that is, upwards of 5 instances), it can become undesirable for
-each instance to maintain its own connection pool. In this case, you can leverage
+each instance to maintain its own connection pool. In this case, you can use
 centralised connection pools such as [PgBouncer].
 
 !!! warning

docs/reference/configuration/application.md

@@ -4,7 +4,7 @@ Dependency-Track's configuration system is based on [MicroProfile Config],
 enabling it to support multiple [sources](#sources).
 
 !!! tip
-    A comprehensive list of supported config properties can be found in
+    The full list of supported config properties can be found in
     the [configuration reference](properties.md).
 
 ## Sources
@@ -59,7 +59,9 @@ separated by hyphens (`-`) and periods (`.`). For example:
 foo.BAR-baz=123
 ```
 
+<!-- vale DependencyTrack.AIBuzzwords = NO -->
 Environment variables commonly only support alphanumeric characters and underscores (`_`).
+<!-- vale DependencyTrack.AIBuzzwords = YES -->
 To bridge this gap, Dependency-Track will use the following matching strategies,
 as [defined](https://download.eclipse.org/microprofile/microprofile-config-3.1/microprofile-config-spec-3.1.html#default_configsources.env.mapping)
 by [MicroProfile Config]:

docs/reference/configuration/datasources.md

@@ -13,8 +13,8 @@ dt.datasource.<name>.<property>=<value>
 For available properties, and their environment variable equivalents, refer to the [configuration reference].
 
 !!! tip
-    When `<name>` is omitted, `default` is assumed.
-    This means that `dt.datasource.url` and `dt.datasource.default.url` are treated equally.
+    When `<name>` is omitted, `default` is assumed, so
+    `dt.datasource.url` and `dt.datasource.default.url` are treated equally.
 
 The `default` data source is *required*. It serves the REST API
 and the vast majority of background processing.

docs/reference/datasources/github-advisories.md

@@ -2,7 +2,7 @@
 
 The [GitHub Advisory Database](https://github.com/advisories) (GHSA) contains
 security advisories for open source packages hosted on GitHub and other ecosystems.
-Advisories may or may not overlap with NVD CVE records—GitHub often publishes
+Advisories may or may not overlap with NVD CVE records. GitHub often publishes
 advisories for vulnerabilities that are not yet in the NVD, or with more ecosystem-
 specific detail.
 
@@ -36,5 +36,5 @@ GitHub Advisory mirroring is configured in the administration UI under
 | GitHub Personal Access Token | Required. A GitHub PAT with no scopes assigned is sufficient. Without a token, the GraphQL API rejects requests. |
 
 To create a token, visit [github.com/settings/tokens](https://github.com/settings/tokens)
-and generate a classic or fine-grained token. No scopes are required—the public
+and generate a classic or fine-grained token. No scopes are required; the public
 advisory data is accessible to any authenticated user.

docs/reference/datasources/index.md

@@ -3,7 +3,7 @@
 Vulnerability datasources are the upstream feeds from which Dependency-Track populates
 its internal vulnerability database. The [internal analyzer](../analyzers.md#internal)
 queries this local database when evaluating components, so no external call is made at
-analysis time—only during mirroring.
+analysis time, only during mirroring.
 
 Mirroring runs on a configurable schedule (daily by default) and on instance startup.
 Progress and errors are reported via the `DATASOURCE_MIRRORING`

docs/reference/datasources/internal-components.md

@@ -25,7 +25,7 @@ Two matching modes are available:
 Patterns are matched against the component's PURL namespace and name fields.
 
 !!! note
-    By default, no components are identified as internal—all components are treated
+    By default, no components are identified as internal. All components are treated
     as third-party and may be sent to configured external analyzers.
 
 ## Effects of Being Marked Internal