`ProjectChecker.scan_project()` documentation

[Brownies]

The doc is missing a positional argument source for scan_project() and running the example results in a TypeError: MyProjectChecker.scan_project() takes 2 positional arguments but 3 were given. Also, BaseChecker.report() doesn't accept str or even pathlib.Path types for the source argument. I did manage to work around this by instantiating a SourceFile. However, this seems somewhat cumbersome and feels like it might be a bug/missing feature instead of a documentation issue?

Here's what I came up with

from robocop.source_file import SourceFile

...

    def scan_project(self, source: SourceFile, config_manager: ConfigManager) -> None:
        files_count = 0
        for robot_file in config_manager.root.rglob("*.robot"):
            files_count += 1
            source_file = SourceFile(path=robot_file, config=config_manager.get_config_for_source_file(robot_file))
            self.report(self.project_checker, source=source_file)
        # files can be also parsed (with get_model) and checked here
        self.report(self.test_total_count, source=source, files=files_count)

[bhirsz]

This particular doc is definietely outdated - after recent changes in 7.0 regarding SourceFile addition.

That's the parent class:

class ProjectChecker(BaseChecker):
    def scan_project(
        self, project_source_file: SourceFile | VirtualSourceFile, config_manager: ConfigManager
    ) -> list[Diagnostic]:
        """
        Perform checks on the whole project.

        This method is called after other checks are finished. Define the main logic of the check here.
        Robocop will access ``self.issues`` list to retrieve list of issues found during the check. Issues are
        reported using ``self.report()`` method.
        """
        raise NotImplementedError

And here is example of our custom project checkers from our tests:

class MyProjectChecker(ProjectChecker):
    """Project checker."""

    project_checker: ProjectCheckerRule
    test_total_count: TestTotalCountRule

    def scan_project(self, project_source_file: VirtualSourceFile, config_manager: ConfigManager) -> None:
        files_count = 0
        for robot_file in config_manager.root.rglob("*.robot"):
            files_count += 1
            self.report(self.project_checker, source=SourceFile(robot_file, config=project_source_file.config))
        # files can be also parsed (with get_model) and checked here
        self.report(
            self.test_total_count,
            source=SourceFile(Path("Project-name"), project_source_file.config),
            files=files_count,
        )

You may see there is extra work around providing SourceFiles etc. It is good idea to simplify it.

It's how we call it:

        project_name = self.config_manager.root.name
        project_source_file = VirtualSourceFile(Path(project_name), self.config_manager.default_config)
        for checker in resolved_config.project_checkers:
            checker.issues = []
            checker.scan_project(project_source_file, self.config_manager)
            self.diagnostics.extend(
                [diagnostic for diagnostic in checker.issues if not (diagnostic.severity < config.linter.threshold)]
            )

So the project checker is called only once with virtual source file. Searching files is on the user, which is more complex but it allows you for more customization (for example you can create check that verifies directory structure). But in some cases it would be good to be able to either report issues 'on the project', not on the file (so the SourceFile is not needed).