docs

doc/api/policy.md

@@ -57,7 +57,7 @@ by defining an "onerror" field in a policy manifest. The following values are
 available to change the behavior:
 
 * `"exit"`: will exit the process immediately.
-    No cleanup code will be allowed to run.
+  No cleanup code will be allowed to run.
 * `"log"`: will log the error at the site of the failure.
 * `"throw"`: will throw a JS error at the site of the failure. This is the
   default.
@@ -152,8 +152,12 @@ policy located at `file:///C:/app/policy.json`:
 
 ```json
 {
-  "dependencies": {
-    "./utils.js": "./utils-v2.js"
+  "resources": {
+    "file:///C:/app/utils.js": {
+      "dependencies": {
+        "./utils.js": "./utils-v2.js"
+      }
+    }
   }
 }
 ```
@@ -164,8 +168,9 @@ absolute or relative specifier. However, if a specifier that is not an absolute
 or relative URL string is used, it would not be intercepted. So, if an import
 such as `import('#utils')` was used, it would not be intercepted.
 
-If the value of the redirection is `true` the default searching algorithms are
-used to find the module.
+If the value of the redirection is `true`, a "dependencies" field at the top of
+the policy file will be used. If that field at the top of the policy file is
+`true` the default node searching algorithms are used to find the module.
 
 If the value of the redirection is a string, it is resolved relative to
 the manifest and then immediately used without searching.
@@ -243,7 +248,7 @@ have `blob:` for their protocol scope since they do not adopt origins.
   "scopes": {
     "file:///C:/app/": {},
     "file:": {},
-    "": {},
+    "": {}
   }
 }
 ```
@@ -359,5 +364,64 @@ The following example, would allow access to `fs` for all `data:` resources:
 }
 ```
 
-[relative-URL string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
+#### Example: [import maps][] emulation
+
+Given an import map:
+
+```json
+{
+  "imports": {
+    "react": "./app/node_modules/react/index.js"
+  },
+  "scopes": {
+    "./ssr/": {
+      "react": "./app/node_modules/server-side-react/index.js"
+    }
+  }
+}
+```
+
+```json
+{
+  "dependencies": true,
+  "scopes": {
+    "": {
+      "cascade": true,
+      "dependencies": {
+        "react": "./app/node_modules/react/index.js"
+      }
+    },
+    "./ssr/": {
+      "cascade": true,
+      "dependencies": {
+        "react": "./app/node_modules/server-side-react/index.js"
+      }
+    }
+  }
+}
+```
+
+Import maps assume you can get any resource by default. This means
+`"dependencies"` at the top level of the policy should be set to `true`.
+Policies require this to be opt-in since it enables all resources of the
+application cross linkage which doesn't make sense for many scenarios. They also
+assume any given scope has access to any scope above its allowed dependencies;
+all scopes emulating import maps must set `"cascade": true`.
+
+Import maps only have a single top level scope for their "imports". So for
+emulating `"imports"` use the `""` scope. For emulating `"scopes"` use the
+`"scopes"` in a similar manner to how `"scopes"` works in import maps.
+
+Caveats: Policies do not use string matching for various finding of scope. They
+do URL traversals. This means things like `blob:` and `data:` URLs might not be
+entirely interoperable between the two systems. For example import maps can
+partially match a `data:` or `blob:` URL by partitioning the URL on a `/`
+character, policies intentionally cannot. For `blob:` URLs import map scopes do
+not adopt the origin of the `blob:` URL.
+
+Additionally, import maps only work on `import` so it may be desirable to add a
+`"import"` condition to all dependency mappings.
+
+[import maps]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
+[relative-url string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
 [special schemes]: https://url.spec.whatwg.org/#special-scheme