@aventara/build 0.0.0-stage → 1.0.0-rc.8

package/dist/computed/computed-fields.reader.js

@@ -0,0 +1,184 @@
+import path from "node:path";
+import ts from "typescript";
+const CONFIG_EXPORTS = ["aventaraConfig", "default"];
+const LAYERS = ["application", "client", "agent"];
+const AGENT_PARENTS = ["root", "application", "client"];
+const PHASES = ["create", "update"];
+class NotExact extends Error {
+}
+export function readConfigComputedFields(configFile, options, oldProgram) {
+    const file = path.resolve(configFile);
+    const program = ts.createProgram({
+        rootNames: [file],
+        options: { ...options, noEmit: true, skipLibCheck: true },
+        ...(oldProgram === undefined ? {} : { oldProgram }),
+    });
+    const checker = program.getTypeChecker();
+    const source = program.getSourceFile(file);
+    const module = source === undefined ? undefined : checker.getSymbolAtLocation(source);
+    const exported = module === undefined
+        ? undefined
+        : CONFIG_EXPORTS.map((name) => checker
+            .getExportsOfModule(module)
+            .find((symbol) => symbol.escapedName === name)).find((symbol) => symbol !== undefined);
+    if (exported === undefined) {
+        return {
+            kind: "unread",
+            reason: "it exports neither `aventaraConfig` nor a default",
+        };
+    }
+    const target = exported.flags & ts.SymbolFlags.Alias
+        ? checker.getAliasedSymbol(exported)
+        : exported;
+    const declared = checker.getTypeOfSymbol(target);
+    const [signature] = declared.getCallSignatures();
+    const config = signature === undefined
+        ? declared
+        : (checker.getAwaitedType(signature.getReturnType()) ??
+            signature.getReturnType());
+    try {
+        return {
+            kind: "read",
+            computedFields: computedFieldsOfType(checker, config),
+        };
+    }
+    catch (error) {
+        if (error instanceof NotExact) {
+            return { kind: "unread", reason: error.message };
+        }
+        throw error;
+    }
+}
+function computedFieldsOfType(checker, config) {
+    assertExact(checker, config, "the configuration");
+    const overlays = Object.fromEntries(LAYERS.map((layer) => {
+        const overlay = stated(checker, config, layer, "the configuration");
+        return [
+            layer,
+            overlay === undefined
+                ? {}
+                : layerComputedFields(checker, overlay, layer),
+        ];
+    }));
+    return {
+        agent: overlays.agent,
+        agentExtends: agentParent(checker, config),
+        application: overlays.application,
+        client: overlays.client,
+        root: layerComputedFields(checker, config, "the root"),
+    };
+}
+function agentParent(checker, config) {
+    const agent = stated(checker, config, "agent", "the configuration");
+    const property = agent?.getProperty("extends");
+    if (property !== undefined && property.flags & ts.SymbolFlags.Optional) {
+        throw new NotExact("`extends` in agent may be absent");
+    }
+    const parent = property === undefined ? undefined : checker.getTypeOfSymbol(property);
+    if (parent === undefined) {
+        return "client";
+    }
+    const named = AGENT_PARENTS.find((candidate) => parent.isStringLiteral() && parent.value === candidate);
+    if (named === undefined) {
+        throw new NotExact(`\`agent.extends\` is \`${checker.typeToString(parent)}\`, not one layer`);
+    }
+    return named;
+}
+function layerComputedFields(checker, layer, where) {
+    const resources = stated(checker, layer, "resources", where);
+    if (resources === undefined) {
+        return {};
+    }
+    const result = {};
+    for (const [resource, block] of members(checker, resources, `${where}'s resources`)) {
+        const fields = stated(checker, block, "fields", `resources.${resource}`);
+        if (fields === undefined) {
+            continue;
+        }
+        const phases = {
+            create: [],
+            update: [],
+        };
+        for (const [field, entry] of members(checker, fields, `resources.${resource}.fields`)) {
+            const at = `resources.${resource}.fields.${field}`;
+            const pipelines = stated(checker, entry, "pipelines", at);
+            const compute = pipelines === undefined
+                ? undefined
+                : stated(checker, pipelines, "compute", `${at}.pipelines`);
+            if (compute === undefined) {
+                continue;
+            }
+            for (const phase of PHASES) {
+                if (stagePresent(checker, compute, phase, `${at}.pipelines.compute`)) {
+                    phases[phase].push(field);
+                }
+            }
+        }
+        const create = phases.create.sort();
+        const update = phases.update.sort();
+        if (create.length > 0 || update.length > 0) {
+            result[resource] = {
+                ...(create.length === 0 ? {} : { create }),
+                ...(update.length === 0 ? {} : { update }),
+            };
+        }
+    }
+    return Object.fromEntries(Object.entries(result).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
+}
+function assertExact(checker, type, where) {
+    if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) {
+        throw new NotExact(`${where} has no type (\`${checker.typeToString(type)}\`)`);
+    }
+    if (type.isUnion()) {
+        throw new NotExact(`${where} is one of several shapes (\`${checker.typeToString(type)}\`)`);
+    }
+    if (checker.getIndexInfosOfType(type).length > 0) {
+        throw new NotExact(`${where} is not a literal: it has an index signature`);
+    }
+}
+function stated(checker, type, name, where) {
+    const property = type.getProperty(name);
+    if (property === undefined) {
+        return undefined;
+    }
+    if (property.flags & ts.SymbolFlags.Optional) {
+        throw new NotExact(`\`${name}\` in ${where} may be absent`);
+    }
+    const value = checker.getTypeOfSymbol(property);
+    if (value.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Never)) {
+        return undefined;
+    }
+    assertExact(checker, value, `\`${name}\` in ${where}`);
+    return value;
+}
+function stagePresent(checker, compute, phase, where) {
+    const property = compute.getProperty(phase);
+    if (property === undefined) {
+        return false;
+    }
+    if (property.flags & ts.SymbolFlags.Optional) {
+        throw new NotExact(`\`${phase}\` in ${where} may be absent`);
+    }
+    const stage = checker.getTypeOfSymbol(property);
+    if (stage.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Never)) {
+        return false;
+    }
+    const undefinedMember = (candidate) => (candidate.flags & ts.TypeFlags.Undefined) !== 0;
+    if (stage.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown) ||
+        (stage.isUnion() && stage.types.some(undefinedMember))) {
+        throw new NotExact(`\`${phase}\` in ${where} may be undefined (\`${checker.typeToString(stage)}\`)`);
+    }
+    return true;
+}
+function members(checker, type, where) {
+    return type
+        .getProperties()
+        .map((property) => {
+        const name = property.getName();
+        const value = stated(checker, type, name, where);
+        return value === undefined
+            ? undefined
+            : [name, value];
+    })
+        .filter((entry) => entry !== undefined);
+}

package/dist/contracts/contracts-file.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createJiti } from "jiti";
+import { readGeneratedFile, writeGeneratedFile, } from "../project/generated-file.js";
+export function writeContractsFile(projectDirectory, contractsFile, compiled) {
+    return writeGeneratedFile(projectDirectory, contractsFile, compiled.source);
+}
+export async function checkContractsFile(projectDirectory, contractsFile, compiled, changesOf) {
+    const file = path.join(projectDirectory, contractsFile);
+    const text = readGeneratedFile(projectDirectory, contractsFile);
+    if (text === undefined) {
+        return { kind: "missing" };
+    }
+    if (text === compiled.source) {
+        return { kind: "fresh" };
+    }
+    const previous = await previousContracts(projectDirectory, file);
+    if (previous === undefined) {
+        return {
+            kind: "stale",
+            changes: ["it could not be read as a prebuilt Contracts file"],
+        };
+    }
+    const changes = changesOf(previous, compiled.prebuilt);
+    return {
+        kind: "stale",
+        changes: changes.length > 0
+            ? changes
+            : [
+                "its text is not what this build writes, though it records the same core version, file format and inputs",
+            ],
+    };
+}
+async function previousContracts(projectDirectory, file) {
+    const jiti = createJiti(pathToFileURL(path.join(projectDirectory, "package.json")).href, { moduleCache: false, fsCache: false, interopDefault: false });
+    try {
+        const module = await jiti.import(file);
+        return module.aventaraContracts?.fingerprints?.resources === undefined
+            ? undefined
+            : module.aventaraContracts;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/contracts/prebuilt-contracts.compiler.js

@@ -0,0 +1,49 @@
+import { AvBuildError } from "../build.error.js";
+function notAtBuildTime() {
+    throw new AvBuildError("the adapter was called during aventara-build; a build compiles the Contracts and runs no operation.");
+}
+function buildTimeAdapter(description) {
+    return {
+        model: description.model,
+        ...(description.referentialActions === undefined
+            ? {}
+            : { referentialActions: description.referentialActions }),
+        ...(description.computedFields === undefined
+            ? {}
+            : { computedFields: description.computedFields }),
+        ...(description.sqlStatements === undefined
+            ? {}
+            : { sqlStatements: description.sqlStatements }),
+        execute: notAtBuildTime,
+        ...(description.sqlStatements === true
+            ? { executeSql: notAtBuildTime }
+            : {}),
+        ...(description.transactions === "interactive"
+            ? { transaction: notAtBuildTime }
+            : {}),
+    };
+}
+function diagnosticLines(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => `  - ${diagnostic.code} at ${diagnostic.path}: ${diagnostic.message} (${diagnostic.docs})`)
+        .join("\n");
+}
+export async function compilePrebuiltContracts(project) {
+    const { core, internal, config, description } = project;
+    let contracts;
+    try {
+        const framework = await core.createFramework({
+            ...config,
+            adapter: buildTimeAdapter(description),
+        });
+        contracts = framework.contracts;
+    }
+    catch (error) {
+        if (error instanceof core.AvConstructionError) {
+            throw new AvBuildError(`${project.configFile} with ${project.adapterFile} does not compile: ${error.message} (${error.stage}).\n${diagnosticLines(error.diagnostics)}`, { cause: error });
+        }
+        throw error;
+    }
+    const prebuilt = await internal.prebuiltContractsOf(description.model, config, contracts);
+    return { prebuilt, source: internal.emitPrebuiltContracts(prebuilt) };
+}

package/dist/node-version.guard.js

@@ -0,0 +1,47 @@
+import { readFileSync } from "fs";
+function versionOf(text) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(text);
+    if (match === null) {
+        throw new Error(`"${text}" is not a Node version`);
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareVersions(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        const difference = left[index] - right[index];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+}
+function admits(range, version) {
+    return range.split("||").some((part) => {
+        const comparator = /^\s*(\^|>=)(\d+\.\d+\.\d+)\s*$/.exec(part);
+        if (comparator === null) {
+            throw new Error(`engines.node "${range}": the bin's Node guard reads only "^x.y.z" and ">=x.y.z" joined by "||"`);
+        }
+        const floor = versionOf(comparator[2]);
+        return (compareVersions(version, floor) >= 0 &&
+            (comparator[1] === ">=" || version[0] === floor[0]));
+    });
+}
+export function nodeVersionRefusal(bin, packageName, range, version) {
+    return admits(range, versionOf(version))
+        ? undefined
+        : `${bin}: Node ${version} is not supported; ${packageName} needs Node ${range}.`;
+}
+export function refuseUnsupportedNode(bin, manifestUrl) {
+    const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
+    const range = manifest.engines === undefined ? undefined : manifest.engines.node;
+    if (range === undefined) {
+        throw new Error(`${manifest.name} declares no engines.node for its bin's Node guard`);
+    }
+    const refusal = nodeVersionRefusal(bin, manifest.name, range, process.version);
+    if (refusal === undefined) {
+        return false;
+    }
+    process.stderr.write(`${refusal}\n`);
+    process.exitCode = 1;
+    return true;
+}

package/dist/project/generated-file.js

@@ -0,0 +1,19 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+export function readGeneratedFile(projectDirectory, file) {
+    try {
+        return readFileSync(path.join(projectDirectory, file), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeGeneratedFile(projectDirectory, file, text) {
+    if (readGeneratedFile(projectDirectory, file) === text) {
+        return "unchanged";
+    }
+    const target = path.join(projectDirectory, file);
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(target, text);
+    return "written";
+}

package/dist/project/generated-files.resolver.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+const DEFAULT_DIRECTORY = "src/generated/aventara";
+const TREE_EXPORT = "aventaraResources";
+const TREE_MODULE = "resources.generated";
+function filesIn(directory) {
+    return {
+        resources: `${directory}/${TREE_MODULE}.ts`,
+        computedFields: `${directory}/computed-fields.generated.ts`,
+        contracts: `${directory}/contracts.generated.ts`,
+    };
+}
+export const DEFAULT_GENERATED_FILES = filesIn(DEFAULT_DIRECTORY);
+function treeSpecifier(source) {
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) ||
+            !ts.isStringLiteral(statement.moduleSpecifier) ||
+            statement.importClause?.namedBindings === undefined ||
+            !ts.isNamedImports(statement.importClause.namedBindings)) {
+            continue;
+        }
+        const imported = statement.importClause.namedBindings.elements.some((element) => (element.propertyName ?? element.name).text === TREE_EXPORT);
+        const specifier = statement.moduleSpecifier.text;
+        if (imported && specifier.startsWith(".")) {
+            return specifier;
+        }
+    }
+    return undefined;
+}
+export function resolveGeneratedFiles(projectDirectory, configFile) {
+    const configPath = path.join(projectDirectory, configFile);
+    const source = ts.createSourceFile(configPath, readFileSync(configPath, "utf8"), ts.ScriptTarget.Latest, false);
+    const specifier = treeSpecifier(source);
+    if (specifier === undefined) {
+        return DEFAULT_GENERATED_FILES;
+    }
+    const module = path.resolve(path.dirname(configPath), specifier);
+    const directory = path.relative(projectDirectory, path.dirname(module));
+    const inside = directory !== "" &&
+        directory !== ".." &&
+        !directory.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(directory);
+    return inside &&
+        path.basename(module).replace(/\.[cm]?[jt]s$/, "") === TREE_MODULE
+        ? filesIn(directory.split(path.sep).join("/"))
+        : DEFAULT_GENERATED_FILES;
+}

package/dist/project/project-modules.loader.js

@@ -0,0 +1,119 @@
+import { statSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createJiti } from "jiti";
+import { AvBuildError } from "../build.error.js";
+const EXTENSIONS = [".js", ".ts", ".mjs", ".cjs", ".mts", ".cts"];
+const EXTENSIONS_AS_LISTED = [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"];
+export const PROJECT_MODULES = {
+    config: "src/aventara.config",
+    adapter: "src/aventara.adapter",
+};
+const CONFIG_EXPORTS = ["aventaraConfig", "default"];
+function projectFile(projectDirectory, module) {
+    const present = EXTENSIONS.map((extension) => `${module}${extension}`).filter((file) => statSync(path.join(projectDirectory, file), {
+        throwIfNoEntry: false,
+    })?.isFile() === true);
+    if (present.length === 0) {
+        const [first, ...others] = EXTENSIONS_AS_LISTED;
+        throw new AvBuildError(`no ${module}${first}, ${others.slice(0, -1).join(", ")} or ${others.at(-1)} in ${projectDirectory}. Run aventara-build from the project's root (the aventara:prepare script does).`);
+    }
+    if (present.length > 1) {
+        throw new AvBuildError(`${present.slice(0, -1).join(", ")} and ${present.at(-1)} are all ${module}; keep one and delete the other${present.length > 2 ? "s" : ""}.`);
+    }
+    return present[0];
+}
+async function evaluate(jiti, projectDirectory, file) {
+    try {
+        return await jiti.import(path.join(projectDirectory, file));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new AvBuildError(`${file} could not be run: ${message.split("\n", 1)[0]}. aventara-build runs it at build time, so its top-level code must run without a server, a database client or a request.`, { cause: error });
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function configOf(file, namespace) {
+    const name = CONFIG_EXPORTS.find((candidate) => Object.hasOwn(namespace, candidate));
+    if (name === undefined) {
+        throw new AvBuildError(`${file} exports neither \`aventaraConfig\` nor a default: export the configuration as \`export const aventaraConfig = { … } as const\`.`);
+    }
+    const shown = name === "default" ? "its default export" : `\`${name}\``;
+    const value = namespace[name];
+    if (typeof value === "function") {
+        throw new AvBuildError(`${shown} in ${file} is a function. aventara-build runs the configuration without a database client, so export the configuration itself, as a value without \`adapter\`, and join the adapter where the framework is created (\`{ ...aventaraConfig, adapter }\`).`);
+    }
+    if (!isRecord(value)) {
+        throw new AvBuildError(`${shown} in ${file} is not an object: it must be the configuration, \`{ api, … } as const\`.`);
+    }
+    if (Object.hasOwn(value, "adapter")) {
+        throw new AvBuildError(`${shown} in ${file} builds its own adapter (\`adapter\`). Export the configuration without it and join the adapter where the framework is created: \`{ ...aventaraConfig, adapter: await createPrismaAdapter({ ...adapter, client }) }\`.`);
+    }
+    if (Object.hasOwn(value, "prebuilt")) {
+        throw new AvBuildError(`${shown} in ${file} sets \`prebuilt\`, which is this build's output: pass it where the framework is created.`);
+    }
+    return value;
+}
+const TRANSACTIONS = [
+    "interactive",
+    "none",
+];
+function descriptionOf(file, namespace) {
+    const shape = "`export default describePrismaAdapter({ discovery, provider, driver })` (or your adapter's describe function)";
+    if (!Object.hasOwn(namespace, "default")) {
+        throw new AvBuildError(`${file} has no default export; it must be the adapter's description: ${shape}.`);
+    }
+    const value = namespace.default;
+    if (!isRecord(value)) {
+        throw new AvBuildError(`${file}'s default export is not an object; it must be the adapter's description: ${shape}.`);
+    }
+    const wrong = (member, expected) => new AvBuildError(`${file}'s default export is not an adapter description: its \`${member}\` is not ${expected}. It must be ${shape}.`);
+    if (!isRecord(value.model)) {
+        throw wrong("model", "an object");
+    }
+    if (!TRANSACTIONS.includes(value.transactions)) {
+        throw wrong("transactions", '"interactive" or "none"');
+    }
+    for (const member of ["referentialActions", "computedFields"]) {
+        if (value[member] !== undefined && !isRecord(value[member])) {
+            throw wrong(member, "an object");
+        }
+    }
+    if (value.sqlStatements !== undefined &&
+        typeof value.sqlStatements !== "boolean") {
+        throw wrong("sqlStatements", "a boolean");
+    }
+    return value;
+}
+async function projectCore(jiti) {
+    try {
+        const [core, internal] = await Promise.all([
+            jiti.import("@aventara/core"),
+            jiti.import("@aventara/core/internal"),
+        ]);
+        return { core, internal };
+    }
+    catch (error) {
+        throw new AvBuildError(`@aventara/core could not be loaded from the project (${error instanceof Error ? error.message.split("\n", 1)[0] : String(error)}); install it beside @aventara/build.`, { cause: error });
+    }
+}
+export function findProjectModules(projectDirectory) {
+    return {
+        configFile: projectFile(projectDirectory, PROJECT_MODULES.config),
+        adapterFile: projectFile(projectDirectory, PROJECT_MODULES.adapter),
+    };
+}
+export async function loadProjectModules(projectDirectory, { configFile, adapterFile }) {
+    const jiti = createJiti(pathToFileURL(path.join(projectDirectory, "package.json")).href, {
+        moduleCache: false,
+        fsCache: false,
+        interopDefault: false,
+        nativeModules: ["@aventara/core"],
+    });
+    const project = await projectCore(jiti);
+    const config = configOf(configFile, await evaluate(jiti, projectDirectory, configFile));
+    const description = descriptionOf(adapterFile, await evaluate(jiti, projectDirectory, adapterFile));
+    return { ...project, configFile, config, adapterFile, description };
+}

package/dist/project/tsconfig.reader.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { AvBuildError } from "../build.error.js";
+function defaultOptions() {
+    return {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        strict: true,
+    };
+}
+export function projectCompilerOptions(projectDirectory) {
+    assertClassicCompilerApi();
+    const tsconfig = ts.findConfigFile(projectDirectory, ts.sys.fileExists, "tsconfig.json");
+    if (tsconfig === undefined) {
+        return defaultOptions();
+    }
+    const read = ts.readConfigFile(tsconfig, ts.sys.readFile);
+    if (read.error !== undefined) {
+        return defaultOptions();
+    }
+    return ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(tsconfig)).options;
+}
+export function importSuffixOf(options, directory) {
+    if (options.allowImportingTsExtensions === true ||
+        options
+            .rewriteRelativeImportExtensions === true) {
+        return ".ts";
+    }
+    if (options.module === ts.ModuleKind.CommonJS ||
+        options.moduleResolution === ts.ModuleResolutionKind.Bundler) {
+        return "";
+    }
+    if (options.module === ts.ModuleKind.Node16 ||
+        options.module === ts.ModuleKind.NodeNext) {
+        return packageType(directory) === "module" ? ".js" : "";
+    }
+    return ".js";
+}
+function packageType(directory) {
+    for (let current = path.resolve(directory);;) {
+        const manifest = path.join(current, "package.json");
+        if (existsSync(manifest)) {
+            try {
+                return JSON.parse(readFileSync(manifest, "utf8")).type;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+export function relativeSpecifier(from, to, suffix) {
+    const relative = path
+        .relative(path.dirname(from), to.replace(/\.ts$/, ""))
+        .split(path.sep)
+        .join("/");
+    return `${relative.startsWith(".") ? relative : `./${relative}`}${suffix}`;
+}
+function assertClassicCompilerApi() {
+    const compiler = ts;
+    if (typeof compiler?.createProgram === "function" &&
+        typeof compiler.findConfigFile === "function") {
+        return;
+    }
+    throw new AvBuildError(`the installed \`typescript\` ${compiler?.version ?? "(no version)"} has no classic compiler API (\`createProgram\`), which aventara-build reads the project's Resources and configuration with; install a \`typescript\` below 7.`);
+}