import { existsSync, readFileSync, readdirSync } from "node:fs"; import { dirname, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import { describe, expect, it } from "vitest"; import { SUPPORTED_PLUGINS } from "./registry.js"; const TEST_DIR = dirname(fileURLToPath(import.meta.url)); type PlaceholderDocsCase = { integrationId: string; expectedPlaceholder: string; rejectsPostgresStyle?: boolean; }; const DOC_DIRECTORY_ALIASES = { graphqlintegration: "graphql", } as const; const DOC_DIRECTORY_EXCLUSIONS = new Set(["base"]); function hasDocDirectoryAlias( pluginId: string, ): pluginId is keyof typeof DOC_DIRECTORY_ALIASES { return pluginId in DOC_DIRECTORY_ALIASES; } const EXPECTED_DOC_DIRECTORIES = Array.from( new Set( Object.values(SUPPORTED_PLUGINS) .map((pluginId) => hasDocDirectoryAlias(pluginId) ? DOC_DIRECTORY_ALIASES[pluginId] : pluginId, ) .filter((directory) => !DOC_DIRECTORY_EXCLUSIONS.has(directory)), ), ).sort(); const ACTUAL_DOC_DIRECTORIES = readdirSync(TEST_DIR, { withFileTypes: true }) .filter((entry) => entry.isDirectory()) .map((entry) => entry.name) .filter((directory) => !DOC_DIRECTORY_EXCLUSIONS.has(directory)) .sort(); const PLACEHOLDER_DOC_CASES: PlaceholderDocsCase[] = [ { integrationId: "athena", expectedPlaceholder: "?" }, { integrationId: "bigquery", expectedPlaceholder: "?" }, { integrationId: "cockroachdb", expectedPlaceholder: "$1", rejectsPostgresStyle: false, }, { integrationId: "databricks", expectedPlaceholder: ":PARAM_1" }, { integrationId: "dynamodb", expectedPlaceholder: "?" }, { integrationId: "lakebase", expectedPlaceholder: "$1", rejectsPostgresStyle: false, }, { integrationId: "mariadb", expectedPlaceholder: "?" }, { integrationId: "mssql", expectedPlaceholder: "@PARAM_1" }, { integrationId: "mysql", expectedPlaceholder: "?" }, { integrationId: "oracledb", expectedPlaceholder: ":1" }, { integrationId: "redshift", expectedPlaceholder: "$1", rejectsPostgresStyle: false, }, { integrationId: "snowflake", expectedPlaceholder: "?" }, { integrationId: "snowflakepostgres", expectedPlaceholder: "$1", rejectsPostgresStyle: false, }, ]; function readIntegrationFile(integrationId: string, fileName: string): string { return readFileSync(resolve(TEST_DIR, integrationId, fileName), "utf8"); } describe("SQL integration documentation", () => { it("documents every supported integration directory", () => { expect(ACTUAL_DOC_DIRECTORIES).toEqual(EXPECTED_DOC_DIRECTORIES); for (const integrationId of EXPECTED_DOC_DIRECTORIES) { expect(existsSync(resolve(TEST_DIR, integrationId, "README.md"))).toBe( true, ); expect(existsSync(resolve(TEST_DIR, integrationId, "types.ts"))).toBe( true, ); } }); it.each(PLACEHOLDER_DOC_CASES)( "$integrationId README uses $expectedPlaceholder placeholders", ({ integrationId, expectedPlaceholder, rejectsPostgresStyle = true }) => { const readme = readIntegrationFile(integrationId, "README.md"); expect(readme).toContain(expectedPlaceholder); if (rejectsPostgresStyle) { expect(readme).not.toMatch(/\$\d+/); } }, ); it.each(PLACEHOLDER_DOC_CASES)( "$integrationId JSDoc uses $expectedPlaceholder placeholders", ({ integrationId, expectedPlaceholder, rejectsPostgresStyle = true }) => { const typeDocs = readIntegrationFile(integrationId, "types.ts"); expect(typeDocs).toContain(expectedPlaceholder); if (rejectsPostgresStyle) { expect(typeDocs).not.toMatch(/\$\d+/); } }, ); });