diff --git a/tools/flir-demo/README.md b/tools/flir-demo/README.md new file mode 100644 index 0000000000..caf2d90f45 --- /dev/null +++ b/tools/flir-demo/README.md @@ -0,0 +1,29 @@ +# flir migration rules on sample calls + +*Handbook: [`architecture/r-layer/conventions/`](/handbook/architecture/r-layer/conventions/README.md) is the node this folder serves.* + +`calls.R` holds old-style calls to `degree()`, `sample_gnp()`, `simplify()` and `clique_size_counts()`, +each with a comment saying what the rules should do with it. +`rules/` holds the rules `tools/generate-flir-rules.R` writes for those four functions. + +To see the rules at work, rewrite `calls.R` in place from the repository root and read the diff: + +```r +flir::fix( + "tools/flir-demo/calls.R", + linters = list.files("tools/flir-demo/rules", full.names = TRUE) +) +``` + +```sh +git diff tools/flir-demo/calls.R +git checkout tools/flir-demo/calls.R +``` + +`flir::lint()` with the same arguments lists the matches without changing the file. + +After a change to the generator or its template, regenerate the rules before running flir again: + +```sh +Rscript tools/generate-flir-rules.R tools/flir-demo/rules degree sample_gnp simplify clique_size_counts +``` diff --git a/tools/flir-demo/calls.R b/tools/flir-demo/calls.R new file mode 100644 index 0000000000..82e8585f8c --- /dev/null +++ b/tools/flir-demo/calls.R @@ -0,0 +1,49 @@ +# Old-style calls to igraph functions whose arguments moved behind `...` in +# igraph 3.0.0. Each comment says what the rules should do with the call. + +library(igraph) +library(magrittr) + +g <- make_ring(10) + +# degree(): old formals graph, v, mode, loops, normalized + +# by position: mode, loops and normalized all get named +degree(g, V(g), mode = "out", loops = FALSE, normalized = TRUE) +# by position, only mode +degree(g, 1:3, mode = "in") +# by an abbreviation of the old name +degree(g, mode = "out", loops = FALSE) +# already new style: left alone +degree(g, mode = "out") +# piped: the graph comes from the left-hand side +g |> degree(V(g), mode = "out") +g %>% degree(V(g), mode = "out") +# magrittr with a `.` placeholder: the graph is not first, so positions are +# as written +g %>% degree(., V(.), mode = "out") + +# Left to the runtime recovery, not rewritten by position: +# a named argument shifts the unnamed ones +degree(g, v = 1:3, "out", TRUE) +# an empty slot +degree(g, , "out") +# `...` of a wrapper +my_degree <- function(...) degree(g, ..., "out") + +# sample_gnp(): old formals n, p, directed, loops +sample_gnp(10, 0.2, directed = TRUE, loops = FALSE) +sample_gnp(10, 0.2, directed = TRUE) + +# simplify(): old formals graph, remove.multiple, remove.loops, edge.attr.comb +# edge.attr.comb is renamed edge_attr_combine +simplify(g, TRUE, TRUE, edge_attr_combine = "first") +simplify(g, edge_attr_combine = "sum") +igraph::simplify(g, edge_attr_combine = "sum") + +# clique_size_counts(): old formals graph, min, max, maximal +clique_size_counts(g, min = 2, max = 4, maximal = TRUE) +# `mi` binds to min, `max` to max, `maxi` to maximal +clique_size_counts(g, min = 2, max = 4, maximal = TRUE) +# `ma` is ambiguous between max and maximal: an error in R, left alone +clique_size_counts(g, ma = 4) diff --git a/tools/flir-demo/rules/migrate-3.0.0-clique_size_counts.yml b/tools/flir-demo/rules/migrate-3.0.0-clique_size_counts.yml new file mode 100644 index 0000000000..007c90262f --- /dev/null +++ b/tools/flir-demo/rules/migrate-3.0.0-clique_size_counts.yml @@ -0,0 +1,166 @@ +id: igraph-3.0.0-clique_size_counts-min +language: r +severity: warning +rule: + kind: argument + has: { field: value, pattern: $V } + any: + - # passed by name + has: { field: name, kind: identifier, regex: '^(mi)$' } + inside: + kind: arguments + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?clique_size_counts$' } + - # passed by position + not: { has: { field: name, kind: identifier } } + nthChild: { position: 2, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|m|mi|min)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?clique_size_counts$' } + not: + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } + not: { has: { field: rhs, kind: call, has: { kind: arguments, has: { kind: argument, has: { field: value, kind: identifier, regex: '^[.]$' } } } } } + - # passed by position after a pipe + not: { has: { field: name, kind: identifier } } + nthChild: { position: 1, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: value, kind: identifier, regex: '^[._]$' } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|m|mi|min)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?clique_size_counts$' } + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } +fix: min = ~~V~~ +message: igraph 3.0.0 requires `min` of `clique_size_counts()` to be passed by its full name. +--- +id: igraph-3.0.0-clique_size_counts-max +language: r +severity: warning +rule: + kind: argument + has: { field: value, pattern: $V } + any: + - # passed by position + not: { has: { field: name, kind: identifier } } + nthChild: { position: 3, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|m|mi|min|ma|max)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?clique_size_counts$' } + not: + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } + not: { has: { field: rhs, kind: call, has: { kind: arguments, has: { kind: argument, has: { field: value, kind: identifier, regex: '^[.]$' } } } } } + - # passed by position after a pipe + not: { has: { field: name, kind: identifier } } + nthChild: { position: 2, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: value, kind: identifier, regex: '^[._]$' } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|m|mi|min|ma|max)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?clique_size_counts$' } + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } +fix: max = ~~V~~ +message: igraph 3.0.0 requires `max` of `clique_size_counts()` to be passed by its full name. +--- +id: igraph-3.0.0-clique_size_counts-maximal +language: r +severity: warning +rule: + kind: argument + has: { field: value, pattern: $V } + any: + - # passed by name + has: { field: name, kind: identifier, regex: '^(maxi|maxim|maxima)$' } + inside: + kind: arguments + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?clique_size_counts$' } + - # passed by position + not: { has: { field: name, kind: identifier } } + nthChild: { position: 4, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|m|mi|min|ma|max|maxi|maxim|maxima|maximal)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?clique_size_counts$' } + not: + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } + not: { has: { field: rhs, kind: call, has: { kind: arguments, has: { kind: argument, has: { field: value, kind: identifier, regex: '^[.]$' } } } } } + - # passed by position after a pipe + not: { has: { field: name, kind: identifier } } + nthChild: { position: 3, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: value, kind: identifier, regex: '^[._]$' } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|m|mi|min|ma|max|maxi|maxim|maxima|maximal)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?clique_size_counts$' } + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } +fix: maximal = ~~V~~ +message: igraph 3.0.0 requires `maximal` of `clique_size_counts()` to be passed by its full name. diff --git a/tools/flir-demo/rules/migrate-3.0.0-degree.yml b/tools/flir-demo/rules/migrate-3.0.0-degree.yml new file mode 100644 index 0000000000..56471f0e41 --- /dev/null +++ b/tools/flir-demo/rules/migrate-3.0.0-degree.yml @@ -0,0 +1,173 @@ +id: igraph-3.0.0-degree-mode +language: r +severity: warning +rule: + kind: argument + has: { field: value, pattern: $V } + any: + - # passed by name + has: { field: name, kind: identifier, regex: '^(m|mo|mod)$' } + inside: + kind: arguments + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?degree$' } + - # passed by position + not: { has: { field: name, kind: identifier } } + nthChild: { position: 3, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|v|m|mo|mod|mode)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?degree$' } + not: + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } + not: { has: { field: rhs, kind: call, has: { kind: arguments, has: { kind: argument, has: { field: value, kind: identifier, regex: '^[.]$' } } } } } + - # passed by position after a pipe + not: { has: { field: name, kind: identifier } } + nthChild: { position: 2, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: value, kind: identifier, regex: '^[._]$' } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|v|m|mo|mod|mode)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?degree$' } + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } +fix: mode = ~~V~~ +message: igraph 3.0.0 requires `mode` of `degree()` to be passed by its full name. +--- +id: igraph-3.0.0-degree-loops +language: r +severity: warning +rule: + kind: argument + has: { field: value, pattern: $V } + any: + - # passed by name + has: { field: name, kind: identifier, regex: '^(l|lo|loo|loop)$' } + inside: + kind: arguments + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?degree$' } + - # passed by position + not: { has: { field: name, kind: identifier } } + nthChild: { position: 4, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|v|m|mo|mod|mode|l|lo|loo|loop|loops)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?degree$' } + not: + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } + not: { has: { field: rhs, kind: call, has: { kind: arguments, has: { kind: argument, has: { field: value, kind: identifier, regex: '^[.]$' } } } } } + - # passed by position after a pipe + not: { has: { field: name, kind: identifier } } + nthChild: { position: 3, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: value, kind: identifier, regex: '^[._]$' } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|v|m|mo|mod|mode|l|lo|loo|loop|loops)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?degree$' } + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } +fix: loops = ~~V~~ +message: igraph 3.0.0 requires `loops` of `degree()` to be passed by its full name. +--- +id: igraph-3.0.0-degree-normalized +language: r +severity: warning +rule: + kind: argument + has: { field: value, pattern: $V } + any: + - # passed by name + has: { field: name, kind: identifier, regex: '^(n|no|nor|norm|norma|normal|normali|normaliz|normalize)$' } + inside: + kind: arguments + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?degree$' } + - # passed by position + not: { has: { field: name, kind: identifier } } + nthChild: { position: 5, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|v|m|mo|mod|mode|l|lo|loo|loop|loops|n|no|nor|norm|norma|normal|normali|normaliz|normalize|normalized)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?degree$' } + not: + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } + not: { has: { field: rhs, kind: call, has: { kind: arguments, has: { kind: argument, has: { field: value, kind: identifier, regex: '^[.]$' } } } } } + - # passed by position after a pipe + not: { has: { field: name, kind: identifier } } + nthChild: { position: 4, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: value, kind: identifier, regex: '^[._]$' } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|v|m|mo|mod|mode|l|lo|loo|loop|loops|n|no|nor|norm|norma|normal|normali|normaliz|normalize|normalized)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?degree$' } + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } +fix: normalized = ~~V~~ +message: igraph 3.0.0 requires `normalized` of `degree()` to be passed by its full name. diff --git a/tools/flir-demo/rules/migrate-3.0.0-sample_gnp.yml b/tools/flir-demo/rules/migrate-3.0.0-sample_gnp.yml new file mode 100644 index 0000000000..1c6dfa6a91 --- /dev/null +++ b/tools/flir-demo/rules/migrate-3.0.0-sample_gnp.yml @@ -0,0 +1,115 @@ +id: igraph-3.0.0-sample_gnp-directed +language: r +severity: warning +rule: + kind: argument + has: { field: value, pattern: $V } + any: + - # passed by name + has: { field: name, kind: identifier, regex: '^(d|di|dir|dire|direc|direct|directe)$' } + inside: + kind: arguments + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?sample_gnp$' } + - # passed by position + not: { has: { field: name, kind: identifier } } + nthChild: { position: 3, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: name, regex: '^(n|p|d|di|dir|dire|direc|direct|directe|directed)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?sample_gnp$' } + not: + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } + not: { has: { field: rhs, kind: call, has: { kind: arguments, has: { kind: argument, has: { field: value, kind: identifier, regex: '^[.]$' } } } } } + - # passed by position after a pipe + not: { has: { field: name, kind: identifier } } + nthChild: { position: 2, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: value, kind: identifier, regex: '^[._]$' } } + - has: { kind: argument, has: { field: name, regex: '^(n|p|d|di|dir|dire|direc|direct|directe|directed)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?sample_gnp$' } + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } +fix: directed = ~~V~~ +message: igraph 3.0.0 requires `directed` of `sample_gnp()` to be passed by its full name. +--- +id: igraph-3.0.0-sample_gnp-loops +language: r +severity: warning +rule: + kind: argument + has: { field: value, pattern: $V } + any: + - # passed by name + has: { field: name, kind: identifier, regex: '^(l|lo|loo|loop)$' } + inside: + kind: arguments + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?sample_gnp$' } + - # passed by position + not: { has: { field: name, kind: identifier } } + nthChild: { position: 4, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: name, regex: '^(n|p|d|di|dir|dire|direc|direct|directe|directed|l|lo|loo|loop|loops)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?sample_gnp$' } + not: + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } + not: { has: { field: rhs, kind: call, has: { kind: arguments, has: { kind: argument, has: { field: value, kind: identifier, regex: '^[.]$' } } } } } + - # passed by position after a pipe + not: { has: { field: name, kind: identifier } } + nthChild: { position: 3, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: value, kind: identifier, regex: '^[._]$' } } + - has: { kind: argument, has: { field: name, regex: '^(n|p|d|di|dir|dire|direc|direct|directe|directed|l|lo|loo|loop|loops)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?sample_gnp$' } + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } +fix: loops = ~~V~~ +message: igraph 3.0.0 requires `loops` of `sample_gnp()` to be passed by its full name. diff --git a/tools/flir-demo/rules/migrate-3.0.0-simplify.yml b/tools/flir-demo/rules/migrate-3.0.0-simplify.yml new file mode 100644 index 0000000000..86865b9886 --- /dev/null +++ b/tools/flir-demo/rules/migrate-3.0.0-simplify.yml @@ -0,0 +1,57 @@ +id: igraph-3.0.0-simplify-edge.attr.comb +language: r +severity: warning +rule: + kind: argument + has: { field: value, pattern: $V } + any: + - # passed by name + has: { field: name, kind: identifier, regex: '^(e|ed|edg|edge|edge[.]|edge[.]a|edge[.]at|edge[.]att|edge[.]attr|edge[.]attr[.]|edge[.]attr[.]c|edge[.]attr[.]co|edge[.]attr[.]com|edge[.]attr[.]comb)$' } + inside: + kind: arguments + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?simplify$' } + - # passed by position + not: { has: { field: name, kind: identifier } } + nthChild: { position: 4, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|r|re|rem|remo|remov|remove|remove[.]|remove[.]m|remove[.]mu|remove[.]mul|remove[.]mult|remove[.]multi|remove[.]multip|remove[.]multipl|remove[.]multiple|remove[.]l|remove[.]lo|remove[.]loo|remove[.]loop|remove[.]loops|e|ed|edg|edge|edge[.]|edge[.]a|edge[.]at|edge[.]att|edge[.]attr|edge[.]attr[.]|edge[.]attr[.]c|edge[.]attr[.]co|edge[.]attr[.]com|edge[.]attr[.]comb)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?simplify$' } + not: + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } + not: { has: { field: rhs, kind: call, has: { kind: arguments, has: { kind: argument, has: { field: value, kind: identifier, regex: '^[.]$' } } } } } + - # passed by position after a pipe + not: { has: { field: name, kind: identifier } } + nthChild: { position: 3, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: value, kind: identifier, regex: '^[._]$' } } + - has: { kind: argument, has: { field: name, regex: '^(g|gr|gra|grap|graph|r|re|rem|remo|remov|remove|remove[.]|remove[.]m|remove[.]mu|remove[.]mul|remove[.]mult|remove[.]multi|remove[.]multip|remove[.]multipl|remove[.]multiple|remove[.]l|remove[.]lo|remove[.]loo|remove[.]loop|remove[.]loops|e|ed|edg|edge|edge[.]|edge[.]a|edge[.]at|edge[.]att|edge[.]attr|edge[.]attr[.]|edge[.]attr[.]c|edge[.]attr[.]co|edge[.]attr[.]com|edge[.]attr[.]comb)$' } } + inside: + kind: call + has: { field: function, regex: '^(igraph:::?)?simplify$' } + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } +fix: edge_attr_combine = ~~V~~ +message: igraph 3.0.0 requires `edge_attr_combine` of `simplify()` to be passed by its full name. diff --git a/tools/flir-rule.yml.mustache b/tools/flir-rule.yml.mustache new file mode 100644 index 0000000000..5a139c5246 --- /dev/null +++ b/tools/flir-rule.yml.mustache @@ -0,0 +1,73 @@ +{{=<< >>=}} +<> +<<#rules>> +<<^is_first_rule>> +--- +<> +id: igraph-<>-<>-<> +language: r +severity: warning +rule: + kind: argument + has: { field: value, pattern: $V } + any: +<<#regex_matching_old_name_spellings>> + - # passed by name + has: { field: name, kind: identifier, regex: '<<& regex_matching_old_name_spellings>>' } + inside: + kind: arguments + inside: + kind: call + has: { field: function, regex: '<<& regex_matching_function_name>>' } +<> + - # passed by position + not: { has: { field: name, kind: identifier } } + nthChild: { position: <>, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: name, regex: '<<& regex_matching_names_blocking_position>>' } } + inside: + kind: call + has: { field: function, regex: '<<& regex_matching_function_name>>' } + not: + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } + not: { has: { field: rhs, kind: call, has: { kind: arguments, has: { kind: argument, has: { field: value, kind: identifier, regex: '^[.]$' } } } } } +<<#position_after_pipe>> + - # passed by position after a pipe + not: { has: { field: name, kind: identifier } } + nthChild: { position: <>, ofRule: { kind: argument, not: { has: { field: name, kind: identifier } } } } + inside: + kind: arguments + not: + any: + - has: { kind: comma, follows: { kind: comma } } + - has: { kind: comma, follows: { regex: '^\($' } } + - has: { kind: comma, precedes: { regex: '^\)$' } } + - has: { kind: argument, has: { kind: dots } } + - has: { kind: argument, has: { field: value, kind: identifier, regex: '^[._]$' } } + - has: { kind: argument, has: { field: name, regex: '<<& regex_matching_names_blocking_position>>' } } + inside: + kind: call + has: { field: function, regex: '<<& regex_matching_function_name>>' } + inside: + kind: binary_operator + field: rhs + has: { field: operator, regex: '^(\|>|%>%)$' } +<> +fix: <> = ~~V~~ +message: igraph <> requires `<>` of `<>()` to be passed by its full name. +<> diff --git a/tools/generate-flir-rules.R b/tools/generate-flir-rules.R new file mode 100644 index 0000000000..13effb3540 --- /dev/null +++ b/tools/generate-flir-rules.R @@ -0,0 +1,178 @@ +#!/usr/bin/env Rscript +# +# Generate flir rules from the argument-migration registry (tools/migrations/). +# +# For each registry entry, writes one file `migrate--.yml` holding one +# rule per old positional slot that moved behind `...`. Each rule matches the +# argument R would have bound to that old formal and rewrites it to +# ` = `, in three cases: +# +# - passed by its old name, or by an abbreviation unique under `old`; +# - passed as the k-th unnamed argument of a call that is not piped; +# - passed as the (k-1)-th unnamed argument of a call on the right of `|>`, or +# of `%>%` without a `.` placeholder. +# +# The positional cases only fire when the binding is decidable from syntax: no +# named argument that could take one of the old formals 1..k (k being the +# position of the rule's formal in `old`), no empty slot, no `...`. Take the +# rule for `mode` of `degree()`, whose old formals were `graph, v, mode, loops, +# normalized`: `mode` comes third, so k = 3, and the rule looks for the +# argument R binds to `mode` as the third unnamed one. None of these calls lets +# it say which one that is: +# +# - `degree(g, v = 1:3, "out", TRUE)`: the third unnamed argument is `TRUE`, +# but `v =` takes the second formal, so `mode` gets `"out"` and `TRUE` goes +# to `loops`; +# - `degree(g, , "out")`: `mode` gets `"out"`, though `"out"` is only the +# second unnamed argument written, because the empty slot stands for `v`; +# - `degree(g, ..., "out")`, inside a wrapper: how many arguments `...` holds +# is only known at run time: with none, `"out"` goes to `v`; with one, +# `mode` gets `"out"`; with two or more, `mode` gets one of them. +# +# Every other call is left to the runtime recovery. See +# https://github.com/igraph/rigraph/issues/2933. +# +# Usage: +# Rscript tools/generate-flir-rules.R [out_dir] [fn ...] +# +# `out_dir` defaults to inst/flir/rules. By default, rules are written for every +# function in the registry; list function names after `out_dir` to write rules +# for those functions only, e.g. +# Rscript tools/generate-flir-rules.R out/ sample_gnp degree +# +# The YAML lives in tools/flir-rule.yml.mustache, rendered with whisker. + +source(file.path("tools", "generate-migrations.R")) + +# The names R binds to the formal `name` among `formals`: the full name, plus +# every abbreviation of it no other formal claims. `duplicates.ok = TRUE` makes +# `pmatch()` match each abbreviation on its own: by default it would match them +# jointly, as in a call, and the exact match would take `name` away from the +# shorter ones. For `mode` of `degree()`: +# +# formals <- c("graph", "v", "mode", "loops", "normalized") +# abbreviations <- c("m", "mo", "mod", "mode") +# pmatch(abbreviations, formals) # NA NA NA 3 +# pmatch(abbreviations, formals, duplicates.ok = TRUE) # 3 3 3 3 +# +# For `clique_size_counts()`, whose old formals share prefixes, `m` and `ma` +# are ambiguous and are left out: +# +# formals <- c("graph", "min", "max", "maximal") +# names_that_bind_to("min", formals) # "mi" "min" +# names_that_bind_to("max", formals) # "max" +# names_that_bind_to("maximal", formals) # "maxi" "maxim" "maxima" "maximal" +names_that_bind_to <- function(name, formals) { + abbreviations <- all_abbreviations_of(name) + bound_to_formal <- pmatch(abbreviations, formals, duplicates.ok = TRUE) + abbreviations[bound_to_formal %in% match(name, formals)] +} + +# Every abbreviation of every name in `names`, the full names included. +all_abbreviations_of <- function(names) { + unique(unlist(lapply(names, function(name) { + substring(name, 1, seq_len(nchar(name))) + }))) +} + +# A regex matching any of the names `x` in full, dots escaped. +regex_exactly_matching_any_of <- function(x) { + paste0("^(", paste(gsub(".", "[.]", x, fixed = TRUE), collapse = "|"), ")$") +} + +# A regex matching the function part of a call to `fn`, bare or `igraph::`. +regex_matching_call_to <- function(fn) { + paste0("^(igraph:::?)?", gsub(".", "[.]", fn, fixed = TRUE), "$") +} + +# The values the template fills in for the rule moving `old_name` to +# `new_name`. +template_values_for_rule <- function(entry, old_name, new_name) { + position <- match(old_name, entry$old) + # Writing the new name over itself would change nothing yet lint forever. + old_name_spellings <- setdiff( + names_that_bind_to(old_name, entry$old), + new_name + ) + # A named argument that may bind to one of the old formals up to `position` + # shifts the unnamed ones, so the positional branches must not fire. For + # `mode` of `degree()`, in third position: in `degree(g, v = 1:3, "out")`, + # `"out"` binds to `mode` though it is only the second unnamed argument. + # Any spelling of `graph`, `v` or `mode` blocks: + # + # old <- c("graph", "v", "mode", "loops", "normalized") + # all_abbreviations_of(old[seq_len(3)]) + # # "g" "gr" "gra" "grap" "graph" "v" "m" "mo" "mod" "mode" + names_blocking_position <- all_abbreviations_of(entry$old[seq_len(position)]) + list( + when = entry$when, + fn = entry$fn, + regex_matching_function_name = regex_matching_call_to(entry$fn), + old_name = old_name, + new_name = new_name, + regex_matching_old_name_spellings = if (length(old_name_spellings)) { + regex_exactly_matching_any_of(old_name_spellings) + } else { + FALSE + }, + regex_matching_names_blocking_position = regex_exactly_matching_any_of( + names_blocking_position + ), + position = position, + # On the right of a pipe the first formal is filled by the left-hand side. + position_after_pipe = if (position > 1L) position - 1L else FALSE + ) +} + +# The rule file for one registry entry: one rule per old formal that moved +# behind `...`. +render_rule_file <- function(entry, template) { + rules <- Map( + function(old_name, new_name) { + template_values_for_rule(entry, old_name, new_name) + }, + entry$recover_old, + entry$recover_new + ) + for (i in seq_along(rules)) { + rules[[i]]$is_first_rule <- i == 1L + } + whisker::whisker.render(template, list(rules = unname(rules))) +} + +generate_flir_rules <- function(registry_path, out_dir, fns = NULL) { + migrations <- load_migrations(registry_path) + if (length(fns)) { + unknown <- setdiff(fns, names(migrations)) + if (length(unknown)) { + stop( + "Not in the registry: ", + paste(unknown, collapse = ", "), + call. = FALSE + ) + } + migrations <- migrations[fns] + } + template <- paste( + readLines(file.path("tools", "flir-rule.yml.mustache")), + collapse = "\n" + ) + dir.create(out_dir, recursive = TRUE, showWarnings = FALSE) + for (entry in migrations) { + if (!length(entry$recover_old)) { + next + } + path <- file.path( + out_dir, + sprintf("migrate-%s-%s.yml", entry$when, entry$fn) + ) + writeLines(render_rule_file(entry, template), path, sep = "") + message("wrote ", path) + } +} + +if (sys.nframe() == 0L && !interactive()) { + args <- commandArgs(trailingOnly = TRUE) + out_dir <- if (length(args)) args[[1]] else file.path("inst", "flir", "rules") + generate_flir_rules(migration_registry_files(), out_dir, args[-1]) +}