@titannio/webtoolkit-cli 1.3.0

package/dist/guards/dal-service-repository-check.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env tsx
+/**
+ * DAL + Service + Repository Compliance Report
+ *
+ * Analisa a camada backend e identifica violacoes de fronteira arquitetural
+ * entre Controllers, Services, Repositories, Routes, Middlewares e o agregador
+ * central de DAL.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import ts from 'typescript';
+import { BASE_LAYER_EXCLUDE_PATTERNS, BASE_TYPESCRIPT_EXTENSIONS, assertConfiguredScanScope, compilePatterns, hasExtension, isMainModule, loadGuardConfig, resolveProjectPath } from './guard-config.js';
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+function normalizeFilePath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+function isAllowedFile(filePath, excludePatterns) {
+    if (!hasExtension(filePath, BASE_TYPESCRIPT_EXTENSIONS))
+        return false;
+    return !excludePatterns.some((pattern) => pattern.test(filePath));
+}
+function collectFiles(rootDir, excludePatterns) {
+    const files = [];
+    const walk = (dir) => {
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+            return;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!excludePatterns.some((pattern) => pattern.test(fullPath))) {
+                    walk(fullPath);
+                }
+                continue;
+            }
+            if (entry.isFile() && isAllowedFile(fullPath, excludePatterns)) {
+                files.push(fullPath);
+            }
+        }
+    };
+    walk(rootDir);
+    return files;
+}
+function readCompilerOptions(tsconfigPath) {
+    let configResult;
+    try {
+        configResult = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+    }
+    catch (error) {
+        throw new Error(`Failed to read backend tsconfig: ${error.message}`);
+    }
+    if (configResult.error) {
+        const message = ts.flattenDiagnosticMessageText(configResult.error.messageText, '\n');
+        throw new Error(`Failed to read backend tsconfig: ${message}`);
+    }
+    const parsed = ts.parseJsonConfigFileContent(configResult.config, ts.sys, path.dirname(tsconfigPath));
+    return parsed.options;
+}
+function matchesPath(relativePath, configuredPath) {
+    const normalized = normalizeFilePath(configuredPath).replace(/^\/|\/$/g, '');
+    return relativePath === normalized || relativePath.startsWith(`${normalized}/`);
+}
+function classifyLayer(filePath, sourceDirectory, layers) {
+    const normalized = normalizeFilePath(path.resolve(filePath));
+    const relative = normalizeFilePath(path.relative(sourceDirectory, normalized));
+    for (const layer of layers) {
+        if ((layer.exclude ?? []).some((excluded) => matchesPath(relative, excluded)))
+            continue;
+        if (layer.paths.some((candidate) => matchesPath(relative, candidate)))
+            return layer.name;
+    }
+    return 'other';
+}
+function isInternalSourceFile(filePath, sourceDirectory) {
+    const relativePath = path.relative(sourceDirectory, path.resolve(filePath));
+    return relativePath !== '..' && !relativePath.startsWith(`..${path.sep}`) && !path.isAbsolute(relativePath);
+}
+function resolveImportTarget(sourceFileName, moduleSpecifier, compilerOptions) {
+    const resolved = ts.resolveModuleName(moduleSpecifier, sourceFileName, compilerOptions, ts.sys);
+    return resolved.resolvedModule?.resolvedFileName ?? null;
+}
+function isViolation(sourceLayer, targetLayer, forbiddenDependencies) {
+    return (forbiddenDependencies[sourceLayer] ?? []).includes(targetLayer);
+}
+function buildViolationMessage(sourceLayer, targetLayer) {
+    return `${sourceLayer} cannot depend directly on ${targetLayer}`;
+}
+function formatPercent(value) {
+    return `${value.toFixed(1)}%`;
+}
+function printHeader() {
+    console.log(`${colors.bright}${colors.blue}╔═══════════════════════════════════════════════════════════════╗${colors.reset}`);
+    console.log(`${colors.bright}${colors.blue}║       DAL + Service + Repository Compliance Report            ║${colors.reset}`);
+    console.log(`${colors.bright}${colors.blue}╚═══════════════════════════════════════════════════════════════╝${colors.reset}`);
+    console.log();
+}
+function getLineNumber(sourceFile, position) {
+    const lineAndChar = sourceFile.getLineAndCharacterOfPosition(position);
+    return lineAndChar.line + 1;
+}
+export async function runDalServiceRepositoryGuard(options = {}) {
+    const rootDir = options.rootDir ?? process.cwd();
+    const config = options.config ?? await loadGuardConfig('dalServiceRepository', rootDir);
+    /* v8 ignore next -- every invalid operand and the valid fallthrough are asserted */
+    if (!config.sourceDirectory || !config.tsconfig || config.layers.length === 0) {
+        throw new Error('guards.dalServiceRepository requires sourceDirectory, tsconfig and non-empty layers.');
+    }
+    const sourceDirectory = resolveProjectPath(rootDir, config.sourceDirectory);
+    const tsconfigPath = resolveProjectPath(rootDir, config.tsconfig);
+    const excludePatterns = compilePatterns(config.excludePatterns, BASE_LAYER_EXCLUDE_PATTERNS);
+    const evaluatedLayers = new Set(config.layers.map((layer) => layer.name));
+    printHeader();
+    console.log(`${colors.cyan}Scope:${colors.reset} ${normalizeFilePath(path.relative(rootDir, sourceDirectory))}`);
+    console.log(`${colors.cyan}Rules:${colors.reset}`);
+    for (const [layer, forbidden] of Object.entries(config.forbiddenDependencies)) {
+        console.log(`  - ${layer} cannot import ${forbidden.join(', ')}`);
+    }
+    console.log();
+    const compilerOptions = readCompilerOptions(tsconfigPath);
+    const files = collectFiles(sourceDirectory, excludePatterns);
+    assertConfiguredScanScope({
+        root: rootDir,
+        guardName: 'dal-service-repository',
+        configPath: 'guards.dalServiceRepository.sourceDirectory',
+        configuredPaths: [config.sourceDirectory],
+        eligibleFiles: files,
+    });
+    const reports = [];
+    const ruleCounts = new Map();
+    const layerCounts = new Map();
+    let evaluatedFiles = 0;
+    let compliantFiles = 0;
+    let totalViolations = 0;
+    for (const filePath of files) {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        const layer = classifyLayer(filePath, sourceDirectory, config.layers);
+        const evaluated = evaluatedLayers.has(layer);
+        const violations = [];
+        if (evaluated)
+            evaluatedFiles++;
+        if (evaluated) {
+            layerCounts.set(layer, (layerCounts.get(layer) ?? 0) + 1);
+        }
+        for (const statement of sourceFile.statements) {
+            if (!ts.isImportDeclaration(statement))
+                continue;
+            if (!ts.isStringLiteralLike(statement.moduleSpecifier))
+                continue;
+            const moduleSpecifier = statement.moduleSpecifier.text;
+            const resolvedFileName = resolveImportTarget(filePath, moduleSpecifier, compilerOptions);
+            if (!resolvedFileName)
+                continue;
+            if (!isInternalSourceFile(resolvedFileName, sourceDirectory))
+                continue;
+            const targetLayer = classifyLayer(resolvedFileName, sourceDirectory, config.layers);
+            if (targetLayer === 'other')
+                continue;
+            if (!evaluated)
+                continue;
+            if (!isViolation(layer, targetLayer, config.forbiddenDependencies))
+                continue;
+            const line = getLineNumber(sourceFile, statement.getStart(sourceFile));
+            const ruleId = `${layer}-forbidden-${targetLayer}`;
+            violations.push({
+                ruleId,
+                message: buildViolationMessage(layer, targetLayer),
+                line,
+                importPath: normalizeFilePath(path.relative(rootDir, resolvedFileName)),
+                targetLayer,
+            });
+        }
+        if (evaluated) {
+            if (violations.length === 0) {
+                compliantFiles++;
+            }
+            else {
+                totalViolations += violations.length;
+                for (const violation of violations) {
+                    ruleCounts.set(violation.ruleId, (ruleCounts.get(violation.ruleId) ?? 0) + 1);
+                }
+            }
+        }
+        reports.push({
+            filePath: normalizeFilePath(path.relative(rootDir, filePath)),
+            layer,
+            evaluated,
+            violations,
+        });
+    }
+    const evaluatedReports = reports.filter((report) => report.evaluated);
+    const violatingReports = evaluatedReports.filter((report) => report.violations.length > 0);
+    const complianceRate = evaluatedFiles === 0 ? 100 : (compliantFiles / evaluatedFiles) * 100;
+    console.log(`${colors.bright}${colors.blue}Summary${colors.reset}`);
+    console.log(`${colors.gray}────────${colors.reset}`);
+    console.log(`Evaluated files: ${colors.bright}${evaluatedFiles}${colors.reset}`);
+    console.log(`Compliant files: ${colors.bright}${colors.green}${compliantFiles}${colors.reset}`);
+    console.log(`Files with violations: ${colors.bright}${colors.red}${violatingReports.length}${colors.reset}`);
+    console.log(`Total violations: ${colors.bright}${colors.red}${totalViolations}${colors.reset}`);
+    console.log(`Compliance rate: ${colors.bright}${complianceRate >= 90 ? colors.green : complianceRate >= 70 ? colors.yellow : colors.red}${formatPercent(complianceRate)}${colors.reset}`);
+    console.log();
+    if (layerCounts.size > 0) {
+        console.log(`${colors.bright}${colors.blue}Layer coverage${colors.reset}`);
+        console.log(`${colors.gray}────────────────${colors.reset}`);
+        for (const [layer, count] of Array.from(layerCounts.entries()).sort((a, b) => a[0].localeCompare(b[0]))) {
+            console.log(`- ${layer}: ${count}`);
+        }
+        console.log();
+    }
+    if (ruleCounts.size > 0) {
+        console.log(`${colors.bright}${colors.blue}Violation groups${colors.reset}`);
+        console.log(`${colors.gray}────────────────${colors.reset}`);
+        for (const [ruleId, count] of Array.from(ruleCounts.entries()).sort((a, b) => b[1] - a[1])) {
+            console.log(`- ${ruleId}: ${count}`);
+        }
+        console.log();
+    }
+    if (violatingReports.length > 0) {
+        console.log(`${colors.bright}${colors.red}Files with violations${colors.reset}`);
+        console.log(`${colors.gray}─────────────────────${colors.reset}`);
+        const sortedReports = violatingReports.toSorted((a, b) => b.violations.length - a.violations.length);
+        for (const report of sortedReports.slice(0, 20)) {
+            console.log(`${colors.bright}${report.filePath}${colors.reset} [${report.layer}] (${report.violations.length})`);
+            for (const violation of report.violations.slice(0, 5)) {
+                console.log(`  ${colors.gray}L${violation.line}${colors.reset} ${violation.ruleId} -> ${violation.message} ${colors.gray}[${violation.importPath}]${colors.reset}`);
+            }
+            if (report.violations.length > 5) {
+                console.log(`  ${colors.gray}... and ${report.violations.length - 5} more violation(s)${colors.reset}`);
+            }
+            console.log();
+        }
+        if (sortedReports.length > 20) {
+            console.log(`${colors.gray}... and ${sortedReports.length - 20} more file(s) with violations${colors.reset}`);
+            console.log();
+        }
+    }
+    else {
+        console.log(`${colors.green}${colors.bright}No DAL/Service/Repository boundary violations found.${colors.reset}`);
+        console.log();
+    }
+    console.log(`${colors.cyan}Notes:${colors.reset}`);
+    console.log(`- Only files classified by the configured layers are evaluated`);
+    console.log(`- This report is deterministic and exits with code 1 when violations exist`);
+    console.log();
+    return totalViolations > 0 ? 1 : 0;
+}
+/* v8 ignore start -- executable adapter */
+if (isMainModule(import.meta.url)) {
+    runDalServiceRepositoryGuard().then((code) => {
+        process.exitCode = code;
+    }).catch((error) => {
+        console.error(`${colors.bright}${colors.red}Failed to generate DAL compliance report:${colors.reset}`, error);
+        process.exitCode = 1;
+    });
+}
+/* v8 ignore stop */

package/dist/guards/dependency-cruiser-guard.d.ts

@@ -0,0 +1,14 @@
+import { spawnSync } from 'node:child_process';
+type DependencyCruiserGuardOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    execPath?: string;
+    searchStart?: string;
+    exists?: (target: string) => boolean;
+    readFile?: (target: string, encoding: BufferEncoding) => string;
+    spawn?: typeof spawnSync;
+    error?: (message?: unknown) => void;
+};
+export declare function resolveDependencyCruiserBin(options?: DependencyCruiserGuardOptions): string;
+export declare function runDependencyCruiserGuard(args: string[], options?: DependencyCruiserGuardOptions): number;
+export {};

package/dist/guards/dependency-cruiser-guard.js

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+function findDependencyCruiserPackageRoot(searchStart, exists, readFile) {
+    let current = searchStart;
+    while (true) {
+        if (path.basename(current) !== 'node_modules') {
+            const manifestPath = path.join(current, 'node_modules', 'dependency-cruiser', 'package.json');
+            if (exists(manifestPath)) {
+                const manifest = JSON.parse(readFile(manifestPath, 'utf8'));
+                if (manifest.name === 'dependency-cruiser') {
+                    return path.dirname(manifestPath);
+                }
+            }
+        }
+        const directManifestPath = path.join(current, 'package.json');
+        if (exists(directManifestPath)) {
+            const manifest = JSON.parse(readFile(directManifestPath, 'utf8'));
+            if (manifest.name === 'dependency-cruiser') {
+                return current;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error(`Could not find dependency-cruiser package root from ${searchStart}.`);
+        }
+        current = parent;
+    }
+}
+export function resolveDependencyCruiserBin(options = {}) {
+    const exists = options.exists ?? existsSync;
+    const readFile = options.readFile ?? readFileSync;
+    const searchStart = options.searchStart ?? path.dirname(fileURLToPath(import.meta.url));
+    const packageRoot = findDependencyCruiserPackageRoot(searchStart, exists, readFile);
+    const binPath = path.join(packageRoot, 'bin', 'dependency-cruise.mjs');
+    if (!exists(binPath)) {
+        throw new Error(`dependency-cruiser binary not found at ${binPath}.`);
+    }
+    return binPath;
+}
+export function runDependencyCruiserGuard(args, options = {}) {
+    const writeError = options.error ?? console.error;
+    let binPath;
+    try {
+        binPath = resolveDependencyCruiserBin(options);
+    }
+    catch (error) {
+        writeError(`Dependency Cruiser guard is unavailable: ${error.message}`);
+        writeError('The dependency-cruiser runtime dependency must be resolvable from @titannio/webtoolkit-cli.');
+        return 1;
+    }
+    const result = (options.spawn ?? spawnSync)(options.execPath ?? process.execPath, [binPath, ...args], {
+        cwd: options.cwd ?? process.cwd(),
+        env: {
+            ...(options.env ?? process.env),
+            FORCE_COLOR: '1',
+        },
+        stdio: 'inherit',
+    });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+}
+/* v8 ignore start -- executable adapter */
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    process.exit(runDependencyCruiserGuard(process.argv.slice(2)));
+}
+/* v8 ignore stop */

package/dist/guards/documentation-guard.d.ts

@@ -0,0 +1,3 @@
+import { type DocumentationConfig } from '../config.js';
+export declare function validateDocumentationConfig(config: DocumentationConfig): void;
+export declare function checkDocumentation(root: string, config: DocumentationConfig): string[];