Detectors¶

def detect(
    self,
    context: AnalysisContext,
    config: BashStrictModeConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashStrictModeConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    if "set -euo pipefail" not in context.code:
        return [
            self.build_violation(
                config,
                contains="set -euo pipefail",
                suggestion="Add 'set -euo pipefail' near the top of the script.",
            ),
        ]
    return []

def detect(
    self,
    context: AnalysisContext,
    config: BashQuoteVariablesConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashQuoteVariablesConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = [
        self.build_violation(
            config,
            contains="quote",
            location=Location(line=idx, column=1),
            suggestion='Quote variable expansions like "$var".',
        )
        for idx, line in enumerate(context.code.splitlines(), start=1)
        if re.search(r"\$\w+", line) and '"' not in line
    ]
    return violations

def detect(
    self,
    context: AnalysisContext,
    config: BashEvalUsageConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashEvalUsageConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = [
        self.build_violation(
            config,
            contains="eval",
            location=Location(line=idx, column=line.find("eval") + 1),
            suggestion="Avoid eval; use arrays or case statements instead.",
        )
        for idx, line in enumerate(context.code.splitlines(), start=1)
        if "eval" in line
    ]
    return violations

def detect(
    self,
    context: AnalysisContext,
    config: BashDoubleBracketsConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashDoubleBracketsConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = [
        self.build_violation(
            config,
            contains="[",
            location=Location(line=idx, column=1),
            suggestion="Prefer [[ ]] over [ ] for conditionals.",
        )
        for idx, line in enumerate(context.code.splitlines(), start=1)
        if re.search(r"\[[^\\[]", line) and "[[" not in line
    ]
    return violations

def detect(
    self,
    context: AnalysisContext,
    config: BashCommandSubstitutionConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashCommandSubstitutionConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = [
        self.build_violation(
            config,
            contains="`",
            location=Location(line=idx, column=line.find("`") + 1),
            suggestion="Use $(...) instead of backticks.",
        )
        for idx, line in enumerate(context.code.splitlines(), start=1)
        if "`" in line
    ]
    return violations

def detect(
    self,
    context: AnalysisContext,
    config: BashReadonlyConstantsConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashReadonlyConstantsConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = [
        self.build_violation(
            config,
            contains="readonly",
            location=Location(line=idx, column=1),
            suggestion="Declare constants with readonly.",
        )
        for idx, line in enumerate(context.code.splitlines(), start=1)
        if re.match(r"^[A-Z][A-Z0-9_]*=", line) and "readonly" not in line
    ]
    return violations

def detect(  # noqa: C901
    self,
    context: AnalysisContext,
    config: BashExitCodeConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashExitCodeConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = []
    lines = context.code.splitlines()
    for idx, line in enumerate(lines, start=1):
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        if re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", stripped):
            continue
        if stripped.startswith("export ") and "=" in stripped:
            continue
        if re.match(r"^\w+\s*\(\)\s*\{", stripped):
            continue
        if re.match(
            r"^(if|then|elif|else|fi|for|while|until|case|select|do|done)\b",
            stripped,
        ):
            continue
        if stripped.startswith(("set ", "{", "}")):
            continue
        if re.match(r"^(return|exit)\b", stripped):
            continue
        if "||" in stripped or "&&" in stripped or "$?" in stripped:
            continue
        next_line = lines[idx] if idx < len(lines) else ""
        if "$?" in next_line:
            continue
        if re.match(r"^[A-Za-z0-9_./-]+", stripped):
            violations.append(
                self.build_violation(
                    config,
                    contains="exit code",
                    location=Location(line=idx, column=1),
                    suggestion=(
                        "Check exit codes with `||`, `&&`, or explicit `$?` tests."
                    ),
                ),
            )
            break
    return violations

def detect(
    self,
    context: AnalysisContext,
    config: Bash006Config,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (Bash006Config): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    lines = [
        line
        for line in context.code.splitlines()
        if line.strip() and not line.strip().startswith("#")
    ]
    has_function = any(
        re.match(r"^\s*(?:function\s+)?\w+\s*\(\)\s*\{", line) for line in lines
    )
    max_len = config.max_script_length_without_functions or 50
    if not has_function and len(lines) > max_len:
        return [
            self.build_violation(
                config,
                contains="function",
                location=Location(line=1, column=1),
                suggestion="Extract reusable logic into functions.",
            ),
        ]
    return []

def detect(
    self,
    context: AnalysisContext,
    config: BashLocalVariablesConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashLocalVariablesConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = []
    in_function = False
    for idx, line in enumerate(context.code.splitlines(), start=1):
        stripped = line.strip()
        if re.match(r"^\s*(?:function\s+)?\w+\s*\(\)\s*\{", line):
            in_function = True
            continue
        if in_function and stripped.startswith("}"):
            in_function = False
            continue
        if not in_function:
            continue
        if re.match(
            r"^[A-Za-z_][A-Za-z0-9_]*=",
            stripped,
        ) and not stripped.startswith("local "):
            violations.append(
                self.build_violation(
                    config,
                    contains="local",
                    location=Location(line=idx, column=1),
                    suggestion="Declare function variables with local.",
                ),
            )
            break
    return violations

def detect(
    self,
    context: AnalysisContext,
    config: BashArgumentValidationConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashArgumentValidationConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    code = context.code
    uses_args = bool(re.search(r"\$(?:[1-9]|@|\*)", code))
    has_validation = "$#" in code or "getopts" in code
    if uses_args and not has_validation:
        return [
            self.build_violation(
                config,
                contains="$#",
                location=Location(line=1, column=1),
                suggestion="Validate arguments with `$#` checks or getopts.",
            ),
        ]
    return []

def detect(
    self,
    context: AnalysisContext,
    config: Bash011Config,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (Bash011Config): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = []
    min_len = config.min_variable_name_length or 3
    for idx, line in enumerate(context.code.splitlines(), start=1):
        match = re.match(r"^\s*([A-Za-z_][A-Za-z0-9_]*)=", line)
        if not match:
            continue
        name = match[1]
        if name.isupper() or name in {"i", "j", "k"}:
            continue
        if len(name) < min_len:
            violations.append(
                self.build_violation(
                    config,
                    contains=name,
                    location=Location(line=idx, column=1),
                    suggestion="Use descriptive variable names.",
                ),
            )
            break
    return violations

def detect(
    self,
    context: AnalysisContext,
    config: BashSignalHandlingConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashSignalHandlingConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    if "trap " not in context.code:
        return [
            self.build_violation(
                config,
                contains="trap",
                location=Location(line=1, column=1),
                suggestion="Add trap handlers for cleanup and signals.",
            ),
        ]
    return []

def detect(
    self,
    context: AnalysisContext,
    config: BashArrayUsageConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashArrayUsageConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    if re.search(r"\bIFS=|\bfor\s+\w+\s+in\s+\$", context.code):
        return [
            self.build_violation(
                config,
                contains="array",
                location=Location(line=1, column=1),
                suggestion='Prefer arrays and iterate with "${array[@]}".',
            ),
        ]
    return []

def detect(
    self,
    context: AnalysisContext,
    config: BashUsageInfoConfig,
) -> list[Violation]:
    """Detect violations for the current analysis context.

    Args:
        context (AnalysisContext): Analysis context containing source text and intermediate metrics.
        config (BashUsageInfoConfig): Typed detector or analyzer configuration that controls thresholds.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    if not re.search(r"\busage\b", context.code) and not re.search(
        r"--help|-h",
        context.code,
    ):
        return [
            self.build_violation(
                config,
                contains="usage",
                location=Location(line=1, column=1),
                suggestion="Provide a usage function or -h/--help flag.",
            ),
        ]
    return []

def detect(
    self,
    context: AnalysisContext,
    config: CppSmartPointerConfig,
) -> list[Violation]:
    """Flag lines containing raw ``new`` or ``delete`` expressions.

    Args:
        context (AnalysisContext): Analysis context with C++ source text.
        config (CppSmartPointerConfig): Smart-pointer detection configuration.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = [
        self.build_violation(
            config,
            contains="new",
            location=Location(line=idx, column=1),
            suggestion=("Prefer smart pointers and RAII over manual new/delete."),
        )
        for idx, line in enumerate(context.code.splitlines(), start=1)
        if re.search(r"\bnew\b", line) or re.search(r"\bdelete\b", line)
    ]
    return violations

def detect(
    self,
    context: AnalysisContext,
    config: CppNullptrConfig,
) -> list[Violation]:
    """Flag lines that reference the ``NULL`` macro.

    Args:
        context (AnalysisContext): Analysis context with C++ source text.
        config (CppNullptrConfig): Nullptr detection configuration.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = [
        self.build_violation(
            config,
            contains="nullptr",
            location=Location(line=idx, column=1),
            suggestion="Use nullptr instead of NULL/0.",
        )
        for idx, line in enumerate(context.code.splitlines(), start=1)
        if re.search(r"\bNULL\b", line)
    ]
    return violations

def detect(
    self,
    context: AnalysisContext,
    config: CppRaiiConfig,
) -> list[Violation]:
    """Flag lines with ``new``/``delete``/``malloc``/``free`` that bypass RAII.

    Args:
        context (AnalysisContext): Analysis context with C++ source text.
        config (CppRaiiConfig): RAII detection configuration.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = [
        self.build_violation(
            config,
            contains="RAII",
            location=Location(line=idx, column=1),
            suggestion="Prefer RAII wrappers instead of manual resource control.",
        )
        for idx, line in enumerate(context.code.splitlines(), start=1)
        if re.search(r"\bnew\b|\bdelete\b|malloc\(|free\(", line)
    ]
    return violations

def detect(
    self,
    context: AnalysisContext,
    config: CppAutoConfig,
) -> list[Violation]:
    """Flag assignments with explicit ``std::`` types that could use ``auto``.

    Args:
        context (AnalysisContext): Analysis context with C++ source text.
        config (CppAutoConfig): Auto-deduction detection configuration.

    Returns:
        list[Violation]: Violations detected for the analyzed context.
    """
    violations: list[Violation] = []
    for idx, line in enumerate(context.code.splitlines(), start=1):
        if "auto " in line:
            continue
        if "std::" in line and "=" in line:
            violations.append(
                self.build_violation(
                    config,
                    contains="auto",
                    location=Location(line=idx, column=1),
                    suggestion="Use auto for obvious type deduction.",
                ),
            )
    return violations