feat(readme): generate readme again

cli.js

@@ -27,7 +27,7 @@ const generate = require('./lib/generateName');
 const filterRefs = require('./lib/filterRefs');
 const validate = require('./lib/validateSchemas');
 const build = require('./lib/markdownBuilder');
-const write = require('./lib/writeMarkdown');
+const { writereadme } = require('./lib/writeMarkdown');
 const readme = require('./lib/readmeBuilder');
 const formatInfo = require('./lib/formatInfo');
 const { loader } = require('./lib/schemaProxy');
@@ -149,25 +149,36 @@ readdirp.promise(schemaPath, { root: schemaPath, fileFilter: `*.${schemaExtensio
     traverse,
 
     // remove pure ref schemas
-    //filterRefs,
+    // filterRefs,
 
     (x) => {
+      console.log('emitting');
       const y = list(x);
-      console.log(JSON.stringify(y, undefined, ' '));
+      console.log(y);
       return y;
     },
 
+    // build readme
+    readme({
+      readme: !argv.n,
+    }),
+
+    writereadme({
+      readme: !argv.n,
+      out: argv.o,
+      info,
+      error,
+      debug,
+      meta: argv.m,
+    }),
+
     /* skip for now
     // generate Markdown ASTs
     build({
       header: argv.h,
       links: docs,
     }),
 
-    // build readme
-    readme({
-      readme: !argv.n,
-    }),
 
     // write to files
 

lib/formattingTools.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2019 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+const i18n = require('es2015-i18n-tag').default;
+const { list } = require('mdast-builder');
+const stringify = require('mdast-util-to-string');
+const inspect = require('unist-util-inspect');
+const remark = require('remark');
+const unified = require('unified');
+const strip = require('strip-markdown');
+const s = require('./symbols');
+
+function gentitle(titles, type) {
+  const [firsttitle] = titles;
+  const lasttitle = [...titles].pop();
+  if (titles.length === 1) {
+    return firsttitle;
+  }
+  if (lasttitle) {
+    return lasttitle;
+  }
+  return i18n`Untitled ${type} in ${firsttitle}`;
+}
+
+function gendescription(schema) {
+  if (schema && schema[s.meta]) {
+    return schema[s.meta].shortdescription;
+  }
+}
+
+module.exports = {
+  gentitle, gendescription,
+};

lib/readmeBuilder.js

@@ -10,12 +10,14 @@
  * governing permissions and limitations under the License.
  */
 const {
-  map, pairs, pipe, filter, list: flist,
+  map, pairs, pipe, filter, list: flist, mapSort,
 } = require('ferrum');
 const {
   root, paragraph, text, heading, list, listItem, link, inlineCode,
 } = require('mdast-builder');
 const inspect = require('unist-util-inspect');
+const s = require('./symbols');
+const { gentitle, gendescription, sortedlist } = require('./formattingTools');
 
 
 /**
@@ -25,44 +27,50 @@ const inspect = require('unist-util-inspect');
 function build({ readme = true }) {
   return (schemas) => {
     if (readme) {
+      console.log('building readme');
       const toplevel = flist(pipe(
-        pairs(schemas),
-        filter(([_, schema]) => schema.direct),
-        map(([name, schema]) => listItem(paragraph([
-          link(`./${name}.schema.md`, schema.shortdescription, [text(schema.title)]),
+        schemas,
+        filter(schema => !schema[s.parent]), // remove schemas with a parent
+        mapSort(schema => gentitle(schema[s.titles], schema.type)),
+        map(schema => listItem(paragraph([
+          link(`./${schema[s.slug]}.schema.md`, gendescription(schema), [text(gentitle(schema[s.titles], schema.type))]),
           text(' – '),
-          inlineCode(schema.schema.$id),
+          inlineCode(schema.$id),
         ]))),
       ), Array);
 
       const bytype = type => flist(pipe(
-        pairs(schemas),
-        filter(([_, schema]) => !schema.direct),
-        filter(([_, schema]) => schema.schema.type === type),
-        map(([name, schema]) => listItem(paragraph([
-          link(`./${name}.schema.md`, schema.shortdescription, [text(schema.title)]),
+        schemas,
+        filter(schema => schema.type === type), // remove schemas without matching type
+        filter(schema => !!schema[s.parent]), // keep only schemas with a parent
+        mapSort(schema => gentitle(schema[s.titles], schema.type)),
+        map(schema => listItem(paragraph([
+          link(`./${schema[s.slug]}.schema.md`, gendescription(schema), [text(gentitle(schema[s.titles], schema.type))]),
           text(' – '),
-          inlineCode(`${schema.id}#${schema.pointer}`),
+          inlineCode(`${schema[s.id]}#${schema[s.pointer]}`),
         ]))),
       ), Array);
 
-      const arrays = schemas.README = {
-        markdown: root([
-          heading(1, text('README')),
-          heading(2, text('Top-level Schemas')),
-          list('unordered', toplevel),
-          heading(2, text('Other Schemas')),
 
-          heading(3, text('Objects')),
-          list('unordered', bytype('object')),
+      const readmenode = root([
+        heading(1, text('README')),
+        heading(2, text('Top-level Schemas')),
+        list('unordered', toplevel),
 
-          heading(3, text('Arrays')),
-          list('unordered', bytype('array')),
-        ]),
-      };
-      return schemas;
+        heading(2, text('Other Schemas')),
+
+        heading(3, text('Objects')),
+        list('unordered', bytype('object')),
+
+        heading(3, text('Arrays')),
+        list('unordered', bytype('array')),
+      ]);
+
+      // console.log(inspect(readmenode));
+
+      return readmenode;
     }
-    return schemas;
+    return null;
   };
 }
 

lib/schemaProxy.js

@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 const ghslugger = require('github-slugger');
+const { basename } = require('path');
 const { formatmeta } = require('./formatInfo');
 const symbols = require('./symbols');
 
@@ -45,8 +46,8 @@ const handler = ({
   };
 
   meta[symbols.resolve] = (target, prop, receiver) => (path) => {
-    //console.log('trying to resolve', path, 'in', receiver[symbols.filename]);
-    if (path==undefined) {
+    // console.log('trying to resolve', path, 'in', receiver[symbols.filename]);
+    if (path == undefined) {
       return receiver;
     }
     const [head, ...tail] = typeof path === 'string' ? path.split('/') : path;
@@ -63,7 +64,7 @@ const handler = ({
 
   meta[symbols.slug] = (target, prop, receiver) => {
     if (!receiver[myslug] && !parent && receiver[symbols.filename]) {
-      receiver[myslug] = slugger.slug(receiver[symbols.filename].replace(/\..*$/, ''));
+      receiver[myslug] = slugger.slug(basename(receiver[symbols.filename]).replace(/\..*$/, ''));
     }
     if (!receiver[myslug]) {
       const parentslug = parent[symbols.slug];
@@ -88,7 +89,7 @@ const handler = ({
       if (typeof retval === 'object') {
         if (retval.$ref) {
           const [uri, pointer] = retval.$ref.split('#');
-          //console.log('resolving ref', uri, pointer, 'from', receiver[symbols.filename]);
+          // console.log('resolving ref', uri, pointer, 'from', receiver[symbols.filename]);
           const basedoc = uri || receiver[symbols.id];
           if (schemas.known[basedoc]) {
             const referenced = schemas.known[basedoc][symbols.resolve](pointer);

lib/writeMarkdown.js

@@ -17,7 +17,7 @@ const inspect = require('unist-util-inspect');
 const fs = require('fs-extra');
 const yaml = require('js-yaml');
 
-function writeMarkdown({
+function writemarkdown({
   out, debug, error, info, meta,
 }) {
   const dbg = (message) => {
@@ -60,4 +60,39 @@ function writeMarkdown({
   };
 }
 
-module.exports = writeMarkdown;
+function writereadme({
+  out, debug, error, info, meta, readme,
+}) {
+  const processor = unified()
+    .use(stringify);
+
+  if (readme) {
+    fs.mkdirpSync(out);
+
+    return (readmeast) => {
+      const fileName = path.resolve(out, 'README.md');
+
+      const output =
+        // add YAML frontmatter
+        (!meta ? '' : '---\n')
+        + (!meta ? '' : yaml.safeDump(meta))
+        + (!meta ? '' : '---\n\n')
+
+        + processor.stringify(readmeast);
+
+
+      fs.writeFile(fileName, output, (err) => {
+        if (err) {
+          error(err);
+        }
+        info(`${fileName} created`);
+      });
+
+      return fileName;
+    };
+  } else {
+    return args => args;
+  }
+}
+
+module.exports = { writemarkdown, writereadme };

test/schemaProxy.test.js

@@ -189,11 +189,13 @@ describe('Testing Schema Proxy', () => {
       'custom.schema.json',
     ];
 
-    const schemas = files.map(file => {
+    const schemas = files.map((file) => {
       const fname = path.resolve(__dirname, '..', 'examples', 'schemas', file);
       return myloader(require(fname), fname);
     });
 
+    assert.equal(schemas[0][slug], 'abstract');
+
     assert.deepEqual(schemas[2].title, 'Complex References');
     assert.equal(schemas[2].properties.refnamed.title, 'Simple');
     assert.equal(schemas[2].properties.refrefed.title, 'Simple');