@vercube/scan 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present - Vercube
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @vercube/scan
+
+Shared source-scanning and AST-extraction utilities for the [Vercube](https://github.com/vercube/vercube) framework. It discovers `@Controller` routes, `@Injectable` services and `BaseMiddleware` subclasses by parsing TypeScript/JavaScript with [`oxc-parser`](https://www.npmjs.com/package/oxc-parser).
+
+This package is the single source of truth used by both the [`@vercube/nitro`](../nitro) and [`@vercube/vite`](../vite) integrations. You usually don't depend on it directly.
+
+## Installation
+
+```bash
+pnpm add @vercube/scan
+```
+
+## API
+
+### Pure extractors
+
+Operate on a source string and return discovered classes (with placeholder import specifiers):
+
+```ts
+import { extractRoutes, extractServices, extractMiddlewares } from '@vercube/scan';
+
+extractRoutes(code); // RouteInfo[]
+extractServices(code); // ServiceInfo[]
+extractMiddlewares(code); // MiddlewareInfo[]
+```
+
+### Scanning
+
+`scanFiles` / `scanDir` walk directories (via [`tinyglobby`](https://www.npmjs.com/package/tinyglobby)); the higher-level helpers read files, extract, and resolve each import to its real path:
+
+```ts
+import { getRoutes, getServices, getMiddlewares, scanProject, scanSource } from '@vercube/scan';
+
+// Nitro-style: dedicated api/routes/services subdirectories
+await scanProject({ baseDirs: ['/abs/src'] });
+
+// Vercube-style: walk the whole tree, classes can live anywhere
+await scanSource({ dirs: ['/abs/src'] });
+// → { routes, services, middlewares } with imports resolved to real paths
+```
+
+`scanSource` reads each file once and applies all three extractors, deduplicating services that are already registered as routes.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,338 @@
+//#region src/Ast.d.ts
+/**
+ * Unwraps export declarations to retrieve the underlying class node,
+ * along with metadata about the export style.
+ *
+ * Handles the following AST patterns:
+ * - `ExportDefaultDeclaration` wrapping a `ClassDeclaration` → `isDefault: true`
+ * - `ExportNamedDeclaration` wrapping a `ClassDeclaration` → `isDefault: false`
+ * - Direct `ClassDeclaration` or `Class` nodes → `isDefault: false`
+ *
+ * @param node - An AST node from the program body to inspect.
+ * @returns An object containing the class AST node and whether it is a default export, or `null` if not a class.
+ */
+declare function getClassNode(node: any): {
+  classNode: any;
+  isDefault: boolean;
+} | null;
+/**
+ * Builds an import statement for a class, choosing default vs named syntax.
+ *
+ * @param className - The class identifier to import.
+ * @param source - The module specifier to import from.
+ * @param isDefault - Whether the class is a default export.
+ * @returns The generated import statement string.
+ */
+declare function buildImport(className: string, source: string, isDefault: boolean): string;
+/**
+ * Searches a list of decorators for a `CallExpression` matching the given name
+ * and extracts its first string argument.
+ *
+ * Used to retrieve the path argument from decorators like `@Controller('/api/foo')`.
+ * If the decorator is found but has no string argument, an empty string is returned.
+ * If no matching decorator is found, `null` is returned.
+ *
+ * @param decorators - The array of decorator AST nodes to search, or `undefined` if none exist.
+ * @param name - The decorator function name to match against (e.g. 'Controller').
+ * @returns The string argument value, an empty string if no argument is provided, or `null` if the decorator is not found.
+ */
+declare function extractDecoratorArg(decorators: any[] | undefined, name: string): string | null;
+/**
+ * Returns true if the given decorators array contains a decorator matching `name`.
+ * Supports both `@Name` identifier and `@Name()` call expression styles.
+ *
+ * @param decorators - The array of decorator AST nodes to search.
+ * @param name - The decorator name to match.
+ * @returns Whether a matching decorator exists.
+ */
+declare function hasDecorator(decorators: any[] | undefined, name: string): boolean;
+/**
+ * Returns true if the class node extends a superclass with the given name.
+ *
+ * @param classNode - The class AST node to inspect.
+ * @param name - The expected superclass identifier name.
+ * @returns Whether the class extends the named superclass.
+ */
+declare function extendsSuperClass(classNode: any, name: string): boolean;
+/**
+ * Normalizes a route path by removing duplicate slashes and ensuring
+ * the path starts with a single leading slash.
+ *
+ * @param path - The raw concatenated path string to normalize.
+ * @returns A cleaned path string with a leading slash and no duplicate separators.
+ */
+declare function normalizePath(path: string): string;
+/**
+ * Extracts named route parameters from a path string.
+ *
+ * Scans the path for segments prefixed with ':' and returns an array of
+ * parameter names with the ':' prefix stripped.
+ *
+ * @param route - The normalized route path to scan for parameters.
+ * @returns An array of parameter name strings, empty if none are found.
+ */
+declare function extractParams(route: string): string[];
+//#endregion
+//#region src/Types.d.ts
+/**
+ * Basic information about a scanned source file.
+ */
+type FileInfo = {
+  /** The path of the file relative to the directory it was scanned from. */path: string; /** The absolute path of the file on disk. */
+  fullPath: string;
+};
+/**
+ * Represents a single extracted route from a controller class.
+ */
+interface RouteInfo extends FileInfo {
+  /** The import statement required to load the controller class. */
+  import: string;
+  /** The name of the import statement. */
+  importClassName: string;
+  /** The full normalized route path, including the base controller path and method path. */
+  route: string;
+  /** The HTTP method in uppercase (e.g. 'GET', 'POST', 'PUT'). */
+  method: string;
+  /** Array of route parameter names extracted from path segments prefixed with ':'. */
+  params: string[];
+}
+/**
+ * Represents a single injectable service class discovered during scanning.
+ */
+interface ServiceInfo extends FileInfo {
+  /** The import statement required to load the service class. */
+  import: string;
+  /** The name of the imported class. */
+  importClassName: string;
+}
+/**
+ * Represents a single middleware class discovered during scanning.
+ */
+interface MiddlewareInfo extends FileInfo {
+  /** The import statement required to load the middleware class. */
+  import: string;
+  /** The name of the imported class. */
+  importClassName: string;
+}
+/**
+ * Minimal logger interface used to report non-fatal scanning issues.
+ */
+interface ScanLogger {
+  warn(message: string): void;
+}
+//#endregion
+//#region src/Extract.d.ts
+/**
+ * Placeholder module specifier embedded in generated route imports.
+ * Callers resolve it to the real file path once known (see {@link Transform}).
+ */
+declare const IMPORT_SOURCE = "#internal/vercube-route-plugin";
+/**
+ * Placeholder module specifier embedded in generated service imports.
+ */
+declare const SERVICE_IMPORT_SOURCE = "#internal/vercube-service-source";
+/**
+ * Placeholder module specifier embedded in generated middleware imports.
+ */
+declare const MIDDLEWARE_IMPORT_SOURCE = "#internal/vercube-middleware-source";
+/**
+ * Extracts all route definitions from the given TypeScript/JavaScript source code.
+ *
+ * Parses the source using `oxc-parser` and traverses the resulting AST to find
+ * classes decorated with `@Controller(path)`. For each such class, it inspects
+ * method definitions for HTTP method decorators (`@Get`, `@Post`, `@Put`, `@Delete`,
+ * `@Patch`, `@Options`, `@Head`) and constructs full route paths by concatenating
+ * the controller base path with the method-level path.
+ *
+ * @param code - The raw TypeScript or JavaScript source code string to analyze.
+ * @returns An array of {@link RouteInfo} objects representing all discovered routes.
+ */
+declare function extractRoutes(code: string): RouteInfo[];
+/**
+ * Extracts every `@Controller`-decorated class from the given source code,
+ * regardless of whether it declares HTTP method routes.
+ *
+ * Unlike {@link extractRoutes} (which emits one entry per HTTP route method),
+ * this returns one entry per controller class — so controllers that only carry
+ * non-HTTP handlers (e.g. WebSocket `@Message` methods) are still discovered for
+ * binding into the DI container.
+ *
+ * @param code - The raw TypeScript or JavaScript source code string to analyze.
+ * @returns An array of {@link ServiceInfo} objects for all discovered controller classes.
+ */
+declare function extractControllers(code: string): ServiceInfo[];
+/**
+ * Extracts all `@Injectable`-decorated class definitions from the given source code.
+ *
+ * @param code - The raw TypeScript or JavaScript source code string to analyze.
+ * @returns An array of {@link ServiceInfo} objects for all discovered injectable classes.
+ */
+declare function extractServices(code: string): ServiceInfo[];
+/**
+ * Extracts all class definitions that extend `BaseMiddleware` from the given source code.
+ *
+ * @param code - The raw TypeScript or JavaScript source code string to analyze.
+ * @returns An array of {@link MiddlewareInfo} objects for all discovered middleware classes.
+ */
+declare function extractMiddlewares(code: string): MiddlewareInfo[];
+//#endregion
+//#region src/Project.d.ts
+/**
+ * Options describing where to scan for controllers, services and middleware.
+ *
+ * `baseDirs` are the project source roots (e.g. `src/`). The remaining options
+ * name the subdirectories scanned within each base root.
+ */
+interface ScanProjectOptions {
+  /** Project source roots to scan within. */
+  baseDirs: string[];
+  /** Subdirectory holding API controllers. Defaults to `api`. */
+  apiDir?: string;
+  /** Subdirectory holding route controllers. Defaults to `routes`. */
+  routesDir?: string;
+  /** Subdirectories scanned for `@Injectable` services. Defaults to `['api', 'routes', 'services', 'repositories']`. */
+  serviceDirs?: string[];
+  /** Subdirectory holding middleware classes. Defaults to `middleware`. */
+  middlewareDir?: string;
+  /** Optional logger forwarded to the underlying scanner. */
+  logger?: ScanLogger;
+}
+/**
+ * Scans the API and routes directories for controllers and returns every route
+ * with its `import` resolved to the controller's real file path.
+ *
+ * @param options - Where to scan. See {@link ScanProjectOptions}.
+ * @returns The discovered routes with resolved imports.
+ */
+declare function getRoutes(options: ScanProjectOptions): Promise<RouteInfo[]>;
+/**
+ * Scans the configured service directories for `@Injectable` classes and returns
+ * every service with its `import` resolved to the class's real file path.
+ *
+ * @param options - Where to scan. See {@link ScanProjectOptions}.
+ * @returns The discovered services with resolved imports.
+ */
+declare function getServices(options: ScanProjectOptions): Promise<ServiceInfo[]>;
+/**
+ * Scans the middleware directory for `BaseMiddleware` subclasses and returns
+ * every middleware with its `import` resolved to the class's real file path.
+ *
+ * @param options - Where to scan. See {@link ScanProjectOptions}.
+ * @returns The discovered middleware with resolved imports.
+ */
+declare function getMiddlewares(options: ScanProjectOptions): Promise<MiddlewareInfo[]>;
+/**
+ * Convenience wrapper that scans routes, services and middleware in one call.
+ *
+ * Services whose class name is already registered as a route are filtered out
+ * so a controller is never imported twice.
+ *
+ * @param options - Where to scan. See {@link ScanProjectOptions}.
+ * @returns The discovered routes, deduplicated services, and middleware.
+ */
+declare function scanProject(options: ScanProjectOptions): Promise<{
+  routes: RouteInfo[];
+  services: ServiceInfo[];
+  middlewares: MiddlewareInfo[];
+}>;
+/**
+ * Options for {@link scanSource}.
+ */
+interface ScanSourceOptions {
+  /** Directories whose entire file tree is scanned for decorated classes. */
+  dirs: string[];
+  /** Optional logger forwarded to the underlying scanner. */
+  logger?: ScanLogger;
+}
+/**
+ * Recursively scans the given directories for `@Controller` classes,
+ * `@Injectable` services and `BaseMiddleware` subclasses, reading each file only
+ * once.
+ *
+ * Unlike {@link scanProject}, this does not assume the Nitro convention of
+ * dedicated `api`/`routes`/`services` subdirectories — decorated classes are
+ * discovered wherever they live in the tree, which matches how Vercube apps are
+ * typically organised. **Every** `@Controller` class is returned for binding
+ * (not just those with HTTP routes), so WebSocket-only controllers are bound
+ * too, while `routes` carries the concrete HTTP routes (method + path) for
+ * request matching. Services already discovered as controllers are filtered out
+ * so a class is never imported twice.
+ *
+ * @param options - Directories to scan. See {@link ScanSourceOptions}.
+ * @returns The discovered controllers, HTTP routes, deduplicated services, and middleware, all with resolved imports.
+ */
+declare function scanSource(options: ScanSourceOptions): Promise<{
+  controllers: ServiceInfo[];
+  routes: RouteInfo[];
+  services: ServiceInfo[];
+  middlewares: MiddlewareInfo[];
+}>;
+//#endregion
+//#region src/Scan.d.ts
+/**
+ * Glob pattern matching every source file extension the scanner understands.
+ */
+declare const GLOB_SCAN_PATTERN = "**/*.{js,mjs,cjs,ts,mts,cts,tsx,jsx}";
+/**
+ * Scans a single base directory for files inside the named subdirectory.
+ *
+ * Globs `<name>/**` relative to `dir`, returning each match as a {@link FileInfo}
+ * with its absolute path and the path relative to `<dir>/<name>`. Results are
+ * sorted by relative path for deterministic output.
+ *
+ * @param dir - The base directory to scan within.
+ * @param name - The subdirectory (e.g. 'api', 'routes', 'services') to look in.
+ * @param logger - Optional logger used to warn when `<dir>/<name>` is not a directory.
+ * @returns A sorted list of discovered files.
+ */
+declare function scanDir(dir: string, name: string, logger?: ScanLogger): Promise<FileInfo[]>;
+/**
+ * Scans every base directory for files inside the named subdirectory.
+ *
+ * @param baseDirs - The base directories to scan (e.g. the project source roots).
+ * @param name - The subdirectory to look in within each base directory.
+ * @param logger - Optional logger forwarded to {@link scanDir}.
+ * @returns The flattened list of discovered files across all base directories.
+ */
+declare function scanFiles(baseDirs: string[], name: string, logger?: ScanLogger): Promise<FileInfo[]>;
+//#endregion
+//#region src/Transform.d.ts
+/**
+ * Reads a controller file from disk and returns all routes defined in classes
+ * decorated with `@Controller` and methods decorated with HTTP decorators.
+ *
+ * The returned `import` statements still contain the placeholder source; resolve
+ * them to the real file path with {@link resolveImports} when generating code.
+ *
+ * @param file - File info (path and fullPath) to analyze.
+ * @returns A list of {@link RouteInfo} for every route in the file.
+ */
+declare function transformRoute(file: FileInfo): Promise<RouteInfo[]>;
+/**
+ * Reads a file from disk and returns all `@Injectable`-decorated classes found within it.
+ *
+ * @param file - File info (path and fullPath) to analyze.
+ * @returns A list of {@link ServiceInfo} for every injectable class in the file.
+ */
+declare function transformService(file: FileInfo): Promise<ServiceInfo[]>;
+/**
+ * Reads a file from disk and returns all classes extending `BaseMiddleware` found within it.
+ *
+ * @param file - File info (path and fullPath) to analyze.
+ * @returns A list of {@link MiddlewareInfo} for every middleware class in the file.
+ */
+declare function transformMiddleware(file: FileInfo): Promise<MiddlewareInfo[]>;
+/**
+ * Replaces the placeholder import source in each entry with the entry's real
+ * absolute file path, producing import statements that load the actual module.
+ *
+ * @param entries - Scanned entries whose `import` still references the placeholder source.
+ * @param placeholder - The placeholder module specifier to replace.
+ * @returns The entries with resolved `import` statements.
+ */
+declare function resolveImports<T extends {
+  import: string;
+  fullPath: string;
+}>(entries: T[], placeholder: string): T[];
+//#endregion
+export { FileInfo, GLOB_SCAN_PATTERN, IMPORT_SOURCE, MIDDLEWARE_IMPORT_SOURCE, MiddlewareInfo, RouteInfo, SERVICE_IMPORT_SOURCE, ScanLogger, ScanProjectOptions, ScanSourceOptions, ServiceInfo, buildImport, extendsSuperClass, extractControllers, extractDecoratorArg, extractMiddlewares, extractParams, extractRoutes, extractServices, getClassNode, getMiddlewares, getRoutes, getServices, hasDecorator, normalizePath, resolveImports, scanDir, scanFiles, scanProject, scanSource, transformMiddleware, transformRoute, transformService };

package/dist/index.mjs

@@ -0,0 +1,514 @@
+import { parseSync } from "oxc-parser";
+import { readFileSync } from "node:fs";
+import { join, relative } from "pathe";
+import { glob } from "tinyglobby";
+//#region src/Ast.ts
+/**
+* Pre-compiled regular expression for extracting named route parameters.
+* Matches path segments prefixed with ':' (e.g. ':id', ':slug').
+* Uses the global flag for iterative matching via `exec`.
+*/
+const PARAM_RE = /:([^/]+)/g;
+/**
+* Unwraps export declarations to retrieve the underlying class node,
+* along with metadata about the export style.
+*
+* Handles the following AST patterns:
+* - `ExportDefaultDeclaration` wrapping a `ClassDeclaration` → `isDefault: true`
+* - `ExportNamedDeclaration` wrapping a `ClassDeclaration` → `isDefault: false`
+* - Direct `ClassDeclaration` or `Class` nodes → `isDefault: false`
+*
+* @param node - An AST node from the program body to inspect.
+* @returns An object containing the class AST node and whether it is a default export, or `null` if not a class.
+*/
+function getClassNode(node) {
+	if (node.type === "ExportDefaultDeclaration") {
+		const decl = node.declaration;
+		if (decl?.type === "ClassDeclaration" || decl?.type === "Class") return {
+			classNode: decl,
+			isDefault: true
+		};
+	}
+	if (node.type === "ExportNamedDeclaration") {
+		const decl = node.declaration;
+		if (decl?.type === "ClassDeclaration" || decl?.type === "Class") return {
+			classNode: decl,
+			isDefault: false
+		};
+	}
+	if (node?.type === "ClassDeclaration" || node?.type === "Class") return {
+		classNode: node,
+		isDefault: false
+	};
+	return null;
+}
+/**
+* Builds an import statement for a class, choosing default vs named syntax.
+*
+* @param className - The class identifier to import.
+* @param source - The module specifier to import from.
+* @param isDefault - Whether the class is a default export.
+* @returns The generated import statement string.
+*/
+function buildImport(className, source, isDefault) {
+	return isDefault ? `import ${className} from '${source}';` : `import { ${className} } from '${source}';`;
+}
+/**
+* Searches a list of decorators for a `CallExpression` matching the given name
+* and extracts its first string argument.
+*
+* Used to retrieve the path argument from decorators like `@Controller('/api/foo')`.
+* If the decorator is found but has no string argument, an empty string is returned.
+* If no matching decorator is found, `null` is returned.
+*
+* @param decorators - The array of decorator AST nodes to search, or `undefined` if none exist.
+* @param name - The decorator function name to match against (e.g. 'Controller').
+* @returns The string argument value, an empty string if no argument is provided, or `null` if the decorator is not found.
+*/
+function extractDecoratorArg(decorators, name) {
+	if (!decorators) return null;
+	for (const dec of decorators) {
+		const expr = dec.expression;
+		if (expr?.type === "CallExpression" && expr.callee?.name === name) {
+			const arg = expr.arguments?.[0];
+			if (arg?.type === "Literal" && typeof arg.value === "string") return arg.value;
+			return "";
+		}
+	}
+	return null;
+}
+/**
+* Returns true if the given decorators array contains a decorator matching `name`.
+* Supports both `@Name` identifier and `@Name()` call expression styles.
+*
+* @param decorators - The array of decorator AST nodes to search.
+* @param name - The decorator name to match.
+* @returns Whether a matching decorator exists.
+*/
+function hasDecorator(decorators, name) {
+	if (!decorators) return false;
+	for (const dec of decorators) {
+		const expr = dec.expression;
+		if (expr?.type === "CallExpression" && expr.callee?.name === name) return true;
+		if (expr?.type === "Identifier" && expr.name === name) return true;
+	}
+	return false;
+}
+/**
+* Returns true if the class node extends a superclass with the given name.
+*
+* @param classNode - The class AST node to inspect.
+* @param name - The expected superclass identifier name.
+* @returns Whether the class extends the named superclass.
+*/
+function extendsSuperClass(classNode, name) {
+	return classNode.superClass?.type === "Identifier" && classNode.superClass.name === name;
+}
+/**
+* Normalizes a route path by removing duplicate slashes and ensuring
+* the path starts with a single leading slash.
+*
+* @param path - The raw concatenated path string to normalize.
+* @returns A cleaned path string with a leading slash and no duplicate separators.
+*/
+function normalizePath(path) {
+	return "/" + path.split("/").filter(Boolean).join("/");
+}
+/**
+* Extracts named route parameters from a path string.
+*
+* Scans the path for segments prefixed with ':' and returns an array of
+* parameter names with the ':' prefix stripped.
+*
+* @param route - The normalized route path to scan for parameters.
+* @returns An array of parameter name strings, empty if none are found.
+*/
+function extractParams(route) {
+	const params = [];
+	let match;
+	while (match = PARAM_RE.exec(route)) params.push(match[1]);
+	PARAM_RE.lastIndex = 0;
+	return params;
+}
+//#endregion
+//#region src/Extract.ts
+/**
+* Placeholder module specifier embedded in generated route imports.
+* Callers resolve it to the real file path once known (see {@link Transform}).
+*/
+const IMPORT_SOURCE = "#internal/vercube-route-plugin";
+/**
+* Placeholder module specifier embedded in generated service imports.
+*/
+const SERVICE_IMPORT_SOURCE = "#internal/vercube-service-source";
+/**
+* Placeholder module specifier embedded in generated middleware imports.
+*/
+const MIDDLEWARE_IMPORT_SOURCE = "#internal/vercube-middleware-source";
+/**
+* Mapping of decorator names to their corresponding uppercase HTTP method strings.
+* Used for O(1) lookup and simultaneous method name resolution.
+*/
+const HTTP_METHODS = {
+	Get: "GET",
+	Post: "POST",
+	Put: "PUT",
+	Delete: "DELETE",
+	Patch: "PATCH",
+	Options: "OPTIONS",
+	Head: "HEAD"
+};
+/**
+* Extracts all route definitions from the given TypeScript/JavaScript source code.
+*
+* Parses the source using `oxc-parser` and traverses the resulting AST to find
+* classes decorated with `@Controller(path)`. For each such class, it inspects
+* method definitions for HTTP method decorators (`@Get`, `@Post`, `@Put`, `@Delete`,
+* `@Patch`, `@Options`, `@Head`) and constructs full route paths by concatenating
+* the controller base path with the method-level path.
+*
+* @param code - The raw TypeScript or JavaScript source code string to analyze.
+* @returns An array of {@link RouteInfo} objects representing all discovered routes.
+*/
+function extractRoutes(code) {
+	const ast = parseSync("file.ts", code).program;
+	const routes = [];
+	for (const node of ast.body) {
+		const classInfo = getClassNode(node);
+		if (!classInfo) continue;
+		const { classNode, isDefault } = classInfo;
+		const basePath = extractDecoratorArg(classNode.decorators, "Controller");
+		if (basePath === null) continue;
+		const className = classNode.id?.name;
+		if (!className) continue;
+		const importStatement = buildImport(className, IMPORT_SOURCE, isDefault);
+		for (const member of classNode.body?.body ?? []) {
+			if (member.type !== "MethodDefinition") continue;
+			for (const decorator of member.decorators ?? []) {
+				const expr = decorator.expression;
+				if (expr?.type !== "CallExpression") continue;
+				const method = HTTP_METHODS[expr.callee?.name];
+				if (!method) continue;
+				const arg = expr.arguments?.[0];
+				const fullRoute = normalizePath(basePath + (arg?.type === "Literal" && typeof arg.value === "string" ? arg.value : ""));
+				routes.push({
+					import: importStatement,
+					importClassName: className,
+					route: fullRoute,
+					method,
+					fullPath: "",
+					path: "",
+					params: extractParams(fullRoute)
+				});
+			}
+		}
+	}
+	return routes;
+}
+/**
+* Extracts every `@Controller`-decorated class from the given source code,
+* regardless of whether it declares HTTP method routes.
+*
+* Unlike {@link extractRoutes} (which emits one entry per HTTP route method),
+* this returns one entry per controller class — so controllers that only carry
+* non-HTTP handlers (e.g. WebSocket `@Message` methods) are still discovered for
+* binding into the DI container.
+*
+* @param code - The raw TypeScript or JavaScript source code string to analyze.
+* @returns An array of {@link ServiceInfo} objects for all discovered controller classes.
+*/
+function extractControllers(code) {
+	const ast = parseSync("file.ts", code).program;
+	const controllers = [];
+	for (const node of ast.body) {
+		const classInfo = getClassNode(node);
+		if (!classInfo) continue;
+		const { classNode, isDefault } = classInfo;
+		if (extractDecoratorArg(classNode.decorators, "Controller") === null) continue;
+		const className = classNode.id?.name;
+		if (!className) continue;
+		controllers.push({
+			import: buildImport(className, IMPORT_SOURCE, isDefault),
+			importClassName: className,
+			fullPath: "",
+			path: ""
+		});
+	}
+	return controllers;
+}
+/**
+* Extracts all `@Injectable`-decorated class definitions from the given source code.
+*
+* @param code - The raw TypeScript or JavaScript source code string to analyze.
+* @returns An array of {@link ServiceInfo} objects for all discovered injectable classes.
+*/
+function extractServices(code) {
+	const ast = parseSync("file.ts", code).program;
+	const services = [];
+	for (const node of ast.body) {
+		const classInfo = getClassNode(node);
+		if (!classInfo) continue;
+		const { classNode, isDefault } = classInfo;
+		if (!hasDecorator(classNode.decorators, "Injectable")) continue;
+		const className = classNode.id?.name;
+		if (!className) continue;
+		services.push({
+			import: buildImport(className, SERVICE_IMPORT_SOURCE, isDefault),
+			importClassName: className,
+			fullPath: "",
+			path: ""
+		});
+	}
+	return services;
+}
+/**
+* Extracts all class definitions that extend `BaseMiddleware` from the given source code.
+*
+* @param code - The raw TypeScript or JavaScript source code string to analyze.
+* @returns An array of {@link MiddlewareInfo} objects for all discovered middleware classes.
+*/
+function extractMiddlewares(code) {
+	const ast = parseSync("file.ts", code).program;
+	const middlewares = [];
+	for (const node of ast.body) {
+		const classInfo = getClassNode(node);
+		if (!classInfo) continue;
+		const { classNode, isDefault } = classInfo;
+		if (!extendsSuperClass(classNode, "BaseMiddleware")) continue;
+		const className = classNode.id?.name;
+		if (!className) continue;
+		middlewares.push({
+			import: buildImport(className, MIDDLEWARE_IMPORT_SOURCE, isDefault),
+			importClassName: className,
+			fullPath: "",
+			path: ""
+		});
+	}
+	return middlewares;
+}
+//#endregion
+//#region src/Scan.ts
+/**
+* Glob pattern matching every source file extension the scanner understands.
+*/
+const GLOB_SCAN_PATTERN = "**/*.{js,mjs,cjs,ts,mts,cts,tsx,jsx}";
+/**
+* Scans a single base directory for files inside the named subdirectory.
+*
+* Globs `<name>/**` relative to `dir`, returning each match as a {@link FileInfo}
+* with its absolute path and the path relative to `<dir>/<name>`. Results are
+* sorted by relative path for deterministic output.
+*
+* @param dir - The base directory to scan within.
+* @param name - The subdirectory (e.g. 'api', 'routes', 'services') to look in.
+* @param logger - Optional logger used to warn when `<dir>/<name>` is not a directory.
+* @returns A sorted list of discovered files.
+*/
+async function scanDir(dir, name, logger) {
+	return (await glob(join(name, GLOB_SCAN_PATTERN), {
+		cwd: dir,
+		dot: true,
+		absolute: true
+	}).catch((error) => {
+		if (error?.code === "ENOTDIR") {
+			logger?.warn(`Ignoring \`${join(dir, name)}\`. It must be a directory.`);
+			return [];
+		}
+		throw error;
+	})).map((fullPath) => ({
+		fullPath,
+		path: relative(join(dir, name), fullPath)
+	})).sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+* Scans every base directory for files inside the named subdirectory.
+*
+* @param baseDirs - The base directories to scan (e.g. the project source roots).
+* @param name - The subdirectory to look in within each base directory.
+* @param logger - Optional logger forwarded to {@link scanDir}.
+* @returns The flattened list of discovered files across all base directories.
+*/
+async function scanFiles(baseDirs, name, logger) {
+	return Promise.all(baseDirs.map((dir) => scanDir(dir, name, logger))).then((r) => r.flat());
+}
+//#endregion
+//#region src/Transform.ts
+/**
+* Reads a controller file from disk and returns all routes defined in classes
+* decorated with `@Controller` and methods decorated with HTTP decorators.
+*
+* The returned `import` statements still contain the placeholder source; resolve
+* them to the real file path with {@link resolveImports} when generating code.
+*
+* @param file - File info (path and fullPath) to analyze.
+* @returns A list of {@link RouteInfo} for every route in the file.
+*/
+async function transformRoute(file) {
+	return extractRoutes(readFileSync(file.fullPath, "utf8")).map((route) => ({
+		...route,
+		...file
+	}));
+}
+/**
+* Reads a file from disk and returns all `@Injectable`-decorated classes found within it.
+*
+* @param file - File info (path and fullPath) to analyze.
+* @returns A list of {@link ServiceInfo} for every injectable class in the file.
+*/
+async function transformService(file) {
+	return extractServices(readFileSync(file.fullPath, "utf8")).map((service) => ({
+		...service,
+		...file
+	}));
+}
+/**
+* Reads a file from disk and returns all classes extending `BaseMiddleware` found within it.
+*
+* @param file - File info (path and fullPath) to analyze.
+* @returns A list of {@link MiddlewareInfo} for every middleware class in the file.
+*/
+async function transformMiddleware(file) {
+	return extractMiddlewares(readFileSync(file.fullPath, "utf8")).map((middleware) => ({
+		...middleware,
+		...file
+	}));
+}
+/**
+* Replaces the placeholder import source in each entry with the entry's real
+* absolute file path, producing import statements that load the actual module.
+*
+* @param entries - Scanned entries whose `import` still references the placeholder source.
+* @param placeholder - The placeholder module specifier to replace.
+* @returns The entries with resolved `import` statements.
+*/
+function resolveImports(entries, placeholder) {
+	return entries.map((entry) => ({
+		...entry,
+		import: entry.import.replace(placeholder, entry.fullPath)
+	}));
+}
+//#endregion
+//#region src/Project.ts
+const DEFAULT_API_DIR = "api";
+const DEFAULT_ROUTES_DIR = "routes";
+const DEFAULT_SERVICE_DIRS = [
+	"api",
+	"routes",
+	"services",
+	"repositories"
+];
+const DEFAULT_MIDDLEWARE_DIR = "middleware";
+/**
+* Scans the API and routes directories for controllers and returns every route
+* with its `import` resolved to the controller's real file path.
+*
+* @param options - Where to scan. See {@link ScanProjectOptions}.
+* @returns The discovered routes with resolved imports.
+*/
+async function getRoutes(options) {
+	const { baseDirs, apiDir = DEFAULT_API_DIR, routesDir = DEFAULT_ROUTES_DIR, logger } = options;
+	const files = await Promise.all([scanFiles(baseDirs, apiDir, logger), scanFiles(baseDirs, routesDir, logger)]).then((r) => r.flat());
+	return resolveImports(await Promise.all(files.map((file) => transformRoute(file))).then((r) => r.flat()), IMPORT_SOURCE);
+}
+/**
+* Scans the configured service directories for `@Injectable` classes and returns
+* every service with its `import` resolved to the class's real file path.
+*
+* @param options - Where to scan. See {@link ScanProjectOptions}.
+* @returns The discovered services with resolved imports.
+*/
+async function getServices(options) {
+	const { baseDirs, serviceDirs = DEFAULT_SERVICE_DIRS, logger } = options;
+	const files = await Promise.all(serviceDirs.map((dir) => scanFiles(baseDirs, dir, logger))).then((r) => r.flat());
+	return resolveImports(await Promise.all(files.map((file) => transformService(file))).then((r) => r.flat()), SERVICE_IMPORT_SOURCE);
+}
+/**
+* Scans the middleware directory for `BaseMiddleware` subclasses and returns
+* every middleware with its `import` resolved to the class's real file path.
+*
+* @param options - Where to scan. See {@link ScanProjectOptions}.
+* @returns The discovered middleware with resolved imports.
+*/
+async function getMiddlewares(options) {
+	const { baseDirs, middlewareDir = DEFAULT_MIDDLEWARE_DIR, logger } = options;
+	const files = await scanFiles(baseDirs, middlewareDir, logger);
+	return resolveImports(await Promise.all(files.map((file) => transformMiddleware(file))).then((r) => r.flat()), MIDDLEWARE_IMPORT_SOURCE);
+}
+/**
+* Convenience wrapper that scans routes, services and middleware in one call.
+*
+* Services whose class name is already registered as a route are filtered out
+* so a controller is never imported twice.
+*
+* @param options - Where to scan. See {@link ScanProjectOptions}.
+* @returns The discovered routes, deduplicated services, and middleware.
+*/
+async function scanProject(options) {
+	const [routes, services, middlewares] = await Promise.all([
+		getRoutes(options),
+		getServices(options),
+		getMiddlewares(options)
+	]);
+	const routeClassNames = new Set(routes.map((r) => r.importClassName));
+	return {
+		routes,
+		services: services.filter((s) => !routeClassNames.has(s.importClassName)),
+		middlewares
+	};
+}
+/**
+* Recursively scans the given directories for `@Controller` classes,
+* `@Injectable` services and `BaseMiddleware` subclasses, reading each file only
+* once.
+*
+* Unlike {@link scanProject}, this does not assume the Nitro convention of
+* dedicated `api`/`routes`/`services` subdirectories — decorated classes are
+* discovered wherever they live in the tree, which matches how Vercube apps are
+* typically organised. **Every** `@Controller` class is returned for binding
+* (not just those with HTTP routes), so WebSocket-only controllers are bound
+* too, while `routes` carries the concrete HTTP routes (method + path) for
+* request matching. Services already discovered as controllers are filtered out
+* so a class is never imported twice.
+*
+* @param options - Directories to scan. See {@link ScanSourceOptions}.
+* @returns The discovered controllers, HTTP routes, deduplicated services, and middleware, all with resolved imports.
+*/
+async function scanSource(options) {
+	const files = await scanFiles(options.dirs, ".", options.logger);
+	const controllers = [];
+	const routes = [];
+	const services = [];
+	const middlewares = [];
+	for (const file of files) {
+		const code = readFileSync(file.fullPath, "utf8");
+		for (const controller of extractControllers(code)) controllers.push({
+			...controller,
+			...file,
+			import: controller.import.replace(IMPORT_SOURCE, file.fullPath)
+		});
+		for (const route of extractRoutes(code)) routes.push({
+			...route,
+			...file,
+			import: route.import.replace(IMPORT_SOURCE, file.fullPath)
+		});
+		for (const service of extractServices(code)) services.push({
+			...service,
+			...file,
+			import: service.import.replace(SERVICE_IMPORT_SOURCE, file.fullPath)
+		});
+		for (const middleware of extractMiddlewares(code)) middlewares.push({
+			...middleware,
+			...file,
+			import: middleware.import.replace(MIDDLEWARE_IMPORT_SOURCE, file.fullPath)
+		});
+	}
+	const controllerClassNames = new Set(controllers.map((c) => c.importClassName));
+	return {
+		controllers,
+		routes,
+		services: services.filter((s) => !controllerClassNames.has(s.importClassName)),
+		middlewares
+	};
+}
+//#endregion
+export { GLOB_SCAN_PATTERN, IMPORT_SOURCE, MIDDLEWARE_IMPORT_SOURCE, SERVICE_IMPORT_SOURCE, buildImport, extendsSuperClass, extractControllers, extractDecoratorArg, extractMiddlewares, extractParams, extractRoutes, extractServices, getClassNode, getMiddlewares, getRoutes, getServices, hasDecorator, normalizePath, resolveImports, scanDir, scanFiles, scanProject, scanSource, transformMiddleware, transformRoute, transformService };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vercube/scan",
+  "version": "1.1.0",
+  "description": "Source scanning and AST extraction utilities for the Vercube framework",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercube/vercube.git",
+    "directory": "packages/scan"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "vercube",
+    "scan",
+    "ast",
+    "framework"
+  ],
+  "dependencies": {
+    "oxc-parser": "0.112.0",
+    "pathe": "2.0.3",
+    "tinyglobby": "0.2.15"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --config ../../tsdown.config.ts --config-loader=unrun"
+  }
+}