Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

14.5 KB
Raw Blame
"""Open a draft pull request that removes a stale flag's checks from the code.

The cleanup starts from the flag's latest code analysis: it targets the repository the analysis read
and hands the agent the checks the analysis found. The work runs as a Tasks run that opens the pull
request, the same way the experiments flag-cleanup PR does
(`products/experiments/backend/experiment_service.py`).
"""

from __future__ import annotations

import re
from typing import TYPE_CHECKING
from uuid import UUID

from django.db import models, transaction

from posthog.dataclasses import frozen

from products.feature_flags.backend.code_analysis import (
    SAFE_KEY,
    CodeAnalysisError,
    CodeAnalysisStatus,
    FlagCodeAnalysisResult,
    TaskPrompt,
    get_code_analysis_status,
    get_code_analysis_target,
    latest_cleanup_analysis,
    latest_code_analysis,
    latest_run_for_task,
    lock_flag_code_work,
    require_ai_allowed,
)
from products.feature_flags.backend.facade.config import ConfigFormatError
from products.feature_flags.backend.flag_status import FeatureFlagStatus, FeatureFlagStatusChecker
from products.feature_flags.backend.models import FeatureFlag, FeatureFlagCodeAnalysis
from products.tasks.backend.facade import api as tasks_facade

if TYPE_CHECKING:
    from posthog.models import User

ENABLED = "enabled"
DISABLED = "disabled"

# File paths come from the analysis agent's output. Only plain paths reach the cleanup prompt, so text
# the agent copied from the repository cannot add instructions there.
_SAFE_PATH = re.compile(r"[\w./@+-]{1,300}")
_SAFE_COMMIT = re.compile(r"[0-9a-f]{7,40}")
# The prompt lists at most this many checks. The agent searches the repository again in any case.
_MAX_PROMPT_REFERENCES = 50


class CodeCleanupUnavailableReason(models.TextChoices):
    ANALYSIS_NOT_READY = "analysis_not_ready", "Analysis not ready"
    NO_REFERENCES = "no_references", "No references"
    NOT_STALE = "not_stale", "Not stale"
    UNSUPPORTED_CONFIG = "unsupported_config", "Unsupported configuration"


@frozen
class CodeCleanupAvailability:
    unavailable_reason: CodeCleanupUnavailableReason | None
    suggested_outcome: str | None
    outcome_options: tuple[str, ...]


@frozen
class CodeCleanupRun:
    task_id: UUID
    run_status: str
    is_terminal: bool
    pr_url: str | None
    error_message: str | None
    can_view_task: bool


def _outcome_options(flag: FeatureFlag) -> tuple[str, ...] | None:
    """Outcomes the code can keep, or None when the flag's configuration can't be read safely."""
    # The cleanup run can push code, so check the key again: older flags predate the key validation.
    if not SAFE_KEY.fullmatch(flag.key):
        return None
    try:
        variants = flag.variants
    except ConfigFormatError:
        return None
    raw_keys = [variant.get("key") for variant in variants if isinstance(variant, dict)]
    if not raw_keys:
        return (ENABLED, DISABLED)
    # Variant keys go into the prompt, so they must be as safe as a flag key.
    # A variant named like a boolean outcome would get the boolean instruction in the prompt.
    keys = [
        key for key in raw_keys if isinstance(key, str) and SAFE_KEY.fullmatch(key) and key not in (ENABLED, DISABLED)
    ]
    if len(keys) != len(raw_keys):
        return None
    return (DISABLED, *keys)


def _suggested_outcome(flag: FeatureFlag) -> str | None:
    """The outcome every user gets today, which is the code to keep. None when users get different outcomes."""
    # Early access enrollment and holdouts serve some users outside the release conditions, also when
    # the flag has none, so they come before the shortcuts below.
    if flag.has_feature_enrollment or flag.holdout:
        return None
    # With no release conditions nothing matches, so every user gets false. The status checker counts this
    # shape as fully rolled out, which is right for staleness but not for which code runs.
    if not flag.conditions:
        return DISABLED
    checker = FeatureFlagStatusChecker(feature_flag=flag)
    if checker.get_rollout_summary(flag).max_rollout_percentage == 0:
        return DISABLED
    # With early exit, a targeted condition below 100% that comes before the untargeted 100% one serves
    # false to the users it targets. The status checker ignores early exit, so it can't name one outcome.
    if flag.early_exit and len(flag.conditions) > 1:
        return None
    is_fully_rolled_out, _ = checker.is_flag_fully_rolled_out(flag)
    if is_fully_rolled_out:
        return checker.sole_served_variant(flag) if flag.variants else ENABLED
    return None


def get_cleanup_availability(flag: FeatureFlag, analysis_status: CodeAnalysisStatus) -> CodeCleanupAvailability:
    def unavailable(reason: CodeCleanupUnavailableReason) -> CodeCleanupAvailability:
        return CodeCleanupAvailability(unavailable_reason=reason, suggested_outcome=None, outcome_options=())

    if analysis_status.result is None:
        return unavailable(CodeCleanupUnavailableReason.ANALYSIS_NOT_READY)
    if not analysis_status.result.references:
        return unavailable(CodeCleanupUnavailableReason.NO_REFERENCES)
    flag_status, _ = FeatureFlagStatusChecker(feature_flag=flag).get_status()
    if flag_status != FeatureFlagStatus.STALE:
        return unavailable(CodeCleanupUnavailableReason.NOT_STALE)
    options = _outcome_options(flag)
    if options is None:
        return unavailable(CodeCleanupUnavailableReason.UNSUPPORTED_CONFIG)
    return CodeCleanupAvailability(
        unavailable_reason=None, suggested_outcome=_suggested_outcome(flag), outcome_options=options
    )


def get_cleanup_run(flag: FeatureFlag, user: User) -> CodeCleanupRun | None:
    """The flag's latest cleanup run, from whichever analysis started it.

    A newer analysis doesn't hide a cleanup, so the page keeps its pull request and can't open a second one.
    """
    analysis = latest_cleanup_analysis(flag)
    if analysis is None or analysis.cleanup_task_id is None:
        return None
    run = latest_run_for_task(analysis.cleanup_task_id, analysis.team_id)
    # The run is created with its task, so a missing one is unreadable, for example after a project
    # transfer. Treat it as absent so it can't block a new request forever.
    if run is None:
        return None
    return CodeCleanupRun(
        task_id=analysis.cleanup_task_id,
        run_status=run.status,
        is_terminal=run.is_terminal,
        pr_url=run.pr_url,
        error_message=run.error_message,
        can_view_task=tasks_facade.task_visible(analysis.cleanup_task_id, analysis.team_id, user.id),
    )


def _keep_instruction(outcome: str) -> str:
    if outcome == ENABLED:
        return "Keep the code that runs when the flag is enabled. Remove the code that runs when it is disabled."
    if outcome == DISABLED:
        return (
            "Keep the code that runs when the flag is disabled or evaluates to false. Remove the code that runs "
            "when it is enabled or set to any variant."
        )
    return f'Keep the code that runs for the variant "{outcome}". Remove the code for every other outcome.'


def _reference_lines(result: FlagCodeAnalysisResult) -> list[str]:
    lines = [
        f"- {reference.file}:{reference.check_line}"
        for reference in result.references[:_MAX_PROMPT_REFERENCES]
        if _SAFE_PATH.fullmatch(reference.file)
    ]
    return lines or ["- (none that can be listed here, so search the repository)"]


def build_code_cleanup_prompt(
    flag: FeatureFlag, repository: str, keep_outcome: str, result: FlagCodeAnalysisResult
) -> TaskPrompt:
    """Return the task title and the agent's instructions.

    Only the flag key, safe variant keys, plain file paths and a hex commit are interpolated. The
    analysis summaries and notes are model output, so they stay out of the prompt.
    """
    title = f"Remove stale feature flag {flag.key}"
    at_commit = f" at commit {result.commit_sha}" if _SAFE_COMMIT.fullmatch(result.commit_sha) else ""
    description = "\n".join(
        [
            f'Remove every check of the PostHog feature flag "{flag.key}" from this repository, keep the right code path, and open a draft pull request.',
            "",
            f"Repository: {repository}",
            f'Feature flag key: "{flag.key}"',
            "PostHog marks this flag as stale, so it no longer needs to decide which code runs.",
            "",
            "## Which code to keep",
            f"- {_keep_instruction(keep_outcome)}",
            "",
            "## Where the flag is checked",
            f"An earlier read-only analysis{at_commit} found checks at these places:",
            *_reference_lines(result),
            "The code can have changed since that analysis. Use the list as a starting point, then search the repository again:",
            f'- Search for the exact key "{flag.key}" and follow every constant, enum, or config entry that holds it.',
            "- Inspect local flag helpers and wrapper components that take the key.",
            "- Cover every language and every directory that deploys on its own.",
            "",
            "## Rules",
            "- At each check, keep the body of the branch to keep, then delete the flag check and the other branches.",
            "- If the kept branch does nothing, delete the check entirely. Do not leave an empty block or a no-op component.",
            "- Remove the dead code the change creates: unused imports, helpers, components, constants, and the flag key constant itself when nothing else uses it.",
            "- Update or delete tests that only exercise the removed branches, and fix tests that mock the flag.",
            "- Leave reads of the flag's payload unchanged, because you don't know its value. List them in the pull request description.",
            "- Do not touch unrelated code.",
            "- If the right code path is unclear at a check, leave it unchanged and list it in the pull request description.",
            "- Do not change the flag in PostHog.",
            "- If the repository has no checks of the flag, do not open a pull request. Say so in your final message.",
            "",
            "## Output",
            f'Open a draft pull request titled "{title}".',
            "In the description, say which outcome the code keeps, list the files you changed, and list anything left for a person to review.",
            "End the description with a reminder to archive the flag in PostHog after the change deploys.",
        ]
    )
    return TaskPrompt(title=title, description=description)


def _cleanup_in_progress(run: CodeCleanupRun | None) -> bool:
    # Only a run that is still going blocks another. A finished run can be followed by a new one even when it
    # opened a pull request, because that pull request may have been closed.
    return run is not None and not run.is_terminal


def can_request_cleanup(availability: CodeCleanupAvailability, run: CodeCleanupRun | None) -> bool:
    """Whether `start_code_cleanup` accepts a request now, so the page doesn't copy its rules."""
    return availability.unavailable_reason is None and not _cleanup_in_progress(run)


def start_code_cleanup(flag: FeatureFlag, user: User, keep_outcome: str | None = None) -> FeatureFlagCodeAnalysis:
    require_ai_allowed(flag)

    latest = latest_code_analysis(flag)
    if latest is None:
        raise CodeAnalysisError(
            "cleanup_unavailable", "Analyze the flag's code first, then open the cleanup pull request."
        )
    # Resolved before the lock because it can call GitHub. GitHub installations can be shared across
    # projects, so the repository must still belong to this one.
    target = get_code_analysis_target(flag, requested_repository=latest.repository)
    if target.repository is None:
        raise CodeAnalysisError(
            "no_repository",
            f"{latest.repository} is no longer connected to this project. Connect it, or analyze another repository.",
        )

    # The lock makes the checks and the new task one step, so two concurrent requests cannot both open a
    # pull request. The task's workflow starts on commit, so a rollback starts nothing.
    with transaction.atomic():
        lock_flag_code_work(flag)
        analysis_status = get_code_analysis_status(flag, user)
        if analysis_status is None or analysis_status.analysis.id != latest.id:
            raise CodeAnalysisError(
                "cleanup_unavailable", "The flag was analyzed again. Review the new result, then try again."
            )
        if _cleanup_in_progress(get_cleanup_run(flag, user)):
            raise CodeAnalysisError(
                "cleanup_exists", "A cleanup pull request for this flag is already being opened. Wait for it to finish."
            )
        availability = get_cleanup_availability(flag, analysis_status)
        if availability.unavailable_reason == CodeCleanupUnavailableReason.ANALYSIS_NOT_READY:
            raise CodeAnalysisError(
                "cleanup_unavailable", "Wait for the analysis to finish, then open the cleanup pull request."
            )
        if availability.unavailable_reason == CodeCleanupUnavailableReason.NOT_STALE:
            raise CodeAnalysisError(
                "cleanup_unavailable", "Only stale flags can be removed from the code. This flag isn't stale."
            )
        if availability.unavailable_reason is not None:
            raise CodeAnalysisError("cleanup_unavailable", "This flag has no code that can be removed automatically.")

        outcome = keep_outcome or availability.suggested_outcome
        if outcome is None:
            raise CodeAnalysisError(
                "outcome_required", "Users get different outcomes from this flag. Choose which code to keep."
            )
        if outcome not in availability.outcome_options:
            raise CodeAnalysisError("invalid_outcome", f"Choose one of: {', '.join(availability.outcome_options)}.")

        assert analysis_status.result is not None
        prompt = build_code_cleanup_prompt(flag, target.repository, outcome, analysis_status.result)
        created = tasks_facade.create_and_run_task(
            team=flag.team,
            title=prompt.title,
            description=prompt.description,
            origin_product=tasks_facade.TaskOriginProduct.FEATURE_FLAGS,
            user_id=user.id,
            repository=target.repository,
            create_pr=True,
            posthog_mcp_scopes="read_only",
            interaction_origin="feature_flags",
            ai_stage="implementation",
        )
        analysis = analysis_status.analysis
        analysis.cleanup_task_id = created.task_id
        analysis.save(update_fields=["cleanup_task_id"])
        return analysis