docs: update undefined var check reference

Signed-off-by: David Karlsson <[email protected]>

frontend/dockerfile/docs/rules/undefined-var.md

@@ -13,24 +13,21 @@ Usage of undefined variable '$foo'
 
 ## Description
 
-Before you reference an environment variable or a build argument in a `RUN`
-instruction, you should ensure that the variable is declared in the Dockerfile,
-using the `ARG` or `ENV` instructions.
+This check ensures that environment variables and build arguments are correctly
+declared before being used in the following instructions: `ADD`, `ARG`, `COPY`,
+`ENV`, and `FROM`. While undeclared variables might not cause an immediate
+build failure, they can lead to unexpected behavior or errors later in the
+build process.
 
-Attempting to access an environment variable without explicitly declaring it
-doesn't necessarily result in a build error, but it may yield an unexpected
-result or an error later on in the build process.
-
-This check also attempts to detect if you're accessing a variable with a typo.
-For example, given the following Dockerfile:
+It also detects common mistakes like typos in variable names. For example, in
+the following Dockerfile:
 
 ```dockerfile
 FROM alpine
 ENV PATH=$PAHT:/app/bin
 ```
 
-The check detects that `$PAHT` is undefined, and that it's probably a
-misspelling of `PATH`.
+The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`:
 
 ```text
 Usage of undefined variable '$PAHT' (did you mean $PATH?)
@@ -53,3 +50,17 @@ ARG foo
 COPY $foo .
 ```
 
+❌ Bad: `$foo` is undefined.
+
+```dockerfile
+FROM alpine AS base
+ARG VERSION=$foo
+```
+
+✅ Good: the base image defines `$PYTHON_VERSION`
+
+```dockerfile
+FROM python AS base
+ARG VERSION=$PYTHON_VERSION
+```
+

frontend/dockerfile/linter/docs/UndefinedVar.md

@@ -6,24 +6,21 @@ Usage of undefined variable '$foo'
 
 ## Description
 
-Before you reference an environment variable or a build argument in a `RUN`
-instruction, you should ensure that the variable is declared in the Dockerfile,
-using the `ARG` or `ENV` instructions.
+This check ensures that environment variables and build arguments are correctly
+declared before being used in the following instructions: `ADD`, `ARG`, `COPY`,
+`ENV`, and `FROM`. While undeclared variables might not cause an immediate
+build failure, they can lead to unexpected behavior or errors later in the
+build process.
 
-Attempting to access an environment variable without explicitly declaring it
-doesn't necessarily result in a build error, but it may yield an unexpected
-result or an error later on in the build process.
-
-This check also attempts to detect if you're accessing a variable with a typo.
-For example, given the following Dockerfile:
+It also detects common mistakes like typos in variable names. For example, in
+the following Dockerfile:
 
 ```dockerfile
 FROM alpine
 ENV PATH=$PAHT:/app/bin
 ```
 
-The check detects that `$PAHT` is undefined, and that it's probably a
-misspelling of `PATH`.
+The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`:
 
 ```text
 Usage of undefined variable '$PAHT' (did you mean $PATH?)
@@ -45,3 +42,17 @@ FROM alpine AS base
 ARG foo
 COPY $foo .
 ```
+
+❌ Bad: `$foo` is undefined.
+
+```dockerfile
+FROM alpine AS base
+ARG VERSION=$foo
+```
+
+✅ Good: the base image defines `$PYTHON_VERSION`
+
+```dockerfile
+FROM python AS base
+ARG VERSION=$PYTHON_VERSION
+```