Fix plugin related types for remarkable (#29530)

* @types/remarkable had some holes when it came to writing plugins. See the CHANGELOG.md for information

* @types/remarkable had some holes when it came to writing plugins. See the CHANGELOG.md for information

* refactor values to support derferred executions

* remove unneeded dependency

* fix catastrophic, world-ending newline that crept in

* fix tslint problems

types/remarkable/lib/index.d.ts

@@ -76,7 +76,7 @@ declare namespace Remarkable {
         [key: string]: any;
     }
 
-    type GetBreak = (tokens: Token[], idx: number) => "" | "\n";
+    type GetBreak = (tokens: ContentToken[], idx: number) => "" | "\n";
 
     interface Options {
         /**
@@ -134,11 +134,49 @@ declare namespace Remarkable {
         options: Options;
     }
 
+    interface ParsingState {
+        src: string;
+        env: Env;
+        options: Options;
+        tokens: [ContentToken];
+        inlineMode: boolean;
+
+        pos: number;
+        posMax: number;
+        pending: string;
+        level: number;
+
+        inline: ParserInline;
+        block: ParserBlock;
+        renderer: Renderer;
+        typographer: boolean;
+
+        push: (token: ContentToken) => void;
+    }
+
+    /**
+     * Return `true` if the parsing function has recognized the current position
+     * in the input as one if its tokens.
+     */
+    type ParsingRule = (
+        /**
+         * Representation of the current input stream, and the results of
+         * parsing it so far.
+         */
+        state: ParsingState,
+
+        /**
+         * If `true` we just do the recognition part, and don't bother to push a
+         * token.
+         */
+        silent: boolean
+    ) => boolean;
+
     type Rule = (
         /**
          * The list of tokens currently being processed.
          */
-        tokens: Token[],
+        tokens: ContentToken[],
 
         /**
          * The index of the token currently being processed.
@@ -227,12 +265,17 @@ declare namespace Remarkable {
         getBreak: GetBreak;
     }
 
-    interface BaseToken {
+    interface TagToken {
         /**
          * The nesting level of the associated markdown structure in the source.
          */
         level: number;
 
+        /**
+         * The type of the token.
+         */
+        type: string;
+
         /**
          * Tokens generated by block parsing rules also include a `lines`
          * property which is a 2 elements array marking the first and last line of the
@@ -241,27 +284,7 @@ declare namespace Remarkable {
         lines?: [number, number];
     }
 
-    interface TagToken extends BaseToken {
-        /**
-         * Tag tokens have a variety of types and each is a name of a
-         * rendering rule.
-         */
-        type: string;
-    }
-
-    interface ContentToken extends BaseToken {
-        /**
-         * A text token has a `content` property containing the text it represents.
-         */
-        content: string;
-
-        /**
-         * The type of the token.
-         */
-        type: "text";
-    }
-
-    interface BlockContentToken extends BaseToken {
+    interface BlockContentToken extends TagToken {
         /**
          * The content of the block. This might include inline mardown syntax
          * which may need further processing by the inline rules.
@@ -273,11 +296,24 @@ declare namespace Remarkable {
          * with the inline parser tokens as the inline parsing rules are applied.
          */
         children: Token[];
+    }
+
+    interface ContentToken extends TagToken {
+        /**
+         * A text token has a `content` property. This is passed to
+         * the corresponding renderer to be converted for output.
+         */
+        content: any;
 
         /**
          * The type of the token.
          */
-        type: "inline";
+        type: string;
+
+        /**
+         * Is this a block element
+         */
+        block: boolean;
     }
 
     interface MiscTokenProps {
@@ -343,5 +379,17 @@ declare namespace Remarkable {
         title?: string;
     }
 
-    type Token = (TagToken | ContentToken | BlockContentToken) & MiscTokenProps;
+    type Token = (BlockContentToken | ContentToken | TagToken) & MiscTokenProps;
+}
+
+declare class ParserBlock {
+    tokenize(state: Remarkable.ParsingState, startLine: number, endLine: number): void;
+    parse(str: string, options: Remarkable.Options, env: Remarkable.Env, tokens: [Remarkable.Token]): void;
+}
+
+declare class ParserInline {
+    skipToken(state: Remarkable.ParsingState): void;
+    tokenize(state: Remarkable.ParsingState): void;
+    parse(str: string, options: Remarkable.Options, env: Remarkable.Env, tokens: [Remarkable.Token]): void;
+    validateLink(url: string): boolean;
 }

types/remarkable/lib/ruler.d.ts

@@ -13,22 +13,22 @@ declare class Ruler {
   /**
    * Replace the rule `ruleName` with a new rule.
    */
-  at(ruleName: string, fn: Remarkable.Rule, options: Remarkable.Options): void;
+  at(ruleName: string, fn: Remarkable.ParsingRule, options: Remarkable.Options): void;
 
   /**
    * Add a rule to the chain before given the `ruleName`.
    */
-  before(beforeName: string, ruleName: string, fn: Remarkable.Rule, options: Remarkable.Options): void;
+  before(beforeName: string, ruleName: string, fn: Remarkable.ParsingRule, options: Remarkable.Options): void;
 
   /**
    * Add a rule to the chain after the given `ruleName`.
    */
-  after(afterName: string, ruleName: string, fn: Remarkable.Rule, options: Remarkable.Options): void;
+  after(afterName: string, ruleName: string, fn: Remarkable.ParsingRule, options: Remarkable.Options): void;
 
   /**
    * Add a rule to the end of chain.
    */
-  push(ruleName: string, fn: Remarkable.Rule, options: Remarkable.Options): void;
+  push(ruleName: string, fn: Remarkable.ParsingRule, options: Remarkable.Options): void;
 
   /**
    * Enable a rule or list of rules.