Implement ConfigLoader.tryLoadFromPackageFolder()

Author: octogonz

tsdoc-config/.vscode/launch.json

@@ -0,0 +1,26 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Jest All",
+      "program": "${workspaceFolder}/node_modules/jest/bin/jest",
+      "args": ["--runInBand"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Jest Current File",
+      "program": "${workspaceFolder}/node_modules/jest/bin/jest",
+      "args": ["${relativeFile}"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    }
+  ]
+}

tsdoc-config/src/ConfigLoader.ts

@@ -0,0 +1,79 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { TSDocConfigFile } from './TSDocConfigFile';
+
+interface IPackageJson {
+  name?: string;
+  version?: string;
+  main?: string;
+  typings?: string;
+  types?: string;
+  tsdocConfig?: string;
+}
+
+export class ConfigLoader {
+  public static readonly JSON_FILE_NAME: string = 'tsdoc-config.json';
+
+  private static _getExpectedPathForPackage(packageJson: IPackageJson): string {
+    // Rule 1: If package.json contains the field "tsdocConfig" then that takes precedence
+    // then that takes precedence.  This convention will be rarely needed, since the later
+    // generally produce a good result.
+    if (packageJson.tsdocConfig) {
+      return packageJson.tsdocConfig;
+    }
+
+    // Rule 2: If package.json contains a field such as "types" or "typings", then look
+    // for the file in that folder
+    //
+    // Rule 3: If package.json contains a field such as "main", then we would look
+    // for the file in that folder.
+    //
+    // Rule 4: Other wise look in the package.json folder, since the default entry point
+    // is './index.js'
+
+    let entryPointPath: string = 'index.js';
+    if (packageJson.types) {
+      entryPointPath = packageJson.types;
+    } else if (packageJson.typings) {
+      entryPointPath = packageJson.typings;
+    } else if (packageJson.main) {
+      entryPointPath = packageJson.main;
+    }
+    const entryPointFolder: string = path.dirname(entryPointPath);
+
+    return path.join(entryPointFolder, ConfigLoader.JSON_FILE_NAME);
+  }
+
+  /**
+   * Given a `packageFolder` path, probe for tsdoc-config.json and return the
+   * path to this file.
+   * @returns the absolute path, or `undefined` if not found
+   */
+  private static _tryGetValidPath(packageFolder: string): string | undefined {
+    const packageJsonPath: string = path.join(packageFolder, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+      throw new Error('package.json was not found under the path: ' + packageFolder);
+    }
+    const packageJsonContent: string = fs.readFileSync(packageJsonPath).toString();
+    const packageJson: IPackageJson = JSON.parse(packageJsonContent);
+    const configFilePath: string = ConfigLoader._getExpectedPathForPackage(packageJson);
+    const configFileAbsolutePath: string = path.resolve(packageFolder, configFilePath);
+
+    if (fs.existsSync(configFileAbsolutePath)) {
+      return configFileAbsolutePath;
+    }
+
+    return undefined;
+  }
+
+  public static tryLoadFromPackageFolder(packageFolder: string): TSDocConfigFile | undefined {
+
+    const rootConfigFilePath: string | undefined = ConfigLoader._tryGetValidPath(packageFolder);
+
+    if (!rootConfigFilePath) {
+      return undefined;
+    }
+
+    return TSDocConfigFile.load(rootConfigFilePath);
+  }
+}

tsdoc-config/src/TSDocConfigFile.ts

@@ -0,0 +1,17 @@
+interface ITSDocConfigFileData {
+  filePath: string;
+}
+
+export class TSDocConfigFile {
+  public readonly filePath: string;
+
+  private constructor(data: ITSDocConfigFileData) {
+    this.filePath = data.filePath;
+  }
+
+  public static load(filePath: string): TSDocConfigFile {
+    return new TSDocConfigFile({
+      filePath
+    });
+  }
+}

tsdoc-config/src/__tests__/ConfigLoader.test.ts

@@ -0,0 +1,33 @@
+import * as path from 'path';
+
+import { TSDocConfigFile } from '../TSDocConfigFile';
+import { ConfigLoader } from '../ConfigLoader';
+
+function getRelativePath(testPath: string): string {
+  return path.relative(__dirname, testPath).split('\\').join('/');
+}
+
+test('Resolve p1', () => {
+  const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder(
+    path.join(__dirname, 'assets/p1'));
+  expect(configFile).toBeDefined();
+  expect(getRelativePath(configFile!.filePath)).toEqual('assets/p1/folder/tsdoc-config.json');
+});
+test('Resolve p2', () => {
+  const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder(
+    path.join(__dirname, 'assets/p2'));
+  expect(configFile).toBeDefined();
+  expect(getRelativePath(configFile!.filePath)).toEqual('assets/p2/folder/tsdoc-config.json');
+});
+test('Resolve p3', () => {
+  const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder(
+    path.join(__dirname, 'assets/p3'));
+  expect(configFile).toBeDefined();
+  expect(getRelativePath(configFile!.filePath)).toEqual('assets/p3/folder/tsdoc-config.json');
+});
+test('Resolve p4', () => {
+  const configFile: TSDocConfigFile | undefined = ConfigLoader.tryLoadFromPackageFolder(
+    path.join(__dirname, 'assets/p4'));
+  expect(configFile).toBeDefined();
+  expect(getRelativePath(configFile!.filePath)).toEqual('assets/p4/tsdoc-config.json');
+});

tsdoc-config/src/__tests__/assets/p1/folder/tsdoc-config.json

@@ -0,0 +1,3 @@
+{
+  "tsdocVersion": "0.12"
+}

tsdoc-config/src/__tests__/assets/p1/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "p1",
+  "version": "1.0.0",
+  "tsdocConfig": "./folder/tsdoc-config.json"
+}

tsdoc-config/src/__tests__/assets/p2/folder/index.d.ts

@@ -0,0 +1 @@
+// empty

tsdoc-config/src/__tests__/assets/p2/folder/tsdoc-config.json

@@ -0,0 +1,3 @@
+{
+  "tsdocVersion": "0.12"
+}

tsdoc-config/src/__tests__/assets/p2/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "p2",
+  "version": "1.0.0",
+  "typings": "./folder/index.d.ts"
+}

tsdoc-config/src/__tests__/assets/p3/folder/index.js

@@ -0,0 +1 @@
+// empty