setup static scanning (#21)

no longer using '/spec/' in path
fix typos
updated theme
added a json include example in the docs as a placeholder

.devcontainer/devcontainer.json

@@ -6,7 +6,9 @@
             "extensions": [
                 "ms-azuretools.vscode-docker",
                 "Redocly.openapi-vs-code",
-                "emeraldwalk.RunOnSave"
+                "emeraldwalk.RunOnSave",
+                "42Crunch.vscode-openapi",
+                "stoplight.spectral"
             ]
         }
     },

.github/workflows/lint.yaml

@@ -0,0 +1,27 @@
+name: 'OpenAPI lint'
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - 1.0.0*
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: "Bundle and Build"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Lint
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: >-
+          npx --yes @redocly/cli bundle ./docs/_data/openapi-split.yaml -o ./docs/openapi.yaml &&
+          npx @redocly/cli lint ./docs/openapi.yaml

.github/workflows/owasp.yaml

@@ -0,0 +1,27 @@
+name: 'OWASP Spectral lint'
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - 1.0.0*
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: "Bundle and Build"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Lint
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: >-
+          npx --yes @redocly/cli bundle ./docs/_data/openapi-split.yaml -o ./docs/openapi.yaml &&
+          npx --yes @stoplight/spectral-cli lint docs/openapi.yaml --ruleset https://unpkg.com/@stoplight/spectral-owasp-ruleset/dist/ruleset.mjs

.vscode/settings.json

@@ -8,5 +8,10 @@
                 "cmd": ".devcontainer/post.sh bundle"
             }
         ]
-    }
+    },
+    // note this only covers the 2019 top ten https://github.com/stoplightio/spectral-owasp-ruleset/issues/47
+    "spectral.rulesetFile": "https://unpkg.com/@stoplight/spectral-owasp-ruleset/dist/ruleset.mjs",
+    "spectral.validateFiles": [
+        "**/docs/openapi.yaml"
+    ]
 }

README.md

@@ -1,3 +1,6 @@
+![Redocly Lint](https://github.com/TROLIE/spec/actions/workflows/lint/badge.svg)
+![Spectral OWASP Scan](https://github.com/TROLIE/spec/actions/workflows/owasp/badge.svg)
+
 # TROLIE
 
 Transmission Ratings and Operating Limits Information Exchange
@@ -14,17 +17,17 @@ Transmission Ratings and Operating Limits Information Exchange
   <img alt="Official LF Energy Project logo" src="https://artwork.lfenergy.org/other/lf-energy-project/horizontal/color/lf-energy-project-horizontal-color.png" width="200">
 </picture>
 
-## Specification Editors
+## To Specification Editors
 
 The `docs/` folder contains a Jekyll site for the GH Pages along with the yaml
-that is used with `redocly bundle` to created the OpenAPI specification.
+that is used with `redocly bundle` to create the OpenAPI specification.
 
-To simply the local setup of the toolchain, a devcontainer is provided. This
-will also install VS Code extensions to help with local editing as well.
+To simplify the local setup of the toolchain, a devcontainer is provided. This
+will also install VS Code extensions to help with local editing.
 
 If your company uses MITM, self-signed certificates through your Internet proxy
 and/or proxies upstream RubyGem or npm repos, please follow the instructions in
-the next section.
+the next section to get the local devcontainer editing experience working.
 
 ### Self-Signed Certs and Repo Proxies
 

docs/_config.yml

@@ -3,13 +3,15 @@ email: [email protected]
 
 description: >-
  Transmission Ratings and Operating Limits Information Exchange 
-baseurl: "/" # the subpath of your site, e.g. /blog
 url: "https://trolie.energy" # the base hostname & protocol for your site, e.g. http://example.com
+logo: https://artwork.lfenergy.org/projects/trolie/horizontal/color/TROLIE-horizontal-color.png
 # twitter_username: jekyllrb
 github_username: TROLIE
 
 # Build settings
-remote_theme: pages-themes/[email protected]
+remote_theme: pages-themes/[email protected]
+
+show_downloads: false
 
 plugins:
   - jekyll-remote-theme

docs/_data/examples/forecast-limits-slim.json

@@ -0,0 +1,31 @@
+[
+    {
+        "transmission-facility-id": "line2",
+        "periods": [
+            {
+                "period-start": "2023-07-12T16:00:00-07:00",
+                "updated-time": "2023-07-12T13:05:43.044267100-07:00",
+                "values": [
+                    {
+                        "type": "normal",
+                        "value": {
+                            "mva": 160
+                        }
+                    },
+                    {
+                        "type": "emergency",
+                        "value": {
+                            "mva": 165
+                        }
+                    },
+                    {
+                        "type": "loadshed",
+                        "value": {
+                            "mva": 170
+                        }
+                    }
+                ]
+            }
+        ]
+    }
+]

docs/_data/paths/limits_forecast-snapshot.yaml

@@ -27,20 +27,7 @@ get:
           schema:
             $ref: ../components/schemas/forecast-limit-set.yaml
           example:
-            - transmission-facility-id: line2
-              periods:
-                - period-start: '2023-07-12T16:00:00-07:00'
-                  updated-time: '2023-07-12T13:05:43.044267100-07:00'
-                  values:
-                    - type: normal
-                      value:
-                        mva: 160
-                    - type: emergency
-                      value:
-                        mva: 165
-                    - type: loadshed
-                      value:
-                        mva: 170
+            $ref: ../examples/forecast-limits-slim.json
         application/vnd.trolie.forecast-limit-set-detailed.v1+json:
           schema:
             $ref: ../components/schemas/forecast-limit-set-detailed.yaml

docs/index.md

@@ -18,3 +18,8 @@ title: Home
 <picture>
   <img alt="Official LF Energy Project logo" src="https://artwork.lfenergy.org/other/lf-energy-project/horizontal/color/lf-energy-project-horizontal-color.png" width="200">
 </picture>
+
+### Example:
+```json
+{% include_relative _data/examples/forecast-limits-slim.json %}
+```

redocly.yaml

@@ -4,4 +4,11 @@ apis:
 extends:
   - recommended-strict
 rules:
-  operation-summary: warn
+  operation-summary: warn
+  rule/path-item-get-operation-defined:
+    subject:
+      type: MediaType
+      property: example
+    assertions:
+      defined: true
+    severity: warn