# reviewer

```
shadcn-maestro reviewer [--screen <id>] [--cwd <path>] [--json]
```

`reviewer` detects the stack and the package manager, resolves the routes, extracts each screen with its layouts, imports and regions, and writes the map to `.shadcn-maestro/map/`. Run it again at any time: unchanged files are kept, changed ones are re-read, and annotations whose source changed become stale.

## Dependency check

Before mapping, `reviewer` compares `agent-browser --version` and `shadcn --version` with the latest version on npm.

| Issue | Status | When |
| --- | --- | --- |
| `dependency_missing` | `pending` (exit `3`) | `agent-browser` or `shadcn` is not on PATH |
| `dependency_outdated` | `pending` (exit `3`) | Either is older than the npm latest |
| `dependency_check_skipped` | mapping continues | npm cannot be reached |

When blocked, it maps nothing and prints `npm i -g agent-browser@latest shadcn@latest` as the next action.

## Summary

Without `--screen`, it prints the stack, the screens with their routes, the components shared between screens and the references it could not resolve. Output for a Vite and React Router app:

```txt
Structural scan complete (map revision f59569dccc26dfb1).
Semantic review: not verified (0 reviewed, 0 pending, 0 stale, 0 disputed annotations).
  Next: Annotate screen:src/pages/Customers.tsx, screen:src/pages/Reports.tsx, screen:src/pages/Settings.tsx (shadcn-maestro reviewer annotate), then obtain an independent review
Stack: vite (react-router), manager npm, shadcn yes, tailwind yes

Screens:
  screen:src/pages/Customers.tsx  /customers  (react-router)
  screen:src/pages/Reports.tsx  /reports  (react-router)
  screen:src/pages/Settings.tsx  /settings  (react-router)
Shared components:
  src/components/PageHeader.tsx#PageHeader  src/components/PageHeader.tsx:3  used by 3 screens
Unresolved:
  unresolved-import  src/main.tsx:7  ./index.css ("./index.css" does not resolve to a file)
```

"Semantic review: not verified" means no screen has a reviewed annotation yet; the next line says which screens to [annotate](/cli/annotate).

## One screen

`--screen <id>` prints one screen with its layouts, regions and components. With `--json`, `data` holds the stack, the map revision, the review state of that screen, the screen record, its components and its unresolved references:

```json
{
  "schemaVersion": 1,
  "command": "reviewer",
  "status": "ok",
  "data": {
    "stack": {
      "framework": "vite",
      "routers": [
        {
          "kind": "react-router",
          "evidence": "package.json: react-router-dom@7.6.0"
        }
      ],
      "manager": "npm",
      "managerEvidence": [
        "package-lock.json"
      ],
      "shadcn": "components.json",
      "tailwind": "package.json: tailwindcss@^4.3.3"
    },
    "revision": "f59569dccc26dfb1",
    "scan": "complete",
    "changedIds": [],
    "affectedScreenIds": [],
    "invalidatedAnnotationIds": [],
    "semanticReview": {
      "verified": false,
      "state": "pending",
      "annotations": {
        "reviewed": 0,
        "pending": 0,
        "disputed": 0,
        "stale": 0
      },
      "missing": [
        "screen:src/pages/Customers.tsx"
      ],
      "orphaned": [],
      "disputes": [],
      "nextAction": "Annotate screen:src/pages/Customers.tsx (shadcn-maestro reviewer annotate), then obtain an independent review"
    },
    "screen": {
      "componentIds": [
        "src/components/PageHeader.tsx#PageHeader"
      ],
      "entryFile": "src/pages/Customers.tsx",
      "id": "screen:src/pages/Customers.tsx",
      "kind": "screen",
      "layoutIds": [],
      "patterns": [
        "/customers"
      ],
      "regionIds": [
        "src/pages/Customers.tsx#Customers/jsx:0",
        "src/pages/Customers.tsx#Customers/jsx:0.0",
        "src/pages/Customers.tsx#Customers/jsx:0.0.0",
        "… 15 more region ids"
      ],
      "router": "react-router",
      "record": "screens/screen_src_pages_Customers.tsx.06156dd448161987.json"
    },
    "components": [
      {
        "id": "src/components/PageHeader.tsx#PageHeader",
        "record": "components/src_components_PageHeader.tsx_PageHeader.c54623dcea70a691.json",
        "definition": "src/components/PageHeader.tsx:3",
        "screenIds": [
          "screen:src/pages/Customers.tsx",
          "screen:src/pages/Reports.tsx",
          "screen:src/pages/Settings.tsx"
        ]
      }
    ],
    "unresolved": {
      "items": []
    }
  },
  "issues": [],
  "nextAction": null
}
```

The `regionIds` list was shortened for this page. Use `revision` as `expectedMapRevision` and the region `ref`s as evidence when you annotate.

## Errors

| Issue | Status | Meaning |
| --- | --- | --- |
| `multiple_apps` | `pending` | More than one app under `--cwd`; `data.candidates` lists them. Run again with `--cwd <path>` |
| `astro_not_supported` | `error` | The app is an Astro project |
| `stack_not_supported` | `error` | No supported framework was found |
| `invalid_package_json` | issue | A `package.json` cannot be read; it is skipped and mapping continues |
| `manager_conflict` | issue | Evidence for more than one package manager |
| `unknown_screen` | `error` | `--screen` names a screen that is not in the map |
| `map_update_failed` | `error` | The map could not be written |