@power-seo/content-analysis 1.0.6 → 1.0.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CCBD SEO Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,9 +12,9 @@ Keyword-focused content analysis with real-time scoring, readability checks, and
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
 [![tree-shakeable](https://img.shields.io/badge/tree--shakeable-yes-brightgreen)](https://bundlephobia.com/package/@power-seo/content-analysis)
 
-`@power-seo/content-analysis` delivers a comprehensive, WordPress SEO plugin–style scoring pipeline for evaluating text content, comparable to Yoast SEO, All in One SEO (AIOSEO), Rank Math, SEOPress, and The SEO Framework. Provide a page title, meta description, body content, focus keyphrase, images, and links — get back structured `good` / `needs-improvement` / `poor` results across all critical SEO factors. Run it server-side in a CMS, client-side in a React editor, or inside a CI content quality gate. All 13 analysis checks are fully configurable and tree-shakeable.
+`@power-seo/content-analysis` delivers a comprehensive, WordPress SEO plugin–style scoring pipeline for evaluating text content, comparable to Yoast SEO, All in One SEO (AIOSEO), Rank Math, SEOPress, and The SEO Framework. Provide a page title, meta description, body content, focus keyphrase, images, and links — get back structured `good` / `ok` / `poor` results across all critical SEO factors. Run it server-side in a CMS, client-side in a React editor, or inside a CI content quality gate. All 13 analysis checks are fully configurable and tree-shakeable.
 
-> **Zero runtime dependencies** — only `@power-seo/core` as a peer.
+> **Zero external runtime dependencies** — `@power-seo/core` is a direct dependency bundled with this package; no extra install needed.
 
 ---
 
@@ -82,15 +82,15 @@ Keyword-focused content analysis with real-time scoring, readability checks, and
 ## Installation
 
 ```bash
-npm install @power-seo/content-analysis @power-seo/core
+npm install @power-seo/content-analysis
 ```
 
 ```bash
-yarn add @power-seo/content-analysis @power-seo/core
+yarn add @power-seo/content-analysis
 ```
 
 ```bash
-pnpm add @power-seo/content-analysis @power-seo/core
+pnpm add @power-seo/content-analysis
 ```
 
 ---
@@ -103,21 +103,21 @@ import { analyzeContent } from '@power-seo/content-analysis';
 const result = analyzeContent({
   title: 'Best Running Shoes for Beginners',
   metaDescription: 'Discover the best running shoes for beginners with our expert guide.',
-  keyphrase: 'running shoes for beginners',
+  focusKeyphrase: 'running shoes for beginners',
   content: '<h1>Best Running Shoes</h1><p>Finding the right running shoes...</p>',
-  url: 'https://example.com/best-running-shoes',
 });
 
-console.log(result.overallStatus); // "good" | "needs-improvement" | "poor"
+console.log(result.score);      // e.g. 38
+console.log(result.maxScore);   // e.g. 55
 console.log(result.results);
-// [{ id: 'title-presence', status: 'good', message: '...' }, ...]
+// [{ id: 'title-presence', status: 'good', description: '...', score: 5, maxScore: 5 }, ...]
 ```
 
 ![SEO Check Results](../../image/content-analysis/check-results.svg)
 
 **Status thresholds (per check):**
 - `good` — check fully passes
-- `needs-improvement` — check partially passes
+- `ok` — check partially passes
 - `poor` — check fails
 
 ---
@@ -134,16 +134,16 @@ import { analyzeContent } from '@power-seo/content-analysis';
 const output = analyzeContent({
   title: 'Next.js SEO Best Practices',
   metaDescription: 'Learn how to optimize your Next.js app for search engines with meta tags and structured data.',
-  keyphrase: 'next.js seo',
+  focusKeyphrase: 'next.js seo',
   content: htmlString,
-  url: 'https://example.com/nextjs-seo',
   images: imageList,
   internalLinks: internalLinks,
   externalLinks: externalLinks,
 });
 
-// output.overallStatus  → 'good' | 'needs-improvement' | 'poor'
-// output.results        → AnalysisResult[]
+// output.score      → number (sum of all check scores)
+// output.maxScore   → number (maximum possible score)
+// output.results    → AnalysisResult[]
 ```
 
 ### Running Individual Checks
@@ -162,20 +162,22 @@ import {
 } from '@power-seo/content-analysis';
 
 const titleResults = checkTitle({
-  title: 'React SEO Guide',
-  keyphrase: 'react seo',
   content: '',
+  title: 'React SEO Guide',
+  focusKeyphrase: 'react seo',
 });
-// [{ id: 'title-presence', status: 'good', message: '...' },
-//  { id: 'title-keyphrase', status: 'good', message: '...' }]
+// [
+//   { id: 'title-presence', title: 'SEO title', description: '...', status: 'good', score: 5, maxScore: 5 },
+//   { id: 'title-keyphrase', title: 'Keyphrase in title', description: '...', status: 'good', score: 5, maxScore: 5 }
+// ]
 
 const wcResult = checkWordCount({ content: shortHtml });
-// { id: 'word-count', status: 'poor', message: 'Content is 180 words, below minimum of 300.' }
+// { id: 'word-count', title: 'Word count', description: 'The content is 180 words...', status: 'poor', score: 1, maxScore: 5 }
 ```
 
 ### Disabling Specific Checks
 
-Pass `config.disabledChecks` to skip checks that don't apply to your content type:
+Pass `config.disabledChecks` to exclude specific checks from the output. Checks are still executed internally but their results are filtered from `output.results` and excluded from `score`/`maxScore` totals. Invalid check IDs are silently ignored.
 
 ```ts
 import { analyzeContent } from '@power-seo/content-analysis';
@@ -191,6 +193,7 @@ Import from the `/react` entry point for pre-built analysis UI components:
 
 ```tsx
 import { ContentAnalyzer, ScorePanel, CheckList } from '@power-seo/content-analysis/react';
+import { analyzeContent } from '@power-seo/content-analysis';
 import type { ContentAnalysisInput } from '@power-seo/content-analysis';
 
 // All-in-one component
@@ -217,13 +220,13 @@ Block deploys when SEO checks fail:
 ```ts
 import { analyzeContent } from '@power-seo/content-analysis';
 
-const output = analyzeContent({ title, metaDescription, keyphrase, content });
+const output = analyzeContent({ title, metaDescription, focusKeyphrase, content });
 
 const failures = output.results.filter((r) => r.status === 'poor');
 
 if (failures.length > 0) {
   console.error('SEO checks failed:');
-  failures.forEach((r) => console.error(' ✗', r.message));
+  failures.forEach((r) => console.error(' ✗', r.description));
   process.exit(1);
 }
 ```
@@ -255,31 +258,31 @@ function analyzeContent(
 | `content`         | `string`                               | ✅       | Body HTML string                               |
 | `title`           | `string`                               | —        | Page `<title>` content                         |
 | `metaDescription` | `string`                               | —        | Meta description content                       |
-| `keyphrase`       | `string`                               | —        | Focus keyphrase to analyze against             |
-| `url`             | `string`                               | —        | Page URL (used for slug analysis)              |
+| `focusKeyphrase`  | `string`                               | —        | Focus keyphrase to analyze against             |
+| `slug`            | `string`                               | —        | URL slug (used for keyphrase-in-slug check)    |
 | `images`          | `Array<{ src: string; alt?: string }>` | —        | Images found on the page                       |
 | `internalLinks`   | `string[]`                             | —        | Internal link URLs                             |
 | `externalLinks`   | `string[]`                             | —        | External link URLs                             |
 
 #### `ContentAnalysisOutput`
 
-| Field           | Type               | Description                                               |
-| --------------- | ------------------ | --------------------------------------------------------- |
-| `overallStatus` | `AnalysisStatus`   | `'good'` \| `'needs-improvement'` \| `'poor'`            |
-| `score`         | `number`           | Sum of all individual check scores                        |
-| `maxScore`      | `number`           | Maximum possible score (varies by enabled checks)         |
-| `results`       | `AnalysisResult[]` | Per-check results                                         |
-| `recommendations` | `string[]`       | Descriptions from all failed or partial checks            |
+| Field             | Type               | Description                                           |
+| ----------------- | ------------------ | ----------------------------------------------------- |
+| `score`           | `number`           | Sum of all individual check scores                    |
+| `maxScore`        | `number`           | Maximum possible score (varies by enabled checks)     |
+| `results`         | `AnalysisResult[]` | Per-check results                                     |
+| `recommendations` | `string[]`         | Descriptions from all failed or partial checks        |
 
 #### `AnalysisResult`
 
-| Field     | Type             | Description                                   |
-| --------- | ---------------- | --------------------------------------------- |
-| `id`      | `CheckId`        | Unique check identifier (see table below)     |
-| `status`  | `AnalysisStatus` | `'good'` \| `'needs-improvement'` \| `'poor'` |
-| `message` | `string`         | Human-readable actionable feedback            |
-| `score`   | `number`         | Points earned for this check                  |
-| `maxScore`| `number`         | Maximum points for this check                 |
+| Field         | Type             | Description                                               |
+| ------------- | ---------------- | --------------------------------------------------------- |
+| `id`          | `string`         | Unique check identifier (one of the `CheckId` values)     |
+| `title`       | `string`         | Short display label for the check (e.g. `"SEO title"`)    |
+| `description` | `string`         | Human-readable actionable feedback                        |
+| `status`      | `AnalysisStatus` | `'good'` \| `'ok'` \| `'poor'`                            |
+| `score`       | `number`         | Points earned for this check                              |
+| `maxScore`    | `number`         | Maximum points for this check                             |
 
 #### `AnalysisConfig`
 
@@ -289,15 +292,17 @@ function analyzeContent(
 
 ### Individual Check Functions
 
-| Function                      | Check ID(s)                                                    | Checks For                                         |
-| ----------------------------- | -------------------------------------------------------------- | -------------------------------------------------- |
-| `checkTitle(input)`           | `title-presence`, `title-keyphrase`                            | Title presence, length (30–60 chars), keyphrase    |
-| `checkMetaDescription(input)` | `meta-description-presence`, `meta-description-keyphrase`      | Description presence, length (120–160 chars), keyphrase |
-| `checkKeyphraseUsage(input)`  | `keyphrase-density`, `keyphrase-distribution`                  | Density (0.5–2.5%) and occurrence in key areas     |
-| `checkHeadings(input)`        | `heading-structure`, `heading-keyphrase`                       | H1 presence, hierarchy, keyphrase in subheadings   |
-| `checkWordCount(input)`       | `word-count`                                                   | Min 300 words (good at 1,000+)                     |
-| `checkImages(input)`          | `image-alt`, `image-keyphrase`                                 | Alt text presence and keyphrase in alt             |
-| `checkLinks(input)`           | `internal-links`, `external-links`                             | Internal and external link presence                |
+| Function                      | Check ID(s)                                                    | Checks For                                                                                  |
+| ----------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `checkTitle(input)`           | `title-presence`, `title-keyphrase`                            | Title presence **and** length (50–60 chars, validated inside `title-presence`), keyphrase    |
+| `checkMetaDescription(input)` | `meta-description-presence`, `meta-description-keyphrase`      | Description presence, length (120–160 chars), keyphrase                                     |
+| `checkKeyphraseUsage(input)`  | `keyphrase-density`, `keyphrase-distribution`                  | Density (0.5–2.5%) and occurrence in key areas                                              |
+| `checkHeadings(input)`        | `heading-structure`, `heading-keyphrase`                       | H1 presence, hierarchy, keyphrase in subheadings                                            |
+| `checkWordCount(input)`       | `word-count`                                                   | Min 300 words (good at 1,000+)                                                              |
+| `checkImages(input)`          | `image-alt`, `image-keyphrase`                                 | Alt text presence and keyphrase in alt                                                      |
+| `checkLinks(input)`           | `internal-links`, `external-links`                             | Internal and external link presence                                                         |
+
+> **Note:** There is no separate `title-length` check ID. Title length validation (50–60 chars) is evaluated inside the `title-presence` check — a title that exists but is outside the recommended range returns `status: 'ok'` rather than `'good'`.
 
 ### Types
 
@@ -305,10 +310,10 @@ function analyzeContent(
 | ----------------------- | --------------------------------------------------------- |
 | `CheckId`               | Union of all 13 built-in check IDs                        |
 | `AnalysisConfig`        | `{ disabledChecks?: CheckId[] }`                          |
-| `AnalysisStatus`        | `'good' \| 'needs-improvement' \| 'poor'`                 |
+| `AnalysisStatus`        | `'good' \| 'ok' \| 'poor'`                               |
 | `ContentAnalysisInput`  | Input shape for `analyzeContent()`                        |
 | `ContentAnalysisOutput` | Output shape from `analyzeContent()`                      |
-| `AnalysisResult`        | Single check result with id, status, message, score       |
+| `AnalysisResult`        | Single check result with id, title, description, status, score, maxScore |
 
 ---
 
@@ -326,7 +331,7 @@ function analyzeContent(
 ## Architecture Overview
 
 - **Pure TypeScript** — no compiled binary, no native modules
-- **Zero runtime dependencies** — only `@power-seo/core` as a peer dependency
+- **Zero external runtime dependencies** — `@power-seo/core` ships as a direct dependency, no separate install
 - **Framework-agnostic** — works in any JavaScript environment
 - **SSR compatible** — safe to run in Next.js Server Components, Remix loaders, or Express handlers
 - **Edge runtime safe** — no Node.js-specific APIs; runs in Cloudflare Workers, Vercel Edge, Deno

package/dist/index.cjs

@@ -1,8 +1,38 @@
-'use strict';
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-var core = require('@power-seo/core');
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  analyzeContent: () => analyzeContent,
+  checkHeadings: () => checkHeadings,
+  checkImages: () => checkImages,
+  checkKeyphraseUsage: () => checkKeyphraseUsage,
+  checkLinks: () => checkLinks,
+  checkMetaDescription: () => checkMetaDescription,
+  checkTitle: () => checkTitle,
+  checkWordCount: () => checkWordCount
+});
+module.exports = __toCommonJS(src_exports);
 
 // src/checks/title.ts
+var import_core = require("@power-seo/core");
 function checkTitle(input) {
   const results = [];
   const { title, focusKeyphrase } = input;
@@ -17,7 +47,7 @@ function checkTitle(input) {
     });
     return results;
   }
-  const validation = core.validateTitle(title);
+  const validation = (0, import_core.validateTitle)(title);
   if (!validation.valid) {
     results.push({
       id: "title-presence",
@@ -71,6 +101,9 @@ function checkTitle(input) {
   }
   return results;
 }
+
+// src/checks/meta-description.ts
+var import_core2 = require("@power-seo/core");
 function checkMetaDescription(input) {
   const results = [];
   const { metaDescription, focusKeyphrase } = input;
@@ -85,7 +118,7 @@ function checkMetaDescription(input) {
     });
     return results;
   }
-  const validation = core.validateMetaDescription(metaDescription);
+  const validation = (0, import_core2.validateMetaDescription)(metaDescription);
   if (!validation.valid) {
     results.push({
       id: "meta-description-presence",
@@ -139,6 +172,9 @@ function checkMetaDescription(input) {
   }
   return results;
 }
+
+// src/checks/keyphrase-usage.ts
+var import_core3 = require("@power-seo/core");
 function checkKeyphraseUsage(input) {
   const results = [];
   const { focusKeyphrase, title, metaDescription, content, slug, images } = input;
@@ -153,7 +189,7 @@ function checkKeyphraseUsage(input) {
     });
     return results;
   }
-  const occurrences = core.analyzeKeyphraseOccurrences({
+  const occurrences = (0, import_core3.analyzeKeyphraseOccurrences)({
     keyphrase: focusKeyphrase,
     title,
     metaDescription,
@@ -161,27 +197,27 @@ function checkKeyphraseUsage(input) {
     slug,
     images
   });
-  const densityResult = core.calculateKeywordDensity(focusKeyphrase, content);
-  if (densityResult.density < core.KEYWORD_DENSITY.MIN) {
+  const densityResult = (0, import_core3.calculateKeywordDensity)(focusKeyphrase, content);
+  if (densityResult.density < import_core3.KEYWORD_DENSITY.MIN) {
     results.push({
       id: "keyphrase-density",
       title: "Keyphrase density",
-      description: `Keyphrase density is ${densityResult.density}%, which is below the recommended minimum of ${core.KEYWORD_DENSITY.MIN}%. Use the keyphrase more often.`,
+      description: `Keyphrase density is ${densityResult.density}%, which is below the recommended minimum of ${import_core3.KEYWORD_DENSITY.MIN}%. Use the keyphrase more often.`,
       status: "poor",
       score: 1,
       maxScore: 5
     });
-  } else if (densityResult.density > core.KEYWORD_DENSITY.MAX) {
+  } else if (densityResult.density > import_core3.KEYWORD_DENSITY.MAX) {
     results.push({
       id: "keyphrase-density",
       title: "Keyphrase density",
-      description: `Keyphrase density is ${densityResult.density}%, which exceeds the recommended maximum of ${core.KEYWORD_DENSITY.MAX}%. Reduce usage to avoid keyword stuffing.`,
+      description: `Keyphrase density is ${densityResult.density}%, which exceeds the recommended maximum of ${import_core3.KEYWORD_DENSITY.MAX}%. Reduce usage to avoid keyword stuffing.`,
       status: "poor",
       score: 1,
       maxScore: 5
     });
-  } else if (densityResult.density >= core.KEYWORD_DENSITY.MIN && densityResult.density <= core.KEYWORD_DENSITY.MAX) {
-    const isOptimal = Math.abs(densityResult.density - core.KEYWORD_DENSITY.OPTIMAL) < 0.5;
+  } else if (densityResult.density >= import_core3.KEYWORD_DENSITY.MIN && densityResult.density <= import_core3.KEYWORD_DENSITY.MAX) {
+    const isOptimal = Math.abs(densityResult.density - import_core3.KEYWORD_DENSITY.OPTIMAL) < 0.5;
     results.push({
       id: "keyphrase-density",
       title: "Keyphrase density",
@@ -227,15 +263,37 @@ function checkKeyphraseUsage(input) {
   }
   return results;
 }
+
+// src/checks/headings.ts
+var import_core4 = require("@power-seo/core");
 function parseHeadings(html) {
   const headings = [];
-  const regex = /<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi;
-  let match;
-  while ((match = regex.exec(html)) !== null) {
+  const lc = html.toLowerCase();
+  let pos = 0;
+  while (pos < lc.length) {
+    let earliest = -1;
+    let earliestLevel = 0;
+    for (let level = 1; level <= 6; level++) {
+      const idx = lc.indexOf(`<h${level}`, pos);
+      if (idx !== -1 && (earliest === -1 || idx < earliest)) {
+        earliest = idx;
+        earliestLevel = level;
+      }
+    }
+    if (earliest === -1) break;
+    const contentStart = lc.indexOf(">", earliest);
+    if (contentStart === -1) break;
+    const closeTag = `</h${earliestLevel}>`;
+    const closeIdx = lc.indexOf(closeTag, contentStart + 1);
+    if (closeIdx === -1) {
+      pos = contentStart + 1;
+      continue;
+    }
     headings.push({
-      level: parseInt(match[1], 10),
-      text: core.stripHtml(match[2])
+      level: earliestLevel,
+      text: (0, import_core4.stripHtml)(html.slice(contentStart + 1, closeIdx))
     });
+    pos = closeIdx + closeTag.length;
   }
   return headings;
 }
@@ -327,24 +385,27 @@ function checkHeadings(input) {
   }
   return results;
 }
+
+// src/checks/word-count.ts
+var import_core5 = require("@power-seo/core");
 function checkWordCount(input) {
-  const words = core.getWords(input.content);
+  const words = (0, import_core5.getWords)(input.content);
   const count = words.length;
-  if (count < core.MIN_WORD_COUNT) {
+  if (count < import_core5.MIN_WORD_COUNT) {
     return {
       id: "word-count",
       title: "Word count",
-      description: `The content is ${count} words, which is below the recommended minimum of ${core.MIN_WORD_COUNT}. Add more content to improve SEO.`,
+      description: `The content is ${count} words, which is below the recommended minimum of ${import_core5.MIN_WORD_COUNT}. Add more content to improve SEO.`,
       status: "poor",
       score: 1,
       maxScore: 5
     };
   }
-  if (count < core.RECOMMENDED_WORD_COUNT) {
+  if (count < import_core5.RECOMMENDED_WORD_COUNT) {
     return {
       id: "word-count",
       title: "Word count",
-      description: `The content is ${count} words. Consider expanding to at least ${core.RECOMMENDED_WORD_COUNT} words for more comprehensive coverage.`,
+      description: `The content is ${count} words. Consider expanding to at least ${import_core5.RECOMMENDED_WORD_COUNT} words for more comprehensive coverage.`,
       status: "ok",
       score: 3,
       maxScore: 5
@@ -512,14 +573,15 @@ function analyzeContent(input, config) {
     recommendations
   };
 }
-
-exports.analyzeContent = analyzeContent;
-exports.checkHeadings = checkHeadings;
-exports.checkImages = checkImages;
-exports.checkKeyphraseUsage = checkKeyphraseUsage;
-exports.checkLinks = checkLinks;
-exports.checkMetaDescription = checkMetaDescription;
-exports.checkTitle = checkTitle;
-exports.checkWordCount = checkWordCount;
-//# sourceMappingURL=index.cjs.map
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  analyzeContent,
+  checkHeadings,
+  checkImages,
+  checkKeyphraseUsage,
+  checkLinks,
+  checkMetaDescription,
+  checkTitle,
+  checkWordCount
+});
 //# sourceMappingURL=index.cjs.map