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 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 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 tag, nothing to check return null; } // Get content before $before_define = substr($contents, 0, $define_pos); // Check for HTML comment opening $html_comment_pos = strpos($before_define, '', $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: ^^^^^^^^^^^ This gets parsed as: Component docblock Which is invalid JavaScript, causing: SyntaxError: Unexpected identifier 'docblock' SOLUTION: Use jqhtml comment syntax instead: WRONG: RIGHT: <%-- This is a docblock for my component --%> The <%-- --%> syntax is a true comment that is completely stripped before parsing. QUICK FIX: 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"; } }