dependency-cruiser 10.8.0 → 11.2.0

package/README.md

@@ -21,7 +21,7 @@ you can stick on the wall to impress your grandma.
 ### Install it
 
 - `npm install --save-dev dependency-cruiser` to use it as a validator in your project (recommended) or...
-- `npm install --global dependency-cruiser` if you just want to to inspect multiple projects.
+- `npm install --global dependency-cruiser` if you just want to inspect multiple projects.
 
 ### Show stuff to your grandma
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dependency-cruiser",
-  "version": "10.8.0",
+  "version": "11.2.0",
   "description": "Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.",
   "keywords": [
     "static analysis",
@@ -76,7 +76,6 @@
     "depcruise:all": "node ./bin/dependency-cruise.js src bin test configs types tools --config",
     "depcruise:baseline": "node ./bin/depcruise-baseline.js src bin test configs types tools",
     "depcruise:explain": "node ./bin/dependency-cruise.js src bin test configs types tools --output-type err-long --config --progress none",
-    "depcruise:graph:dev": "node ./bin/dependency-cruise.js bin src --prefix vscode://file/$(pwd)/ --config --output-type dot --progress cli-feedback | dot -T svg | node ./bin/wrap-stream-in-html.js | browser",
     "depcruise:graph:doc": "npm-run-all depcruise:graph:doc:json --parallel depcruise:graph:doc:fmt-* depcruise:graph:doc:samples",
     "depcruise:graph:doc:json": "node ./bin/dependency-cruise.js bin src test --config --output-type json --output-to tmp_graph_deps.json --progress",
     "depcruise:graph:doc:fmt-detail": "./bin/depcruise-fmt.js -T dot -f - tmp_graph_deps.json | dot -T svg | tee doc/real-world-samples/dependency-cruiser-without-node_modules.svg | node bin/wrap-stream-in-html.js > docs/dependency-cruiser-dependency-graph.html",
@@ -88,7 +87,9 @@
     "depcruise:graph:dot": "node ./bin/dependency-cruise.js bin src --config --output-type dot | dot -T svg > tmp_deps.svg",
     "depcruise:graph:fdp": "node ./bin/dependency-cruise.js bin src --config --output-type dot | fdp -GK=0.1 -Gsplines=true -T svg > tmp_deps.svg",
     "depcruise:graph:osage": "node ./bin/dependency-cruise.js bin src --config --output-type dot | osage -Gpack=32 -GpackMode=array2 -T svg > tmp_deps.svg",
-    "depcruise:report": "node ./bin/dependency-cruise.js src bin test configs types --output-type err-html --config --output-to dependency-violations.html",
+    "depcruise:graph:view": "node ./bin/dependency-cruise.js bin src --prefix vscode://file/$(pwd)/ --config configs/.dependency-cruiser-show-metrics-config.json --output-type dot --progress cli-feedback | dot -T svg | node ./bin/wrap-stream-in-html.js | browser",
+    "depcruise:report": "node ./bin/dependency-cruise.js src bin test configs types --output-type err-html --config configs/.dependency-cruiser-show-metrics-config.json --output-to dependency-violations.html",
+    "depcruise:report:view": "node ./bin/dependency-cruise.js src bin test configs types --output-type err-html --config configs/.dependency-cruiser-show-metrics-config.json --output-to - | browser",
     "depcruise:focus": "node ./bin/dependency-cruise.js src bin test configs types --progress --config --output-type text --focus",
     "lint": "npm-run-all --parallel --aggregate-output lint:eslint lint:prettier:check lint:types",
     "lint:eslint": "eslint bin/dependency-cruise.js src test configs tools/**/*.mjs --cache --cache-location .cache/eslint/",
@@ -151,18 +152,18 @@
     "safe-regex": "2.1.1",
     "semver": "^7.3.5",
     "semver-try-require": "^5.0.1",
-    "teamcity-service-messages": "0.1.11",
+    "teamcity-service-messages": "0.1.12",
     "tsconfig-paths-webpack-plugin": "3.5.2",
     "wrap-ansi": "^7.0.0"
   },
   "devDependencies": {
-    "@babel/core": "7.16.0",
-    "@babel/plugin-transform-modules-commonjs": "7.16.0",
-    "@babel/preset-typescript": "7.16.0",
-    "@swc/core": "1.2.113",
-    "@typescript-eslint/eslint-plugin": "5.4.0",
-    "@typescript-eslint/parser": "5.4.0",
-    "@vue/compiler-sfc": "3.2.23",
+    "@babel/core": "7.16.5",
+    "@babel/plugin-transform-modules-commonjs": "7.16.5",
+    "@babel/preset-typescript": "7.16.5",
+    "@swc/core": "1.2.123",
+    "@typescript-eslint/eslint-plugin": "5.8.0",
+    "@typescript-eslint/parser": "5.8.0",
+    "@vue/compiler-sfc": "3.2.26",
     "c8": "7.10.0",
     "chai": "4.3.4",
     "chai-json-schema": "1.5.1",
@@ -172,22 +173,22 @@
     "eslint-config-prettier": "8.3.0",
     "eslint-plugin-budapestian": "3.0.1",
     "eslint-plugin-import": "2.25.3",
-    "eslint-plugin-mocha": "9.0.0",
+    "eslint-plugin-mocha": "^9.0.0",
     "eslint-plugin-node": "11.1.0",
     "eslint-plugin-security": "1.4.0",
     "eslint-plugin-unicorn": "39.0.0",
     "husky": "^4.3.8",
     "intercept-stdout": "0.1.2",
-    "lint-staged": "12.1.2",
+    "lint-staged": "12.1.4",
     "mocha": "9.1.3",
     "normalize-newline": "^3.0.0",
     "npm-run-all": "4.1.5",
-    "prettier": "2.5.0",
+    "prettier": "2.5.1",
     "proxyquire": "2.1.3",
     "shx": "0.3.3",
-    "svelte": "3.44.2",
+    "svelte": "3.44.3",
     "symlink-dir": "5.0.1",
-    "typescript": "4.5.2",
+    "typescript": "4.5.4",
     "upem": "^7.0.0",
     "vue-template-compiler": "2.6.14",
     "yarn": "1.22.17"
@@ -219,6 +220,11 @@
         "policy": "wanted",
         "because": "version 5 only exports ejs - and we use cjs and don't transpile"
       },
+      {
+        "package": "eslint-plugin-mocha",
+        "policy": "wanted",
+        "because": "version 10 dropped support for node 12, which we still do support"
+      },
       {
         "package": "normalize-newline",
         "policy": "wanted",

package/src/enrich/clear-caches.js

@@ -1,4 +1,4 @@
-const utl = require("./derive/utl");
+const utl = require("./derive/module-utl");
 
 module.exports = function clearCaches() {
   utl.clearCache();

package/src/enrich/derive/circular/get-cycle.js

@@ -1,4 +1,4 @@
-const { findModuleByName } = require("../utl");
+const { findModuleByName } = require("../module-utl");
 /* about the absence of checks whether attributes/ objects actually
  * exist:
  * - it saves CPU cycles to the effect of being ~30% faster than with the

package/src/enrich/derive/dependents/get-dependents.js

@@ -1,4 +1,4 @@
-const { isDependent } = require("../utl");
+const { isDependent } = require("../module-utl");
 
 module.exports = function getDependents(pModule, pModules) {
   // perf between O(n) in an unconnected graph and O(n^2) in a fully connected one

package/src/enrich/derive/{metrics/get-stability-metrics.js → folders/aggregate-to-folders.js}

@@ -1,11 +1,12 @@
 /* eslint-disable security/detect-object-injection */
 const path = require("path").posix;
-const { foldersObject2folderArray, getParentFolders } = require("./utl");
+const { calculateInstability, metricsAreCalculable } = require("../module-utl");
 const {
   getAfferentCouplings,
   getEfferentCouplings,
-  metricsAreCalculable,
-} = require("./module-utl");
+  getParentFolders,
+  object2Array,
+} = require("./utl");
 
 function upsertCouplings(pAllDependents, pNewDependents) {
   pNewDependents.forEach((pNewDependent) => {
@@ -34,16 +35,14 @@ function upsertFolderAttributes(pAllMetrics, pModule, pDirname) {
     )
   );
   pAllMetrics[pDirname].moduleCount += 1;
-
   return pAllMetrics;
 }
 
-function orderFolderMetrics(pLeftMetric, pRightMetric) {
-  // return pLeft.name.localeCompare(pRight.name);
-  // For intended use in a table it's probably more useful to sort by
-  // instability. Might need to be either configurable or flexible
-  // in the output, though
-  return pRightMetric.instability - pLeftMetric.instability;
+function aggregateToFolder(pAllFolders, pModule) {
+  getParentFolders(path.dirname(pModule.source)).forEach((pParentDirectory) =>
+    upsertFolderAttributes(pAllFolders, pModule, pParentDirectory)
+  );
+  return pAllFolders;
 }
 
 function sumCounts(pAll, pCurrent) {
@@ -59,12 +58,15 @@ function getFolderLevelCouplings(pCouplingArray) {
           : path.dirname(pCoupling.name)
       )
     )
-  );
+  ).map((pCoupling) => ({ name: pCoupling }));
 }
 
 function calculateFolderMetrics(pFolder) {
-  const lModuleDependents = foldersObject2folderArray(pFolder.dependents);
-  const lModuleDependencies = foldersObject2folderArray(pFolder.dependencies);
+  const lModuleDependents = object2Array(pFolder.dependents);
+  const lModuleDependencies = object2Array(pFolder.dependencies);
+  // this calculation might look superfluous (why not just .length the dependents
+  // and dependencies?), but it isn't because there can be > 1 relation between
+  // two folders
   const lAfferentCouplings = lModuleDependents.reduce(sumCounts, 0);
   const lEfferentCouplings = lModuleDependencies.reduce(sumCounts, 0);
 
@@ -72,26 +74,33 @@ function calculateFolderMetrics(pFolder) {
     ...pFolder,
     afferentCouplings: lAfferentCouplings,
     efferentCouplings: lEfferentCouplings,
-    // when both afferentCouplings and efferentCouplings equal 0 instability will
-    // yield NaN. Judging Bob Martin's intention, a component with no outgoing
-    // dependencies is maximum stable (0)
-    instability:
-      lEfferentCouplings / (lEfferentCouplings + lAfferentCouplings) || 0,
+    instability: calculateInstability(lEfferentCouplings, lAfferentCouplings),
     dependents: getFolderLevelCouplings(lModuleDependents),
     dependencies: getFolderLevelCouplings(lModuleDependencies),
   };
 }
 
-module.exports = function getStabilityMetrics(pModules) {
-  return foldersObject2folderArray(
-    pModules.filter(metricsAreCalculable).reduce((pAllFolders, pModule) => {
-      getParentFolders(path.dirname(pModule.source)).forEach(
-        (pParentDirectory) =>
-          upsertFolderAttributes(pAllFolders, pModule, pParentDirectory)
-      );
-      return pAllFolders;
-    }, {})
-  )
-    .map(calculateFolderMetrics)
-    .sort(orderFolderMetrics);
+function findFolderByName(pAllFolders, pName) {
+  return pAllFolders.find((pFolder) => pFolder.name === pName);
+}
+
+function denormalizeInstability(pAllFolders) {
+  return (pFolder) => ({
+    ...pFolder,
+    dependencies: pFolder.dependencies.map((pDependency) => {
+      const lFolder = findFolderByName(pAllFolders, pDependency.name) || {};
+      return {
+        ...pDependency,
+        instability: lFolder.instability >= 0 ? lFolder.instability : 0,
+      };
+    }),
+  });
+}
+
+module.exports = function aggregateToFolders(pModules) {
+  const lFolders = object2Array(
+    pModules.filter(metricsAreCalculable).reduce(aggregateToFolder, {})
+  ).map(calculateFolderMetrics);
+
+  return lFolders.map(denormalizeInstability(lFolders));
 };

package/src/enrich/derive/folders/index.js

@@ -0,0 +1,9 @@
+const aggregateToFolders = require("./aggregate-to-folders");
+
+module.exports = function deriveFolderMetrics(pModules, pOptions) {
+  let lReturnValue = {};
+  if (pOptions.metrics) {
+    lReturnValue = { folders: aggregateToFolders(pModules) };
+  }
+  return lReturnValue;
+};

package/src/enrich/derive/folders/utl.js

@@ -0,0 +1,44 @@
+/* eslint-disable security/detect-object-injection */
+const path = require("path").posix;
+
+function getAfferentCouplings(pModule, pDirname) {
+  return pModule.dependents.filter(
+    (pDependent) => !pDependent.startsWith(pDirname.concat(path.sep))
+  );
+}
+
+function getEfferentCouplings(pModule, pDirname) {
+  return pModule.dependencies.filter(
+    (pDependency) => !pDependency.resolved.startsWith(pDirname.concat(path.sep))
+  );
+}
+
+/**
+ *
+ * @param {string} pPath
+ * @returns string[]
+ */
+function getParentFolders(pPath) {
+  let lFragments = pPath.split("/");
+  let lReturnValue = [];
+
+  while (lFragments.length > 0) {
+    lReturnValue.push(lFragments.join("/"));
+    lFragments.pop();
+  }
+  return lReturnValue.reverse();
+}
+
+function object2Array(pObject) {
+  return Object.keys(pObject).map((pKey) => ({
+    name: pKey,
+    ...pObject[pKey],
+  }));
+}
+
+module.exports = {
+  getAfferentCouplings,
+  getEfferentCouplings,
+  getParentFolders,
+  object2Array,
+};

package/src/enrich/derive/metrics/get-module-metrics.js

@@ -0,0 +1,39 @@
+const { findModuleByName } = require("../module-utl");
+const { calculateInstability, metricsAreCalculable } = require("../module-utl");
+
+function addInstabilityMetric(pModule) {
+  return {
+    ...pModule,
+    ...(metricsAreCalculable(pModule)
+      ? {
+          instability: calculateInstability(
+            pModule.dependencies.length,
+            pModule.dependents.length
+          ),
+        }
+      : {}),
+  };
+}
+
+function addInstabilityToDependency(pAllModules) {
+  return (pDependency) => ({
+    ...pDependency,
+    instability:
+      (findModuleByName(pAllModules, pDependency.resolved) || {}).instability ||
+      0,
+  });
+}
+
+function deNormalizeInstabilityMetricsToDependencies(pModule, _, pAllModules) {
+  return {
+    ...pModule,
+    dependencies: pModule.dependencies.map(
+      addInstabilityToDependency(pAllModules)
+    ),
+  };
+}
+
+module.exports = {
+  addInstabilityMetric,
+  deNormalizeInstabilityMetricsToDependencies,
+};

package/src/enrich/derive/metrics/index.js

@@ -0,0 +1,14 @@
+const { clearCache } = require("../module-utl");
+const {
+  addInstabilityMetric,
+  deNormalizeInstabilityMetricsToDependencies,
+} = require("./get-module-metrics");
+
+module.exports = function deriveModulesMetrics(pModules, pOptions) {
+  if (pOptions.metrics) {
+    const lModules = pModules.map(addInstabilityMetric);
+    clearCache();
+    return lModules.map(deNormalizeInstabilityMetricsToDependencies);
+  }
+  return pModules;
+};

package/src/enrich/derive/{utl.js → module-utl.js}

@@ -28,6 +28,32 @@ function isDependent(pResolvedName) {
     );
 }
 
+function metricsAreCalculable(pModule) {
+  return (
+    !pModule.coreModule &&
+    !pModule.couldNotResolve &&
+    !pModule.matchesDoNotFollow
+  );
+}
+
+/**
+ * returns the Instability of a component given the number of incoming (afferent)
+ * and outgoign (efferent) connections ('couplings')
+ *
+ * @param {number} pEfferentCouplingCount
+ * @param {number} pAfferentCouplingCount
+ * @returns number
+ */
+function calculateInstability(pEfferentCouplingCount, pAfferentCouplingCount) {
+  // when both afferentCouplings and efferentCouplings equal 0 instability will
+  // yield NaN. Judging Bob Martin's intention, a component with no outgoing
+  // dependencies is maximum stable (0)
+  return (
+    pEfferentCouplingCount /
+      (pEfferentCouplingCount + pAfferentCouplingCount) || 0
+  );
+}
+
 function clearCache() {
   gIndexedGraph = null;
 }
@@ -36,4 +62,6 @@ module.exports = {
   findModuleByName,
   clearCache,
   isDependent,
+  metricsAreCalculable,
+  calculateInstability,
 };

package/src/enrich/derive/orphan/is-orphan.js

@@ -1,4 +1,4 @@
-const { isDependent } = require("../utl");
+const { isDependent } = require("../module-utl");
 
 module.exports = (pModule, pGraph) => {
   if (pModule.dependencies.length > 0) {

package/src/enrich/derive/reachable/get-path.js

@@ -1,4 +1,4 @@
-const { findModuleByName } = require("../utl");
+const { findModuleByName } = require("../module-utl");
 
 function getPath(pGraph, pFrom, pTo, pVisited = new Set()) {
   let lReturnValue = [];

package/src/enrich/derive/reachable/index.js

@@ -4,7 +4,7 @@ const _clone = require("lodash/clone");
 const _get = require("lodash/get");
 const _has = require("lodash/has");
 const matchers = require("../../../validate/matchers");
-const { extractGroups } = require("../../../validate/utl");
+const { extractGroups } = require("../../../utl/regex-util");
 const getPath = require("./get-path");
 
 function getReachableRules(pRuleSet) {

package/src/enrich/enrich-modules.js

@@ -8,7 +8,7 @@ const addDependents = require("./derive/dependents");
 const deriveReachable = require("./derive/reachable");
 const addValidations = require("./add-validations");
 const softenKnownViolations = require("./soften-known-violations");
-const deriveModuleMetrics = require("./derive/metrics/module");
+const deriveModuleMetrics = require("./derive/metrics");
 
 module.exports = function enrichModules(pModules, pOptions) {
   bus.emit("progress", "analyzing: cycles", { level: busLogLevels.INFO });
@@ -19,7 +19,7 @@ module.exports = function enrichModules(pModules, pOptions) {
   lModules = deriveOrphans(lModules);
   bus.emit("progress", "analyzing: reachables", { level: busLogLevels.INFO });
   lModules = deriveReachable(lModules, pOptions.ruleSet);
-  bus.emit("progress", "analyzing: calculating module metrics", {
+  bus.emit("progress", "analyzing: module metrics", {
     level: busLogLevels.INFO,
   });
   lModules = deriveModuleMetrics(lModules, pOptions);

package/src/enrich/index.js

@@ -1,5 +1,5 @@
 const enrichModules = require("./enrich-modules");
-const deriveFolderMetrics = require("./derive/metrics/folder.js");
+const aggregateToFolders = require("./derive/folders");
 const summarize = require("./summarize");
 const clearCaches = require("./clear-caches");
 
@@ -10,7 +10,7 @@ module.exports = function enrich(pModules, pOptions, pFileAndDirectoryArray) {
   clearCaches();
   return {
     modules: lModules,
-    ...deriveFolderMetrics(lModules, pOptions),
+    ...aggregateToFolders(lModules, pOptions),
     summary: summarize(lModules, pOptions, pFileAndDirectoryArray),
   };
 };

package/src/enrich/summarize/summarize-modules.js

@@ -1,14 +1,15 @@
 const _flattenDeep = require("lodash/flattenDeep");
 const _get = require("lodash/get");
+const _has = require("lodash/has");
 const _uniqWith = require("lodash/uniqWith");
 const { findRuleByName } = require("../../graph-utl/rule-set");
 const compare = require("../../graph-utl/compare");
 const isSameViolation = require("./is-same-violation");
 
-function cutNonTransgressions(pSourceEntry) {
+function cutNonTransgressions(pModule) {
   return {
-    source: pSourceEntry.source,
-    dependencies: pSourceEntry.dependencies.filter(
+    ...pModule,
+    dependencies: pModule.dependencies.filter(
       (pDependency) => pDependency.valid === false
     ),
   };
@@ -30,21 +31,38 @@ function extractMetaData(pViolations) {
 }
 function toDependencyViolationSummary(pRule, pModule, pDependency, pRuleSet) {
   let lReturnValue = {
+    type: "dependency",
     from: pModule.source,
     to: pDependency.resolved,
     rule: pRule,
   };
 
   if (
-    pDependency.cycle &&
+    _has(pDependency, "cycle") &&
     _get(findRuleByName(pRuleSet, pRule.name), "to.circular")
   ) {
     lReturnValue = {
       ...lReturnValue,
+      type: "cycle",
       cycle: pDependency.cycle,
     };
   }
 
+  if (
+    _has(pModule, "instability") &&
+    _has(pDependency, "instability") &&
+    _has(findRuleByName(pRuleSet, pRule.name), "to.moreUnstable")
+  ) {
+    lReturnValue = {
+      ...lReturnValue,
+      type: "instability",
+      metrics: {
+        from: { instability: pModule.instability },
+        to: { instability: pDependency.instability },
+      },
+    };
+  }
+
   return lReturnValue;
 }
 
@@ -82,7 +100,7 @@ function extractDependencyViolations(pModules, pRuleSet) {
 
 function toModuleViolationSummary(pRule, pModule, pRuleSet) {
   let lReturnValue = [
-    { from: pModule.source, to: pModule.source, rule: pRule },
+    { type: "module", from: pModule.source, to: pModule.source, rule: pRule },
   ];
   if (
     pModule.reaches &&
@@ -101,6 +119,7 @@ function toModuleViolationSummary(pRule, pModule, pRuleSet) {
         []
       )
       .map((pToModule) => ({
+        type: "reachability",
         from: pModule.source,
         to: pToModule.to,
         rule: pRule,

package/src/extract/get-dependencies.js

@@ -21,15 +21,18 @@ function extractFromSwcAST(pOptions, pFileName) {
   );
 }
 
-function extractFromTypeScriptAST(pOptions, pFileName) {
+function extractFromTypeScriptAST(pOptions, pFileName, pTranspileOptions) {
   return extractTypeScriptDeps(
-    toTypescriptAST.getASTCached(path.join(pOptions.baseDir, pFileName)),
+    toTypescriptAST.getASTCached(
+      path.join(pOptions.baseDir, pFileName),
+      pTranspileOptions
+    ),
     pOptions.exoticRequireStrings
   );
 }
 
 function isTypeScriptCompatible(pFileName) {
-  return [".ts", ".tsx", ".js", ".mjs", ".cjs"].includes(
+  return [".ts", ".tsx", ".js", ".mjs", ".cjs", ".vue"].includes(
     path.extname(pFileName)
   );
 }
@@ -88,9 +91,11 @@ function extractWithTsc(
   pFileName,
   pTranspileOptions
 ) {
-  pDependencies = extractFromTypeScriptAST(pCruiseOptions, pFileName).filter(
-    (pDep) => pCruiseOptions.moduleSystems.includes(pDep.moduleSystem)
-  );
+  pDependencies = extractFromTypeScriptAST(
+    pCruiseOptions,
+    pFileName,
+    pTranspileOptions
+  ).filter((pDep) => pCruiseOptions.moduleSystems.includes(pDep.moduleSystem));
 
   if (pCruiseOptions.tsPreCompilationDeps === "specify") {
     pDependencies = detectPreCompilationNess(

package/src/extract/parse/to-typescript-ast.js

@@ -2,21 +2,28 @@ const fs = require("fs");
 const tryRequire = require("semver-try-require");
 const _memoize = require("lodash/memoize");
 const { supportedTranspilers } = require("../../../src/meta.js");
+const transpile = require("../transpile");
+const getExtension = require("../utl/get-extension");
 
 const typescript = tryRequire("typescript", supportedTranspilers.typescript);
 
 /**
  * Compiles pTypescriptSource into a (typescript) AST
  *
- * @param {string} pTypescriptSource - the source to compile
- * @param {string} [pFileName] - (optional) file name the typescript
- *                              compiler can use in error messages
+ * @param {object} pFileRecord Record with source code, an extension and a filename
+ * @param {any} [pTranspileOptions] options for the transpiler(s) - a tsconfig or
+ *                                a babel config
  * @return {object} - a (typescript) AST
  */
-function getASTFromSource(pTypescriptSource, pFileName) {
+function getASTFromSource(pFileRecord, pTranspileOptions) {
+  let lSource = pFileRecord.source;
+  if (pFileRecord.extension === ".vue") {
+    lSource = transpile(pFileRecord, pTranspileOptions);
+  }
+
   return typescript.createSourceFile(
-    pFileName || "$internal-file-name",
-    pTypescriptSource,
+    pFileRecord.filename || "$internal-file-name",
+    lSource,
     typescript.ScriptTarget.Latest,
     false
   );
@@ -27,10 +34,19 @@ function getASTFromSource(pTypescriptSource, pFileName) {
  * AST and returns it
  *
  * @param {string} pFileName - the name of the file to compile
+ * @param {any} [pTranspileOptions] options for the transpiler(s) - a tsconfig or
+ *                                a babel config
  * @return {object} - a (typescript) AST
  */
-function getAST(pFileName) {
-  return getASTFromSource(fs.readFileSync(pFileName, "utf8"), pFileName);
+function getAST(pFileName, pTranspileOptions) {
+  return getASTFromSource(
+    {
+      source: fs.readFileSync(pFileName, "utf8"),
+      extension: getExtension(pFileName),
+      filename: pFileName,
+    },
+    pTranspileOptions
+  );
 }
 
 const getASTCached = _memoize(getAST);

package/src/extract/utl/get-extension.js

@@ -5,16 +5,20 @@ const path = require("path");
  *
  * Just using path.extname would be fine for most cases,
  * except for coffeescript, where a markdown extension can
- * mean literate coffeescript.
+ * mean literate coffeescript, and for typescript where
+ * .d.ts and .ts are slightly different beasts
  *
  * @param {string} pFileName path to the file to be parsed
  * @return {string}          extension
  */
 module.exports = function getExtensions(pFileName) {
-  let lReturnValue = path.extname(pFileName);
+  if (pFileName.endsWith(".d.ts")) {
+    return ".d.ts";
+  }
 
-  if (lReturnValue === ".md") {
-    return pFileName.endsWith(".coffee.md") ? ".coffee.md" : lReturnValue;
+  if (pFileName.endsWith(".coffee.md")) {
+    return ".coffee.md";
   }
-  return lReturnValue;
+
+  return path.extname(pFileName);
 };