[bc-linter] Add BC Linter configuration support (#7016)

This PR makes bc-linter configurable (via .bc-linter.yml, [see the
spec](https://github.com/pytorch/test-infra/blob/e73b14f75422a0fb38212c2d465f9a86fb20a11c/tools/stronghold/docs/bc_linter_config.md)).


#### Changes:

- added api.config with yaml loader
- config status is logged (and loaded config is printed with --verbose)
- simplified default excludes to [".", "./", "/./", "/."] (removed
pytorch-specific paths, added them back [via config
file](pytorch/pytorch#161319))
- for globs used pathspec (gitwildmatch)

#### Action + Dependencies

- added runtime deps file tools/stronghold/requirements.runtime.txt
(PyYAML, pathspec).
- composite action now installs runtime deps before build/run.

#### Tests

- Added tests for glob semantics, loader behaviors, defaults, scan
flags, annotations, and top‑level vs nested paths.


Backtesting [new config](pytorch/pytorch#161319)
against paths in PyTorch codebase:

```
- Total .py files: 13820
- Old allowed (a07e5d9 rules): 4926
- New allowed: 4926
- Diffs: 0 (perfect match)
```

Testing action end-to-end close to prod:
pytorch/pytorch#161325
see [this
run](https://github.com/pytorch/pytorch/actions/runs/17168177594/job/48713225885?pr=161325#step:2:6155),
correctly returns a single warning (job failure is expected).

Author: izaitsevfb

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

@@ -61,6 +61,7 @@ runs:
       shell: bash
       run: |
         set -eux
+        python3 -m pip install -r ../_test-infra/tools/stronghold/requirements.runtime.txt
         ../_test-infra/tools/stronghold/bin/build-check-api-compatibility
         ../_test-infra/tools/stronghold/bin/check-api-compatibility \
             --base-commit=${{ inputs.base_sha }} \

.github/workflows/bc-linter-tests.yml

@@ -0,0 +1,32 @@
+name: BC-Linter Tests
+
+on:
+  pull_request:
+    paths:
+      - .github/workflows/bc-linter-tests.yml
+      - tools/stronghold/**
+  push:
+    branches:
+      - main
+    paths:
+      - .github/workflows/bc-linter-tests.yml
+      - tools/stronghold/**
+
+defaults:
+  run:
+    working-directory: tools/stronghold/
+
+jobs:
+  bc-linter-tests:
+    name: BC-Linter Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.11'
+          cache: pip
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Run BC-Linter tests
+        run: python -m pytest tests/ -v

tools/stronghold/docs/bc_linter_config.md

@@ -0,0 +1,71 @@
+# BC Linter Configuration (beta)
+
+This document describes the configuration format for the Stronghold BC linter.
+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).
+- If the file is missing or empty, defaults are applied (see below).
+
+### Schema (YAML)
+```yml
+version: 1
+
+paths:
+  include:
+    - "**/*.py"         # globs of files to consider (default)
+  exclude:
+    - "**/.*/**"        # exclude hidden directories by default
+    - "**/.*"           # exclude hidden files by default
+
+scan:
+  functions: true        # check free functions and methods
+  classes: true          # check classes/dataclasses
+  public_only: true      # ignore names starting with "_" at any level
+
+annotations:
+  include:               # decorators that force‑include a symbol
+    - name: "bc_linter_include"  # matched by simple name or dotted suffix
+      propagate_to_members: false # for classes, include methods/inner classes
+  exclude:               # decorators that force‑exclude a symbol
+    - name: "bc_linter_skip"     # matched by simple name or dotted suffix
+      propagate_to_members: true  # for classes, exclude methods/inner classes
+
+excluded_violations: []  # e.g. ["ParameterRenamed", "FieldTypeChanged"]
+```
+
+### Behavior notes
+- Regardless of the config, ONLY `.py` files are considered.
+- Paths precedence: `annotations.exclude` > `annotations.include` > `paths`.
+  Annotations can override file include/exclude rules.
+- Name matching for annotations: A decorator matches if either its simple name
+  equals the configured `name` (e.g., `@bc_linter_skip`) or if its dotted
+  attribute ends with the configured `name` (e.g., `@proj.bc_linter_skip`).
+- `public_only`: When true, any symbol whose qualified name contains a component
+  that starts with `_` is ignored (e.g., `module._Internal.func`, `Class._m`).
+- Rule suppression: `excluded_violations` contains class names from
+  `api.violations` to omit from output (e.g., `FieldTypeChanged`).
+- Invariants not affected by config:
+  - Deleted methods of a deleted class are not double‑reported (only the class).
+  - Nested class deletions collapse to the outermost deleted class.
+  - Dataclass detection and field inference are unchanged.
+
+### Defaults
+If `.bc-linter.yml` is missing or empty, the following defaults apply:
+
+```
+version: 1
+paths:
+  include: ["**/*.py"]
+  exclude: [".*", ".*/**", ".*/**/*", "**/.*/**", "**/.*"]
+scan:
+  functions: true
+  classes: true
+  public_only: true
+annotations:
+  include: []
+  exclude: []
+excluded_violations: []
+```

tools/stronghold/requirements.runtime.txt

@@ -0,0 +1,2 @@
+PyYAML==6.0.2
+pathspec==0.12.1

tools/stronghold/requirements.txt

@@ -3,3 +3,5 @@ flake8==5.0.4
 mypy==0.990
 pip==23.3
 pytest==7.2.0
+PyYAML==6.0.2
+pathspec==0.12.1

tools/stronghold/src/api/__init__.py

@@ -22,6 +22,8 @@ class Parameters:
     variadic_kwargs: bool
     # The line where the function is defined.
     line: int
+    # Decorator names applied to this function/method (simple or dotted form).
+    decorators: Sequence[str] = ()
 
 
 @dataclasses.dataclass
@@ -62,6 +64,8 @@ class Class:
     fields: Sequence[Field]
     line: int
     dataclass: bool = False
+    # Decorator names applied to the class (simple or dotted form).
+    decorators: Sequence[str] = ()
 
 
 @dataclasses.dataclass

tools/stronghold/src/api/ast.py

@@ -80,11 +80,15 @@ def _function_def_to_parameters(node: ast.FunctionDef) -> api.Parameters:
         )
         for i, arg in enumerate(args.kwonlyargs)
     ]
+    dec_names = tuple(
+        n for n in (_decorator_to_name(d) for d in node.decorator_list) if n
+    )
     return api.Parameters(
         parameters=params,
         variadic_args=args.vararg is not None,
         variadic_kwargs=args.kwarg is not None,
         line=node.lineno,
+        decorators=dec_names,
     )
 
 
@@ -106,10 +110,11 @@ def visit_ClassDef(self, node: ast.ClassDef) -> None:
         # class name pushed onto a new context.
         if self._classes is not None:
             name = ".".join(self._context + [node.name])
+            dec_names = [
+                n for n in (_decorator_to_name(d) for d in node.decorator_list) if n
+            ]
             is_dataclass = any(
-                (isinstance(dec, ast.Name) and dec.id == "dataclass")
-                or (isinstance(dec, ast.Attribute) and dec.attr == "dataclass")
-                for dec in node.decorator_list
+                (n == "dataclass" or n.endswith(".dataclass")) for n in dec_names
             )
             fields: list[api.Field] = []
             for stmt in node.body:
@@ -180,7 +185,10 @@ def _is_field_func(f: ast.AST) -> bool:
                                 )
                             )
             self._classes[name] = api.Class(
-                fields=fields, line=node.lineno, dataclass=is_dataclass
+                fields=fields,
+                line=node.lineno,
+                dataclass=is_dataclass,
+                decorators=tuple(dec_names),
             )
 
         _ContextualNodeVisitor(
@@ -191,3 +199,39 @@ def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
         # Records this function.
         name = ".".join(self._context + [node.name])
         self._functions[name] = node
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        # Treat async functions similarly by normalizing to FunctionDef shape.
+        name = ".".join(self._context + [node.name])
+        fnode = ast.FunctionDef(
+            name=node.name,
+            args=node.args,
+            body=node.body,
+            decorator_list=node.decorator_list,
+            returns=node.returns,
+            type_comment=node.type_comment,
+        )
+        self._functions[name] = fnode
+
+
+def _decorator_to_name(expr: ast.AST) -> str:
+    """Extracts a dotted name for a decorator expression.
+    For calls like @dec(...), returns the callee name "dec".
+    For attributes like @pkg.mod.dec, returns "pkg.mod.dec".
+    For names like @dec, returns "dec".
+    """
+
+    def _attr_chain(a: ast.AST) -> str | None:
+        if isinstance(a, ast.Name):
+            return a.id
+        if isinstance(a, ast.Attribute):
+            left = _attr_chain(a.value)
+            if left is None:
+                return a.attr
+            return f"{left}.{a.attr}"
+        return None
+
+    if isinstance(expr, ast.Call):
+        expr = expr.func
+    name = _attr_chain(expr)
+    return name or ""

tools/stronghold/src/api/checker.py

@@ -1,11 +1,14 @@
 """Runs the API backward compatibility on the head commit."""
 
 import argparse
+import dataclasses
+import json
 import pathlib
 import subprocess
 import sys
 
 import api.compatibility
+import api.config
 import api.git
 import api.github
 
@@ -22,6 +25,13 @@ def run() -> None:
         help="Failures are suppressed"
         "(alternative to #suppress-api-compatibility-check commit message tag).",
     )
+    parser.add_argument(
+        "--verbose",
+        default=False,
+        required=False,
+        action="store_true",
+        help="Enable verbose output",
+    )
     args = parser.parse_args(sys.argv[1:])
 
     repo = api.git.Repository(pathlib.Path("."))
@@ -35,8 +45,21 @@ def run() -> None:
     repo.run(["fetch", "origin", args.base_commit], check=True)
     print("::endgroup::")
 
+    # Load config and optionally print when detected
+    cfg, cfg_status = api.config.load_config_with_status(repo.dir)
+    if cfg_status == "parsed":
+        # Explicitly log successful config discovery and parsing
+        print("BC-linter: Using .bc-linter.yml (parsed successfully)")
+        if args.verbose:
+            print("BC-linter: Parsed config:")
+            print(json.dumps(dataclasses.asdict(cfg), indent=2, sort_keys=True))
+    elif args.verbose:
+        # In verbose mode, also indicate fallback to defaults
+        reason = "missing" if cfg_status == "default_missing" else "invalid/malformed"
+        print(f"BC-linter: No usable config ({reason}); using defaults")
+
     violations = api.compatibility.check_range(
-        repo, head=args.head_commit, base=args.base_commit
+        repo, head=args.head_commit, base=args.base_commit, config=cfg
     )
     if len(violations) == 0:
         return