@expressots/studio-agent 4.0.0-preview.1 → 4.0.0-preview.3

package/dist/discovery/route-scanner.js

@@ -5,35 +5,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { glob } from 'glob';
-/** Regular expressions for parsing TypeScript/JavaScript files */
-const PATTERNS = {
-    // Match @controller decorator with path
-    controller: /@controller\s*\(\s*['"`]([^'"`]+)['"`]/gi,
-    // Match HTTP method decorators
-    httpMethods: {
-        get: /@Get\s*\(\s*['"`]?([^'"`\)]*)?['"`]?\s*\)/gi,
-        post: /@Post\s*\(\s*['"`]?([^'"`\)]*)?['"`]?\s*\)/gi,
-        put: /@Put\s*\(\s*['"`]?([^'"`\)]*)?['"`]?\s*\)/gi,
-        patch: /@Patch\s*\(\s*['"`]?([^'"`\)]*)?['"`]?\s*\)/gi,
-        delete: /@Delete\s*\(\s*['"`]?([^'"`\)]*)?['"`]?\s*\)/gi,
-        head: /@Head\s*\(\s*['"`]?([^'"`\)]*)?['"`]?\s*\)/gi,
-        options: /@Options\s*\(\s*['"`]?([^'"`\)]*)?['"`]?\s*\)/gi,
-    },
-    // Match class declaration
-    classDeclaration: /class\s+(\w+)/g,
-    // Match constructor injection
-    constructorInjection: /constructor\s*\([^)]*\)/g,
-    // Match @inject decorator
-    inject: /@inject\s*\(\s*(\w+)\s*\)/gi,
-    // Match method declaration
-    methodDeclaration: /(?:async\s+)?(\w+)\s*\([^)]*\)\s*(?::\s*[^{]+)?\s*\{/g,
-    // Match service/provider decorators
-    injectable: /@provide\s*\(\s*(\w+)?\s*\)/gi,
-    // Match middleware decorator
-    middleware: /@middleware\s*\(/gi,
-    // Match scope decorator  
-    scope: /@scope\s*\(\s*(\w+)\s*\)/gi,
-};
+// NOTE: HTTP method decorators, controller decorators, and the
+// `extends ExpressoMiddleware` pattern are matched inline below — the
+// scanner uses balanced-paren walks rather than fragile capture-group
+// regexes so it can handle decorator arguments like
+// `@Get('/x', AuthMw, RoleGuard("admin"))`.
 /**
  * Type names that look like dependencies syntactically but aren't ones we
  * want to plot on the architecture graph. Lowercased for cheap comparison.
@@ -105,24 +81,322 @@ function findConstructorParams(content) {
  *   - multi-modifier combos:       `@inject(SYM) private readonly foo: Foo`
  *   - multiple params separated by commas
  *
+ * For each parameter we return the most useful identifier for the
+ * architecture graph — the `@inject(TOKEN)` argument when present (the
+ * actual DI binding key, which always has a matching provider node),
+ * otherwise the constructor parameter type. This restores edges that
+ * previously dangled when controllers depended on an interface (e.g.
+ * `IUserService`) bound to a concrete class (`UserService`).
+ *
  * The previous implementation captured the access modifier (`private`)
  * instead of the type, so the architecture graph never drew a dependency
  * edge from a controller to its use case.
  */
+/**
+ * Generate a JSON-friendly placeholder for a TypeScript type literal.
+ * Best-effort: union types collapse to the first arm, generics fall back
+ * to `null`, arrays become `[]`. The result is meant to seed an HTTP
+ * client form, not pass strict validation.
+ */
+function sampleForType(typeName) {
+    const t = typeName.trim();
+    // Strip wrapping `()`s and trailing whitespace.
+    const head = t.replace(/^\(+|\)+$/g, '').trim();
+    // Array types: `Foo[]` or `Array<Foo>`.
+    if (/\[\]$/.test(head) || /^Array\s*</i.test(head)) {
+        return [];
+    }
+    // Union — pick the first non-null/undefined arm.
+    if (head.includes('|')) {
+        const arms = head
+            .split('|')
+            .map((a) => a.trim())
+            .filter((a) => a && a !== 'null' && a !== 'undefined');
+        if (arms.length > 0)
+            return sampleForType(arms[0]);
+        return null;
+    }
+    // Strip generics: `Promise<Foo>` → `Promise`. Unhandled below ⇒ null.
+    const bare = head.replace(/<.*$/, '').toLowerCase();
+    switch (bare) {
+        case 'string':
+            return '';
+        case 'number':
+        case 'bigint':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'date':
+            return new Date(0).toISOString();
+        case 'object':
+        case 'record':
+            return {};
+        case 'any':
+        case 'unknown':
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Starting at `fromIndex` in `content`, walk forward to the next method
+ * declaration and return its name + the *balanced* parameter list.
+ *
+ * The previous implementation used a simple `\(([^)]*)\)` regex which
+ * stops at the first `)` it sees — fatal for ExpressoTS controllers
+ * because parameter decorators like `@body()` have their own parens.
+ * That bug caused every route whose handler accepted `@body() / @param() /
+ * @query() / @inject()` to silently disappear from the static scan,
+ * which then forced the runtime scanner to fall back to
+ * `controller: 'Unknown'` (the "Other" group in the Studio API client).
+ *
+ * Returns `null` when no method signature is found.
+ */
+function findNextMethodSignature(content, fromIndex) {
+    // A method signature looks like:
+    //   <visibility?> <static?> <async?> name ( … ) <return-type?> {
+    // We anchor on `name(` — once located we use balanced paren matching to
+    // capture the parameter list, then verify a `{` follows (to skip
+    // forward-declared arrow types or call expressions).
+    const HEAD = /(?:public\s+|private\s+|protected\s+)?(?:static\s+)?(?:async\s+)?([A-Za-z_$][\w$]*)\s*\(/g;
+    HEAD.lastIndex = fromIndex;
+    let match;
+    while ((match = HEAD.exec(content)) !== null) {
+        const name = match[1];
+        // Skip control-flow keywords that look like method names.
+        if (name === 'if' ||
+            name === 'for' ||
+            name === 'while' ||
+            name === 'switch' ||
+            name === 'catch' ||
+            name === 'return') {
+            continue;
+        }
+        const openParen = match.index + match[0].length - 1; // points at '('
+        let depth = 1;
+        let i = openParen + 1;
+        for (; i < content.length && depth > 0; i++) {
+            const ch = content[i];
+            if (ch === '(')
+                depth++;
+            else if (ch === ')')
+                depth--;
+        }
+        if (depth !== 0)
+            return null; // unbalanced — give up
+        const closeParen = i - 1;
+        const params = content.slice(openParen + 1, closeParen);
+        // Walk past the optional return-type annotation up to the first
+        // non-whitespace character after the `)`. Accept `{` as a method
+        // body (skip ahead) and `=>` to also detect arrow assignments
+        // (uncommon in controllers but harmless to allow).
+        let j = closeParen + 1;
+        while (j < content.length && /\s/.test(content[j]))
+            j++;
+        if (content[j] === ':') {
+            // Skip `: ReturnType`
+            while (j < content.length && content[j] !== '{' && content[j] !== ';' && content[j] !== '\n') {
+                j++;
+            }
+            while (j < content.length && /\s/.test(content[j]))
+                j++;
+        }
+        if (content[j] === '{') {
+            return { name, params, absoluteEndIndex: j };
+        }
+        // Not a method body — keep scanning.
+    }
+    return null;
+}
+/**
+ * Extract dependency identifiers from class-level field injection.
+ *
+ * ExpressoTS supports two equivalent DI patterns:
+ *
+ *   1. Constructor injection: `constructor(private foo: Foo) {}`
+ *   2. Field injection:       `@inject(Foo) private foo: Foo;`
+ *
+ * (1) is handled by `findConstructorParams` + `extractParamTypes`. (2)
+ * needs its own scanner because the `@inject(TOKEN)` decorator sits on
+ * a *property* declaration and therefore never appears inside the
+ * constructor parameter list. Without this extractor, the architecture
+ * map showed orphan controllers / services for any project that picked
+ * field injection (the default in the CLI's generated useCase template).
+ *
+ * Returns the most useful identifier per field — the `@inject(TOKEN)`
+ * argument (which is always a real DI binding key) and falls back to
+ * the declared type when the token is missing.
+ */
+function extractFieldInjectionTypes(classBody) {
+    const out = [];
+    const seen = new Set();
+    // `@inject(TOKEN) <visibility?> <readonly?> <name><?> : <Type>;|=`
+    // Token is captured greedily to support `Symbol.for(...)` and
+    // `SYMBOL_TYPES.Foo` style identifiers.
+    const FIELD_INJECT_RE = /@inject\s*\(\s*([\w.$]+)\s*\)\s*(?:public\s+|private\s+|protected\s+)?(?:readonly\s+)?\w+\s*\??\s*:\s*([A-Za-z_$][\w.$]*)/g;
+    let match;
+    while ((match = FIELD_INJECT_RE.exec(classBody)) !== null) {
+        const injectToken = match[1];
+        const typeName = match[2];
+        const candidate = injectToken || typeName;
+        if (!candidate)
+            continue;
+        const head = candidate.split('.').pop() || candidate;
+        if (PRIMITIVE_TYPES.has(head.toLowerCase()))
+            continue;
+        if (seen.has(head))
+            continue;
+        seen.add(head);
+        out.push(head);
+    }
+    return out;
+}
+/**
+ * Capture the full balanced argument list of a decorator call.
+ *
+ * Given `content` and the index of the opening `(` (immediately after
+ * the decorator name), returns the substring between `(` and the
+ * matching `)`. Handles strings, template literals, and nested call
+ * expressions so decorators like
+ *
+ *   @controller("/x", isAuthenticated, RoleGuard("admin"))
+ *
+ * round-trip cleanly. Returns `null` when the parens are unbalanced.
+ */
+function extractBalancedArgs(content, openParenIdx) {
+    if (content[openParenIdx] !== '(')
+        return null;
+    let depth = 1;
+    let i = openParenIdx + 1;
+    while (i < content.length && depth > 0) {
+        const ch = content[i];
+        if (ch === '"' || ch === "'" || ch === '`') {
+            const close = ch;
+            i++;
+            while (i < content.length) {
+                if (content[i] === '\\') {
+                    i += 2;
+                    continue;
+                }
+                if (content[i] === close) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        if (ch === '(')
+            depth++;
+        else if (ch === ')')
+            depth--;
+        i++;
+    }
+    if (depth !== 0)
+        return null;
+    return content.slice(openParenIdx + 1, i - 1);
+}
+/**
+ * Split a decorator argument list on top-level commas, respecting
+ * strings and bracket / paren nesting. Used to peel off the path arg
+ * (always the first entry) from the trailing middleware identifiers.
+ */
+function splitTopLevelArgs(args) {
+    const out = [];
+    let buf = '';
+    let paren = 0;
+    let bracket = 0;
+    let brace = 0;
+    for (let i = 0; i < args.length; i++) {
+        const ch = args[i];
+        if (ch === '"' || ch === "'" || ch === '`') {
+            const close = ch;
+            buf += ch;
+            i++;
+            while (i < args.length) {
+                buf += args[i];
+                if (args[i] === '\\' && i + 1 < args.length) {
+                    buf += args[i + 1];
+                    i += 2;
+                    continue;
+                }
+                if (args[i] === close)
+                    break;
+                i++;
+            }
+            continue;
+        }
+        if (ch === '(')
+            paren++;
+        else if (ch === ')')
+            paren--;
+        else if (ch === '[')
+            bracket++;
+        else if (ch === ']')
+            bracket--;
+        else if (ch === '{')
+            brace++;
+        else if (ch === '}')
+            brace--;
+        if (ch === ',' && paren === 0 && bracket === 0 && brace === 0) {
+            out.push(buf.trim());
+            buf = '';
+            continue;
+        }
+        buf += ch;
+    }
+    const tail = buf.trim();
+    if (tail.length > 0)
+        out.push(tail);
+    return out;
+}
+/**
+ * Extract identifier references from a decorator argument that is
+ * supposed to be a middleware reference. Accepts plain identifiers
+ * (`MyMiddleware`), dotted access (`Mw.User`), and call expressions
+ * (`RoleGuard("admin")`) — the latter still resolves to a single
+ * identifier ("RoleGuard"). Returns `null` when the arg is not an
+ * identifier reference (e.g. a string token, an arrow function, an
+ * object literal). Those forms are real but can't be plotted as an
+ * architecture node from the static scan alone.
+ */
+function middlewareIdentifierFromArg(arg) {
+    const trimmed = arg.trim();
+    if (!trimmed)
+        return null;
+    // Strip a trailing `(...)` so `RoleGuard("admin")` → `RoleGuard`.
+    const match = trimmed.match(/^([A-Za-z_$][\w.$]*)/);
+    if (!match)
+        return null;
+    const head = match[1].split('.').pop();
+    if (!head)
+        return null;
+    // Skip JS reserved words and the path-style identifiers that aren't
+    // class references (e.g. `'/path'` would already have failed the
+    // regex; this catches `null`, `undefined`, `true`, `false`).
+    if (head === 'null' || head === 'undefined' || head === 'true' || head === 'false') {
+        return null;
+    }
+    return head;
+}
 function extractParamTypes(params) {
     const out = [];
     // Anchor each iteration to consume exactly one parameter:
     //   1) Optional `@decorator(...)` prefix(es) — args may contain commas
-    //   2) Optional access modifier
-    //   3) Optional `readonly`
-    //   4) Parameter name
-    //   5) `:` then the captured Type (allow `Foo`, `Ns.Foo`, `Foo<...>`)
-    const PARAM_RE = /(?:@\w+\s*\([^)]*\)\s*)*(?:(?:public|private|protected)\s+)?(?:readonly\s+)?(\w+)\s*:\s*([A-Za-z_$][\w.$]*)/g;
+    //      Capture group 1 isolates the *first* @inject(...) token so we
+    //      can prefer it over the declared type when both are present.
+    //   2) Optional access modifier (and `readonly`)
+    //   3) Parameter name (non-capturing, we don't need it)
+    //   4) `:` then the captured Type (allow `Foo`, `Ns.Foo`, `Foo<...>`)
+    //   5) `?:` is allowed to support optional injection
+    const PARAM_RE = /(?:@\w+\s*\(\s*([\w.$]+)?\s*\)\s*)*(?:(?:public|private|protected)\s+)?(?:readonly\s+)?\w+\s*\??\s*:\s*([A-Za-z_$][\w.$]*)/g;
     for (const match of params.matchAll(PARAM_RE)) {
+        const injectToken = match[1];
         const typeName = match[2];
-        if (!typeName)
+        const candidate = injectToken || typeName;
+        if (!candidate)
             continue;
-        const head = typeName.split('.').pop() || typeName;
+        const head = candidate.split('.').pop() || candidate;
         if (PRIMITIVE_TYPES.has(head.toLowerCase()))
             continue;
         out.push(head);
@@ -136,6 +410,44 @@ export class RouteScanner {
     providers = [];
     middleware = [];
     dependencies = [];
+    /**
+     * Class names of middleware discovered statically. Used to:
+     *   1. Suppress the same class from being added to `services[]`
+     *      (the legacy heuristic promoted any `@provide`-decorated class).
+     *   2. Resolve middleware identifiers parsed out of `@controller`/
+     *      `@Get` arguments to the matching scanner record.
+     */
+    middlewareClassNames = new Set();
+    /**
+     * Bindings extracted from `@controller(path, ...mw)` and route
+     * decorators (`@Get(path, ...mw)`). Each entry is the source of a
+     * future `middleware → controller` edge.
+     */
+    staticMiddlewareBindings = [];
+    /**
+     * Interface → implementation lookup populated from `class X implements IY`.
+     * Used by `buildDependencyGraph` to redirect edges that target an
+     * interface name (e.g. `IUserService`) to the concrete class node
+     * (`UserService`). Without this fallback the architecture map shows
+     * an orphan source node and a dangling edge for every interface-typed
+     * constructor parameter, which is the default ExpressoTS pattern.
+     */
+    implementsMap = new Map();
+    /**
+     * Discovered `CreateModule(...)` declarations. Two-pass: we collect
+     * raw items per module first, then expand nested module references
+     * into their concrete class members so the UI can group nodes by
+     * leaf module without re-doing the resolution.
+     */
+    modules = [];
+    moduleRawItems = new Map();
+    /**
+     * DTO class name → sample JSON body (e.g. `{ name: "", age: 0 }`).
+     * Built from class field declarations during the file pre-pass and
+     * consumed when a controller method has an `@Body()` parameter so the
+     * Studio API client can auto-fill a working request body.
+     */
+    dtoSamples = new Map();
     constructor(srcPath = './src') {
         this.srcPath = path.resolve(srcPath);
     }
@@ -146,23 +458,112 @@ export class RouteScanner {
         this.services = [];
         this.providers = [];
         this.middleware = [];
+        this.middlewareClassNames.clear();
+        this.staticMiddlewareBindings = [];
         this.dependencies = [];
+        this.implementsMap.clear();
+        this.dtoSamples.clear();
+        this.modules = [];
+        this.moduleRawItems.clear();
         // Find all TypeScript files
         const files = await this.findTypeScriptFiles();
+        // First pass: harvest middleware class names so the main parse can
+        // suppress them from the generic `@provide` → service bucket. This
+        // matters because middleware classes are typically also decorated
+        // with `@provide(...)` so they can be DI-resolved when added via
+        // `Middleware.add(new MyMiddleware())`. Without this pre-pass the
+        // architecture map would render every middleware as a "Service"
+        // node and then flag it as orphan because nothing `@inject`s it.
+        for (const file of files) {
+            this.preScanForMiddlewareClasses(file);
+        }
         // Parse each file
         for (const file of files) {
             await this.parseFile(file);
         }
         // Build dependency graph
         this.buildDependencyGraph();
+        // Resolve nested module references after every file has been parsed
+        // (modules can reference other modules declared in different files).
+        this.resolveModules();
         return {
             controllers: this.controllers,
             services: this.services,
             providers: this.providers,
             middleware: this.middleware,
             dependencies: this.dependencies,
+            modules: this.modules,
         };
     }
+    /**
+     * Cheap regex scan to find every class that extends `ExpressoMiddleware`.
+     * Records the class name and creates a `MiddlewareInfo` placeholder
+     * with `scope: 'unknown'`. The scope is upgraded later by
+     * `buildDependencyGraph()` (when the class shows up in a controller
+     * decorator) and by the agent's runtime merge step (for global
+     * middleware added via `Middleware.add()`).
+     */
+    preScanForMiddlewareClasses(filePath) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const re = /class\s+(\w+)(?:\s*<[^>]*>)?\s+extends\s+ExpressoMiddleware\b/g;
+        let match;
+        while ((match = re.exec(content)) !== null) {
+            const name = match[1];
+            if (this.middlewareClassNames.has(name))
+                continue;
+            this.middlewareClassNames.add(name);
+            this.middleware.push({
+                name,
+                filePath,
+                dependencies: [],
+                methods: [],
+                scope: 'unknown',
+            });
+        }
+    }
+    /**
+     * Recursively expand `moduleRawItems` into concrete class members.
+     * A module item that references another module name is replaced with
+     * that module's flattened members. Cycles are guarded with a visited
+     * set so a self-referential module never blows the stack.
+     */
+    resolveModules() {
+        const moduleNames = new Set(this.moduleRawItems.keys());
+        const memo = new Map();
+        const expand = (moduleName, visiting) => {
+            if (memo.has(moduleName))
+                return memo.get(moduleName);
+            if (visiting.has(moduleName))
+                return []; // cycle
+            visiting.add(moduleName);
+            const raw = this.moduleRawItems.get(moduleName);
+            if (!raw) {
+                visiting.delete(moduleName);
+                return [];
+            }
+            const out = new Set();
+            for (const item of raw.items) {
+                if (moduleNames.has(item)) {
+                    for (const sub of expand(item, visiting))
+                        out.add(sub);
+                }
+                else {
+                    out.add(item);
+                }
+            }
+            visiting.delete(moduleName);
+            const result = [...out];
+            memo.set(moduleName, result);
+            return result;
+        };
+        for (const [name, raw] of this.moduleRawItems) {
+            this.modules.push({
+                name,
+                filePath: raw.filePath,
+                members: expand(name, new Set()),
+            });
+        }
+    }
     /** Get all discovered routes */
     getRoutes() {
         return this.controllers.flatMap((c) => c.routes);
@@ -183,6 +584,88 @@ export class RouteScanner {
     async parseFile(filePath) {
         const content = fs.readFileSync(filePath, 'utf-8');
         const lines = content.split('\n');
+        // Record every `class X implements IY[, IZ]` so the dependency graph
+        // can redirect interface-typed edges to the concrete class node.
+        // We do this regardless of whether the class is a controller, service
+        // or provider — interfaces can be implemented anywhere.
+        const implementsRe = /class\s+(\w+)(?:\s+extends\s+[\w.<>,\s]+)?\s+implements\s+([\w.<>,\s]+?)\s*\{/g;
+        let implMatch;
+        while ((implMatch = implementsRe.exec(content)) !== null) {
+            const className = implMatch[1];
+            const ifaces = implMatch[2]
+                .split(',')
+                .map((s) => s.trim().replace(/<.*$/, '').split('.').pop())
+                .filter(Boolean);
+            for (const iface of ifaces) {
+                // Only register if not already mapped — first hit wins, which
+                // matches the typical "one impl per interface" convention.
+                if (!this.implementsMap.has(iface)) {
+                    this.implementsMap.set(iface, className);
+                }
+            }
+        }
+        // Build DTO samples for every class / interface / type-alias whose
+        // name matches the convention (`*Dto`, `*Request`, `*Payload`,
+        // `*Input`, `*Body`, including upper-case `*DTO` etc). We register
+        // each sample under its declared name *and* — when the name starts
+        // with `I` (the interface-prefix convention) — under the
+        // I-stripped name too, so a route typed `@body() x: IFooDto` finds
+        // the sample built from `interface IFooDto` or class `FooDto`.
+        const isDtoLike = (n) => /(Dto|Request|Payload|Input|Body)$/i.test(n);
+        const registerSample = (declaredName, sample) => {
+            if (Object.keys(sample).length === 0)
+                return;
+            this.dtoSamples.set(declaredName, sample);
+            if (declaredName.startsWith('I') && declaredName.length > 1) {
+                const stripped = declaredName.slice(1);
+                if (!this.dtoSamples.has(stripped)) {
+                    this.dtoSamples.set(stripped, sample);
+                }
+            }
+        };
+        const fieldRe = /^[ \t]*(?:public\s+|private\s+|protected\s+)?(?:readonly\s+)?(\w+)\s*\??\s*:\s*([A-Za-z_$][\w.<>[\]|\s'"]*?)\s*[;=,]/gm;
+        const buildSampleFromBody = (body) => {
+            const sample = {};
+            fieldRe.lastIndex = 0;
+            let fieldMatch;
+            while ((fieldMatch = fieldRe.exec(body)) !== null) {
+                const fieldName = fieldMatch[1];
+                const typeName = fieldMatch[2];
+                if (fieldName === 'constructor')
+                    continue;
+                sample[fieldName] = sampleForType(typeName);
+            }
+            return sample;
+        };
+        // (a) Classes — same shape as before but with a permissive header.
+        const classRe = /class\s+(\w+)(?:\s+extends\s+[\w.<>,\s]+)?(?:\s+implements\s+[\w.<>,\s]+)?\s*\{([\s\S]*?)\n\}/g;
+        let classMatch;
+        while ((classMatch = classRe.exec(content)) !== null) {
+            const declaredName = classMatch[1];
+            if (!isDtoLike(declaredName))
+                continue;
+            registerSample(declaredName, buildSampleFromBody(classMatch[2]));
+        }
+        // (b) Interfaces — `interface IUserCreateRequestDTO { … }` with
+        // optional `extends Foo, Bar`.
+        const interfaceRe = /interface\s+(\w+)(?:\s+extends\s+[\w.<>,\s]+)?\s*\{([\s\S]*?)\n\}/g;
+        let interfaceMatch;
+        while ((interfaceMatch = interfaceRe.exec(content)) !== null) {
+            const declaredName = interfaceMatch[1];
+            if (!isDtoLike(declaredName))
+                continue;
+            registerSample(declaredName, buildSampleFromBody(interfaceMatch[2]));
+        }
+        // (c) Type aliases — `type FooDto = { … }`. Generic + intersection
+        // forms are out of scope; we only care about the inline-object case.
+        const typeAliasRe = /type\s+(\w+)\s*=\s*\{([\s\S]*?)\n\}/g;
+        let typeAliasMatch;
+        while ((typeAliasMatch = typeAliasRe.exec(content)) !== null) {
+            const declaredName = typeAliasMatch[1];
+            if (!isDtoLike(declaredName))
+                continue;
+            registerSample(declaredName, buildSampleFromBody(typeAliasMatch[2]));
+        }
         // Check if this is a controller
         const controllerMatch = content.match(/@controller\s*\(\s*['"`]([^'"`]+)['"`]/i);
         if (controllerMatch) {
@@ -192,27 +675,102 @@ export class RouteScanner {
                 this.controllers.push(controller);
             }
         }
-        // Check if this is a service/provider
-        const injectableMatch = content.match(/@provide\s*\(/i);
-        if (injectableMatch) {
-            const service = this.parseService(content, filePath);
-            if (service) {
-                // Determine if it's a service or provider based on naming
-                if (filePath.includes('provider') ||
-                    service.name.toLowerCase().includes('provider')) {
-                    this.providers.push(service);
+        // Check if this is a service/provider. We require the file to
+        // contain at least one `@provide(<Identifier>) ... class <X>` pair
+        // so that arbitrary uses of `provide` (e.g. methods named `provide`,
+        // doc-comments, mock objects in tests) don't get promoted to ghost
+        // services. The pair is matched with a lookahead that allows the
+        // typical `@provide(Foo) @scope(...) export class Foo` formatting.
+        //
+        // Classes we already classified as middleware (in the pre-pass) are
+        // skipped so they don't end up as both a "Service" and a
+        // "Middleware" node — `Middleware.add(new MyMw())` requires the
+        // class to be DI-bound, so middleware is almost always also
+        // `@provide`-decorated.
+        const provideClassRe = /@provide\s*\(\s*([\w.$]+)?\s*\)[\s\S]{0,400}?\bclass\s+(\w+)/g;
+        const provideMatches = [...content.matchAll(provideClassRe)];
+        for (const match of provideMatches) {
+            const declaredClass = match[2];
+            if (this.middlewareClassNames.has(declaredClass)) {
+                // Hydrate the middleware record with constructor / field
+                // dependencies and method names. We piggy-back on
+                // `parseService` because the extraction logic is identical
+                // (DI deps come from the same decorators).
+                const enriched = this.parseService(content, filePath, declaredClass);
+                if (enriched) {
+                    const target = this.middleware.find((m) => m.name === declaredClass);
+                    if (target) {
+                        target.dependencies = enriched.dependencies;
+                        target.methods = enriched.methods;
+                    }
+                }
+                continue;
+            }
+            const service = this.parseService(content, filePath, declaredClass);
+            if (!service)
+                continue;
+            // Determine if it's a service or provider based on naming
+            if (filePath.includes('provider') ||
+                service.name.toLowerCase().includes('provider')) {
+                this.providers.push(service);
+            }
+            else {
+                this.services.push(service);
+            }
+        }
+        // Detect `export const Foo = CreateModule([Bar, Baz])`. Anonymous
+        // inline modules (e.g. inside `configContainer([CreateModule([...])])`)
+        // are skipped — only named exports get a UI grouping. We capture the
+        // bracket contents with a balanced-bracket walk so multi-line arrays
+        // and nested `CreateModule(...)` calls aren't truncated.
+        const moduleHeadRe = /(?:export\s+)?const\s+(\w+)\s*(?::\s*[\w<>,\s]+)?\s*=\s*CreateModule\s*\(\s*\[/g;
+        let mhMatch;
+        while ((mhMatch = moduleHeadRe.exec(content)) !== null) {
+            const moduleName = mhMatch[1];
+            const arrayStart = mhMatch.index + mhMatch[0].length;
+            let depth = 1;
+            let i = arrayStart;
+            for (; i < content.length && depth > 0; i++) {
+                const ch = content[i];
+                if (ch === '[')
+                    depth++;
+                else if (ch === ']')
+                    depth--;
+            }
+            if (depth !== 0)
+                continue; // malformed — skip
+            const arrayBody = content.slice(arrayStart, i - 1);
+            // Split on commas at depth 0 (so `CreateModule([…])` nested
+            // expressions stay intact). Then trim whitespace / trailing
+            // commas, and accept identifiers only.
+            const items = [];
+            let bracketDepth = 0;
+            let parenDepth = 0;
+            let buf = '';
+            for (const ch of arrayBody) {
+                if (ch === '[' || ch === '{')
+                    bracketDepth++;
+                else if (ch === ']' || ch === '}')
+                    bracketDepth--;
+                else if (ch === '(')
+                    parenDepth++;
+                else if (ch === ')')
+                    parenDepth--;
+                if (ch === ',' && bracketDepth === 0 && parenDepth === 0) {
+                    const id = buf.trim();
+                    if (/^[A-Za-z_$][\w.$]*$/.test(id))
+                        items.push(id.split('.').pop());
+                    buf = '';
                 }
                 else {
-                    this.services.push(service);
+                    buf += ch;
                 }
             }
-        }
-        // Check for middleware
-        const middlewareMatch = content.match(/@middleware\s*\(/i);
-        if (middlewareMatch) {
-            const classMatch = content.match(/class\s+(\w+)/);
-            if (classMatch) {
-                this.middleware.push(classMatch[1]);
+            const tail = buf.trim();
+            if (/^[A-Za-z_$][\w.$]*$/.test(tail))
+                items.push(tail.split('.').pop());
+            if (items.length > 0) {
+                this.moduleRawItems.set(moduleName, { filePath, items });
             }
         }
     }
@@ -225,35 +783,121 @@ export class RouteScanner {
         const className = classMatch[1];
         const routes = [];
         const dependencies = [];
-        // Extract constructor dependencies. We use a balanced-paren scanner
-        // here because parameter decorators (@inject(MyService)) contain
-        // their own parentheses and a naive `[^)]*` regex would truncate
-        // the parameter list at the wrong `)`.
+        // Extract controller-level middleware from `@controller(path, ...mw)`.
+        // Walk the full balanced arg list so call-expression middleware
+        // (`RoleGuard("admin")`) and multi-line decorators are handled.
+        const ctrlDecoratorIdx = content.search(/@controller\s*\(/i);
+        if (ctrlDecoratorIdx >= 0) {
+            const openParen = content.indexOf('(', ctrlDecoratorIdx);
+            const args = openParen >= 0 ? extractBalancedArgs(content, openParen) : null;
+            if (args) {
+                const parts = splitTopLevelArgs(args);
+                // First entry is always the path string — skip it.
+                for (const part of parts.slice(1)) {
+                    const ident = middlewareIdentifierFromArg(part);
+                    if (!ident)
+                        continue;
+                    this.staticMiddlewareBindings.push({
+                        middlewareName: ident,
+                        controllerName: className,
+                        scope: 'controller',
+                    });
+                }
+            }
+        }
+        // Extract constructor-style dependencies. Balanced-paren aware so
+        // parameter decorators (@inject(MyService)) don't truncate the
+        // parameter list at the wrong `)`.
         const params = findConstructorParams(content);
         if (params) {
             dependencies.push(...extractParamTypes(params));
         }
-        // Find HTTP method decorators
-        for (const [method, regex] of Object.entries(PATTERNS.httpMethods)) {
-            regex.lastIndex = 0;
-            let match;
-            while ((match = regex.exec(content)) !== null) {
-                const routePath = match[1] || '/';
-                const lineNumber = this.getLineNumber(content, match.index, lines);
-                // Find the method name (next function after decorator)
-                const afterDecorator = content.slice(match.index);
-                const methodMatch = afterDecorator.match(/(?:async\s+)?(\w+)\s*\([^)]*\)\s*(?::\s*[^{]+)?\s*\{/);
-                if (methodMatch) {
-                    routes.push({
-                        path: this.normalizePath(basePath, routePath),
-                        method: method.toUpperCase(),
-                        controller: className,
-                        controllerMethod: methodMatch[1],
-                        filePath,
-                        lineNumber,
-                    });
+        // Also extract field-injection dependencies — the default pattern
+        // produced by `expressots g controller`. Without this the
+        // architecture map shows the controller as an isolated node even
+        // though it's wired to a use case via `@inject(UseCase)`.
+        const ctrlBodyRe = new RegExp(`class\\s+${className}\\b(?:\\s+extends\\s+[\\w.<>,\\s]+)?(?:\\s+implements\\s+[\\w.<>,\\s]+)?\\s*\\{([\\s\\S]*?)\\n\\}`);
+        const ctrlBody = content.match(ctrlBodyRe)?.[1] ?? '';
+        if (ctrlBody) {
+            for (const dep of extractFieldInjectionTypes(ctrlBody)) {
+                if (!dependencies.includes(dep))
+                    dependencies.push(dep);
+            }
+        }
+        // Find HTTP method decorators. Each match advances a balanced-paren
+        // method-signature scanner so handlers with parameter decorators
+        // (`@body()`, `@param()`, `@inject()`, …) are still detected. We
+        // ignore the original regex's captured path because it stops at
+        // the first `)` — fine for `@Get('/x')` but breaks for
+        // `@Get('/x', AuthMw, RoleGuard("admin"))`. Instead we walk the
+        // full balanced arg list ourselves and split on top-level commas.
+        const httpDecoratorRe = /@(Get|Post|Put|Patch|Delete|Head|Options)\s*\(/gi;
+        let match;
+        while ((match = httpDecoratorRe.exec(content)) !== null) {
+            const method = match[1].toLowerCase();
+            const openParen = match.index + match[0].length - 1;
+            const args = extractBalancedArgs(content, openParen);
+            const parts = args !== null ? splitTopLevelArgs(args) : [];
+            // First arg is the path. May be quoted; strip the quotes.
+            let routePath = '/';
+            if (parts.length > 0) {
+                const raw = parts[0].trim();
+                const m = raw.match(/^['"`]([^'"`]*)['"`]$/);
+                if (m)
+                    routePath = m[1] || '/';
+            }
+            const lineNumber = this.getLineNumber(content, match.index, lines);
+            const sig = findNextMethodSignature(content, match.index);
+            if (!sig)
+                continue;
+            const route = {
+                path: this.normalizePath(basePath, routePath),
+                method: method.toUpperCase(),
+                controller: className,
+                controllerMethod: sig.name,
+                filePath,
+                lineNumber,
+            };
+            // Trailing decorator args after the path are middleware refs.
+            // We record bindings for every identifier-shaped arg so the
+            // architecture map can draw a `middleware → controller` edge
+            // labelled with the route. Non-identifier args (string registry
+            // names, inline arrow functions) are silently skipped — the
+            // adapter's runtime collector picks those up later.
+            for (const part of parts.slice(1)) {
+                const ident = middlewareIdentifierFromArg(part);
+                if (!ident)
+                    continue;
+                this.staticMiddlewareBindings.push({
+                    middlewareName: ident,
+                    controllerName: className,
+                    scope: 'route',
+                    controllerMethod: sig.name,
+                });
+            }
+            // Detect `@Body() name: DtoType` (case-insensitive — the
+            // decorator is exported as both `Body` and `body` from
+            // adapter-express). Captured groups:
+            //   1 = parameter name (informational)
+            //   2 = parameter type (the DTO class / interface name)
+            const bodyParamRe = /@body\s*\(\s*\)\s*(\w+)\s*\??\s*:\s*([A-Za-z_$][\w.$]*)/i;
+            const bodyMatch = sig.params.match(bodyParamRe);
+            if (bodyMatch) {
+                const rawDtoName = bodyMatch[2].split('.').pop() || bodyMatch[2];
+                route.bodyDto = rawDtoName;
+                // Look up the inferred sample. Try the literal name first, then
+                // strip a leading `I` (the common interface-prefix convention,
+                // e.g. `IUserCreateRequestDTO` → `UserCreateRequestDTO`) so a
+                // sample harvested from the implementing class still applies.
+                const sample = this.dtoSamples.get(rawDtoName) ??
+                    (rawDtoName.startsWith('I')
+                        ? this.dtoSamples.get(rawDtoName.slice(1))
+                        : undefined);
+                if (sample) {
+                    route.bodySample = sample;
                 }
             }
+            routes.push(route);
         }
         return {
             name: className,
@@ -262,12 +906,31 @@ export class RouteScanner {
             dependencies,
         };
     }
-    /** Parse service from file content */
-    parseService(content, filePath) {
-        const classMatch = content.match(/class\s+(\w+)/);
-        if (!classMatch)
-            return null;
-        const className = classMatch[1];
+    /**
+     * Parse service from file content.
+     *
+     * `declaredClass` is the class name that the caller already verified
+     * is paired with an `@provide()` decorator. We use it instead of the
+     * first `class \w+` match to avoid mis-tagging unrelated classes (e.g.
+     * a test fixture) as services when a single file has more than one.
+     */
+    parseService(content, filePath, declaredClass) {
+        let className = null;
+        if (declaredClass) {
+            // Confirm the requested class actually exists in the file before
+            // we report it as a service. Belt-and-braces — the caller already
+            // matched it against `@provide(...)`.
+            const found = new RegExp(`class\\s+${declaredClass}\\b`).test(content);
+            if (!found)
+                return null;
+            className = declaredClass;
+        }
+        else {
+            const classMatch = content.match(/class\s+(\w+)/);
+            if (!classMatch)
+                return null;
+            className = classMatch[1];
+        }
         const dependencies = [];
         const methods = [];
         // Extract constructor dependencies (same parser as controllers so the
@@ -277,13 +940,65 @@ export class RouteScanner {
         if (params) {
             dependencies.push(...extractParamTypes(params));
         }
-        // Extract public methods (simplified)
-        const methodMatches = content.matchAll(/(?:public\s+)?(?:async\s+)?(\w+)\s*\([^)]*\)\s*(?::\s*[^{]+)?\s*\{/g);
+        // Pull the specific class body once — used for both method
+        // discovery and field-injection extraction.
+        const classBodyRe = new RegExp(`class\\s+${className}\\b(?:\\s+extends\\s+[\\w.<>,\\s]+)?(?:\\s+implements\\s+[\\w.<>,\\s]+)?\\s*\\{([\\s\\S]*?)\\n\\}`);
+        const classBody = content.match(classBodyRe)?.[1] ?? '';
+        // Field-injection dependencies — `@inject(Foo) private foo: Foo;`.
+        // Required for any service that wires its collaborators via
+        // property decorators instead of a constructor.
+        if (classBody) {
+            for (const dep of extractFieldInjectionTypes(classBody)) {
+                if (!dependencies.includes(dep))
+                    dependencies.push(dep);
+            }
+        }
+        // Extract public methods. We scan the specific class body (not the
+        // first `class { … }` we find, and not the whole file) and skip JS
+        // control-flow keywords so statements like `if (x.is(y)) {` don't
+        // get reported as methods (which produced bogus services like
+        // "is" with 1 method on the architecture map).
+        const KEYWORD_BLOCKLIST = new Set([
+            'if',
+            'else',
+            'for',
+            'while',
+            'do',
+            'switch',
+            'case',
+            'try',
+            'catch',
+            'finally',
+            'return',
+            'throw',
+            'new',
+            'await',
+            'yield',
+            'typeof',
+            'instanceof',
+            'in',
+            'of',
+            'function',
+            'class',
+            'this',
+            'super',
+            'is',
+        ]);
+        // Method declarations start at the beginning of a line (modulo
+        // indentation). Anchoring to ^/`m` flag prevents matches inside
+        // expression bodies.
+        const methodMatches = classBody.matchAll(/^[ \t]*(?:public\s+|private\s+|protected\s+)?(?:static\s+)?(?:async\s+)?(\w+)\s*\([^)]*\)\s*(?::\s*[^{;]+)?\s*\{/gm);
+        const seenMethods = new Set();
         for (const match of methodMatches) {
             const methodName = match[1];
-            if (methodName !== 'constructor' && !methodName.startsWith('_')) {
-                methods.push(methodName);
+            if (methodName === 'constructor' ||
+                methodName.startsWith('_') ||
+                KEYWORD_BLOCKLIST.has(methodName) ||
+                seenMethods.has(methodName)) {
+                continue;
             }
+            seenMethods.add(methodName);
+            methods.push(methodName);
         }
         return {
             name: className,
@@ -294,12 +1009,37 @@ export class RouteScanner {
     }
     /** Build the dependency graph */
     buildDependencyGraph() {
+        // Set of node names that actually exist in the graph. Edges that
+        // target a non-existent node are dangling and will be redirected
+        // through `implementsMap` if possible.
+        const nodeNames = new Set();
+        for (const c of this.controllers)
+            nodeNames.add(c.name);
+        for (const s of this.services)
+            nodeNames.add(s.name);
+        for (const p of this.providers)
+            nodeNames.add(p.name);
+        for (const m of this.middleware)
+            nodeNames.add(m.name);
+        // Resolve a raw dependency identifier (an @inject token or declared
+        // type name) to the concrete class node when possible. This restores
+        // edges for the common pattern where a controller depends on an
+        // interface (`IUserService`) that's implemented by a concrete class
+        // (`UserService`) registered as the provider.
+        const resolveTarget = (raw) => {
+            if (nodeNames.has(raw))
+                return raw;
+            const mapped = this.implementsMap.get(raw);
+            if (mapped && nodeNames.has(mapped))
+                return mapped;
+            return raw;
+        };
         // Add controller -> service dependencies
         for (const controller of this.controllers) {
             for (const dep of controller.dependencies) {
                 this.dependencies.push({
                     source: controller.name,
-                    target: dep,
+                    target: resolveTarget(dep),
                     type: 'controller',
                 });
             }
@@ -309,13 +1049,53 @@ export class RouteScanner {
             for (const dep of service.dependencies) {
                 this.dependencies.push({
                     source: service.name,
-                    target: dep,
+                    target: resolveTarget(dep),
                     type: service.name.toLowerCase().includes('provider')
                         ? 'provider'
                         : 'service',
                 });
             }
         }
+        // Add middleware -> controller edges from the static decorator
+        // scan. Direction is middleware → controller because the
+        // architecture map reads them as "this middleware protects /
+        // wraps that controller", which matches the request flow.
+        //
+        // Bindings whose middleware identifier doesn't resolve to a known
+        // class node are skipped silently. Common reasons:
+        //   - imported from a third-party package the scanner doesn't
+        //     reach (e.g. `helmet`, `cors`)
+        //   - bound by string registry name (`use('auth')`) — the runtime
+        //     collector will surface those instead.
+        const seenMiddlewareEdge = new Set();
+        for (const binding of this.staticMiddlewareBindings) {
+            const sourceName = binding.middlewareName;
+            if (!nodeNames.has(sourceName))
+                continue;
+            if (!nodeNames.has(binding.controllerName))
+                continue;
+            const key = `${sourceName}->${binding.controllerName}@${binding.scope}`;
+            if (seenMiddlewareEdge.has(key))
+                continue;
+            seenMiddlewareEdge.add(key);
+            this.dependencies.push({
+                source: sourceName,
+                target: binding.controllerName,
+                type: 'middleware',
+            });
+            // Promote the middleware's scope based on how it's wired.
+            // `controller` overrides `route` because a middleware applied at
+            // both levels is most usefully described as controller-scoped.
+            const mw = this.middleware.find((m) => m.name === sourceName);
+            if (mw) {
+                if (binding.scope === 'controller') {
+                    mw.scope = 'controller';
+                }
+                else if (mw.scope !== 'controller') {
+                    mw.scope = 'route';
+                }
+            }
+        }
     }
     /** Get line number for a position in content */
     getLineNumber(_content, position, lines) {
@@ -348,37 +1128,79 @@ export class RouteScanner {
     /** Scan Express app for routes (runtime) */
     static scanExpressApp(app) {
         const routes = [];
-        if (!app || !app._router) {
+        // Express 5 renamed `app._router` to `app.router`. Fall back gracefully
+        // so the agent stays compatible with both major versions.
+        const router = app?._router ?? app?.router;
+        if (!app || !router?.stack) {
             return routes;
         }
+        // Standard HTTP-7. Anything outside this set (ACL, BIND, CHECKOUT,
+        // M-SEARCH, PROPFIND, SUBSCRIBE, …) is a low-level WebDAV / IETF
+        // extension verb. Express's underlying `methods` library exposes them
+        // all by default, which made the API client's "Discovered routes"
+        // chips list 30+ entries per `app.use(middleware)` layer. Filtering
+        // here keeps the picker focused on what users actually expose.
+        const STANDARD_METHODS = new Set([
+            'GET',
+            'POST',
+            'PUT',
+            'PATCH',
+            'DELETE',
+            'HEAD',
+            'OPTIONS',
+        ]);
         const extractRoutes = (stack, basePath = '') => {
             for (const layer of stack) {
                 if (layer.route) {
-                    // This is a route
                     const route = layer.route;
-                    const methods = Object.keys(route.methods).filter((m) => route.methods[m]);
+                    // Skip catch-all paths registered as routes. Those are almost
+                    // always framework / middleware artefacts (e.g. `app.use(...)`
+                    // promoted to a route in some Express 5 builds), not user
+                    // endpoints worth surfacing in the API client.
+                    if (!route.path || route.path === '*' || route.path === '/*') {
+                        continue;
+                    }
+                    const methods = Object.keys(route.methods)
+                        .filter((m) => route.methods[m])
+                        .map((m) => m.toUpperCase())
+                        .filter((m) => STANDARD_METHODS.has(m));
                     for (const method of methods) {
                         routes.push({
                             path: basePath + route.path,
-                            method: method.toUpperCase(),
+                            method,
                             controller: 'Unknown',
                             controllerMethod: 'Unknown',
                         });
                     }
                 }
-                else if (layer.name === 'router' && layer.handle.stack) {
-                    // This is a nested router
-                    const routerPath = layer.regexp.source
-                        .replace('\\/?(?=\\/|$)', '')
-                        .replace(/\\\//g, '/')
-                        .replace(/\^/g, '')
-                        .replace(/\$/g, '')
-                        .replace(/\(\?:\(\[\^\\\/\]\+\?\)\)/g, ':param');
+                else if (layer.name === 'router' && layer.handle?.stack) {
+                    // This is a nested router. Express 5 attaches the mount path
+                    // directly as `layer.path` (a literal string like `/api`), so
+                    // we prefer that. Older Express 4 layers only exposed
+                    // `layer.regexp`, which we still parse as a fallback.
+                    //
+                    // Both fields can legitimately be missing — e.g. when the
+                    // router is mounted at the root (`app.use(router)`), Express
+                    // 5 omits `regexp` entirely. Treating that as an empty
+                    // prefix is correct; trying to read `.source` blew up the
+                    // whole scan with "Cannot read properties of undefined".
+                    let routerPath = '';
+                    if (typeof layer.path === 'string') {
+                        routerPath = layer.path;
+                    }
+                    else if (layer.regexp?.source) {
+                        routerPath = layer.regexp.source
+                            .replace('\\/?(?=\\/|$)', '')
+                            .replace(/\\\//g, '/')
+                            .replace(/\^/g, '')
+                            .replace(/\$/g, '')
+                            .replace(/\(\?:\(\[\^\\\/\]\+\?\)\)/g, ':param');
+                    }
                     extractRoutes(layer.handle.stack, basePath + routerPath);
                 }
             }
         };
-        extractRoutes(app._router.stack);
+        extractRoutes(router.stack);
         return routes;
     }
 }