# Validator Quirks

> Known behaviors of `@modyo/widget-validator`, at the version this MCP pins, that can surprise a `widgets-validate` run. Rules and profiles: `modyo://docs/widgets/reference-validator-rules`.

---

## Empty folders with `projectFiles`

`projectFiles` is an array of `{ path, content }`. The validator writes those files to a temporary folder and validates that folder, so a folder exists only if at least one file is inside it. An empty folder cannot be represented.

| Profile | Effect |
|---------|--------|
| `domain-1.4` | None for a widget created from the canonical template: the profile only requires folders that the template always fills with files (`src/app`, `src/config`, `src/shared`, `src/locales`, `src/styles`, `tests`) |
| `type-based` | Required folders that are empty in the widget come back as `Missing required folder: <folder>` |

For a `type-based` widget, include a sentinel file in each required folder that is empty:

```json
[
  { "path": "src/hooks/.gitkeep", "content": "" },
  { "path": "src/types/.gitkeep", "content": "" }
]
```

`widgets-validate` sends `projectFiles` as received; it does not add sentinel files. With `projectPath` the validator reads the real folder and this does not apply.

---

## A rejected manifest stops the validation

When `widget.manifest.json` exists but does not point to a supported template (invalid JSON, no `template`, another package, a version before 1.4 or another major), the validator runs no rule. The report has `profile: null` and a single error in category `Widget Manifest`, rule `Profile Selection`, with the reason.

Fix the manifest, or remove it if the widget uses the type-based structure. The messages are listed in `modyo://docs/widgets/reference-validator-rules` (Fail closed).

---

## Missing manifest

A widget with `src/app/main.tsx` and `src/features/` but without `widget.manifest.json` is validated by the `type-based` rules, and every type-based folder comes back missing. The first error, `Widget Manifest` / `Missing Manifest`, names the cause.

- With `projectPath`: add `widget.manifest.json` at the widget root.
- With `projectFiles`: include `widget.manifest.json` among the files. It is the file that selects the profile, so collecting only `src/` is not enough.

---

## Portal System checks little

- *Portal Registration* only looks for the text `availablePortals` in `src/app/main.tsx`. A widget that registers the wrong portal, or none (`availablePortals={{}}`), still passes.
- The check only runs when a `.tsx` file under `src/features` uses `<DModal` or `<DOffcanvas`.

Opening a portal whose name is not registered fails at runtime. Check the registration by hand: `modyo://docs/widgets/patterns-features` (Adding a feature).

---

## See also

- `modyo://docs/widgets/reference-validator-rules`
- `modyo://docs/widgets/reference-troubleshooting`
