qWeave - PL/SQL Embedded HTML/CSS/JS Linter

Intelligent linting and formatting for HTML, CSS, and JavaScript embedded in Oracle PL/SQL q-quote strings.

qWeave transforms your PL/SQL web procedures into a first-class development experience with real-time diagnostics, syntax highlighting, and formatting support.

🚀 Quick Start

Create a PL/SQL CLOB with embedded HTML:

DECLARE
  l_html CLOB := q'~
    <html>
      <head>
        <style>
          body { background: #f0f0f0; }
        </style>
      </head>
      <body>
        <h1>Hello World</h1>
        <script>
          console.log("Page loaded");
        </script>
      </body>
    </html>
  ~';
BEGIN
  htp.prn(l_html);
END;

Add PL/SQL injections anywhere in your HTML:

Inline Pattern (stays within q-quotes):

l_html CLOB := q'~<h1>Welcome q'~|| v_username ||~'!</h1>~';

Cross-boundary Pattern (breaks across quote boundaries):

l_html CLOB := q'~<input value="~'|| v_user_input ||q'~" required>~';

Get instant feedback:
- HTML validation (missing alt tags, invalid nesting, etc.)
- CSS linting (invalid properties, colors, vendor prefixes)
- JavaScript errors (undefined variables, syntax issues)
- Accessibility warnings
- Format Document support

✨ Features

🔍 Advanced Linting

HTML: Latest vscode-html-languageservice with accessibility checks
CSS: Stylelint 16.24+ with standard config and custom rules
JavaScript: ESLint 9.36+ with comprehensive rule set
Real-time: Diagnostics update as you type (300ms debounce)

🎨 Syntax Highlighting

Full PL/SQL syntax highlighting within HTML contexts
Supports both inline and cross-boundary injection patterns
TextMate grammar integration for seamless VS Code experience

🛠 Developer Tools

Format Document: Prettier formatting for embedded HTML
Virtual Document: Preview reconstructed HTML with placeholders
Quick Fixes: Convert between injection patterns
Copy Virtual: Export clean HTML for testing

⚙️ Configurable

Toggle individual linters (HTML/CSS/JS)
Advanced HTML checks (img alt, rel attributes, inline styles)
Custom ESLint rules and source type (script/module)
Project config support (Stylelint/ESLint)

📖 PL/SQL Injection Patterns

qWeave supports two distinct injection patterns, each designed for specific use cases:

Pattern 1: Inline Injections - `q'~|| expression ||~'`

Purpose: Inject PL/SQL within an existing q-quote literal
Best for: Text content, complete values
How it works: The q'~|| ||~' stays inside the outer q'~ ~' boundary

-- ✅ INLINE: Stays within the same q-quote
l_html CLOB := q'~
  <div>
    <h1>Welcome q'~|| v_username ||~'!</h1>
    <p>Today is q'~|| TO_CHAR(SYSDATE, 'DD-MON-YYYY') ||~'</p>
    <span>Records: q'~|| v_record_count ||~'</span>
  </div>
~';

Pattern 2: Cross-boundary Injections - `~'|| expression ||q'~`

Purpose: Break out of q-quote, inject PL/SQL, then resume q-quote
Best for: Attribute values, partial content, complex scenarios
How it works:

~' ENDS the current q-quote
|| expression || injects PL/SQL code
q'~ STARTS a new q-quote

-- ✅ CROSS-BOUNDARY: Breaks across quote boundaries
l_html CLOB := q'~
  <input type="text" 
         name="username"
         value="~'|| v_current_value ||q'~" 
         data-user-id="~'|| v_user.id ||q'~"
         class="form-control">
  <img src="~'|| v_avatar_url ||q'~" 
       alt="~'|| v_user.display_name ||q'~">
~';

Why Different Patterns?

Inline Pattern (q'~|| ||~'):

Keeps everything within one string boundary
Clean for text content and simple values
Easy to read: "insert this PL/SQL here"

Cross-boundary Pattern (~'|| ||q'~):

Allows breaking string boundaries for complex scenarios
Perfect for HTML attributes that need dynamic values
Visual clarity: "end string → inject PL/SQL → start new string"

Pattern 3: Mixed Usage

Combine both patterns in the same HTML block for maximum flexibility:

l_html CLOB := q'~
  <div class="user-card" 
       data-id="~'|| v_user.id ||q'~"
       data-role="~'|| v_user.role ||q'~">
    <h2>Hello q'~|| v_user.display_name ||~'!</h2>
    <p>Last login: q'~|| v_user.last_login_formatted ||~'</p>
    <img src="~'|| v_user.avatar_url ||q'~" 
         alt="Avatar for q'~|| v_user.display_name ||~'">
  </div>
~';

Quick Reference

Pattern	Syntax	Use Case	Example
Inline	`q'~\\\|\\\| expr \\\|\\\|~'`	Text content, simple values	`<h1>q'~\\\|\\\| v_title \\\|\\\|~'</h1>`
Cross-boundary	`~'\\\|\\\| expr \\\|\\\|q'~`	Attributes, complex injections	`<div id="~'\\\|\\\| v_id \\\|\\\|q'~">`

🎯 Commands & Usage

Command	Description	Shortcut
Open Virtual Document	Preview reconstructed HTML	Command Palette
Copy Virtual HTML	Copy clean HTML to clipboard	Command Palette
Run Lint Now	Force immediate re-analysis	Command Palette
Format Document	Format embedded HTML with Prettier	Alt+Shift+F
**Inline to q'~\	\	… \	\	~'**	Quick Fix for injection patterns	Ctrl+.

⚙️ Configuration

Access via VS Code Settings → Extensions → qWeave:

Core Settings

qWeave.enableHtml: Enable HTML diagnostics (default: true)
qWeave.enableCss: Enable CSS diagnostics (default: true)
qWeave.enableJs: Enable JavaScript diagnostics (default: true)
qWeave.debounceMs: Analysis delay in milliseconds (default: 300)

Advanced HTML Checks

qWeave.htmlAdvanced.imgAltRequired: Require alt attributes on images (default: true)
qWeave.htmlAdvanced.anchorRelForTargetBlank: Require rel="noopener noreferrer" for target="_blank" (default: true)
qWeave.htmlAdvanced.noInlineStyle: Warn on inline style attributes (default: false)

Linter Configuration

qWeave.useStylelintRc: Use project Stylelint config (default: true)
qWeave.useEslintRc: Use project ESLint config (default: true)
qWeave.eslintRules: Additional ESLint rules object (default: {})
qWeave.jsSourceType: Parse as "script" or "module" (default: "script")

🔧 How It Works

Detection: Scans for variable CLOB := q'~...~'; patterns
Parsing: Extracts literal HTML and dynamic PL/SQL segments
Reconstruction: Builds virtual HTML with safe placeholders
Analysis: Runs HTML/CSS/JS linters on virtual document
Mapping: Maps diagnostics back to original PL/SQL positions
Display: Shows errors/warnings directly in your PL/SQL file

🎨 Syntax Highlighting

qWeave provides rich syntax highlighting for:

HTML structure within q-quotes
CSS in <style> blocks
JavaScript in <script> blocks
PL/SQL expressions in both injection patterns
Proper scoping and context-aware highlighting

📋 Requirements

VS Code: 1.84 or higher
File Types: .sql, .pls, .plsql, .pks, .pkb, .pkg, .bdy
Language Mode: PL/SQL or SQL

🐛 Troubleshooting

No diagnostics appearing?

Ensure file language is set to "PL/SQL" or "SQL"
Check that your CLOB starts with variable CLOB := q'~
Run "qWeave: Run Lint Now" to force analysis

Syntax highlighting not working?

Reload VS Code window after installation
Verify file extension is recognized (.sql, .plsql, etc.)

Format Document not available?

Set qWeave as default formatter in Settings
Or use Command Palette → "Format Document With..." → qWeave

📄 License

MIT License - see LICENSE file for details.

Made for Oracle PL/SQL developers who build web applications with embedded HTML/CSS/JavaScript.

qWeave

Carbon-Flux

qWeave - PL/SQL Embedded HTML/CSS/JS Linter

🚀 Quick Start

✨ Features

🔍 Advanced Linting

🎨 Syntax Highlighting

🛠 Developer Tools

⚙️ Configurable

📖 PL/SQL Injection Patterns

Pattern 1: Inline Injections - q'~|| expression ||~'

Pattern 2: Cross-boundary Injections - ~'|| expression ||q'~

Why Different Patterns?

Pattern 3: Mixed Usage

Quick Reference

🎯 Commands & Usage

⚙️ Configuration

Core Settings

Advanced HTML Checks

Linter Configuration

🔧 How It Works

🎨 Syntax Highlighting

📋 Requirements

🐛 Troubleshooting

📄 License

Pattern 1: Inline Injections - `q'~|| expression ||~'`

Pattern 2: Cross-boundary Injections - `~'|| expression ||q'~`