@arkebcacy/beacon-cli-temp 0.1.1

package/src/schema/terms/collection/lib/create.ts

@@ -0,0 +1,33 @@
+import apiCreate from '#cli/cs/terms/create.js';
+import type Term from '#cli/cs/terms/Term.js';
+import type TransferResults from '#cli/schema/xfer/TransferResults.js';
+import { MutableTransferResults } from '#cli/schema/xfer/TransferResults.js';
+import type ProgressBar from '#cli/ui/progress/ProgressBar.js';
+import ProgressReporter from '#cli/ui/progress/ProgressReporter.js';
+import type Collection from '../Collection.js';
+
+export default function create(
+	this: Collection,
+	term: Term,
+	idx?: number,
+): (bar: ProgressBar) => Promise<TransferResults> {
+	this.byUid.set(term.uid, term);
+	const order = this.insertTermIntoSiblings(term, idx) + 1;
+
+	return async (bar) => {
+		const results = new MutableTransferResults();
+		using reporter = new ProgressReporter(bar, 'creating', term.name);
+
+		try {
+			await apiCreate(this.client, this.taxonomy.uid, term, order);
+			results.created.add(term.uid);
+		} catch (ex: unknown) {
+			results.errored.set(term.uid, ex);
+		} finally {
+			bar.increment();
+			reporter.finish('created');
+		}
+
+		return results;
+	};
+}

package/src/schema/terms/collection/lib/descendants.ts

@@ -0,0 +1,14 @@
+import type Term from '#cli/cs/terms/Term.js';
+import type Collection from '../Collection.js';
+
+export default function* descendants(
+	this: Collection,
+	parentUid: string | null,
+): Generator<Term> {
+	const children = this.children(parentUid);
+
+	for (const child of children) {
+		yield child;
+		yield* this.descendants(child.uid);
+	}
+}

package/src/schema/terms/collection/lib/getRequired.ts

@@ -0,0 +1,11 @@
+import type Term from '#cli/cs/terms/Term.js';
+import type Collection from '../Collection.js';
+
+export default function getRequired(this: Collection, uid: Term['uid']) {
+	const existing = this.byUid.get(uid);
+	if (!existing) {
+		throw new Error(`Term ${uid} not found`);
+	}
+
+	return existing;
+}

package/src/schema/terms/collection/lib/getSiblingContext.ts

@@ -0,0 +1,24 @@
+import type Term from '#cli/cs/terms/Term.js';
+import type Collection from '../Collection.js';
+
+interface Result {
+	readonly idx: number;
+
+	// Intentionally returns a mutable array. Consumers are expected to mutate it
+	// to adjust sibling order.
+	readonly siblings: Term[];
+}
+
+export function getSiblingContext(this: Collection, term: Term): Result {
+	const siblings = this.byParentUid.get(term.parent_uid);
+	if (!siblings) {
+		throw new Error('Parent not found');
+	}
+
+	const idx = siblings.findIndex((s) => s.uid === term.uid);
+	if (idx === -1) {
+		throw new Error('Term not found in parent');
+	}
+
+	return { idx, siblings };
+}

package/src/schema/terms/collection/lib/insertTermIntoSiblings.ts

@@ -0,0 +1,22 @@
+import type Term from '#cli/cs/terms/Term.js';
+import type Collection from '../Collection.js';
+
+export default function insertTermIntoSiblings(
+	this: Collection,
+	term: Term,
+	idx?: number,
+) {
+	const siblings = this.byParentUid.get(term.parent_uid);
+
+	if (siblings) {
+		if (typeof idx === 'number') {
+			siblings.splice(idx, 0, term);
+		} else {
+			siblings.push(term);
+		}
+	} else {
+		this.byParentUid.set(term.parent_uid, [term]);
+	}
+
+	return typeof idx === 'number' ? idx : (siblings?.length ?? 0);
+}

package/src/schema/terms/collection/lib/move.ts

@@ -0,0 +1,50 @@
+import apiMove from '#cli/cs/terms/move.js';
+import type Term from '#cli/cs/terms/Term.js';
+import type TransferResults from '#cli/schema/xfer/TransferResults.js';
+import { MutableTransferResults } from '#cli/schema/xfer/TransferResults.js';
+import type ProgressBar from '#cli/ui/progress/ProgressBar.js';
+import ProgressReporter from '#cli/ui/progress/ProgressReporter.js';
+import type Collection from '../Collection.js';
+
+export default function move(
+	this: Collection,
+	term: Term,
+	newParentUid: string | null,
+	newIdx?: number,
+): ((bar: ProgressBar) => Promise<TransferResults>) | undefined {
+	const existing = this.getRequired(term.uid);
+	if (existing.parent_uid === newParentUid) {
+		return;
+	}
+
+	const { siblings: oldSiblings, idx: oldIdx } =
+		this.getSiblingContext(existing);
+
+	oldSiblings.splice(oldIdx, 1);
+	existing.parent_uid = newParentUid;
+	const order = this.insertTermIntoSiblings(existing, newIdx) + 1;
+
+	return async (bar) => {
+		const results = new MutableTransferResults();
+		using reporter = new ProgressReporter(bar, 'moving', term.name);
+
+		try {
+			await apiMove(
+				this.client,
+				this.taxonomy.uid,
+				term.uid,
+				newParentUid,
+				order,
+			);
+
+			results.updated.add(term.uid);
+		} catch (ex: unknown) {
+			results.errored.set(term.uid, ex);
+		} finally {
+			bar.increment();
+			reporter.finish('moved');
+		}
+
+		return results;
+	};
+}

package/src/schema/terms/collection/lib/remove.ts

@@ -0,0 +1,73 @@
+import apiRemove from '#cli/cs/terms/remove.js';
+import type Term from '#cli/cs/terms/Term.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import type TransferResults from '#cli/schema/xfer/TransferResults.js';
+import { MutableTransferResults } from '#cli/schema/xfer/TransferResults.js';
+import type ProgressBar from '#cli/ui/progress/ProgressBar.js';
+import ProgressReporter from '#cli/ui/progress/ProgressReporter.js';
+import type Collection from '../Collection.js';
+
+export default function remove(
+	this: Collection,
+	term: Term,
+): (bar: ProgressBar) => Promise<TransferResults> {
+	const existing = this.getRequired(term.uid);
+	const descendants = [...this.descendants(existing.uid)];
+	const { siblings, idx } = this.getSiblingContext(existing);
+
+	this.byUid.delete(term.uid);
+	this.byParentUid.delete(term.uid);
+	siblings.splice(idx, 1);
+
+	for (const descendant of descendants) {
+		this.byUid.delete(descendant.uid);
+		this.byParentUid.delete(descendant.uid);
+	}
+
+	return async (bar) => {
+		const results = new MutableTransferResults();
+		const strategy = getUi().options.schema.deletionStrategy;
+		const msg = humanizeKey(term, descendants);
+
+		if (strategy === 'delete') {
+			using reporter = new ProgressReporter(bar, 'deleting', msg);
+
+			try {
+				await apiRemove(this.client, this.taxonomy.uid, term.uid);
+				results.deleted.add(term.uid);
+				descendants.forEach((d) => results.deleted.add(d.uid));
+			} catch (ex: unknown) {
+				results.errored.set(term.uid, ex);
+				// Do we include descendants here as well? They didn't really error.
+			} finally {
+				bar.increment();
+				reporter.finish('deleted');
+			}
+		} else {
+			bar.increment();
+		}
+
+		if (strategy === 'warn') {
+			bar.update({ action: 'skipping', key: `deletion of ${msg}` });
+		}
+
+		if (strategy === 'ignore' || strategy === 'warn') {
+			results.unmodified.add(term.uid);
+		}
+
+		return results;
+	};
+}
+
+function humanizeKey(term: Term, descendants: readonly Term[]) {
+	const descendantCount = descendants.length;
+
+	const descendantMsg =
+		descendantCount === 0
+			? ''
+			: descendantCount === 1
+				? '1 descendant'
+				: `${descendantCount.toLocaleString()} descendants`;
+
+	return [term.name, descendantMsg].filter(Boolean).join(' and ');
+}

package/src/schema/terms/collection/lib/update.ts

@@ -0,0 +1,37 @@
+import type Term from '#cli/cs/terms/Term.js';
+import apiUpdate from '#cli/cs/terms/update.js';
+import type TransferResults from '#cli/schema/xfer/TransferResults.js';
+import { MutableTransferResults } from '#cli/schema/xfer/TransferResults.js';
+import type ProgressBar from '#cli/ui/progress/ProgressBar.js';
+import ProgressReporter from '#cli/ui/progress/ProgressReporter.js';
+import type Collection from '../Collection.js';
+
+export default function update(
+	this: Collection,
+	term: Term,
+	name: string,
+): ((bar: ProgressBar) => Promise<TransferResults>) | undefined {
+	const existing = this.getRequired(term.uid);
+	if (existing.name === name) {
+		return;
+	}
+
+	existing.name = name;
+
+	return async (bar) => {
+		const results = new MutableTransferResults();
+		using reporter = new ProgressReporter(bar, 'updating', term.uid);
+
+		try {
+			await apiUpdate(this.client, this.taxonomy.uid, term.uid, name);
+			results.updated.add(term.uid);
+		} catch (ex: unknown) {
+			results.errored.set(term.uid, ex);
+		} finally {
+			bar.increment();
+			reporter.finish('updated');
+		}
+
+		return results;
+	};
+}

package/src/schema/terms/lib/ActionType.ts

@@ -0,0 +1,2 @@
+type ActionType = 'create' | 'delete' | 'move' | 'update';
+export default ActionType;

package/src/schema/terms/lib/TermAction.ts

@@ -0,0 +1,9 @@
+import type ProgressBar from '#cli/ui/progress/ProgressBar.js';
+import type TransferResults from '../../xfer/TransferResults.js';
+import type ActionType from './ActionType.js';
+
+export default interface TermAction {
+	readonly type: ActionType;
+	readonly key: string;
+	readonly fn: (bar: ProgressBar) => Promise<TransferResults>;
+}

package/src/schema/terms/lib/deletions.ts

@@ -0,0 +1,33 @@
+import flatten from '#cli/dto/taxonomy/flatten.js';
+import type NormalizedTaxonomy from '#cli/dto/taxonomy/NormalizedTaxonomy.js';
+import type Collection from '#cli/schema/terms/collection/Collection.js';
+import type TermAction from './TermAction.js';
+
+export default function* deletions(
+	fs: NormalizedTaxonomy,
+	csTerms: Collection,
+): Generator<TermAction> {
+	const fsTermUids = new Set(flatten(fs.terms ?? []).map((x) => x.uid));
+
+	const getFirstTermForRemoval = () => {
+		// This intentionally re-start iteration from the beginning each time it
+		// is called because the act of removing a term from the collection will
+		// mutate the collection. We want to continue removing terms until there
+		// are no further mutations to make.
+		for (const csTerm of csTerms.all()) {
+			if (fsTermUids.has(csTerm.uid)) {
+				continue;
+			}
+
+			return csTerm;
+		}
+	};
+
+	let csTerm = getFirstTermForRemoval();
+	while (csTerm) {
+		// The call to csTerms.remove() is a mutation, requiring us to restart
+		// the call to csTerms.all()
+		yield { fn: csTerms.remove(csTerm), key: csTerm.uid, type: 'delete' };
+		csTerm = getFirstTermForRemoval();
+	}
+}

package/src/schema/terms/lib/filterTaxonomies.ts

@@ -0,0 +1,17 @@
+import type NormalizedTaxonomy from '#cli/dto/taxonomy/NormalizedTaxonomy.js';
+import taxonomyStrategy from '#cli/dto/taxonomy/taxonomyStrategy.js';
+
+export default function filterTaxonomies(
+	normalized: ReadonlyMap<string, NormalizedTaxonomy>,
+): ReadonlyMap<string, NormalizedTaxonomy> {
+	const withTerms = new Map<string, NormalizedTaxonomy>();
+
+	for (const [uid, taxonomy] of normalized) {
+		const strategy = taxonomyStrategy(taxonomy.taxonomy.uid);
+		if (strategy === 'taxonomy and terms') {
+			withTerms.set(uid, taxonomy);
+		}
+	}
+
+	return withTerms;
+}

package/src/schema/terms/lib/mutations.ts

@@ -0,0 +1,67 @@
+import type NormalizedTaxonomy from '#cli/dto/taxonomy/NormalizedTaxonomy.js';
+import type { TermTreeNode } from '#cli/dto/taxonomy/NormalizedTaxonomy.js';
+import type Collection from '#cli/schema/terms/collection/Collection.js';
+import deletions from './deletions.js';
+import type TermAction from './TermAction.js';
+
+type MaybeTermAction = Omit<TermAction, 'fn'> & {
+	readonly fn: TermAction['fn'] | undefined;
+};
+
+export default function mutations(
+	fs: NormalizedTaxonomy,
+	csTerms: Collection,
+): readonly TermAction[] {
+	function* traverse(
+		fsTerms: readonly TermTreeNode[],
+		parentUid: string | null,
+	): Generator<MaybeTermAction> {
+		for (let idx = 0; idx < fsTerms.length; idx += 1) {
+			const fsTerm = fsTerms[idx];
+			if (!fsTerm) {
+				throw new Error('Missing term');
+			}
+
+			const { uid: key } = fsTerm;
+
+			const existing = csTerms.get(fsTerm.uid);
+
+			if (existing) {
+				// Handle any name changes.
+				const fn = csTerms.update(existing, fsTerm.name);
+				yield { fn, key, type: 'update' };
+			}
+
+			// This intentionally re-queries the term in the index position because
+			// each iteration of the loop could potentially mutate the collection.
+			if (csTerms.children(parentUid)[idx]?.uid === key) {
+				// Early exit: there is a term in the correct position, and the
+				// UIDs match, so there is nothing further to do.
+				yield* traverse(fsTerm.children ?? [], key);
+				continue;
+			}
+
+			if (existing) {
+				// There is a term with a matching UID _somewhere_ in the hierarchy,
+				// but it isn't in the right position. It needs to be moved into place.
+				const fn = csTerms.move(existing, parentUid, idx);
+				yield { fn, key, type: 'move' };
+			} else {
+				// There is no existing term with a matching UID, so we need to create
+				// one and insert it into position.
+				const fn = csTerms.create({ ...fsTerm, parent_uid: parentUid }, idx);
+				yield { fn, key, type: 'create' };
+			}
+
+			yield* traverse(fsTerm.children ?? [], key);
+		}
+	}
+
+	const maybeActions = [
+		...deletions(fs, csTerms),
+		...traverse(fs.terms ?? [], null),
+	];
+
+	const isAction = (x: MaybeTermAction): x is TermAction => x.fn !== undefined;
+	return maybeActions.filter(isAction);
+}

package/src/schema/terms/lib/processActions.ts

@@ -0,0 +1,35 @@
+import type Term from '#cli/cs/terms/Term.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import type TransferResults from '#cli/schema/xfer/TransferResults.js';
+import {
+	merge,
+	MutableTransferResults,
+} from '#cli/schema/xfer/TransferResults.js';
+import type TermAction from './TermAction.js';
+
+export default async function processActions(
+	human: string,
+	actions: readonly TermAction[],
+	allTerms: readonly Term[],
+): Promise<TransferResults> {
+	let result = initialResults(allTerms);
+
+	if (actions.length === 0) {
+		return result;
+	}
+
+	using bar = getUi().createProgressBar(human, actions.length);
+
+	for (const action of actions) {
+		const actionResult = await action.fn(bar);
+		result = merge(result, actionResult);
+	}
+
+	return result;
+}
+
+function initialResults(allTerms: readonly Term[]): TransferResults {
+	const result = new MutableTransferResults();
+	allTerms.forEach((term) => result.unmodified.add(term.uid));
+	return result;
+}

package/src/schema/terms/toContentstack.ts

@@ -0,0 +1,28 @@
+import type Ctx from '../ctx/Ctx.js';
+import type TransferResults from '../xfer/TransferResults.js';
+import Collection from './collection/Collection.js';
+import filterTaxonomies from './lib/filterTaxonomies.js';
+import mutations from './lib/mutations.js';
+import processActions from './lib/processActions.js';
+
+export default async function* toContentstack(
+	ctx: Ctx,
+): AsyncGenerator<[string, TransferResults]> {
+	const fsWithTerms = filterTaxonomies(ctx.fs.taxonomies.byUid);
+	if (fsWithTerms.size === 0) {
+		return;
+	}
+
+	for (const [taxonomyUid, normalized] of fsWithTerms) {
+		const csTaxonomy = ctx.cs.taxonomies.byUid.get(taxonomyUid);
+		if (!csTaxonomy) {
+			throw new Error(`Taxonomy not found: ${normalized.taxonomy.name}`);
+		}
+
+		const human = `${normalized.taxonomy.name} Terms`;
+		const csTerms = new Collection(ctx.cs.client, csTaxonomy);
+		const actions = mutations(normalized, csTerms);
+		const allTerms = [...csTerms.all()];
+		yield [human, await processActions(human, actions, allTerms)];
+	}
+}

package/src/schema/xfer/Filename.ts

@@ -0,0 +1,2 @@
+const Filename = Symbol('Filename');
+export default Filename;

package/src/schema/xfer/TransferResults.ts

@@ -0,0 +1,64 @@
+export default interface TransferResults {
+	readonly created: ReadonlySet<string>;
+	readonly updated: ReadonlySet<string>;
+	readonly deleted: ReadonlySet<string>;
+	readonly unmodified: ReadonlySet<string>;
+	readonly errored: ReadonlyMap<string, unknown>;
+}
+
+export class MutableTransferResults implements TransferResults {
+	public readonly created = new Set<string>();
+	public readonly updated = new Set<string>();
+	public readonly deleted = new Set<string>();
+	public readonly unmodified = new Set<string>();
+	public readonly errored = new Map<string, unknown>();
+}
+
+export function merge(
+	a: Partial<TransferResults>,
+	b: Partial<TransferResults>,
+): TransferResults {
+	const merged = new MutableTransferResults();
+
+	function* keysIn(key: Exclude<keyof TransferResults, 'errored'>) {
+		for (const x of a[key] ?? []) {
+			yield x;
+		}
+
+		for (const x of b[key] ?? []) {
+			yield x;
+		}
+	}
+
+	for (const key of keysIn('unmodified')) {
+		merged.unmodified.add(key);
+	}
+
+	for (const key of keysIn('updated')) {
+		merged.updated.add(key);
+		merged.unmodified.delete(key);
+	}
+
+	for (const key of keysIn('created')) {
+		merged.created.add(key);
+		merged.updated.delete(key);
+		merged.unmodified.delete(key);
+	}
+
+	for (const key of keysIn('deleted')) {
+		merged.deleted.add(key);
+		merged.created.delete(key);
+		merged.updated.delete(key);
+		merged.unmodified.delete(key);
+	}
+
+	for (const [key, err] of [...(a.errored ?? []), ...(b.errored ?? [])]) {
+		merged.errored.set(key, err);
+		merged.created.delete(key);
+		merged.updated.delete(key);
+		merged.unmodified.delete(key);
+		merged.deleted.delete(key);
+	}
+
+	return merged;
+}

package/src/schema/xfer/indexFromFilesystem.ts

@@ -0,0 +1,47 @@
+import readYaml from '#cli/fs/readYaml.js';
+import tryReadDir from '#cli/fs/tryReadDir.js';
+import isRecord from '#cli/util/isRecord.js';
+import { extname, resolve } from 'node:path';
+import { styleText } from 'node:util';
+import getUi from '../lib/SchemaUi.js';
+import Filename from './Filename.js';
+
+export default async function indexFromFilesystem<
+	TItem extends Record<string, unknown>,
+>(
+	schemaPath: string,
+	typeGuard: (a: Record<string, unknown>) => a is TItem,
+	key: (a: TItem) => string,
+): Promise<ReadonlyMap<string, TItem & { [Filename]: string }>> {
+	const files = await tryReadDir(schemaPath);
+	const result = new Map<string, TItem & { [Filename]: string }>();
+	const ui = getUi();
+
+	for (const file of files) {
+		if (!file.isFile() || extname(file.name).toLowerCase() !== '.yaml') {
+			continue;
+		}
+
+		const fullPath = resolve(schemaPath, file.name);
+		const parsed = await readYaml(fullPath);
+
+		if (!isRecord(parsed) || !typeGuard(parsed)) {
+			ui.warn(
+				'Invalid serialization found:',
+				styleText('yellowBright', file.name),
+			);
+
+			continue;
+		}
+
+		if (result.has(key(parsed))) {
+			ui.warn('Duplicate key found:', styleText('yellowBright', key(parsed)));
+
+			continue;
+		}
+
+		result.set(key(parsed), { ...parsed, [Filename]: file.name });
+	}
+
+	return result;
+}

package/src/schema/xfer/lib/MergePlan.ts

@@ -0,0 +1,6 @@
+export default interface MergePlan<TItem> {
+	readonly toCreate: ReadonlyMap<string, TItem>;
+	readonly toRemove: ReadonlyMap<string, TItem>;
+	readonly toSkip: ReadonlySet<string>;
+	readonly toUpdate: ReadonlyMap<string, TItem>;
+}

package/src/schema/xfer/lib/handleCreations.ts

@@ -0,0 +1,25 @@
+import ProgressReporter from '#cli/ui/progress/ProgressReporter.js';
+import type { TransferContext } from './processPlan.js';
+
+export default async function handleCreations<TItem>(
+	ctx: TransferContext<TItem>,
+	collectError: (key: string, ex: unknown) => void,
+) {
+	const created = new Set<string>();
+
+	for (const [key, item] of ctx.plan.toCreate) {
+		using reporter = new ProgressReporter(ctx.progress, 'creating', key);
+
+		try {
+			await ctx.create(item);
+			created.add(key);
+		} catch (ex: unknown) {
+			collectError(key, ex);
+		} finally {
+			ctx.progress.increment();
+			reporter.finish('created');
+		}
+	}
+
+	return created;
+}