@vayo-hq/ast 0.1.1-beta.0

package/README.md

@@ -0,0 +1,62 @@
+# @vayo-hq/ast
+
+Vayo's static analysis pass — the part of `vayo scan` that reads your
+Express app's source without needing any traffic first.
+
+Given a bootstrapped Express app (`export default app` or `export const
+app`), `scanProject(rootDir, config)` uses `express-list-endpoints` +
+`ts-morph` to recover, per route: the middleware chain, an auth-required
+guess (configurable middleware-name patterns), scopes (configurable
+scope-check function names), a folder/group guess from your route file
+layout, and — when your project uses Zod or a plain Mongoose model — a
+best-effort request body schema, all without executing a single request.
+
+```ts
+import { scanProject, type VayoConfig } from "@vayo-hq/ast";
+
+const config: VayoConfig = { appEntryPath: "./src/app.js" };
+const { routes } = await scanProject(process.cwd(), config);
+```
+
+## Optional JSDoc tags
+
+A route's leading comment can carry explicit tags — recognized only inside
+a comment that also has a bare `@vayo` sentinel line, so an unrelated TODO
+or workaround comment is never misread as a declaration:
+
+```js
+/**
+ * Fetch a single order by ID.
+ * @vayo
+ * @group Orders
+ * @deprecated
+ * @response 200 OrderSchema
+ * @example 404 {"message": "Order not found"}
+ * @description
+ * Longer, multi-line explanation of this endpoint — the counterpart to
+ * the one-line summary above.
+ */
+router.get("/orders/:id", getOrder);
+```
+
+- **`@group <name>`** (nested: `@group Admin/Users`) wins over both the
+  folder-layout guess and the URL-segment fallback, and locks the
+  endpoint's folder placement against being dragged elsewhere in the UI.
+- **`@deprecated`** marks the endpoint deprecated independent of its API
+  version's own lifecycle, and locks it against being un-deprecated in
+  the UI.
+- **`@response <status> <SchemaName>`** points at an existing Zod schema
+  to use for that status code's response shape.
+- **`@example <status> <JSON>`** provides a literal example response
+  value for a status code.
+- **`@description`** fills in a longer, multi-line description separate
+  from the one-line `summary` every route already gets for free.
+
+Most people never call this directly —
+[`vayo`](https://www.npmjs.com/package/vayo)'s `vayo scan` command
+is the intended entry point. This package exists standalone for anyone
+building custom tooling around the same static pass.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,240 @@
+import { Project, type CallExpression } from "ts-morph";
+import type { JSONSchema } from "@vayo-hq/types";
+export declare const DEFAULT_AUTH_MIDDLEWARE_PATTERNS: string[];
+export declare const DEFAULT_SCOPE_CHECK_PATTERNS: string[];
+/** Body-validation middleware names to recognize a Zod schema argument
+ * against (docs/04-capture-engine.md Step 2 #3) — configurable the same way
+ * auth/scope patterns are, since every team names this differently. */
+export declare const DEFAULT_VALIDATION_MIDDLEWARE_PATTERNS: string[];
+export interface VayoConfig {
+    appEntryPath: string;
+    authMiddlewarePatterns?: string[];
+    scopeCheckPatterns?: string[];
+    validationMiddlewarePatterns?: string[];
+    redact?: string[];
+}
+export interface StaticRouteResult {
+    method: string;
+    pathTemplate: string;
+    middlewareChain: string[];
+    authRequiredGuess: boolean;
+    scopes: string[];
+    group: string;
+    /** "declared" when an explicit `@group <name>` tag was found in the
+     * route's leading comment (swagger-jsdoc's own convention), "inferred"
+     * when `group` instead came from the `routes/` file-layout convention or
+     * the URL-segment fallback (docs/04-capture-engine.md Step 2 #4). Lets
+     * the UI treat a `"declared"` grouping as authoritative — e.g. refusing
+     * to let a drag-and-drop move it to a different sidebar folder, since
+     * that would silently diverge from what the code itself says. */
+    groupSource: "declared" | "inferred";
+    summary: string | null;
+    /** Longer, potentially multi-line/multi-paragraph explanation from an
+     * explicit `@description` tag — OpenAPI's own standard Operation Object
+     * distinguishes this from `summary` (a short one-liner); see
+     * `extractDescription`. `null` when absent, same as `summary`. */
+    description: string | null;
+    /** True when an explicit bare `@deprecated` tag was found in the route's
+     * leading comment (the same OpenAPI/swagger-jsdoc convention `deprecated:
+     * true` on an Operation Object mirrors) — docs/04-capture-engine.md Step
+     * 2 #4a. Always `false` when absent; there's no inferred/guessed
+     * "probably deprecated" signal the way `group` has multiple fallbacks. */
+    deprecated: boolean;
+    /** A Zod- or Mongoose-derived request body shape, when one could be
+     * traced statically — see `findRequestSchemaForRoute`/
+     * `findMongooseRequestSchemaForRoute` below. `null` (not an empty
+     * object) when nothing was found, so a merge never mistakes "found
+     * nothing" for "this endpoint genuinely takes no body." */
+    requestSchema: JSONSchema | null;
+    /** "declared" when `requestSchema` came from a Zod schema the code
+     * itself validates against, "inferred" when it came from a Mongoose
+     * model's schema instead (docs/03-data-model.md) — `null` exactly when
+     * `requestSchema` is. */
+    requestSchemaSource: "declared" | "inferred" | null;
+    /** Response body shape(s) declared via one or more `@response <status>
+     * <SchemaName>` tags in the route's leading comment, keyed by status code
+     * (docs/04-capture-engine.md Step 2 #4b) — see `extractDeclaredResponseSchemas`
+     * below. Empty when none were found; unlike `requestSchema` there's no
+     * "inferred" convention for a response shape (no Mongoose-model
+     * equivalent for "what does this endpoint send back"), so a declared
+     * response schema is always high-confidence when present at all. */
+    declaredResponseSchemas: Record<string, JSONSchema>;
+    /** Literal example response value(s) declared via one or more `@example
+     * <status> <JSON>` tags, keyed by status code — see
+     * `extractDeclaredExamples` below. Empty when none were found. */
+    declaredExamples: Record<string, unknown>;
+}
+export interface StaticScanResult {
+    routes: StaticRouteResult[];
+}
+/** Folder/mount-path convention (docs/04-capture-engine.md Step 2 #4): a
+ * route registered from a file under `routes/orders/*.ts` -> "Orders", and
+ * one under `routes/admin/users/*.ts` -> "Admin/Users" — every directory
+ * segment between `routes/` and the file itself becomes one level of the
+ * "/"-separated group path, so `@vayo-hq/db-mongo`'s `autoOrganizeFolders` can
+ * turn a nested route-file layout into real nested sidebar folders instead
+ * of flattening it to one level. Falls back to the first meaningful path
+ * segment (never nested — a URL's own segments aren't a reliable
+ * organizational signal the way a deliberate file layout is) when the entry
+ * file isn't organized that way at all (e.g. a single flat app.ts, as in
+ * the demo app). */
+export declare function inferGroup(pathTemplate: string, sourceFilePath: string): string;
+/** True when `registrationPath` (a literal string found at a route
+ * registration site, e.g. `router.get("/:id", ...)`) resolves to
+ * `runtimePath` (the fully-mounted path `express-list-endpoints` reports,
+ * e.g. `/api/admin/products/:id`). Exact equality covers routes registered
+ * directly on `app` with their full path repeated (today's flat demo-app
+ * style); segment-suffix equality covers `express.Router()` composition
+ * mounted via `app.use(prefix, router)` at any nesting depth — the router's
+ * own registration only ever sees its path relative to wherever it gets
+ * mounted, but `express-list-endpoints` resolves the live app's actual
+ * router stack at runtime, so the runtime path is always the source of
+ * truth here; only the static side needs to tolerate the prefix it can't
+ * see. Segment-based (not raw substring) so `/id` can never accidentally
+ * suffix-match inside `/userid`. */
+export declare function pathSegmentsMatch(registrationPath: string, runtimePath: string): boolean;
+/** Joins an `express.Router()`'s own relative registration path onto the
+ * literal prefix it's mounted at (`app.use(prefix, router)`) — mirrors how
+ * Express itself resolves it, including the router-root special case
+ * (`router.get("/", ...)` mounted at `prefix` resolves to exactly `prefix`,
+ * not `prefix + "/"`). Empty `prefix` (a registration found directly on
+ * `app`, never resolved through a mount call) is a no-op, so today's flat
+ * style keeps matching by plain equality with zero special-casing. */
+export declare function joinMountedPath(prefix: string, relativePath: string): string;
+/** Scans every file in the project for `X.use("/prefix", router)` calls and
+ * maps each mounted router's *source file* to the literal prefix it's
+ * mounted at — the piece `express-list-endpoints` can't give us (it only
+ * reports the live app's fully-*resolved* runtime paths, not which static
+ * file each route came from). One level of mounting only (a router
+ * mounted directly on `app` or on another router) — sufficient for the
+ * "one router per domain, all mounted in one place" convention this is
+ * built around; deeper indirection just falls through to the
+ * `pathSegmentsMatch` fallback below. */
+export declare function buildMountPrefixMap(project: Project): Map<string, string>;
+/** Extracts the middleware chain from a static route registration's own
+ * arguments (e.g. `router.post("/", requireAuth, requireRole("admin"),
+ * handler)` -> `["requireAuth", "requireRole"]`), in registration order.
+ *
+ * Needed because `express-list-endpoints` (7.x) merges endpoints that share
+ * a literal path across different HTTP methods by concatenating their
+ * `methods` arrays, but silently keeps only the *first-registered* method's
+ * own `middlewares` array for the merged entry (see its `addEndpoints`) — a
+ * public `GET "/"` registered before a protected `POST "/"` on the same
+ * path makes the protected POST inherit GET's *empty* middleware chain.
+ * Reading it statically, per registration, sidesteps that upstream bug —
+ * this is the actual mechanism the Flowmap tab and `authRequiredGuess`
+ * below depend on being correct per method, not just per path.
+ *
+ * The first argument (the path string) and the last (the handler, always
+ * anonymous in every convention this cares about) are dropped; everything
+ * between is either a plain identifier (`requireAuth`) or a middleware
+ * factory call (`requireRole("admin")`, reported by its callee name). */
+export declare function extractMiddlewareNames(call: CallExpression): string[];
+/** Finds a request-body Zod schema statically associated with a route
+ * registration, trying two conventions in order: (1) a validation-
+ * middleware call among the route's own arguments (`validateBody(Schema)`,
+ * `zValidator("json", Schema)` — the schema is whichever argument actually
+ * resolves, checked last-to-first since the schema is usually the final
+ * arg), then (2) `Schema.parse(req.body)`/`.safeParse(...)` called directly
+ * inside the handler body. Returns null — never throws, never guesses —
+ * when neither convention matches. */
+export declare function findRequestSchemaForRoute(call: CallExpression, validationPatterns: string[]): JSONSchema | null;
+/** Finds a request-body schema inferred from a Mongoose model, when the
+ * Zod path above found nothing — see the two conventions documented
+ * above. Never throws, never guesses; null when neither matches. */
+export declare function findMongooseRequestSchemaForRoute(call: CallExpression): JSONSchema | null;
+/** JSDoc/leading-comment above a route registration statement, if any —
+ * higher fidelity than nothing, never required (docs/04-capture-engine.md
+ * Step 2 #6). Absent for the demo app on purpose: the M1 done-when bar
+ * requires zero annotations in demo-app's own code. Strips out any
+ * `@vayo`/`@group`/`@deprecated` tag lines (see `hasVayoDocSentinel`/
+ * `extractExplicitGroup`/`extractDeprecated` below) — same
+ * description-vs-structured-tags split swagger-jsdoc itself uses, so a tag
+ * doesn't show up twice (once as this summary, once as its own structured
+ * field). */
+export declare function extractSummary(call: CallExpression): string | null;
+/** Explicit `@description` tag in the same leading comment `extractSummary`
+ * reads — OpenAPI's own standard Operation Object distinguishes a short
+ * `summary` (one-liner) from a longer `description` (can be multiple
+ * paragraphs, markdown-supported); Vayo's zero-annotation `summary`
+ * extraction only ever produces the former. Unlike `@group`/`@deprecated`/
+ * `@response`/`@example`, the tag's own text can continue across multiple
+ * lines — everything from right after `@description` on its own line
+ * through the line before the next recognized `@`-tag (or the comment's
+ * end) is joined together, e.g.:
+ * ```
+ *  * @description
+ *  * Returns the full order record including line items.
+ *  * Use `include=customer` to also embed customer info.
+ * ```
+ * Only recognized inside a comment carrying the `@vayo` sentinel
+ * (`hasVayoDocSentinel`) — same reasoning as every other structured tag
+ * here: an incidental "see the @description field" sentence elsewhere
+ * shouldn't silently become this endpoint's documented description. */
+export declare function extractDescription(call: CallExpression): string | null;
+/** Explicit `@group <name>` tag in the same leading comment `extractSummary`
+ * reads — swagger-jsdoc's own convention (e.g. `@group Orders - order
+ * management`) for declaring a route's documentation grouping directly in
+ * code, rather than leaving it to the `routes/` file-layout convention or a
+ * guessed URL segment (docs/04-capture-engine.md Step 2 #4). A trailing
+ * `- description` some tools also allow after the name is trimmed off,
+ * since that's redundant with `extractSummary`'s own result. Nested groups
+ * follow the same "/"-separated convention `inferGroup` uses, e.g.
+ * `@group Admin/Users`. Only recognized inside a comment carrying the
+ * `@vayo` sentinel (`hasVayoDocSentinel`) — otherwise this text is treated
+ * as ordinary prose, never a declaration. */
+export declare function extractExplicitGroup(call: CallExpression): string | null;
+/** Bare `@deprecated` tag in the same leading comment `extractSummary`
+ * reads — the OpenAPI/swagger-jsdoc convention for marking a specific
+ * route deprecated in code, independent of the whole API *version*'s own
+ * lifecycle (`ApiVersionDoc.status`, `07-api-versioning.md`): a route can
+ * be deprecated while the version it belongs to is still fully active.
+ * Unlike `@group`, this tag carries no value of its own — its mere
+ * presence is the signal, matching how `@deprecated` is used bare in both
+ * conventions, so the whole line must be nothing else (a stray "the
+ * @deprecated tag needs cleanup" TODO elsewhere in a legitimately
+ * `@vayo`-tagged block still shouldn't flip this on). Only recognized
+ * inside a comment carrying the `@vayo` sentinel — see
+ * `extractExplicitGroup`'s own comment for why that gate exists at all. */
+export declare function extractDeprecated(call: CallExpression): boolean;
+/** Explicit `@response <status> <SchemaName>` tag(s) in the same leading
+ * comment `extractSummary` reads — declares a route's response body shape
+ * for a given status code by pointing at an existing Zod schema identifier
+ * (`findSchemaByName` above), the mirror of how `findRequestSchemaForRoute`
+ * traces a *request* body from a Zod schema — just declared explicitly
+ * rather than found at a fixed call-site convention, since there's no
+ * equivalent "always the last argument to X" shape for a response the way
+ * there is for request-validation middleware. One line per status code,
+ * e.g. `@response 200 OrderSchema` / `@response 404 ErrorSchema` — multiple
+ * lines declare multiple statuses. A name that doesn't resolve to a real
+ * Zod schema anywhere in scope is silently skipped for that line, never
+ * guessed. Only recognized inside a comment carrying the `@vayo` sentinel —
+ * see `extractExplicitGroup`'s comment for why that gate exists at all. */
+export declare function extractDeclaredResponseSchemas(call: CallExpression): Record<string, JSONSchema>;
+/** Explicit `@example <status> <JSON>` tag(s) in the same leading comment —
+ * a literal example response value for a given status code, declared
+ * directly in code rather than captured from real traffic or pinned by a
+ * team member from Try It Now (docs/03-data-model.md `vayo_examples`).
+ * One line per status code, e.g. `@example 200 {"id":"abc","total":42}` —
+ * single-line JSON only (no multi-line objects), to keep parsing this out
+ * of a free-text comment unambiguous. Invalid JSON on a matching line is
+ * silently skipped for that line, never thrown — same "never guess" bar
+ * every other tag here holds itself to. Only recognized inside a comment
+ * carrying the `@vayo` sentinel. */
+export declare function extractDeclaredExamples(call: CallExpression): Record<string, unknown>;
+/**
+ * Runs the static pass against a bootstrapped instance of the user's app.
+ *
+ * `config.appEntryPath` (resolved relative to `rootDir`) must be a module
+ * loadable via dynamic `import()` that exports a already-configured Express
+ * app — either `export default app` or `export const app`. It should be the
+ * user's plain app (no Vayo middleware mounted), so express-list-endpoints
+ * reports only the user's own routes/middleware — see apps/demo-app for the
+ * create-app-vs-start-server split this implies.
+ *
+ * Async (unlike the synchronous signature sketched in
+ * docs/08-packages-and-repo-structure.md) because bootstrapping a live app
+ * instance is inherently a dynamic import — there's no way to do that
+ * synchronously in an ESM-resolution world.
+ */
+export declare function scanProject(rootDir: string, config: VayoConfig): Promise<StaticScanResult>;