fix: rewrite string enum extractor as a token parser

src/__tests__/markdown-helpers.spec.ts

@@ -104,6 +104,76 @@ def fn():
       expect(extractStringEnum('wassup')).toBe(null);
     });
 
+    it('should error helpfully on invalid value separators', () => {
+      expect(() => extractStringEnum('Can be `x` sometimes `y'))
+        .toThrowErrorMatchingInlineSnapshot(`
+        "Unexpected separator token while extracting string enum, expected a comma or "and" or "or" but found "s"
+        Context: \`x\` sometimes \`y
+                     ^"
+      `);
+    });
+
+    it('should error helpfully on unterminated enum strings', () => {
+      expect(() => extractStringEnum('Can be `x` or `y')).toThrowErrorMatchingInlineSnapshot(`
+        "Unexpected early termination of token sequence while extracting string enum, did you forget to close a quote?
+        Context: \`x\` or \`y"
+      `);
+    });
+
+    describe('mixed ticks', () => {
+      it('should extract an enum when mixed quotes are used', () => {
+        const values = extractStringEnum('Can be `x"` or "`y"')!;
+        expect(values).not.toBe(null);
+        expect(values).toHaveLength(2);
+        expect(values[0].value).toBe('x"');
+        expect(values[1].value).toBe('`y');
+      });
+    });
+
+    describe('deprecated wrappers', () => {
+      it('should handle strikethrough deprecation wrappers', () => {
+        const values = extractStringEnum('Can be `x` or ~~`y`~~')!;
+        expect(values).not.toBe(null);
+        expect(values).toHaveLength(2);
+        expect(values[0].value).toBe('x');
+        expect(values[1].value).toBe('y');
+      });
+    });
+
+    describe('lead-in descriptions', () => {
+      it('should handle value lists that smoothly lead in to prose with a comma', () => {
+        const values = extractStringEnum('Can be `x` or `y`, where `x` implies that...')!;
+        expect(values).not.toBe(null);
+        expect(values).toHaveLength(2);
+        expect(values[0].value).toBe('x');
+        expect(values[1].value).toBe('y');
+      });
+
+      it('should handle value lists that smoothly lead in to prose with a fullstop', () => {
+        const values = extractStringEnum('Can be `x` or `y`. The `x` value implies that...')!;
+        expect(values).not.toBe(null);
+        expect(values).toHaveLength(2);
+        expect(values[0].value).toBe('x');
+        expect(values[1].value).toBe('y');
+      });
+
+      it('should handle value lists that smoothly lead in to prose with a semicolon', () => {
+        const values = extractStringEnum('Can be `x` or `y`; the `x` value implies that...')!;
+        expect(values).not.toBe(null);
+        expect(values).toHaveLength(2);
+        expect(values[0].value).toBe('x');
+        expect(values[1].value).toBe('y');
+      });
+
+      it('should handle value lists that smoothly lead in to prose with a hyphen', () => {
+        const values = extractStringEnum('Can be `x` or `y` - the `x` value implies that...')!;
+        expect(values).not.toBe(null);
+        expect(values).toHaveLength(2);
+        expect(values[0].value).toBe('x');
+        expect(values[1].value).toBe('y');
+      });
+    });
+
     describe('with backticks', () => {
       it('should extract an enum of the format "can be x"', () => {
         const values = extractStringEnum('Can be `x`')!;