---
name: validate-conventions
description: >
  Audits a SmartStack project for convention violations — namespace prefixes
  by Clean Architecture layer, entity patterns (BaseEntity + tenant interfaces
  + private ctor + factory), and controller routing (NavRoute vs hardcoded
  Route). Produces a structured JSON report of findings. Use when the user
  asks to audit, validate or check a project's conformance with SmartStack
  conventions. Keywords: audit, conventions, conformance, check project,
  validate structure, namespace, NavRoute, entity compliance.
phase: validation
cli: cli/validate-conventions
allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
---

# validate-conventions

Scans a SmartStack project and reports convention violations across three
categories. Delegates all logic to a CLI invoked via Bash.

## When to use this skill

Activate when the user asks to:

- Audit a project for SmartStack conformance
- Check whether an entity / controller / namespace follows the conventions
- Validate the structure before a PR / deployment
- Understand which parts of the project drift from the framework patterns

### When NOT to use

- For runtime tests (unit / integration) → use the project's test runner
- For lint / style issues (formatting, unused imports) → use ESLint / StyleCop
- For architectural diagrams → use dedicated diagramming tools

---

## Invocation

Invoke via **Bash**. The CLI accepts the project path as an argument (or uses
the current working directory) and runs a selection of checks:

```bash
npx --prefer-offline tsx skills/validation/conventions/cli/validate-conventions/index.ts \
  [--project-path <abs-path>] \
  [--checks <list>] \
  [--base-namespace <name>]
```

### Arguments

- `--project-path` (optional) — absolute path of the SmartStack project. If
  omitted, the CLI uses `process.cwd()`.
- `--checks` (optional) — comma-separated list of checks to run. Valid values:
  `namespaces`, `entities`, `controllers`, `all`. Default: `all`.
- `--base-namespace` (optional) — override the auto-detected base namespace
  (e.g. `--base-namespace Acme.Corp`). Use when the CLI cannot detect the
  expected namespace from `.csproj` files.

### Examples

Full audit of the default project:
```bash
npx --prefer-offline tsx skills/validation/conventions/cli/validate-conventions/index.ts \
  --project-path "D:/01 - projets/SmartStack.app/02-Develop"
```

Only check controller routes:
```bash
npx --prefer-offline tsx skills/validation/conventions/cli/validate-conventions/index.ts \
  --project-path "D:/..." --checks controllers
```

---

## Reading the result

The CLI prints a JSON envelope on stdout:

```json
{
  "success": true,
  "command": "validate-conventions",
  "data": {
    "valid": true,
    "summary": "All checks passed (47 files inspected, 3 warnings, 0 infos)"
  },
  "report": {
    "projectPath": "...",
    "structure": { "domain": "...", "application": "...", ... },
    "checksRun": ["namespaces", "entities", "controllers"],
    "filesInspected": 47,
    "findings": [
      {
        "severity": "warning",
        "category": "entities",
        "message": "Entity \"Foo\" is missing a factory method",
        "file": "src/Domain/Foo.cs",
        "suggestion": "Add: public static Foo Create(...)"
      }
    ],
    "counts": { "errors": 0, "warnings": 3, "infos": 0 },
    "byCategory": { "namespaces": 0, "entities": 3, "controllers": 0 }
  },
  "errors": [],
  "warnings": [],
  "nextSteps": ["Review the warnings — they indicate drift..."]
}
```

### Interpretation

- `data.valid` — `true` when `counts.errors === 0`. Warnings don't block.
- `report.findings` — the authoritative list of violations. Each finding has
  a `severity`, `category`, `message`, optional `file` path (relative to the
  project root), and `suggestion` for how to fix it.
- `report.counts` — quick totals for a summary.
- `report.byCategory` — violations grouped by category — useful to decide
  which layer to focus on first.

### What to tell the user

- If `valid === true` and `counts.warnings === 0`: celebrate.
- If `valid === true` and `counts.warnings > 0`: report the warnings grouped
  by category and suggest reviewing the most severe ones first.
- If `valid === false`: show the errors FIRST (group by category), then the
  warnings. Highlight files that appear in multiple findings.

---

## Checks implemented in this version

### 1. `namespaces`

Scans `.cs` files in each Clean Architecture layer and verifies the namespace
starts with the expected prefix:

- `{BaseNamespace}.Domain` for files in Domain
- `{BaseNamespace}.Application` for files in Application
- `{BaseNamespace}.Infrastructure` for files in Infrastructure
- `{BaseNamespace}.Api` for files in Api

Findings are downgraded from `error` to `warning` when the namespace still
follows the Clean Architecture pattern (`{Base}.{Layer}`) but with a different
base (common in client extension projects).

### 2. `entities`

For every class / record in the Domain layer that inherits `BaseEntity`:

- **Warning** if no tenant interface is declared (ITenantEntity,
  IOptionalTenantEntity, IScopedTenantEntity)
- **Warning** if there is no private parameterless constructor (required by EF)
- **Warning** if there is no `public static {Name} Create(...)` factory method

Value objects and classes that do not inherit BaseEntity are skipped.

### 3. `controllers`

For every controller in the API layer (excluding a whitelist of system
controllers):

- **Error** if the controller declares BOTH `[NavRoute(...)]` and a hardcoded
  `[Route(...)]` — these conflict at runtime
- **Error** if a NavRoute has fewer than 2 dot-separated segments
- **Error** if a NavRoute contains uppercase characters
- **Warning** if the controller uses hardcoded `[Route(...)]` instead of
  `[NavRoute]`

---

## Checks not yet implemented (future)

The legacy MCP tool `validate_conventions` shipped 16 checks. This first version
ports 3 of them. The remaining 13 will be added in upcoming waves:

`tables`, `migrations`, `services`, `tenants`, `layouts`, `tabs`, `hierarchies`,
`protected-actions`, `permissions`, `frontend-routes`, `feature-json`,
`code-patterns`, `architecture`.

If the user asks for one of these, inform them it's not yet available as a
CLI check — suggest manual review or wait for the next wave.

---

## Rules

- Never invoke the CLI without first confirming the project path with the user.
- Parse the stdout JSON — ignore stderr.
- If the CLI exits non-zero, treat it as a failure (errors found OR internal
  error). Read `errors[]` first, then `report.findings` if any.
- Progressive disclosure: `patterns.md` contains deeper context on why these
  conventions exist and how to fix common violations.