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

package/src/scoring/assessors/assessor.js

@@ -0,0 +1,269 @@
+// External dependencies.
+import {filter, find, findIndex, isFunction, isUndefined, map} from 'lodash';
+
+// Internal dependencies.
+import AssessmentResult from '../../values/AssessmentResult.js';
+import {build} from '../../parse/build';
+import LanguageProcessor from '../../parse/language/LanguageProcessor.js';
+import MissingArgument from '../../errors/missingArgument.js';
+import {showTrace} from '../../helpers/errors.js';
+
+// The maximum score of individual assessment is 9. This is why we set the "score rating" here to 9.
+const ScoreRating = 9;
+
+/**
+ * The Assessor is a base class for all assessors.
+ */
+class Assessor {
+  /**
+   * Creates a new Assessor instance.
+   * @param {Researcher}	researcher	The researcher to use.
+   * @param {Object}		[options]	The assessor options.
+   */
+  constructor(researcher, options) {
+    this.type = 'assessor';
+    this.setResearcher(researcher);
+    this._assessments = [];
+
+    this._options = options || {};
+  }
+
+  /**
+   * Checks if the researcher is defined and sets it.
+   *
+   * @param   {Researcher} researcher The researcher to use in the assessor.
+   *
+   * @throws  {MissingArgument} Parameter needs to be a valid researcher object.
+   * @returns {void}
+   */
+  setResearcher(researcher) {
+    if (isUndefined(researcher)) {
+      throw new MissingArgument('The assessor requires a researcher.');
+    }
+    this._researcher = researcher;
+  }
+
+  /**
+   * Gets all available assessments.
+   * @returns {Assessment[]} assessment
+   */
+  getAvailableAssessments() {
+    return this._assessments;
+  }
+
+  /**
+   * Checks whether the Assessment is applicable.
+   *
+   * @param {Assessment} assessment The Assessment object that needs to be checked.
+   * @param {Paper} paper The Paper object to check against.
+   * @param {Researcher} [researcher] The Researcher object containing additional information.
+   * @returns {boolean} Whether or not the Assessment is applicable.
+   */
+  isApplicable(assessment, paper, researcher) {
+    if (
+      assessment.hasOwnProperty('isApplicable') ||
+      typeof assessment.isApplicable === 'function'
+    ) {
+      return assessment.isApplicable(paper, researcher);
+    }
+
+    return true;
+  }
+
+  /**
+   * Determines whether an assessment has a marker.
+   *
+   * @param {Assessment} assessment The assessment to check for.
+   * @returns {boolean} Whether or not the assessment has a marker.
+   */
+  hasMarker(assessment) {
+    return (
+      isFunction(this._options.marker) &&
+      (assessment.hasOwnProperty('getMarks') || typeof assessment.getMarks === 'function')
+    );
+  }
+
+  /**
+   * Returns the specific marker for this assessor.
+   *
+   * @returns {Function} The specific marker for this assessor.
+   */
+  getSpecificMarker() {
+    return this._options.marker;
+  }
+
+  /**
+   * Returns the paper that was most recently assessed.
+   *
+   * @returns {Paper} The paper that was most recently assessed.
+   */
+  getPaper() {
+    return this._lastPaper;
+  }
+
+  /**
+   * Runs the researches defined in the task list or the default researches.
+   *
+   * @param {Paper} paper The paper to run assessments on.
+   * @param i18n
+   * @returns {void}
+   */
+  assess(paper, i18n) {
+    this._researcher.setPaper(paper);
+
+    const languageProcessor = new LanguageProcessor(this._researcher);
+    const shortcodes = paper._attributes && paper._attributes.shortcodes;
+    paper.setTree(build(paper, languageProcessor, shortcodes));
+
+    let assessments = this.getAvailableAssessments();
+    this.results = [];
+
+    assessments = filter(
+      assessments,
+      function(assessment) {
+        return this.isApplicable(assessment, paper, this._researcher);
+      }.bind(this)
+    );
+
+    this.results = map(assessments, assessment =>
+      this.executeAssessment({
+        paper,
+        researcher: this._researcher,
+        assessment,
+        i18n
+      })
+    );
+    this._lastPaper = paper;
+  }
+
+  /**
+   * Executes an assessment and returns the AssessmentResult.
+   *
+   * @param {Paper} paper The paper to pass to the assessment.
+   * @param {Researcher} researcher The researcher to pass to the assessment.
+   * @param {Assessment} assessment The assessment to execute.
+   * @param i18n
+   * @returns {AssessmentResult} The result of the assessment.
+   */
+  executeAssessment({paper, researcher, assessment, i18n}) {
+    let result;
+
+    try {
+      result = assessment.getResult(paper, researcher, i18n);
+      result.setIdentifier(assessment.identifier);
+    } catch (assessmentError) {
+      showTrace(assessmentError);
+
+      result = new AssessmentResult();
+
+      result.setScore(-1);
+    }
+    return result;
+  }
+
+  /**
+   * Filters out all assessment results that have no score and no text.
+   *
+   * @returns {AssessmentResult[]} The array with all the valid assessments.
+   */
+  getValidResults() {
+    return filter(
+      this.results,
+      function(result) {
+        return this.isValidResult(result);
+      }.bind(this)
+    );
+  }
+
+  /**
+   * Returns if an assessmentResult is valid.
+   *
+   * @param {AssessmentResult} assessmentResult The assessmentResult to validate.
+   * @returns {boolean} whether or not the result is valid.
+   */
+  isValidResult(assessmentResult) {
+    return assessmentResult.hasScore() && assessmentResult.hasText();
+  }
+
+  /**
+   * Returns the overall score. Calculates the total score by adding all scores and dividing these
+   * by the number of results times the ScoreRating.
+   *
+   * @returns {number} The overall score.
+   */
+  calculateOverallScore() {
+    const results = this.getValidResults();
+
+    const totalScore = results.reduce(
+      (total, assessmentResult) => total + assessmentResult.getScore(),
+      0
+    );
+
+    return Math.round((totalScore / (results.length * ScoreRating)) * 100) || 0;
+  }
+
+  /**
+   * Registers an assessment and adds it to the internal assessments object.
+   *
+   * @param {string} name The name of the assessment.
+   * @param {Assessment} assessment The object containing function to run as an assessment and it's requirements.
+   * @returns {boolean} Whether registering the assessment was successful.
+   */
+  addAssessment(name, assessment) {
+    if (!assessment.hasOwnProperty('identifier')) {
+      assessment.identifier = name;
+    }
+    // If the assessor already has the same assessment, remove it and replace it with the new assessment with the same identifier.
+    if (this.getAssessment(assessment.identifier)) {
+      this.removeAssessment(assessment.identifier);
+    }
+
+    this._assessments.push(assessment);
+    return true;
+  }
+
+  /**
+   * Removes a specific Assessment from the list of Assessments.
+   *
+   * @param {string} name The Assessment to remove from the list of assessments.
+   * @returns {void}
+   */
+  removeAssessment(name) {
+    const toDelete = findIndex(this._assessments, function(assessment) {
+      return assessment.hasOwnProperty('identifier') && name === assessment.identifier;
+    });
+
+    if (-1 !== toDelete) {
+      this._assessments.splice(toDelete, 1);
+    }
+  }
+
+  /**
+   * Returns an assessment by identifier
+   *
+   * @param {string} identifier The identifier of the assessment.
+   * @returns {undefined|Assessment} The object if found, otherwise undefined.
+   */
+  getAssessment(identifier) {
+    return find(this._assessments, function(assessment) {
+      return assessment.hasOwnProperty('identifier') && identifier === assessment.identifier;
+    });
+  }
+
+  /**
+   * Checks which of the available assessments are applicable and returns an array with applicable assessments.
+   *
+   * @returns {Assessment[]} The array with applicable assessments.
+   */
+  getApplicableAssessments() {
+    const availableAssessments = this.getAvailableAssessments();
+    return filter(
+      availableAssessments,
+      function(availableAssessment) {
+        return this.isApplicable(availableAssessment, this.getPaper(), this._researcher);
+      }.bind(this)
+    );
+  }
+}
+
+export default Assessor;

package/src/scoring/assessors/avadaAssessor.js

@@ -0,0 +1,67 @@
+import {ContentAssessor, SEOAssessor} from '../../../src/scoring/assessors/index';
+import {
+  getMaxPoint,
+  groupAssessmentsByCategory,
+  groupAssessmentsByStatus
+} from '../helpers';
+
+/**
+ * The AvadaAssessor class is used for the general SEO analysis.
+ */
+export default class AvadaAssessor {
+  /**
+   * Creates a new AvadaAssessor instance.
+   * @param {Researcher}  researcher  The researcher to use.
+   * @param {Object}    [options]  The assessor options.
+   */
+  constructor(researcher, options) {
+    const seoAssessor = new SEOAssessor(researcher, options);
+    const contentAssessor = new ContentAssessor(researcher, options);
+    this.seoAssessor = seoAssessor;
+    this.contentAssessor = contentAssessor;
+    this.researcher = researcher;
+  }
+
+  assess(paper, i18n) {
+    this.seoAssessor.assess(paper, i18n);
+    this.contentAssessor.assess(paper, i18n);
+
+    let assessments = [...this.seoAssessor.results, ...this.contentAssessor.results];
+    assessments = assessments.map(assessment => ({
+      ...assessment.config,
+      body: assessment.body,
+      status: assessment.status,
+      score: assessment.score,
+      title: assessment.title || assessment.config.title
+    }));
+    this.assessments = assessments;
+  }
+
+  getResult(groupBy = 'category', getScore = true) {
+    let assessments = [];
+    switch (groupBy) {
+      case 'category':
+        assessments = groupAssessmentsByCategory(this.assessments);
+        break;
+      case 'status':
+        assessments = groupAssessmentsByStatus(this.assessments);
+        break;
+    }
+
+    return {
+      assessments,
+      ...(getScore ? {score: this.getScore()} : {})
+    };
+  }
+
+  getScore() {
+    let point = 0;
+
+    this.assessments.forEach(assessment => {
+      point += assessment.score;
+    });
+
+    const maxPoint = getMaxPoint(this.assessments);
+    return Math.round((point * 100) / maxPoint);
+  }
+}

package/src/scoring/assessors/contentAssessor.js

@@ -0,0 +1,159 @@
+import {map, sum} from 'lodash';
+import Assessor from './assessor.js';
+import ParagraphTooLong from '../assessments/readability/ParagraphTooLongAssessment.js';
+import SentenceLengthInText from '../assessments/readability/SentenceLengthInTextAssessment.js';
+import SentenceBeginnings from '../assessments/readability/SentenceBeginningsAssessment.js';
+import TransitionWords from '../assessments/readability/TransitionWordsAssessment.js';
+import scoreToRating from '../interpreters/scoreToRating.js';
+
+/**
+ * The ContentAssessor class is used for the readability analysis.
+ */
+export default class ContentAssessor extends Assessor {
+  /**
+   * Creates a new ContentAssessor instance.
+   * @param {Researcher}	researcher	The researcher to use.
+   * @param {Object}		[options]	The assessor options.
+   */
+  constructor(researcher, options) {
+    super(researcher, options);
+    this.type = 'contentAssessor';
+
+    this._assessments = [
+      new ParagraphTooLong(),
+      new SentenceLengthInText(),
+      new TransitionWords(),
+      new SentenceBeginnings()
+    ];
+  }
+
+  /**
+   * Calculates the weighted rating for languages that have all assessments based on a given rating.
+   *
+   * @param {string} rating The rating to be weighted.
+   * @returns {number} The weighted rating.
+   */
+  calculatePenaltyPointsFullSupport(rating) {
+    switch (rating) {
+      case 'bad':
+        return 3;
+      case 'ok':
+        return 2;
+      default:
+      case 'good':
+        return 0;
+    }
+  }
+
+  /**
+   * Calculates the weighted rating for languages that don't have all assessments based on a given rating.
+   *
+   * @param {string} rating The rating to be weighted.
+   * @returns {number} The weighted rating.
+   */
+  calculatePenaltyPointsPartialSupport(rating) {
+    switch (rating) {
+      case 'bad':
+        return 4;
+      case 'ok':
+        return 2;
+      default:
+      case 'good':
+        return 0;
+    }
+  }
+
+  /**
+   * Determines whether a language is fully supported. If a language supports 7 content assessments,
+   * it is fully supported
+   *
+   * @returns {boolean} True if fully supported.
+   */
+  _allAssessmentsSupported() {
+    const numberOfAssessments = this._assessments.length;
+    const applicableAssessments = this.getApplicableAssessments();
+    return applicableAssessments.length === numberOfAssessments;
+  }
+
+  /**
+   * Calculates the penalty points based on the assessment results.
+   *
+   * @returns {number} The total penalty points for the results.
+   */
+  calculatePenaltyPoints() {
+    const results = this.getValidResults();
+
+    const penaltyPoints = map(
+      results,
+      function(result) {
+        const rating = scoreToRating(result.getScore());
+
+        if (this._allAssessmentsSupported()) {
+          return this.calculatePenaltyPointsFullSupport(rating);
+        }
+
+        return this.calculatePenaltyPointsPartialSupport(rating);
+      }.bind(this)
+    );
+
+    return sum(penaltyPoints);
+  }
+
+  /**
+   * Rates the penalty points
+   *
+   * @param {number} totalPenaltyPoints The amount of penalty points.
+   * @returns {number} The score based on the amount of penalty points.
+   *
+   * @private
+   */
+  _ratePenaltyPoints(totalPenaltyPoints) {
+    if (this.getValidResults().length === 1) {
+      // If we have only 1 result, we only have a "no content" result
+      return 30;
+    }
+
+    if (this._allAssessmentsSupported()) {
+      // Determine the total score based on the total penalty points.
+      if (totalPenaltyPoints > 6) {
+        // A red indicator.
+        return 30;
+      }
+
+      if (totalPenaltyPoints > 4) {
+        // An orange indicator.
+        return 60;
+      }
+    } else {
+      if (totalPenaltyPoints > 4) {
+        // A red indicator.
+        return 30;
+      }
+
+      if (totalPenaltyPoints > 2) {
+        // An orange indicator.
+        return 60;
+      }
+    }
+    // A green indicator.
+    return 90;
+  }
+
+  /**
+   * Calculates the overall score based on the assessment results.
+   *
+   * @returns {number} The overall score.
+   */
+  calculateOverallScore() {
+    const results = this.getValidResults();
+
+    // If you have no content, you have a red indicator.
+    if (results.length === 0) {
+      return 30;
+    }
+
+    const totalPenaltyPoints = this.calculatePenaltyPoints();
+
+    return this._ratePenaltyPoints(totalPenaltyPoints);
+  }
+}

package/src/scoring/assessors/index.js

@@ -0,0 +1,4 @@
+export {default as Assessor} from './assessor.js';
+export {default as ContentAssessor} from './contentAssessor.js';
+export {default as SEOAssessor} from './seoAssessor.js';
+export {default as AvadaAssessor} from './avadaAssessor.js';

package/src/scoring/assessors/seoAssessor.js

@@ -0,0 +1,57 @@
+import Assessor from './assessor';
+import IntroductionKeywordAssessment from '../assessments/seo/IntroductionKeywordAssessment';
+import KeyphraseLengthAssessment from '../assessments/seo/KeyphraseLengthAssessment';
+import MetaDescriptionKeywordAssessment from '../assessments/seo/MetaDescriptionKeywordAssessment';
+import MetaDescriptionLength from '../assessments/seo/MetaDescriptionLengthAssessment';
+import SubheadingsKeyword from '../assessments/seo/SubHeadingsKeywordAssessment';
+import OutboundLinks from '../assessments/seo/OutboundLinksAssessment';
+import KeyphraseDensityAssessment from '../assessments/seo/KeywordDensityAssessment';
+import InternalLinksAssessment from '../assessments/seo/InternalLinksAssessment';
+import SlugKeywordAssessment from '../assessments/seo/UrlKeywordAssessment';
+import ImageCount from '../assessments/seo/ImageCountAssessment';
+import TextLength from '../assessments/seo/TextLengthAssessment';
+import TitleWidth from '../assessments/seo/PageTitleWidthAssessment';
+import SingleH1Assessment from '../assessments/seo/SingleH1Assessment';
+import KeyphraseAssessment from '../assessments/seo/KeyphraseAssessment';
+import SingleTitleAssessment from '../assessments/seo/SingleTitleAssessment';
+import UrlLengthAssessment from '../assessments/seo/UrlLengthAssessment';
+import NumberInMetaTitleAssessment from '../assessments/seo/NumberInMetaTitleAssessment';
+import TextImagesAssessment from '../assessments/seo/TextImagesAssessment';
+import MetaTitleKeywordAssessment from '../assessments/seo/MetaTitleKeywordAssessment';
+
+/**
+ * The SEOAssessor class is used for the general SEO analysis.
+ */
+export default class SEOAssessor extends Assessor {
+  /**
+   * Creates a new SEOAssessor instance.
+   * @param {Researcher}	researcher	The researcher to use.
+   * @param {Object}		[options]	The assessor options.
+   */
+  constructor(researcher, options) {
+    super(researcher, options);
+    this.type = 'SEOAssessor';
+
+    this._assessments = [
+      new MetaTitleKeywordAssessment(),
+      new TextImagesAssessment(),
+      new NumberInMetaTitleAssessment(),
+      new IntroductionKeywordAssessment(),
+      new KeyphraseLengthAssessment(),
+      new MetaDescriptionKeywordAssessment(),
+      new MetaDescriptionLength(),
+      new SubheadingsKeyword(),
+      new OutboundLinks(),
+      new KeyphraseDensityAssessment(),
+      new ImageCount(),
+      new UrlLengthAssessment(),
+      new TextLength(),
+      new SingleTitleAssessment(),
+      new KeyphraseAssessment(),
+      new InternalLinksAssessment(),
+      new TitleWidth(),
+      new SlugKeywordAssessment(),
+      new SingleH1Assessment()
+    ];
+  }
+}

package/src/scoring/helpers/assessments/checkForTooLongSentences.js

@@ -0,0 +1,13 @@
+import { filter } from "lodash";
+
+/**
+ * Checks for too long sentences.
+ * @param {array} sentences The array with objects containing sentences and their lengths.
+ * @param {number} recommendedValue The recommended maximum length of sentence.
+ * @returns {array} The array with objects containing too long sentences and their lengths.
+ */
+export default function( sentences, recommendedValue ) {
+	return filter( sentences, function( sentence ) {
+		return sentence.sentenceLength > recommendedValue;
+	} );
+}

package/src/scoring/helpers/assessments/inRange.js

@@ -0,0 +1,49 @@
+/**
+ * Checks if `n` is between `start` and `end` but not including `start`.
+ *
+ * @param {number} number The number to check.
+ * @param {number} start The start of the range.
+ * @param {number} end The end of the range.
+ * @returns {boolean} Returns `true` if `number` is in the range, else `false`.
+ */
+function inRangeEndInclusive( number, start, end ) {
+	return number > start && number <= end;
+}
+
+/**
+ * Checks if `n` is between `start` and up to, but not including, `end`.
+ *
+ * @param {number} number The number to check.
+ * @param {number} start The start of the range.
+ * @param {number} end The end of the range.
+ * @returns {boolean} Returns `true` if `number` is in the range, else `false`.
+ */
+function inRangeStartInclusive( number, start, end ) {
+	return number >= start && number < end;
+}
+
+/**
+ * Checks if `n` is between `start` and `end`, including both.
+ *
+ * @param {number} number The number to check.
+ * @param {number} start The start of the range.
+ * @param {number} end The end of the range.
+ * @returns {boolean} Returns `true` if `number` is in the range, else `false`.
+ */
+function inRangeStartEndInclusive( number, start, end ) {
+	return number >= start && number <= end;
+}
+
+export {
+	inRangeEndInclusive as inRange,
+	inRangeStartInclusive,
+	inRangeEndInclusive,
+	inRangeStartEndInclusive,
+};
+
+export default {
+	inRange: inRangeEndInclusive,
+	inRangeStartInclusive: inRangeStartInclusive,
+	inRangeEndInclusive: inRangeEndInclusive,
+	inRangeStartEndInclusive: inRangeStartEndInclusive,
+};

package/src/scoring/helpers/assessments/keyphraseLengthFactor.js

@@ -0,0 +1,10 @@
+/**
+ * Calculates the keyphrase length weighting factor used to calculate the keyword density and the recommended keyword count.
+ * Keyphrase length gets a base weight of 0.7, plus a specific weight for the keyphrase length (keyphraseLength / 3).
+ *
+ * @param {number} keyphraseLength The length of the keyphrase in words.
+ * @returns {number} The keyphrase length weighting factor.
+ */
+export default function( keyphraseLength ) {
+	return ( 0.7 + keyphraseLength / 3 );
+}

package/src/scoring/helpers/assessments/recommendedKeywordCount.js

@@ -0,0 +1,43 @@
+import getAllWordsFromTree from "../../../languageProcessing/helpers/word/getAllWordsFromTree";
+import keyphraseLengthFactor from "./keyphraseLengthFactor.js";
+
+/**
+ * Calculates a recommended keyphrase count for a paper's text. The formula to calculate this number is based on the
+ * keyphrase density formula.
+ *
+ * @param {Paper}	paper						The paper to analyze.
+ * @param {number}	keyphraseLength				The length of the focus keyphrase in words.
+ * @param {number}	recommendedKeyphraseDensity	The recommended keyphrase density (either maximum or minimum).
+ * @param {string}	maxOrMin					Whether it's a maximum or minimum recommended keyphrase density.
+ * @param {function} customGetWords				A helper to get words from the text for languages that don't use the default approach.
+ *
+ * @returns {number} The recommended keyphrase count.
+ */
+export default function( paper, keyphraseLength, recommendedKeyphraseDensity, maxOrMin, customGetWords ) {
+	const wordCount = customGetWords ? customGetWords( paper.getText() ).length : getAllWordsFromTree( paper ).length;
+
+	if ( wordCount === 0 ) {
+		return 0;
+	}
+
+	const lengthKeyphraseFactor = keyphraseLengthFactor( keyphraseLength );
+	const recommendedKeyphraseCount = ( recommendedKeyphraseDensity * wordCount ) / ( 100 * lengthKeyphraseFactor );
+
+	/*
+	 * The recommended keyphrase count should always be at least 2,
+	 * regardless of the keyphrase density, the word count, or the keyphrase length.
+	 */
+	if ( recommendedKeyphraseCount < 2 ) {
+		return 2;
+	}
+
+	switch ( maxOrMin ) {
+		case "min":
+			// Round up for the recommended minimum count.
+			return Math.ceil( recommendedKeyphraseCount );
+		default:
+		case "max":
+			// Round down for the recommended maximum count.
+			return Math.floor( recommendedKeyphraseCount );
+	}
+}