axyseo 2.0.0-alpha.0.0.20 → 2.0.0-alpha.0.0.4

package/src/parsedPaper/assess/TreeAssessor.js

@@ -0,0 +1,184 @@
+import { __, sprintf } from "@wordpress/i18n";
+import AssessmentResult from "../../values/AssessmentResult";
+
+/**
+ * Analyzes a paper by doing a list of assessments on a tree representation of a text and its metadata.
+ * Aggregates the scores on each individual assessment into an overall score.
+ *
+ * This score can represent anything from the readability to the SEO of the given text and metadata.
+ *
+ * @memberOf module:parsedPaper/assess
+ */
+class TreeAssessor {
+	/**
+	 * Creates a new assessor.
+	 *
+	 * @param {Object}                                     options                 Assessor options.
+	 * @param {module:parsedPaper/research.TreeResearcher} options.researcher      Supplies the assessments with researches and their
+	 *                                                                             (cached) results.
+	 * @param {module:parsedPaper/assess.ScoreAggregator}  options.scoreAggregator Aggregates the scores on the individual assessments into one.
+	 * @param {module:parsedPaper/assess.Assessment[]}     [options.assessments]   The list of assessments to apply.
+	 */
+	constructor( options ) {
+		/**
+		 * Supplies the assessments with researches and their (cached) results.
+		 * @type {module:parsedPaper/research.TreeResearcher}
+		 */
+		this.researcher = options.researcher;
+		/**
+		 * Aggregates the scores on the individual assessments into one overall score.
+		 * @type {module:parsedPaper/assess.ScoreAggregator}
+		 */
+		this.scoreAggregator = options.scoreAggregator;
+		/**
+		 * The list of assessments to apply.
+		 * @type {module:parsedPaper/assess.Assessment[]}
+		 */
+		this._assessments = options.assessments || [];
+		// Make sure that all of the assessments have the researcher.
+		this._assessments.forEach( assessment => assessment.setResearcher( this.researcher ) );
+	}
+
+	/**
+	 * Returns the list of available assessments.
+	 *
+	 * @returns {module:parsedPaper/assess.Assessment[]} The list of all available assessments.
+	 */
+	getAssessments() {
+		return this._assessments;
+	}
+
+	/**
+	 * Assesses the given text by applying all the assessments to it
+	 * and aggregating the resulting scores.
+	 *
+	 * @param {Paper}                      paper The paper to assess. This contains metadata about the text.
+	 * @param {module:parsedPaper/structure.Node} node  The root node of the tree to check.
+	 *
+	 * @returns {Promise<{results: AssessmentResult[], score: number}>} The assessment results and the overall score.
+	 */
+	async assess( paper, node ) {
+		const applicableAssessments = await this.getApplicableAssessments( paper, node );
+		/*
+		  Apply every applicable assessment on the document.
+		  Wait before they are done before aggregating the results
+		  and returning the results and final score.
+		 */
+		const results = await Promise.all(
+			applicableAssessments.map( assessment => this.applyAssessment( assessment, paper, node ) )
+		);
+		// Filter out errored assessments.
+		const validResults = results.filter( result => result.getScore() !== -1 );
+		// Compute overall score.
+		const score = this.scoreAggregator.aggregate( validResults );
+
+		return { results, score };
+	}
+
+	/**
+	 * Applies the given assessment to the paper-node combination.
+	 *
+	 * @param {module:parsedPaper/assess.Assessment} assessment The assessment to apply.
+	 * @param {Paper}                         paper      The paper to apply the assessment to.
+	 * @param {module:parsedPaper/structure.Node}    node       The root node of the tree to apply the assessment to.
+	 *
+	 * @returns {Promise<AssessmentResult>} The result of the assessment.
+	 */
+	async applyAssessment( assessment, paper, node ) {
+		return assessment.apply( paper, node ).catch(
+			() => {
+				return new AssessmentResult( {
+					text: sprintf(
+						/* translators: %1$s expands to the name of the assessment. */
+						__( "An error occurred in the '%1$s' assessment", "wordpress-seo" ),
+						assessment.name
+					),
+					score: -1,
+				} );
+			}
+		);
+	}
+
+	/**
+	 * Adds the assessment to the list of assessments to apply.
+	 *
+	 * @param {string}                        name       The name to register the assessment under.
+	 * @param {module:parsedPaper/assess.Assessment} assessment The assessment to add.
+	 *
+	 * @returns {void}
+	 */
+	registerAssessment( name, assessment ) {
+		assessment.name = name;
+		assessment.setResearcher( this.researcher );
+		this._assessments.push( assessment );
+	}
+
+	/**
+	 * Removes the assessment registered under the given name, if it exists.
+	 *
+	 * @param {string} name The name of the assessment to remove.
+	 *
+	 * @returns {module:parsedPaper/assess.Assessment|null} The deleted assessment, or null if no assessment has been deleted.
+	 */
+	removeAssessment( name ) {
+		const index = this._assessments.findIndex( assessment => assessment.name === name );
+		if ( index > -1 ) {
+			const deleted = this._assessments.splice( index, 1 );
+			return deleted[ 0 ];
+		}
+		return null;
+	}
+
+	/**
+	 * Returns the assessment registered under the given name.
+	 * Returns `null` if no assessment is registered under the given name.
+	 *
+	 * @param {string} name The name of the assessment to get.
+	 *
+	 * @returns {Assessment|null} The assessment.
+	 */
+	getAssessment( name ) {
+		const assessmentToReturn = this._assessments.find( assessment => assessment.name === name );
+		return assessmentToReturn ? assessmentToReturn : null;
+	}
+
+	/**
+	 * Sets the assessments that this assessor needs to apply.
+	 *
+	 * @param {module:parsedPaper/assess.Assessment[]} assessments The assessments to set.
+	 *
+	 * @returns {void}
+	 */
+	setAssessments( assessments ) {
+		this._assessments = assessments;
+	}
+
+	/**
+	 * Returns the list of applicable assessments.
+	 *
+	 * @param {Paper}                      paper The paper to check.
+	 * @param {module:parsedPaper/structure.Node} node  The tree to check.
+	 *
+	 * @returns {Promise<Array>} The list of applicable assessments.
+	 */
+	async getApplicableAssessments( paper, node ) {
+		// List to store the applicable assessments in (empty for now).
+		const applicableAssessments = [];
+
+		// Asynchronously add each assessment to the list if they are applicable.
+		const promises = this._assessments.map( assessment =>
+			assessment.isApplicable( paper, node ).then(
+				applicable => {
+					if ( applicable ) {
+						applicableAssessments.push( assessment );
+					}
+				}
+			)
+		);
+
+		// Wait before all the applicable assessments have been added before returning them.
+		return Promise.all( promises ).then( () => applicableAssessments );
+	}
+}
+
+export default TreeAssessor;

package/src/parsedPaper/assess/assessmentListFactories.js

@@ -0,0 +1,73 @@
+/**
+ * Factory functions for creating lists of assessments.
+ *
+ * To be used in creating the different kinds of assessors.
+ */
+
+/**
+ * Creates a new list of SEO assessments.
+ *
+ * @returns {module:parsedPaper/assess.Assessment[]} The list of SEO assessments.
+ *
+ * @private
+ * @memberOf module:parsedPaper/assess
+ */
+const constructSEOAssessments = () => [
+	// Needs to be populated by fancy new assessments that work on the tree representation of the text.
+];
+
+/**
+ * Creates a new list of readability assessments.
+ *
+ * @returns {module:parsedPaper/assess.Assessment[]} The list of readability assessments.
+ *
+ * @private
+ * @memberOf module:parsedPaper/assess
+ */
+const constructReadabilityAssessments = () => [
+	// Needs to be populated by fancy new assessments that work on the tree representation of the text.
+];
+
+/**
+ * Creates a new list of SEO assessments for taxonomy pages.
+ *
+ * @returns {module:parsedPaper/assess.Assessment[]} The list of SEO assessments.
+ *
+ * @private
+ * @memberOf module:parsedPaper/assess
+ */
+const constructTaxonomyAssessments = () => [
+	// Needs to be populated by fancy new assessments that work on the tree representation of the text.
+];
+
+/**
+ * Creates a new list of SEO assessments for related keyphrases.
+ *
+ * @returns {module:parsedPaper/assess.Assessment[]} The list of SEO assessments.
+ *
+ * @private
+ * @memberOf module:parsedPaper/assess
+ */
+const constructRelatedKeyphraseAssessments = () => [
+	// Needs to be populated by fancy new assessments that work on the tree representation of the text.
+];
+
+/**
+ * Creates a new list of SEO assessments for related keyphrases on taxonomy pages.
+ *
+ * @returns {module:parsedPaper/assess.Assessment[]} The list of SEO assessments.
+ *
+ * @private
+ * @memberOf module:parsedPaper/assess
+ */
+const constructRelatedKeyphraseTaxonomyAssessments = () => [
+	// Needs to be populated by fancy new assessments that work on the tree representation of the text.
+];
+
+export {
+	constructSEOAssessments,
+	constructReadabilityAssessments,
+	constructTaxonomyAssessments,
+	constructRelatedKeyphraseAssessments,
+	constructRelatedKeyphraseTaxonomyAssessments,
+};

package/src/parsedPaper/assess/assessments/Assessment.js

@@ -0,0 +1,79 @@
+/**
+ * An assessment that can be applied to a formatted text and its meta data.
+ *
+ * @memberOf module:parsedPaper/assess
+ *
+ * @abstract
+ */
+class Assessment {
+	/**
+	 * Creates a new assessment.
+	 *
+	 * @param {string}                              name       The name to give this assessment.
+	 * @param {module:parsedPaper/research.TreeResearcher} researcher The researcher to do researches with.
+	 *
+	 * @abstract
+	 */
+	constructor( name, researcher ) {
+		/**
+		 * This assessment's name.
+		 * @type {string}
+		 */
+		this.name = name;
+		/**
+		 * The researcher to do researches with.
+		 * @type {module:parsedPaper/research.TreeResearcher}
+		 * @private
+		 */
+		this._researcher = researcher;
+	}
+
+	/**
+	 * Sets a new researcher on this assessment.
+	 *
+	 * @param {module:parsedPaper/research.TreeResearcher} researcher The researcher to do researches with.
+	 *
+	 * @returns {void}
+	 */
+	setResearcher( researcher ) {
+		this._researcher = researcher;
+	}
+
+	/**
+	 * Returns the researcher used by this assessment.
+	 *
+	 * @returns {module:parsedPaper/research.TreeResearcher} The researcher used by this assessment.
+	 */
+	getResearcher() {
+		return this._researcher;
+	}
+
+	/**
+	 * Checks whether this assessment is applicable to the given paper and tree combination.
+	 *
+	 * @param {ParsedPaper} parsedPaper The parsedPaper to check.
+	 *
+	 * @returns {Promise<boolean>} Whether this assessment is applicable to the given paper and tree combination (wrapped in a promise).
+	 *
+	 * @abstract
+	 */
+	async isApplicable( parsedPaper ) { // eslint-disable-line no-unused-vars
+		console.warn( "`isApplicable` should be implemented by a child class of `Assessment`." );
+	}
+
+	/**
+	 * Applies this assessment to the given combination of parsedPaper and tree.
+	 *
+	 * @param {ParsedPaper} parsedPaper The parsedPaper to check.
+	 *
+	 * @returns {Promise<AssessmentResult>} The result of this assessment (wrapped in a promise).
+	 *
+	 * @abstract
+	 */
+	async apply( parsedPaper ) { // eslint-disable-line no-unused-vars
+		console.warn( "`apply` should be implemented by a child class of `Assessment`." );
+	}
+}
+
+
+export default Assessment;

package/src/parsedPaper/assess/assessments/index.js

@@ -0,0 +1,6 @@
+/**
+ * Contains the logic to assess a tree.
+ *
+ * @module module:parsedPaper/assess
+ */
+export { default as Assessment } from "./Assessment";

package/src/parsedPaper/assess/assessorFactories.js

@@ -0,0 +1,104 @@
+/* Assessment list factories. */
+import {
+	constructReadabilityAssessments,
+	constructRelatedKeyphraseAssessments,
+	constructRelatedKeyphraseTaxonomyAssessments,
+	constructSEOAssessments,
+	constructTaxonomyAssessments,
+} from "./assessmentListFactories";
+
+import {
+	constructSEOAssessments as constructCornerstoneSEOAssessments,
+	constructRelatedKeyphraseAssessments as constructCornerstoneRelatedKeyphraseAssessments,
+	constructReadabilityAssessments as constructCornerstoneReadabilityAssessments,
+} from "./cornerstone/assessmentListFactories";
+
+/* Score aggregators */
+import { ReadabilityScoreAggregator, SEOScoreAggregator } from "../../scoring/scoreAggregators";
+
+/* Base TreeAssessor class */
+import TreeAssessor from "./TreeAssessor";
+
+/**
+ * Maps combinations of assessor parameters (if the assessor is for related keyphrases, cornerstone content and/or taxonomy pages)
+ * to functions that generate a list of applicable assessments.
+ *
+ * @const
+ * @private
+ * @type {Object}
+ */
+const SEO_ASSESSMENTS_MAP = {
+	Default: constructSEOAssessments,
+
+	RelatedKeyphrase: constructRelatedKeyphraseAssessments,
+	Taxonomy: constructTaxonomyAssessments,
+	RelatedKeyphraseTaxonomy: constructRelatedKeyphraseTaxonomyAssessments,
+
+	Cornerstone: constructCornerstoneSEOAssessments,
+	CornerstoneRelatedKeyphrase: constructCornerstoneRelatedKeyphraseAssessments,
+};
+
+/**
+ * Constructs a new SEO assessor.
+ *
+ * @param {module:parsedPaper/research.TreeResearcher} researcher The researcher the assessments need to use to get information about the text.
+ *
+ * @param {Object}                              config                    The assessor configuration.
+ * @param {boolean}                             [config.relatedKeyphrase] If this assessor is for a related keyphrase, instead of the main one.
+ * @param {boolean}                             [config.taxonomy]         If this assessor is for a taxonomy page, instead of a regular page.
+ * @param {boolean}                             [config.cornerstone]      If this assessor is for cornerstone content.
+ *
+ * @returns {module:parsedPaper/assess.TreeAssessor} The created SEO assessor.
+ *
+ * @throws {Error} An error when no assessor exists for the given combination of configuration options.
+ *
+ * @memberOf module:parsedPaper/assess
+ */
+const constructSEOAssessor = function( researcher, config ) {
+	/*
+	 * Construct the key to retrieve the right assessment list factory.
+	 * E.g. "RelatedKeyphraseTaxonomy" for related keyphrase + taxonomy;
+	 */
+	const cornerstone = config.cornerstone ? "Cornerstone" : "";
+	const relatedKeyphrase = config.relatedKeyphrase ? "RelatedKeyphrase" : "";
+	const taxonomy = config.taxonomy ? "Taxonomy" : "";
+
+	// (Empty key defaults to "Default" key)
+	const key = [ cornerstone, relatedKeyphrase, taxonomy ].join( "" ) || "Default";
+
+	// Retrieve the assessment list factory.
+	const assessmentFactory = SEO_ASSESSMENTS_MAP[ key ];
+
+	// This specific combination of cornerstone, taxonomy and related keyphrase does not exist.
+	if ( ! assessmentFactory ) {
+		throw new Error( "Cannot make an assessor based on the provided combination of configuration options" );
+	}
+
+	// Construct assessor.
+	const assessments = assessmentFactory();
+	const scoreAggregator = new SEOScoreAggregator();
+	return new TreeAssessor( { researcher, assessments, scoreAggregator } );
+};
+
+/**
+ * Constructs a new readability assessor.
+ *
+ * @param {module:parsedPaper/research.TreeResearcher} researcher           The researcher the assessments need to use to
+ *                                                                          get information about the text.
+ * @param {boolean}                                    isCornerstoneContent If the to be analyzed content is considered cornerstone content
+ * (which uses stricter boundaries).
+ *
+ * @returns {module:parsedPaper/assess.TreeAssessor} The created readability assessor.
+ *
+ * @memberOf module:parsedPaper/assess
+ */
+const constructReadabilityAssessor = function( researcher, isCornerstoneContent = false ) {
+	const assessments = isCornerstoneContent ? constructReadabilityAssessments() : constructCornerstoneReadabilityAssessments();
+	const scoreAggregator = new ReadabilityScoreAggregator();
+	return new TreeAssessor( { researcher, assessments, scoreAggregator } );
+};
+
+export {
+	constructSEOAssessor,
+	constructReadabilityAssessor,
+};

package/src/parsedPaper/assess/cornerstone/assessmentListFactories.js

@@ -0,0 +1,47 @@
+/**
+ * Factory functions for creating lists of assessments for cornerstone content.
+ *
+ * To be used in creating the different kinds of assessors.
+ */
+
+/**
+ * Creates a new list of SEO assessments.
+ *
+ * @returns {module:parsedPaper/assess.Assessment[]} The list of SEO assessments.
+ *
+ * @private
+ * @memberOf module:parsedPaper/assess
+ */
+const constructSEOAssessments = () => [
+	// Needs to be populated by fancy new assessments that work on the tree representation of the text.
+];
+
+/**
+ * Creates a new list of readability assessments.
+ *
+ * @returns {module:parsedPaper/assess.Assessment[]} The list of readability assessments.
+ *
+ * @private
+ * @memberOf module:parsedPaper/assess
+ */
+const constructReadabilityAssessments = () => [
+	// Needs to be populated by fancy new assessments that work on the tree representation of the text.
+];
+
+/**
+ * Creates a new list of SEO assessments for related keyphrases.
+ *
+ * @returns {module:parsedPaper/assess.Assessment[]} The list of SEO assessments.
+ *
+ * @private
+ * @memberOf module:parsedPaper/assess
+ */
+const constructRelatedKeyphraseAssessments = () => [
+	// Needs to be populated by fancy new assessments that work on the tree representation of the text.
+];
+
+export {
+	constructSEOAssessments,
+	constructReadabilityAssessments,
+	constructRelatedKeyphraseAssessments,
+};

package/src/parsedPaper/assess/cornerstone/index.js

@@ -0,0 +1,5 @@
+import * as cornerstoneAssessmentListFactories from "./assessmentListFactories";
+
+export {
+	cornerstoneAssessmentListFactories,
+};

package/src/parsedPaper/assess/index.js

@@ -0,0 +1,20 @@
+import TreeAssessor from "./TreeAssessor";
+import * as ScoreAggregators from "../../scoring/scoreAggregators";
+import * as Assessments from "./assessments";
+import * as assessorFactories from "./assessorFactories";
+import { cornerstoneAssessmentListFactories } from "./cornerstone";
+
+/**
+ * Contains the logic to assess a tree representation of a text.
+ *
+ * @module tree/assess
+ *
+ * @see module:parsedPaper/structure
+ */
+export {
+	TreeAssessor,
+	ScoreAggregators,
+	Assessments,
+	assessorFactories,
+	cornerstoneAssessmentListFactories,
+};

package/src/parsedPaper/build/PaperParser.js

@@ -0,0 +1,105 @@
+import ParsedPaper from "../ParsedPaper";
+import { forEach } from "lodash";
+
+/**
+ * A class responsible for pre-processing the Paper, returning a ParsedPaper.
+ *
+ * @module parsedPaper
+ *
+ * @see module:parsedPaper/builder
+ * @see module:parsedPaper/structure
+ */
+class PaperParser {
+	/**
+	 * Constructs a PaperParser class.
+	 *
+	 * @param {Function} treeBuilder A function that receives text and returns a tree.
+	 *
+	 * @constructor
+	 */
+	constructor( treeBuilder ) {
+		this._parsedPaper = new ParsedPaper();
+		this._treeBuilder = treeBuilder;
+
+		this._metaDataModifiers = {};
+	}
+
+	/**
+	 * Processes a Paper resulting in a ParsedPaper.
+	 *
+	 * @param {Paper} paper The Paper to parse.
+	 *
+	 * @returns {ParsedPaper} A parsedPaper instance.
+	 */
+	parse( paper ) {
+		// Build tree and set it to the ParsedPaper.
+		this._parsedPaper.setTree(
+			this._treeBuilder( paper.getText() )
+		);
+
+		// Build metaData and set it to the ParsedPaper.
+		this._parsedPaper.setMetaData(
+			this.constructMetaData( paper )
+		);
+
+		return this._parsedPaper;
+	}
+
+	/**
+	 * Constructs the metaData from the Paper.
+	 *
+	 * @param {Paper} paper The paper to construct the metaData from.
+	 *
+	 * @returns {Object} The metaData.
+	 */
+	constructMetaData( paper ) {
+		let metaData = {};
+
+		// Map things to metaData.
+
+		// Run additional modifiers;
+		metaData = Object.assign( {}, this.runMetaDataModifiers( metaData, paper ) );
+
+		return metaData;
+	}
+
+	/**
+	 * Sets a metaData modifying function behind a function name on the internal metaDataModifiers object.
+	 *
+	 * @param {string}   modifierName       The name of the to be registered function.
+	 * @param {Function} modifierFunction   The function that modifies the metaData. Should accept a metaData object
+	 * 									    and optionally the paper.
+	 * @returns {void}
+	 */
+	registerMetaDataModifier( modifierName, modifierFunction ) {
+		/*
+		 * The metaDataModifier should accept the metaData and return the altered metaData.
+		 */
+		this._metaDataModifiers[ modifierName ] = modifierFunction;
+	}
+
+	/**
+	 * Runs all registered metaDataModifiers.
+	 * If one of the functions errors, it is skipped and its metaData changes are discarded.
+	 *
+	 * @param {Object} metaData The initial state of the metaData, that should be modified.
+	 * @param {Paper}  paper    The paper.
+	 *
+	 * @returns {Object} A modified metaData object.
+	 */
+	runMetaDataModifiers( metaData, paper ) {
+		let modifiedMetaData = metaData;
+		forEach( this._metaDataModifiers, ( modifierFunction, modifierName ) => {
+			try {
+				const previousMetaData = Object.assign( {}, modifiedMetaData );
+				modifiedMetaData = modifierFunction( previousMetaData, paper );
+			} catch ( modifierError ) {
+				console.warn( `An error with message "${ modifierError.message}" occurred in metaData modifier ` +
+				`function called ${ modifierName }. Skipping that function...` );
+			}
+		} );
+		return modifiedMetaData;
+	}
+}
+
+export default PaperParser;