Add JQHTML-COMMENT-01 code quality rule and fix existing violations
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
root
166
app/RSpade/CodeQuality/Rules/Jqhtml/JqhtmlHtmlComment_CodeQualityRule.php
Executable file
166
app/RSpade/CodeQuality/Rules/Jqhtml/JqhtmlHtmlComment_CodeQualityRule.php
Executable file
@@ -0,0 +1,166 @@
|
||||
<?php
|
||||
|
||||
namespace App\RSpade\CodeQuality\Rules\Jqhtml;
|
||||
|
||||
use App\RSpade\CodeQuality\Rules\CodeQualityRule_Abstract;
|
||||
|
||||
/**
|
||||
* JqhtmlHtmlCommentRule - Detects HTML comments used before <Define> in jqhtml files
|
||||
*
|
||||
* Catches the common mistake of using <!-- --> comments for docblocks instead of
|
||||
* the correct <%-- --%> jqhtml comment syntax. HTML comments in jqhtml files
|
||||
* still have their contents parsed as JavaScript, causing cryptic errors.
|
||||
*/
|
||||
class JqhtmlHtmlComment_CodeQualityRule extends CodeQualityRule_Abstract
|
||||
{
|
||||
public function get_id(): string
|
||||
{
|
||||
return 'JQHTML-COMMENT-01';
|
||||
}
|
||||
|
||||
public function get_name(): string
|
||||
{
|
||||
return 'Jqhtml HTML Comment Detection';
|
||||
}
|
||||
|
||||
public function get_description(): string
|
||||
{
|
||||
return 'Detects HTML comments (<!-- -->) used before <Define> tag - must use <%-- --%> syntax';
|
||||
}
|
||||
|
||||
public function get_file_patterns(): array
|
||||
{
|
||||
return ['*.jqhtml'];
|
||||
}
|
||||
|
||||
public function get_default_severity(): string
|
||||
{
|
||||
return 'critical';
|
||||
}
|
||||
|
||||
/**
|
||||
* Run during manifest scan for immediate feedback on this common mistake.
|
||||
*
|
||||
* EXCEPTION: This rule has been explicitly approved to run at manifest-time because
|
||||
* HTML comments before <Define> cause cryptic JavaScript parsing errors that are
|
||||
* extremely difficult to debug. Catching this early prevents developer confusion.
|
||||
*/
|
||||
public function is_called_during_manifest_scan(): bool
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Process file during manifest update to detect HTML comments used as docblocks
|
||||
*
|
||||
* Only flags HTML comments that appear BEFORE any jqhtml comment starts.
|
||||
* HTML comments inside jqhtml comments (<%-- ... --%>) are safe - they're
|
||||
* documentation/examples and will be stripped with the jqhtml comment.
|
||||
*/
|
||||
public function on_manifest_file_update(string $file_path, string $contents, array $metadata = []): ?array
|
||||
{
|
||||
// Find the position of first <Define: tag
|
||||
$define_pos = strpos($contents, '<Define:');
|
||||
if ($define_pos === false) {
|
||||
// No <Define> tag, nothing to check
|
||||
return null;
|
||||
}
|
||||
|
||||
// Get content before <Define>
|
||||
$before_define = substr($contents, 0, $define_pos);
|
||||
|
||||
// Check for HTML comment opening
|
||||
$html_comment_pos = strpos($before_define, '<!--');
|
||||
if ($html_comment_pos === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Check for jqhtml comment opening
|
||||
$jqhtml_comment_pos = strpos($before_define, '<%--');
|
||||
|
||||
// If jqhtml comment starts BEFORE the HTML comment, then the HTML comment
|
||||
// is inside the jqhtml comment block (documentation/example) and is safe
|
||||
if ($jqhtml_comment_pos !== false && $jqhtml_comment_pos < $html_comment_pos) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Found HTML comment before any jqhtml comment - this is the docblock mistake
|
||||
$line_number = substr_count(substr($contents, 0, $html_comment_pos), "\n") + 1;
|
||||
|
||||
// Extract the comment content for the error message
|
||||
$comment_end = strpos($contents, '-->', $html_comment_pos);
|
||||
$comment_text = $comment_end !== false
|
||||
? substr($contents, $html_comment_pos, min($comment_end - $html_comment_pos + 3, 100))
|
||||
: substr($contents, $html_comment_pos, 50);
|
||||
|
||||
return [
|
||||
'html_comment_violation' => [
|
||||
'line' => $line_number,
|
||||
'code' => trim($comment_text),
|
||||
],
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* Check jqhtml file for HTML comment violations stored in metadata
|
||||
*/
|
||||
public function check(string $file_path, string $contents, array $metadata = []): void
|
||||
{
|
||||
// Check for violations in code quality metadata
|
||||
if (!isset($metadata['code_quality_metadata']['JQHTML-COMMENT-01']['html_comment_violation'])) {
|
||||
return;
|
||||
}
|
||||
|
||||
$violation = $metadata['code_quality_metadata']['JQHTML-COMMENT-01']['html_comment_violation'];
|
||||
|
||||
$error_message = "Code Quality Violation (JQHTML-COMMENT-01) - HTML Comment in Jqhtml File\n\n";
|
||||
$error_message .= "CRITICAL: HTML comments (<!-- -->) are NOT safe for docblocks in .jqhtml files.\n\n";
|
||||
$error_message .= "File: {$file_path}\n";
|
||||
$error_message .= "Line: {$violation['line']}\n";
|
||||
$error_message .= "Code: {$violation['code']}\n\n";
|
||||
$error_message .= $this->get_remediation();
|
||||
|
||||
throw new \App\RSpade\CodeQuality\RuntimeChecks\YoureDoingItWrongException(
|
||||
$error_message,
|
||||
0,
|
||||
null,
|
||||
base_path($file_path),
|
||||
$violation['line']
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get remediation instructions
|
||||
*/
|
||||
private function get_remediation(): string
|
||||
{
|
||||
return "PROBLEM: HTML comments in jqhtml files still have their contents parsed as JavaScript.
|
||||
This causes cryptic syntax errors because the template engine processes everything inside <!-- -->.
|
||||
|
||||
EXAMPLE OF THE BUG:
|
||||
<!-- Component docblock -->
|
||||
^^^^^^^^^^^
|
||||
This gets parsed as: Component docblock
|
||||
Which is invalid JavaScript, causing: SyntaxError: Unexpected identifier 'docblock'
|
||||
|
||||
SOLUTION: Use jqhtml comment syntax instead:
|
||||
|
||||
WRONG: <!-- This is a docblock for my component -->
|
||||
RIGHT: <%-- This is a docblock for my component --%>
|
||||
|
||||
The <%-- --%> syntax is a true comment that is completely stripped before parsing.
|
||||
|
||||
QUICK FIX:
|
||||
Find: <!--
|
||||
Replace: <%--
|
||||
|
||||
Find: -->
|
||||
Replace: --%>
|
||||
|
||||
WHY THIS MATTERS:
|
||||
- HTML comments are NOT comments in jqhtml - their contents are parsed
|
||||
- This causes confusing 'Unexpected identifier' or 'Unexpected token' errors
|
||||
- The error messages don't indicate the real problem (using wrong comment syntax)
|
||||
- Developers waste time debugging JavaScript when the fix is just changing comment delimiters";
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user