# magendoo/module-catalog-quality

> Catalog data quality observability for Magento 2 — completeness scoring, filter-blind detection, and gap reporting

`composer require magendoo/module-catalog-quality`

Canonical URL: https://packagento.com/magendoo/module-catalog-quality

## At a glance

- **Vendor**: magendoo (https://packagento.com/magendoo.md)
- **Latest version**: 2.0.0 — released 2026-07-18
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/magendoo/module-catalog-quality and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require magendoo/module-catalog-quality:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Catalog data quality observability for Magento 2 — completeness scoring, filter-blind detection, and gap reporting

## README

**Catalog data quality observability for Magento 2.**  
Know exactly which products are hurting your conversion rate before your customers find out.

[![Magento 2](https://img.shields.io/badge/Magento-2.4.x-orange)](https://devdocs.magento.com/)
[![PHP](https://img.shields.io/badge/PHP-8.2%2B-blue)](https://www.php.net/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)

---

### What It Does

Magendoo_CatalogQuality scores every product in your catalog against a two-axis quality model — **Enrichment** (are the important attributes filled in?) and **Consistency** (do they meet your content rules?) — and combines them into a single **Product Health Score (PHS)** between 0 and 100. Products are graded A–E.

The module answers three questions that every Magento merchant needs:

1. **Which products are incomplete?** — The Gap List shows every product's grade, PHS, priority gaps, and the specific missing attribute codes.
2. **Which products are invisible in layered navigation?** — The Filter-Blind detector flags products that have no value for a filterable attribute, making them unfindable when shoppers use your category filters.
3. **Which filter attributes have the worst coverage across categories?** — The Filter Coverage Matrix shows fill rates as a colour-coded heatmap, scoped by attribute set.

No auto-fix. Just clear, actionable diagnostic data.

---

### Screenshots

#### Dashboard

![Catalog Quality Dashboard](docs/images/dashboard.png)

The dashboard shows the **Catalog Health Index (CHI)** — an aggregate PHS across all scored products of the default store view, weighted by 90-day product revenue when revenue weighting is enabled and sales data exists — alongside grade distribution, filter-blind product count, and a 30-day CHI trend chart.

#### Product Gap List

![Product Gap List](docs/images/gap-list.png)

Every scored product in one grid: grade badge, PHS, P1/P2/P3 gap counts, a filter-blind chip, and colour-coded missing attribute chips. Red chips are filterable attributes directly causing filter-blindness; grey chips are other priority gaps.

#### Filter Coverage Matrix

![Filter Coverage Matrix](docs/images/filter-matrix.png)

Rows are user-defined filterable attributes; columns are active categories (filterable by attribute set). Each cell shows the fill-rate percentage, colour-coded from green (≥90 %) to red (<35 %). The callout above the matrix links to the Gap List for drilling into individual filter-blind products.

#### Attribute Priorities

![Attribute Priorities](docs/images/priorities.png)

The priority grid controls how much each attribute matters to the score. Priority levels are inline-editable; every change is audited and marks the score index for rebuild.

---

### Features

- **Two-axis PHS scoring**: Enrichment completeness × Consistency conformance multipliers
- **A–E grade thresholds**: ≥90 → A, ≥80 → B, ≥70 → C, ≥50 → D, <50 → E
- **Revenue-weighted CHI**: weights products by 90-day revenue (order totals minus refunds, processing/complete orders); falls back to the equal-weighted average when no revenue exists
- **Filter-blind detection**: flags products invisible in layered navigation per store view, considering only filterable attributes that belong to the product's own attribute set
- **Attribute Priority System**: P1/P2/P3/P4/Ignore per attribute, with category and attribute-set overrides; every change is audited and marks the score index for rebuild
- **Placeholder blocklist**: regex and literal patterns to catch values like "N/A", "TBD", "Lorem ipsum"
- **9 built-in quality rules**: Meta Title, Meta Description, URL Key, Name, Description, Image, Price, Filterable Attribute, Category Assignment — each rule's enabled flag and severity come from the `magendoo_cq_rule_config` table
- **Conditional attribute groups**: score module-specific attributes only when their control flag is on (e.g. base-price fields only when `baseprice_is_enabled = 1`)
- **Magento indexer integration**: incremental updates via MView subscriptions on the product entity, EAV value, and category-assignment tables; full reindex via CLI
- **Nightly CHI snapshots**: 30-day trend data stored automatically via cron (one row per store view per UTC day)
- **CSV export** of the priority table via CLI (`catalog-quality:priorities:export`)
- **REST API**: 6 endpoints for scores and priorities
- **Inline-editable Priority Grid**: change priority levels without leaving the listing
- **Filter Coverage Matrix**: attribute set filter, product counts per category column
- **UTC everywhere**: all timestamps the module writes (score computation times, priority history, snapshots, run logs) are UTC

---

### Requirements

| Dependency | Version |
|---|---|
| PHP | ≥ 8.2 |
| Magento Open Source / Adobe Commerce | 2.4.x |
| `magento/framework` | ≥ 103.0 |
| `magento/module-catalog` | ≥ 104.0 |

---

### Installation

#### Via Composer (recommended)

Until the package is listed on Packagist, add the GitHub repository first:

```bash
composer config repositories.magendoo-catalog-quality vcs https://github.com/magendooro/magento2-catalog-quality
```

Then install:

```bash
composer require magendoo/module-catalog-quality
bin/magento module:enable Magendoo_CatalogQuality
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush
```

#### Manual

1. Copy the module directory into `app/code/Magendoo/CatalogQuality/`
2. Run the same CLI commands above

---

### Upgrading from 1.x to 2.0

_(README truncated for .md surface. Full README on https://packagento.com/magendoo/module-catalog-quality.)_

## Recent Versions

| Version | Released |
|---|---|
| 2.0.0 | 2026-07-18 |
| 1.0.0 | 2026-04-21 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| magento/framework | >=103.0 |
| magento/module-backend | >=102.0 |
| magento/module-catalog | >=104.0 |
| magento/module-eav | >=102.0 |
| magento/module-indexer | >=100.4 |
| magento/module-store | >=101.0 |
| magento/module-ui | >=101.2 |
| php | >=8.2 |

## Quality

Latest release (2.0.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Warning | 5 | 5 warnings (ruleset: Magento2) |
| PHPMD | Warning | 43 | 43 rule violations (UnusedPrivateField:43) |
| Cpd | Pass | 0 |  |
| Composer validate | Info | 8 | valid; 8 advisory notes (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 15 | 15 | – | – |
| 2.4.8 | – | 15 | 15 | – |
| 2.4.9 | – | – | 15 | 15 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["magendoo/module-catalog-quality"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

magendoo is a Magento 2 vendor on Packagento. See https://packagento.com/magendoo.md for their full catalogue.