fix(lint): address review feedback on path selection

The two assertions on the linted file name compared against raw console
output. The console wraps at 80 columns, so a long enough temporary path
splits the name across lines and the assertion fails. Under xdist the
path gains a popen-gwN segment, which is what makes it reproducible
there. Reproduced directly: a path of the right length renders the line
as "models/seed_model.sq\nl:". Both assertions now compare against the
output with the wrapping removed.

A directory now says so instead of reporting that no models were found
in it, which read as though the directory were empty.

The docstring records that relative paths resolve against the current
working directory rather than the project path. That is what path-based
tools pass, but it means the Python API only accepts relative paths when
called from inside the project.

The linter guide now frames path selection as the option for tools that
hand over file names, and points CI use towards a model selector instead
of paths from git diff, so that the models affected by a change are
linted rather than only the files that were edited.

Signed-off-by: Adegbite Ayoade <tripleaceme@gmail.com>

Author: tripleaceme

docs/guides/linter.md

@@ -127,9 +127,13 @@ Error: Linter detected errors in the code. Please fix them before proceeding.
 
 Use `sqlmesh lint --help` for more information.
 
-Models can be selected by name with `--model`, by model file path, or by both at once. Selecting by
-path lets `sqlmesh lint` be wired up to path-based tooling such as [pre-commit](https://pre-commit.com/),
-which passes the names of the changed files:
+Models can be selected by name with `--model`, by model file path, or by both at once.
+
+Selecting by path is intended for tools that hand `sqlmesh lint` a list of file names, such as
+[pre-commit](https://pre-commit.com/) hooks and editor integrations. To lint the models that changed
+on a branch in CI, prefer a model selector such as `git:main` over passing paths from
+`git diff --name-only`, so that the models affected by a change are selected rather than only the
+files that were edited.
 
 ``` bash
 $ sqlmesh lint models/full_model.sql models/incremental_model.sql

sqlmesh/core/context.py

@@ -3617,12 +3617,22 @@ def lint_models(
                 value of ``linter.use_project_index`` is used. Indexed linting of selected
                 models reloads an already-loaded context so the requested scope is applied.
             paths: Model file paths to lint, each resolved to the model(s) defined in it. Can be
-                combined with `models`.
+                combined with `models`. Relative paths are resolved against the current working
+                directory rather than the project path, which is what path-based tools such as
+                pre-commit pass. Calling this from the Python API with relative paths therefore
+                only works from inside the project directory.
         """
         models = list(models) if models is not None else []
         target_paths = [Path(path) for path in paths] if paths is not None else []
 
         # Fail fast on a mistyped path instead of loading and linting the whole project.
+        directory_paths = [str(path) for path in target_paths if path.is_dir()]
+        if directory_paths:
+            raise SQLMeshError(
+                f"Expected model files but got director{'ies' if len(directory_paths) > 1 else 'y'}: "
+                f"{', '.join(directory_paths)}. Pass the model files themselves."
+            )
+
         missing_paths = [str(path) for path in target_paths if not path.is_file()]
         if missing_paths:
             raise SQLMeshError(

tests/cli/test_cli.py

@@ -1492,7 +1492,7 @@ def test_lint_paths(runner, tmp_path):
         cli, ["--paths", tmp_path, "lint", str(tmp_path / "models" / "seed_model.sql")]
     )
     assert result.output.count("Linter errors for") == 1
-    assert "seed_model.sql" in result.output
+    assert "seed_model.sql" in result.output.replace("\n", "")
     assert result.exit_code == 1
 
     # Multiple model files can be passed, as pre-commit does.
@@ -1556,7 +1556,7 @@ def test_lint_relative_path(runner, tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     result = runner.invoke(cli, ["--paths", tmp_path, "lint", "models/seed_model.sql"])
     assert result.output.count("Linter errors for") == 1
-    assert "seed_model.sql" in result.output
+    assert "seed_model.sql" in result.output.replace("\n", "")
     assert result.exit_code == 1
 
 
@@ -1586,6 +1586,14 @@ def test_lint_unknown_path(runner, tmp_path):
     assert "No models were found at the following path(s)" in result.output
     assert "Linter errors for" not in result.output
 
+    # A directory says so, rather than claiming it contains no models.
+    result = runner.invoke(cli, ["--paths", tmp_path, "lint", str(tmp_path / "models")])
+    assert result.exit_code == 1
+    output = result.output.replace("\n", "")
+    assert "Expected model files but got directory" in output
+    assert "Pass the model files themselves." in output
+    assert "Linter errors for" not in result.output
+
 
 def test_lint_no_models(runner, tmp_path):
     with open(tmp_path / "config.yaml", "w", encoding="utf-8") as f: