Crafter.Build/interfaces/Crafter.Build-Clang.cppm

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

export module Crafter.Build:Clang;
import std;
import :Shader;
import :Interface;
import :Implementation;
import :External;
import :Toolchain;
namespace fs = std::filesystem;

export namespace Crafter {
    struct BuildResult {
        std::string result;
        bool repack;
        std::unordered_set<std::string> libs;
        // Compile flags (typically -I include paths) the dep wants its
        // consumers to see — sourced from its external dependencies' include
        // dirs so headers a dep exposes in its public modules are reachable
        // when a consumer #includes them directly. Propagates transitively.
        std::unordered_set<std::string> publicCompileFlags;
    };

    struct Define {
        std::string name;
        std::string value;
    };

    // A browser-wasm codegen variant. The same wasm32 target is compiled more
    // than once, each pass adding `flags` to every translation unit, so newer
    // ISA features (relaxed SIMD today; threads, future SIMD revisions, … later)
    // can be adopted without dropping engines that lack them. Each non-empty
    // `label` emits an additional `outputName.<label>.wasm` alongside the
    // baseline `outputName.wasm`; `probes` names the runtime feature-detect
    // checks (see wasi-runtime/runtime.js's probe registry) that must all pass
    // for a browser to be served this variant. The first variant whose probes
    // pass wins; the baseline is the universal fallback.
    struct WasmVariant {
        std::string label;
        std::vector<std::string> flags;
        std::vector<std::string> probes;
    };

    enum class ConfigurationType {
        Executable,
        LibraryStatic,
        LibraryDynamic,
    };

    struct Test;

    struct TestRunner {
        // Command template the harness executes to run the test binary.
        // Local runners leave this empty; prefix runners (Cmd, Wine) set it to
        // a template like "wine {bin} {args}" or "qemu-aarch64 {bin} {args}".
        std::string exec;
        // Display name; also the cache key for the availability probe.
        std::string name;
        // Runs once per RunTests invocation (cached by `name`). Exit 0 = runner
        // is available; non-zero = skip every Test using this runner with a
        // "runner unavailable" message. Empty = always available (e.g., Local).
        std::string probe;

        bool IsLocal() const { return exec.empty(); }

        static TestRunner Local();
        // Prefix runner: wraps the local binary in `<command> {bin} {args}`.
        // Used for qemu-user, wasmtime, and similar single-binary wrappers.
        static TestRunner Cmd(std::string command);
        // Run a Windows .exe through Wine. Probes `wine` on PATH.
        static TestRunner Wine();
        // Parse a `<kind>[:<arg>]` spec used by CRAFTER_BUILD_RUNNER_<target>
        // and --runner=. Supported: "local", "cmd:<binary>". Returns nullopt
        // for an empty string; throws on a non-empty unrecognized spec.
        static std::optional<TestRunner> FromSpec(std::string_view spec);
        // Honor CRAFTER_BUILD_RUNNER_<target> (power-user override). Triple
        // dashes/dots become underscores so they're valid in env-var names.
        // Returns `fallback` when the env var is unset.
        static TestRunner FromEnv(std::string_view target, TestRunner fallback = Local());
        // Derive a runner from a Configuration's target triple + sysroot.
        // Returns Local() when target equals the host, Wine() for Windows
        // targets, `qemu-<arch>` (with QEMU_LD_PREFIX
        // set when cfg.sysroot is non-empty) for non-host -linux- triples,
        // `wasmtime` for wasm32-wasi/wasm64-wasi, and Local() as a last
        // resort. CRAFTER_BUILD_RUNNER_<target> still wins as an override
        // upstream of this — see FromEnv.
        static TestRunner ForTarget(const struct Configuration& cfg);
    };

    enum class TestOutcome { Pass, Fail, Crash, Timeout, Skipped };

    struct TestResult {
        std::string name;
        TestOutcome outcome = TestOutcome::Pass;
        std::int32_t exitCode = 0;
        std::int32_t signal = 0;
        std::chrono::milliseconds duration{0};
        std::string output;
    };

    // One lint diagnostic. Produced by LintContext::Report — or derived by
    // the driver when a transform rule's SetContent output differs from the
    // file on disk ("would reformat") — collected and printed compiler-style
    // by RunLint (Crafter.Build:Lint):
    //   <file>:<line>: warning: <message> [<rule>]
    struct LintFinding {
        fs::path file;
        std::size_t line = 0;   // 1-based; 0 = whole-file finding
        std::string rule;       // name of the rule that produced it
        std::string message;
    };

    // Parsed `// lint-disable-*` suppression directives for one file (see
    // LintContext::Suppressed). Line keys are 1-based and refer to the line a
    // next-line directive TARGETS (the line after the comment).
    struct LintSuppressions {
        bool fileAll = false;
        std::unordered_set<std::string> fileRules;
        std::unordered_set<std::size_t> lineAll;
        std::unordered_map<std::size_t, std::unordered_set<std::string>> lineRules;
    };

    // Lexical class of a LintToken, mirroring clang's token kinds one-to-one.
    enum class LintTokenKind {
        Punctuation,
        Keyword,
        Identifier,
        Literal,   // string, raw string, character, integer, floating literal
        Comment,   // // ... or /* ... */
    };

    // One token from LintContext::Tokens(). `offset`/`length` are byte offsets
    // into LintContext::content and stay valid until the next SetContent.
    //
    // A raw string literal or a block comment is ONE token and may span lines,
    // which is exactly what the hand-rolled scanners could not represent. The
    // stream also covers text inside preprocessor branches that are inactive
    // for the host — clang_tokenize lexes, it does not evaluate #if — so token
    // rules see every platform's code, not just the one being built.
    struct LintToken {
        LintTokenKind kind = LintTokenKind::Punctuation;
        std::size_t offset = 0;
        std::size_t length = 0;
        std::size_t line = 0;    // 1-based, of the token's first byte
        std::size_t column = 0;  // 1-based, of the token's first byte
    };

    // What a LintDecl declares.
    enum class LintDeclKind {
        Namespace,
        Class,
        Struct,
        Union,
        Enum,
        EnumConstant,
        TypeAlias,
        Function,
        Method,
        Constructor,
        Destructor,
        Field,
        Variable,   // local or namespace-scope variable
        Parameter,
        Other,
    };

    inline constexpr std::size_t LintNoParent = static_cast<std::size_t>(-1);

    // One declaration from LintContext::Decls(), for declarations written in
    // the file under lint (never ones pulled in from a header or module).
    //
    // The vector is flattened depth-first with parents before children, and
    // `parent` indexes back into it — that is how a rule asks "is this at
    // namespace scope, or inside a function?" without re-deriving a brace
    // stack from the text.
    struct LintDecl {
        LintDeclKind kind = LintDeclKind::Other;
        std::string name;   // unqualified spelling; empty when anonymous
        std::string type;   // clang's resolved spelling: "char *", "std::int32_t"
        std::size_t line = 0;
        std::size_t column = 0;
        std::size_t nameOffset = 0;  // byte offset of the declared name
        std::size_t begin = 0;  // byte offsets of the whole declaration, for
        std::size_t end = 0;    // marking a region a transform must not touch
        // For the FIRST declarator of a statement, `begin` is the start of the
        // shared type and so precedes `nameOffset`. For a continuation
        // declarator — the `b` of `int* a, b;` — the extent starts at the name,
        // so begin == nameOffset. That is how a multi-declarator statement is
        // recognised without re-parsing the text, and each declarator's `type`
        // is its OWN resolved type: `int *` for a, plain `int` for b.
        std::size_t parent = LintNoParent;
        bool isDefinition = false;
        bool isStatic = false;
        bool isConstexpr = false;
        bool isScopedEnum = false;  // `enum class` rather than plain `enum`
        // ---- foreign-API boundary ----
        // Set when this declaration's spelling is dictated by somebody else's
        // header, so the type-modernising rules must leave its bytes alone.
        // Replaces the hand-maintained substring denylists, which could only
        // ever grow: a new external library needs no new entry here.
        // ---- constness ----
        // The declared type is const-qualified.
        bool isConst = false;
        // A scalar: integer, floating, bool, enum or pointer. For these,
        // "is it ever written" is decidable from assignments, ++/--, address-of
        // and reference bindings alone — there are no member calls that could
        // mutate it — so isMutated is exact rather than a guess.
        bool isScalar = false;
        // Written to somewhere in this file: assigned, incremented, had its
        // address taken, or bound to a non-const reference. Only meaningful
        // for a declaration whose uses are all in this file, so a local rather
        // than something with external linkage.
        bool isMutated = false;
        // The initialiser is a constant expression, as decided by clang's own
        // constant evaluator rather than by inspecting its tokens. Only set for
        // Variable and Field.
        bool isConstantInitialised = false;
        // Method declared const. Only set for Method.
        bool isConstMethod = false;
        // Method declared static. Only set for Method.
        bool isStaticMethod = false;
        // The binding of a range-for: `for (T x : range)`. A loop binding is
        // not a variable a reader thinks of as assignable, so constness advice
        // about it is noise.
        bool isLoopVariable = false;
        bool isExternC = false;    // declared with C language linkage
        bool isForeignApi = false; // its type or its body binds to an entity
                                   // declared outside the project root
    };

    // Per-file view handed to each LintRule's check callback. Every member
    // function is out-of-line (defined in Crafter.Build:Lint's implementation
    // unit) because rule lambdas execute from the user's project.so and
    // resolve against the running executable: clang does not emit
    // module-attached in-class inline bodies into consumers (see ArgQuery
    // below).
    struct LintContext {
        fs::path file;                        // absolute path of the file under lint
        std::string content;                  // whole file as read from disk
        std::vector<std::string_view> lines;  // views into `content`, one per line, no '\n'

        std::string Extension() const;              // ".cppm", ".cpp", ".h", ...
        std::string_view Line(std::size_t n) const; // 1-based; empty if out of range
        // `content` with comments and string/char literal bodies blanked to
        // spaces, newlines preserved — offsets and line numbers stay valid.
        // Built from Tokens() on first call, cached per file, so raw strings,
        // escapes, encoding prefixes and literals like '"' all come out right.
        // A raw string is reduced to R"…" with the body and the delimiter
        // scaffolding blanked, leaving exactly two quote characters.
        //
        // Convenient for a quick scan, but Tokens() is the better tool for
        // anything structural: this view cannot tell an identifier from a
        // keyword, and it has already thrown away where the literals were.
        const std::string& CommentStripped();
        // Record a finding at `line` (1-based; pass 0 for a whole-file finding).
        void Report(std::size_t line, std::string message);
        // Replace the file's content. Makes this rule a *transform*:
        // `crafter-build format` writes the result back to disk; `lint`
        // derives would-reformat findings from it (dry — never writes).
        // `lines` is re-split and CommentStripped() re-derives on next call;
        // string_views taken before this call are invalidated. Recommended
        // pattern: build the new string, call SetContent once at the end. Do
        // not assign `content` directly — that bypasses the re-split. May be
        // combined with Report() in the same rule.
        void SetContent(std::string newContent);
        // True when `rule` is suppressed at `line` (1-based; 0 = whole-file,
        // which only file-level directives cover) by a suppression comment:
        //   // lint-disable-next-line [rules...]   applies to the following line
        //   // lint-disable-file [rules...]        applies to the whole file
        // Rule names are space- or comma-separated; none = all rules. The
        // driver already filters Report()
        // findings and reverts line-preserving transform edits on suppressed
        // lines; a transform that MERGES or SPLITS lines must consult this
        // itself for every line its edit touches (the driver cannot map lines
        // across a count-changing rewrite). Parsed lazily from the raw lines;
        // re-parsed after SetContent.
        bool Suppressed(std::string_view rule, std::size_t line);

        // The file lexed by clang, in source order. Built on first call, cached
        // per file, re-lexed after SetContent. Empty for extensions that are
        // not C or C++ (shaders): lexing GLSL as C++ would produce nonsense.
        //
        // Prefer this to scanning characters. It is the only view that gets
        // raw strings, line splices, digraphs and nested quoting right, and
        // offsets index straight into `content`, so a transform can find in
        // the token stream and edit in place.
        std::span<const LintToken> Tokens();
        // The token's own bytes: content.substr(tok.offset, tok.length).
        std::string_view TokenText(const LintToken& token) const;
        // Tokens whose FIRST byte is on `line` (1-based). A token that starts
        // earlier and spans into `line` — a raw string, a block comment — is
        // not included; ask Tokens() directly when that matters.
        std::span<const LintToken> TokensOnLine(std::size_t line);
        // True when a comment token starts on `line`. Replaces `Line(n).contains("//")`,
        // which false-positives on a `//` inside a string literal.
        bool LineHasComment(std::size_t line);
        // True when `line` (1-based) is touched by a token that spans more
        // than one line — a raw string or a block comment. A transform that
        // joins, splits or rewrites such a line changes what is inside that
        // token, so this is the guard to consult before reflowing anything.
        // Replaces `Line(n).contains("R\"")`, which both misses raw strings
        // opened on an earlier line and fires on the characters R" appearing
        // inside an ordinary literal.
        bool LineHasMultiLineToken(std::size_t line);

        // Declarations written in this file, flattened depth-first with
        // parents before children (see LintDecl). Empty when the AST is not
        // available — check AstAvailable() first, and do not read an empty
        // result as "this file declares nothing".
        //
        // Requires the module PCMs, unlike Tokens(): a module unit's
        // `import std;` cannot resolve without them, and clang treats that as
        // fatal rather than recovering. RunLint builds them on demand for
        // rules registered through AddAstLintRule and fails the run if it
        // cannot, so a semantic rule never silently reports clean.
        //
        // One further asymmetry worth knowing: an AST is ONE configuration's
        // slice. Declarations inside a preprocessor branch that is inactive
        // for the host are absent here, though Tokens() still sees them. Rules
        // that must cover every platform belong on tokens.
        std::span<const LintDecl> Decls();
        bool AstAvailable();
        // Why AstAvailable() is false — a missing PCM, a parse error, a file
        // that is not a translation unit. Empty when the AST is available.
        std::string_view AstUnavailableReason();

        // Driver wiring — set by RunLint before each check call. Not for rules.
        std::string activeRule;
        std::vector<LintFinding>* sink = nullptr;
        std::optional<std::string> commentStrippedCache;
        std::optional<LintSuppressions> suppressionsCache;
        std::optional<std::vector<LintToken>> tokenCache;
        // Per-line flag, 0-based, for LineHasMultiLineToken. Derived from
        // tokenCache and invalidated with it.
        std::optional<std::vector<bool>> spannedLineCache;
        // Flags this file parses with, from GetCompileCommand of the
        // Configuration that owns it. Empty disables Decls().
        std::string compileCommand;
        // Declarations resolving outside this are foreign API (LintDecl).
        fs::path projectRoot;
        std::optional<std::vector<LintDecl>> declCache;
        std::string astReason;
    };

    // A named lint rule: `check` runs once per (rule, file) over the project's
    // own sources. Rules self-filter by ctx.Extension() / ctx.file. A rule
    // that calls ctx.SetContent is a transform — defined once, it both gates
    // `crafter-build lint` and fixes under `crafter-build format`.
    struct LintRule {
        std::string name;
        std::function<void(LintContext&)> check;
        // Registered via AddAstLintRule: this rule reads Decls(), so the run
        // has to produce the module PCMs first, and must fail rather than let
        // the rule quietly find nothing.
        bool needsAst = false;
    };

    // The host target triple: what the resolved toolchain's clang++ prints
    // for -print-target-triple (see GetToolchain). Used as the default for
    // Configuration::target so projects don't have to hardcode it for the
    // no-cross-compile case. Returns "" when no compiler could be resolved;
    // those projects still need an explicit cfg.target, and the first build
    // step reports the missing compiler.
    std::string HostTarget();
    // Target equality that ignores the vendor field: x86_64-pc-linux-gnu,
    // x86_64-unknown-linux-gnu and x86_64-linux-gnu are one target as far as
    // "does this test run on this host" goes, and which spelling a clang
    // reports depends on how it was built. The strings themselves are never
    // rewritten: clang rejects a PCM whose triple string differs from the
    // importing unit's, so what the user wrote is what the compiler sees.
    std::string NormalizeTarget(std::string_view triple);
    bool SameTarget(std::string_view a, std::string_view b);

    struct Configuration {
        fs::path path;
        std::string outputName;
        std::string name;
        std::string march = "native";
        std::string mtune = "native";
        std::string target = HostTarget();
        std::string sysroot;
        bool debug = false;
        ConfigurationType type = ConfigurationType::Executable;
        std::vector<std::unique_ptr<Module>> interfaces;
        std::vector<Implementation> implementations;
        std::vector<fs::path> cFiles;
        std::vector<fs::path> cuda;
        std::vector<Configuration*> dependencies;
        std::vector<fs::path> files;
        // Build-time-only source files this configuration exposes to its own
        // and its consumers' shader compiles as glslang #include search
        // paths. Each entry's parent directory (or the entry itself, if it's
        // a directory) is added to the includer for every shader compiled in
        // this configuration and in any configuration that transitively
        // depends on it. Files are NOT copied — they're read in place from
        // the dep's source tree, like C++ -I include dirs.
        std::vector<fs::path> buildFiles;
        std::vector<Define> defines;
        std::vector<Shader> shaders;
        // Source assets compressed via Crafter.Asset's SaveCompressed →
        // .ctex/.cmesh in this configuration's bin dir.
        //
        // Each entry is either:
        //   - A single .png/.obj file. Output lands flat in the bin dir:
        //     bin/<filename>.ctex or bin/<filename>.cmesh.
        //   - A directory. The build recurses; .png/.obj are compressed
        //     with the relative tree mirrored under bin/<dirname>/, and
        //     every other file in the tree is copied through unchanged.
        //     Lets mod/map trees (mod.json + cannon/base.obj +
        //     cannon/color.png) keep their nested layout so JSON paths
        //     like "cannon/base.cmesh" resolve at runtime.
        //
        // Crafter.Asset must be reachable through cfg.dependencies (the
        // build engine links its library API into crafter-build via a
        // self-host pass). Forwarded to a consuming executable's bin dir
        // alongside .spv shaders and cfg.files entries.
        std::vector<fs::path> assets;
        std::vector<ExternalDependency> externalDependencies;
        std::vector<std::string> compileFlags;
        std::vector<std::string> linkFlags;
        // Browser-wasm feature-detected variants. Empty (the default) builds a
        // single outputName.wasm with the baseline wasm flag set. Non-empty
        // builds the baseline plus one outputName.<label>.wasm per entry, each
        // recompiling the whole build graph with that entry's `flags`;
        // EnableWasiBrowserRuntime emits a variants.json manifest the shipped
        // runtime.js uses to pick the right variant per browser. Populate via
        // EnableWasiRelaxedSimdVariant for the common case.
        std::vector<WasmVariant> wasmVariants;
        // Extra wasm codegen flags injected into this configuration's compile +
        // link command for the active variant pass. Set across the whole build
        // graph by the variant driver inside Build(); part of VariantId so each
        // variant's objects/PCMs land in their own build+bin dir and never
        // clobber the baseline's. Not for direct project use — declare
        // wasmVariants instead.
        std::vector<std::string> wasmVariantFlags;
        // The project args ApplyStandardArgs did not interpret — i.e. the
        // project's own flags, whose effect on the build the framework cannot
        // see. Hashed into VariantId because such a flag typically decides what
        // gets compiled or bundled (`--no-webgpu` dropping entries from
        // cfg.files, say), and without it both flag settings share one bin dir
        // and interleave their outputs there. Populated by ApplyStandardArgs;
        // the args it does recognise are excluded, since their effect already
        // shows up in target/march/mtune/debug/sysroot/type.
        std::vector<std::string> projectArgs;
        std::vector<Test> tests;
        // Lint rules for `crafter-build lint`. Populate via AddLintRule.
        std::vector<LintRule> lintRules;
        void GetInterfacesAndImplementations(std::span<fs::path> interfaces, std::span<fs::path> implementations);
        // Retry the `import X;` names GetInterfacesAndImplementations could not
        // place, against the dependency DAG as it stands now. Sources are
        // scanned when they're declared, but `dependencies` is often assigned
        // afterwards (AddTest does exactly this), and an import that resolved to
        // nothing leaves no staleness edge — so a dependency's interface could
        // change and this Configuration's objects would be silently reused
        // against the new layout. Build() calls this before checking mtimes;
        // calling it again is harmless.
        void ResolvePendingImports();
        // Declare a test. Sources default to `tests/<name>/main.cpp` resolved
        // against this Configuration's path; target/march/mtune/sysroot/debug
        // are inherited from this Configuration so cross-arch projects don't
        // have to re-specify. Returns a builder for chaining defines, deps,
        // etc. Defined in Crafter.Build:Test.
        struct TestBuilder AddTest(std::string_view name);
        // Same as AddTest, but compiles the parent's `interfaces` directly
        // into this test's Configuration (rather than going through a dep).
        // Use when the test must rebuild those interfaces with its own
        // compile flags — typically per-march SIMD codegen.
        struct TestBuilder AddTest(std::string_view name, std::span<fs::path> interfaces);
        // Math-style fan-out: one Test per MarchTier, all sharing the same
        // `tests/<name>/main.cpp` source and the same interface set, each
        // compiled with the tier's `-march`/`-mtune`. Test names are
        // `<name>-<march>`.
        void AddMarchVariants(std::string_view name, std::span<fs::path> interfaces, std::span<const struct MarchTier> tiers);
        // Register a lint rule for `crafter-build lint` / `format`. Rules
        // registered on any Configuration whose path lies inside the project
        // root are collected (deduplicated by name, root-first) — attach them
        // to the lib or the exe config, either works. Rules that call
        // ctx.SetContent are transforms (see LintContext::SetContent).
        // Defined in Crafter.Build:Lint.
        void AddLintRule(std::string name, std::function<void(LintContext&)> check);
        // Same, for a rule that reads LintContext::Decls(). Declared
        // separately rather than as a flag on AddLintRule so existing
        // registrations keep compiling. Such a rule makes the run build the
        // module PCMs if they are missing, and a file whose AST could not be
        // produced becomes an error instead of a silent pass. Prefer
        // report-only: a transform running after the first one forces a
        // re-parse of everything it changed.
        void AddAstLintRule(std::string name, std::function<void(LintContext&)> check);
        // Suffix that uniquely identifies this Configuration's compile state.
        // target+march+mtune are spelled out for readability; the rest
        // (type, debug, sysroot, defines, compileFlags, the toolchain)
        // collapse into a short hash so two Configurations sharing a path but
        // with different compile state can't clobber each other's outputs.
        std::string VariantId() const { return VariantId(GetToolchain()); }
        // The variant under an explicit toolchain; VariantId() is this for
        // the running one. The compiler is compile state like any flag: a
        // PCM can only be read by the clang release that wrote it, and
        // staleness is decided by mtimes, which a compiler update does not
        // touch. Before the toolchain was hashed, a project built with clang
        // 22 kept its PCMs when crafter-build moved to clang 23, and the
        // first edit afterwards failed with "module file ... uses an older
        // format that is no longer supported" until the project was cleaned.
        // Keyed here, an update starts an empty directory and rebuilds; the
        // old one stays until `crafter-build clean`.
        std::string VariantId(const Toolchain& toolchain) const {
            std::string compileKey;
            compileKey += std::to_string(static_cast<std::int32_t>(type));
            compileKey += '|';
            compileKey += debug ? '1' : '0';
            compileKey += '|';
            compileKey += sysroot;
            for (const Define& d : defines) {
                compileKey += "|D:";
                compileKey += d.name;
                compileKey += '=';
                compileKey += d.value;
            }
            for (const std::string& f : compileFlags) {
                compileKey += "|F:";
                compileKey += f;
            }
            // Wasm variant codegen flags perturb every object/PCM, so they must
            // key into a distinct build+bin dir from the baseline (and from
            // each other) to avoid clobbering.
            for (const std::string& f : wasmVariantFlags) {
                compileKey += "|W:";
                compileKey += f;
            }
            // Sorted by ApplyStandardArgs, so flag order on the command line
            // doesn't split the cache.
            for (const std::string& a : projectArgs) {
                compileKey += "|A:";
                compileKey += a;
            }
            compileKey += "|T:";
            compileKey += toolchain.Key();
            std::size_t configHash = std::hash<std::string>{}(compileKey);
            return std::format("{}-{}-{}-{}-{:08x}", name, target, march, mtune, configHash);
        }
        fs::path BuildDir() const { return path / "build" / VariantId(); }
        fs::path BinDir() const { return path / "bin" / VariantId(); }
        fs::path PcmDir() const {
            return type == ConfigurationType::Executable ? BuildDir() : BinDir();
        }
    };

    struct Test {
        Configuration config;
        TestRunner runner;
        std::chrono::seconds timeout{60};
        std::vector<std::string> args;
        // Declarative preconditions. Each entry is "tool:<name>",
        // "file:<path>", or "env:<VAR>". Evaluated before the test runs; any
        // unmet require turns the test into a Skip with a derived reason.
        // Also doubles as the "I know this runner might not be here" opt-in:
        // when the test's derived runner needs a tool (e.g. qemu-aarch64,
        // wasmtime, wine) and the matching tool: entry isn't present, an
        // unavailable runner becomes a Fail instead of a silent Skip — the
        // dependency has to be declared to be allowed to be missing.
        std::vector<std::string> requires_;
    };

    // Directory holding the std module PCM for this Configuration. Keyed on
    // target+march because a BMI is only loadable by a TU with matching target
    // features, and suffixed with the wasm variant flags for the same reason.
    fs::path StdPcmDir(const Configuration& config);

    // Where Build leaves this Configuration's linked artifact: the executable
    // (with the target's suffix), `lib<name>.a` / `<name>.lib`, or the shared
    // library / DLL. The one rule every "is the consumer older than its
    // dependency" check reads, so a staleness test and the link step can't
    // disagree about the file name.
    fs::path ExpectedOutput(const Configuration& config);

    // The clang invocation every C++ translation unit in this Configuration is
    // compiled with, before anything that depends on work having happened
    // (dependency public flags, external dependency flags — Build appends
    // those itself). A pure function of the Configuration.
    //
    // Anything that needs to PARSE this project's sources rather than build
    // them — the linter's AST layer, a future compile_commands.json — must go
    // through this instead of assembling its own flags. A precompiled module
    // is rejected outright by a TU whose target features differ from the one
    // that wrote it, so approximately-right flags fail hard rather than
    // degrade: omitting -march=native alone produces hundreds of "compiled
    // with the target feature '+avx512bw' but the current translation unit is
    // not" errors and no usable parse.
    struct CompileCommand {
        std::string command;          // full C++ compile prefix, shell-ready
        // Sub-sets Build also needs on its own: the .c compile path takes the
        // includes, defines and user flags but not the module-only bits.
        std::string includeFlags;
        std::string defineFlags;
        std::string userFlags;
        std::string ltoCompileFlags;
        std::string ltoLinkFlags;
        // -I flags from external dependencies' declared includeDirs, for this
        // configuration and its dependencies. Deliberately NOT folded into
        // `command`: Build appends the authoritative set from the external build
        // results instead. Exposed for callers that only PARSE sources and so
        // cannot wait for a build to tell them where the headers are.
        std::string externalIncludeFlags;
        // ThinLTO is on: objects hold bitcode, so archiving needs llvm-ar.
        bool useLto = false;
        fs::path stdPcmDir;
        fs::path pcmDir;
    };
    CompileCommand GetCompileCommand(const Configuration& config);

    BuildResult Build(Configuration& config, std::unordered_map<fs::path, std::shared_future<BuildResult>>& depResults, std::mutex& depMutex);

    // Takes main's argv verbatim so the CLI entry point is a one-liner;
    // the shape is inherited from the language, not chosen here.
    // lint-disable-next-line no-char-pointer
    std::int32_t Run(std::int32_t argc, char** argv);

    // Delete the bin/ and build/ trees beside `projectFile`, returning the paths
    // that existed and were removed. Backs `crafter-build clean`.
    //
    // Deliberately does not load the project: cleaning is most often reached
    // when something is already wrong, and a clean that first needs project.cpp
    // to compile (and its git dependencies to be present) is useless exactly
    // then. That means variant directories are not enumerated — the whole tree
    // goes, which is what the by-hand `rm -rf bin build` did anyway.
    std::vector<fs::path> CleanProject(const fs::path& projectFile);

    // Add a small index.html + runtime.js pair next to the .wasm output so the
    // build can be loaded directly in a browser (just `serve` the bin dir and
    // open it). Opt-in: WASI builds destined for wasmtime/wasmer don't need
    // this and shouldn't carry the extra files. Call from project.cpp after
    // outputName is set; index.html is generated against the current
    // outputName so renaming the binary later requires another call.
    void EnableWasiBrowserRuntime(Configuration& cfg);

    // Register the relaxed-SIMD codegen variant on cfg. Builds an additional
    // outputName.relaxed-simd.wasm compiled with -mrelaxed-simd (FMA,
    // dot-product, relaxed swizzle/laneselect, …); the shipped runtime serves
    // it only to engines that report relaxed-SIMD support (Chrome 114+, Firefox
    // 120+) and falls back to the baseline outputName.wasm everywhere else
    // (e.g. Safari, which still gates relaxed SIMD behind a flag as of mid
    // 2026). Idempotent. Call before EnableWasiBrowserRuntime so the emitted
    // variants.json manifest includes it. A no-op for non-wasm targets at build
    // time (no wasm is produced), but harmless to declare unconditionally.
    void EnableWasiRelaxedSimdVariant(Configuration& cfg);

    // View over the project's args with simple query helpers. Has(flag) for
    // boolean switches; Get(prefix) for valued options (e.g. Get("--prefix=")
    // returns the substring after the equals). Definitions are out-of-line so
    // project.so resolves them from the executable: clang does not emit
    // module-attached in-class inline bodies into consumers.
    struct ArgQuery {
        std::span<const std::string_view> args;
        bool Has(std::string_view flag) const;
        std::optional<std::string> Get(std::string_view prefix) const;
    };

    // Apply the framework's standard CLI args + env vars onto cfg:
    //   --debug             cfg.debug = true
    //   --target=<triple>   cfg.target = <triple>
    //   --march=<value>     cfg.march = <value>
    //   --mtune=<value>     cfg.mtune = <value>
    //   --lib               cfg.type promoted Executable → LibraryStatic
    //   --shared            cfg.type promoted LibraryStatic → LibraryDynamic
    // Promotions chain in priority order so `--lib --shared` lands on
    // LibraryDynamic regardless of arg order; each is a no-op when the
    // baseline doesn't match (e.g. --shared on an Executable, or --lib on a
    // pre-set library).
    //   $CRAFTER_BUILD_MARCH / $CRAFTER_BUILD_MTUNE seed march/mtune.
    // Env applies first, then args, so CLI wins over env wins over caller's
    // pre-set defaults. Returns an ArgQuery over the same span so projects
    // can query their own flags (`--timing`, ...) without re-rolling the
    // for-arg-in-args loop.
    ArgQuery ApplyStandardArgs(Configuration& cfg, std::span<const std::string_view> args);
}