JS: Deprecate PathExpr, PathString, and Path

Author: asgerf

javascript/ql/lib/semmle/javascript/AMD.qll

@@ -61,8 +61,14 @@ class AmdModuleDefinition extends CallExpr instanceof AmdModuleDefinition::Range
     result = this.getArgument(1)
   }
 
+  /** DEPRECATED. Use `getDependencyExpr` instead. */
+  deprecated PathExpr getDependency(int i) { result = this.getDependencyExpr(i) }
+
+  /** DEPRECATED. Use `getADependencyExpr` instead. */
+  deprecated PathExpr getADependency() { result = this.getADependencyExpr() }
+
   /** Gets the `i`th dependency of this module definition. */
-  PathExpr getDependency(int i) {
+  Expr getDependencyExpr(int i) {
     exists(Expr expr |
       expr = this.getDependencies().getElement(i) and
       not isPseudoDependency(expr.getStringValue()) and
@@ -71,8 +77,8 @@ class AmdModuleDefinition extends CallExpr instanceof AmdModuleDefinition::Range
   }
 
   /** Gets a dependency of this module definition. */
-  PathExpr getADependency() {
-    result = this.getDependency(_) or
+  Expr getADependencyExpr() {
+    result = this.getDependencyExpr(_) or
     result = this.getARequireCall().getAnArgument()
   }
 
@@ -233,7 +239,7 @@ private class AmdDependencyPath extends PathExprCandidate {
 }
 
 /** A constant path element appearing in an AMD dependency expression. */
-private class ConstantAmdDependencyPathElement extends PathExpr, ConstantString {
+deprecated private class ConstantAmdDependencyPathElement extends PathExpr, ConstantString {
   ConstantAmdDependencyPathElement() { this = any(AmdDependencyPath amd).getAPart() }
 
   override string getValue() { result = this.getStringValue() }
@@ -261,9 +267,11 @@ private predicate amdModuleTopLevel(AmdModuleDefinition def, TopLevel tl) {
  * An AMD dependency, viewed as an import.
  */
 private class AmdDependencyImport extends Import {
-  AmdDependencyImport() { this = any(AmdModuleDefinition def).getADependency() }
+  AmdDependencyImport() { this = any(AmdModuleDefinition def).getADependencyExpr() }
 
-  override Module getEnclosingModule() { this = result.(AmdModule).getDefine().getADependency() }
+  override Module getEnclosingModule() {
+    this = result.(AmdModule).getDefine().getADependencyExpr()
+  }
 
   override Expr getImportedPathExpr() { result = this }
 
@@ -274,7 +282,7 @@ private class AmdDependencyImport extends Import {
    * adding well-known JavaScript file extensions like `.js`.
    */
   private File guessTarget() {
-    exists(PathString imported, string abspath, string dirname, string basename |
+    exists(StringAsPath imported, string abspath, string dirname, string basename |
       this.targetCandidate(result, abspath, imported, dirname, basename)
     |
       abspath.regexpMatch(".*/\\Q" + imported + "\\E")
@@ -296,7 +304,7 @@ private class AmdDependencyImport extends Import {
    * `dirname` and `basename` to the dirname and basename (respectively) of `imported`.
    */
   private predicate targetCandidate(
-    File f, string abspath, PathString imported, string dirname, string basename
+    File f, string abspath, StringAsPath imported, string dirname, string basename
   ) {
     imported = this.getImportedPathString() and
     f.getStem() = imported.getStem() and

javascript/ql/lib/semmle/javascript/ES2015Modules.qll

@@ -150,7 +150,7 @@ class ImportDeclaration extends Stmt, Import, @import_declaration {
 }
 
 /** A literal path expression appearing in an `import` declaration. */
-private class LiteralImportPath extends PathExpr, ConstantString {
+deprecated private class LiteralImportPath extends PathExpr, ConstantString {
   LiteralImportPath() { exists(ImportDeclaration req | this = req.getChildExpr(-1)) }
 
   override string getValue() { result = this.getStringValue() }
@@ -731,7 +731,7 @@ abstract class ReExportDeclaration extends ExportDeclaration {
 }
 
 /** A literal path expression appearing in a re-export declaration. */
-private class LiteralReExportPath extends PathExpr, ConstantString {
+deprecated private class LiteralReExportPath extends PathExpr, ConstantString {
   LiteralReExportPath() { exists(ReExportDeclaration bred | this = bred.getImportedPath()) }
 
   override string getValue() { result = this.getStringValue() }

javascript/ql/lib/semmle/javascript/Expr.qll

@@ -2852,7 +2852,7 @@ class DynamicImportExpr extends @dynamic_import, Expr, Import {
 }
 
 /** A literal path expression appearing in a dynamic import. */
-private class LiteralDynamicImportPath extends PathExpr, ConstantString {
+deprecated private class LiteralDynamicImportPath extends PathExpr, ConstantString {
   LiteralDynamicImportPath() {
     exists(DynamicImportExpr di | this.getParentExpr*() = di.getSource())
   }

javascript/ql/lib/semmle/javascript/Modules.qll

@@ -69,7 +69,7 @@ abstract class Module extends TopLevel {
    * This predicate is not part of the public API, it is only exposed to allow
    * overriding by subclasses.
    */
-  predicate searchRoot(PathExpr path, Folder searchRoot, int priority) {
+  deprecated predicate searchRoot(PathExpr path, Folder searchRoot, int priority) {
     path.getEnclosingModule() = this and
     priority = 0 and
     exists(string v | v = path.getValue() |
@@ -90,7 +90,7 @@ abstract class Module extends TopLevel {
    * resolves to a folder containing a main module (such as `index.js`), then
    * that file is the result.
    */
-  File resolve(PathExpr path) {
+  deprecated File resolve(PathExpr path) {
     path.getEnclosingModule() = this and
     (
       // handle the case where the import path is complete
@@ -149,7 +149,7 @@ abstract class Import extends AstNode {
   /**
    * Gets the module the path of this import resolves to.
    */
-  File getTargetFile() { result = Resolver::resolveExpr(this.getImportedPathExpr()) }
+  File getTargetFile() { result = ImportPathResolver::resolveExpr(this.getImportedPathExpr()) }
 
   /**
    * DEPRECATED. Use `getImportedModule()` instead.

javascript/ql/lib/semmle/javascript/NodeJS.qll

@@ -146,7 +146,7 @@ class NodeModule extends Module {
     )
   }
 
-  override predicate searchRoot(PathExpr path, Folder searchRoot, int priority) {
+  deprecated override predicate searchRoot(PathExpr path, Folder searchRoot, int priority) {
     path.getEnclosingModule() = this and
     exists(string pathval | pathval = path.getValue() |
       // paths starting with `./` or `../` are resolved relative to the importing
@@ -333,7 +333,7 @@ class Require extends CallExpr, Import {
    * The result can be a JavaScript file, a JSON file or a `.node` file.
    * Externs files are not treated differently from other files by this predicate.
    */
-  File getImportedFile() { result = this.load(min(int prio | exists(this.load(prio)))) }
+  deprecated File getImportedFile() { result = this.load(min(int prio | exists(this.load(prio)))) }
 
   /**
    * Gets the file that this `require` refers to (which may not be a JavaScript file),
@@ -390,7 +390,7 @@ class Require extends CallExpr, Import {
    * predicate `tryExtensions` that handles the repeated distinction between
    * `.js`, `.json` and `.node`.
    */
-  private File load(int priority) {
+  deprecated private File load(int priority) {
     exists(int r | this.getEnclosingModule().searchRoot(this.getImportedPathExpr(), _, r) |
       result = loadAsFile(this, r, priority - prioritiesPerCandidate() * r) or
       result =
@@ -403,7 +403,7 @@ class Require extends CallExpr, Import {
 }
 
 /** An argument to `require` or `require.resolve`, considered as a path expression. */
-private class RequirePath extends PathExprCandidate {
+deprecated private class RequirePath extends PathExprCandidate {
   RequirePath() {
     this = any(Require req).getArgument(0)
     or
@@ -416,14 +416,14 @@ private class RequirePath extends PathExprCandidate {
 }
 
 /** A constant path element appearing in a call to `require` or `require.resolve`. */
-private class ConstantRequirePathElement extends PathExpr, ConstantString {
+deprecated private class ConstantRequirePathElement extends PathExpr, ConstantString {
   ConstantRequirePathElement() { this = any(RequirePath rp).getAPart() }
 
   override string getValue() { result = this.getStringValue() }
 }
 
 /** A `__dirname` path expression. */
-private class DirNamePath extends PathExpr, VarAccess {
+deprecated private class DirNamePath extends PathExpr, VarAccess {
   DirNamePath() {
     this.getName() = "__dirname" and
     this.getVariable().getScope() instanceof ModuleScope
@@ -433,7 +433,7 @@ private class DirNamePath extends PathExpr, VarAccess {
 }
 
 /** A `__filename` path expression. */
-private class FileNamePath extends PathExpr, VarAccess {
+deprecated private class FileNamePath extends PathExpr, VarAccess {
   FileNamePath() {
     this.getName() = "__filename" and
     this.getVariable().getScope() instanceof ModuleScope
@@ -446,7 +446,7 @@ private class FileNamePath extends PathExpr, VarAccess {
  * A path expression of the form `path.join(p, "...")` where
  * `p` is also a path expression.
  */
-private class JoinedPath extends PathExpr, @call_expr {
+deprecated private class JoinedPath extends PathExpr, @call_expr {
   JoinedPath() {
     exists(MethodCallExpr call | call = this |
       call.getReceiver().(VarAccess).getName() = "path" and

javascript/ql/lib/semmle/javascript/NodeModuleResolutionImpl.qll

@@ -45,8 +45,8 @@ int numberOfExtensions() { result = count(getFileExtensionPriority(_)) }
  * Gets the resolution target with the given `priority` of `req`
  * when resolved from the root with priority `rootPriority`.
  */
-File loadAsFile(Require req, int rootPriority, int priority) {
-  exists(PathExpr path | path = req.getImportedPathExpr() |
+deprecated File loadAsFile(Require req, int rootPriority, int priority) {
+  exists(PathExpr path | path = req.getImportedPath() |
     result = path.resolve(rootPriority) and priority = 0
     or
     exists(Folder encl | encl = path.resolveUpTo(path.getNumComponent() - 1, rootPriority) |
@@ -60,8 +60,8 @@ File loadAsFile(Require req, int rootPriority, int priority) {
  * with the given `priority` of `req` when resolved from the root with
  * priority `rootPriority`.
  */
-File loadAsDirectory(Require req, int rootPriority, int priority) {
-  exists(Folder dir | dir = req.getImportedPathExpr().(PathExpr).resolve(rootPriority) |
+deprecated File loadAsDirectory(Require req, int rootPriority, int priority) {
+  exists(Folder dir | dir = req.getImportedPath().resolve(rootPriority) |
     result = resolveMainModule(dir.(NpmPackage).getPackageJson(), priority, ".") or
     result = tryExtensions(dir, "index", priority - (numberOfExtensions() + 1))
   )
@@ -99,7 +99,7 @@ private string getStem(string name) {
  * Gets a file that a main module from `pkg` exported as `mainPath` with the given `priority`.
  * `mainPath` is "." if it's the main module of the package.
  */
-private File resolveMainPath(PackageJson pkg, string mainPath, int priority) {
+deprecated private File resolveMainPath(PackageJson pkg, string mainPath, int priority) {
   exists(PathExpr main | main = MainModulePath::of(pkg, mainPath) |
     result = main.resolve() and priority = 0
     or
@@ -132,7 +132,7 @@ private File resolveMainPath(PackageJson pkg, string mainPath, int priority) {
 /**
  * Gets the main module described by `pkg` with the given `priority`.
  */
-File resolveMainModule(PackageJson pkg, int priority, string exportPath) {
+deprecated File resolveMainModule(PackageJson pkg, int priority, string exportPath) {
   result = resolveMainPath(pkg, exportPath, priority)
   or
   exportPath = "." and
@@ -178,7 +178,7 @@ private string getASrcFolderName() { result = ["ts", "js", "src", "lib"] }
  * A JSON string in a `package.json` file specifying the path of one of the exported
  * modules of the package.
  */
-class MainModulePath extends PathExpr, @json_string {
+deprecated class MainModulePath extends PathExpr, @json_string {
   PackageJson pkg;
 
   MainModulePath() {
@@ -228,7 +228,7 @@ private string getExportRelativePath(JsonValue part) {
   result.matches(".%")
 }
 
-module MainModulePath {
+deprecated module MainModulePath {
   /** Gets the path to the main entry point of `pkg`. */
   MainModulePath of(PackageJson pkg) { result = of(pkg, ".") }
 
@@ -244,7 +244,7 @@ module MainModulePath {
  * These files are often imported directly from a client when a "main" module is not specified.
  * For performance reasons this only exists if there is no "main" field in the `package.json` file.
  */
-private class FilesPath extends PathExpr, @json_string {
+deprecated private class FilesPath extends PathExpr, @json_string {
   PackageJson pkg;
 
   FilesPath() {
@@ -263,15 +263,15 @@ private class FilesPath extends PathExpr, @json_string {
   }
 }
 
-private module FilesPath {
+deprecated private module FilesPath {
   FilesPath of(PackageJson pkg) { result.getPackageJson() = pkg }
 }
 
 /**
  * A JSON string in a `package.json` file specifying the path of the
  * TypeScript typings entry point.
  */
-class TypingsModulePathString extends PathString {
+deprecated class TypingsModulePathString extends PathString {
   PackageJson pkg;
 
   TypingsModulePathString() {
@@ -288,7 +288,7 @@ class TypingsModulePathString extends PathString {
 }
 
 /** Companion module to the `TypingsModulePathString` class. */
-module TypingsModulePathString {
+deprecated module TypingsModulePathString {
   /** Get the typings path for the given `package.json` file. */
   TypingsModulePathString of(PackageJson pkg) { result.getPackageJson() = pkg }
 }

javascript/ql/lib/semmle/javascript/PackageExports.qll

@@ -6,6 +6,7 @@
 
 import javascript
 private import semmle.javascript.internal.CachedStages
+private import semmle.javascript.internal.paths.PackageJsonEx
 
 /**
  * Gets a parameter that is a library input to a top-level package.
@@ -126,19 +127,12 @@ private DataFlow::Node getAValueExportedByPackage() {
   //   ....
   // }));
   // ```
-  // Such files are not recognized as modules, so we manually use `NodeModule::resolveMainModule` to resolve the file against a `package.json` file.
+  // Such files are not recognized as modules, so we manually use `PackageJsonEx` to resolve the file against a `package.json` file.
   exists(ImmediatelyInvokedFunctionExpr func, DataFlow::ParameterNode factory, int i |
     factory.getName() = "factory" and
     func.getParameter(i) = factory.getParameter() and
     DataFlow::globalVarRef("define").getACall().getAnArgument() = factory.getALocalUse() and
-    func.getFile() =
-      min(int j, File f |
-        f =
-          NodeModule::resolveMainModule(any(PackageJson pack | exists(pack.getPackageName())), j,
-            ".")
-      |
-        f order by j
-      )
+    func.getFile() = any(PackageJsonEx pack).getMainFileOrBestGuess()
   |
     result = func.getInvocation().getArgument(i).flow().getAFunctionValue().getAReturn()
     or