glirastes 0.4.0 → 0.5.1

package/dist/cjs/codegen/route-scanner.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTH_PATTERNS = exports.createRouteSourceFingerprint = void 0;
+exports.toRoutePath = toRoutePath;
+exports.scanNextAppRoutes = scanNextAppRoutes;
+exports.writeNextAppRouteScan = writeNextAppRouteScan;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const fs_utils_js_1 = require("./fs-utils.js");
+const execution_inventory_js_1 = require("./execution-inventory.js");
+const route_fingerprint_js_1 = require("./route-fingerprint.js");
+const route_exports_js_1 = require("./route-exports.js");
+var route_fingerprint_js_2 = require("./route-fingerprint.js");
+Object.defineProperty(exports, "createRouteSourceFingerprint", { enumerable: true, get: function () { return route_fingerprint_js_2.createRouteSourceFingerprint; } });
+exports.AUTH_PATTERNS = [
+    ['resolvePrincipal', /\bresolvePrincipal\s*\(/],
+    ['resolveUser', /\bresolveUser\s*\(/],
+    ['getServerSession', /\bgetServerSession\s*\(/],
+    ['getSession', /\bgetSession\s*\(/],
+    ['auth', /\bauth\s*\(/],
+];
+const EXTERNAL_PATTERNS = [
+    ['fetch', /\bfetch\s*\(/],
+    ['dynamic-code', /\b(?:eval|Function)\s*\(/],
+    ['child-process', /\b(?:exec|execFile|spawn)\s*\(/],
+];
+function toSourceFile(rootDir, absolutePath) {
+    return (0, node_path_1.relative)(rootDir, absolutePath).split(node_path_1.sep).join('/');
+}
+function toRoutePath(apiDir, routeFile) {
+    const routeDirectory = (0, node_path_1.relative)(apiDir, (0, node_path_1.dirname)(routeFile));
+    const pathParams = [];
+    const segments = routeDirectory
+        .split(node_path_1.sep)
+        .filter((segment) => segment && !/^\(.+\)$/.test(segment))
+        .map((segment) => {
+        const optionalCatchAll = segment.match(/^\[\[\.\.\.(.+)\]\]$/);
+        if (optionalCatchAll) {
+            pathParams.push(optionalCatchAll[1]);
+            return `*${optionalCatchAll[1]}`;
+        }
+        const catchAll = segment.match(/^\[\.\.\.(.+)\]$/);
+        if (catchAll) {
+            pathParams.push(catchAll[1]);
+            return `*${catchAll[1]}`;
+        }
+        const dynamic = segment.match(/^\[(.+)\]$/);
+        if (dynamic) {
+            pathParams.push(dynamic[1]);
+            return `:${dynamic[1]}`;
+        }
+        return segment;
+    });
+    return {
+        path: `/api${segments.length ? `/${segments.join('/')}` : ''}`,
+        pathParams,
+    };
+}
+function extractQueryParams(body) {
+    const params = new Map();
+    for (const match of body.matchAll(/\bsearchParams\.(getAll|get)\(\s*['"`]([^'"`]+)['"`]\s*\)/g)) {
+        const name = match[2];
+        const repeated = match[1] === 'getAll';
+        params.set(name, repeated || (params.get(name) ?? false));
+    }
+    return [...params]
+        .map(([name, repeated]) => ({ name, repeated }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function importBindings(source) {
+    const imports = new Map();
+    for (const match of source.matchAll(/import\s*\{([^}]+)\}\s*from\s*['"`]([^'"`]+)['"`]/g)) {
+        for (const item of match[1].split(',')) {
+            const [imported, local = imported] = item.trim().split(/\s+as\s+/);
+            if (local)
+                imports.set(local.trim(), match[2]);
+        }
+    }
+    return imports;
+}
+function extractSchemaBindings(body, imports) {
+    const bindings = new Map();
+    for (const match of body.matchAll(/\b([A-Za-z_$][\w$]*)\.safeParse\s*\(/g)) {
+        const symbol = match[1];
+        const module = imports.get(symbol);
+        if (module)
+            bindings.set(symbol, module);
+    }
+    return [...bindings]
+        .map(([symbol, module]) => ({ symbol, module }))
+        .sort((left, right) => left.symbol.localeCompare(right.symbol));
+}
+function evidence(source, patterns) {
+    return patterns
+        .filter(([, pattern]) => pattern.test(source))
+        .map(([name]) => name);
+}
+function reviewReasons(options) {
+    const reasons = [];
+    if (options.authEvidence.length === 0) {
+        reasons.push('auth-boundary-unverified');
+    }
+    if (options.externalCallEvidence.length > 0) {
+        reasons.push('external-call-detected');
+    }
+    if (options.method === 'GET' || options.method === 'HEAD') {
+        reasons.push('data-classification-unverified');
+    }
+    else if (options.method === 'DELETE') {
+        reasons.push('delete-operation');
+    }
+    else {
+        reasons.push('write-operation');
+    }
+    return reasons;
+}
+async function scanRouteCandidates(options, respectLegacyIgnores, strictSources) {
+    const apiDir = (0, node_path_1.join)(options.rootDir, options.apiDir ?? 'src/app/api');
+    const candidates = [];
+    const ignored = [];
+    const findings = [];
+    for (const routeFile of strictSources ? [...strictSources.keys()].sort() : await (0, fs_utils_js_1.findRouteFiles)(apiDir)) {
+        const source = strictSources ? strictSources.get(routeFile) : await (0, fs_utils_js_1.readFileSafe)(routeFile);
+        const sourceFile = toSourceFile(options.rootDir, routeFile);
+        if (respectLegacyIgnores
+            && (source.includes('@ai-ignore')
+                || await (0, fs_utils_js_1.isDirAiIgnored)((0, node_path_1.dirname)(routeFile)))) {
+            ignored.push(sourceFile);
+            continue;
+        }
+        const imports = importBindings(source);
+        const route = toRoutePath(apiDir, routeFile);
+        const parsed = (0, route_exports_js_1.readRouteExports)(source, sourceFile);
+        // HEAD is a tool only for the tools generator (source discovery); the
+        // legacy scan upload keeps its five-method contract with the Platform.
+        const included = (method) => Boolean(strictSources) || method !== 'HEAD';
+        findings.push(...parsed.findings
+            .filter((finding) => included(finding.exportName))
+            .map((finding) => ({ sourceFile, ...finding })));
+        for (const { method, body } of parsed.exports.filter((entry) => included(entry.method))) {
+            const authEvidence = evidence(body, exports.AUTH_PATTERNS);
+            const externalCallEvidence = evidence(body, EXTERNAL_PATTERNS);
+            candidates.push({
+                sourceFile,
+                sourceFingerprint: (0, route_fingerprint_js_1.createRouteSourceFingerprint)(source, method, route.path),
+                exportName: method,
+                method,
+                path: route.path,
+                pathParams: route.pathParams,
+                queryParams: extractQueryParams(body),
+                schemaBindings: extractSchemaBindings(body, imports),
+                authEvidence,
+                externalCallEvidence,
+                riskClass: method === 'DELETE'
+                    ? 'delete'
+                    : method === 'GET' || method === 'HEAD'
+                        ? 'unknown'
+                        : 'write',
+                autoApprovalEligible: false,
+                reviewReasons: reviewReasons({
+                    method,
+                    authEvidence,
+                    externalCallEvidence,
+                }),
+            });
+        }
+    }
+    return { candidates, ignored, ...(findings.length ? { findings } : {}) };
+}
+async function scanNextAppRoutes(options) {
+    if (options.mode === 'source-discovery') {
+        const inputRoot = (0, node_path_1.resolve)(options.rootDir);
+        const rootDir = await (0, promises_1.realpath)(options.rootDir);
+        const relativeApi = (0, node_path_1.relative)(inputRoot, (0, node_path_1.resolve)(inputRoot, options.apiDir ?? 'src/app/api'));
+        if (relativeApi.startsWith(`..${node_path_1.sep}`) || relativeApi === '..')
+            throw new Error('Source directory must remain inside the app');
+        const apiDir = (0, node_path_1.resolve)(rootDir, relativeApi);
+        const sources = new Map();
+        let visited = 0;
+        const walk = async (directory) => {
+            if (++visited > 10_000 || await (0, promises_1.realpath)(directory) !== directory)
+                throw new Error('Source discovery is incomplete');
+            for (const entry of await (0, promises_1.readdir)(directory, { withFileTypes: true })) {
+                if (entry.name === 'node_modules' || entry.name === '.git')
+                    continue;
+                if (entry.isDirectory() && entry.name.startsWith('_'))
+                    continue;
+                const path = (0, node_path_1.join)(directory, entry.name);
+                if (entry.isSymbolicLink())
+                    throw new Error('Source discovery is incomplete');
+                if (entry.isDirectory()) {
+                    await walk(path);
+                    continue;
+                }
+                if (!entry.isFile() || !/^route\.(ts|tsx|js|jsx)$/.test(entry.name))
+                    continue;
+                if (sources.size >= 5_000 || await (0, promises_1.realpath)(path) !== path || (await (0, promises_1.stat)(path)).size > 2_000_000) {
+                    throw new Error('Source discovery is incomplete');
+                }
+                sources.set(path, await (0, promises_1.readFile)(path, 'utf8'));
+            }
+        };
+        await walk(apiDir);
+        return scanRouteCandidates({ ...options, rootDir, apiDir: relativeApi }, false, sources);
+    }
+    if ((options.mode ?? 'legacy-route-scan') === 'legacy-route-scan') {
+        return scanRouteCandidates(options, true);
+    }
+    if (!options.inventory) {
+        throw new Error('Foundation inventory mode requires an execution inventory');
+    }
+    const discovery = await (0, execution_inventory_js_1.discoverFoundationExecutions)({
+        rootDir: options.rootDir,
+        inventory: options.inventory,
+    });
+    const scanned = await scanRouteCandidates(options, false);
+    const endpointKeys = new Set(discovery.executions
+        .filter((execution) => execution.executionKind === 'endpoint')
+        .map((execution) => execution.stableKey));
+    return {
+        candidates: scanned.candidates.filter((candidate) => (endpointKeys.has(`${candidate.method} ${candidate.path}`))),
+        ignored: [],
+        executions: discovery.executions,
+        inventoryDigest: discovery.inventoryDigest,
+        ...(scanned.findings ? { findings: scanned.findings } : {}),
+    };
+}
+async function writeNextAppRouteScan(options) {
+    const result = await scanNextAppRoutes(options);
+    const outputPath = (0, node_path_1.resolve)(options.rootDir, options.outputPath ?? '.glirastes/route-scan.json');
+    const artifact = {
+        schemaVersion: 1,
+        generatedAt: (options.now?.() ?? new Date()).toISOString(),
+        ...result,
+    };
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(outputPath), { recursive: true });
+    await (0, promises_1.writeFile)(outputPath, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+    return { outputPath, result };
+}

package/dist/cjs/codegen/tools/canonical.d.ts

@@ -0,0 +1,12 @@
+import { type LocalJsonSchema } from '../../runtime/json-schema.js';
+/** Locale-independent ordering so outputs are byte-identical across Node versions. */
+export declare function compareCodeUnits(left: string, right: string): number;
+export declare function sortKeysDeep(value: unknown): unknown;
+/** Canonical file form for every generator-owned JSON output. */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Digest(value: string): string;
+/** UUIDv5-shaped identifier scoped to the app; same inputs, same identifier. */
+export declare function deterministicUuid(appId: string, parts: ReadonlyArray<string>): string;
+export declare const OPAQUE_JSON_SCHEMA: LocalJsonSchema;
+/** Must equal what the runtime computes for `createJsonSchemaLike(schema)` at boot. */
+export declare function jsonSchemaDigest(schema: LocalJsonSchema): string;

package/dist/cjs/codegen/tools/canonical.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPAQUE_JSON_SCHEMA = void 0;
+exports.compareCodeUnits = compareCodeUnits;
+exports.sortKeysDeep = sortKeysDeep;
+exports.canonicalJson = canonicalJson;
+exports.sha256Digest = sha256Digest;
+exports.deterministicUuid = deterministicUuid;
+exports.jsonSchemaDigest = jsonSchemaDigest;
+const node_crypto_1 = require("node:crypto");
+const json_schema_js_1 = require("../../runtime/json-schema.js");
+const local_tool_bindings_js_1 = require("../../runtime/local-tool-bindings.js");
+/** Locale-independent ordering so outputs are byte-identical across Node versions. */
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort(compareCodeUnits)
+        .map((key) => [key, sortKeysDeep(value[key])]));
+}
+/** Canonical file form for every generator-owned JSON output. */
+function canonicalJson(value) {
+    return `${JSON.stringify(sortKeysDeep(value), null, 2)}\n`;
+}
+function sha256Digest(value) {
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(value).digest('base64url')}`;
+}
+/** UUIDv5-shaped identifier scoped to the app; same inputs, same identifier. */
+function deterministicUuid(appId, parts) {
+    const bytes = (0, node_crypto_1.createHash)('sha1')
+        .update(Buffer.from(appId.replaceAll('-', ''), 'hex'))
+        .update(JSON.stringify(['glirastes.tools.v1', ...parts]))
+        .digest()
+        .subarray(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x50;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+exports.OPAQUE_JSON_SCHEMA = Object.freeze({});
+/** Must equal what the runtime computes for `createJsonSchemaLike(schema)` at boot. */
+function jsonSchemaDigest(schema) {
+    return (0, local_tool_bindings_js_1.createLocalSchemaDigest)((0, json_schema_js_1.createJsonSchemaLike)(schema));
+}

package/dist/cjs/codegen/tools/sources/nest-decorators.d.ts

@@ -0,0 +1,27 @@
+/**
+ * How a file reaches the decorators of `@nestjs/common`, through a named or a
+ * namespace import. Shared by the Nest endpoint source and the execution
+ * inventory, so a controller the source enumerates is one the inventory verifies.
+ */
+import ts from 'typescript';
+import type { EndpointMethod } from '../../../types.js';
+/** The HTTP method decorators of `@nestjs/common` that become endpoint tools. */
+export declare const NEST_METHOD_DECORATORS: Readonly<Record<string, EndpointMethod>>;
+export interface NestImports {
+    /** Local name → exported name, for named imports of `@nestjs/common`. */
+    common: Map<string, string>;
+    commonNamespaces: Set<string>;
+    core: Set<string>;
+    createZodDto: Set<string>;
+}
+/** The `@nestjs/common`, `@nestjs/core` and `nestjs-zod` bindings of a file, ignoring type-only imports. */
+export declare function readImports(file: ts.SourceFile): NestImports;
+/** The `@nestjs/common` export a decorator calls, e.g. `Get` for `@Get(':id')` or `@common.Get()`. */
+export declare function decoratorName(decorator: ts.Decorator, imports: NestImports): {
+    name: string;
+    args: ts.NodeArray<ts.Expression>;
+} | undefined;
+export declare function decoratorsOf(node: ts.Node, imports: NestImports): Array<{
+    name: string;
+    args: ts.NodeArray<ts.Expression>;
+}>;

package/dist/cjs/codegen/tools/sources/nest-decorators.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEST_METHOD_DECORATORS = void 0;
+exports.readImports = readImports;
+exports.decoratorName = decoratorName;
+exports.decoratorsOf = decoratorsOf;
+/**
+ * How a file reaches the decorators of `@nestjs/common`, through a named or a
+ * namespace import. Shared by the Nest endpoint source and the execution
+ * inventory, so a controller the source enumerates is one the inventory verifies.
+ */
+const typescript_1 = __importDefault(require("typescript"));
+const NEST_COMMON = '@nestjs/common';
+const NEST_CORE = '@nestjs/core';
+const NEST_ZOD = 'nestjs-zod';
+/** The HTTP method decorators of `@nestjs/common` that become endpoint tools. */
+exports.NEST_METHOD_DECORATORS = {
+    Get: 'GET', Head: 'HEAD', Post: 'POST', Put: 'PUT', Patch: 'PATCH', Delete: 'DELETE',
+};
+/** The `@nestjs/common`, `@nestjs/core` and `nestjs-zod` bindings of a file, ignoring type-only imports. */
+function readImports(file) {
+    const imports = { common: new Map(), commonNamespaces: new Set(), core: new Set(), createZodDto: new Set() };
+    for (const statement of file.statements) {
+        if (!typescript_1.default.isImportDeclaration(statement) || !typescript_1.default.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        if (statement.importClause?.isTypeOnly)
+            continue;
+        const module = statement.moduleSpecifier.text;
+        const bindings = statement.importClause?.namedBindings;
+        if (module === NEST_COMMON && bindings && typescript_1.default.isNamespaceImport(bindings))
+            imports.commonNamespaces.add(bindings.name.text);
+        if (!bindings || !typescript_1.default.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            if (element.isTypeOnly)
+                continue;
+            const exported = (element.propertyName ?? element.name).text;
+            if (module === NEST_COMMON)
+                imports.common.set(element.name.text, exported);
+            if (module === NEST_CORE)
+                imports.core.add(exported);
+            if (module === NEST_ZOD && exported === 'createZodDto')
+                imports.createZodDto.add(element.name.text);
+        }
+    }
+    return imports;
+}
+/** The `@nestjs/common` export a decorator calls, e.g. `Get` for `@Get(':id')` or `@common.Get()`. */
+function decoratorName(decorator, imports) {
+    const call = decorator.expression;
+    if (!typescript_1.default.isCallExpression(call))
+        return undefined;
+    const callee = call.expression;
+    if (typescript_1.default.isIdentifier(callee)) {
+        const name = imports.common.get(callee.text);
+        return name ? { name, args: call.arguments } : undefined;
+    }
+    if (typescript_1.default.isPropertyAccessExpression(callee) && typescript_1.default.isIdentifier(callee.expression)
+        && imports.commonNamespaces.has(callee.expression.text)) {
+        return { name: callee.name.text, args: call.arguments };
+    }
+    return undefined;
+}
+function decoratorsOf(node, imports) {
+    const decorators = typescript_1.default.canHaveDecorators(node) ? typescript_1.default.getDecorators(node) ?? [] : [];
+    return decorators.flatMap((decorator) => {
+        const found = decoratorName(decorator, imports);
+        return found ? [found] : [];
+    });
+}