WIP

Author: enisdenjo

scripts/audit-implementation.mjs

@@ -34,6 +34,7 @@ async function main() {
   const counts = {
     total: 0,
     ok: 0,
+    notice: 0,
     warn: 0,
     error: 0,
   };
@@ -42,6 +43,9 @@ async function main() {
     if (result.status === 'ok') {
       counts.ok++;
     }
+    if (result.status === 'notice') {
+      counts.notice++;
+    }
     if (result.status === 'warn') {
       counts.warn++;
     }

src/__tests__/__snapshots__/audits.ts.snap

@@ -42,10 +42,38 @@ exports[`should not change globally unique audit ids 1`] = `
     "id": "9C48",
     "name": "MAY NOT allow executing mutations on GET requests",
   },
+  {
+    "id": "9ABE",
+    "name": "MAY respond with 4xx status code if content-type is not supplied on POST requests",
+  },
   {
     "id": "03D4",
     "name": "MUST accept application/json POST requests",
   },
+  {
+    "id": "A5BF",
+    "name": "MAY use 400 status code when request body is missing on POST",
+  },
+  {
+    "id": "423L",
+    "name": "MAY use 400 status code on missing {query} parameter",
+  },
+  {
+    "id": "LKJ0",
+    "name": "MAY use 400 status code on object {query} parameter",
+  },
+  {
+    "id": "LKJ1",
+    "name": "MAY use 400 status code on number {query} parameter",
+  },
+  {
+    "id": "LKJ2",
+    "name": "MAY use 400 status code on boolean {query} parameter",
+  },
+  {
+    "id": "LKJ3",
+    "name": "MAY use 400 status code on array {query} parameter",
+  },
   {
     "id": "34A2",
     "name": "SHOULD allow string {query} parameter when accepting application/graphql-response+json",
@@ -54,6 +82,22 @@ exports[`should not change globally unique audit ids 1`] = `
     "id": "13EE",
     "name": "MUST allow string {query} parameter when accepting application/json",
   },
+  {
+    "id": "6C00",
+    "name": "MAY use 400 status code on object {operationName} parameter",
+  },
+  {
+    "id": "6C01",
+    "name": "MAY use 400 status code on number {operationName} parameter",
+  },
+  {
+    "id": "6C02",
+    "name": "MAY use 400 status code on boolean {operationName} parameter",
+  },
+  {
+    "id": "6C03",
+    "name": "MAY use 400 status code on array {operationName} parameter",
+  },
   {
     "id": "8161",
     "name": "SHOULD allow string {operationName} parameter when accepting application/graphql-response+json",
@@ -86,6 +130,22 @@ exports[`should not change globally unique audit ids 1`] = `
     "id": "0222",
     "name": "MUST allow null {extensions} parameter when accepting application/json",
   },
+  {
+    "id": "4760",
+    "name": "MAY use 400 status code on string {variables} parameter",
+  },
+  {
+    "id": "4761",
+    "name": "MAY use 400 status code on number {variables} parameter",
+  },
+  {
+    "id": "4762",
+    "name": "MAY use 400 status code on boolean {variables} parameter",
+  },
+  {
+    "id": "4763",
+    "name": "MAY use 400 status code on array {variables} parameter",
+  },
   {
     "id": "2EA1",
     "name": "SHOULD allow map {variables} parameter when accepting application/graphql-response+json",
@@ -102,6 +162,22 @@ exports[`should not change globally unique audit ids 1`] = `
     "id": "6A70",
     "name": "MAY allow URL-encoded JSON string {variables} parameter in GETs when accepting application/json",
   },
+  {
+    "id": "58B0",
+    "name": "MAY use 400 status code on string {extensions} parameter",
+  },
+  {
+    "id": "58B1",
+    "name": "MAY use 400 status code on number {extensions} parameter",
+  },
+  {
+    "id": "58B2",
+    "name": "MAY use 400 status code on boolean {extensions} parameter",
+  },
+  {
+    "id": "58B3",
+    "name": "MAY use 400 status code on array {extensions} parameter",
+  },
   {
     "id": "428F",
     "name": "SHOULD allow map {extensions} parameter when accepting application/graphql-response+json",
@@ -110,6 +186,22 @@ exports[`should not change globally unique audit ids 1`] = `
     "id": "1B7A",
     "name": "MUST allow map {extensions} parameter when accepting application/json",
   },
+  {
+    "id": "B6DC",
+    "name": "MAY use 4xx or 5xx status codes on JSON parsing failure",
+  },
+  {
+    "id": "BCF8",
+    "name": "MAY use 400 status code on JSON parsing failure",
+  },
+  {
+    "id": "8764",
+    "name": "MAY use 4xx or 5xx status codes if parameters are invalid",
+  },
+  {
+    "id": "3E3A",
+    "name": "MAY use 400 status code if parameters are invalid",
+  },
   {
     "id": "572B",
     "name": "SHOULD use 200 status code on document parsing failure when accepting application/json",

src/audits/common.ts

@@ -9,7 +9,10 @@
  *
  * @category Audits
  */
-export type AuditRequirement = 'MUST' | 'SHOULD' | 'MAY';
+export type AuditRequirement =
+  | 'MUST' // error
+  | 'SHOULD' // warning
+  | 'MAY'; // notice (suggestion)
 
 /**
  * Audit name starting with the audit requirement level.
@@ -67,7 +70,7 @@ export interface AuditFail {
    */
   id: string;
   name: AuditName;
-  status: 'warn' | 'error';
+  status: 'notice' | 'warn' | 'error';
   reason: string;
   response: Response;
 }

src/audits/render.ts

@@ -10,6 +10,7 @@ export async function renderAuditResultsToHTML(results: AuditResult[]) {
   const grouped = {
     total: 0,
     ok: [] as AuditOk[],
+    notice: [] as AuditFail[],
     warn: [] as AuditFail[],
     error: [] as AuditFail[],
   };
@@ -34,6 +35,9 @@ export async function renderAuditResultsToHTML(results: AuditResult[]) {
   if (grouped.ok.length) {
     report += `<li><span style="font-family: monospace">✅</span> <b>${grouped.ok.length}</b> pass</li>\n`;
   }
+  if (grouped.notice.length) {
+    report += `<li><span style="font-family: monospace">💡</span> <b>${grouped.notice.length}</b> notices (suggestions)</li>\n`;
+  }
   if (grouped.warn.length) {
     // TODO: warning sign is rendered as "⚠️" in markdown instead of the emoji
     report += `<li><span style="font-family: monospace">⚠️</span> <b>${grouped.warn.length}</b> warnings (optional)</li>\n`;
@@ -54,6 +58,18 @@ export async function renderAuditResultsToHTML(results: AuditResult[]) {
     report += '\n';
   }
 
+  if (grouped.notice.length) {
+    report += `<h2>Notices</h2>\n`;
+    report +=
+      'The server <i>MAY</i> support these, but are truly optional. These are suggestions following recommended conventions.\n';
+    report += '<ol>\n';
+    for (const [, result] of grouped.notice.entries()) {
+      report += await printAuditFail(result);
+    }
+    report += '</ol>\n';
+    report += '\n';
+  }
+
   if (grouped.warn.length) {
     report += `<h2>Warnings</h2>\n`;
     report += 'The server <i>SHOULD</i> support these, but is not required.\n';