diff --git a/ghost/package-json/lib/package-json.js b/ghost/package-json/lib/package-json.js new file mode 100644 index 0000000000..213a2a1521 --- /dev/null +++ b/ghost/package-json/lib/package-json.js @@ -0,0 +1,200 @@ +const _ = require('lodash'); +const Promise = require('bluebird'); +const fs = require('fs-extra'); +const join = require('path').join; +const errors = require('@tryghost/errors'); + +const notAPackageRegex = /^\.|_messages|README.md|node_modules|bower_components/i; +const packageJSONPath = 'package.json'; + +/** + * @typedef {Object} Ii18n + * @prop {(key: string) => string} t + */ + +/** + * # Package Utils + * + * Ghost has / is in the process of gaining support for several different types of sub-packages: + * - Themes: have always been packages, but we're going to lean more heavily on npm & package.json in future + * - Adapters: replace fundamental pieces like storage, will become npm modules + * + * These utils facilitate loading, reading, managing etc, packages from the file system. + * + */ +module.exports = class PackageJson { + /** + * Creates an instance of PackageJson, an util used to read and validate package.json files + * @param {Object} dependencies + * @param {Ii18n} dependencies.i18n + */ + constructor({i18n}) { + this.i18n = i18n; + } + + /** + * ### Filter Packages + * Normalizes packages read by read-packages so that the themes module can use them. + * Iterates over each package and return an array of objects which are simplified representations of the package + * with 3 properties: + * - `name` - the package name + * - `package` - contents of the package.json or false if there isn't one + * - `active` - set to true if this package is active + * This data structure is used for listings of packages provided over the API and as such + * deliberately combines multiple sources of information in order to be efficient. + * + * TODO: simplify the package.json representation to contain only fields we use + * + * @param {object} packages as returned by read-packages + * @param {array/string} active as read from the settings object + * @returns {Array} of objects with useful info about themes + */ + filter(packages, active) { + // turn active into an array if it isn't one, so this function can deal with lists and one-offs + if (!Array.isArray(active)) { + active = [active]; + } + + return _.reduce(packages, function (result, pkg, key) { + let item = {}; + if (!key.match(notAPackageRegex)) { + item = { + name: key, + package: pkg['package.json'] || false, + active: _.indexOf(active, key) !== -1 + }; + + result.push(item); + } + + return result; + }, []); + } + + /** + * Parse package.json and validate it has + * all the required fields + * + * @param {string} path + */ + async parse(path) { + let source; + let json; + + try { + source = await fs.readFile(path); + } catch (readError) { + const err = new errors.IncorrectUsageError(); + err.message = this.i18n.t('errors.utils.parsepackagejson.couldNotReadPackage'); + err.context = path; + err.err = readError; + + return Promise.reject(err); + } + + try { + json = JSON.parse(source); + } catch (parseError) { + const err = new errors.IncorrectUsageError(); + err.message = this.i18n.t('errors.utils.parsepackagejson.themeFileIsMalformed'); + err.context = path; + err.err = parseError; + err.help = this.i18n.t('errors.utils.parsepackagejson.willBeRequired', {url: 'https://ghost.org/docs/themes/'}); + + return Promise.reject(err); + } + + const hasRequiredKeys = json.name && json.version; + + if (!hasRequiredKeys) { + const err = new errors.IncorrectUsageError(); + err.message = this.i18n.t('errors.utils.parsepackagejson.nameOrVersionMissing'); + err.context = path; + err.help = this.i18n.t('errors.utils.parsepackagejson.willBeRequired', {url: 'https://ghost.org/docs/themes/'}); + + return Promise.reject(err); + } + + return json; + } + + /** + * Recursively read directory and find the packages in it + * + * @param {string} absolutePath + * @param {string} packageName + * @returns {object} + */ + async processPackage(absolutePath, packageName) { + const pkg = { + name: packageName, + path: absolutePath + }; + + try { + const packageJSON = await this.parse(join(absolutePath, packageJSONPath)); + pkg['package.json'] = packageJSON; + } catch (err) { + // ignore invalid package.json for now, + // because Ghost does not rely/use them at the moment + // in the future, this .catch() will need to be removed, + // so that error is thrown on invalid json syntax + pkg['package.json'] = null; + } + + return pkg; + } + + /** + * @param {string} packagePath + * @param {string} packageName + */ + async readPackage(packagePath, packageName) { + const absolutePath = join(packagePath, packageName); + + try { + const stat = await fs.stat(absolutePath); + if (!stat.isDirectory()) { + return {}; + } + + const pkg = await this.processPackage(absolutePath, packageName); + const res = {}; + res[packageName] = pkg; + return res; + } catch (err) { + return Promise.reject(new errors.NotFoundError({ + message: 'Package not found', + err: err, + help: 'path: ' + packagePath, + context: 'name: ' + packageName + })); + } + } + + /** + * @param {string} packagePath + */ + readPackages(packagePath) { + const self = this; + + return Promise.resolve(fs.readdir(packagePath)) + .filter(function (packageName) { + // Filter out things which are not packages by regex + if (packageName.match(notAPackageRegex)) { + return; + } + // Check the remaining items to ensure they are a directory + return fs.stat(join(packagePath, packageName)).then(function (stat) { + return stat.isDirectory(); + }); + }) + .map(function readPackageJson(packageName) { + const absolutePath = join(packagePath, packageName); + return self.processPackage(absolutePath, packageName); + }) + .then(function (packages) { + return _.keyBy(packages, 'name'); + }); + } +}; diff --git a/ghost/package-json/test/filter_spec.js b/ghost/package-json/test/filter_spec.js new file mode 100644 index 0000000000..854f810708 --- /dev/null +++ b/ghost/package-json/test/filter_spec.js @@ -0,0 +1,133 @@ +const should = require('should'); +const PackageJSON = require('../../../../../core/server/lib/fs/package-json/package-json'); + +const packageJSON = new PackageJSON({ + i18n: { + t: key => key + } +}); + +describe('lib/fs/package-json', function () { + // @TODO: introduce some non-theme package examples + const casper = { + name: 'casper', + path: '~/content/themes/casper', + 'package.json': { + name: 'casper', + description: 'The default personal blogging theme for Ghost. Beautiful, minimal and responsive.', + demo: 'https://demo.ghost.io', + version: '1.3.5', + engines: {}, + license: 'MIT', + screenshots: {}, + author: {}, + gpm: {}, + keywords: {}, + repository: {}, + bugs: 'https://github.com/TryGhost/Casper/issues', + contributors: 'https://github.com/TryGhost/Casper/graphs/contributors' + } + }; + + const simplePackage = { + name: 'simple', + path: '~/content/themes/simple', + 'package.json': { + name: 'simple', + version: '0.1.0' + } + }; + + const missingPackageJson = { + name: 'missing', + path: '~/content/themes/missing', + 'package.json': null + }; + + it('should filter packages correctly', function () { + const result = packageJSON.filter({casper: casper}); + let package1; + + result.should.be.an.Array().with.lengthOf(1); + package1 = result[0]; + + package1.should.be.an.Object().with.properties('name', 'package', 'active'); + Object.keys(package1).should.be.an.Array().with.lengthOf(3); + package1.name.should.eql('casper'); + package1.package.should.be.an.Object().with.properties('name', 'version'); + package1.active.should.be.false(); + }); + + it('should filter packages and handle a single active package string', function () { + const result = packageJSON.filter({casper: casper, simple: simplePackage}, 'casper'); + let package1; + let package2; + + result.should.be.an.Array().with.lengthOf(2); + package1 = result[0]; + package2 = result[1]; + + package1.should.be.an.Object().with.properties('name', 'package', 'active'); + Object.keys(package1).should.be.an.Array().with.lengthOf(3); + package1.name.should.eql('casper'); + package1.package.should.be.an.Object().with.properties('name', 'version'); + package1.active.should.be.true(); + + package2.should.be.an.Object().with.properties('name', 'package', 'active'); + Object.keys(package2).should.be.an.Array().with.lengthOf(3); + package2.name.should.eql('simple'); + package2.package.should.be.an.Object().with.properties('name', 'version'); + package2.active.should.be.false(); + }); + + it('should filter packages and handle an array of active packages', function () { + const result = packageJSON.filter({casper: casper, simple: simplePackage}, ['casper', 'simple']); + let package1; + let package2; + + result.should.be.an.Array().with.lengthOf(2); + package1 = result[0]; + package2 = result[1]; + + package1.should.be.an.Object().with.properties('name', 'package', 'active'); + Object.keys(package1).should.be.an.Array().with.lengthOf(3); + package1.name.should.eql('casper'); + package1.package.should.be.an.Object().with.properties('name', 'version'); + package1.active.should.be.true(); + + package2.should.be.an.Object().with.properties('name', 'package', 'active'); + Object.keys(package2).should.be.an.Array().with.lengthOf(3); + package2.name.should.eql('simple'); + package2.package.should.be.an.Object().with.properties('name', 'version'); + package2.active.should.be.true(); + }); + + it('handles packages with no package.json even though this makes us sad', function () { + const result = packageJSON.filter({casper: casper, missing: missingPackageJson}, ['casper']); + let package1; + let package2; + + result.should.be.an.Array().with.lengthOf(2); + package1 = result[0]; + package2 = result[1]; + + package1.should.be.an.Object().with.properties('name', 'package', 'active'); + Object.keys(package1).should.be.an.Array().with.lengthOf(3); + package1.name.should.eql('casper'); + package1.package.should.be.an.Object().with.properties('name', 'version'); + package1.active.should.be.true(); + + package2.should.be.an.Object().with.properties('name', 'package', 'active'); + Object.keys(package2).should.be.an.Array().with.lengthOf(3); + package2.name.should.eql('missing'); + package2.package.should.be.false(); + package2.active.should.be.false(); + }); + + it('filters out things which are not packages', function () { + const result = packageJSON.filter({ + '.git': {}, '.anything': {}, 'README.md': {}, _messages: {} + }); + result.should.be.an.Array().with.lengthOf(0); + }); +}); diff --git a/ghost/package-json/test/parse_spec.js b/ghost/package-json/test/parse_spec.js new file mode 100644 index 0000000000..ffe3b206ac --- /dev/null +++ b/ghost/package-json/test/parse_spec.js @@ -0,0 +1,130 @@ +const should = require('should'); +const tmp = require('tmp'); +const fs = require('fs-extra'); +const PackageJSON = require('../../../../../core/server/lib/fs/package-json/package-json'); + +const packageJSON = new PackageJSON({ + i18n: { + t: key => key + } +}); + +describe('lib/fs/package-json: parse', function () { + it('should parse valid package.json', function (done) { + let pkgJson; + let tmpFile; + + tmpFile = tmp.fileSync(); + pkgJson = JSON.stringify({ + name: 'test', + version: '0.0.0' + }); + + fs.writeSync(tmpFile.fd, pkgJson); + + packageJSON.parse(tmpFile.name) + .then(function (pkg) { + pkg.should.eql({ + name: 'test', + version: '0.0.0' + }); + + done(); + }) + .catch(done) + .finally(tmpFile.removeCallback); + }); + + it('should fail when name is missing', function (done) { + let pkgJson; + let tmpFile; + + tmpFile = tmp.fileSync(); + pkgJson = JSON.stringify({ + version: '0.0.0' + }); + + fs.writeSync(tmpFile.fd, pkgJson); + + packageJSON.parse(tmpFile.name) + .then(function () { + done(new Error('packageJSON.parse succeeded, but should\'ve failed')); + }) + .catch(function (err) { + err.message.should.equal('errors.utils.parsepackagejson.nameOrVersionMissing'); + err.context.should.equal(tmpFile.name); + err.help.should.equal('errors.utils.parsepackagejson.willBeRequired'); + + done(); + }) + .catch(done) + .finally(tmpFile.removeCallback); + }); + + it('should fail when version is missing', function (done) { + let pkgJson; + let tmpFile; + + tmpFile = tmp.fileSync(); + pkgJson = JSON.stringify({ + name: 'test' + }); + + fs.writeSync(tmpFile.fd, pkgJson); + + packageJSON.parse(tmpFile.name) + .then(function () { + done(new Error('packageJSON.parse succeeded, but should\'ve failed')); + }) + .catch(function (err) { + err.message.should.equal('errors.utils.parsepackagejson.nameOrVersionMissing'); + err.context.should.equal(tmpFile.name); + err.help.should.equal('errors.utils.parsepackagejson.willBeRequired'); + + done(); + }) + .catch(done) + .finally(tmpFile.removeCallback); + }); + + it('should fail when JSON is invalid', function (done) { + let pkgJson; + let tmpFile; + + tmpFile = tmp.fileSync(); + pkgJson = '{name:"test"}'; + + fs.writeSync(tmpFile.fd, pkgJson); + + packageJSON.parse(tmpFile.name) + .then(function () { + done(new Error('packageJSON.parse succeeded, but should\'ve failed')); + }) + .catch(function (err) { + err.message.should.equal('errors.utils.parsepackagejson.themeFileIsMalformed'); + err.context.should.equal(tmpFile.name); + err.help.should.equal('errors.utils.parsepackagejson.willBeRequired'); + + done(); + }) + .catch(done) + .finally(tmpFile.removeCallback); + }); + + it('should fail when file is missing', function (done) { + const tmpFile = tmp.fileSync(); + + tmpFile.removeCallback(); + packageJSON.parse(tmpFile.name) + .then(function () { + done(new Error('packageJSON.parse succeeded, but should\'ve failed')); + }) + .catch(function (err) { + err.message.should.equal('errors.utils.parsepackagejson.couldNotReadPackage'); + err.context.should.equal(tmpFile.name); + + done(); + }) + .catch(done); + }); +}); diff --git a/ghost/package-json/test/read_spec.js b/ghost/package-json/test/read_spec.js new file mode 100644 index 0000000000..2f2a83ce06 --- /dev/null +++ b/ghost/package-json/test/read_spec.js @@ -0,0 +1,269 @@ +const should = require('should'); +const tmp = require('tmp'); +const join = require('path').join; +const fs = require('fs-extra'); +const PackageJSON = require('../../../../../core/server/lib/fs/package-json/package-json'); + +const packageJSON = new PackageJSON({ + i18n: { + t: key => key + } +}); + +describe('lib/fs/package-json: read', function () { + describe('all', function () { + it('should read directory and ignore unneeded items', function (done) { + const packagePath = tmp.dirSync({unsafeCleanup: true}); + + // create example theme + fs.mkdirSync(join(packagePath.name, 'casper')); + fs.writeFileSync(join(packagePath.name, 'casper', 'index.hbs'), ''); + + // create some trash + fs.mkdirSync(join(packagePath.name, 'node_modules')); + fs.mkdirSync(join(packagePath.name, 'bower_components')); + fs.mkdirSync(join(packagePath.name, '.git')); + fs.writeFileSync(join(packagePath.name, '.DS_Store'), ''); + + packageJSON.readPackages(packagePath.name) + .then(function (pkgs) { + pkgs.should.eql({ + casper: { + name: 'casper', + path: join(packagePath.name, 'casper'), + 'package.json': null + } + }); + + done(); + }) + .catch(done) + .finally(packagePath.removeCallback); + }); + + it('should read directory and parse package.json files', function (done) { + let packagePath; + let pkgJson; + + packagePath = tmp.dirSync({unsafeCleanup: true}); + pkgJson = JSON.stringify({ + name: 'test', + version: '0.0.0' + }); + + // create example theme + fs.mkdirSync(join(packagePath.name, 'testtheme')); + fs.writeFileSync(join(packagePath.name, 'testtheme', 'package.json'), pkgJson); + fs.writeFileSync(join(packagePath.name, 'testtheme', 'index.hbs'), ''); + + packageJSON.readPackages(packagePath.name) + .then(function (pkgs) { + pkgs.should.eql({ + testtheme: { + name: 'testtheme', + path: join(packagePath.name, 'testtheme'), + 'package.json': { + name: 'test', + version: '0.0.0' + } + } + }); + + done(); + }) + .catch(done) + .finally(packagePath.removeCallback); + }); + + it('should read directory and ignore invalid package.json files', function (done) { + let packagePath; + let pkgJson; + + packagePath = tmp.dirSync({unsafeCleanup: true}); + pkgJson = JSON.stringify({ + name: 'test' + }); + + // create example theme + fs.mkdirSync(join(packagePath.name, 'testtheme')); + fs.writeFileSync(join(packagePath.name, 'testtheme', 'package.json'), pkgJson); + fs.writeFileSync(join(packagePath.name, 'testtheme', 'index.hbs'), ''); + + packageJSON.readPackages(packagePath.name) + .then(function (pkgs) { + pkgs.should.eql({ + testtheme: { + name: 'testtheme', + path: join(packagePath.name, 'testtheme'), + 'package.json': null + } + }); + + done(); + }) + .catch(done) + .finally(packagePath.removeCallback); + }); + }); + + describe('one', function () { + it('should read directory and ignore unneeded items', function (done) { + const packagePath = tmp.dirSync({unsafeCleanup: true}); + + // create example theme + fs.mkdirSync(join(packagePath.name, 'casper')); + fs.writeFileSync(join(packagePath.name, 'casper', 'index.hbs'), ''); + + // create some trash + fs.mkdirSync(join(packagePath.name, 'node_modules')); + fs.mkdirSync(join(packagePath.name, 'bower_components')); + fs.mkdirSync(join(packagePath.name, '.git')); + fs.writeFileSync(join(packagePath.name, '.DS_Store'), ''); + + packageJSON.readPackage(packagePath.name, 'casper') + .then(function (pkgs) { + pkgs.should.eql({ + casper: { + name: 'casper', + path: join(packagePath.name, 'casper'), + 'package.json': null + } + }); + + done(); + }) + .catch(done) + .finally(packagePath.removeCallback); + }); + + it('should read directory and parse package.json files', function (done) { + let packagePath; + let pkgJson; + + packagePath = tmp.dirSync({unsafeCleanup: true}); + pkgJson = JSON.stringify({ + name: 'test', + version: '0.0.0' + }); + + // create example theme + fs.mkdirSync(join(packagePath.name, 'testtheme')); + fs.writeFileSync(join(packagePath.name, 'testtheme', 'package.json'), pkgJson); + fs.writeFileSync(join(packagePath.name, 'testtheme', 'index.hbs'), ''); + + packageJSON.readPackage(packagePath.name, 'testtheme') + .then(function (pkgs) { + pkgs.should.eql({ + testtheme: { + name: 'testtheme', + path: join(packagePath.name, 'testtheme'), + 'package.json': { + name: 'test', + version: '0.0.0' + } + } + }); + + done(); + }) + .catch(done) + .finally(packagePath.removeCallback); + }); + + it('should read directory and ignore invalid package.json files', function (done) { + let packagePath; + let pkgJson; + + packagePath = tmp.dirSync({unsafeCleanup: true}); + pkgJson = JSON.stringify({ + name: 'test' + }); + + // create example theme + fs.mkdirSync(join(packagePath.name, 'testtheme')); + fs.writeFileSync(join(packagePath.name, 'testtheme', 'package.json'), pkgJson); + fs.writeFileSync(join(packagePath.name, 'testtheme', 'index.hbs'), ''); + + packageJSON.readPackage(packagePath.name, 'testtheme') + .then(function (pkgs) { + pkgs.should.eql({ + testtheme: { + name: 'testtheme', + path: join(packagePath.name, 'testtheme'), + 'package.json': null + } + }); + + done(); + }) + .catch(done) + .finally(packagePath.removeCallback); + }); + + it('should read directory and include only single requested package', function (done) { + const packagePath = tmp.dirSync({unsafeCleanup: true}); + + // create trash + fs.writeFileSync(join(packagePath.name, 'casper.zip'), ''); + fs.writeFileSync(join(packagePath.name, '.DS_Store'), ''); + + // create actual theme + fs.mkdirSync(join(packagePath.name, 'casper')); + fs.mkdirSync(join(packagePath.name, 'casper', 'partials')); + fs.writeFileSync(join(packagePath.name, 'casper', 'index.hbs'), ''); + fs.writeFileSync(join(packagePath.name, 'casper', 'partials', 'navigation.hbs'), ''); + fs.mkdirSync(join(packagePath.name, 'not-casper')); + fs.writeFileSync(join(packagePath.name, 'not-casper', 'index.hbs'), ''); + + packageJSON.readPackage(packagePath.name, 'casper') + .then(function (pkgs) { + pkgs.should.eql({ + casper: { + name: 'casper', + path: join(packagePath.name, 'casper'), + 'package.json': null + } + }); + + done(); + }) + .catch(done) + .finally(packagePath.removeCallback); + }); + + it('should return an error if package cannot be found', function (done) { + const packagePath = tmp.dirSync({unsafeCleanup: true}); + + // create trash + fs.writeFileSync(join(packagePath.name, 'casper.zip'), ''); + fs.writeFileSync(join(packagePath.name, '.DS_Store'), ''); + + packageJSON.readPackage(packagePath.name, 'casper') + .then(function () { + done('Should have thrown an error'); + }) + .catch(function (err) { + err.message.should.eql('Package not found'); + done(); + }) + .finally(packagePath.removeCallback); + }); + + it('should return empty object if package is not a directory', function (done) { + const packagePath = tmp.dirSync({unsafeCleanup: true}); + + // create trash + fs.writeFileSync(join(packagePath.name, 'casper.zip'), ''); + fs.writeFileSync(join(packagePath.name, '.DS_Store'), ''); + + packageJSON.readPackage(packagePath.name, 'casper.zip') + .then(function (pkg) { + pkg.should.eql({}); + + done(); + }) + .catch(done) + .finally(packagePath.removeCallback); + }); + }); +});