feat(@angular-devkit/schematics): support reading JSON content directly from a Tree

The schematics `Tree` now contains an additional `readJSON` method that supports directly
reading and parsing the content of a file as UTF-8 JSON with comment support. This avoids the need to manually
decode a Buffer, parse and handle JSON comments within a schematic when JSON content is needed.
If a file path does not exist, an exception will be thrown. While this differs from the semantics of `read`,
it helps reduce the amount of code needed for common schematic use cases. JSON parse errors will also result
in an exception being thrown with a message detailing the error.

Author: clydin

goldens/public-api/angular_devkit/schematics/index.md

@@ -7,6 +7,7 @@
 /// <reference types="node" />
 
 import { BaseException } from '@angular-devkit/core';
+import { JsonValue } from '@angular-devkit/core';
 import { logging } from '@angular-devkit/core';
 import { Observable } from 'rxjs';
 import { Path } from '@angular-devkit/core';
@@ -235,6 +236,8 @@ export class DelegateTree implements Tree_2 {
     // (undocumented)
     read(path: string): Buffer | null;
     // (undocumented)
+    readJson(path: string): JsonValue;
+    // (undocumented)
     readText(path: string): string;
     // (undocumented)
     rename(from: string, to: string): void;
@@ -549,6 +552,8 @@ export class HostTree implements Tree_2 {
     // (undocumented)
     read(path: string): Buffer | null;
     // (undocumented)
+    readJson(path: string): JsonValue;
+    // (undocumented)
     readText(path: string): string;
     // (undocumented)
     rename(from: string, to: string): void;

goldens/public-api/angular_devkit/schematics/testing/index.md

@@ -6,6 +6,7 @@
 
 /// <reference types="node" />
 
+import { JsonValue } from '@angular-devkit/core';
 import { logging } from '@angular-devkit/core';
 import { Observable } from 'rxjs';
 import { Path } from '@angular-devkit/core';

goldens/public-api/angular_devkit/schematics/tools/index.md

@@ -8,6 +8,7 @@
 
 import { BaseException } from '@angular-devkit/core';
 import { JsonObject } from '@angular-devkit/core';
+import { JsonValue } from '@angular-devkit/core';
 import { logging } from '@angular-devkit/core';
 import { Observable } from 'rxjs';
 import { Path } from '@angular-devkit/core';

packages/angular_devkit/schematics/BUILD.bazel

@@ -37,6 +37,7 @@ ts_library(
         "//packages/angular_devkit/core",
         "//packages/angular_devkit/core/node",  # TODO: get rid of this for 6.0
         "@npm//@types/node",
+        "@npm//jsonc-parser",
         "@npm//magic-string",
         "@npm//rxjs",
     ],

packages/angular_devkit/schematics/src/tree/delegate.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import { JsonValue } from '@angular-devkit/core';
 import { Action } from './action';
 import {
   DirEntry,
@@ -38,6 +39,9 @@ export class DelegateTree implements Tree {
   readText(path: string): string {
     return this._other.readText(path);
   }
+  readJson(path: string): JsonValue {
+    return this._other.readJson(path);
+  }
   exists(path: string): boolean {
     return this._other.exists(path);
   }

packages/angular_devkit/schematics/src/tree/host-tree.ts

@@ -7,6 +7,7 @@
  */
 
 import {
+  JsonValue,
   Path,
   PathFragment,
   PathIsDirectoryException,
@@ -16,6 +17,7 @@ import {
   normalize,
   virtualFs,
 } from '@angular-devkit/core';
+import { ParseError, parse as jsoncParse, printParseErrorCode } from 'jsonc-parser';
 import { EMPTY, Observable } from 'rxjs';
 import { concatMap, map, mergeMap } from 'rxjs/operators';
 import { TextDecoder } from 'util';
@@ -310,6 +312,22 @@ export class HostTree implements Tree {
     }
   }
 
+  readJson(path: string): JsonValue {
+    const content = this.readText(path);
+    const errors: ParseError[] = [];
+    const result = jsoncParse(content, errors, { allowTrailingComma: true });
+
+    // If there is a parse error throw with the error information
+    if (errors[0]) {
+      const { error, offset } = errors[0];
+      throw new Error(
+        `Failed to parse "${path}" as JSON. ${printParseErrorCode(error)} at offset: ${offset}.`,
+      );
+    }
+
+    return result;
+  }
+
   exists(path: string): boolean {
     return this._recordSync.isFile(this._normalizePath(path));
   }

packages/angular_devkit/schematics/src/tree/host-tree_spec.ts

@@ -34,6 +34,61 @@ describe('HostTree', () => {
     });
   });
 
+  describe('readJson', () => {
+    it('returns a JSON value when reading a file that exists', () => {
+      const tree = new HostTree();
+      tree.create('/textfile1', '{ "a": true, "b": "xyz" }');
+      tree.create('/textfile2', '123');
+      tree.create('/textfile3', 'null');
+      expect(tree.readJson('/textfile1')).toEqual({ a: true, b: 'xyz' });
+      expect(tree.readJson('/textfile2')).toEqual(123);
+      expect(tree.readJson('/textfile3')).toBeNull();
+    });
+
+    it('returns a JSON value when reading a file with comments', () => {
+      const tree = new HostTree();
+      tree.create(
+        '/textfile1',
+        '{ "a": true, /* inner object\nmultiline comment\n */ "b": "xyz" }',
+      );
+      tree.create('/textfile2', '123 // number value');
+      tree.create('/textfile3', 'null // null value');
+      expect(tree.readJson('/textfile1')).toEqual({ a: true, b: 'xyz' });
+      expect(tree.readJson('/textfile2')).toEqual(123);
+      expect(tree.readJson('/textfile3')).toBeNull();
+    });
+
+    it('returns a JSON value when reading a file with trailing commas', () => {
+      const tree = new HostTree();
+      tree.create('/textfile1', '{ "a": true, "b": "xyz", }');
+      tree.create('/textfile2', '[5, 4, 3, 2, 1, ]');
+      expect(tree.readJson('/textfile1')).toEqual({ a: true, b: 'xyz' });
+      expect(tree.readJson('/textfile2')).toEqual([5, 4, 3, 2, 1]);
+    });
+
+    it('throws an error when a file does not exist', () => {
+      const tree = new HostTree();
+      const path = '/textfile1';
+      expect(() => tree.readJson(path)).toThrowError(`Path "${path}" does not exist.`);
+    });
+
+    it('throws an error if the JSON is malformed', () => {
+      const tree = new HostTree();
+      const path = '/textfile1';
+      tree.create(path, '{ "a": true;;;;; "b": "xyz" }');
+      expect(() => tree.readJson(path)).toThrowError(
+        `Failed to parse "${path}" as JSON. InvalidSymbol at offset: 7.`,
+      );
+    });
+
+    it('throws an error when invalid UTF-8 characters are present', () => {
+      const tree = new HostTree();
+      const path = '/textfile1';
+      tree.create(path, Buffer.from([0xff, 0xff, 0xff, 0xff]));
+      expect(() => tree.readJson(path)).toThrowError(`Failed to decode "${path}" as UTF-8 text.`);
+    });
+  });
+
   describe('merge', () => {
     it('should create files from each tree', () => {
       const tree = new HostTree();

packages/angular_devkit/schematics/src/tree/interface.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import { Path, PathFragment } from '@angular-devkit/core';
+import { JsonValue, Path, PathFragment } from '@angular-devkit/core';
 import { Action } from './action';
 
 export enum MergeStrategy {
@@ -94,6 +94,20 @@ export interface Tree {
    */
   readText(path: string): string;
 
+  /**
+   * Reads and parses a file from the Tree as a UTF-8 encoded JSON file.
+   * Supports parsing JSON (RFC 8259) with the following extensions:
+   * * Single-line and multi-line JavaScript comments
+   * * Trailing commas within objects and arrays
+   *
+   * @param path The path of the file to read.
+   * @returns A JsonValue containing the parsed contents of the file.
+   * @throws {@link FileDoesNotExistException} if the file is not found.
+   * @throws An error if the file contains invalid UTF-8 characters.
+   * @throws An error if the file contains malformed JSON.
+   */
+  readJson(path: string): JsonValue;
+
   exists(path: string): boolean;
   get(path: string): FileEntry | null;
   getDir(path: string): DirEntry;

packages/angular_devkit/schematics/src/tree/null.ts

@@ -6,7 +6,15 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import { BaseException, Path, PathFragment, dirname, join, normalize } from '@angular-devkit/core';
+import {
+  BaseException,
+  JsonValue,
+  Path,
+  PathFragment,
+  dirname,
+  join,
+  normalize,
+} from '@angular-devkit/core';
 import { FileDoesNotExistException } from '../exception/exception';
 import { Action } from './action';
 import { DirEntry, MergeStrategy, Tree, TreeSymbol, UpdateRecorder } from './interface';
@@ -60,6 +68,9 @@ export class NullTree implements Tree {
   readText(path: string): string {
     throw new FileDoesNotExistException(path);
   }
+  readJson(path: string): JsonValue {
+    throw new FileDoesNotExistException(path);
+  }
   get(_path: string) {
     return null;
   }

packages/angular_devkit/schematics/src/tree/scoped.ts

@@ -7,6 +7,7 @@
  */
 
 import {
+  JsonValue,
   NormalizedRoot,
   Path,
   PathFragment,
@@ -116,6 +117,9 @@ export class ScopedTree implements Tree {
   readText(path: string): string {
     return this._base.readText(this._fullPath(path));
   }
+  readJson(path: string): JsonValue {
+    return this._base.readJson(this._fullPath(path));
+  }
   exists(path: string): boolean {
     return this._base.exists(this._fullPath(path));
   }