chore: add pylint disable comments for CodeFlow warnings

Add pylint disable comments to suppress CodeFlow warnings that ruff
noqa comments cannot address (different linter codes):

- hookspecs.py: module-level 'pylint: disable=unused-argument' for
  pluggy hookspec placeholder parameters (14 warnings)
- _dispatch.py: 'pylint: disable=import-outside-toplevel' for circular
  dependency deferral (2 warnings)
- ai_commands.py: same for circular dependency deferral (1 warning)
- base_provider.py: same for optional rstr dependency (1 warning)
- main.py: 'pylint: disable=unused-import' for CLI command registration
  side-effect import (1 warning)
- sync_docs.py: 'pylint: disable=wrong-import-position' for sys.path-
  dependent import (1 warning)
- test_doc_sync.py: same for sys.path-dependent import (1 warning)

All 21 CodeFlow warnings addressed. ruff/mypy/pytest all pass.

Author: sunbos

.gitignore

@@ -81,3 +81,6 @@ node_modules/
 
 # mkdocs build output (deployed via GitHub Actions, not committed)
 site/
+
+# CodeFlow warning reports (local analysis artifacts, not for repo)
+codeflow-warnings*.md

scripts/sync_docs.py

@@ -17,7 +17,9 @@
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from _fact_extractors import collect_all_facts  # requires sys.path setup above
+# Import after sys.path manipulation — cannot be at module top.
+# pylint: disable=wrong-import-position
+from _fact_extractors import collect_all_facts
 
 ROOT = Path(__file__).resolve().parent.parent
 

src/sqlseed/cli/ai_commands.py

@@ -257,6 +257,8 @@ def _handle_ai_verification_streaming(
 
 
 def _write_ai_output(output: str, db_path: str, result: Any) -> None:
+    # Import inside function to avoid circular dependency.
+    # pylint: disable=import-outside-toplevel
     from sqlseed.cli.main import _sanitize_table_config  # noqa: PLC0415
 
     _sanitize_table_config(result)

src/sqlseed/cli/main.py

@@ -369,6 +369,7 @@ def main() -> None:
 # (ai_commands imports `cli` from this module at module level).
 # NOTE: Do NOT use contextlib.suppress here — it silently swallows
 # the circular ImportError that occurs when main.py is loaded first.
+# pylint: disable=unused-import
 try:  # noqa: SIM105
     import sqlseed.cli.ai_commands  # noqa: F401
 except ImportError:

src/sqlseed/generators/_dispatch.py

@@ -50,6 +50,8 @@ def generate(self, type_name: str, **params: Any) -> Any:
 
 def verify_dispatch_sync() -> None:
     """Verify that GENERATOR_MAP entries match actual methods on BaseProvider."""
+    # Imports inside function to avoid circular dependency at module load time.
+    # pylint: disable=import-outside-toplevel
     from sqlseed.generators.base_provider import BaseProvider  # noqa: PLC0415
 
     for gen_name, method_name in GeneratorDispatchMixin._GENERATOR_MAP.items():

src/sqlseed/generators/base_provider.py

@@ -351,6 +351,8 @@ def _get_array_count(self) -> int:
     def _gen_pattern(self, *, pattern: str | None = None, regex: str | None = None) -> str:
         effective = pattern or regex or ""
         try:
+            # Optional dependency — import inside function to defer ImportError.
+            # pylint: disable=import-outside-toplevel
             import rstr as _rstr  # noqa: PLC0415
         except ImportError as err:
             raise ImportError(

src/sqlseed/plugins/hookspecs.py

@@ -4,6 +4,10 @@
 
 import pluggy
 
+# pluggy hookspec methods use placeholder parameters that are intentionally
+# unused — they define the hook signature for plugin implementers.
+# pylint: disable=unused-argument
+
 hookspec = pluggy.HookspecMarker("sqlseed")
 hookimpl = pluggy.HookimplMarker("sqlseed")
 

tests/test_doc_sync.py

@@ -20,6 +20,8 @@
 # Import shared fact extractors from scripts/ to avoid code duplication.
 # This ensures tests validate the same logic that sync_docs.py uses.
 sys.path.insert(0, str(ROOT / "scripts"))
+# Import after sys.path manipulation — cannot be at module top.
+# pylint: disable=wrong-import-position
 from _fact_extractors import (  # noqa: E402
     get_enum_name_patterns,
     get_exact_match_rules,