Run the Cypher examples and check names on changed pages

.github/workflows/docs-checks.yml

@@ -18,3 +18,19 @@ jobs:
         with:
           node-version: 22
       - run: node scripts/check-docs.mjs
+
+  examples-and-names:
+    name: Examples and names
+    # Only PRs into main: docs on a release branch describe a Memgraph that isn't out yet, so
+    # their examples are checked when the release branch is merged into main.
+    if: github.event_name == 'pull_request' && github.base_ref == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      # The pages this PR changes: their Cypher examples run on the latest Memgraph, and the names in them are checked.
+      - run: python3 scripts/check-examples.py --base HEAD^1
+        env:
+          MEMGRAPH_ENTERPRISE_LICENSE: ${{ secrets.MEMGRAPH_ENTERPRISE_LICENSE }}
+          MEMGRAPH_ORGANIZATION_NAME: ${{ secrets.MEMGRAPH_ORGANIZATION_NAME }}

AGENTS.md

@@ -22,7 +22,9 @@ The short version, for everyone:
   old address that redirects, and to a `#section` that exists.
 - Images go in `public/pages/` and are linked as `/pages/...`, with alt text.
 - Every code block has a language; `cypher` blocks run as written on the
-  current release, and Cypher comments use `//`.
+  current release, and Cypher comments use `//`. A `cypher` block that isn't
+  meant to run says why in its fence: ` ```cypher template` (grammar such as
+  `[IF NOT EXISTS]`), `invalid` (wrong on purpose), `neo4j` or `output`.
 - A new page is added to its folder's `_meta.ts`, and no page is hidden. A
   renamed, moved or deleted page gets a redirect in `next.config.mjs`, and
   links to it are updated.
@@ -43,8 +45,10 @@ The short version, for everyone:
 pnpm i
 pnpm dev    # http://localhost:3000/docs
 pnpm check  # links, section links, redirects, sidebar and release-note versions
+python3 scripts/check-examples.py --base origin/main  # Cypher examples and names on the pages you changed; needs Docker
 ```
 
-`pnpm check` also runs on every PR, and a PR that fails it can't be merged. It reads only the
-checkout, takes a second and needs no install; `node scripts/check-docs.mjs`
-does the same.
+Both run on every PR.
+`pnpm check` reads only the checkout and takes a second. The examples check
+runs each changed page's `cypher` blocks on Memgraph in Docker and fails only
+on the blocks the PR changes; problems elsewhere on the page show as warnings.

pages/data-migration/migrate-from-neo4j/using-csv-files.mdx

@@ -85,7 +85,7 @@ schema below:
 
 To create this graph in your Neo4j instance run the following queries:
 
-```cypher
+```cypher neo4j
 LOAD CSV WITH HEADERS FROM 'https://gist.githubusercontent.com/jexp/054bc6baf36604061bf407aa8cd08608/raw/8bdd36dfc88381995e6823ff3f419b5a0cb8ac4f/orders.csv' AS column
 MERGE (order:Order {orderID: column.OrderID})
     ON CREATE SET order.shipName = column.ShipName;

pages/database-management/authentication-and-authorization/mlbac-migration-guide.mdx

@@ -28,7 +28,7 @@ Current label-based access control implementation was good for a number of use c
 
 **Before (v3.6):**
 Rules matched exact label sets only. By executing the following query:
-```cypher
+```cypher invalid
 GRANT READ ON LABELS :User
 ```
 
@@ -104,7 +104,7 @@ Global permissions only (grants on `*`)
 | CREATE_DELETE   | CREATE, READ, UPDATE, DELETE |
 
 Example:
-```cypher
+```cypher invalid
 // v3.6
 GRANT UPDATE ON LABELS * TO alice;
 

pages/fundamentals/data-types.mdx

@@ -72,7 +72,7 @@ CREATE (:Node {property: {key: "value"}});
 
 But these are not:
 
-```cypher
+```cypher invalid
 MATCH (n:Node) SET n.property[0] = 0;
 MATCH (n:Node) SET n.property.key = "other value";
 ```

pages/querying/clauses/call.mdx

@@ -312,7 +312,7 @@ RETURN DISTINCT n;
 
 The scoped `CALL (...)` form cannot be combined with `OPTIONAL`:
 
-```cypher
+```cypher invalid
 MATCH (p:Player)
 OPTIONAL CALL (p) {
   MATCH (p)-[:PLAYS_FOR]->(team:Team)

pages/querying/differences-in-cypher-implementations.mdx

@@ -100,7 +100,7 @@ Relationship uniqueness, existence, and type constraints are **not** supported a
 
 In Neo4j, to find the shortest possible path between two nodes, you would use the `shortestPath` algorithm:
 
-```cypher
+```cypher neo4j
 MATCH p=shortestPath(
 (:Person {name:"Keanu Reeves"})-[*]-(:Person {name:"Tom Hanks"})
 )
@@ -118,7 +118,7 @@ RETURN p
 
 In Neo4j, to find K shortest paths between two nodes, you would use the `SHORTEST` algorithm with a number:
 
-```cypher
+```cypher neo4j
 MATCH p = SHORTEST 3 (start:A)-[:E]->(end:B) 
 RETURN p;
 ```
@@ -136,7 +136,7 @@ Note that Memgraph requires both source and target nodes to be matched first usi
 
 ### NOT label expression
 In Neo4j, you can use the `NOT` label expression (`!`):
-```cypher
+```cypher neo4j
 MATCH (:Person {name:'Tom Hanks'})-[r:!ACTED_IN]->(m:Movie)
 Return type(r) AS type, m.title AS movies
 ```
@@ -150,7 +150,7 @@ RETURN type(r) AS type, m.title AS movies;
 ### Search for patterns of a fixed length
 
 In Neo4j, to search for patterns of a fixed length, you would use the following construct:
-```cypher
+```cypher neo4j
 MATCH (tom:Person {name:'Tom Hanks'})--{2}(colleagues:Person)
 RETURN DISTINCT colleagues.name AS name, colleagues.born AS bornIn
 ORDER BY bornIn
@@ -165,7 +165,7 @@ LIMIT 5
 ```
 
 Similarly, to match a graph for patterns of a variable length, you would run the following query in Neo4j:
-```cypher
+```cypher neo4j
 MATCH (p:Person {name:'Tom Hanks'})--{1,4}(colleagues:Person)
 RETURN DISTINCT colleagues.name AS name, colleagues.born AS bornIn
 ORDER BY bornIn, name
@@ -198,7 +198,7 @@ In other cases, Memgraph does not yet support patterns in functions, e.g. `size(
 
 {<h4 id="conditional-expressions-case" className="custom-header">Conditional expressions (<code>CASE</code>)</h4>}
 - More than one value after `WHEN` operator: 
-  ```cypher
+  ```cypher neo4j
   MATCH (n:Person)
   RETURN
   CASE n.eyes
@@ -221,7 +221,7 @@ In other cases, Memgraph does not yet support patterns in functions, e.g. `size(
 
 {<h4 id="type-predicate-expressions" className="custom-header">Type predicate expressions</h4>}
 The following expression is not supported in Memgraph:
-```cypher
+```cypher neo4j
 UNWIND [42, true, 'abc'] AS val
 RETURN val, val IS :: INTEGER AS isInteger
 ```