support custom dir (#7145)

### Summary
This PR adds an option to specify BC linter config path, which will be
used in vllm-project/vllm#21234

### Test plan
Locally test against PR: vllm-project/vllm#24614

Before:
```
../test-infra/tools/stronghold/bin/check-api-compatibility --base-commit=b5e383cd8b62975dec605bed05e22d273c296c7a --head-commit=38ce6fa81660f0be6e0e61672fdc499bcd7fabc4

::group::fetch github.event.pull_request.base.sha
From ssh://github.com/zhewenl/vllm
 * branch                b5e383cd8b62975dec605bed05e22d273c296c7a -> FETCH_HEAD
::endgroup::
fatal: path 'vllm/_bc_linter.py' exists on disk, but not in 'b5e383cd8b62975dec605bed05e22d273c296c7a'
::warning file=vllm/v1/core/sched/output.py,line=99::Function CachedRequestData: num_computed_tokens changed from list[int] to list[float]
::warning file=vllm/v1/core/sched/scheduler.py,line=1::Function Scheduler.get_grammar_bitmask: function deleted
::warning file=vllm/v1/core/sched/scheduler.py,line=1::Function Scheduler.update_draft_token_ids: function deleted
```

After:
```
../test-infra/tools/stronghold/bin/check-api-compatibility --base-commit=b5e383cd8b62975dec605bed05e22d273c296c7a --head-commit=38ce6fa81660f0be6e0e61672fdc499bcd7fabc4 --config-dir=.github

::group::fetch github.event.pull_request.base.sha
From ssh://github.com/zhewenl/vllm
 * branch                b5e383cd8b62975dec605bed05e22d273c296c7a -> FETCH_HEAD
::endgroup::
BC-linter: Using .bc-linter.yml (parsed successfully)
fatal: path 'vllm/_bc_linter.py' exists on disk, but not in 'b5e383cd8b62975dec605bed05e22d273c296c7a'
::warning file=vllm/v1/core/sched/output.py,line=99::Function CachedRequestData: num_computed_tokens changed from list[int] to list[float]
> ../test-infra/tools/stronghold/bin/check-api-compatibility --base-commit=b5e383cd8b62975dec605bed05e22d273c296c7a --head-commit=38ce6fa81660f0be6e0e61672fdc499bcd7fabc4
```

Note the difference in `scheduler.py`, before the we specifying the
local config the bc linter yml was not respected - so the default rules
are applied and we check ALL python files; after specifying the yml the
warnings are restricted to ONLY the functions with annotations

Author: zhewenl

.github/actions/bc-lint/action.yml

@@ -19,6 +19,10 @@ inputs:
     description: 'Link to the docs to display in case of failure'
     required: false
     default: ''
+  config_dir:
+    description: 'Directory to load .bc-linter.yml from (defaults to repository root)'
+    required: false
+    default: ''
 runs:
   using: 'composite'
   steps:
@@ -66,7 +70,8 @@ runs:
         ../_test-infra/tools/stronghold/bin/check-api-compatibility \
             --base-commit=${{ inputs.base_sha }} \
             --head-commit=${{ steps.merge_changes.outputs.new_head_sha }} \
-            ${{ inputs.suppression == 'true' && '--suppressed' || '' }}
+            ${{ inputs.suppression == 'true' && '--suppressed' || '' }} \
+            ${{ inputs.config_dir != '' && format('--config-dir={0}', inputs.config_dir) || '' }}
 
     - name: Display documentation link if failed
       if: ${{ failure() && inputs.docs_link }}

tools/stronghold/docs/bc_linter_config.md

@@ -5,8 +5,10 @@ The config enables repo‑specific path selection, rule suppression, and custom
 annotations to include/exclude specific APIs.
 
 ### Config file location
-- Place a YAML file named `.bc-linter.yml` at the repository root being linted
-  (the target repo).
+- By default the linter searches for a `.bc-linter.yml` file at the root of
+  the repository being linted.
+- Provide an alternative directory with `--config-dir` if the file lives
+  somewhere else.
 - If the file is missing or empty, defaults are applied (see below).
 
 ### Schema (YAML)

tools/stronghold/src/api/checker.py

@@ -32,6 +32,12 @@ def run() -> None:
         action="store_true",
         help="Enable verbose output",
     )
+    parser.add_argument(
+        "--config-dir",
+        type=str,
+        default=None,
+        help="Directory to load .bc-linter.yml from (defaults to repository root)",
+    )
     args = parser.parse_args(sys.argv[1:])
 
     repo = api.git.Repository(pathlib.Path("."))
@@ -46,7 +52,13 @@ def run() -> None:
     print("::endgroup::")
 
     # Load config and optionally print when detected
-    cfg, cfg_status = api.config.load_config_with_status(repo.dir)
+    # By default, configuration is loaded from the repository root.  A custom
+    # configuration directory may be provided via ``config_dir`` either as an
+    # absolute path or a path relative to ``repo_root``.
+    cfg_path = pathlib.Path(args.config_dir) if args.config_dir else repo.dir
+    if not cfg_path.is_absolute():
+        cfg_path = repo.dir / cfg_path
+    cfg, cfg_status = api.config.load_config_with_status(cfg_path)
     if cfg_status == "parsed":
         # Explicitly log successful config discovery and parsing
         print("BC-linter: Using .bc-linter.yml (parsed successfully)")

tools/stronghold/src/api/config.py

@@ -54,15 +54,16 @@ def default_config() -> Config:
     return Config()
 
 
-def load_config_with_status(repo_root: pathlib.Path) -> tuple[Config, str]:
-    """Loads configuration from `.bc-linter.yml` in the given repository root.
+def load_config_with_status(config_dir: pathlib.Path) -> tuple[Config, str]:
+    """Loads configuration from `.bc-linter.yml` in the given directory.
 
     Returns (config, status) where status is one of:
     - 'parsed'            -> config file existed and parsed successfully
     - 'default_missing'   -> no config file found
     - 'default_error'     -> file existed but YAML missing/invalid or parser unavailable
     """
-    cfg_path = repo_root / ".bc-linter.yml"
+
+    cfg_path = config_dir / ".bc-linter.yml"
     if not cfg_path.exists():
         return (default_config(), "default_missing")
 
@@ -159,12 +160,11 @@ def _ann_list(raw: Any) -> list[AnnotationSpec]:
     return (cfg, "parsed")
 
 
-def load_config(repo_root: pathlib.Path) -> Config:
-    """Loads configuration from `.bc-linter.yml` in the given repository root.
-
+def load_config(config_dir: pathlib.Path) -> Config:
+    """Loads configuration from `.bc-linter.yml` in the given directory.
     If the file does not exist or cannot be parsed, returns defaults.
     """
-    cfg, _ = load_config_with_status(repo_root)
+    cfg, _ = load_config_with_status(config_dir)
     return cfg
 
 

tools/stronghold/tests/api/test_config_loader.py

@@ -149,3 +149,23 @@ def test_warn_on_unknown_top_level_keys(tmp_path: pathlib.Path, capsys) -> None:
     assert status == "parsed"
     out = capsys.readouterr().out
     assert "::warning::BC-linter: Unknown keys in .bc-linter.yml: ['typpo']" in out
+
+
+def test_load_config_from_custom_directory(tmp_path: pathlib.Path) -> None:
+    config_dir = tmp_path / "subdir"
+    config_dir.mkdir()
+    yml = textwrap.dedent(
+        """
+        version: 1
+        include: ["src/**/*.py"]
+        """
+    )
+    (config_dir / ".bc-linter.yml").write_text(yml)
+
+    cfg_rel, status_rel = load_config_with_status(config_dir)
+    assert status_rel == "parsed"
+    assert cfg_rel.include == ["src/**/*.py"]
+
+    cfg_abs, status_abs = load_config_with_status(config_dir)
+    assert status_abs == "parsed"
+    assert cfg_abs.include == ["src/**/*.py"]