@shrkcrft/framework-scanners 0.1.0-alpha.10

package/dist/extractors/express-extractor.js

@@ -0,0 +1,193 @@
+import { createHash } from 'node:crypto';
+import * as nodePath from 'node:path';
+import * as ts from 'typescript';
+import { EdgeKind, NodeKind } from '@shrkcrft/graph';
+export const EXPRESS_EXTRACTOR_SOURCE = 'express-extractor@v1';
+const HTTP_METHOD_NAMES = new Set(['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'all']);
+// CommonJS-style detection uses a split string for the `require(` token
+// so the import-hygiene scanner doesn't flag the needle itself as a
+// lazy `require('node:*')`.
+const REQ = 'requ' + 'ire';
+const FAST_FILTER_NEEDLES = [
+    "from 'express'",
+    'from "express"',
+    `${REQ}('express')`,
+    `${REQ}("express")`,
+    'express.Router(',
+];
+/**
+ * Express extractor.
+ *
+ * Express has no decorators, so detection is signature-based:
+ *   - A variable initialized with a call to `express()` or
+ *     `express.Router()` (or to `Router(...)` when `Router` was
+ *     imported from `'express'`) becomes a **router** entity.
+ *   - Subsequent `<router>.get(path, …)` etc. calls become **route**
+ *     entities with method + path data.
+ *
+ * Middleware chains (extra handlers in the call args) are recorded on
+ * the route entity's `data.middlewareCount`. Detailed middleware-node
+ * extraction is out of scope for the MVP.
+ */
+export const expressExtractor = {
+    framework: 'express',
+    label: 'Express',
+    fileMatches({ path, content }) {
+        if (!/\.(?:t|j)sx?$/.test(path))
+            return false;
+        for (const needle of FAST_FILTER_NEEDLES) {
+            if (content.includes(needle))
+                return true;
+        }
+        return false;
+    },
+    extract(input) {
+        const nodes = [];
+        const edges = [];
+        const sf = parse(input);
+        if (!sf)
+            return { nodes, edges };
+        // 1. Find router bindings: variable names initialized with
+        //    `express()`, `express.Router()`, or `Router()` from express.
+        const routerNames = new Set();
+        const routerNodeByName = new Map();
+        const namedRouterImports = collectNamedRouterImports(sf);
+        const collectRouters = (node) => {
+            if (ts.isVariableStatement(node)) {
+                for (const decl of node.declarationList.declarations) {
+                    if (!ts.isIdentifier(decl.name))
+                        continue;
+                    const init = decl.initializer;
+                    if (!init)
+                        continue;
+                    if (isRouterFactory(init, namedRouterImports)) {
+                        const name = decl.name.text;
+                        routerNames.add(name);
+                        const entity = makeRouterEntity(input, name);
+                        routerNodeByName.set(name, entity);
+                        nodes.push(entity);
+                        edges.push(edge(input.fileNodeId, entity.id, EdgeKind.FrameworkDeclares, { subtype: 'router' }));
+                    }
+                }
+            }
+            ts.forEachChild(node, collectRouters);
+        };
+        ts.forEachChild(sf, collectRouters);
+        // 2. Walk every CallExpression matching <name>.<method>(<path>, ...).
+        const collectRoutes = (node) => {
+            if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+                const objExpr = node.expression.expression;
+                const method = node.expression.name.text;
+                if (HTTP_METHOD_NAMES.has(method) && ts.isIdentifier(objExpr) && routerNames.has(objExpr.text)) {
+                    const arg0 = node.arguments[0];
+                    if (arg0 && ts.isStringLiteral(arg0)) {
+                        const path = arg0.text;
+                        const router = routerNodeByName.get(objExpr.text);
+                        const route = makeRouteEntity(input, objExpr.text, method.toUpperCase(), path, node.arguments.length - 1);
+                        nodes.push(route);
+                        edges.push(edge(router.id, route.id, EdgeKind.HandlesRoute, {
+                            method: method.toUpperCase(),
+                            path,
+                        }));
+                        edges.push(edge(input.fileNodeId, route.id, EdgeKind.FrameworkDeclares, { subtype: 'route' }));
+                    }
+                }
+            }
+            ts.forEachChild(node, collectRoutes);
+        };
+        ts.forEachChild(sf, collectRoutes);
+        return { nodes, edges };
+    },
+};
+function collectNamedRouterImports(sf) {
+    // Local names bound to `Router` imported from `'express'`.
+    const out = new Set();
+    for (const stmt of sf.statements) {
+        if (!ts.isImportDeclaration(stmt))
+            continue;
+        if (!ts.isStringLiteral(stmt.moduleSpecifier) || stmt.moduleSpecifier.text !== 'express')
+            continue;
+        const clause = stmt.importClause;
+        if (!clause)
+            continue;
+        if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+            for (const elem of clause.namedBindings.elements) {
+                const propertyName = elem.propertyName ? elem.propertyName.text : elem.name.text;
+                if (propertyName === 'Router')
+                    out.add(elem.name.text);
+            }
+        }
+    }
+    return out;
+}
+function isRouterFactory(node, namedRouterImports) {
+    if (!ts.isCallExpression(node))
+        return false;
+    const callee = node.expression;
+    if (ts.isIdentifier(callee)) {
+        if (callee.text === 'express')
+            return true;
+        if (namedRouterImports.has(callee.text))
+            return true;
+        return false;
+    }
+    if (ts.isPropertyAccessExpression(callee)) {
+        // express.Router()
+        if (ts.isIdentifier(callee.expression) &&
+            callee.expression.text === 'express' &&
+            callee.name.text === 'Router') {
+            return true;
+        }
+    }
+    return false;
+}
+function makeRouterEntity(input, name) {
+    return {
+        id: `framework:express:router:${input.filePath}#${name}`,
+        kind: NodeKind.FrameworkEntity,
+        label: name,
+        path: input.filePath,
+        tags: ['express', 'router'],
+        data: { framework: 'express', subtype: 'router', name },
+    };
+}
+function makeRouteEntity(input, routerName, method, path, middlewareCount) {
+    return {
+        id: `framework:express:route:${input.filePath}#${routerName}#${method}:${path}`,
+        kind: NodeKind.FrameworkEntity,
+        label: `${method} ${path}`,
+        path: input.filePath,
+        tags: ['express', 'route'],
+        data: {
+            framework: 'express',
+            subtype: 'route',
+            method,
+            path,
+            router: routerName,
+            middlewareCount,
+        },
+    };
+}
+function edge(from, to, kind, data) {
+    return {
+        id: createHash('sha1').update(`${from}|${to}|${kind}`).digest('hex'),
+        from,
+        to,
+        kind,
+        source: EXPRESS_EXTRACTOR_SOURCE,
+        ...(data ? { data } : {}),
+    };
+}
+function parse(input) {
+    const ext = nodePath.extname(input.filePath).toLowerCase();
+    const kind = ext === '.tsx' ? ts.ScriptKind.TSX
+        : ext === '.jsx' ? ts.ScriptKind.JSX
+            : ext === '.js' || ext === '.mjs' || ext === '.cjs' ? ts.ScriptKind.JS
+                : ts.ScriptKind.TS;
+    try {
+        return ts.createSourceFile(input.filePath, input.content, ts.ScriptTarget.Latest, true, kind);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/extractors/fastapi-extractor.d.ts

@@ -0,0 +1,19 @@
+import type { IFrameworkExtractor } from '../extractor-api/framework-extractor.js';
+export declare const FASTAPI_EXTRACTOR_SOURCE = "fastapi-extractor@v1";
+/**
+ * FastAPI extractor.
+ *
+ * Regex-only (Python is not parsed via the TS AST). Detection:
+ *   - `<name> = FastAPI(...)` and `<name> = APIRouter(...)` → app /
+ *     router entity.
+ *   - `@<name>.<method>('<path>', ...)` → route entity, with the
+ *     decorated function captured on the next non-blank, non-decorator
+ *     line as the handler name.
+ *
+ * Out of scope (Python-only follow-ups):
+ *   - Path-operation function parameters (Pydantic body / query / path).
+ *   - Dependency injection (Depends()).
+ *   - Nested router includes (include_router).
+ */
+export declare const fastapiExtractor: IFrameworkExtractor;
+//# sourceMappingURL=fastapi-extractor.d.ts.map

package/dist/extractors/fastapi-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastapi-extractor.d.ts","sourceRoot":"","sources":["../../src/extractors/fastapi-extractor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,mBAAmB,EACpB,MAAM,yCAAyC,CAAC;AAEjD,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAW/D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,mBAmE9B,CAAC"}

package/dist/extractors/fastapi-extractor.js

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto';
+import { EdgeKind, NodeKind } from '@shrkcrft/graph';
+export const FASTAPI_EXTRACTOR_SOURCE = 'fastapi-extractor@v1';
+const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch', 'head', 'options'];
+const FAST_FILTER_NEEDLES = [
+    'from fastapi',
+    'fastapi import',
+    'FastAPI(',
+    'APIRouter(',
+];
+/**
+ * FastAPI extractor.
+ *
+ * Regex-only (Python is not parsed via the TS AST). Detection:
+ *   - `<name> = FastAPI(...)` and `<name> = APIRouter(...)` → app /
+ *     router entity.
+ *   - `@<name>.<method>('<path>', ...)` → route entity, with the
+ *     decorated function captured on the next non-blank, non-decorator
+ *     line as the handler name.
+ *
+ * Out of scope (Python-only follow-ups):
+ *   - Path-operation function parameters (Pydantic body / query / path).
+ *   - Dependency injection (Depends()).
+ *   - Nested router includes (include_router).
+ */
+export const fastapiExtractor = {
+    framework: 'fastapi',
+    label: 'FastAPI',
+    fileMatches({ path, content }) {
+        if (!path.endsWith('.py'))
+            return false;
+        for (const needle of FAST_FILTER_NEEDLES) {
+            if (content.includes(needle))
+                return true;
+        }
+        return false;
+    },
+    extract(input) {
+        const nodes = [];
+        const edges = [];
+        const appNames = new Map();
+        const lines = input.content.split('\n');
+        // First pass: find `<name> = FastAPI(` / `APIRouter(`.
+        const appRe = /^([A-Za-z_]\w*)\s*=\s*(FastAPI|APIRouter)\s*\(/;
+        for (let i = 0; i < lines.length; i += 1) {
+            const m = appRe.exec(lines[i]);
+            if (!m)
+                continue;
+            const name = m[1];
+            const kind = m[2] === 'FastAPI' ? 'app' : 'router';
+            const node = makeAppEntity(input, name, kind);
+            appNames.set(name, node);
+            nodes.push(node);
+            edges.push(edge(input.fileNodeId, node.id, EdgeKind.FrameworkDeclares, { subtype: kind }));
+        }
+        if (appNames.size === 0)
+            return { nodes, edges };
+        // Second pass: decorators on the line preceding a `def` / `async def`.
+        const decoratorRe = /^@([A-Za-z_]\w*)\.([a-z]+)\s*\(\s*['"]([^'"]+)['"]/;
+        const defRe = /^(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/;
+        for (let i = 0; i < lines.length; i += 1) {
+            const dm = decoratorRe.exec(lines[i]);
+            if (!dm)
+                continue;
+            const appName = dm[1];
+            const method = dm[2];
+            const path = dm[3];
+            if (!appNames.has(appName))
+                continue;
+            if (!HTTP_METHODS.includes(method))
+                continue;
+            // Find the handler def — scan forward through additional decorators.
+            let handler = 'handler';
+            for (let j = i + 1; j < lines.length; j += 1) {
+                const line = lines[j];
+                const trimmed = line.trimStart();
+                if (trimmed.length === 0)
+                    continue;
+                if (trimmed.startsWith('@'))
+                    continue; // stacked decorator
+                const def = defRe.exec(trimmed);
+                if (def)
+                    handler = def[1];
+                break;
+            }
+            const app = appNames.get(appName);
+            const route = makeRouteEntity(input, appName, handler, method.toUpperCase(), path);
+            nodes.push(route);
+            edges.push(edge(app.id, route.id, EdgeKind.HandlesRoute, {
+                method: method.toUpperCase(),
+                path,
+                handler,
+            }));
+            edges.push(edge(input.fileNodeId, route.id, EdgeKind.FrameworkDeclares, { subtype: 'route' }));
+        }
+        return { nodes, edges };
+    },
+};
+function makeAppEntity(input, name, subtype) {
+    return {
+        id: `framework:fastapi:${subtype}:${input.filePath}#${name}`,
+        kind: NodeKind.FrameworkEntity,
+        label: name,
+        path: input.filePath,
+        tags: ['fastapi', subtype],
+        data: { framework: 'fastapi', subtype, name },
+    };
+}
+function makeRouteEntity(input, appName, handler, method, path) {
+    return {
+        id: `framework:fastapi:route:${input.filePath}#${appName}.${handler}#${method}:${path}`,
+        kind: NodeKind.FrameworkEntity,
+        label: `${method} ${path}`,
+        path: input.filePath,
+        tags: ['fastapi', 'route'],
+        data: {
+            framework: 'fastapi',
+            subtype: 'route',
+            app: appName,
+            handler,
+            method,
+            path,
+        },
+    };
+}
+function edge(from, to, kind, data) {
+    return {
+        id: createHash('sha1').update(`${from}|${to}|${kind}`).digest('hex'),
+        from,
+        to,
+        kind,
+        source: FASTAPI_EXTRACTOR_SOURCE,
+        ...(data ? { data } : {}),
+    };
+}

package/dist/extractors/fastify-extractor.d.ts

@@ -0,0 +1,13 @@
+import type { IFrameworkExtractor } from '../extractor-api/framework-extractor.js';
+export declare const FASTIFY_EXTRACTOR_SOURCE = "fastify-extractor@v1";
+/**
+ * Fastify extractor.
+ *
+ * Detection model is similar to Express but for Fastify's API:
+ *   - A variable initialized with `fastify(...)` or `Fastify(...)` becomes a
+ *     **server** entity.
+ *   - Subsequent `<server>.get('/path', ...)`, `.post`, etc. become **route**
+ *     entities. `.route({ method, url })` is also recognised.
+ */
+export declare const fastifyExtractor: IFrameworkExtractor;
+//# sourceMappingURL=fastify-extractor.d.ts.map

package/dist/extractors/fastify-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify-extractor.d.ts","sourceRoot":"","sources":["../../src/extractors/fastify-extractor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAGV,mBAAmB,EACpB,MAAM,yCAAyC,CAAC;AAEjD,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAY/D;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,mBAiE9B,CAAC"}

package/dist/extractors/fastify-extractor.js

@@ -0,0 +1,166 @@
+import { createHash } from 'node:crypto';
+import * as nodePath from 'node:path';
+import * as ts from 'typescript';
+import { EdgeKind, NodeKind } from '@shrkcrft/graph';
+export const FASTIFY_EXTRACTOR_SOURCE = 'fastify-extractor@v1';
+const HTTP_METHOD_NAMES = new Set(['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'all', 'route']);
+const FAST_FILTER_NEEDLES = [
+    "from 'fastify'",
+    'from "fastify"',
+    '@fastify/',
+    'fastify(',
+    'Fastify(',
+];
+/**
+ * Fastify extractor.
+ *
+ * Detection model is similar to Express but for Fastify's API:
+ *   - A variable initialized with `fastify(...)` or `Fastify(...)` becomes a
+ *     **server** entity.
+ *   - Subsequent `<server>.get('/path', ...)`, `.post`, etc. become **route**
+ *     entities. `.route({ method, url })` is also recognised.
+ */
+export const fastifyExtractor = {
+    framework: 'fastify',
+    label: 'Fastify',
+    fileMatches({ path, content }) {
+        if (!/\.(?:t|j)sx?$/.test(path))
+            return false;
+        for (const needle of FAST_FILTER_NEEDLES) {
+            if (content.includes(needle))
+                return true;
+        }
+        return false;
+    },
+    extract(input) {
+        const nodes = [];
+        const edges = [];
+        const sf = parse(input);
+        if (!sf)
+            return { nodes, edges };
+        const serverNames = new Set();
+        const serverNodeByName = new Map();
+        const findServers = (node) => {
+            if (ts.isVariableStatement(node)) {
+                for (const decl of node.declarationList.declarations) {
+                    if (!ts.isIdentifier(decl.name))
+                        continue;
+                    const init = decl.initializer;
+                    if (!init)
+                        continue;
+                    if (isFastifyFactory(init)) {
+                        const name = decl.name.text;
+                        serverNames.add(name);
+                        const entity = makeServerEntity(input, name);
+                        serverNodeByName.set(name, entity);
+                        nodes.push(entity);
+                        edges.push(edge(input.fileNodeId, entity.id, EdgeKind.FrameworkDeclares, { subtype: 'server' }));
+                    }
+                }
+            }
+            ts.forEachChild(node, findServers);
+        };
+        ts.forEachChild(sf, findServers);
+        const findRoutes = (node) => {
+            if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+                const objExpr = node.expression.expression;
+                const method = node.expression.name.text;
+                if (HTTP_METHOD_NAMES.has(method) &&
+                    ts.isIdentifier(objExpr) &&
+                    serverNames.has(objExpr.text)) {
+                    const route = parseRouteCall(input, objExpr.text, method, node);
+                    if (route) {
+                        const serverEntity = serverNodeByName.get(objExpr.text);
+                        nodes.push(route);
+                        edges.push(edge(serverEntity.id, route.id, EdgeKind.HandlesRoute, {
+                            method: route.data?.['method'] ?? '?',
+                            path: route.data?.['path'] ?? '?',
+                        }));
+                        edges.push(edge(input.fileNodeId, route.id, EdgeKind.FrameworkDeclares, { subtype: 'route' }));
+                    }
+                }
+            }
+            ts.forEachChild(node, findRoutes);
+        };
+        ts.forEachChild(sf, findRoutes);
+        return { nodes, edges };
+    },
+};
+function isFastifyFactory(node) {
+    if (!ts.isCallExpression(node))
+        return false;
+    const callee = node.expression;
+    if (ts.isIdentifier(callee)) {
+        return callee.text === 'fastify' || callee.text === 'Fastify';
+    }
+    return false;
+}
+function parseRouteCall(input, serverName, method, call) {
+    const arg0 = call.arguments[0];
+    if (!arg0)
+        return undefined;
+    if (method === 'route') {
+        if (!ts.isObjectLiteralExpression(arg0))
+            return undefined;
+        let m;
+        let p;
+        for (const prop of arg0.properties) {
+            if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+                continue;
+            const v = prop.initializer;
+            if (prop.name.text === 'method' && ts.isStringLiteral(v))
+                m = v.text.toUpperCase();
+            if ((prop.name.text === 'url' || prop.name.text === 'path') && ts.isStringLiteral(v))
+                p = v.text;
+        }
+        if (!m || !p)
+            return undefined;
+        return makeRouteEntity(input, serverName, m, p);
+    }
+    if (!ts.isStringLiteral(arg0))
+        return undefined;
+    return makeRouteEntity(input, serverName, method.toUpperCase(), arg0.text);
+}
+function makeServerEntity(input, name) {
+    return {
+        id: `framework:fastify:server:${input.filePath}#${name}`,
+        kind: NodeKind.FrameworkEntity,
+        label: name,
+        path: input.filePath,
+        tags: ['fastify', 'server'],
+        data: { framework: 'fastify', subtype: 'server', name },
+    };
+}
+function makeRouteEntity(input, serverName, method, path) {
+    return {
+        id: `framework:fastify:route:${input.filePath}#${serverName}#${method}:${path}`,
+        kind: NodeKind.FrameworkEntity,
+        label: `${method} ${path}`,
+        path: input.filePath,
+        tags: ['fastify', 'route'],
+        data: { framework: 'fastify', subtype: 'route', method, path, server: serverName },
+    };
+}
+function edge(from, to, kind, data) {
+    return {
+        id: createHash('sha1').update(`${from}|${to}|${kind}`).digest('hex'),
+        from,
+        to,
+        kind,
+        source: FASTIFY_EXTRACTOR_SOURCE,
+        ...(data ? { data } : {}),
+    };
+}
+function parse(input) {
+    const ext = nodePath.extname(input.filePath).toLowerCase();
+    const kind = ext === '.tsx' ? ts.ScriptKind.TSX
+        : ext === '.jsx' ? ts.ScriptKind.JSX
+            : ext === '.js' || ext === '.mjs' || ext === '.cjs' ? ts.ScriptKind.JS
+                : ts.ScriptKind.TS;
+    try {
+        return ts.createSourceFile(input.filePath, input.content, ts.ScriptTarget.Latest, true, kind);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/extractors/flask-extractor.d.ts

@@ -0,0 +1,16 @@
+import type { IFrameworkExtractor } from '../extractor-api/framework-extractor.js';
+export declare const FLASK_EXTRACTOR_SOURCE = "flask-extractor@v1";
+/**
+ * Flask extractor.
+ *
+ * Regex-only. Detection model:
+ *   - `<name> = Flask(...)` → **app** entity.
+ *   - `<name> = Blueprint('<bp>', __name__, ...)` → **blueprint**
+ *     entity. The first string argument is captured as the blueprint
+ *     name.
+ *   - `@<name>.route('<path>', methods=[...])` immediately preceding a
+ *     `def <handler>` → **route** entity with method(s) + path +
+ *     handler. The default method is GET when `methods=` is absent.
+ */
+export declare const flaskExtractor: IFrameworkExtractor;
+//# sourceMappingURL=flask-extractor.d.ts.map

package/dist/extractors/flask-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flask-extractor.d.ts","sourceRoot":"","sources":["../../src/extractors/flask-extractor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,mBAAmB,EACpB,MAAM,yCAAyC,CAAC;AAEjD,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAW3D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,EAAE,mBA8E5B,CAAC"}