Crafter.Build/interfaces/Crafter.Build-Lint.cppm

// SPDX-License-Identifier: LGPL-3.0-only
// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®

module;
#include "Crafter.Build-Api.h"
export module Crafter.Build:Lint;
import std;
import :Clang;

export namespace Crafter {
    enum class LintMode {
        // `lint`: diagnose only; transform output becomes would-reformat
        // findings. Never writes. The default.
        Report,
        // `format --check`: dry run; record the files that would change.
        Check,
        // `format`: rewrite changed files in place.
        Apply,
    };

    struct RunLintOptions {
        // Rule-name globs ('*', '?'); empty = every registered rule.
        std::vector<std::string> globs;
        // Enumerate matching rule names without running them.
        bool listOnly = false;
        LintMode mode = LintMode::Report;
        // Skip rules registered with AddAstLintRule instead of building the
        // module PCMs they need. The escape hatch for a fresh clone where the
        // token-based rules are wanted immediately; the run then exits normally
        // rather than erroring, so it must be asked for explicitly.
        bool noAst = false;
        // Absolute path of the loaded project.cpp. It is linted too, and its
        // parent directory is the project root that decides which dependency
        // Configurations contribute rules/files (GitProject / cache-dir deps
        // are foreign code and skipped). Empty => fall back to cfg.path.
        std::filesystem::path projectFile;
    };

    struct LintSummary {
        std::vector<LintFinding> findings;  // sorted by (file, line); filled in every mode
        // Apply: files rewritten on disk. Report/Check: files a transform
        // would change. The `format` verb's exit code keys off this in Check
        // mode; formatting files in Apply mode is success.
        std::vector<std::filesystem::path> changedFiles;
        std::size_t filesLinted = 0;
        std::size_t rulesRun = 0;           // rules remaining after glob filter
        // Rule exceptions, write failures, and infrastructure failures such as
        // libclang not loading. Counted in Clean() so a run that could not do
        // its job never looks like a run that found nothing.
        std::size_t errors = 0;
        bool noRulesDefined = false;        // project registered no rules at all
        // Host-side only (like TestSummary::AllPassed), safe as in-class inline.
        bool Clean() const { return findings.empty() && !noRulesDefined && errors == 0; }
    };

    // Run the project's lint rules over its own sources: module interfaces
    // (+ partitions), implementations, cFiles, cuda, shaders, declared tests'
    // sources, and project.cpp itself — for the root Configuration plus every
    // transitive dependency whose path lies inside the project root. Rules
    // run in registration order per file, each seeing the previous rule's
    // transform output; a rule that throws is reverted and surfaced as a
    // finding + error. Only Apply mode writes to disk, and only files whose
    // final content differs from the original. Prints per-mode output:
    // findings compiler-style (Report), would-change paths (Check), or
    // formatted paths (Apply), plus a summary line.
    CRAFTER_API LintSummary RunLint(Configuration& projectCfg, const RunLintOptions& opts);
}