From 90a9a8e503d7bf86bf8a9166f5f1a50dc6cfd385 Mon Sep 17 00:00:00 2001
From: Lars Trieloff <trieloff@adobe.com>
Date: Tue, 3 Dec 2019 16:06:19 +0000
Subject: [PATCH] feat(markdown): show extensibility and abstraction in header

---
 cli.js                 |  5 ++-
 lib/formatInfo.js      | 22 ++++++++++
 lib/markdownBuilder.js | 97 ++++++++++++++++++++++++++++++++++++++----
 lib/writeMarkdown.js   | 12 +++---
 4 files changed, 120 insertions(+), 16 deletions(-)

diff --git a/cli.js b/cli.js
index 4411b00a..3e454d03 100755
--- a/cli.js
+++ b/cli.js
@@ -163,7 +163,8 @@ readdirp.promise(schemaPath, { root: schemaPath, fileFilter: `*.${schemaExtensio
 
     // generate Markdown ASTs
     build({
-      header: argv.h
+      header: argv.h,
+      links: docs,
     }),
 
     // build readme
@@ -178,7 +179,7 @@ readdirp.promise(schemaPath, { root: schemaPath, fileFilter: `*.${schemaExtensio
       info,
       error,
       debug,
-      meta: argv.m
+      meta: argv.m,
     }),
   ))
 
diff --git a/lib/formatInfo.js b/lib/formatInfo.js
index 456cb100..da4debe7 100644
--- a/lib/formatInfo.js
+++ b/lib/formatInfo.js
@@ -57,11 +57,33 @@ function formatInfo({ extension }) {
     }
   }
 
+  function isabstract(schema) {
+    return schema.definitions !== undefined &&
+      (!schema.properties || Object.keys(schema.properties).length === 0);
+  }
+
+  function isextensible(schema) {
+    return schema.definitions !== undefined || schema['meta:extensible'] === true;
+  }
+
+  function formatmeta(schema) {
+    return {
+      abstract: isabstract(schema.schema),
+      extensible: isextensible(schema.schema),
+      status: undefined,
+      identifiable: undefined,
+      custom: undefined,
+      additional: undefined,
+      definedin: undefined
+    };
+  }
+
   return schemas => map(schemas, (schema) => {
     const newobj = {
       ...schema,
       ...parsedescription(plaindescription(schema)),
       title: formatname(schema),
+      meta: formatmeta(schema)
     };
     return newobj;
   });
diff --git a/lib/markdownBuilder.js b/lib/markdownBuilder.js
index 3c9f8942..7d1170eb 100644
--- a/lib/markdownBuilder.js
+++ b/lib/markdownBuilder.js
@@ -9,19 +9,100 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-const { each, values } = require('ferrum');
 const {
-  root, paragraph, text, heading, code
+  each, values, map, list: flist,
+} = require('ferrum');
+const {
+  root, paragraph, text, heading, code, table, tableRow, tableCell, link,
 } = require('mdast-builder');
 
-function build({ header }) {
+function build({ header, links = {} }) {
+  const headerprops = [
+    {
+      name: 'abstract',
+      title: 'Abstract',
+      truelabel: 'Cannot be instantiated',
+      falselabel: 'Can be instantiated',
+      undefinedlabel: 'Unknown abstraction'
+    },
+    {
+      name: 'extensible',
+      title: 'Extensible',
+      undefinedlable: 'Unknown extensibility',
+      truelabel: 'Yes',
+      falselabel: 'No',
+    },
+    {
+      name: 'status',
+      title: 'Status',
+      undefinedlabel: 'Unknown status',
+      truelabel: 'Yes',
+      falselabel: 'No',
+    },
+    {
+      name: 'identifiable',
+      title: 'Identifiable',
+      truelabel: 'Yes',
+      falselabel: 'No',
+      undefinedlabel: 'Unknown identifiability'
+    },
+    {
+      name: 'custom',
+      title: 'Custom Properties',
+      truelabel: 'Allowed',
+      falselabel: 'Forbidden',
+      undefinedlabel: 'Unknown custom properties'
+    },
+    {
+      name: 'additional',
+      title: 'Additional Properties',
+      truelabel: 'Allowed',
+      falselabel: 'Forbidden',
+      undefinedlabel: 'Unknown additional properties'
+    },
+    {
+      name: 'defined',
+      title: 'Defined In',
+      undefinedlabel: 'Unknown definition'
+    },
+  ];
+
+
   function makeheader(schema) {
     if (header) {
       return [
-        heading(1, text(schema.title)),
-        paragraph(code('txt', schema.id + (schema.pointer ? '#' + schema.pointer : ''))),
-        schema.longdescription
-      ]
+        heading(1, text(`${schema.title} Schema`)),
+        paragraph(code('txt', schema.id + (schema.pointer ? `#${schema.pointer}` : ''))),
+        schema.longdescription,
+        table('left', [
+          // iterate over header
+          tableRow(
+            flist(
+              map(headerprops,
+                ({ name, title }) => {
+                  if (links[name]) {
+                    return tableCell(link(links[name], `What does ${title} mean?`, text(title)));
+                  }
+                  return tableCell(text(title));
+                }), Array,
+            ),
+          ),
+          tableRow(
+            flist(
+              map(headerprops,
+                (prop) => {
+                  // this is a linked property
+                  
+                  if (schema.meta && schema.meta[prop.name] && schema.meta[prop.name].link) {
+                    return tableCell(link(schema.meta[prop.name].link, '', text(schema.meta[prop.name].text)));
+                  }
+                  const value = schema.meta ? schema.meta[prop.name] : undefined;
+                  return tableCell(text(prop[String(value) + 'label'] || 'Unknown'));
+                }), Array,
+            ),
+          ),
+        ]),
+      ];
     }
     return [];
   }
@@ -30,7 +111,7 @@ function build({ header }) {
   // eslint-disable-next-line no-return-assign, no-param-reassign
     each(values(schemas), schema => schema.markdown = root([
     // todo add more elements
-      ...makeheader(schema)
+      ...makeheader(schema),
     ]));
     return schemas;
   };
diff --git a/lib/writeMarkdown.js b/lib/writeMarkdown.js
index b21adb5d..c43951fe 100644
--- a/lib/writeMarkdown.js
+++ b/lib/writeMarkdown.js
@@ -18,7 +18,7 @@ const fs = require('fs-extra');
 const yaml = require('js-yaml');
 
 function writeMarkdown({
-  out, debug, error, info, meta
+  out, debug, error, info, meta,
 }) {
   const dbg = (message) => {
     if (debug && typeof message === 'object') {
@@ -38,13 +38,13 @@ function writeMarkdown({
       dbg(schema.markdown);
       const fileName = path.resolve(out, `${name}.schema.md`);
 
-      const output = 
+      const output =
         // add YAML frontmatter
-        (!meta ? '' : '---\n') + 
-        (!meta ? '' : yaml.safeDump(meta)) + 
-        (!meta ? '' : '---\n\n') + 
+        (!meta ? '' : '---\n')
+        + (!meta ? '' : yaml.safeDump(meta))
+        + (!meta ? '' : '---\n\n')
 
-        processor.stringify(schema.markdown);
+        + processor.stringify(schema.markdown);
 
 
       fs.writeFile(fileName, output, (err) => {