Tweak format changes

Breaking line(endAbsolute) onto multiple lines changed a bunch of tests

.github/workflows/e2e-tests.yml

@@ -3,7 +3,6 @@ on:
   push:
     branches: [ main ]
   pull_request:
-    branches: [ main ]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -161,11 +160,11 @@ jobs:
       continue-on-error: true
       run: rm -r test-results
     - name: check for changes
-      if: ${{ matrix.os == 'namespace-profile-ubuntu-8-cores' && matrix.shardIndex == 1 }}
+      if: ${{ matrix.os == 'namespace-profile-ubuntu-8-cores' && matrix.shardIndex == 1 && github.ref != 'refs/heads/main' }}
       shell: bash
       id: git-check
       run: |
-          git add .
+          git add e2e/playwright/snapshot-tests.spec.ts-snapshots
           if git status | grep -q "Changes to be committed"
           then echo "modified=true" >> $GITHUB_OUTPUT
           else echo "modified=false" >> $GITHUB_OUTPUT
@@ -174,14 +173,14 @@ jobs:
       if: steps.git-check.outputs.modified == 'true'
       shell: bash
       run: |
-        git add .
+        git add e2e/playwright/snapshot-tests.spec.ts-snapshots
         git config --local user.email "github-actions[bot]@users.noreply.github.com"
         git config --local user.name "github-actions[bot]"
         git remote set-url origin https://${{ github.actor }}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git
         git fetch origin
         echo ${{ github.head_ref }}
         git checkout ${{ github.head_ref }}
-        git commit -am "A snapshot a day keeps the bugs away! 📷🐛 (OS: ${{matrix.os}})" || true
+        git commit -m "A snapshot a day keeps the bugs away! 📷🐛 (OS: ${{matrix.os}})" || true
         git push
         git push origin ${{ github.head_ref }}
     # only upload artifacts if there's actually changes

docs/kcl/patternTransform2d.md

@@ -9,7 +9,7 @@ Just like patternTransform, but works on 2D sketches not 3D solids.
 
 
 ```js
-patternTransform2d(total_instances: integer, transform_function: FunctionParam, solid_set: SketchSet) -> [Sketch]
+patternTransform2d(total_instances: integer, transform_function: FunctionParam, solid_set: SketchSet, use_original?: bool) -> [Sketch]
 ```
 
 
@@ -20,6 +20,7 @@ patternTransform2d(total_instances: integer, transform_function: FunctionParam,
 | `total_instances` | `integer` |  | Yes |
 | `transform_function` | `FunctionParam` |  | Yes |
 | `solid_set` | [`SketchSet`](/docs/kcl/types/SketchSet) | A sketch or a group of sketches. | Yes |
+| `use_original` | `bool` |  | No |
 
 ### Returns
 

docs/kcl/types.md

@@ -47,21 +47,6 @@ myObj = { a = 0, b = "thing" }
 We support two different ways of getting properties from objects, you can call
 `myObj.a` or `myObj["a"]` both work.
 
-
-## Functions
-
-We also have support for defining your own functions. Functions can take in any
-type of argument. Below is an example of the syntax:
-
-```
-fn myFn(x) {
-  return x
-}
-```
-
-As you can see above `myFn` just returns whatever it is given.
-
-
 ## Binary expressions
 
 You can also do math! Let's show an example below:
@@ -76,6 +61,120 @@ You can nest expressions in parenthesis as well:
 myMathExpression = 3 + (1 * 2 / (3 - 7))
 ```
 
+## Functions
+
+We also have support for defining your own functions. Functions can take in any
+type of argument. Below is an example of the syntax:
+
+```
+fn myFn(x) {
+  return x
+}
+```
+
+As you can see above `myFn` just returns whatever it is given.
+
+KCL's early drafts used positional arguments, but we now use keyword arguments. If you declare a
+function like this:
+
+```
+fn add(left, right) {
+  return left + right
+}
+```
+
+You can call it like this:
+
+```
+total = add(left = 1, right = 2)
+```
+
+Functions can also declare one *unlabeled* arg. If you do want to declare an unlabeled arg, it must
+be the first arg declared.
+
+```
+// The @ indicates an argument can be used without a label.
+// Note that only the first argument can use @.
+fn increment(@x) {
+  return x + 1
+}
+
+fn add(@x, delta) {
+  return x + delta
+}
+
+two = increment(1)
+three = add(1, delta = 2)
+```
+
+## Pipelines
+
+It can be hard to read repeated function calls, because of all the nested brackets.
+
+```
+i = 1
+x = h(g(f(i)))
+```
+
+You can make this easier to read by breaking it into many declarations, but that is a bit annoying.
+
+```
+i  = 1
+x0 = f(i)
+x1 = g(x0)
+x  = h(x1)
+```
+
+Instead, you can use the pipeline operator (`|>`) to simplify this.
+
+Basically, `x |> f(%)` is a shorthand for `f(x)`. The left-hand side of the `|>` gets put into
+the `%` in the right-hand side.
+
+So, this means `x |> f(%) |> g(%)` is shorthand for `g(f(x))`. The code example above, with its
+somewhat-clunky `x0` and `x1` constants could be rewritten as
+
+```
+i = 1
+x = i
+|> f(%)
+|> g(%)
+|> h(%)
+```
+
+This helps keep your code neat and avoid unnecessary declarations.
+
+## Pipelines and keyword arguments
+
+Say you have a long pipeline of sketch functions, like this:
+
+```
+startSketch()
+|> line(%, end = [3, 4])
+|> line(%, end = [10, 10])
+|> line(%, end = [-13, -14])
+|> close(%)
+```
+
+In this example, each function call outputs a sketch, and it gets put into the next function call via
+the `%`, into the first (unlabeled) argument.
+
+If a function call uses an unlabeled first parameter, it will default to `%` if it's not given. This
+means that `|> line(%, end = [3, 4])` and `|> line(end = [3, 4])` are equivalent! So the above
+could be rewritten as 
+
+```
+startSketch()
+|> line(end = [3, 4])
+|> line(end = [10, 10])
+|> line(end = [-13, -14])
+|> close()
+```
+
+Note that we are still in the process of migrating KCL's standard library to use keyword arguments. So some
+functions are still unfortunately using positional arguments. We're moving them over, so keep checking back.
+Some functions like `angledLine`, `startProfileAt` etc are still using the old positional argument syntax.
+Check the docs page for each function and look at its examples to see.
+
 ## Tags
 
 Tags are used to give a name (tag) to a specific path.
@@ -88,17 +187,17 @@ way:
 ```
 startSketchOn('XZ')
   |> startProfileAt(origin, %)
-  |> angledLine([0, 191.26], %, $rectangleSegmentA001)
-  |> angledLine([
-       segAng(rectangleSegmentA001) - 90,
-       196.99
-     ], %, $rectangleSegmentB001)
-  |> angledLine([
-       segAng(rectangleSegmentA001),
-       -segLen(rectangleSegmentA001)
-     ], %, $rectangleSegmentC001)
-  |> lineTo([profileStartX(%), profileStartY(%)], %)
-  |> close(%)
+  |> angledLine({angle = 0, length = 191.26}, %, $rectangleSegmentA001)
+  |> angledLine({
+       angle = segAng(rectangleSegmentA001) - 90,
+       length = 196.99,
+     }, %, $rectangleSegmentB001)
+  |> angledLine({
+       angle = segAng(rectangleSegmentA001),
+       length = -segLen(rectangleSegmentA001),
+     }, %, $rectangleSegmentC001)
+  |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
+  |> close()
 ```
 
 ### Tag Identifier
@@ -121,17 +220,17 @@ However if the code was written like this:
 fn rect(origin) {
   return startSketchOn('XZ')
     |> startProfileAt(origin, %)
-    |> angledLine([0, 191.26], %, $rectangleSegmentA001)
-    |> angledLine([
-         segAng(rectangleSegmentA001) - 90,
-         196.99
-       ], %, $rectangleSegmentB001)
-    |> angledLine([
-         segAng(rectangleSegmentA001),
-         -segLen(rectangleSegmentA001)
-       ], %, $rectangleSegmentC001)
-    |> lineTo([profileStartX(%), profileStartY(%)], %)
-    |> close(%)
+    |> angledLine({angle = 0, length = 191.26}, %, $rectangleSegmentA001)
+    |> angledLine({
+         angle = segAng(rectangleSegmentA001) - 90,
+         length = 196.99
+       }, %, $rectangleSegmentB001)
+    |> angledLine({
+         angle = segAng(rectangleSegmentA001),
+         length = -segLen(rectangleSegmentA001)
+       }, %, $rectangleSegmentC001)
+    |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
+    |> close()
 }
 
 rect([0, 0])
@@ -149,17 +248,17 @@ For example the following code works.
 fn rect(origin) {
   return startSketchOn('XZ')
     |> startProfileAt(origin, %)
-    |> angledLine([0, 191.26], %, $rectangleSegmentA001)
-    |> angledLine([
-         segAng(rectangleSegmentA001) - 90,
-         196.99
-       ], %, $rectangleSegmentB001)
-    |> angledLine([
-         segAng(rectangleSegmentA001),
-         -segLen(rectangleSegmentA001)
-       ], %, $rectangleSegmentC001)
-    |> lineTo([profileStartX(%), profileStartY(%)], %)
-    |> close(%)
+    |> angledLine({angle = 0, length = 191.26}, %, $rectangleSegmentA001)
+    |> angledLine({
+         angle = segAng(rectangleSegmentA001) - 90,
+         length = 196.99
+       }, %, $rectangleSegmentB001)
+    |> angledLine({
+         angle = segAng(rectangleSegmentA001),
+         length = -segLen(rectangleSegmentA001)
+       }, %, $rectangleSegmentC001)
+    |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
+    |> close()
 }
 
 rect([0, 0])

docs/kcl/types/ArtifactId.md

@@ -0,0 +1,15 @@
+---
+title: "ArtifactId"
+excerpt: ""
+layout: manual
+---
+
+
+**Type:** `string` (`uuid`)
+
+
+
+
+
+
+

docs/kcl/types/CircularPattern2dData.md

@@ -20,5 +20,6 @@ Data for a circular pattern on a 2D sketch.
 | `center` |`[number, number]`| The center about which to make the pattern. This is a 2D vector. | No |
 | `arcDegrees` |`number`| The arc angle (in degrees) to place the repetitions. Must be greater than 0. | No |
 | `rotateDuplicates` |`boolean`| Whether or not to rotate the duplicates as they are copied. | No |
+| `useOriginal` |`boolean`| If the target being patterned is itself a pattern, then, should you use the original solid, or the pattern? | No |
 
 

docs/kcl/types/CircularPattern3dData.md

@@ -21,5 +21,6 @@ Data for a circular pattern on a 3D model.
 | `center` |`[number, number, number]`| The center about which to make the pattern. This is a 3D vector. | No |
 | `arcDegrees` |`number`| The arc angle (in degrees) to place the repetitions. Must be greater than 0. | No |
 | `rotateDuplicates` |`boolean`| Whether or not to rotate the duplicates as they are copied. | No |
+| `useOriginal` |`boolean`| If the target being patterned is itself a pattern, then, should you use the original solid, or the pattern? | No |
 
 

docs/kcl/types/Face.md

@@ -17,6 +17,7 @@ A face.
 | Property | Type | Description | Required |
 |----------|------|-------------|----------|
 | `id` |`string`| The id of the face. | No |
+| `artifactId` |[`ArtifactId`](/docs/kcl/types/ArtifactId)| The artifact ID. | No |
 | `value` |`string`| The tag of the face. | No |
 | `xAxis` |[`Point3d`](/docs/kcl/types/Point3d)| What should the face’s X axis be? | No |
 | `yAxis` |[`Point3d`](/docs/kcl/types/Point3d)| What should the face’s Y axis be? | No |

docs/kcl/types/Helix.md

@@ -17,6 +17,7 @@ A helix.
 | Property | Type | Description | Required |
 |----------|------|-------------|----------|
 | `value` |`string`| The id of the helix. | No |
+| `artifactId` |[`ArtifactId`](/docs/kcl/types/ArtifactId)| The artifact ID. | No |
 | `revolutions` |`number`| Number of revolutions. | No |
 | `angleStart` |`number`| Start angle (in degrees). | No |
 | `ccw` |`boolean`| Is the helix rotation counter clockwise? | No |

docs/kcl/types/HelixData.md

@@ -1,26 +0,0 @@
----
-title: "HelixData"
-excerpt: "Data for a helix."
-layout: manual
----
-
-Data for a helix.
-
-**Type:** `object`
-
-
-
-
-
-## Properties
-
-| Property | Type | Description | Required |
-|----------|------|-------------|----------|
-| `revolutions` |`number`| Number of revolutions. | No |
-| `angleStart` |`number`| Start angle (in degrees). | No |
-| `ccw` |`boolean`| Is the helix rotation counter clockwise? The default is `false`. | No |
-| `length` |`number`| Length of the helix. This is not necessary if the helix is created around an edge. If not given the length of the edge is used. | No |
-| `radius` |`number`| Radius of the helix. | No |
-| `axis` |[`Axis3dOrEdgeReference`](/docs/kcl/types/Axis3dOrEdgeReference)| Axis to use as mirror. | No |
-
-

docs/kcl/types/HelixValue.md

@@ -17,6 +17,7 @@ A helix.
 | Property | Type | Description | Required |
 |----------|------|-------------|----------|
 | `value` |`string`| The id of the helix. | No |
+| `artifactId` |[`ArtifactId`](/docs/kcl/types/ArtifactId)| The artifact ID. | No |
 | `revolutions` |`number`| Number of revolutions. | No |
 | `angleStart` |`number`| Start angle (in degrees). | No |
 | `ccw` |`boolean`| Is the helix rotation counter clockwise? | No |

docs/kcl/types/Plane.md

@@ -17,6 +17,7 @@ A plane.
 | Property | Type | Description | Required |
 |----------|------|-------------|----------|
 | `id` |`string`| The id of the plane. | No |
+| `artifactId` |[`ArtifactId`](/docs/kcl/types/ArtifactId)| The artifact ID. | No |
 | `value` |[`PlaneType`](/docs/kcl/types/PlaneType)| A plane. | No |
 | `origin` |[`Point3d`](/docs/kcl/types/Point3d)| Origin of the plane. | No |
 | `xAxis` |[`Point3d`](/docs/kcl/types/Point3d)| What should the plane’s X axis be? | No |

docs/kcl/types/Sketch.md

@@ -21,6 +21,8 @@ A sketch is a collection of paths.
 | `on` |[`SketchSurface`](/docs/kcl/types/SketchSurface)| What the sketch is on (can be a plane or a face). | No |
 | `start` |[`BasePath`](/docs/kcl/types/BasePath)| The starting path. | No |
 | `tags` |`object`| Tag identifiers that have been declared in this sketch. | No |
+| `artifactId` |[`ArtifactId`](/docs/kcl/types/ArtifactId)| The original id of the sketch. This stays the same even if the sketch is is sketched on face etc. | No |
+| `originalId` |`string`|  | No |
 | `units` |[`UnitLen`](/docs/kcl/types/UnitLen)| A sketch is a collection of paths. | No |
 | `__meta` |`[` [`Metadata`](/docs/kcl/types/Metadata) `]`| Metadata. | No |
 

docs/kcl/types/SketchSet.md

@@ -30,6 +30,8 @@ A sketch is a collection of paths.
 | `on` |[`SketchSurface`](/docs/kcl/types/SketchSurface)| What the sketch is on (can be a plane or a face). | No |
 | `start` |[`BasePath`](/docs/kcl/types/BasePath)| The starting path. | No |
 | `tags` |`object`| Tag identifiers that have been declared in this sketch. | No |
+| `artifactId` |[`ArtifactId`](/docs/kcl/types/ArtifactId)| The original id of the sketch. This stays the same even if the sketch is is sketched on face etc. | No |
+| `originalId` |`string`|  | No |
 | `units` |[`UnitLen`](/docs/kcl/types/UnitLen)| A sketch or a group of sketches. | No |
 | `__meta` |`[` [`Metadata`](/docs/kcl/types/Metadata) `]`| Metadata. | No |
 

docs/kcl/types/SketchSurface.md

@@ -26,6 +26,7 @@ A plane.
 |----------|------|-------------|----------|
 | `type` |enum: `plane`|  | No |
 | `id` |`string`| The id of the plane. | No |
+| `artifactId` |[`ArtifactId`](/docs/kcl/types/ArtifactId)| The artifact ID. | No |
 | `value` |[`PlaneType`](/docs/kcl/types/PlaneType)| A sketch type. | No |
 | `origin` |[`Point3d`](/docs/kcl/types/Point3d)| Origin of the plane. | No |
 | `xAxis` |[`Point3d`](/docs/kcl/types/Point3d)| What should the plane’s X axis be? | No |
@@ -50,6 +51,7 @@ A face.
 |----------|------|-------------|----------|
 | `type` |enum: `face`|  | No |
 | `id` |`string`| The id of the face. | No |
+| `artifactId` |[`ArtifactId`](/docs/kcl/types/ArtifactId)| The artifact ID. | No |
 | `value` |`string`| The tag of the face. | No |
 | `xAxis` |[`Point3d`](/docs/kcl/types/Point3d)| What should the face’s X axis be? | No |
 | `yAxis` |[`Point3d`](/docs/kcl/types/Point3d)| What should the face’s Y axis be? | No |

docs/kcl/types/Solid.md

@@ -17,6 +17,7 @@ An solid is a collection of extrude surfaces.
 | Property | Type | Description | Required |
 |----------|------|-------------|----------|
 | `id` |`string`| The id of the solid. | No |
+| `artifactId` |[`ArtifactId`](/docs/kcl/types/ArtifactId)| The artifact ID of the solid.  Unlike `id`, this doesn't change. | No |
 | `value` |`[` [`ExtrudeSurface`](/docs/kcl/types/ExtrudeSurface) `]`| The extrude surfaces. | No |
 | `sketch` |[`Sketch`](/docs/kcl/types/Sketch)| The sketch. | No |
 | `height` |`number`| The height of the solid. | No |

docs/kcl/types/SolidSet.md

@@ -26,6 +26,7 @@ An solid is a collection of extrude surfaces.
 |----------|------|-------------|----------|
 | `type` |enum: `solid`|  | No |
 | `id` |`string`| The id of the solid. | No |
+| `artifactId` |[`ArtifactId`](/docs/kcl/types/ArtifactId)| The artifact ID of the solid.  Unlike `id`, this doesn't change. | No |
 | `value` |`[` [`ExtrudeSurface`](/docs/kcl/types/ExtrudeSurface) `]`| The extrude surfaces. | No |
 | `sketch` |[`Sketch`](/docs/kcl/types/Sketch)| The sketch. | No |
 | `height` |`number`| The height of the solid. | No |

e2e/playwright/can-create-sketches-on-all-planes-and-their-back-sides.spec.ts

@@ -19,6 +19,8 @@ test.describe(
       await page.setBodyDimensions({ width: 1200, height: 500 })
 
       await homePage.goToModelingScene()
+      // FIXME: Cannot use scene.waitForExecutionDone() since there is no KCL code
+      await page.waitForTimeout(10000)
       await u.openDebugPanel()
 
       const coord =

e2e/playwright/code-pane-and-errors.spec.ts

@@ -10,6 +10,7 @@ test.describe('Code pane and errors', { tag: ['@skipWin'] }, () => {
   test('Typing KCL errors induces a badge on the code pane button', async ({
     page,
     homePage,
+    scene,
   }) => {
     const u = await getUtils(page)
 
@@ -30,11 +31,7 @@ test.describe('Code pane and errors', { tag: ['@skipWin'] }, () => {
 
     await page.setBodyDimensions({ width: 1200, height: 500 })
     await homePage.goToModelingScene()
-
-    // wait for execution done
-    await u.openDebugPanel()
-    await u.expectCmdLog('[data-message-type="execution-done"]')
-    await u.closeDebugPanel()
+    await scene.waitForExecutionDone()
 
     // Ensure no badge is present
     const codePaneButtonHolder = page.locator('#code-button-holder')
@@ -175,7 +172,9 @@ test.describe('Code pane and errors', { tag: ['@skipWin'] }, () => {
     await page.setBodyDimensions({ width: 1200, height: 500 })
     await homePage.goToModelingScene()
 
-    await page.waitForTimeout(1000)
+    // FIXME: await scene.waitForExecutionDone() does not work. It still fails.
+    // I needed to increase this timeout to get this to pass.
+    await page.waitForTimeout(10000)
 
     // Ensure badge is present
     const codePaneButtonHolder = page.locator('#code-button-holder')
@@ -187,7 +186,7 @@ test.describe('Code pane and errors', { tag: ['@skipWin'] }, () => {
     // click in the editor to focus it
     await page.locator('.cm-content').click()
 
-    await page.waitForTimeout(500)
+    await page.waitForTimeout(2000)
 
     // go to the start of the editor and enter more text which will trigger
     // a lint error.
@@ -204,8 +203,9 @@ test.describe('Code pane and errors', { tag: ['@skipWin'] }, () => {
     await page.keyboard.press('ArrowUp')
     await page.keyboard.press('Home')
     await page.keyboard.type('foo_bar = 1')
-    await page.waitForTimeout(500)
+    await page.waitForTimeout(2000)
     await page.keyboard.press('Enter')
+    await page.waitForTimeout(2000)
 
     // ensure we have a lint error
     await expect(page.locator('.cm-lint-marker-info').first()).toBeVisible()

e2e/playwright/command-bar-tests.spec.ts

@@ -174,6 +174,9 @@ test.describe('Command bar tests', { tag: ['@skipWin'] }, () => {
       await page.setBodyDimensions({ width: 1200, height: 500 })
       await homePage.goToModelingScene()
 
+      // FIXME: No KCL code, unable to wait for engine execution
+      await page.waitForTimeout(10000)
+
       await expect(
         page.getByRole('button', { name: 'Start Sketch' })
       ).not.toBeDisabled()

e2e/playwright/desktop-export.spec.ts

@@ -9,8 +9,8 @@ import fsp from 'fs/promises'
 
 test(
   'export works on the first try',
-  { tag: '@electron' },
-  async ({ page, context }, testInfo) => {
+  { tag: ['@electron', '@skipLocalEngine'] },
+  async ({ page, context, scene }, testInfo) => {
     await context.folderSetupFn(async (dir) => {
       const bracketDir = path.join(dir, 'bracket')
       await Promise.all([fsp.mkdir(bracketDir, { recursive: true })])
@@ -118,8 +118,9 @@ test(
       // Close the file pane
       await u.closeFilePanel()
 
-      // wait for it to finish executing (todo: make this more robust)
-      await page.waitForTimeout(1000)
+      // FIXME: await scene.waitForExecutionDone() does not work. The modeling indicator stays in -receive-reliable and not execution done
+      await page.waitForTimeout(10000)
+
       // expect zero errors in guter
       await expect(page.locator('.cm-lint-marker-error')).not.toBeVisible()
 

e2e/playwright/editor-tests.spec.ts

@@ -490,6 +490,11 @@ test.describe('Editor tests', { tag: ['@skipWin'] }, () => {
     await page.keyboard.press('ArrowLeft')
     await page.keyboard.press('ArrowRight')
 
+    // FIXME: lsp errors do not propagate to the frontend until engine is connected and code is executed
+    // This timeout is to wait for engine connection. LSP and code execution errors should be handled differently
+    // LSP can emit errors as fast as it waits and show them in the editor
+    await page.waitForTimeout(10000)
+
     // error in guter
     await expect(page.locator('.cm-lint-marker-info').first()).toBeVisible()
 
@@ -641,7 +646,7 @@ test.describe('Editor tests', { tag: ['@skipWin'] }, () => {
     width = 0.500
     height = 0.500
     dia = 4
-  
+
     fn squareHole = (l, w) => {
   squareHoleSketch = startSketchOn('XY')
   |> startProfileAt([-width / 2, -length / 2], %)
@@ -714,7 +719,7 @@ test.describe('Editor tests', { tag: ['@skipWin'] }, () => {
     |> line(end = [0, -10], tag = $revolveAxis)
     |> close()
     |> extrude(length = 10)
-  
+
     sketch001 = startSketchOn(box, revolveAxis)
     |> startProfileAt([5, 10], %)
     |> line(end = [0, -10])