faces-review
Review Jakarta Faces code for common mistakes, anti-patterns, and rule violations
SKILL.md.claude/skills/faces-review/SKILL.md
GitHubVersion 1.8.0
Review the Jakarta Faces code in $ARGUMENTS (if no argument, scan the project for .xhtml and backing bean files) against the rules in .claude/faces/rules.md and its topic files.
Step 1: Determine the Faces Version
Before reviewing anything, establish BOTH Faces versions — they are not per definition the same. See "Version Discipline" in .claude/faces/rules.md.
Runtime version (which APIs exist), in this order:
- An explicit
jakarta.faces-api/javax.facesdependency, or a bundled Faces implementation (org.glassfish:jakarta.facesfor Mojarra up to 4.x,org.glassfish.mojarra:mojarrafor Mojarra 5.0+,org.apache.myfaces.core:myfaces-implfor MyFaces) — whose major.minor tracks the Faces version it implements. - Otherwise the
jakarta.jakartaee-api/jakarta.jakartaee-web-apiversion, mapped via the version lineage in.claude/faces/rules.md(full Jakarta EE server only). - Otherwise the target application server, or as a last resort the XML namespaces used in the
.xhtmlfiles.
Declared version (which descriptor schema applies): the version attribute and xsi:schemaLocation of faces-config.xml — see the Configuration checklist below.
State both at the top of the report, with how each was detected. If the runtime version cannot be determined, say so and assume the most recent RELEASED version (Faces 4.1) — never assume an unreleased one. Never substitute the declared version for the runtime version.
Then hold every suggestion to the runtime version:
- Verify an API before recommending it, against the sources listed under "References" in
.claude/faces/rules.md, using the set for the detected runtime version — this skill has no web access, so delegate the lookup to anAgent. If it cannot be verified, do not recommend it; report the API as unconfirmed instead. - A genuinely useful newer API may be mentioned only as
infoseverity, explicitly labelled with the version that introduces it and the fact that it requires an upgrade. It is never anerrororwarning.
Finally, establish the project's MARKUP STYLE the same way — plain Faces components (<h:inputText>) or passthrough elements (<input type="text" faces:value="...">) — by taking the dominant one across the .xhtml files. Both are valid; see "Passthrough Elements" in .claude/faces/rules.md. When there is no dominant style, as in a new or empty project, default to plain Faces components.
- Write every suggestion in the detected style. Do not nudge a project toward the other one.
- Report a view that mixes both as
info, never aserrororwarning. - NEVER propose a wholesale conversion from one style to the other, and never as a "modernisation". Some components have no passthrough element form at all, so such a conversion can only ever be partial, which is worse than either style consistently applied.
Step 2: Review Checklist
For every non-trivial construct, ask in this order: (1) is it still needed, or does a built-in already do this? (2) is the mechanism available in the detected runtime version? (3) is it implemented correctly? Report at the highest level that fires and stop — NEVER propose modernising something you would delete.
Superseded Constructs
Hand-rolled code that a built-in has since replaced. Report info when it merely duplicates the built-in, warning when the hand-rolled version has a defect the built-in does not. The replacement MUST exist in the detected runtime version. Suggest a plain Faces replacement; only propose an OmniFaces one when the project already depends on OmniFaces.
| Hand-rolled | Built-in | Since |
|---|---|---|
PhaseListener shuttling FacesMessages through the session to survive a redirect |
navigation from <f:viewAction>, which keeps them automatically; else Flash.setKeepMessages(true) at the redirecting call site |
2.2 |
immediate="true" on an ajax UICommand to skip input processing |
<f:ajax> — execute already defaults to @this; on a PrimeFaces command, process="@this" |
2.0 |
isPostback() guard in @PostConstruct for GET-only initialization |
<f:viewAction> |
2.2 |
| Custom converter for a standard type | implicit converters (incl. UUID since 4.1) |
varies |
Application.evaluateExpressionGet() calls |
@Inject @ManagedProperty |
2.3 |
| Hand-rolled server push (one-way, server to client) | <f:websocket>/<o:socket>, or <o:sse> |
Faces 2.3 / OmniFaces 5.2 |
A PhaseListener calling Flash.setKeepMessages(true) on every postback is not a fix for the first row: the flash saves the messages whether or not the response is a redirect, so they are rendered again on the next request and keep echoing forward. A NavigationHandler decorator checking NavigationCase.isRedirect() is sound but is global machinery for a rare case.
Two notes on immediate="true". On a non-ajax command it is still the mechanism, but ask first whether the command should be ajax at all — converting it drops the need entirely on a standard UICommand, and on a PrimeFaces command only together with process="@this", which is not its default; only a command that genuinely must not use ajax (e.g. a file download) is left needing it. On a UIInput it means something else entirely — conversion and validation move to Apply Request Values — so it must never be stripped mechanically.
Because these findings are the most prone to false positives, each one MUST state what the built-in covers and confirm nothing else is lost. If the construct does more than the built-in, report info naming the difference — never as a fix-this.
XHTML / Facelets
- XML namespaces match the project's Faces version. A namespace outside the standard ones is invalid only when nothing registers it — check for a
@FacesComponent(createTag = true)class, a*.taglib.xml, a composite library and third-party dependencies first, and report a namespace that resolves but that no tag uses asinfo, neverwarning/error.jakarta.faces.componentandhttp://xmlns.jcp.org/jsf/componentboth resolve on Faces 4.0+, so neither is a broken reference; an@FacesComponentthat pins the old one while the page uses the new one IS broken and is anerror— see "XML Namespaces" in.claude/faces/rules.md. - HTML5 doctype
<!DOCTYPE html>is used, not XHTML doctype. - No "god form", no nested
UIForm, andUIInput/UICommandcomponents are inside aUIForm— see "Component Rules" in.claude/faces/rules.md. - Every
UIInputhas a correspondingUIMessage. A<h:message for>naming a composite component does NOT count for the input inside it — it resolves to the composite's own client id and stays empty; report it as anerrorunless the composite already carries its own message in<cc:implementation>, or its<cc:interface componentType>backing component extendsUIInput, which makes the composite itself the input andfor="compositeId"correct.<p:message for>/<p:messages for>naming a composite does count, but only on PrimeFaces 14.0.0+ and only for the first input inside it; on PrimeFaces 13 and older, report it exactly as<h:message>— see "Component Rules" in.claude/faces/rules.md. - A catch-all
UIMessageswithredisplay="false"exists in each view; when using ajax, its ID is covered byrender/update. - Conditionally rendered components that are ajax-updated are wrapped in an always-rendered container, and ajax updates target the wrapper ID.
- A
<h:panelGroup>whose only attribute isrenderedemits no element at all and reads as<ui:fragment rendered="...">; when it wraps a single component,renderedbelongs on that component and the wrapper goes. Reportinfo. Neither rewrite applies inside<h:panelGrid>, where the wrapper is a cell, nor to a wrapper that is an ajaxrender/updatetarget, which needs the element it emits — see "Facelets Rules" in.claude/faces/rules.md. NamingContainer,UIInputandUICommandcomponents have explicit IDs (no generated IDs); IDs follow naming convention (property name forvalue, method name foraction, view ID name for forms/panels).bindingis not used for data binding;bindingis only used on page-scoped variables for component cross-referencing within the same view.- Ajax
render/updatereferences acrossNamingContainerboundaries use full client ID with leading colon. - JSTL tags are only used for build-time view construction, not for conditional rendering (use
renderedattribute instead). - No inline styles; CSS is in separate files.
- Resources are referenced via
<h:outputScript>,<h:outputStylesheet>,<h:graphicImage>, or#{resource[]}, never by a hardcoded path; a hardcoded path bypasses anyResourceHandler, including those possibly adding cache busting. - No duplicate/copy-pasted XHTML blocks; reusable code is in templates, includes, tag files, or composite components.
- File download commands do not use ajax (or use
<p:fileDownload>if PrimeFaces).
Directory Structure
Run this over every .xhtml OUTSIDE /WEB-INF/, before reporting on what any of them contain. It is a check on WHERE each file is, so a file whose contents are flawless still fails it — passing the XHTML checklist above is not grounds for clearing a file here, and a report that clears an .xhtml outside /WEB-INF/ without naming its kind has skipped this section.
Classify each one, because the webapp root is the correct home for exactly one kind:
| Kind | How to recognize it | Verdict |
|---|---|---|
| View | none of the below — a page a user navigates to | correct where it is |
| Template | contains <ui:insert>, or another file points template= at it |
error |
| Include | another file points <ui:include src=> at it |
error |
| Tag file | declared in a *.taglib.xml |
error |
| Composite | contains <cc:interface> — that alone is the marker; the root is usually <ui:component> but <ui:composition> is equally valid, so never key recognition off the root element |
warning |
| Asset (script, style, image, font) | not .xhtml; under the resources directory |
warning |
The severities differ because the fixes do. Moving a template, include or tag file into /WEB-INF/ needs no configuration — only the template/src references to it have to follow. Moving a composite or asset has TWO halves, and either alone breaks the application: move the files into /WEB-INF/resources/ AND set jakarta.faces.WEBAPP_RESOURCES_DIRECTORY to WEB-INF/resources. Name both in the fix.
State the exposure from the FacesServlet mapping rather than assuming source disclosure:
- Mapped to
*.xhtml(the recommended mapping): the file is processed, not served, so the source does NOT leak. What is reachable is the file rendered standalone at its own URL, outside the view that was meant to supply itsui:paramvalues orcc.attrs, itsf:metadata, and its access checks. - Mapped only to a legacy pattern (
*.jsf,*.faces,/faces/*), which overrides the implicit*.xhtmlmapping:*.xhtmlreaches the container's default servlet and the raw Facelets source is downloadable — EL expressions, bean and property names, and markup arenderedattribute would have withheld. Confirm no<security-constraint>covers*.xhtmlbefore reporting the source as exposed; that constraint is the other way a project blocks this.
/WEB-INF/ closes both cases whatever the mapping. Report the composite before a plain asset when both apply, since a composite exposes its <cc:implementation> while an asset exposes only itself.
Backing Beans
- Bean declaration, scope choice,
Serializable,@PostConstructinitialization and getter purity all follow "CDI and Bean Management" and "Scope Selection" in.claude/faces/rules.md. UISelectManybacking properties use mutable collections (new ArrayList), notList.of(),Arrays.asList(), orStream.toList().actionmethods are used for business logic;actionListeneris only used to prepare/gate the action.- Event listeners use a mechanism that exists in the detected version — see the "System Events and Phase Listeners" section in
.claude/faces/rules.md.
Configuration (if accessible)
web.xmlhasFACELETS_SKIP_COMMENTSset totrue.web.xmlhasINTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULLset totrue.WEBAPP_RESOURCES_DIRECTORY: when the resources directory contains composite components (.xhtmlfiles), it MUST be set toWEB-INF/resourcesto prevent direct client access to composite component source code; for plain assets only (scripts, styles, images, fonts) it's merely a recommendation.- FacesServlet is mapped to
*.xhtmlonly (no legacy*.jsf,*.faces,/faces/*). - Each deployment descriptor declares the version of ITS OWN specification — not the Jakarta EE platform version — and should match the API version the runtime actually supplies. A lagging declaration caps the available API features to that older version and should be bumped (
warningif it lags, not an error — it deploys fine). Check theversionattribute AND thexsi:schemaLocation, since bumping only one is the usual half-fix:faces-config.xml-> Jakarta Faces API version, fromjakarta.faces-apior the bundled Mojarra/MyFaces implementation.web.xml-> Jakarta Servlet API version, fromjakarta.servlet-apior the servlet container.beans.xml-> Jakarta CDI API version, fromjakarta.enterprise.cdi-apior the bundled Weld/OpenWebBeans; an empty or absentbeans.xmlis valid and needs no bump.- Take each version from the artifact that supplies that API; only on a full Jakarta EE server may they be derived from the platform version. Verify rather than assume the three move together.
PrimeFaces (if present)
- Consult
.claude/faces/topics/primefaces.mdand check its rules.
OmniFaces (if present)
- Consult
.claude/faces/topics/omnifaces.mdand check for opportunities to simplify code. - A
@FacesConverter/@FacesValidatorclass whose attributes are set by<o:converter>/<o:validator>:managed=trueMUST be absent — reporterror, since the implementation wraps a managed artifact and every attribute is then silently dropped — and the class should be@Dependent. Condition this on the implementation rather than the spec version: only Mojarra 5.0 and newer is exempt, MyFaces still wraps on its 5.0 snapshots. Reportwarningwhen such a class is ALSO attached the standard way (validator="id",<f:validator>,converter="id",<f:converter>,<default-validators>), because it then runs unconfigured there. See "Deferred Attributes" in.claude/faces/topics/conversion-validation.md.
Step 3: Validate Proposed Fixes
A fix that resolves one finding must not introduce another. Before reporting any fix that restructures markup — moving, splitting or wrapping elements — re-check the result against the rest of the checklist.
For form-boundary changes in particular: enumerate every ActionSource and EditableValueHolder in the affected region FIRST, then draw the boundary so each one still has a UIForm ancestor afterwards. Watch for those sitting outside the visual body of a section — in headers, toolbars, ui:fragment or ui:include — and for decorated elements such as <a faces:action>, which do not look like Faces components.
Step 4: Output Format
Open the report with the detected Faces version and how it was detected.
For each finding, report:
- File and line — the location.
- Rule violated — short description of which rule.
- Severity — error (will cause bugs), warning (anti-pattern/risk), or info (improvement opportunity).
- Fix — concrete suggestion, using only APIs available in the detected version. If the fix depends on a newer version, say which version and mark the finding
info.
Group findings by file. If no issues are found, confirm the code follows Faces best practices.