Add comments documenting helper predicates, and add call resolve condition to callMatchesSignature to avoid cartesian product

joefarebrother · joefarebrother · commit 9fa630faf597 · 2025-09-03T11:00:59.000+01:00
diff --git a/python/ql/src/Functions/SignatureOverriddenMethod.ql b/python/ql/src/Functions/SignatureOverriddenMethod.ql
@@ -17,18 +17,21 @@ import semmle.python.dataflow.new.DataFlow
 import semmle.python.dataflow.new.internal.DataFlowDispatch
 import codeql.util.Option
 
+/** Holds if `base` is overriden by `sub` */
 predicate overrides(Function base, Function sub) {
   base.getName() = sub.getName() and
   base.getScope() = getADirectSuperclass+(sub.getScope())
 }
 
+/** Constructs a string to pluralize `str` depending on `num`. */
 bindingset[num, str]
 string plural(int num, string str) {
   num = 1 and result = "1 " + str
   or
   num != 1 and result = num.toString() + " " + str + "s"
 }
 
+/** Describes the minimum number of arguments `func` can accept, using "at least" if it may accept more. */
 string describeMin(Function func) {
   exists(string descr | descr = plural(func.getMinPositionalArguments(), "positional argument") |
     if func.getMinPositionalArguments() = func.getMaxPositionalArguments()
@@ -37,6 +40,7 @@ string describeMin(Function func) {
   )
 }
 
+/** Described the maximum number of arguments `func` can accept, using "at most" if it may accept fewer, and "arbitrarily many" if it has a vararg. */
 string describeMax(Function func) {
   if func.hasVarArg()
   then result = "arbitrarily many positional arguments"
@@ -48,6 +52,7 @@ string describeMax(Function func) {
     )
 }
 
+/** Describes the minumum number of arguments `func` can accept, without repeating "positional arguments". */
 string describeMinShort(Function func) {
   exists(string descr | descr = func.getMinPositionalArguments().toString() |
     if func.getMinPositionalArguments() = func.getMaxPositionalArguments()
@@ -56,6 +61,7 @@ string describeMinShort(Function func) {
   )
 }
 
+/** Describes the maximum number of arguments `func` can accept, without repeating "positional arguments". */
 string describeMaxShort(Function func) {
   if func.hasVarArg()
   then result = "arbitrarily many"
@@ -67,6 +73,7 @@ string describeMaxShort(Function func) {
     )
 }
 
+/** Describe an upper bound on the number of arguments `func` may accept, without specifying "at most". */
 string describeMaxBound(Function func) {
   if func.hasVarArg()
   then result = "arbitrarily many"
@@ -121,6 +128,7 @@ predicate weakSignatureMismatch(Function base, Function sub, string msg) {
   )
 }
 
+/** Holds if `f` should be ignored for considering signature mismatches. */
 predicate ignore(Function f) {
   isClassmethod(f)
   or
@@ -133,18 +141,21 @@ predicate ignore(Function f) {
   )
 }
 
+/** Gets a function that `call` may resolve to. */
 Function resolveCall(Call call) {
   exists(DataFlowCall dfc | call = dfc.getNode().(CallNode).getNode() |
     result = viableCallable(dfc).(DataFlowFunction).getScope()
   )
 }
 
+/** Holds if `call` may resolve to either `base` or `sub`, and `base` is overiden by `sub`. */
 predicate callViableForEitherOverride(Function base, Function sub, Call call) {
   overrides(base, sub) and
   base = resolveCall(call) and
   sub = resolveCall(call)
 }
 
+/** Holds if either both `base` and `sub` are static methods, or both are not static methods, and `base` is overriden by `sub`. */
 predicate matchingStatic(Function base, Function sub) {
   overrides(base, sub) and
   (
@@ -158,7 +169,9 @@ predicate matchingStatic(Function base, Function sub) {
 
 int extraSelfArg(Function func) { if isStaticmethod(func) then result = 0 else result = 1 }
 
+/** Holds if the call `call` matches the signature for `func`. */
 predicate callMatchesSignature(Function func, Call call) {
+  func = resolveCall(call) and
   (
     // Each parameter of the function is accounted for in the call
     forall(Parameter param, int i | param = func.getArg(i) |
@@ -189,12 +202,14 @@ predicate callMatchesSignature(Function func, Call call) {
   )
 }
 
+/** Gets a call which matches the signature of `base`, but not of overriden `sub`. */
 Call getASignatureMismatchWitness(Function base, Function sub) {
   callViableForEitherOverride(base, sub, result) and
   callMatchesSignature(base, result) and
   not callMatchesSignature(sub, result)
 }
 
+/** Choose a 'witnessing' call that matches the signature of `base` but not of overridden `sub`, and is in the file `file`. */
 Call chooseASignatureMismatchWitnessInFile(Function base, Function sub, File file) {
   result =
     min(Call c |
@@ -205,6 +220,7 @@ Call chooseASignatureMismatchWitnessInFile(Function base, Function sub, File fil
     )
 }
 
+/** Choose a 'witnessing' call that matches the signature of `base` but not of overridden `sub`. */
 Call chooseASignatureMismatchWitness(Function base, Function sub) {
   exists(getASignatureMismatchWitness(base, sub)) and
   (
@@ -242,6 +258,7 @@ where
   not ignore(base) and
   matchingStatic(base, sub) and
   (
+    // If we have a witness, alert for a 'weak' mismatch, but prefer the message for a 'strong' mismatch if that holds.
     call.asSome() = chooseASignatureMismatchWitness(base, sub) and
     extraMsg =
       " $@ correctly calls the base method, but does not match the signature of the overriding method." and
@@ -252,6 +269,7 @@ where
       weakSignatureMismatch(base, sub, msg)
     )
     or
+    // With no witness, only alert for 'strong' mismatches.
     not exists(getASignatureMismatchWitness(base, sub)) and
     call.isNone() and
     strongSignatureMismatch(base, sub, msg) and

Original file line number	Diff line number	Diff line change
`@@ -17,18 +17,21 @@ import semmle.python.dataflow.new.DataFlow`
`17`	`17`	`import semmle.python.dataflow.new.internal.DataFlowDispatch`
`18`	`18`	`import codeql.util.Option`
`19`	`19`
	`20`	+/** Holds if `base` is overriden by `sub` */
`20`	`21`	`predicate overrides(Function base, Function sub) {`
`21`	`22`	`base.getName() = sub.getName() and`
`22`	`23`	`base.getScope() = getADirectSuperclass+(sub.getScope())`
`23`	`24`	`}`
`24`	`25`
	`26`	+/** Constructs a string to pluralize `str` depending on `num`. */
`25`	`27`	`bindingset[num, str]`
`26`	`28`	`string plural(int num, string str) {`
`27`	`29`	`num = 1 and result = "1 " + str`
`28`	`30`	`or`
`29`	`31`	`num != 1 and result = num.toString() + " " + str + "s"`
`30`	`32`	`}`
`31`	`33`
	`34`	+/** Describes the minimum number of arguments `func` can accept, using "at least" if it may accept more. */
`32`	`35`	`string describeMin(Function func) {`
`33`	`36`	`exists(string descr \| descr = plural(func.getMinPositionalArguments(), "positional argument") \|`
`34`	`37`	`if func.getMinPositionalArguments() = func.getMaxPositionalArguments()`
`@@ -37,6 +40,7 @@ string describeMin(Function func) {`
`37`	`40`	`)`
`38`	`41`	`}`
`39`	`42`
	`43`	+/** Described the maximum number of arguments `func` can accept, using "at most" if it may accept fewer, and "arbitrarily many" if it has a vararg. */
`40`	`44`	`string describeMax(Function func) {`
`41`	`45`	`if func.hasVarArg()`
`42`	`46`	`then result = "arbitrarily many positional arguments"`
`@@ -48,6 +52,7 @@ string describeMax(Function func) {`
`48`	`52`	`)`
`49`	`53`	`}`
`50`	`54`
	`55`	+/** Describes the minumum number of arguments `func` can accept, without repeating "positional arguments". */
`51`	`56`	`string describeMinShort(Function func) {`
`52`	`57`	`exists(string descr \| descr = func.getMinPositionalArguments().toString() \|`
`53`	`58`	`if func.getMinPositionalArguments() = func.getMaxPositionalArguments()`
`@@ -56,6 +61,7 @@ string describeMinShort(Function func) {`
`56`	`61`	`)`
`57`	`62`	`}`
`58`	`63`
	`64`	+/** Describes the maximum number of arguments `func` can accept, without repeating "positional arguments". */
`59`	`65`	`string describeMaxShort(Function func) {`
`60`	`66`	`if func.hasVarArg()`
`61`	`67`	`then result = "arbitrarily many"`
`@@ -67,6 +73,7 @@ string describeMaxShort(Function func) {`
`67`	`73`	`)`
`68`	`74`	`}`
`69`	`75`
	`76`	+/** Describe an upper bound on the number of arguments `func` may accept, without specifying "at most". */
`70`	`77`	`string describeMaxBound(Function func) {`
`71`	`78`	`if func.hasVarArg()`
`72`	`79`	`then result = "arbitrarily many"`
`@@ -121,6 +128,7 @@ predicate weakSignatureMismatch(Function base, Function sub, string msg) {`
`121`	`128`	`)`
`122`	`129`	`}`
`123`	`130`
	`131`	+/** Holds if `f` should be ignored for considering signature mismatches. */
`124`	`132`	`predicate ignore(Function f) {`
`125`	`133`	`isClassmethod(f)`
`126`	`134`	`or`
`@@ -133,18 +141,21 @@ predicate ignore(Function f) {`
`133`	`141`	`)`
`134`	`142`	`}`
`135`	`143`
	`144`	+/** Gets a function that `call` may resolve to. */
`136`	`145`	`Function resolveCall(Call call) {`
`137`	`146`	`exists(DataFlowCall dfc \| call = dfc.getNode().(CallNode).getNode() \|`
`138`	`147`	`result = viableCallable(dfc).(DataFlowFunction).getScope()`
`139`	`148`	`)`
`140`	`149`	`}`
`141`	`150`
	`151`	+/** Holds if `call` may resolve to either `base` or `sub`, and `base` is overiden by `sub`. */
`142`	`152`	`predicate callViableForEitherOverride(Function base, Function sub, Call call) {`
`143`	`153`	`overrides(base, sub) and`
`144`	`154`	`base = resolveCall(call) and`
`145`	`155`	`sub = resolveCall(call)`
`146`	`156`	`}`
`147`	`157`
	`158`	+/** Holds if either both `base` and `sub` are static methods, or both are not static methods, and `base` is overriden by `sub`. */
`148`	`159`	`predicate matchingStatic(Function base, Function sub) {`
`149`	`160`	`overrides(base, sub) and`
`150`	`161`	`(`
`@@ -158,7 +169,9 @@ predicate matchingStatic(Function base, Function sub) {`
`158`	`169`
`159`	`170`	`int extraSelfArg(Function func) { if isStaticmethod(func) then result = 0 else result = 1 }`
`160`	`171`
	`172`	+/** Holds if the call `call` matches the signature for `func`. */
`161`	`173`	`predicate callMatchesSignature(Function func, Call call) {`
	`174`	`+ func = resolveCall(call) and`
`162`	`175`	`(`
`163`	`176`	`// Each parameter of the function is accounted for in the call`
`164`	`177`	`forall(Parameter param, int i \| param = func.getArg(i) \|`
`@@ -189,12 +202,14 @@ predicate callMatchesSignature(Function func, Call call) {`
`189`	`202`	`)`
`190`	`203`	`}`
`191`	`204`
	`205`	+/** Gets a call which matches the signature of `base`, but not of overriden `sub`. */
`192`	`206`	`Call getASignatureMismatchWitness(Function base, Function sub) {`
`193`	`207`	`callViableForEitherOverride(base, sub, result) and`
`194`	`208`	`callMatchesSignature(base, result) and`
`195`	`209`	`not callMatchesSignature(sub, result)`
`196`	`210`	`}`
`197`	`211`
	`212`	+/** Choose a 'witnessing' call that matches the signature of `base` but not of overridden `sub`, and is in the file `file`. */
`198`	`213`	`Call chooseASignatureMismatchWitnessInFile(Function base, Function sub, File file) {`
`199`	`214`	`result =`
`200`	`215`	`min(Call c \|`
`@@ -205,6 +220,7 @@ Call chooseASignatureMismatchWitnessInFile(Function base, Function sub, File fil`
`205`	`220`	`)`
`206`	`221`	`}`
`207`	`222`
	`223`	+/** Choose a 'witnessing' call that matches the signature of `base` but not of overridden `sub`. */
`208`	`224`	`Call chooseASignatureMismatchWitness(Function base, Function sub) {`
`209`	`225`	`exists(getASignatureMismatchWitness(base, sub)) and`
`210`	`226`	`(`
`@@ -242,6 +258,7 @@ where`
`242`	`258`	`not ignore(base) and`
`243`	`259`	`matchingStatic(base, sub) and`
`244`	`260`	`(`
	`261`	`+ // If we have a witness, alert for a 'weak' mismatch, but prefer the message for a 'strong' mismatch if that holds.`
`245`	`262`	`call.asSome() = chooseASignatureMismatchWitness(base, sub) and`
`246`	`263`	`extraMsg =`
`247`	`264`	`" $@ correctly calls the base method, but does not match the signature of the overriding method." and`
`@@ -252,6 +269,7 @@ where`
`252`	`269`	`weakSignatureMismatch(base, sub, msg)`
`253`	`270`	`)`
`254`	`271`	`or`
	`272`	`+ // With no witness, only alert for 'strong' mismatches.`
`255`	`273`	`not exists(getASignatureMismatchWitness(base, sub)) and`
`256`	`274`	`call.isNone() and`
`257`	`275`	`strongSignatureMismatch(base, sub, msg) and`