/// A special ID that is used for an "always true" predicate.

pub(crate) const ALWAYS_TRUE: ScopedPredicateId = ScopedPredicateId(0xffff_ffff);

/// A special ID that is used for an "always false" predicate.

pub(crate) const ALWAYS_FALSE: ScopedPredicateId = ScopedPredicateId(0xffff_fffe);

const SMALLEST_TERMINAL: ScopedPredicateId = Self::ALWAYS_FALSE;

fn is_terminal(self) -> bool {

self >= Self::SMALLEST_TERMINAL

}

#[inline]

fn new(value: usize) -> Self {

assert!(value <= (Self::SMALLEST_TERMINAL.0 as usize));

#[expect(clippy::cast_possible_truncation)]

Self(value as u32)

}

#[inline]

fn index(self) -> usize {

debug_assert!(!self.is_terminal());

self.0 as usize

}

/// Adds a predicate. Note that we do not deduplicate predicates. If you add a `Predicate`

/// more than once, you will get distinct `ScopedPredicateId`s for each one. (This lets you

/// model predicates that might evaluate to different values at different points of execution.)

pub(crate) fn add_predicate(&mut self, predicate: Predicate<'db>) -> ScopedPredicateId {

self.predicates.push(predicate)

}

pub(crate) fn build(self) -> Predicates<'db> {

self.predicates.into()

}

pub(crate) fn negated(self) -> Self {

match self {

PredicateOrLiteral::Literal(value) => PredicateOrLiteral::Literal(!value),

PredicateOrLiteral::Predicate(Predicate { node, is_positive }) => {

PredicateOrLiteral::Predicate(Predicate {

node,

is_positive: !is_positive,

})

}

}

}

#[returns(copy)]

pub callable: Expression<'db>,

#[returns(copy)]

pub call_expr: Expression<'db>,

/// Whether the call is wrapped in an `await` expression. If `true`, `call_expr` refers to the

/// `await` expression rather than the call itself. This is used to detect terminal `await`s of

/// async functions that return `Never`.

#[returns(copy)]

pub is_await: bool,

/// Extracts a direct or awaited call for checking whether an expression statement can return.

///

/// Callers pass the value of an expression statement, such as `sys.exit()` or `await stop()`.

/// The semantic-index builder uses the returned call to record a reachability constraint:

/// if the call returns `Never`, subsequent statements are unreachable. The

/// `redundant-condition-strict` rule uses the same extraction when recognizing defensive exits.

///

/// The `is_await` flag matters for async functions returning `Never`: calling one creates a

/// coroutine, while awaiting it prevents execution from continuing.

///

/// Calls inside larger expressions, such as `1 + sys.exit()`, are deliberately excluded.

/// Tracking their termination would require many more reachability constraints and degrade

/// analysis performance.

pub fn from_expression(expression: &'ast ast::Expr) -> Option<Self> {

match expression {

ast::Expr::Call(call) => Some(Self {

call,

is_await: false,

}),

ast::Expr::Await(ast::ExprAwait { value, .. }) => {

value.as_call_expr().map(|call| Self {

call,

is_await: true,

})

}

_ => None,

}

}

/// The truthiness of an expression's resulting value.

Expression(Expression<'db>),

/// A boolean operation, `not`, or conditional expression evaluated directly as a condition.

///

/// In `if x and False`, the truthy branch is unreachable. But after `y = x and False`,

/// `if y` may be truthy: it can call `x.__bool__` a second time and get a different result.

Condition(Expression<'db>),

/// A chained comparison evaluated directly as a condition. Its inferred truthiness is

/// available without walking the expression again.

ChainedComparisonCondition(Expression<'db>),

/// Whether a context manager's exit return type allows an exception to be suppressed.

///

/// Resolved during type inference because the context manager's type is unavailable during

/// semantic indexing.

ContextManagerSuppresses {

expression: Expression<'db>,

is_async: bool,

},

/// Whether semantic evaluation rules out every normal entry into a `finally` suite.

///

/// The continuation is captured before constructing this predicate, so its constraint cannot

/// depend on the predicate itself. Deferring evaluation preserves terminal cleanup paths when

/// a context manager's suppression behavior is unavailable during semantic indexing.

FinallyNormalPathImpossible {

scope: ScopeId<'db>,

continuation: ScopedReachabilityConstraintId,

},

/// These predicates are recorded for statements with call expressions. As part of

/// reachability constraints, they are used to determine whether control flow can

/// continue past this statement or not.

///

/// The predicate evaluates to

/// [`crate::Truthiness::AlwaysTrue`] in the common case where a call

/// is inferred as returning an inhabited type: in these situations, we will

/// infer control flow as flowing through the call expression without

/// terminating. If it can be statically guaranteed that a call always

/// returns `Never`/`NoReturn`, however, the predicate evaluates to

/// [`crate::Truthiness::AlwaysFalse`], signaling that control flow

/// ends as a result of the call: these call expressions are terminal.

///

/// These predicates never evaluate to

/// [`crate::Truthiness::Ambiguous`], even if the return type of the

/// call is `Unknown`/`Any`, because that would result in too many false

/// positives.

IsNonTerminalCall(CallableAndCallExpr<'db>),

/// Whether an iterable is statically known to yield at least one item.

///

/// Currently, this predicate is only emitted for direct `range(...)` calls. It is resolved

/// semantically during type checking, so calls to a shadowed `range` remain ambiguous.

IsNonEmptyIterable(Expression<'db>),

Pattern(PatternPredicate<'db>),

/// Whether control flow takes one branch of an OR pattern instead of its remaining

/// alternatives. The selected branch is unknown, but recording a predicate and its negation

/// preserves the fact that exactly one branch is taken.

OrPatternAlternative(ScopeId<'db>),

SubjectElementPattern(SubjectElementPatternPredicate<'db>),

StarImportPlaceholder(StarImportPlaceholderPredicate<'db>),

/// Return `true` for `case [*rest]`, the only sequence pattern with no

/// length or element constraints.

pub fn is_irrefutable(&self) -> bool {

matches!(self.patterns.as_ref(), [PatternPredicateKind::Star(_)])

}

/// Return the patterns before and after the starred element.

pub fn split_around_star(

&self,

) -> Option<(&[PatternPredicateKind<'db>], &[PatternPredicateKind<'db>])> {

let star_index = self

.patterns

.iter()

.position(|pattern| matches!(pattern, PatternPredicateKind::Star(_)))?;

let (prefix, star_and_suffix) = self.patterns.split_at(star_index);

Some((prefix, &star_and_suffix[1..]))

}

pub class: Expression<'db>,

pub positional: Box<[PatternPredicateKind<'db>]>,

pub keywords: Box<[ClassPatternKeywordPredicateKind<'db>]>,

pub fn is_empty(&self) -> bool {

self.positional.is_empty() && self.keywords.is_empty()

}

pub fn is_irrefutable(&self) -> bool {

self.entries.is_empty()

}

Singleton(Singleton),

Value(Expression<'db>),

Or(Box<[PatternPredicateKind<'db>]>),

Class(ClassPatternPredicateKind<'db>),

Mapping(MappingPatternPredicateKind<'db>),

Sequence(SequencePatternPredicateKind<'db>),

As(Option<Box<PatternPredicateKind<'db>>>, Option<Name>),

Star(Option<Name>),

#[returns(copy)]

pub program_file: ProgramFile<'db>,

#[returns(copy)]

pub file_scope: FileScopeId,

#[returns(copy)]

pub subject: Expression<'db>,

#[returns(ref)]

pub kind: PatternPredicateKind<'db>,

#[returns(copy)]

pub guard: Option<Expression<'db>>,

/// A reference to the pattern of the previous match case

#[returns(as_deref)]

pub previous_predicate: Option<Box<PatternPredicate<'db>>>,

pub fn file(self, db: &'db dyn Db) -> File {

self.program_file(db).file(db)

}

pub fn python_file(self, db: &'db dyn Db) -> PythonFile<'db> {

self.program_file(db).python_file(db)

}

pub fn scope(self, db: &'db dyn Db) -> ScopeId<'db> {

self.file_scope(db).to_scope_id(db, self.program_file(db))

}

pub fn program(self, db: &'db dyn Db) -> Program<'db> {

self.scope(db).program(db)

}

#[returns(copy)]

pub importing_file: ProgramFile<'db>,

/// Each symbol imported by a `*` import has a separate predicate associated with it:

/// this field identifies which symbol that is.

///

/// Note that a [`ScopedPlaceId`] is only meaningful if you also know the scope

/// it is relative to. For this specific struct, however, there's no need to store a

/// separate field to hold the ID of the scope. `StarImportPredicate`s are only created

/// for valid `*`-import definitions, and valid `*`-import definitions can only ever

/// exist in the global scope; thus, we know that the `symbol_id` here will be relative

/// to the global scope of the importing file.

#[returns(copy)]

pub symbol_id: ScopedSymbolId,

#[returns(copy)]

pub referenced_file: ProgramFile<'db>,

pub fn scope(self, db: &'db dyn Db) -> ScopeId<'db> {

// See doc-comment above [`StarImportPlaceholderPredicate::symbol_id`]:

// valid `*`-import definitions can only take place in the global scope.

global_scope(db, self.importing_file(db))

}

fn from(predicate: StarImportPlaceholderPredicate<'db>) -> Self {

PredicateOrLiteral::Predicate(Predicate {

node: PredicateNode::StarImportPlaceholder(predicate),

is_positive: true,

})

}