component-detection

component-detection

Classifies the frontend unit being worked on so that the correct skill set, guidelines, and review rules are applied. Detection runs before any code action and produces a single unit type used for routing within the agent.

Unit Types

Page

A route-level unit that maps directly to a URL.

• Path signals: file lives inside app/, pages/, or a directory declared as a route root in framework config.
• Naming signals: page.tsx, page.vue, [slug].tsx, index.tsx inside a route directory, *.page.ts (Angular).
• Content signals: exports getServerSideProps, getStaticProps, loader, generateStaticParams; imports Head, Link, useRouter, or useNavigate at the top level; defines route-level metadata (export const metadata, <Title>).
• Characteristic behaviour: data fetching at the route boundary, loading/error boundary states, route parameters consumed directly.

Component

A reusable, composable UI unit.

• Path signals: file lives inside components/, src/components/, or a feature's local components/ subdirectory.
• Naming signals: *.component.ts / *.component.html (Angular), *.tsx / *.vue outside a route directory, PascalCase filename.
• Content signals: exports a React function component, Vue SFC <template>, or Angular @Component decorated class; defines a props interface or defineProps; renders JSX, a template, or an SFC.
• Characteristic behaviour: accepts props/inputs, emits events/outputs, has no direct route dependency.

Hook / Composable

Encapsulates stateful logic or side effects without rendering.

• Path signals: file lives inside hooks/, composables/, src/hooks/, or src/composables/.
• Naming signals: filename starts with use followed by an uppercase letter (useAuth.ts, useCart.ts), or is an Angular @Injectable() service (*.service.ts).
• Content signals: imports useState, useEffect, useRef, ref, reactive, computed, inject, or RxJS operators; returns state, handlers, or computed values; contains no JSX, template, or render return.
• Characteristic behaviour: state management, async data fetching, event subscriptions, side-effect lifecycle — all without producing a render tree.

Layout

A structural wrapper applied to groups of pages.

• Path signals: file lives inside layouts/, app/layout.tsx (Next.js App Router), src/app/layout.ts (Angular), __layout.vue (Nuxt/SvelteKit pattern used for reference).
• Naming signals: layout.tsx, layout.vue, *.layout.ts, RootLayout, DefaultLayout.
• Content signals: renders <Outlet> (React Router / TanStack Router), <router-outlet> (Angular), <slot> (Vue/Nuxt); wraps children with navigation, sidebars, or global providers.
• Characteristic behaviour: applies persistent chrome (nav, footer, theme provider) around a dynamic child area.

Utility

Pure functions with no framework dependency.

• Path signals: file lives inside utils/, helpers/, lib/, shared/utils/, or src/utils/.
• Naming signals: camelCase or kebab-case filename without framework suffixes (e.g., formatDate.ts, string-utils.ts).
• Content signals: no imports from react, @angular/core, vue, or any framework package; exports only functions, constants, or type aliases; no JSX, no decorators.
• Characteristic behaviour: data transformation, formatting, validation, math — deterministic, testable in isolation.

Style

Styling artifacts with no component logic.

• Path signals: file has extension .module.css, .module.scss, .css, .scss, or is tailwind.config.js / tailwind.config.ts / theme.ts / tokens.ts.
• Naming signals: ends in .styles.ts, .styled.ts, or contains theme / tokens in the name.
• Content signals: contains only CSS/SCSS rules, CSS-in-JS style objects (no JSX), Tailwind configuration exports, or design token definitions.
• Characteristic behaviour: no component rendering, no state, no framework imports — pure visual specification.

Detection Algorithm

Execute the following steps in order. Stop at the first step that produces a confident match.

1. File path check — compare the file's directory segments against the known directory signals for each unit type. An exact directory match is the strongest signal.
2. Naming convention check — apply the naming signals for each unit type to the filename and extension. Prefix/suffix patterns take precedence over generic PascalCase.
3. Content scan — read the top 60 lines of the file. Look for framework imports, decorator usage, export shapes, and structural keywords.
4. Default — if all steps leave the type ambiguous, classify the unit as component. Log the ambiguity and the signals that were evaluated so the developer can inspect or override.

Override

The resolved type can be overridden per-invocation:

--unit-type hook

An explicit override skips all detection steps and is recorded in resolutionSource.unitType = "per-invocation".

Output

{
  "unitType": "component",
  "confidence": "high",
  "detectedBy": "file-path",
  "signals": {
    "path": "src/components/Button.tsx",
    "namingMatch": "PascalCase .tsx",
    "contentMatch": "exports React function component"
  }
}

confidence is one of high (step 1 or 2 matched), medium (step 3 matched), or low (default applied).