@chidchanun/bcp 0.2.1 → 0.2.3

package/packages/config/src/diagnostics.ts

@@ -0,0 +1,226 @@
+import path from "node:path";
+
+import {
+    resolveBcpConfig,
+    type ResolveBcpConfigOverrides,
+    type ResolvedBcpConfig,
+} from "./index.js";
+import {
+    loadBcpEnvironmentSchema,
+} from "./environment-loader.js";
+import {
+    validateEnvironment,
+    type BcpEnvironmentValidationResult,
+} from "./environment-schema.js";
+
+export type BcpConfigurationDiagnosticSeverity =
+    | "error"
+    | "warning";
+
+export interface BcpConfigurationDiagnostic {
+    severity: BcpConfigurationDiagnosticSeverity;
+    code: string;
+    message: string;
+}
+
+export interface BcpConfigurationDiagnosticsReport {
+    ok: boolean;
+    mode: string;
+    configFile: string | null;
+    environmentSchemaFile: string | null;
+    resolvedConfig: ResolvedBcpConfig;
+    environment: {
+        checked: number;
+        present: number;
+        defaults: number;
+    };
+    diagnostics: BcpConfigurationDiagnostic[];
+}
+
+export interface DiagnoseBcpConfigurationOptions {
+    rootDirectory: string;
+    mode: string;
+    environment?: NodeJS.ProcessEnv;
+    overrides?: ResolveBcpConfigOverrides;
+}
+
+export async function diagnoseBcpConfiguration(
+    options: DiagnoseBcpConfigurationOptions
+): Promise<BcpConfigurationDiagnosticsReport> {
+    const environment =
+        options.environment ??
+        process.env;
+    const resolved =
+        await resolveBcpConfig(
+            options.rootDirectory,
+            options.overrides ?? {},
+            environment
+        );
+    const loadedSchema =
+        await loadBcpEnvironmentSchema(
+            options.rootDirectory
+        );
+    const environmentValidation =
+        validateEnvironment(
+            loadedSchema.schema,
+            environment
+        );
+    const diagnostics:
+        BcpConfigurationDiagnostic[] = [];
+
+    appendEnvironmentDiagnostics(
+        diagnostics,
+        environmentValidation
+    );
+    appendRuntimeDiagnostics(
+        diagnostics,
+        options.mode,
+        resolved.config,
+        environment
+    );
+
+    return {
+        ok:
+            !diagnostics.some(
+                (diagnostic) =>
+                    diagnostic.severity ===
+                    "error"
+            ),
+        mode:
+            options.mode,
+        configFile:
+            resolved.file
+                ? path.basename(
+                    resolved.file
+                )
+                : null,
+        environmentSchemaFile:
+            loadedSchema.file
+                ? path.basename(
+                    loadedSchema.file
+                )
+                : null,
+        resolvedConfig:
+            resolved.config,
+        environment: {
+            checked:
+                environmentValidation.checked,
+            present:
+                environmentValidation.present,
+            defaults:
+                environmentValidation.defaults,
+        },
+        diagnostics,
+    };
+}
+
+export function assertConfigurationDiagnostics(
+    report: BcpConfigurationDiagnosticsReport
+): void {
+    if (
+        report.ok
+    ) {
+        return;
+    }
+
+    const errors =
+        report.diagnostics
+            .filter(
+                (diagnostic) =>
+                    diagnostic.severity ===
+                    "error"
+            )
+            .map(
+                (diagnostic) =>
+                    diagnostic.message
+            );
+
+    throw new Error(
+        `BCP Configuration Error:\n${errors.map((message) => `- ${message}`).join("\n")}`
+    );
+}
+
+function appendEnvironmentDiagnostics(
+    diagnostics: BcpConfigurationDiagnostic[],
+    validation: BcpEnvironmentValidationResult
+): void {
+    for (
+        const issue
+        of validation.issues
+    ) {
+        diagnostics.push({
+            severity:
+                issue.severity,
+            code:
+                `environment.${issue.code}`,
+            message:
+                issue.message,
+        });
+    }
+}
+
+function appendRuntimeDiagnostics(
+    diagnostics: BcpConfigurationDiagnostic[],
+    mode: string,
+    config: ResolvedBcpConfig,
+    environment: NodeJS.ProcessEnv
+): void {
+    if (
+        mode !== "production"
+    ) {
+        return;
+    }
+
+    if (
+        config.build.sourceMaps
+    ) {
+        diagnostics.push({
+            severity: "warning",
+            code: "production.source_maps",
+            message:
+                "Production source maps are enabled. Confirm that exposing source information is intentional.",
+        });
+    }
+
+    if (
+        config.security.poweredByHeader
+    ) {
+        diagnostics.push({
+            severity: "warning",
+            code: "production.powered_by",
+            message:
+                "security.poweredByHeader is enabled in production.",
+        });
+    }
+
+    if (
+        config.security.contentSecurityPolicy ===
+        false
+    ) {
+        diagnostics.push({
+            severity: "warning",
+            code: "production.csp_disabled",
+            message:
+                "Content-Security-Policy is disabled. Configure a policy when the application can support one.",
+        });
+    }
+
+    const trustProxy =
+        environment.BCP_TRUST_PROXY
+            ?.trim()
+            .toLowerCase();
+
+    if (
+        trustProxy === "true" ||
+        trustProxy === "1" ||
+        trustProxy === "yes" ||
+        trustProxy === "on"
+    ) {
+        diagnostics.push({
+            severity: "warning",
+            code: "production.trust_proxy",
+            message:
+                "BCP_TRUST_PROXY is enabled. Ensure untrusted clients cannot bypass the trusted reverse proxy/load balancer.",
+        });
+    }
+}

package/packages/config/src/environment-loader.ts

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+    pathToFileURL,
+} from "node:url";
+
+import {
+    assertEnvironmentSchema,
+    type BcpEnvironmentSchema,
+} from "./environment-schema.js";
+
+const ENVIRONMENT_SCHEMA_FILES = [
+    "bcp.environment.ts",
+    "bcp.environment.mts",
+    "bcp.environment.js",
+    "bcp.environment.mjs",
+] as const;
+
+export interface LoadedBcpEnvironmentSchema {
+    file: string | null;
+    schema: BcpEnvironmentSchema;
+}
+
+export function getEnvironmentSchemaFileNames(): string[] {
+    return [
+        ...ENVIRONMENT_SCHEMA_FILES,
+    ];
+}
+
+export async function loadBcpEnvironmentSchema(
+    rootDirectory: string
+): Promise<LoadedBcpEnvironmentSchema> {
+    const matches =
+        ENVIRONMENT_SCHEMA_FILES
+            .map(
+                (fileName) =>
+                    path.join(
+                        rootDirectory,
+                        fileName
+                    )
+            )
+            .filter(
+                (filePath) =>
+                    fs.existsSync(
+                        filePath
+                    )
+            );
+
+    if (
+        matches.length > 1
+    ) {
+        throw new Error(
+            `BCP Framework: multiple environment schema files found: ${matches.map((file) => path.basename(file)).join(", ")}. Keep only one bcp.environment file.`
+        );
+    }
+
+    if (
+        matches.length === 0
+    ) {
+        return {
+            file: null,
+            schema: {},
+        };
+    }
+
+    const file =
+        matches[0];
+    const url =
+        pathToFileURL(
+            file
+        );
+
+    url.searchParams.set(
+        "bcp-environment",
+        `${Date.now()}-${Math.random()}`
+    );
+
+    const module =
+        await import(
+            url.href
+        );
+    const schema =
+        module.default;
+
+    if (
+        schema === undefined
+    ) {
+        throw new Error(
+            `BCP Framework: ${path.basename(file)} must export a default environment schema.`
+        );
+    }
+
+    assertEnvironmentSchema(
+        schema
+    );
+
+    return {
+        file,
+        schema,
+    };
+}