feat: can record files with external urls

Previously, only files whose urls could be expressed relatively to the url of the project (which was always a file url) could be represented in the appmap. Now we are able to include files of any url. The relative representation if it exists is still preferred. If the relative representation does not exists, the origin of the external url will be displayed as a top-level package.

I moved some pure functions in `components/classmap/default/loc.mjs` and `components/classmpa/default/specifier.mjs` to ease testing.

There is a small breaking change which does not warrant a major version bump imo: the relative paths in the appmaps are always start with `./` or `../`. This is to match node module specifier.

components/classmap/default/.ordering

@@ -1,4 +1,6 @@
+specifier.mjs
 position.mjs
+loc.mjs
 entity.mjs
 digest.mjs
 exclusion.mjs

components/classmap/default/digest.test.mjs

@@ -4,12 +4,14 @@ import { getEntitySummary } from "./entity.mjs";
 import { digestEstreeRoot } from "./digest.mjs";
 
 const digest = (content, anonymous = "dummy") => {
-  const source = createSource("protocol://host/path.mjs", content);
+  const source = createSource("protocol://host/base/script.js", content);
   return digestEstreeRoot(parseSource(source), {
     inline: false,
     shallow: false,
     source,
     anonymous,
+    base: "protocol://host/base/",
+    url: "protocol://host/base/script.js",
   }).map(getEntitySummary);
 };
 

components/classmap/default/entity.mjs

@@ -1,16 +1,15 @@
 import { assert } from "../../util/index.mjs";
-import { getUrlBasename, toAbsoluteUrl } from "../../url/index.mjs";
 import { InternalAppmapError } from "../../error/index.mjs";
 import {
   getSourceContent,
   getLeadingCommentArray,
   printComment,
   extractCommentLabelArray,
 } from "../../source/index.mjs";
+import { toSpecifier, toSpecifierBasename } from "./specifier.mjs";
+import { stringifyLoc, parseLoc } from "./loc.mjs";
 import { stringifyPosition } from "./position.mjs";
 
-const { String, parseInt } = globalThis;
-
 const isFunctionEntity = ({ type }) => type === "function";
 
 const printCommentArray = (comments) => {
@@ -31,9 +30,7 @@ export const wrapRootEntityArray = (entities, context) =>
     ? [
         {
           type: "class",
-          name: getUrlBasename(
-            toAbsoluteUrl(context.relative, "protocol://host"),
-          ),
+          name: toSpecifierBasename(context.url, context.base),
           children: entities,
         },
       ]
@@ -62,7 +59,10 @@ export const makeFunctionEntity = (
     ),
     children,
     name: maybe_name ?? context.anonymous,
-    location: `${context.relative}:${String(node.loc.start.line)}`,
+    location: stringifyLoc(
+      toSpecifier(context.url, context.base),
+      node.loc.start.line,
+    ),
     static: false,
     source: context.inline
       ? getSourceContent(context.source).substring(node.start, node.end)
@@ -152,12 +152,6 @@ export const registerEntity = (
       "function entity at root level",
       InternalAppmapError,
     );
-    const parts = /^(.*):([0-9]+)$/u.exec(entity.location);
-    assert(
-      parts !== null,
-      "could not parse function classmap entity location",
-      InternalAppmapError,
-    );
     const { excluded, recursively_excluded: child_recursively_excluded } =
       applyExclude(entity, maybe_parent_entity, recursively_excluded, exclude);
     assert(
@@ -175,8 +169,7 @@ export const registerEntity = (
             link: {
               defined_class: maybe_parent_entity.name,
               method_id: entity.name,
-              path: parts[1],
-              lineno: parseInt(parts[2]),
+              ...parseLoc(entity.location),
               static: entity.static,
             },
           },

components/classmap/default/entity.test.mjs

@@ -20,7 +20,8 @@ import {
 const { Map, Set } = globalThis;
 
 const default_context = {
-  relative: "script.js",
+  url: "protocol://host/script.js",
+  base: "protocol://host/",
   source: null,
   anonymous: "anonymous",
   inline: false,
@@ -41,7 +42,10 @@ const default_context = {
           source,
         }),
       ],
-      { ...default_context, relative: "dirname/basename.extension" },
+      {
+        ...default_context,
+        url: "protocol://host/dirname/basename.extension?search=123#hash",
+      },
     ).map(getEntitySummary),
     [
       {
@@ -163,7 +167,8 @@ assertEqual(
       makeFunctionEntity(parseSource(source).body[0], "reference", "f", [], {
         ...default_context,
         shallow: true,
-        relative: "relative",
+        url: "protocol://host/base/script.js",
+        base: "protocol://host/base/",
         source,
       }),
     ],
@@ -187,7 +192,7 @@ assertEqual(
       link: {
         defined_class: "c",
         method_id: "f",
-        path: "relative",
+        path: "./script.js",
         lineno: 1,
         static: false,
       },
@@ -298,14 +303,20 @@ assertDeepEqual(
         "reference",
         "f",
         [makeClassEntity("c", [], default_context)],
-        { ...default_context, inline: true, source },
+        {
+          ...default_context,
+          inline: true,
+          source,
+          url: "protocol://host/base/script.js",
+          base: "protocol://host/base/",
+        },
       ),
     ),
     [
       {
         type: "function",
         name: "f",
-        location: "script.js:1",
+        location: "./script.js:1",
         static: false,
         source: "function f () {}",
         comment: null,
@@ -326,6 +337,8 @@ assertDeepEqual(
     toClassmapEntity(
       makeFunctionEntity(parseSource(source).body[0], "reference", "f", [], {
         ...default_context,
+        url: "protocol://host/base/script.js",
+        base: "protocol://host/base/",
         inline: true,
         source,
       }),
@@ -334,7 +347,7 @@ assertDeepEqual(
       {
         type: "function",
         name: "f",
-        location: "script.js:1",
+        location: "./script.js:1",
         static: false,
         source: "function f () {}",
         comment: null,

components/classmap/default/exclusion.test.mjs

@@ -29,7 +29,8 @@ const and_exclusion = {
 };
 
 const default_context = {
-  relative: "script.js",
+  url: "protocol://host/base/script.js",
+  base: "protocol://host/base/",
   content: "",
   anonymous: "anonymous",
   inline: false,