GitHub v1.3.1

Self-Healing Code & Diagnostics

Guide

Learn how Coralite's AI self-healing compiler loop, static AST diagnostics, and deterministic auto-fixers deliver zero-defect web components and automated CI code auditing.

Coralite provides a comprehensive, AI-assisted self-healing diagnostic and AST auto-fixing engine designed to maintain zero-defect codebases across Web Components, Plugins, and Page templates.

AI Agent Ready: Coralite's diagnostic engine emits 4-part codeframes with exact source ranges and structural auto-fix actions, enabling AI pair-programming assistants to self-correct invalid code in a single turn.

1. The Self-Healing Compiler Loop

The static analysis engine operates in a deterministic 4-stage self-healing compiler loop:

  1. Static Audit: Scans component templates, PostCSS stylesheets, JS AST blocks, and plugin definitions.
  2. Diagnostic Emission: Identifies structural violations, CSP anti-patterns, serialization leaks, and dead code, mapping them to explicit diagnostic codes (`CORALITE-E*`, `CORALITE-P*`, `CORALITE-PAGE-*`).
  3. AST Auto-Fixer: Applies 1-shot AST transformations (expression lifting to getters, dynamic client import rewriting, single-candidate ref injection, default stripping, and Two-Phase plugin currying).
  4. Post-Fix Re-audit: Re-evaluates modified source files to guarantee that zero errors remain and no regressions were introduced.

2. Comprehensive Diagnostic Catalog

Component Diagnostics (CORALITE-E101 – E304, W401 – W402)

Audits template syntax, script block boundaries, slot signatures, and state reactivity rules.

  • CORALITE-E101 (Attribute Schema): Non-primitive Array or Object constructor in attribute schema. (Auto-fix action: remove_attribute)
  • CORALITE-E102 (Attribute Schema): Mutex violation: required: true combined with default value. (Auto-fix action: strip_default)
  • CORALITE-E103 (Attribute Schema): Async transform or validate function. Attribute handlers must be strictly synchronous.
  • CORALITE-E104 (Attribute/Server): Collision with reserved context keys (state, observe, signal, root, refs, instanceId, emit).
  • CORALITE-E109 (CSS Import Boundary): Static top-level .css import, dynamic .css import outside client(), or unsupported CSS import options. Load stylesheets lazily inside client() via await import('*.css', options).
  • CORALITE-E201 (Template Syntax): Complex non-identifier expression inside template interpolation (e.g. {{ count + 1 }}). Synthesizes getter automatically. (Auto-fix action: lift_to_getter)
  • CORALITE-E202 (Ref Resolution): refs('name') call referencing missing template ref. Injects ref if exactly 1 candidate element exists. (Auto-fix action: inject_ref)
  • CORALITE-E203 (CSP Violation): Inline event listener attribute (onclick="...") inside template violating CSP standards. (Auto-fix action: strips inline listener)
  • CORALITE-E301 (Serialization Boundary): Client block referencing top-level static ES import. Rewrites to dynamic await import(...) inside client() while preserving shared SSR static imports. (Auto-fix action: dynamic_import)
  • CORALITE-E302 (Reactivity Loop): Direct state assignment inside observe(...) callback causing infinite reactivity loops.
  • CORALITE-E303 (Style Block): Asynchronous getter function in style: { ... } block. Style getters must be strictly synchronous.
  • CORALITE-E304 (Client Boundary): Node runtime global (process, Buffer, setImmediate, ...) referenced inside client(). Web-platform globals shared with the browser (console, fetch, URL, crypto, ...) are allowed. Fetch build-time data in server() or paths() and pass it through state.
  • CORALITE-W401 (Dead Code Warning): Unused component getter, server state property, or attribute declaration.
  • CORALITE-W402 (Dead Code Warning): Unused element ref="..." declaration.
  • CORALITE-E403 (Stylesheet Resolution): Missing or unresolvable local or bare-package .css specifier in a dynamic import() call.

Plugin Diagnostics (CORALITE-P101 – P401)

Audits plugin contracts, lifecycle hooks, and isomorphic client boundary serialization.

  • CORALITE-P101 (Plugin Contract): Missing or empty name property in plugin definition.
  • CORALITE-P102 (Plugin Contract): Reserved core plugin name collision (e.g. metadata, refs, static-assets, testing).
  • CORALITE-P201 (Architecture): Single-phase context function. Must use Two-Phase curried resolver (pluginContext) => (instanceContext) => ({ ... }). (Auto-fix action: wrap_two_phase_context)
  • CORALITE-P202 (Lifecycle Hook): Server build hook is not a valid function.
  • CORALITE-P203 (Isomorphic Boundary): Server module import (e.g. node:fs) inside client plugin block.
  • CORALITE-P301 (Serialization Boundary): Client function referencing outer module-scope variable (outer variable leak).
  • CORALITE-P302 (Serialization Boundary): Non-serializable client.config object (contains functions or non-JSON primitives).
  • CORALITE-P303 (Lifecycle Hook): Client runtime hook is not a valid function.
  • CORALITE-P401 (Plugin Contract): Missing definePlugin(...) wrapper call around exported object. (Auto-fix action: wrap_define_plugin)

Page Document Diagnostics (CORALITE-PAGE-101 – 201)

Audits HTML page documents against component schemas and encapsulation rules.

  • CORALITE-PAGE-101 (Custom Element): Unknown custom element tag found on page. Emits Levenshtein fuzzy match suggestions for registered components.
  • CORALITE-PAGE-102 (Required Attribute): Page tag missing required component attribute (required: true). (Auto-fix action: add_required_attribute)
  • CORALITE-PAGE-201 (Encapsulation Violation): Page inline <script> attempting to query or mutate internal component DOM via compound descendant selectors or direct attribute mutations.

3. Automated AST Auto-Fixing (--fix & --dry-run)

Execute 1-shot AST auto-fixing across your workspace using `coralite fix` or domain-specific commands:

bash
Code copied!
  # Auto-fix all workspace components, pages, and plugins
          coralite fix
  
          # Preview proposed fixes in unified colorized diff format without modifying disk
          coralite fix --dry-run
  
          # Migrate page definePage({ ... }) configuration to flat named exports
          coralite fix --migrate-pages
  
          # Auto-fix components directly
          coralite validate-components --fix

4. AI Pair-Programming with init-agent

Scaffold zero-token rule files for AI coding assistants (Claude Code, Cursor, GitHub Copilot) to prevent hallucinations and ensure code compliance from the first prompt:

bash
Code copied!
  # Scaffold AGENTS.md in repo root
          coralite init-agent
  
          # Scaffold AGENTS.md plus .cursor/rules/coralite.mdc and .claude/AGENTS.md
          coralite init-agent --cursor --claude

5. Strict CI Quality Gates

Integrate Coralite's strict audit into your continuous integration pipeline to guarantee zero warnings or dead code in production builds:

bash
Code copied!
  # Strict workspace check (fails build if any errors or unused symbols exist)
          coralite check --strict --coverage