@gtkx/cli 2.0.0-beta.1 → 2.0.0-beta.3

package/src/internal/build-manifest.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 type RecordedPackage = {
     name: string;
     version: string | null;
@@ -7,6 +9,8 @@ type RecordedPackage = {
 type BuildManifest = {
     generator: typeof BUILD_MANIFEST_GENERATOR;
     formatVersion: typeof BUILD_MANIFEST_FORMAT_VERSION;
+    configFile: string;
+    configDigest: string;
     schemas: string[];
     packages: RecordedPackage[];
 };
@@ -17,7 +21,26 @@ type BuildManifestCollector = {
 
 const BUILD_MANIFEST_FILENAME = "gtkx-schemas.json";
 const BUILD_MANIFEST_GENERATOR = "gtkx-build";
-const BUILD_MANIFEST_FORMAT_VERSION = 1;
+const BUILD_MANIFEST_FORMAT_VERSION = 2;
+
+const canonicalConfig = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalConfig(entry));
+    }
+
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+
+    return Object.fromEntries(
+        Object.entries(value)
+            .toSorted(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, canonicalConfig(entry)]),
+    );
+};
+
+const configDigest = (config: unknown): string =>
+    createHash("sha256").update(JSON.stringify(canonicalConfig(config))).digest("hex");
 
 const createBuildManifestCollector = (): BuildManifestCollector => ({ schemas: [] });
 
@@ -25,6 +48,7 @@ export {
     BUILD_MANIFEST_FILENAME,
     BUILD_MANIFEST_FORMAT_VERSION,
     BUILD_MANIFEST_GENERATOR,
+    configDigest,
     createBuildManifestCollector,
     type BuildManifest,
     type BuildManifestCollector,

package/src/internal/build-output.ts

@@ -0,0 +1,113 @@
+import { isPathInside, isRecord } from "@gtkx/utils";
+import { lstatSync, readdirSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import {
+    BUILD_MANIFEST_FILENAME,
+    BUILD_MANIFEST_GENERATOR,
+} from "./build-manifest.js";
+import {
+    type OutputDirectoryTransaction,
+    prepareOutputDirectory,
+    readRegularFile,
+} from "./output-directory.js";
+
+const DEFAULT_BUILD_OUT_DIR = "dist";
+const PRESERVED_BUILD_ENTRIES: ReadonlySet<string> = new Set([".git"]);
+
+type PreparedBuildOutDir = Disposable & { commit: () => void; path: string };
+
+const hasSymlinkComponent = (root: string, target: string): boolean => {
+    let current = root;
+
+    for (const segment of relative(root, target).split(sep)) {
+        current = join(current, segment);
+
+        if (lstatSync(current, { throwIfNoEntry: false })?.isSymbolicLink() === true) {
+            return true;
+        }
+    }
+
+    return false;
+};
+
+const isGtkxBuildDirectory = (path: string): boolean => {
+    const manifest = join(path, BUILD_MANIFEST_FILENAME);
+    const contents = readRegularFile(manifest);
+
+    try {
+        const parsed: unknown = contents === null ? null : JSON.parse(contents);
+
+        return isRecord(parsed) && parsed.generator === BUILD_MANIFEST_GENERATOR;
+    } catch {
+        return false;
+    }
+};
+
+const isReusableBuildDirectory = (path: string): boolean => {
+    const stats = lstatSync(path, { throwIfNoEntry: false });
+
+    if (stats === undefined) {
+        return true;
+    }
+
+    return stats.isDirectory() && (readdirSync(path).length === 0 || isGtkxBuildDirectory(path));
+};
+
+const buildOutputError = (root: string): Error =>
+    new Error(`Build output must be an empty directory or an earlier GTKX build below the project root ${root}`);
+
+const hasGtkxBuildAncestor = (root: string, outDir: string): boolean => {
+    let ancestor = dirname(outDir);
+
+    while (isPathInside(root, ancestor)) {
+        if (isGtkxBuildDirectory(ancestor)) {
+            return true;
+        }
+
+        ancestor = dirname(ancestor);
+    }
+
+    return false;
+};
+
+const assertSafeBuildLocation = (root: string, outDir: string): void => {
+    if (!isPathInside(root, outDir) || hasSymlinkComponent(root, outDir) || hasGtkxBuildAncestor(root, outDir)) {
+        throw buildOutputError(root);
+    }
+};
+
+const resolveBuildOutDir = (root: string, configured?: string): string => {
+    const selected = configured ?? DEFAULT_BUILD_OUT_DIR;
+    const outDir = resolve(root, selected);
+
+    assertSafeBuildLocation(root, outDir);
+
+    if (!isReusableBuildDirectory(outDir)) {
+        throw buildOutputError(root);
+    }
+
+    return outDir;
+};
+
+const prepareBuildOutDir = (root: string, outDir: string): PreparedBuildOutDir => {
+    assertSafeBuildLocation(root, outDir);
+    const prepared = prepareOutputDirectory(root, outDir, isReusableBuildDirectory);
+
+    if (prepared.status === "unsafe") {
+        throw buildOutputError(root);
+    }
+
+    const transaction: OutputDirectoryTransaction = prepared.transaction;
+
+    return {
+        path: transaction.path,
+        commit: () => {
+            transaction.commit(PRESERVED_BUILD_ENTRIES, isGtkxBuildDirectory);
+        },
+        [Symbol.dispose]: () => {
+            transaction[Symbol.dispose]();
+        },
+    };
+};
+
+export { prepareBuildOutDir, resolveBuildOutDir };

package/src/internal/docs-elements.ts

@@ -1,21 +1,27 @@
-import { type ElementProps, type OmittedProps, readBuiltinElements, resolveStore } from "@gtkx/codegen";
+import {
+    type ElementProps,
+    type OmittedProps,
+    resolveStore,
+} from "@gtkx/codegen";
+import { readBuiltinElementsForDocs } from "@gtkx/codegen/internal";
 import { existsSync } from "node:fs";
 
 type DocsElements = {
     props: ElementProps;
     omittedProps: OmittedProps;
+    acceptedChildTypes: Record<string, string[]>;
 };
 
 const resolveDocsElements = async (cwd: string): Promise<DocsElements> => {
     const { gi } = resolveStore(cwd);
 
     if (!existsSync(gi.storeDir)) {
-        return { props: {}, omittedProps: {} };
+        return { props: {}, omittedProps: {}, acceptedChildTypes: {} };
     }
 
-    const { props, omittedProps } = await readBuiltinElements();
+    const { props, omittedProps, acceptedChildTypes } = await readBuiltinElementsForDocs();
 
-    return { props, omittedProps };
+    return { props, omittedProps, acceptedChildTypes };
 };
 
 export { resolveDocsElements };

package/src/internal/entry-arg.ts

@@ -14,6 +14,13 @@ const cwdArg: { cwd: StringArgDef } = {
     },
 };
 
+const configArg: { config: StringArgDef } = {
+    config: {
+        type: "string",
+        description: "Project-relative configuration file (default: gtkx.config.*)",
+    },
+};
+
 const entryArg: { entry: PositionalArgDef; cwd: StringArgDef } = {
     entry: {
         type: "positional",
@@ -57,4 +64,4 @@ const resolveGivenEntry = (cwd: string, entry: string): string => {
 const resolveEntry = (cwd: string, entry: string | undefined): string =>
     entry ? resolveGivenEntry(cwd, entry) : resolveDefaultEntry(cwd);
 
-export { cwdArg, entryArg, resolveCwd, resolveEntry };
+export { configArg, cwdArg, entryArg, resolveCwd, resolveEntry };

package/src/internal/errors.ts

@@ -33,4 +33,4 @@ const withErrorBoundary = <T extends ArgsDef>(command: CommandDef<T>): CommandDe
     };
 };
 
-export { withErrorBoundary };
+export { printError, withErrorBoundary };