feat: add enforcement for optional parameters that the docs and the signature match

Author: MarshallOfSound

.gitignore

@@ -1,3 +1,4 @@
 node_modules
 dist
 *api.json
+tsconfig.tsbuildinfo

.vscode/settings.json

@@ -4,5 +4,6 @@
   "typescript.preferences.quoteStyle": "single",
   "search.exclude": {
     "**/dist": true
-  }
+  },
+  "typescript.tsdk": "node_modules/typescript/lib"
 }

package.json

@@ -25,9 +25,9 @@
     "@types/pretty-ms": "^4.0.0",
     "jest": "^24.7.1",
     "prettier": "^1.17.0",
-    "ts-jest": "^24.0.2",
     "semantic-release": "^15.13.3",
-    "typescript": "^3.4.5"
+    "ts-jest": "^24.0.2",
+    "typescript": "^3.5.1"
   },
   "dependencies": {
     "@types/markdown-it": "^0.0.7",
@@ -40,4 +40,4 @@
     "ora": "^3.4.0",
     "pretty-ms": "^5.0.0"
   }
-}
+}

src/block-parsers.ts

@@ -18,6 +18,61 @@ import {
   EventDocumentationBlock,
 } from './ParsedDocumentation';
 
+type GuessedParam = {
+  name: string;
+  optional: boolean;
+};
+
+export const guessParametersFromSignature = (signature: string) => {
+  expect(signature).to.match(
+    /^\(([a-zA-Z,\[\] ]+|(\.\.\.[^\.])|([a-zA-Z][0-9]))+\)$/g,
+    'signature should be a bracket wrapped group of parameters',
+  );
+  const justParams = signature.slice(1, signature.length - 1);
+  let optionalDepth = 0;
+  const params: GuessedParam[] = [];
+  let currentParam = '';
+  let currentOptional = false;
+  const maybePushCurrent = () => {
+    const trimmed = currentParam.trim();
+    if (trimmed) {
+      params.push({
+        name: trimmed,
+        optional: currentOptional,
+      });
+      currentParam = '';
+    }
+  };
+  for (let i = 0; i < justParams.length; i++) {
+    const char = justParams[i];
+    switch (char) {
+      case '[':
+        optionalDepth++;
+        break;
+      case ']':
+        maybePushCurrent();
+        optionalDepth--;
+        expect(optionalDepth).to.be.gte(
+          0,
+          `optional depth should never be negative, you have too many "]" characters in your signature: "${signature}"`,
+        );
+        break;
+      case ',':
+        maybePushCurrent();
+        break;
+      default:
+        if (!currentParam.trim()) currentOptional = optionalDepth > 0;
+        currentParam += char;
+    }
+  }
+  maybePushCurrent();
+  expect(optionalDepth).to.equal(
+    0,
+    `optional depth should return to 0, you have mismateched [ and ] characters in your signature: "${signature}"`,
+  );
+  return params;
+};
+
 export const _headingToMethodBlock = (
   heading: HeadingContent | null,
 ): MethodDocumentationBlock | null => {
@@ -34,6 +89,7 @@ export const _headingToMethodBlock = (
 
   let parameters: MethodDocumentationBlock['parameters'] = [];
   if (methodSignature !== '()') {
+    const guessedParams = guessParametersFromSignature(methodSignature);
     // If we have parameters we need to find the list of typed keys
     const list = findNextList(heading.content)!;
     expect(list).to.not.equal(
@@ -46,6 +102,18 @@ export const _headingToMethodBlock = (
       required: typedKey.required,
       ...typedKey.type,
     }));
+    expect(parameters).to.have.lengthOf(
+      guessedParams.length,
+      `should have the same number of documented parameters as we have in the method signature: "${methodSignature}"`,
+    );
+    for (let i = 0; i < parameters.length; i++) {
+      expect(parameters[i].required).to.equal(
+        !guessedParams[i].optional,
+        `the optionalality of a paramater in the signature should match the documented optionality in the parameter description: "${methodString}${methodSignature}", while parsing parameter: "${
+          parameters[i].name
+        }"`,
+      );
+    }
   }
 
   const returnTokens =

src/markdown-helpers.ts

@@ -298,7 +298,7 @@ export const rawTypeToTypeInformation = (
                   ...typedKey.type,
                 }))
               : []
-            : genericProvidedParams,
+            : (genericProvidedParams as MethodParameterDocumentation[]),
         returns: innerTypes[innerTypes.length - 1],
       };
     }

tsconfig.json

@@ -12,6 +12,7 @@
 		"rootDir": "src",
 		"experimentalDecorators": true,
 		"strict": true,
-		"esModuleInterop": true
+		"esModuleInterop": true,
+		"incremental": true
 	}
 }

yarn.lock

@@ -6238,10 +6238,10 @@ typedarray@^0.0.6:
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
   integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=
 
-typescript@^3.4.5:
-  version "3.4.5"
-  resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.4.5.tgz#2d2618d10bb566572b8d7aad5180d84257d70a99"
-  integrity sha512-YycBxUb49UUhdNMU5aJ7z5Ej2XGmaIBL0x34vZ82fn3hGvD+bgrMrVDpatgz2f7YxUMJxMkbWxJZeAvDxVe7Vw==
+typescript@^3.5.1:
+  version "3.5.1"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.5.1.tgz#ba72a6a600b2158139c5dd8850f700e231464202"
+  integrity sha512-64HkdiRv1yYZsSe4xC1WVgamNigVYjlssIoaH2HcZF0+ijsk5YK2g0G34w9wJkze8+5ow4STd22AynfO6ZYYLw==
 
 uc.micro@^1.0.1, uc.micro@^1.0.5:
   version "1.0.5"