Skip to content

Fix: FK reading grade of 0 < x < 1 collapses to 0 (normalize to 1) #1725

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pattonwebz merged 3 commits into from
Jul 8, 2026
Merged

Fix: FK reading grade of 0 < x < 1 collapses to 0 (normalize to 1) #1725

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a3d0cff
Fix: normalize FK grade values in (0,1) to 1 instead of collapsing to 0
SteveJonesDev May 28, 2026
dfa89d2
Fix: handle false/null from TextStatistics in edac_normalize_fk_grade
pattonwebz Jun 27, 2026
e616ede
chore: use x.x.x placeholder for @since tags on new function
pattonwebz Jun 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions admin/class-ajax.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ public function summary() {
$simplified_summary_grade = 0;
if ( class_exists( 'DaveChild\TextStatistics\TextStatistics' ) ) {
$text_statistics = new \DaveChild\TextStatistics\TextStatistics();
$simplified_summary_grade = (int) floor( $text_statistics->fleschKincaidGradeLevel( $simplified_summary ) );
$simplified_summary_grade = edac_normalize_fk_grade( $text_statistics->fleschKincaidGradeLevel( $simplified_summary ) );
}
$simplified_summary_grade_failed = ( $simplified_summary_grade > 9 ) ? true : false;

Expand Down Expand Up @@ -671,7 +671,7 @@ public function readability() {
$simplified_summary_grade = 0;
if ( class_exists( 'DaveChild\TextStatistics\TextStatistics' ) ) {
$text_statistics = new \DaveChild\TextStatistics\TextStatistics();
$simplified_summary_grade = (int) floor( $text_statistics->fleschKincaidGradeLevel( $simplified_summary ) );
$simplified_summary_grade = edac_normalize_fk_grade( $text_statistics->fleschKincaidGradeLevel( $simplified_summary ) );
}

$simplified_summary_grade_failed = ( $simplified_summary_grade > 9 ) ? true : false;
Expand Down
2 changes: 1 addition & 1 deletion includes/classes/class-rest-api.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1077,7 +1077,7 @@ private function get_readability_data( $post_id ) {
$simplified_summary_grade = 0;
if ( class_exists( 'DaveChild\TextStatistics\TextStatistics' ) ) {
$text_statistics = new \DaveChild\TextStatistics\TextStatistics();
$simplified_summary_grade = (int) floor( $text_statistics->fleschKincaidGradeLevel( $simplified_summary ) );
$simplified_summary_grade = edac_normalize_fk_grade( $text_statistics->fleschKincaidGradeLevel( $simplified_summary ) );
}

$simplified_summary_grade_failed = $simplified_summary_grade >= 9;
Comment on lines +1080 to 1083

@coderabbitai coderabbitai Bot May 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Align REST failure threshold with “above 9th grade” semantics.

Line 1083 uses >= 9, which treats exactly 9th grade as failed. That conflicts with the “above 9th grade” behavior used in other updated paths, so REST/sidebar can disagree with AJAX for grade 9.

Proposed fix 
-		$simplified_summary_grade_failed      = $simplified_summary_grade >= 9;
+		$simplified_summary_grade_failed      = $simplified_summary_grade > 9;
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
$simplified_summary_grade = edac_normalize_fk_grade( $text_statistics->fleschKincaidGradeLevel( $simplified_summary ) );
}
$simplified_summary_grade_failed = $simplified_summary_grade >= 9;
$simplified_summary_grade = edac_normalize_fk_grade( $text_statistics->fleschKincaidGradeLevel( $simplified_summary ) );
}
$simplified_summary_grade_failed = $simplified_summary_grade > 9;
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@includes/classes/class-rest-api.php` around lines 1080 - 1083, The REST path
incorrectly marks exactly 9th grade as failing by setting
$simplified_summary_grade_failed with the condition "$simplified_summary_grade
>= 9"; change the threshold to strictly greater-than so it matches the “above
9th grade” semantics used elsewhere (i.e. use "$simplified_summary_grade > 9").
Update the assignment that computes $simplified_summary_grade_failed (after
edac_normalize_fk_grade( $text_statistics->fleschKincaidGradeLevel(
$simplified_summary ) )) to use the > operator so REST/sidebar agrees with the
AJAX path.

@pattonwebz pattonwebz Jun 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intentionally not addressing this in PR #1725 — we've opened a dedicated issue #1797 to fix all the inconsistent grade-9 thresholds across the codebase (including this one and the class-ajax.php:669 case) with proper references to WCAG 3.1.5.

@coderabbitai coderabbitai Bot Jun 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pattonwebz Understood — thanks for clarifying. Deferring this from #1725 and handling the grade-9 threshold consistency work in #1797 makes sense, especially if you want to align all affected paths together with the WCAG 3.1.5 rationale. I’m good to leave this out of the current PR.

Expand Down
4 changes: 1 addition & 3 deletions includes/classes/class-summary-generator.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,9 +290,7 @@ private function calculate_content_grade() {
$content_grade = 0;

if ( class_exists( 'DaveChild\TextStatistics\TextStatistics' ) ) {
$content_grade = floor(
( new \DaveChild\TextStatistics\TextStatistics() )->fleschKincaidGradeLevel( $content )
);
$content_grade = edac_normalize_fk_grade( ( new \DaveChild\TextStatistics\TextStatistics() )->fleschKincaidGradeLevel( $content ) );
}

return (int) round( $content_grade );
Expand Down
21 changes: 21 additions & 0 deletions includes/helper-functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -940,6 +940,27 @@ function edac_format_datetime_from_utc( string $utc_datetime ): string {
return wp_date( $format, $timestamp );
}

/**
* Normalize a raw Flesch-Kincaid grade level float to a whole-number grade.
*
* `floor()` alone collapses any FK value in (0, 1) to 0, which misrepresents
* very simple content as "not calculable." Values above 0 but below 1 are
* normalized to 1 so that compliance checks treat them correctly.
*
* @since x.x.x
*
* @param float|bool|null $fk_grade Raw Flesch-Kincaid grade level returned by the library.
* @return int Normalized grade: 0 when the library returned 0, false, or null (not enough content),
* otherwise max(1, floor($fk_grade)).
*/
function edac_normalize_fk_grade( $fk_grade ): int {
$fk_grade = (float) $fk_grade;
if ( $fk_grade <= 0 ) {
return 0;
}
return max( 1, (int) floor( $fk_grade ) );
}

/**
* Determine the icon name to display for the readability panel.
*
Expand Down
51 changes: 51 additions & 0 deletions tests/phpunit/helper-functions/NormalizeFkGradeTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
<?php
/**
* Tests for the edac_normalize_fk_grade helper.
*
* @package Accessibility_Checker
* @since x.x.x
*/

/**
* Tests for edac_normalize_fk_grade.
*
* @covers ::edac_normalize_fk_grade
* @since x.x.x
*/
class NormalizeFkGradeTest extends WP_UnitTestCase {

/**
* Verifies FK grade normalization for the given input/expected pair.
*
* @dataProvider data_normalize_fk_grade
*
* @param float|bool|null $input Raw FK grade value (float, or false/null from the library on empty content).
* @param int $expected Expected normalized integer grade.
*/
public function test_normalize_fk_grade( $input, int $expected ) {
$this->assertSame( $expected, edac_normalize_fk_grade( $input ) );
}

/**
* Data provider for test_normalize_fk_grade.
*
* @return array<string, array{mixed, int}>
*/
public static function data_normalize_fk_grade(): array {
return [
'zero stays zero' => [ 0.0, 0 ],
'negative stays zero' => [ -1.5, 0 ],
'fractional above zero is 1' => [ 0.01, 1 ],
'mid-fraction is 1' => [ 0.5, 1 ],
'just below 1.0 is 1' => [ 0.99, 1 ],
'exactly 1.0 is 1' => [ 1.0, 1 ],
'1.9 floors to 1' => [ 1.9, 1 ],
'9.0 is 9' => [ 9.0, 9 ],
'9.9 floors to 9' => [ 9.9, 9 ],
'10.0 is 10' => [ 10.0, 10 ],
'whole grade passes through' => [ 5.0, 5 ],
'false returns zero' => [ false, 0 ],
'null returns zero' => [ null, 0 ],
];
}
Comment thread
pattonwebz marked this conversation as resolved.
}
Loading