From 4cd41c24c72ee62b4b1f659fc17a41e615312cc3 Mon Sep 17 00:00:00 2001
From: Rasmus Lerchedahl Petersen <yoff@github.com>
Date: Tue, 6 Sep 2022 17:23:40 +0200
Subject: [PATCH] Python: remove comments and start design document

---
 python/ql/lib/design.md                       | 24 +++++++++++++++++++
 .../dataflow/summaries/TestSummaries.qll      |  2 --
 2 files changed, 24 insertions(+), 2 deletions(-)
 create mode 100644 python/ql/lib/design.md

diff --git a/python/ql/lib/design.md b/python/ql/lib/design.md
new file mode 100644
index 00000000000..a390f50beee
--- /dev/null
+++ b/python/ql/lib/design.md
@@ -0,0 +1,24 @@
+# The Python libraries
+
+The Python libraries are a collection of libraries for analysing Python code.
+Everythng can be imported by importing `python.qll`.
+
+## The analysis layers
+
+The analysis is built up in layers. the stack looks like this:
+
+- AST (coms from the extractor)
+- Control flow graph (CFG) (built by the extractor)
+- SSA
+- Call graph
+- Data flow
+
+## Avoiding non-monotonic recursion
+
+Given the many interactivg layers, it is imprtant to decie which predicates are allowed to be mutually recursive in order to avoid non-monotonic recursion when negation is used to express the predicates.
+As an example, we have defined local source as those whcih do not receive local flow. This means that the local flow relation is not allowed to be recursive with anything depending on local sources.
+
+Some particular reatrictions to keep in mind:
+
+- Typetracking needs to use a local flow step not including summaries
+- Typetracking needs to use a call graph not including summaries
diff --git a/python/ql/test/experimental/dataflow/summaries/TestSummaries.qll b/python/ql/test/experimental/dataflow/summaries/TestSummaries.qll
index baae90f5b50..3af7566dfa8 100644
--- a/python/ql/test/experimental/dataflow/summaries/TestSummaries.qll
+++ b/python/ql/test/experimental/dataflow/summaries/TestSummaries.qll
@@ -67,8 +67,6 @@ private class SummarizedCallableMap extends SummarizedCallable {
   }
 }
 
-// Typetracking needs to use a local flow step not including summaries
-// Typetracking needs to use a call graph not including summaries
 private class SummarizedCallableJsonLoads extends SummarizedCallable {
   SummarizedCallableJsonLoads() { this = "json.loads" }