From 03eb060a342575f012e942332e1570850a7e54be Mon Sep 17 00:00:00 2001 From: nscuro Date: Tue, 5 May 2026 21:28:41 +0200 Subject: [PATCH] Improve prose linting * Adds a template to surface linting issues in a more readable format. * Adds a lint-prose-changed Make target that only lints modified files. Helpful because the full docs still have loads of issues. * Raises custom Vale rules from severity warning to error. * Fixes newly raised errors. Signed-off-by: nscuro --- .vale/output.tmpl | 16 +++++++ .vale/styles/DependencyTrack/AIBuzzwords.yml | 2 +- .../DependencyTrack/AIFillerPhrases.yml | 2 +- .../styles/DependencyTrack/AITransitions.yml | 2 +- .vale/styles/DependencyTrack/EmDash.yml | 2 +- AGENTS.md | 2 +- Makefile | 46 +++++++++++++------ README.md | 11 +++-- .../architecture/design/durable-execution.md | 10 ++-- .../design/vulnerability-analysis.md | 4 +- .../administration/configuring-database.md | 4 +- docs/reference/configuration/application.md | 4 +- docs/reference/configuration/datasources.md | 4 +- .../datasources/github-advisories.md | 4 +- docs/reference/datasources/index.md | 2 +- .../datasources/internal-components.md | 2 +- 16 files changed, 76 insertions(+), 41 deletions(-) create mode 100644 .vale/output.tmpl diff --git a/.vale/output.tmpl b/.vale/output.tmpl new file mode 100644 index 0000000..34212a5 --- /dev/null +++ b/.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: ... +Scope a rule by path: edit .vale.ini (see the [docs/tutorials/*.md] block) \ No newline at end of file diff --git a/.vale/styles/DependencyTrack/AIBuzzwords.yml b/.vale/styles/DependencyTrack/AIBuzzwords.yml index bf0835c..8be7514 100644 --- a/.vale/styles/DependencyTrack/AIBuzzwords.yml +++ b/.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 diff --git a/.vale/styles/DependencyTrack/AIFillerPhrases.yml b/.vale/styles/DependencyTrack/AIFillerPhrases.yml index 0c1a3b1..f4f770c 100644 --- a/.vale/styles/DependencyTrack/AIFillerPhrases.yml +++ b/.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 diff --git a/.vale/styles/DependencyTrack/AITransitions.yml b/.vale/styles/DependencyTrack/AITransitions.yml index 4cca04c..bd49858 100644 --- a/.vale/styles/DependencyTrack/AITransitions.yml +++ b/.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 diff --git a/.vale/styles/DependencyTrack/EmDash.yml b/.vale/styles/DependencyTrack/EmDash.yml index 2d168f6..aeceb26 100644 --- a/.vale/styles/DependencyTrack/EmDash.yml +++ b/.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: - '—' diff --git a/AGENTS.md b/AGENTS.md index 2832528..d3adb95 100644 --- a/AGENTS.md +++ b/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` diff --git a/Makefile b/Makefile index e4d8c7d..131aecc 100644 --- a/Makefile +++ b/Makefile @@ -17,23 +17,26 @@ 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" \ @@ -41,7 +44,7 @@ lint-markdown: .PHONY: lint-markdown lint-yaml: - docker run --rm \ + @docker run --rm \ -v "$(shell pwd)":/workdir \ -w /workdir \ "$(YAMLLINT_IMAGE)" \ @@ -49,43 +52,56 @@ lint-yaml: .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)" \ @@ -93,5 +109,5 @@ generate-proto-docs: .PHONY: generate-proto-docs serve: - uv run mkdocs serve --livereload + @uv run mkdocs serve --livereload .PHONY: serve diff --git a/README.md b/README.md index 17c2811..54f9310 100644 --- a/README.md +++ b/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. diff --git a/docs/concepts/architecture/design/durable-execution.md b/docs/concepts/architecture/design/durable-execution.md index c3872bd..8900b11 100644 --- a/docs/concepts/architecture/design/durable-execution.md +++ b/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 diff --git a/docs/concepts/architecture/design/vulnerability-analysis.md b/docs/concepts/architecture/design/vulnerability-analysis.md index 4305875..684b824 100644 --- a/docs/concepts/architecture/design/vulnerability-analysis.md +++ b/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 diff --git a/docs/guides/administration/configuring-database.md b/docs/guides/administration/configuring-database.md index 00da011..b32f19f 100644 --- a/docs/guides/administration/configuring-database.md +++ b/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 diff --git a/docs/reference/configuration/application.md b/docs/reference/configuration/application.md index 985460b..1ae903e 100644 --- a/docs/reference/configuration/application.md +++ b/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 ``` + Environment variables commonly only support alphanumeric characters and underscores (`_`). + 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]: diff --git a/docs/reference/configuration/datasources.md b/docs/reference/configuration/datasources.md index c5bb989..6f7d49d 100644 --- a/docs/reference/configuration/datasources.md +++ b/docs/reference/configuration/datasources.md @@ -13,8 +13,8 @@ dt.datasource..= For available properties, and their environment variable equivalents, refer to the [configuration reference]. !!! tip - When `` is omitted, `default` is assumed. - This means that `dt.datasource.url` and `dt.datasource.default.url` are treated equally. + When `` 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. diff --git a/docs/reference/datasources/github-advisories.md b/docs/reference/datasources/github-advisories.md index f56dc94..af53574 100644 --- a/docs/reference/datasources/github-advisories.md +++ b/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. diff --git a/docs/reference/datasources/index.md b/docs/reference/datasources/index.md index 9e4daa8..6864d94 100644 --- a/docs/reference/datasources/index.md +++ b/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` diff --git a/docs/reference/datasources/internal-components.md b/docs/reference/datasources/internal-components.md index 5eb3ff7..d962545 100644 --- a/docs/reference/datasources/internal-components.md +++ b/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