atmn 1.1.25 → 2.0.0

package/src/actions/pull/changedFixtureKeys.ts

@@ -0,0 +1,88 @@
+import type { CollectionSpec } from "../../generated/emitRuntime";
+import type { PreviewEntry } from "./applyPreview";
+
+const camelOf = (snake: string): string =>
+	snake.replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase());
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+	typeof value === "object" && value !== null && !Array.isArray(value);
+
+const NOOP_ACTIONS = new Set(["none", "skip"]);
+
+/** A nested lane (licenses, variants) is work when any row in it acts. */
+const laneHasWork = (value: unknown): boolean =>
+	Array.isArray(value) &&
+	value.some((row) =>
+		Object.entries(row as Record<string, unknown>).some(
+			([key, entry]) =>
+				key.endsWith("ction") &&
+				typeof entry === "string" &&
+				!NOOP_ACTIONS.has(entry),
+		),
+	);
+
+/**
+ * The top-level fixture keys a preview update touches, in patch order:
+ * content first, then version slug, then the id, so each lookup still finds
+ * the fixture by what the config said before. Null when the preview does not
+ * name its fields, which means the whole fixture is rewritten instead.
+ */
+export const changedFixtureKeys = ({
+	spec,
+	entry,
+	includeMappings,
+	fixtureId,
+	rowId,
+}: {
+	spec: CollectionSpec;
+	entry: PreviewEntry;
+	includeMappings: boolean;
+	/** The public id the located fixture states; null when not a literal string. */
+	fixtureId: string | null;
+	/** The id the server row carries now. */
+	rowId: unknown;
+}): string[] | null => {
+	const keys = new Set<string>();
+	const known = new Set(spec.keys);
+	const addAttribute = (attribute: string): boolean => {
+		const key = camelOf(attribute);
+		if (key === "id" || key === spec.idField || key === "internalId")
+			return true;
+		// Mappings ride include_mappings, never a diff.
+		if (key === "processors" && !includeMappings) return true;
+		if (!known.has(key)) return false;
+		keys.add(key);
+		return true;
+	};
+
+	const planChange = entry.planChange;
+	if (isObject(planChange)) {
+		const previous = planChange.previousAttributes;
+		if (isObject(previous)) {
+			for (const attribute of Object.keys(previous)) {
+				if (!addAttribute(attribute)) return null;
+			}
+		}
+		if (planChange.priceChange !== undefined) keys.add("price");
+		if (planChange.freeTrialChange !== undefined) keys.add("freeTrial");
+		if (Array.isArray(planChange.itemChanges) && planChange.itemChanges.length)
+			keys.add("items");
+		if (planChange.customize !== undefined) return null;
+	}
+	if (isObject(entry.previousAttributes)) {
+		for (const attribute of Object.keys(entry.previousAttributes)) {
+			if (!addAttribute(attribute)) return null;
+		}
+	}
+	if (laneHasWork(entry.licenses) && known.has("licenses"))
+		keys.add("licenses");
+	if (laneHasWork(entry.variants) && known.has("variants"))
+		keys.add("variants");
+
+	const ordered = [...keys].filter((key) => key !== "versionSlug");
+	if (entry.newVersionSlug !== undefined || keys.has("versionSlug"))
+		ordered.push("versionSlug");
+	if (typeof rowId === "string" && fixtureId !== null && rowId !== fixtureId)
+		ordered.push(spec.idField);
+	return ordered.length === 0 ? null : ordered;
+};

package/src/actions/pull/listSourceFiles.ts

@@ -0,0 +1,29 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Every `.ts` file under `directory`, recursively. Generated and scratch
+ * directories are skipped: a pull must never rewrite its own inputs, and a
+ * fixture literal inside `node_modules` or a `.tmp` folder is not the user's.
+ */
+export const listSourceFiles = ({
+	directory,
+}: {
+	directory: string;
+}): string[] => {
+	const files: string[] = [];
+	const walk = (dir: string): void => {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			const path = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (entry.name === "node_modules" || entry.name.startsWith("."))
+					continue;
+				walk(path);
+			} else if (entry.isFile() && entry.name.endsWith(".ts")) {
+				files.push(path);
+			}
+		}
+	};
+	walk(directory);
+	return files;
+};

package/src/actions/pull/locateFixture.ts

@@ -0,0 +1,78 @@
+import type { SgNode } from "@ast-grep/napi";
+import {
+	type FixtureConstraint,
+	type FixtureShape,
+	findFixture,
+} from "../../surgery/findFixture";
+
+/** The file, its source, the node, and the lookup that found it — reuse the
+ * same lookup for the edit, or two versions sharing an id get confused. */
+export type LocatedFixture = {
+	file: string;
+	source: string;
+	node: SgNode;
+	builder: FixtureShape;
+	idField: string;
+	id: string;
+	where?: FixtureConstraint[];
+};
+export type { FixtureConstraint };
+
+/**
+ * Where a fixture literal lives: the config file first (the common case), then
+ * every other walked source file. A stable id wins over the public one, so a
+ * renamed row is still found; `where` narrows rows that share an id, like
+ * plan versions. `files` maps absolute paths to their current source, so later
+ * edits are seen by later lookups. Several `builder` shapes are tried in order
+ * for each lookup, so a stable id in any shape beats a public id in the first.
+ */
+export const locateFixture = ({
+	configPath,
+	files,
+	builder,
+	idField,
+	id,
+	internalId,
+	where,
+	allowDynamic = false,
+}: {
+	configPath: string;
+	files: Map<string, string>;
+	builder: FixtureShape | FixtureShape[];
+	idField: string;
+	id: string;
+	internalId?: string | null;
+	where?: FixtureConstraint[];
+	allowDynamic?: boolean;
+}): LocatedFixture | null => {
+	const others = [...files.keys()].filter((file) => file !== configPath);
+	const ordered = [configPath, ...others];
+	const attempts: {
+		idField: string;
+		id: string;
+		where?: FixtureConstraint[];
+	}[] = [
+		...(typeof internalId === "string"
+			? [{ idField: "internalId", id: internalId }]
+			: []),
+		{ idField, id, where },
+	];
+	const shapes = Array.isArray(builder) ? builder : [builder];
+	for (const attempt of attempts) {
+		for (const file of ordered) {
+			const source = files.get(file);
+			if (source === undefined) continue;
+			for (const shape of shapes) {
+				const node = findFixture({
+					source,
+					builder: shape,
+					allowDynamic,
+					...attempt,
+				});
+				if (node !== null)
+					return { file, source, node, builder: shape, ...attempt };
+			}
+		}
+	}
+	return null;
+};

package/src/actions/pull/resolveCollectionTarget.ts

@@ -0,0 +1,198 @@
+import { dirname, resolve } from "node:path";
+import type { SgNode } from "@ast-grep/napi";
+import { Lang, parse } from "@ast-grep/napi";
+import { findLiteralBinding } from "../../surgery/arrayBinding";
+
+export type CollectionTarget =
+	| { kind: "inline"; file: string }
+	| { kind: "binding"; file: string; name: string };
+
+export const collectionTargetReferenceName = ({
+	target,
+	files,
+	collection,
+	name,
+	fixtureFile,
+}: {
+	target: CollectionTarget;
+	files: Map<string, string>;
+	collection: string;
+	name: string;
+	fixtureFile: string;
+}): string | null => {
+	const source = files.get(target.file);
+	if (source === undefined) return null;
+	const root = parse(Lang.TypeScript, source).root();
+	const array =
+		target.kind === "binding"
+			? findLiteralBinding({ root, name: target.name, kind: "array" })
+			: collectionValue({ root, collection });
+	if (array?.kind() !== "array") return null;
+	for (const element of array.namedChildren()) {
+		if (element.kind() !== "identifier") continue;
+		const localName = element.text();
+		const imported = importedFrom({ root, name: localName });
+		if (imported !== null) {
+			const importedFile = moduleFileOf({
+				from: target.file,
+				specifier: imported.specifier,
+				files,
+			});
+			if (importedFile === fixtureFile && imported.exportedName === name)
+				return localName;
+			continue;
+		}
+		if (target.file === fixtureFile && localName === name) return localName;
+	}
+	return null;
+};
+
+const NAMED_IMPORT =
+	/import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*["']([^"']+)["']/;
+
+/**
+ * Where a collection's array literal lives: inline in the atmn call, a const
+ * the call names, or the const behind the array's last `...spread`; a named
+ * const may be local or imported from a relative `.ts` file. Null when the
+ * value is something this pull cannot append to.
+ */
+export const resolveCollectionTarget = ({
+	configPath,
+	files,
+	collection,
+	kind = "array",
+}: {
+	configPath: string;
+	files: Map<string, string>;
+	collection: string;
+	/** What the key holds: a collection's array, or a singleton's object. */
+	kind?: "array" | "object";
+}): CollectionTarget | null => {
+	const source = files.get(configPath);
+	if (source === undefined) return null;
+	const root = parse(Lang.TypeScript, source).root();
+	const value = collectionValue({ root, collection });
+	if (value === null) return null;
+	if (value.kind() === kind) {
+		const spread = kind === "array" ? trailingSpreadName(value) : null;
+		return spread === null
+			? { kind: "inline", file: configPath }
+			: resolveBinding({ root, name: spread, configPath, files, kind });
+	}
+	// `atmn({ plans })` names the binding without a pair.
+	const named =
+		value.kind() === "identifier" ||
+		value.kind() === "shorthand_property_identifier";
+	if (!named) return null;
+	return resolveBinding({ root, name: value.text(), configPath, files, kind });
+};
+
+/** `[...a, ...b]` appends into `b`; a literal element last means inline. */
+const trailingSpreadName = (array: SgNode): string | null => {
+	const elements = array.namedChildren();
+	const last = elements[elements.length - 1];
+	if (last === undefined || last.kind() !== "spread_element") return null;
+	const argument = last.namedChildren()[0];
+	return argument?.kind() === "identifier" ? argument.text() : null;
+};
+
+const resolveBinding = ({
+	root,
+	name,
+	configPath,
+	files,
+	kind,
+}: {
+	root: SgNode;
+	name: string;
+	configPath: string;
+	files: Map<string, string>;
+	kind: "array" | "object";
+}): CollectionTarget | null => {
+	if (findLiteralBinding({ root, name, kind }) !== null)
+		return { kind: "binding", file: configPath, name };
+	const imported = importedFrom({ root, name });
+	if (imported === null) return null;
+	const file = moduleFileOf({
+		from: configPath,
+		specifier: imported.specifier,
+		files,
+	});
+	if (file === null) return null;
+	const module = parse(Lang.TypeScript, files.get(file) ?? "").root();
+	return findLiteralBinding({
+		root: module,
+		name: imported.exportedName,
+		kind,
+	}) !== null
+		? { kind: "binding", file, name: imported.exportedName }
+		: null;
+};
+
+const collectionValue = ({
+	root,
+	collection,
+}: {
+	root: SgNode;
+	collection: string;
+}): SgNode | null => {
+	const object = root.find("atmn($ARG)")?.getMatch("ARG") ?? null;
+	if (object === null || object.kind() !== "object") return null;
+	for (const member of object.children()) {
+		if (
+			member.kind() === "shorthand_property_identifier" &&
+			member.text() === collection
+		)
+			return member;
+		if (member.kind() !== "pair") continue;
+		const [key, value] = member.namedChildren();
+		if (key?.text() === collection && value !== undefined) return value;
+	}
+	return null;
+};
+
+/** The import binding `name`, with the name it had in the module it came from. */
+const importedFrom = ({
+	root,
+	name,
+}: {
+	root: SgNode;
+	name: string;
+}): { specifier: string; exportedName: string } | null => {
+	for (const statement of root.findAll({
+		rule: { kind: "import_statement" },
+	})) {
+		const match = NAMED_IMPORT.exec(statement.text());
+		if (match === null) continue;
+		for (const entry of match[1].split(",")) {
+			const [exportedName, localName = exportedName] = entry
+				.trim()
+				.split(/\s+as\s+/);
+			if (localName === name && exportedName !== "")
+				return { specifier: match[2], exportedName };
+		}
+	}
+	return null;
+};
+
+/** A relative specifier against the walked files: bare, `.ts`, or a folder index. */
+const moduleFileOf = ({
+	from,
+	specifier,
+	files,
+}: {
+	from: string;
+	specifier: string;
+	files: Map<string, string>;
+}): string | null => {
+	if (!specifier.startsWith(".")) return null;
+	const byResolved = new Map(
+		[...files.keys()].map((file) => [resolve(file), file] as const),
+	);
+	const base = resolve(dirname(from), specifier);
+	for (const candidate of [base, `${base}.ts`, `${base}/index.ts`]) {
+		const file = byResolved.get(candidate);
+		if (file !== undefined) return file;
+	}
+	return null;
+};

package/src/actions/pull/rewriteConfig.ts

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+	COLLECTION_FILES,
+	type ConfigImports,
+	collectionFileSource,
+	rootSource,
+} from "./scaffoldConfig";
+
+const PACKAGE_NAMES = ["atmn", "atmn-nightly"];
+
+/** A file is ours when it imports the config package; anything else is the user's. */
+export const importsConfigPackage = ({
+	text,
+	imports,
+}: {
+	text: string;
+	imports: ConfigImports;
+}): boolean =>
+	[imports.atmn, imports.builders, ...PACKAGE_NAMES].some(
+		(specifier) =>
+			text.includes(`from "${specifier}"`) ||
+			text.includes(`from '${specifier}'`),
+	);
+
+/**
+ * Overwrite without deleting: the config becomes a fresh shell, and each
+ * collection file beside it is rewritten only when it is ours. A collection
+ * whose file belongs to the user is kept inline in the config instead.
+ */
+export const rewriteConfig = ({
+	configPath,
+	imports,
+}: {
+	configPath: string;
+	imports: ConfigImports;
+}): { rewritten: string[]; kept: string[] } => {
+	const configDir = dirname(configPath);
+	const importedFiles = new Set<string>();
+	const rewritten: string[] = [];
+	const kept: string[] = [];
+	for (const [file, collections] of Object.entries(COLLECTION_FILES)) {
+		const path = join(configDir, file);
+		const isUsers =
+			existsSync(path) &&
+			!importsConfigPackage({ text: readFileSync(path, "utf8"), imports });
+		if (isUsers) {
+			kept.push(path);
+			continue;
+		}
+		writeFileSync(path, collectionFileSource({ collections, imports }), "utf8");
+		importedFiles.add(file);
+		rewritten.push(path);
+	}
+	writeFileSync(configPath, rootSource({ imports, importedFiles }), "utf8");
+	return { rewritten: [configPath, ...rewritten], kept };
+};

package/src/actions/pull/scaffoldConfig.ts

@@ -0,0 +1,118 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { configPackageName } from "../../config/configPackageName";
+import { COLLECTIONS } from "../../generated/emit";
+
+/** Where a config imports from: the published package, or generated files in-repo. */
+export type ConfigImports = { atmn: string; builders: string };
+
+export const packageImports = (): ConfigImports => {
+	const name = configPackageName();
+	return { atmn: name, builders: name };
+};
+
+/**
+ * One file per catalog surface. `rewards.ts` holds both reward collections:
+ * a referral program names a reward, so they read as one thing.
+ */
+export const COLLECTION_FILES: Readonly<Record<string, readonly string[]>> = {
+	"features.ts": ["features"],
+	"plans.ts": ["plans"],
+	"rewards.ts": ["rewards", "referralPrograms"],
+};
+
+const builderImportsFor = ({
+	collections,
+	specifier,
+}: {
+	collections: readonly string[];
+	specifier: string;
+}): string => {
+	const builders = collections
+		.flatMap((name) => {
+			const spec = COLLECTIONS[name];
+			if (spec === undefined) return [];
+			return spec.branches
+				? spec.branches.map((branch) => branch.builder)
+				: [spec.builder];
+		})
+		.sort();
+	return `import { ${builders.join(", ")} } from "${specifier}";`;
+};
+
+export const collectionFileSource = ({
+	collections,
+	imports,
+}: {
+	collections: readonly string[];
+	imports: ConfigImports;
+}): string =>
+	[
+		builderImportsFor({ collections, specifier: imports.builders }),
+		"",
+		...collections.map((name) => `export const ${name} = [];`),
+		"",
+	].join("\n");
+
+/** A collection whose file is not imported stays inline as an empty array. */
+export const rootSource = ({
+	imports,
+	importedFiles = new Set(Object.keys(COLLECTION_FILES)),
+}: {
+	imports: ConfigImports;
+	importedFiles?: ReadonlySet<string>;
+}): string => {
+	const collectionImports: string[] = [];
+	const collectionKeys: string[] = [];
+	for (const [file, collections] of Object.entries(COLLECTION_FILES)) {
+		if (importedFiles.has(file)) {
+			collectionImports.push(
+				`import { ${collections.join(", ")} } from "./${file.replace(/\.ts$/, "")}";`,
+			);
+			collectionKeys.push(...collections.map((name) => `\t${name},`));
+		} else {
+			collectionKeys.push(...collections.map((name) => `\t${name}: [],`));
+		}
+	}
+	return [
+		`import { atmn } from "${imports.atmn}";`,
+		...collectionImports,
+		"",
+		"/**",
+		" * Your catalog, as code. `atmn pull` fills the collection files from the",
+		" * server; `atmn push` makes the server match them.",
+		" */",
+		"export default atmn({",
+		...collectionKeys,
+		"\tsettings: {},",
+		"});",
+		"",
+	].join("\n");
+};
+
+/**
+ * The first pull's starting point: a root config that imports one empty
+ * array per collection from its own file, so the pull that follows appends
+ * the whole catalog into them.
+ */
+export const scaffoldConfig = ({
+	directory,
+	configPath = join(directory, "autumn.config.ts"),
+	imports = packageImports(),
+}: {
+	directory: string;
+	/** `-c` may name the file; the folder is created when missing. */
+	configPath?: string;
+	imports?: ConfigImports;
+}): string => {
+	mkdirSync(directory, { recursive: true });
+	writeFileSync(configPath, rootSource({ imports }), "utf8");
+	// Collection files sit beside the config, wherever `-c` put it.
+	const configDir = dirname(configPath);
+	for (const [file, collections] of Object.entries(COLLECTION_FILES)) {
+		const path = join(configDir, file);
+		if (existsSync(path)) continue;
+		writeFileSync(path, collectionFileSource({ collections, imports }), "utf8");
+	}
+	return configPath;
+};