{ "file": "lib/generate-fountainhead-data.js", "content": "
'use strict';\nconst { readFileSync, writeFileSync } = require('fs');\nconst { join, resolve } = require('path');\n\nconst generateClasses = require('./data-types/generate-classes');\nconst generateModules = require('./data-types/generate-modules');\nconst generateSrcFile = require('./data-types/generate-src-file');\nconst generateGuide = require('./data-types/generate-guide');\n\nconst logger = require('./logger');\nconst readDirRecursive = require('./utils/read-dir-recursive');\n\nfunction safeReadFile(filePath) {\n  try {\n    return readFileSync(resolve(filePath), { encoding: 'utf8' });\n  } catch (err) {\n    return console.warn(`Failed to read file: ${filePath}`, err);\n  }\n}\n\n/**\n * This module handles coordinating parsing/reading/saving all of the individual\n * Fountainhead data files after the configs have been validated and the raw\n * YUIDoc data has been generated.\n *\n * Module should:\n * - create and populate `docsMeta` that will be saved as `meta.json`\n * - generate decorated modules files\n * - generate decorated class files\n * - generate decorated src file files\n *\n * NOTE: When switching doc generation from an executable to a function call\n * all file operations had to be changed to a synchronous operation b/c the ember\n * command finishes before the async file operations are complete and the contents\n * are not written to file. This can be switched back to an async method by\n * assembling and returning a promise.all for all async file calls\n *\n * @class generateFountainheadData\n * @constructor\n * @uses DataTypes.GenerateModules\n * @uses DataTypes.GenerateClasses\n * @uses DataTypes.GenerateSrcFile\n * @param {Object} config     Project configuration file\n * @param {Object} yuidocJSON Raw yuidoc generated documentation JSON\n * @return {undefined}\n */\nmodule.exports = function generateFountainheadData(config, yuidocJSON) {\n  const output = config.output;\n\n  /**\n   * Call to handle saving data to a file. Requires a file path and data to save.\n   * If data is not a string, it will be stringified\n   * @method saveObjectToJSON\n   * @param {string}        filePath Path to save file at\n   * @param {Object|string} data     Data to save in file\n   * @return {boolean} True for successful operation, false for failures\n   */\n  function saveObjectToJSON(filePath, data) {\n    try {\n      data = JSON.stringify(data, null, 2);\n      writeFileSync(filePath, data, { encoding: 'utf8' });\n      return true;\n    } catch(ex) {\n      console.warn('Unable to save class JSON');\n      return false;\n    }\n\n    // NOTE: ASYNC REQUIRES PROMISIFYING ALL OPERATIONS\n    // fs.writeFile(filePath, data, err => {\n    //   if (err) { console.warn(`Unable to save ${filePath}`); }\n    // });\n  }\n\n  // Create meta object for docs that gets saved as `meta.json`\n  /**\n   * The `docsMeta` object is the guide for the documentation data. It contains\n   * descriptions of the project as well as arrays of module and class routing\n   * information\n   * @property docsMeta\n   * @type {Object}\n   */\n  let docsMeta = {\n    parser: 'YUIDoc', // We may support JSDoc someday\n    name: config.name,\n    description: config.description,\n    version: config.version,\n    repository: config.repository,\n    logo: config.logo,\n    guides: []\n  };\n  // hashRouting sets Fountainhead to use query params for auto scroll targets.\n  // We default to fragment ids and only override this if the consuming app is using\n  // hash location routing.\n  if (config.hashRouting) { docsMeta.hashRouting = true; }\n\n  // Save raw data, Ember command exits before YUIDoc module finishes file writing\n  saveObjectToJSON(\n    join(output.path, 'yuidoc-data.json'),\n    yuidocJSON\n  );\n\n\n  // ========================================================\n  // Parse Modules\n  // ========================================================\n  const modulesData = generateModules(yuidocJSON.modules);\n  // Update addon meta\n  docsMeta.modules = modulesData.modulesMeta;\n  // Save each module\n  modulesData.modulesDatas.forEach(moduleData => {\n    saveObjectToJSON(\n      join(output.path, 'modules', `${moduleData.name}.json`),\n      moduleData\n    );\n  });\n\n  // ========================================================\n  // Parse Classes and Class Items\n  // ========================================================\n  const classesData = generateClasses(yuidocJSON.classes, yuidocJSON.classitems);\n  // Update addon meta\n  docsMeta.classes = classesData.classesMeta;\n  // Save each class && save class' source file\n  classesData.classesDatas.forEach(classData => {\n    let fileContents;\n\n    saveObjectToJSON(\n      join(output.path, 'classes', `${classData.name}.json`),\n      classData\n    );\n\n    // If a class doesn't have a file somehow don't attempt to read the src\n    if (!classData.file) { return; }\n\n    try {\n      fileContents = readFileSync(resolve(classData.file), { encoding: 'utf8' });\n    } catch(ex) {\n      console.warn(`Failed to read file: ${classData.file}`, ex);\n    }\n\n    saveObjectToJSON(\n      join(output.path, 'files', `${classData.srcFileId}.json`),\n      { file: classData.file, content: generateSrcFile(fileContents) }\n    );\n\n    // NOTE: ASYNC REQUIRES PROMISIFYING ALL OPERATIONS\n    // Read file contents and apply syntax highlighting\n    // fs.readFile(resolve(classData.file), { encoding: 'utf8' }, (err, fileContents) => {\n    //   if (err) { return console.warn(`Unable to save file: ${classData.file}`); }\n    //\n    //   saveObjectToJSON(\n    //     join(output.path, 'files', `${classData.srcFileId}.json`),\n    //     { file: classData.file, content: generateSrcFile(fileContents) }\n    //   );\n    // });\n  });\n\n  // ========================================================\n  // Parse Guides\n  // ========================================================\n  // 1. Check for guides in /guides and include in set first\n  let guidesFiles = []; // Final guide set -> order added matches nav display order\n  try {\n    guidesFiles = guidesFiles.concat(readDirRecursive('guides'));\n  } catch (err) { err; }\n\n  // 2. For each configured guide in `fountainhead.js` check if guide is a `.md` file\n  // and add to base if it isn't already there, else ASSume it's a dir and call\n  // recursive read to add all guides in it to set\n  config.guides.forEach(guideConfig => {\n    if (guideConfig.match(/\\.md$/)) {\n      if (guidesFiles.indexOf(guideConfig) === -1) {\n        guidesFiles.push(guideConfig);\n      }\n    } else {\n      // Directory, concat all files\n      guidesFiles = guidesFiles.concat(readDirRecursive(guideConfig));\n    }\n  });\n\n  // 3. For each guide in set, handle reading/formatting/saving file/group\n  guidesFiles.forEach(guideConfig => {\n    // If `guideConfig` is an object literal it is data for a guide group. Add to\n    // meta and EXIT\n    if (typeof guideConfig === 'object') {\n      docsMeta.guides.push(Object.assign(guideConfig, {\n        linkText: guideConfig.linkText || guideConfig.id,\n        guideGroup: true,\n        type: 'guides',\n        guides: []\n      }));\n      return;\n    }\n\n    // Handles reading frontmatter, parsing guide body, assigning defaults\n    let guide = generateGuide({\n      filePath: guideConfig,\n      fileSrc: safeReadFile(guideConfig)\n    });\n\n    // For each formatted guide, handle private vs protected vs group vs guide\n    if (guide.attributes.private) {\n      // Private access guides should not be saved or included in meta\n      return;\n    } else if (guide.attributes.protected) {\n      // Protected guides should be saved in /docs, but not included in meta\n      saveObjectToJSON(\n        join(output.path, 'guides', `${guide.id}.json`),\n        guide\n      );\n      return;\n    } else if (guide.attributes.group) {\n      // If the formatted guide is group, it needs to be added to that group's\n      // nested guides array. Find group and add\n      let guideGroup = docsMeta.guides.filter(g => g.id === guide.attributes.group);\n\n      if (guideGroup.length) {\n        guideGroup[0].guides.push(guide);\n      } else {\n        // If a group doesn't exist yet create one on the fly\n        docsMeta.guides.push({\n          id: guide.attributes.group,\n          linkText: guide.attributes.group,\n          guideGroup: true,\n          type: 'guides',\n          guides: [guide]\n        });\n      }\n    } else {\n      docsMeta.guides.push(guide);\n    }\n\n    // All guides are saved to flat /output/guides/ directory for consistent API paths\n    saveObjectToJSON(\n      join(output.path, 'guides', `${guide.id}.json`),\n      guide\n    );\n  });\n\n  // ========================================================\n  // Save Fountainhead Master and Meta Data Files\n  // ========================================================\n\n  /*\n   * SHABANGLE!!! Documentation files have been generated and saved. Finish\n   * generating fountainhead data by saving master data file and documentation\n   * meta file\n   */\n  saveObjectToJSON(\n    join(output.path, output.filename),\n    yuidocJSON\n  );\n  saveObjectToJSON(\n    join(output.path, 'meta.json'),\n    docsMeta\n  );\n\n  // ========================================================\n  // Error Logging\n  // ========================================================\n\n  /*\n   * If quiet is falsey, pass the generated yuidoc warnings to our logger with\n   * the list of white listed tags. This lets us support logging warnings\n   * without warning about supported tags like `@passed`\n   */\n  if (!config.quiet) {\n    logger({\n      warnings: yuidocJSON.warnings,\n      whiteListTags: config.whiteListTags\n    });\n  }\n};\n
" }