Test TypeQL reference (#985)

## Goal
Add tests to TypeQL reference to notice if we ever break any syntax.

## Implementation
Adds tests as far as possible.
Notably misses `data-model.adoc`. Also skips some which are quite hand-wavy.

Points of improvement (Maybe todo in this PR)
* Add pre-conditions to a dedicated typeql block that's block-commented out.
* Add counts to read queries I may have forgotten.

Author: krishnangovindraj

.factory/automation.yml

@@ -45,7 +45,7 @@ build:
         
         # TODO: test node and java
         
-        TEST_DIRS=("home" "core-concepts")
+        TEST_DIRS=("home" "core-concepts" "reference/modules/ROOT/pages/typeql")
         TEST_LANGS=("typeql" "python" "rust")
         
         FAILED=false

reference/modules/ROOT/examples/tql/conjunction.tql

@@ -4,6 +4,21 @@ define
   attribute name, value string;
 # pipeline::schema::end
 
+# tag::patterns-schema[]
+define
+    attribute email, value string;
+    attribute phone, value string;
+    attribute username, value string;
+    relation friendship, relates friend @card(0..2);
+    relation marriage, relates spouse @card(0..2);
+    relation policy, relates covered @card(0..);
+    entity user,
+        owns username, owns email, owns phone,
+        plays friendship:friend;
+    entity person, plays marriage:spouse, plays policy:covered;
+
+# end::patterns-schema[]
+
 # pipeline::read::start
 match
 # tag::conjunction-example[]

reference/modules/ROOT/examples/tql/read_statements_functions.tql

@@ -1,38 +1,39 @@
-// tag::with-fun[]
+# tag::with-fun[]
 with fun karma_with_squared_value($user: user) -> karma, double:
   match
     $user has karma $karma;
     let $karma-squared = $karma * $karma;
   return first $karma, $karma-squared;
-// tag::with-fun-match[]
+
+# tag::with-fun-match[]
 match
   $user isa user, has username $name;
   let $karma, $karma-squared = karma_with_squared_value($user);
 select $name, $karma-squared;
-// end::with-fun-match[]
-// end::with-fun[]
+# end::with-fun-match[]
+# end::with-fun[]
 
 
 
-// tag::fun-stream-scalar-return-type[]
+# tag::fun-stream-scalar-return-type[]
 match
   $user isa user;
   let $phone in user_phones($user);
-// end::fun-stream-scalar-return-type[]
+# end::fun-stream-scalar-return-type[]
 
 
-// tag::match-users[]
+# tag::match-users[]
 match
   $user isa user;
-// end::match-users[]
+# end::match-users[]
 
-// tag::fun-stream-tuple-return-type[]
+# tag::fun-stream-tuple-return-type[]
 match
   let $user, $phone, $phone-value in all_users_and_phones();
-// end::fun-stream-tuple-return-type[]
+# end::fun-stream-tuple-return-type[]
 
 
-// tag::fun-single-scalar-return-value[]
+# tag::fun-single-scalar-return-value[]
 match
   let $answer = add(2016, 9);
-// end::fun-single-scalar-return-value[]
+# end::fun-single-scalar-return-value[]

reference/modules/ROOT/examples/tql/redefine_statements_functions.tql

@@ -1,10 +1,10 @@
-// tag::redefine-keyword[]
+# tag::redefine-keyword[]
 redefine
-// end::redefine-keyword[]
+# end::redefine-keyword[]
 
-// tag::with-fun-redefined[]
+# tag::with-fun-redefined[]
   fun karma_with_squared_value($karma: karma) -> double:
     match
       let $karma-squared = $karma * $karma;
     return first $karma-squared;
-// end::with-fun-redefined[]
+# end::with-fun-redefined[]

reference/modules/ROOT/examples/tql/schema_statements_functions.tql

@@ -1,139 +1,156 @@
-// tag::define-keyword[]
+# tag::define-keyword[]
 define
-// end::define-keyword[]
-// tag::entities[]
+# end::define-keyword[]
+# tag::entities[]
   entity content owns id;
   entity page sub content,
     owns page-id,
     owns name;
   entity profile sub page,
     owns username;
-// tag::entity-user[]
+# tag::entity-user[]
   entity user sub profile,
     owns phone,
-    owns karma,
-    plays parentship:parent,
-    plays parentship:child;
-// end::entity-user[]
+    owns karma;
+# end::entity-user[]
 
-// end::entities[]
+# end::entities[]
 
-// tag::entity-user-breakdown[]
+# tag::entity-user-breakdown[]
   entity user;
   user sub profile;
   user owns phone;
   user owns karma;
-  user plays parentship:parent;
-  user plays parentship:child;
-// end::entity-user-breakdown[]
+# end::entity-user-breakdown[]
 
-// tag::entities-annotations[]
+# tag::entities-annotations[]
   content @abstract, owns id @key;
   page @abstract, owns name @card(0..);
   profile @abstract, owns name @card(0..3);
   user owns phone @regex("^\d{8,15}$") @unique;
-// end::entities-annotations[]
+# end::entities-annotations[]
 
-// tag::entities-type-annotations[]
+# tag::entities-type-annotations[]
   content @abstract;
   page @abstract;
   profile @abstract;
-// end::entities-type-annotations[]
+# end::entities-type-annotations[]
 
-// tag::entities-cap-annotations[]
+# tag::entities-cap-annotations[]
   content owns id @key;
   page owns name @card(0..);
   profile owns name @card(0..3);
   user owns phone @regex("^\d{8,15}$") @unique;
-// end::entities-cap-annotations[]
+# end::entities-cap-annotations[]
 
-// tag::all-owns-name[]
+# tag::all-owns-name[]
   entity content;
-// tag::all-owns-name-cards[]
+# tag::all-owns-name-cards[]
   entity page sub content, owns name @card(0..);
   entity profile sub page, owns name @card(0..3);
   entity user sub profile;
-// end::all-owns-name-cards[]
+# end::all-owns-name-cards[]
   attribute name value string;
-// end::all-owns-name[]
+# end::all-owns-name[]
 
-// tag::attributes[]
+# tag::attributes[]
   attribute id value string;
   attribute page-id sub id;
   attribute username sub page-id;
   attribute name value string;
   attribute phone value string;
   attribute karma value double;
-// end::attributes[]
+# end::attributes[]
 
-// tag::attributes-type-annotations[]
+# tag::extended-attributes[]
+attribute bio value string;
+attribute profile-picture value string;
+attribute email @independent, value string @regex("^.*@.*\.com");
+user owns bio, owns profile-picture;
+# end::extended-attributes[]
+
+# tag::attributes-type-annotations[]
   attribute id @abstract;
   attribute page-id @abstract;
-// end::attributes-type-annotations[]
-
-
-// tag::fun-stream-scalar-return-type[]
+# end::attributes-type-annotations[]
+
+# tag::relation-friendship[]
+attribute start-date, value date;
+relation friendship relates friend @card(0..2), owns start-date;
+user plays friendship:friend;
+# end::relation-friendship[]
+
+# tag::relation-group[]
+attribute group-id sub id;
+attribute rank, value string @values("admin", "member");
+attribute tag value string;
+relation group-membership, relates group, relates member,  owns rank;
+entity group, owns name, owns group-id, owns tag, plays group-membership:group;
+user, plays group-membership:member;
+# end::relation-group[]
+
+# tag::fun-stream-scalar-return-type[]
   fun user_phones($user: user) -> { phone }:
     match
       $user has phone $phone;
     return { $phone };
-// end::fun-stream-scalar-return-type[]
+# end::fun-stream-scalar-return-type[]
 
-// tag::fun-stream-tuple-return-type[]
+# tag::fun-stream-tuple-return-type[]
   fun all_users_and_phones() -> { user, phone, string }:
     match
       $user isa user, has phone $phone;
       let $phone-value = $phone;
     return { $user, $phone, $phone-value };
-// end::fun-stream-tuple-return-type[]
+# end::fun-stream-tuple-return-type[]
 
-// tag::fun-stream-scalar-return-value[]
+# tag::fun-stream-scalar-return-value[]
   fun add_streamed($x: integer, $y: integer) -> { integer }:
     match
       let $z = $x + $y;
     return { $z };
-// end::fun-stream-scalar-return-value[]
+# end::fun-stream-scalar-return-value[]
 
-// tag::fun-single-scalar-return-value[]
+# tag::fun-single-scalar-return-value[]
   fun add($x: integer, $y: integer) -> integer:
     match
       let $z = $x + $y;
     return first $z;
-// end::fun-single-scalar-return-value[]
+# end::fun-single-scalar-return-value[]
 
-// tag::fun-aggregate-single-scalar-return[]
+# tag::fun-aggregate-single-scalar-return[]
   fun mean_karma() -> double:
     match
       $user isa user, has karma $karma;
     return mean($karma);
-// end::fun-aggregate-single-scalar-return[]
+# end::fun-aggregate-single-scalar-return[]
 
-// tag::fun-aggregate-single-tuple-return[]
+# tag::fun-aggregate-single-tuple-return[]
   fun karma_sum_and_sum_squares() -> double, double:
     match
       $karma isa karma;
       let $karma-squared = $karma * $karma;
     return sum($karma), sum($karma-squared);
-// end::fun-aggregate-single-tuple-return[]
+# end::fun-aggregate-single-tuple-return[]
 
-// tag::with-fun-defined[]
+# tag::with-fun-defined[]
   fun karma_with_squared_value($user: user) -> karma, double:
     match
       $user has karma $karma;
       let $karma-squared = $karma * $karma;
     return first $karma, $karma-squared;
-// end::with-fun-defined[]
+# end::with-fun-defined[]
 
-// tag::fun-stream-users[]
+# tag::fun-stream-users[]
   fun users() -> { user }:
     match
       $user isa user;
     return { $user };
-// end::fun-stream-users[]
+# end::fun-stream-users[]
 
-// tag::fun-stream-users-with-first[]
+# tag::fun-stream-users-with-first[]
   fun first_user() -> user:
     match
       $user isa user;
     return first $user;
-// end::fun-stream-users-with-first[]
+# end::fun-stream-users-with-first[]

reference/modules/ROOT/examples/tql/undefine_statements_functions.tql

@@ -1,7 +1,7 @@
-// tag::undefine-keyword[]
+# tag::undefine-keyword[]
 undefine
-// end::undefine-keyword[]
+# end::undefine-keyword[]
 
-// tag::with-fun-undefined[]
+# tag::with-fun-undefined[]
   fun karma_with_squared_value;
-// end::with-fun-undefined[]
+# end::with-fun-undefined[]

reference/modules/ROOT/pages/typeql/annotations/abstract.adoc

@@ -1,5 +1,6 @@
 = `@abstract` annotation
 :page-aliases: {page-version}@reference::typeql/statements/abstract.adoc
+:test-typeql: linear
 
 The `@abstract` annotation is used
 // tag::overview[]
@@ -36,6 +37,7 @@ However, it is possible to define an abstract subtype of an abstract type.
 
 [,typeql]
 ----
+#!test[schema]
 include::{page-version}@reference::example$tql/schema_annotations.tql[tags=define-keyword;abstract-attribute]
 ----
 
@@ -44,6 +46,7 @@ It is impossible to define an abstract subtype of a concrete type.
 .Wrong definition!
 [,typeql]
 ----
+#!test[schema, fail_at=runtime]
 define
   attribute categorized-username @abstract, sub username;
 ----
@@ -56,5 +59,6 @@ A concrete sub role type can be defined using **specialization** (keyword `as`).
 
 [,typeql]
 ----
+#!test[schema]
 include::{page-version}@reference::example$tql/schema_annotations.tql[tags=define-keyword;abstract-relation]
 ----

reference/modules/ROOT/pages/typeql/annotations/card.adoc

@@ -1,4 +1,5 @@
 = `@card` annotation
+:test-typeql: linear
 
 The `@card` annotation is used
 // tag::overview[]
@@ -46,20 +47,31 @@ For example, the following definition specifies that an instance of the `page` t
 
 [,typeql]
 ----
+#!test[schema]
+#{{
+include::{page-version}@reference::example$tql/schema_annotations.tql[tags=define-keyword;name-attribute]
+#}}
+#!test[schema]
 include::{page-version}@reference::example$tql/schema_annotations.tql[tags=define-keyword;card-owns-13]
 ----
 
 At the same time, the `page` type can play the `posting:page` role an unlimited number of times:
 
 [,typeql]
 ----
+#!test[schema]
+#{{
+define relation posting relates page;
+#}}
+#!test[schema, rollback]
 include::{page-version}@reference::example$tql/schema_annotations.tql[tags=define-keyword;card-plays-0inf]
 ----
 
 However, an instance of the `posting` relation type can have up to a thousand `page` instances:
 
 [,typeql]
 ----
+#!test[schema]
 include::{page-version}@reference::example$tql/schema_annotations.tql[tags=define-keyword;card-relates-01k]
 ----
 
@@ -76,6 +88,7 @@ For example, the following query defines that:
 
 [,typeql]
 ----
+#!test[schema]
 include::{page-version}@reference::example$tql/schema_annotations.tql[tags=define-keyword;card-owns-13;profile-sub-page;user-owns-name;name-subattributes]
 ----