feat: add rule DOK.08

Signed-off-by: Mats Johansson <extern.mats.johansson@digg.se>

Author: mmjohansson

.prettierrc

@@ -6,6 +6,6 @@
   "printWidth": 120,
   "htmlWhitespaceSensitivity": "ignore",
   "bracketSameLine": false,
-  "vueIndentScriptAndStyle": true
+  "vueIndentScriptAndStyle": true,
+  "trailingComma": "all"
 }
-

GUIDELINES.md

@@ -34,6 +34,7 @@ Detta dokument specificerar reglerna som verktyget tillämpar.
    - [ID: DOK.03](#id-dok03)
    - [ID: DOK.06](#id-dok06)
    - [ID: DOK.07](#id-dok07)
+   - [ID: DOK.08](#id-dok08)
    - [ID: DOK.15](#id-dok15)
    - [ID: DOK.17](#id-dok17)
    - [ID: DOK.19](#id-dok19)
@@ -79,8 +80,7 @@ Detta dokument specificerar reglerna som verktyget tillämpar.
    - [ID: SAK.16](#id-sak16)
    - [ID: SAK.18](#id-sak18)
 10. [Område: Förutsättningar](#område-förutsättningar)
-
-- [ID: FOR.02](#id-for02)
+    - [ID: FOR.02](#id-for02)
 
 ## Område: Dokumentation
 
@@ -203,6 +203,43 @@ Regeln förutsätter att det finns en förekomst av objektet `info` med underlig
 
 ---
 
+### ID: DOK.08
+
+**Krav:** Ett API:s servicenivå SKALL finnas tydligt beskriven i dokumentationen.
+
+**Typ:** SKALL
+
+**JSON Path Plus-uttryck:**
+
+```
+$
+```
+
+**Förklaring:**
+Regeln förutsätter att det finns en förekomst av minst ett av objekten `info.termsOfService`, `info.x-sla` eller `externalDocs` med följande strukturer:
+
+- info
+
+  - termsOfService
+  - x-sla
+    - availability
+    - responseTime
+    - support
+
+- externalDocs
+  - description
+  - url
+
+`externalDocs.description` måste innehålla texten "service level agreement" eller "SLA", och `externalDocs.url` måste vara en giltig URL.
+
+**Exempel:**
+
+![Exempelbild på ovan nämnda objekts placering i en OpenAPI Description](images/dok8.png)
+
+_Ett av objekten räcker för att uppfylla regeln._
+
+---
+
 ### ID: DOK.15
 
 **Krav:** I dokumentationen av API:et SKALL exempel på API:ets fråga (en:request) och svar (en:reply) finnas i sin helhet.

REUSE.toml

@@ -34,6 +34,7 @@ path = [
     "images/dok6-1.png",
     "images/dok6-2.png",
     "images/dok7.png",
+    "images/dok8.png",
     "images/dot1-2.png",
     "images/dot1.png",
     "images/dot4.png",

images/dok8.png

@@ -214,6 +214,78 @@ export class Dok07 extends BaseRuleset {
   }
   severity = DiagnosticSeverity.Warning;
 }
+export class Dok08 extends BaseRuleset {
+  static customProperties: CustomProperties = {
+    område: 'Dokumentation',
+    id: 'DOK.08',
+  };
+  given = '$';
+  message = 'Ett API:s servicenivå SKALL finnas tydligt beskriven i dokumentationen.';
+  then = [
+    {
+      function: (targetVal: any, _opts: string, paths: string[]) => {
+        const isValidUrl = (url: string): boolean => {
+          const urlPattern = new RegExp('^(https?:\\/\\/)?(www\\.)?([a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}(\\/\\S*)?$');
+          return urlPattern.test(url);
+        };
+
+        const hasValidSlaFields = (sla: any): boolean => {
+          return !!(sla?.availability && sla?.responseTime && sla?.support);
+        };
+
+        const includesSlaTerm = (description: string): boolean => {
+          const slaTerms = ['service level agreement', 'sla'];
+          return slaTerms.some((term) => description.includes(term));
+        };
+
+        if (targetVal?.info?.termsOfService) {
+          return [];
+        }
+
+        const customSlaField = targetVal?.info?.['x-sla'];
+        if (customSlaField && hasValidSlaFields(customSlaField)) {
+          return [];
+        }
+
+        const externalDocs = targetVal?.externalDocs;
+        if (
+          externalDocs?.description &&
+          externalDocs?.url &&
+          isValidUrl(externalDocs.url) &&
+          includesSlaTerm(externalDocs.description.toLowerCase())
+        ) {
+          return [];
+        }
+
+        return [
+          {
+            message: this.message,
+            severity: this.severity,
+            paths: paths,
+          },
+        ];
+      },
+    },
+    {
+      function: (targetVal: string, _opts: string, paths: string[]) => {
+        this.trackRuleExecutionHandler(
+          JSON.stringify(targetVal, null, 2),
+          _opts,
+          paths,
+          this.severity,
+          this.constructor.name,
+          moduleName,
+          Dok08.customProperties,
+        );
+      },
+    },
+  ];
+  constructor() {
+    super();
+    super.initializeFormats(['OAS2', 'OAS3']);
+  }
+  severity = DiagnosticSeverity.Error;
+}
 export class Dok19 extends BaseRuleset {
   static customProperties: CustomProperties = {
     område: 'Dokumentation',

rulesets/DokRules.ts

@@ -185,6 +185,138 @@ testRule('Dok07', [
     ],
   },
 ]);
+testRule('Dok08', [
+  {
+    name: 'giltigt testfall - info.termsOfService finns',
+    document: {
+      openapi: '3.1.0',
+      info: {
+        version: '1.0',
+        termsOfService: 'https://url-till-servicelevel-agreement.com/api-sla',
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'giltigt testfall - info.x-sla finns med samtliga tre fält',
+    document: {
+      openapi: '3.1.0',
+      info: {
+        version: '1.0',
+        'x-sla': {
+          availability: 'test',
+          responseTime: 24,
+          support: '24/7',
+        },
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'ogiltigt testfall - info.x-sla finns men ett fält saknas',
+    document: {
+      openapi: '3.1.0',
+      info: {
+        version: '1.0',
+        'x-sla': {
+          availability: 'test',
+          responseTime: 24,
+        },
+      },
+    },
+    errors: [
+      {
+        message: 'Ett API:s servicenivå SKALL finnas tydligt beskriven i dokumentationen.',
+        severity: DiagnosticSeverity.Error,
+      },
+    ],
+  },
+  {
+    name: 'giltigt testfall - externalDocs finns med giltig url och description',
+    document: {
+      openapi: '3.1.0',
+      info: {
+        version: '1.0',
+      },
+      externalDocs: {
+        description: 'Text som innehåller service level agreement',
+        url: 'https://sla.se',
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'ogiltigt testfall - externalDocs finns men description saknar "service level agreement"',
+    document: {
+      openapi: '3.1.0',
+      info: {
+        version: '1.0',
+      },
+      externalDocs: {
+        description: 'Text som inte innehåller vad den ska',
+        url: 'https://sla.se',
+      },
+    },
+    errors: [
+      {
+        message: 'Ett API:s servicenivå SKALL finnas tydligt beskriven i dokumentationen.',
+        severity: DiagnosticSeverity.Error,
+      },
+    ],
+  },
+  {
+    name: 'ogiltigt testfall - externalDocs finns men url:en är ogiltig',
+    document: {
+      openapi: '3.1.0',
+      info: {
+        version: '1.0',
+      },
+      externalDocs: {
+        description: 'Text som innehåller service level agreement',
+        url: 'ftp:/sla.se',
+      },
+    },
+    errors: [
+      {
+        message: 'Ett API:s servicenivå SKALL finnas tydligt beskriven i dokumentationen.',
+        severity: DiagnosticSeverity.Error,
+      },
+    ],
+  },
+  {
+    name: 'ogiltigt testfall - externalDocs finns men ett fält saknas',
+    document: {
+      openapi: '3.1.0',
+      info: {
+        version: '1.0',
+      },
+      externalDocs: {
+        description: 'Text som innehåller service level agreement',
+      },
+    },
+    errors: [
+      {
+        message: 'Ett API:s servicenivå SKALL finnas tydligt beskriven i dokumentationen.',
+        severity: DiagnosticSeverity.Error,
+      },
+    ],
+  },
+  {
+    name: 'ogiltigt testfall - SLA saknas helt',
+    document: {
+      openapi: '3.1.0',
+      info: {
+        version: '1.0',
+      },
+    },
+    errors: [
+      {
+        message: 'Ett API:s servicenivå SKALL finnas tydligt beskriven i dokumentationen.',
+        severity: DiagnosticSeverity.Error,
+      },
+    ],
+  },
+]);
 testRule('Dok17', [
   {
     name: 'giltigt testfall',

tests/dok.test.ts

@@ -59,6 +59,7 @@ const ruleTypes = [
   DokRules.Dok20,
   DokRules.Dok06,
   DokRules.Dok07,
+  DokRules.Dok08,
   FelRules.Fel01,
   FelRules.Fel02,
   FnsRules.Fns08,