feat: dedent spacing

README.md

@@ -23,17 +23,17 @@ Lib mainly provides two pieces [Parser](#Parser) and [Stringifier](#Stringifier)
 Let's go over string parsing:
 
 ```js
-const { parse } = require('comment-parser/lib')
+const { parse } = require('comment-parser/lib');
 
 const source = `
 /**
  * Description may go
  * over few lines followed by @tags
  * @param {string} name the name parameter
  * @param {any} value the value of any type
- */`
+ */`;
 
-const parsed = parse(source)
+const parsed = parse(source);
 ```
 
 Lib source code is written in TypeScript and all data shapes are conveniently available for your IDE of choice. All types described below can be found in [primitives.ts](src/primitives.ts)
@@ -160,13 +160,14 @@ interface Options {
   // escaping chars sequence marking wrapped content literal for the parser
   fence: string;
   // block and comment description compaction strategy
-  spacing: 'compact' | 'preserve';
+  spacing: 'compact' | 'preserve' | 'dedent';
   // tokenizer functions extracting name, type, and description out of tag, see Tokenizer
   tokenizers: Tokenizer[];
 }
 ```
 
 examples
+
 - [default config](https://syavorsky.github.io/comment-parser/#parse-defaults)
 - [line numbers control](https://syavorsky.github.io/comment-parser/#parse-line-numbering)
 - [description spacing](https://syavorsky.github.io/comment-parser/#parse-spacing)
@@ -180,7 +181,11 @@ examples
 The stringifier is an important piece used by other tools updating the source code. It goes over `Block.source[].tokens` items and assembles them back to the string. It might be used with various transforms applied before stringifying.
 
 ```js
-const { parse, stringify, transforms: {flow, align, indent} } = require('comment-parser');
+const {
+  parse,
+  stringify,
+  transforms: { flow, align, indent },
+} = require('comment-parser');
 
 const source = `
   /**
@@ -193,7 +198,7 @@ const source = `
    */`;
 
 const parsed = parse(source);
-const transform = flow(align(), indent(0))
+const transform = flow(align(), indent(0));
 console.log(stringify(transform(parsed[0])));
 ```
 
@@ -211,6 +216,7 @@ console.log(stringify(transform(parsed[0])));
 ```
 
 examples
+
 - [format comments](https://syavorsky.github.io/comment-parser/#stringify-formatting)
 
 [suggest more examples](https://github.com/syavorsky/comment-parser/issues/new?title=example+suggestion%3A+...&labels=example,stringifier)

package.json

@@ -81,6 +81,5 @@
   "bugs": {
     "url": "https://github.com/syavorsky/comment-parser/issues"
   },
-  "homepage": "https://github.com/syavorsky/comment-parser",
-  "dependencies": {}
+  "homepage": "https://github.com/syavorsky/comment-parser"
 }

src/parser/index.ts

@@ -1,8 +1,8 @@
 import { Block, Line, Problem, BlockMarkers, Markers } from '../primitives';
-import { splitLines } from '../util';
+import { splitLines, dedent, compose2, identity } from '../util';
 import blockParser from './block-parser';
 import sourceParser from './source-parser';
-import specParser from './spec-parser';
+import specParser, { dedentSpec } from './spec-parser';
 import { Tokenizer } from './tokenizers/index';
 import tokenizeTag from './tokenizers/tag';
 import tokenizeType from './tokenizers/type';
@@ -17,7 +17,7 @@ export interface Options {
   // escaping chars sequence marking wrapped content literal for the parser
   fence: string;
   // block and comment description compaction strategy
-  spacing: 'compact' | 'preserve';
+  spacing: 'compact' | 'preserve' | 'dedent';
   // comment description markers
   markers: BlockMarkers;
   // tokenizer functions extracting name, type, and description out of tag, see Tokenizer
@@ -57,10 +57,19 @@ export default function getParser({
       if (lines.find(notEmpty) === undefined) continue;
 
       const sections = parseBlock(lines);
-      const specs = sections.slice(1).map(parseSpec);
+      const specFormatter = spacing === 'dedent' ? dedentSpec : identity;
+
+      const specs = sections.slice(1).map(compose2(specFormatter, parseSpec));
+
+      const joinedDescription = joinDescription(sections[0], markers);
+
+      const description =
+        spacing === 'dedent' ? dedent(joinedDescription) : joinedDescription;
+
+      console.log({ joinedDescription, spacing });
 
       blocks.push({
-        description: joinDescription(sections[0], markers),
+        description,
         tags: specs,
         source: lines,
         problems: specs.reduce(

src/parser/spec-parser.ts

@@ -1,5 +1,5 @@
 import { Line, Spec } from '../primitives';
-import { seedSpec } from '../util';
+import { dedent, seedSpec } from '../util';
 import { Tokenizer } from './tokenizers/index';
 
 export type Parser = (source: Line[]) => Spec;
@@ -18,3 +18,10 @@ export default function getParser({ tokenizers }: Options): Parser {
     return spec;
   };
 }
+
+export function dedentSpec(spec: Spec): Spec {
+  return {
+    ...spec,
+    description: dedent(spec.description),
+  };
+}

src/parser/tokenizers/description.ts

@@ -11,7 +11,7 @@ export type Joiner = (lines: Line[], markers?: BlockMarkers) => string;
  * compact - strip surrounding whitespace and concat lines using a single string
  * preserve - preserves original whitespace and line breaks as is
  */
-export type Spacing = 'compact' | 'preserve' | Joiner;
+export type Spacing = 'compact' | 'preserve' | 'dedent' | Joiner;
 
 /**
  * Makes no changes to `spec.lines[].tokens` but joins them into `spec.description`
@@ -32,7 +32,7 @@ export default function descriptionTokenizer(
 
 export function getJoiner(spacing: Spacing): Joiner {
   if (spacing === 'compact') return compactJoiner;
-  if (spacing === 'preserve') return preserveJoiner;
+  if (spacing === 'preserve' || spacing === 'dedent') return preserveJoiner;
 
   return spacing;
 }

src/parser/tokenizers/type.ts

@@ -20,7 +20,7 @@ export type Joiner = (parts: string[]) => string;
  * compact - trim surrounding space, replace line breaks with a single space
  * preserve - concat as is
  */
-export type Spacing = 'compact' | 'preserve' | Joiner;
+export type Spacing = 'compact' | 'preserve' | 'dedent' | Joiner;
 
 /**
  * Sets splits remaining `Spec.lines[].tokes.description` into `type` and `description`
@@ -86,6 +86,7 @@ const trim = (x: string) => x.trim();
 
 function getJoiner(spacing: Spacing): Joiner {
   if (spacing === 'compact') return (t: string[]) => t.map(trim).join('');
-  else if (spacing === 'preserve') return (t: string[]) => t.join('\n');
+  else if (spacing === 'preserve' || spacing === 'dedent')
+    return (t: string[]) => t.join('\n');
   else return spacing;
 }

src/util.ts

@@ -97,3 +97,61 @@ export function rewireSpecs(block: Block): Block {
   block.source = block.source.map((line) => source.get(line.number) || line);
   return block;
 }
+
+/**
+ * Dedent a string. Adapted from 'dedent' npm package
+ * @see https://npm.im/dedent
+ */
+export function dedent(raw: string): string {
+  // first, perform interpolation
+  var result = '';
+  for (var i = 0; i < raw.length; i++) {
+    result += raw[i]
+      // join lines when there is a suppressed newline
+      .replace(/\\\n[ \t]*/g, '')
+      // handle escaped backticks
+      .replace(/\\`/g, '`');
+
+    if (i < (arguments.length <= 1 ? 0 : arguments.length - 1)) {
+      result += arguments.length <= i + 1 ? undefined : arguments[i + 1];
+    }
+  }
+
+  // now strip indentation
+  var lines = result.split('\n');
+  var mindent = null;
+  lines.forEach(function (l) {
+    var m = l.match(/^(\s+)\S+/);
+    if (m) {
+      var indent = m[1].length;
+      if (!mindent) {
+        // this is the first indented line
+        mindent = indent;
+      } else {
+        mindent = Math.min(mindent, indent);
+      }
+    }
+  });
+
+  if (mindent !== null) {
+    result = lines
+      .map(function (l) {
+        return l[0] === ' ' ? l.slice(mindent) : l;
+      })
+      .join('\n');
+  }
+
+  // dedent eats leading and trailing whitespace too
+  result = result.trim();
+
+  // handle escaped newlines at the end to ensure they don't get stripped too
+  return result.replace(/\\n/g, '\n');
+}
+
+/** I combinator */
+export const identity = <T>(x: T): T => x;
+/** B combinator - the Bluebird. Compose two unary functions, right-to-left */
+export const compose2 =
+  <T, U = T, V = T>(f: (y: U) => V, g: (x: T) => U) =>
+  (x: T): V =>
+    f(g(x));