feat: expose OS/stability tags in the API structure (#8)

Author: MarshallOfSound

src/DocsParser.ts

@@ -254,6 +254,7 @@ export class DocsParser {
         name: typedKey.key,
         description: typedKey.description,
         required: typedKey.required,
+        additionalTags: typedKey.additionalTags,
         ...typedKey.type,
       })),
     };

src/ParsedDocumentation.ts

@@ -1,3 +1,12 @@
+export enum DocumentationTag {
+  OS_MACOS = 'os_macos',
+  OS_MAS = 'os_mas',
+  OS_WINDOWS = 'os_windows',
+  OS_LINUX = 'os_linux',
+  STABILITY_EXPERIMENTAL = 'stability_experimental',
+  STABILITY_DEPRECATED = 'stability_deprecated',
+  AVAILABILITY_READONLY = 'availability_readonly',
+}
 export declare type PossibleStringValue = {
   value: string;
   description: string;
@@ -43,6 +52,7 @@ export declare type EventParameterDocumentation = {
 export declare type DocumentationBlock = {
   name: string;
   description: string;
+  additionalTags: DocumentationTag[];
 };
 export declare type MethodDocumentationBlock = DocumentationBlock & {
   signature: string;

src/__tests__/markdown-helpers.spec.ts

@@ -2,9 +2,43 @@ import * as fs from 'fs';
 import * as path from 'path';
 import MarkdownIt from 'markdown-it';
 
-import { safelyJoinTokens, extractStringEnum, rawTypeToTypeInformation } from '../markdown-helpers';
+import {
+  safelyJoinTokens,
+  extractStringEnum,
+  rawTypeToTypeInformation,
+  parseHeadingTags,
+} from '../markdown-helpers';
+import { DocumentationTag } from '../ParsedDocumentation';
 
 describe('markdown-helpers', () => {
+  describe('parseHeadingTags', () => {
+    it('should return an empty array for null input', () => {
+      expect(parseHeadingTags(null)).toEqual([]);
+    });
+
+    it('should return an empty array if there are no tags in the input', () => {
+      expect(parseHeadingTags('String thing no tags')).toEqual([]);
+    });
+
+    it('should return a list of tags if there is one tag', () => {
+      expect(parseHeadingTags(' _macOS_')).toEqual([DocumentationTag.OS_MACOS]);
+    });
+
+    it('should return a list of tags if there are multiple tags', () => {
+      expect(parseHeadingTags(' _macOS_ _Windows_ _Experimental_')).toEqual([
+        DocumentationTag.OS_MACOS,
+        DocumentationTag.OS_WINDOWS,
+        DocumentationTag.STABILITY_EXPERIMENTAL,
+      ]);
+    });
+
+    it('should throw an error if there is a tag not on the whitelist', () => {
+      expect(() => parseHeadingTags(' _Awesome_')).toThrowErrorMatchingInlineSnapshot(
+        `"heading tags must be from the whitelist: [\\"macOS\\",\\"mas\\",\\"Windows\\",\\"Linux\\",\\"Experimental\\",\\"Deprecated\\",\\"Readonly\\"]: expected [ Array(7) ] to include 'Awesome'"`,
+      );
+    });
+  });
+
   describe('safelyJoinTokens', () => {
     it('should join no tokens to an empty string', () => {
       expect(safelyJoinTokens([])).toBe('');

src/block-parsers.ts

@@ -2,6 +2,7 @@ import { expect } from 'chai';
 import Token from 'markdown-it/lib/token';
 
 import {
+  parseHeadingTags,
   headingsAndContent,
   findNextList,
   convertListToTypedKeys,
@@ -78,14 +79,14 @@ export const _headingToMethodBlock = (
 ): MethodDocumentationBlock | null => {
   if (!heading) return null;
 
-  const methodStringRegexp = /`(?:.+\.)?(.+?)(\(.*?\))`/g;
+  const methodStringRegexp = /`(?:.+\.)?(.+?)(\(.*?\))`( _(?:[^_]+?)_)*/g;
   const methodStringMatch = methodStringRegexp.exec(heading.heading)!;
   methodStringRegexp.lastIndex = -1;
   expect(heading.heading).to.match(
     methodStringRegexp,
     'each method should have a code blocked method name',
   );
-  const [, methodString, methodSignature] = methodStringMatch;
+  const [, methodString, methodSignature, headingTags] = methodStringMatch;
 
   let parameters: MethodDocumentationBlock['parameters'] = [];
   if (methodSignature !== '()') {
@@ -129,18 +130,19 @@ export const _headingToMethodBlock = (
     description: parsedDescription,
     parameters,
     returns: parsedReturnType,
+    additionalTags: parseHeadingTags(headingTags),
   };
 };
 
 export const _headingToPropertyBlock = (heading: HeadingContent): PropertyDocumentationBlock => {
-  const propertyStringRegexp = /`(?:.+\.)?(.+?)`/g;
+  const propertyStringRegexp = /`(?:.+\.)?(.+?)`( _(?:[^_]+?)_)*/g;
   const propertyStringMatch = propertyStringRegexp.exec(heading.heading)!;
   propertyStringRegexp.lastIndex = -1;
   expect(heading.heading).to.match(
     propertyStringRegexp,
     'each property should have a code blocked property name',
   );
-  const [, propertyString] = propertyStringMatch;
+  const [, propertyString, headingTags] = propertyStringMatch;
 
   const { parsedDescription, parsedReturnType } = extractReturnType(
     findContentAfterHeadingClose(heading.content),
@@ -157,16 +159,17 @@ export const _headingToPropertyBlock = (heading: HeadingContent): PropertyDocume
     name: propertyString,
     description: parsedDescription,
     required: !/\(optional\)/i.test(parsedDescription),
+    additionalTags: parseHeadingTags(headingTags),
     ...parsedReturnType!,
   };
 };
 
 export const _headingToEventBlock = (heading: HeadingContent): EventDocumentationBlock => {
-  const eventNameRegexp = /^Event: '(.+)'/g;
+  const eventNameRegexp = /^Event: '(.+)'( _(?:[^_]+?)_)*/g;
   const eventNameMatch = eventNameRegexp.exec(heading.heading)!;
   eventNameRegexp.lastIndex = -1;
   expect(heading.heading).to.match(eventNameRegexp, 'each event should have a quoted event name');
-  const [, eventName] = eventNameMatch;
+  const [, eventName, headingTags] = eventNameMatch;
 
   expect(eventName).to.not.equal('', 'should have a non-zero-length event name');
 
@@ -194,6 +197,7 @@ export const _headingToEventBlock = (heading: HeadingContent): EventDocumentatio
     name: eventName,
     description,
     parameters,
+    additionalTags: parseHeadingTags(headingTags),
   };
 };
 

src/markdown-helpers.ts

@@ -5,8 +5,44 @@ import {
   PropertyDocumentationBlock,
   MethodParameterDocumentation,
   PossibleStringValue,
+  DocumentationTag,
 } from './ParsedDocumentation';
 
+const tagMap = {
+  macOS: DocumentationTag.OS_MACOS,
+  mas: DocumentationTag.OS_MAS,
+  Windows: DocumentationTag.OS_WINDOWS,
+  Linux: DocumentationTag.OS_LINUX,
+  Experimental: DocumentationTag.STABILITY_EXPERIMENTAL,
+  Deprecated: DocumentationTag.STABILITY_DEPRECATED,
+  Readonly: DocumentationTag.AVAILABILITY_READONLY,
+};
+
+const ALLOWED_TAGS = Object.keys(tagMap) as (keyof typeof tagMap)[];
+
+export const parseHeadingTags = (tags: string | null): DocumentationTag[] => {
+  if (!tags) return [];
+
+  const parsedTags: (keyof typeof tagMap)[] = [];
+  const matcher = / _([^_]+)_/g;
+  let match: RegExpMatchArray | null;
+  while ((match = matcher.exec(tags))) {
+    expect(ALLOWED_TAGS).to.contain(
+      match[1],
+      `heading tags must be from the whitelist: ${JSON.stringify(ALLOWED_TAGS)}`,
+    );
+    parsedTags.push(match[1] as keyof typeof tagMap);
+  }
+
+  return parsedTags.map(value => {
+    if (tagMap[value]) return tagMap[value];
+
+    throw new Error(
+      `Impossible scenario detected, "${value}" is not an allowed tag but it got past the allowed tags check`,
+    );
+  });
+};
+
 export const findNextList = (tokens: Token[]) => {
   const start = tokens.findIndex(t => t.type === 'bullet_list_open');
   if (start === -1) return null;
@@ -237,6 +273,7 @@ export const rawTypeToTypeInformation = (
             name: typedKey.key,
             description: typedKey.description,
             required: typedKey.required,
+            additionalTags: typedKey.additionalTags,
             ...typedKey.type,
           }))
         : [],
@@ -271,6 +308,7 @@ export const rawTypeToTypeInformation = (
                   name: typedKey.key,
                   description: typedKey.description,
                   required: typedKey.required,
+                  additionalTags: typedKey.additionalTags,
                   ...typedKey.type,
                 }))
               : [],
@@ -514,6 +552,7 @@ type TypedKey = {
   type: TypeInformation;
   description: string;
   required: boolean;
+  additionalTags: DocumentationTag[];
 };
 
 type List = { items: ListItem[] };
@@ -608,6 +647,8 @@ const convertNestedListToTypedKeys = (list: List): TypedKey[] => {
       / ?\(Optional\) ?/,
       'optionality should be defined with "(optional)", all lower case, no capital "O"',
     );
+    const tagMatcher = /.+?((?: _(?:[^_]+?)_)+)/g;
+    const tagMatch = tagMatcher.exec(rawType);
     const cleanedType = rawType.replace(/ ?\(optional\) ?/i, '').replace(/_.+?_/g, '');
     const subTypedKeys = item.nestedList ? convertNestedListToTypedKeys(item.nestedList) : null;
     const type = rawTypeToTypeInformation(cleanedType.trim(), rawDescription, subTypedKeys);
@@ -617,6 +658,7 @@ const convertNestedListToTypedKeys = (list: List): TypedKey[] => {
       key: keyToken.content,
       description: rawDescription.trim().replace(/^- ?/, ''),
       required: !isRootOptional,
+      additionalTags: tagMatch ? parseHeadingTags(tagMatch[1]) : [],
     });
   }