From a51bc22137d044c502b1ec86f68fa49e7bf73176 Mon Sep 17 00:00:00 2001
From: Domenic Denicola <d@domenic.me>
Date: Thu, 11 Jul 2019 13:49:19 -0400
Subject: [PATCH] Add spec for "update an import map"

---
 spec.bs | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
 spec.md | 32 -----------------------------
 2 files changed, 60 insertions(+), 36 deletions(-)

diff --git a/spec.bs b/spec.bs
index 6494022..2309d2a 100644
--- a/spec.bs
+++ b/spec.bs
@@ -63,11 +63,67 @@ A <dfn>import map</dfn> is a [=struct=] with two [=struct/items=]:
 An <dfn>empty import map</dfn> is an [=/import map=] with its [=import map/imports=] and [=import map/scopes=] both being empty maps.
 
 <div algorithm>
-  To <dfn>update an import map</dfn> |import map| with a second [=/import map=] |new import map|:
+  To <dfn>update an import map</dfn> |importMap| with a second [=/import map=] |newImportMap|:
 
-  1. Assert: |import map| is not null.
-  1. Assert: |new import map| is not null.
-  1. <p class="note">TODO: Implement merging. This merges |new import map| into |import map| and thus updates |import map| in-place.</p>
+  1. For each |specifier| → |addresses| of |newImportMap|'s [=import map/imports=], [=map/set=] |importMap|'s [=import map/imports=][|specifier|] to |addresses|.
+  1. For each |url| → |specifierMap| of |newImportMap|'s [=import map/scopes=], [=map/set=] |importMap|'s [=import map/scopes=][|url|] to |specifierMap|.
+  1. Set |importMap|'s [=import map/imports=] to the result of [=map/sorting=] |importMap|'s [=import map/imports=], with an entry |a| being less than an entry |b| if |a|'s [=map/key=] is [=longer or code unit less than=] |b|'s [=map/key=].
+  1. Set |importMap|'s [=import map/scopes=] to the result of [=map/sorting=] |importMap|'s [=import map/scopes=], with an entry |a| being less than an entry |b| if |a|'s [=map/key=] is [=longer or code unit less than=] |b|'s [=map/key=].
+</div>
+
+<div class="example" id="example-merging">
+  [=Update an import map=] merges the two import maps in a very simple way, not performing any deep merging beyond the top level of the "`imports`" and "`scopes`" keys. For example,
+
+  <xmp highlight="html">
+    <script type="importmap">
+    {
+      "imports": {
+        "a": "/a-1.mjs",
+        "b": "/b-1.mjs",
+        "std:kv-storage": ["std:kv-storage", "/kvs-1.mjs"]
+      },
+      "scopes": {
+        "/scope1/": {
+          "a": "/a-2.mjs"
+        }
+      }
+    }
+    </script>
+    <script type="importmap">
+    {
+      "imports": {
+        "b": null,
+        "std:kv-storage": "kvs-2.mjs"
+      },
+      "scopes": {
+        "/scope1/": {
+          "b": "/b-2.mjs"
+        }
+      }
+    }
+    </script>
+  </xmp>
+
+  is equivalent to
+
+  <xmp highlight="html">
+    <script type="importmap">
+    {
+      "imports": {
+        "a": "/a-1.mjs",
+        "b": null,
+        "std:kv-storage": "kvs-2.mjs"
+      },
+      "scopes": {
+        "/scope1/": {
+          "b": "/b-2.mjs"
+        }
+      }
+    }
+    </script>
+  </xmp>
+
+  Notice how the definition for "`/scope1/`" was completely overridden, so there is no longer a redirection for the "`a`" module specifier within that scope.
 </div>
 
 <h2 id="acquiring">Acquiring import maps</h2>
diff --git a/spec.md b/spec.md
index 93f994f..cdda55c 100644
--- a/spec.md
+++ b/spec.md
@@ -2,38 +2,6 @@
 
 The spec for import maps is located at https://wicg.github.io/import-maps/. This document contains notes on things that will eventually be formalized and make their way into the spec.
 
-## Merging import maps
-
-We're looking to do the minimal thing that could work here. As such, I propose the following:
-
-Given two import maps _A_ and _B_, the merged import map is a new import map whose imports are the result of merging _A_'s imports and _B_'s imports, and whose scopes are the result of merging _A_'s scopes and _B_'s scopes. Here, merging two maps means appending their entries to each other, with any conflicting keys from the first map removed.
-
-Example:
-
-```json
-{
-  "imports": { "a": "1", "b": "2" }
-}
-```
-
-+
-
-```json
-{
-  "imports": { "a": "3" }
-}
-```
-
-=
-
-```json
-{
-  "imports": { "b": "2", "a": "3" }
-}
-```
-
-Note that we do not introspect the scopes. If there's two conflicting definitions of how things behave inside a scope, then the last one wins.
-
 ## `import:` URL fetches
 
 _Unlike in previous import map proposals, `import:` URLs no longer involve changes to the URL parser._