From 43ae0e4a6f52c92867c7bf3ba5aefb8de296e841 Mon Sep 17 00:00:00 2001
From: Francois Daoust <fd@tidoust.net>
Date: Wed, 11 Dec 2024 20:09:59 +0100
Subject: [PATCH] Change name of "all" extract, allow CDDL defs for it

When a spec defines CDDL modules, the union of all CDDL is now written to a
file named `[shortname]-all.cddl` instead of simply `[shortname].cddl`. This
is meant to make it slightly clearer that the union of all CDDL file is not
necessarily the panacea. For example, it may not contain a useful first rule
against which a CBOR data item that would match any of the modules may be
validated.

In other words, when the crawler produces a `[shortname].cddl` file, that
means there's no module. If it doesn't, best is to check the module, with
"all" being a reserved module name in the spec that gets interpreted to mean
"any module".

When a spec defines CDDL modules, it may also define CDDL rules that only
appear in the "all" file by specifying `data-cddl-module="all"`. This is useful
to define a useful first type in the "all" extract.
---
 src/browserlib/extract-cddl.mjs | 32 +++++++++++++++++++++-----------
 tests/extract-cddl.js           | 29 ++++++++---------------------
 2 files changed, 29 insertions(+), 32 deletions(-)

diff --git a/src/browserlib/extract-cddl.mjs b/src/browserlib/extract-cddl.mjs
index 4f3d88b7..f1280356 100644
--- a/src/browserlib/extract-cddl.mjs
+++ b/src/browserlib/extract-cddl.mjs
@@ -10,8 +10,9 @@ import trimSpaces from './trim-spaces.mjs';
  * 
  * Each CDDL module is represented as an object with the following keys whose
  * values are strings:
- * - shortname: the CDDL module shortname. Shortname is "" if there are no
- * - label: A full name for the CDDL module.
+ * - shortname: the CDDL module shortname. Shortname is "" if the spec does not
+ * define any module, and "all" for the dump of all CDDL definitions.
+ * - label: A full name for the CDDL module, when defined.
  * - cddl: A dump of the CDDL definitions.
  *
  * If the spec defines more than one module, the first item in the array is the
@@ -36,15 +37,16 @@ export default function () {
     // Retrieve all elements that contains CDDL content
     const cddlEls = getCodeElements([cddlSelector], [indexSelector]);
 
-    // By convention, CDDL defined without specifying a module is defined
-    // for all modules (that CDDL would essentially be lost otherwise, there's
-    // no reason for a spec to define CDDL for no module if it uses modules).
-    // Start by assembled the list of modules
+    // Start by assembling the list of modules
     const modules = {};
     for (const el of cddlEls) {
         const elModules = getModules(el);
         for (const name of elModules) {
-            modules[name] = [];
+            // "all" does not create a module on its own, that's the name of
+            // the CDDL module that contains all CDDL definitions.
+            if (name !== 'all') {
+                modules[name] = [];
+            }
         }
     }
 
@@ -55,6 +57,7 @@ export default function () {
         if (!cddl) {
             continue;
         }
+        // All CDDL appears in the "all" module.
         mergedCddl.push(cddl);
         let elModules = getModules(el);
         if (elModules.length === 0) {
@@ -62,17 +65,24 @@ export default function () {
             elModules = Object.keys(modules);
         }
         for (const name of elModules) {
-            if (!modules[name]) {
-                modules[name] = [];
+            // CDDL defined for the "all" module is only defined for it
+            if (name !== 'all') {
+                if (!modules[name]) {
+                    modules[name] = [];
+                }
+                modules[name].push(cddl);
             }
-            modules[name].push(cddl);
         }
     }
 
     if (mergedCddl.length === 0) {
         return [];
     }
-    const res = [ { name: "", cddl: mergedCddl.join('\n\n') } ];
+
+    const res = [{
+        name: Object.keys(modules).length > 0 ? 'all' : '',
+        cddl: mergedCddl.join('\n\n')
+    }];
     for (const [name, cddl] of Object.entries(modules)) {
         res.push({ name, cddl: cddl.join('\n\n') });
     }
diff --git a/tests/extract-cddl.js b/tests/extract-cddl.js
index bf0f294c..82dd383a 100644
--- a/tests/extract-cddl.js
+++ b/tests/extract-cddl.js
@@ -56,7 +56,7 @@ typedef = tstr
     title: 'extracts CDDL module names from data-cddl-module',
     html: `<pre class="cddl" data-cddl-module="mod">cddl = tstr</pre>`,
     res: [
-      { name: '',    cddl: 'cddl = tstr' },
+      { name: 'all',    cddl: 'cddl = tstr' },
       { name: 'mod', cddl: 'cddl = tstr' }
     ]
   },
@@ -65,7 +65,7 @@ typedef = tstr
     title: 'extracts CDDL module name defined as class',
     html: `<pre class="cddl mod1-cddl cddl-mod2">cddl = tstr</pre>`,
     res: [
-      { name: '',     cddl: 'cddl = tstr' },
+      { name: 'all',  cddl: 'cddl = tstr' },
       { name: 'mod1', cddl: 'cddl = tstr' },
       { name: 'mod2', cddl: 'cddl = tstr' }
     ]
@@ -74,11 +74,8 @@ typedef = tstr
   {
     title: 'assembles CDDL in modules',
     html: `
-      <pre class="cddl">
-        cddl = * rule
-      </pre>
-      <pre class="cddl" data-cddl-module="mod1, mod2">
-        rule = (typedef / groupdef)
+      <pre class="cddl" data-cddl-module="all">
+        rule = (cddl1 / cddl2)
       </pre>
       <pre class="cddl" data-cddl-module="mod1">
         cddl1 = tstr
@@ -93,11 +90,9 @@ typedef = tstr
     `,
     res: [
       {
-        name: '',
+        name: 'all',
         cddl:
-`cddl = * rule
-
-rule = (typedef / groupdef)
+`rule = (cddl1 / cddl2)
 
 cddl1 = tstr
 
@@ -109,11 +104,7 @@ groupdef = tstr`
       {
         name: 'mod1',
         cddl:
-`cddl = * rule
-
-rule = (typedef / groupdef)
-
-cddl1 = tstr
+`cddl1 = tstr
 
 typedef = tstr
 groupdef = tstr`
@@ -121,11 +112,7 @@ groupdef = tstr`
       {
         name: 'mod2',
         cddl:
-`cddl = * rule
-
-rule = (typedef / groupdef)
-
-cddl2 = tstr
+`cddl2 = tstr
 
 typedef = tstr
 groupdef = tstr`