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

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

@@ -0,0 +1,37 @@
+function literal(computedFields) {
+    const ordered = {
+        agent: computedFields.agent,
+        agentExtends: computedFields.agentExtends,
+        application: computedFields.application,
+        client: computedFields.client,
+        root: computedFields.root,
+    };
+    return JSON.stringify(ordered, null, "\t");
+}
+export function emitComputedFieldsModule(configFile, reading) {
+    const header = `// Generated by aventara-build from the type of ${configFile}. Do not edit: regenerate it (aventara:prepare).`;
+    const type = [
+        "",
+        "// What an adapter's discovery artifact carries on its model's type for the stages that run before compute.",
+        "export type AvComputedFields = typeof computedFields;",
+    ];
+    if (reading.kind === "unread") {
+        return `${[
+            header,
+            "",
+            `// Not read: ${reading.reason.replaceAll("\n", " ")}. The stages that run before compute may leave any`,
+            "// create field out; write the configuration `as const` there to have it read.",
+            "export const computedFields = null;",
+            ...type,
+        ].join("\n")}\n`;
+    }
+    return `${[
+        header,
+        'import type { AvConfigComputedFields } from "@aventara/core";',
+        "",
+        "// Which fields the configuration's write compute fills (`compute.create`, `compute.update`), per layer and",
+        "// Resource. The framework compares it with the configuration at startup and warns when they differ.",
+        `export const computedFields = ${literal(reading.computedFields)} as const satisfies AvConfigComputedFields;`,
+        ...type,
+    ].join("\n")}\n`;
+}

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,56 @@
+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;
+    let api;
+    try {
+        const framework = await core.createFramework({
+            ...config,
+            adapter: buildTimeAdapter(description),
+        });
+        contracts = framework.contracts;
+        api = framework.api;
+    }
+    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),
+        client: contracts.client,
+        api,
+    };
+}

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,51 @@
+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, defaultDirectory = DEFAULT_DIRECTORY) {
+    const fallback = defaultDirectory === DEFAULT_DIRECTORY
+        ? DEFAULT_GENERATED_FILES
+        : filesIn(defaultDirectory);
+    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 fallback;
+    }
+    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("/"))
+        : fallback;
+}

package/dist/project/host.catalog.generated.js

@@ -0,0 +1,32 @@
+export const HOST_CATALOG = [
+    {
+        "alias": "nest",
+        "label": "NestJS",
+        "package": "@aventara/nest",
+        "framework": {
+            "package": "@nestjs/core",
+            "range": "^12.0.0"
+        },
+        "layout": {
+            "config": "src/aventara.config",
+            "adapter": "src/aventara.adapter",
+            "generated": "src/generated/aventara"
+        }
+    },
+    {
+        "alias": "next",
+        "label": "Next.js",
+        "package": "@aventara/next",
+        "framework": {
+            "package": "next",
+            "range": ">=16.4 <17"
+        },
+        "layout": {
+            "config": "src/aventara/config",
+            "adapter": "src/aventara/adapter",
+            "generated": "src/aventara/generated",
+            "client": "src/aventara/client.ts",
+            "universal": "src/aventara/universal.ts"
+        }
+    }
+];

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

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { AvEnvFileError, resolveEnvCascade } from "@aventara/client/internal";
+import { AvBuildError } from "../build.error.js";
+export function applyProjectEnv(projectDirectory, env = process.env) {
+    let cascade;
+    try {
+        cascade = resolveEnvCascade({
+            directory: projectDirectory,
+            processEnv: { ...env },
+        });
+    }
+    catch (error) {
+        if (error instanceof AvEnvFileError) {
+            throw new AvBuildError(`${error.message.replace(error.filePath, path.relative(projectDirectory, error.filePath))}.`);
+        }
+        throw error;
+    }
+    const added = [];
+    for (const [name, value] of Object.entries(cascade.env)) {
+        if (env[name] === undefined) {
+            env[name] = value;
+            added.push(name);
+        }
+    }
+    return {
+        loaded: cascade.loaded,
+        restore: () => {
+            for (const name of added) {
+                delete env[name];
+            }
+        },
+    };
+}

package/dist/project/project-layout.resolver.js

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { AvBuildError } from "../build.error.js";
+import { HOST_CATALOG } from "./host.catalog.generated.js";
+const FALLBACK_HOST = "nest";
+function clientLayoutOf(entry) {
+    const { client, universal } = entry.layout;
+    if (client === undefined && universal === undefined) {
+        return undefined;
+    }
+    if (client === undefined ||
+        universal === undefined ||
+        path.posix.dirname(client) !== path.posix.dirname(universal)) {
+        throw new AvBuildError(`${entry.package} declares its browser client at ${client ?? "nowhere"} and its universal entry at ${universal ?? "nowhere"}; the build writes both into one folder, so a host declares both, side by side.`);
+    }
+    return {
+        folder: path.posix.dirname(client),
+        entry: path.posix.basename(client),
+        universal: path.posix.basename(universal),
+    };
+}
+function layoutOf(entry) {
+    const client = clientLayoutOf(entry);
+    return {
+        host: entry.alias,
+        described: entry.alias === FALLBACK_HOST
+            ? `a ${entry.label} project`
+            : `a ${entry.label} project (it depends on ${entry.package})`,
+        config: entry.layout.config,
+        adapter: entry.layout.adapter,
+        generated: entry.layout.generated,
+        ...(client === undefined ? {} : { client }),
+    };
+}
+export const PROJECT_LAYOUTS = Object.fromEntries(HOST_CATALOG.map((entry) => [entry.alias, layoutOf(entry)]));
+const DEPENDENCY_LISTS = ["dependencies", "devDependencies"];
+function hostsOf(projectDirectory) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(path.join(projectDirectory, "package.json"), "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const lists = DEPENDENCY_LISTS.map((list) => typeof manifest === "object" && manifest !== null
+        ? manifest[list]
+        : undefined);
+    return HOST_CATALOG.filter((entry) => lists.some((list) => typeof list === "object" &&
+        list !== null &&
+        Object.hasOwn(list, entry.package)));
+}
+export function resolveProjectLayout(projectDirectory) {
+    const hosts = hostsOf(projectDirectory);
+    if (hosts.length > 1) {
+        throw new AvBuildError(`${projectDirectory}/package.json depends on both ${hosts.map((host) => host.package).join(" and ")}, so it is not clear where the configuration and the adapter are. A project hosts its framework in one of them; remove the other.`);
+    }
+    const [host] = hosts;
+    return PROJECT_LAYOUTS[host === undefined ? FALLBACK_HOST : host.alias];
+}