=== Structure Audit for LearnDash ===
Contributors: rajaamanullah
Tags: learndash, lms, orphaned content, course cleanup, elearning
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Audit your LearnDash site for orphaned lessons, empty courses, quizzes with no questions and broken course links — then clean them up safely.

== Description ==

LearnDash sites accumulate structural debt. Courses get restructured, lessons get detached, quizzes lose their questions, groups lose their leaders — and none of it is visible until a learner hits a wall.

**Structure Audit for LearnDash** scans your site and tells you what is broken, in one screen.

The damage is quiet, which is what makes it expensive. A lesson removed from a course does not get deleted — it stays in the database, unattached, invisible in the course builder but still returned by queries and still counted in your content. A quiz that lost its questions still appears in the course outline and still blocks progression when a learner reaches it. A course whose prerequisite was unpublished simply stops being accessible, and the first you hear about it is a support ticket saying "it won't let me in". None of this shows up in the LearnDash admin, because the admin shows you what exists, not what is missing.

This plugin looks for the missing half. It runs twelve checks across your courses, lessons, topics, quizzes, questions and groups, and reports every item that is structurally wrong — grouped by severity so you know what to fix now and what is merely untidy. Four checks are critical (things learners are hitting today), five are warnings, and three are notices for content that is probably fine but worth confirming.

It is built to be safe to run on a live site. The scan is read-only and changes nothing. Where cleanup is offered, it moves items to the WordPress trash rather than deleting them, so anything removed by mistake is restorable from the normal Trash view. The plugin stores nothing in your database — no options, no tables, no scheduled jobs — so it leaves no trace whether you keep it or remove it.

This plugin requires the LearnDash LMS plugin, which is a separate commercial product sold by its own authors. Install and activate LearnDash first.

= What it checks =

* **Courses with no content** — enrolled learners see an empty course
* **Orphaned lessons** — not attached to any course
* **Orphaned topics** — not attached to a course or lesson
* **Orphaned quizzes** — attached to nothing
* **Quizzes with no questions** — breaks the learner flow
* **Questions not used in any quiz** — question-bank clutter
* **Courses with no certificate** — listed so you can confirm it's deliberate
* **Groups with no group leader** — nobody can administer or report on them
* **Groups with no courses** — membership grants no access
* **Steps pointing at a missing course** — broken associations
* **Unpublished courses with enrolled users** — learners locked out
* **Broken course prerequisites** — can lock learners out permanently

= Safe by design =

* **The scan is read-only.** Running it never changes anything.
* **Cleanup is opt-in and reversible.** Where a cleanup action is offered, items are moved to the **trash** — never permanently deleted — so you can restore them from the WordPress UI.
* **Nothing is stored.** No options, no custom tables, no cron jobs, no cached report.
* **Version-tolerant.** Each check uses LearnDash's own API where available and is skipped gracefully — never fatally — if a function is unavailable in your LearnDash version.
* Results are grouped by severity so you can triage: critical, warning, notice.

= Who it's for =

* **Site owners** doing a spring clean before a launch
* **Agencies and freelancers** auditing an inherited LearnDash site, where nobody remembers how the courses were built
* **Course creators** who have restructured a curriculum and want to know what got left behind
* **Support and ops teams** diagnosing "I can't access my course" tickets without trawling the database

If you have ever exported your LearnDash content and found more lessons in the file than in your courses, this is the gap it measures.

= How it works =

1. Install and activate. The plugin appears under **LearnDash LMS → Structure Audit**.
2. Click **Run structure audit**. The scan is read-only and takes seconds on a typical site.
3. Work down the report, worst first. Expand any check to see exactly which courses, lessons, quizzes or groups are affected, each linked straight to its edit screen.

= Extending it =

Developers can register additional checks with the `rausa_checks` filter, so agencies running the same audit across many client sites can add their own house rules alongside the built-in twelve.

= Disclaimer =

This is an independent add-on. It is not affiliated with, endorsed by or sponsored by LearnDash or its owners. "LearnDash" is used here only to describe the software this plugin works with.

== Installation ==

1. Install and activate the plugin. LearnDash LMS must be active.
2. Go to **LearnDash LMS → Structure Audit** (or **Tools → Structure Audit**).
3. Click **Run structure audit**.

== Frequently Asked Questions ==

= How do I find orphaned lessons in LearnDash? =

Run the audit — orphaned lessons are one of the twelve checks. A lesson is orphaned when it exists as a post but is not attached to any course, which normally happens when a course is restructured or a lesson is removed from the builder rather than deleted. The report lists every one with a link to its edit screen, and offers an opt-in cleanup that moves them to the trash.

= How do I find LearnDash courses with no lessons? =

The "Courses with no content" check finds them. This is flagged as critical because a published course with no steps still accepts enrolments — learners land on it, see nothing, and open a support ticket.

= Why is a learner locked out of a course they are enrolled in? =

Usually one of three structural causes, and the audit checks all of them: the course is unpublished while enrolments still exist, a prerequisite course has been unpublished or deleted, or a step in the course points at a course that no longer exists. Each has its own check in the report.

= How do I find quizzes with no questions? =

It is one of the critical checks. An empty quiz still appears in the course outline and still has to be passed, so it stops learner progression completely while looking perfectly normal in the admin.

= How do I clean up unused quiz questions? =

The "Questions not used in any quiz" check lists every question in the question bank that no quiz references. It is a notice rather than an error, because a deliberately maintained question bank is a legitimate setup — the point is to show you the size of it so you can decide.

= Can I delete orphaned content safely? =

Cleanup moves items to the WordPress trash, so nothing is destroyed and everything is restorable from the normal Trash view until you empty it. The scan itself never removes anything; cleanup only runs when you click it.

= Will this change or delete anything on my site? =

Not on its own. The scan is entirely read-only. Cleanup actions only appear for orphaned content, are never automatic, and move items to the trash rather than deleting them.

= Does it work with LearnDash groups? =

Yes. Three of the checks cover groups — groups with no group leader (nobody can administer or report on them), groups with no courses (membership grants no access), and enrolment problems that surface through group course assignments.

= Which LearnDash versions are supported? =

LearnDash 3.x and 4.x. Every check calls LearnDash's own API behind a function check, so a version that doesn't provide a given function reports that check as skipped rather than failing.

= Why was a check skipped? =

Each check depends on a LearnDash function. If your LearnDash version doesn't provide it, the check is skipped and reported rather than causing an error. This keeps the plugin safe across LearnDash releases.

= Does it store anything in my database? =

No. No options, no custom tables, no transients and no scheduled tasks. The report is generated on demand and nothing is written, so removing the plugin leaves your database exactly as it was.

= I have a very large site. Will this time out? =

The scan examines up to 2,000 items per content type per run, which keeps it within normal PHP limits. Larger-site handling with background scanning is planned.

= "Courses with no certificate" is flagged but I don't use certificates. =

That check is a **notice**, not an error. It's listed so you can confirm the omission is intentional rather than an oversight.

= Does it conflict with other LearnDash add-ons? =

No. It only reads data — it doesn't modify LearnDash behaviour, register front-end output or alter course access, so it sits alongside other add-ons without conflict.

= Can I add my own checks? =

Yes. Register them with the `rausa_checks` filter and they appear in the report alongside the built-in checks, with the same severity grouping and item listing.

== Screenshots ==

1. The structure audit report, grouped by severity.
2. An individual check with its affected items.
3. Cleanup is opt-in and reversible — items are moved to the trash, with a confirmation of how many.

== Changelog ==

= 1.0.0 =
* Initial release: 12 structural checks, severity grouping, safe reversible cleanup for orphaned content, extensible check registry.

== Upgrade Notice ==

= 1.0.0 =
First release.
