dsh-plugin-term-dictionary 1.0.0 → 1.1.0

package/lib/core/transfer.js

@@ -70,6 +70,9 @@ function toRecord(entry) {
 		}
 	};
 	if (typeof entry?.domain === "string" && entry.domain !== "") record.domain = entry.domain;
+	// A group travels through an export, so a backup restores the structure it was filed under; it does NOT
+	// travel in a pack, where the reader organizes entries their own way (see `pack.js`'s allowlist).
+	if (typeof entry?.group === "string" && entry.group !== "") record.group = entry.group;
 	if (Array.isArray(entry?.aliases) && entry.aliases.length > 0) record.aliases = [...entry.aliases];
 	if (entry?.pinned === true) record.pinned = true;
 	if (typeof entry?.source === "string" && entry.source !== "") record.source = entry.source;
@@ -151,6 +154,9 @@ function toEntry(raw) {
 			usage: typeof definition.usage === "string" ? definition.usage : ""
 		},
 		domain: typeof raw.domain === "string" ? raw.domain.trim() : "",
+		// A group is read back from a file like any other label the user assigned — that is what makes an
+		// export a backup of the STRUCTURE and not only of the words.
+		group: typeof raw.group === "string" ? raw.group.trim() : "",
 		aliases: Array.isArray(raw.aliases) ? raw.aliases.filter((alias) => typeof alias === "string" && alias.trim() !== "") : [],
 		pinned: raw.pinned === true
 	};
@@ -191,6 +197,64 @@ function parseImport(text) {
 	return { ok: true, entries, skipped };
 }
 
+/**
+ * The folder path a file sits in, as a group path.
+ *
+ * The picked folder's own name IS the first group: choosing a folder called `packs` is how you say "file
+ * these under `packs`", and dropping the name would put everything at the top level — which is precisely
+ * the structure the user just picked a folder to express.
+ *
+ * @param path - a `relative/path/file.json`, as `webkitRelativePath` reports it.
+ * @returns the group path.
+ */
+function folderPathOf(path) {
+	const parts = String(path)
+		.split("/")
+		.filter((part) => part !== "");
+	// Everything but the file name.
+	return parts.slice(0, -1).join("/");
+}
+
+/**
+ * Read a whole directory into one import.
+ *
+ * A folder is a mixed bag: several exported dictionaries, somebody's downloaded pack files, an
+ * `index.json` that lists packs rather than holding entries, and often a README or a screenshot. So this
+ * reports what it could NOT use instead of refusing the folder — the alternative is a user with twenty
+ * files and one bad one, told "no" with no idea which file it was. Files that are not JSON are not
+ * reported at all: they are not mistakes.
+ *
+ * @param files - `[{ path, text }]`, the directory's files as the browser hands them over.
+ * @param options - `useFolderAsGroup` files each entry under the folder it came from, which is the shape
+ *   people actually keep: one folder per topic, and the reason the option exists at all.
+ * @returns `{ entries, files, used, skipped }`, where `skipped` is `[{ name, error }]`.
+ */
+function collectFolderImport(files, options) {
+	const list = Array.isArray(files) ? files : [];
+	const entries = [];
+	const skipped = [];
+	const useFolder = options?.useFolderAsGroup === true;
+	let used = 0;
+	let jsonFiles = 0;
+	for (const file of list) {
+		const path = typeof file?.path === "string" ? file.path : "";
+		if (!/\.json$/i.test(path)) continue;
+		jsonFiles++;
+		const parsed = parseImport(typeof file?.text === "string" ? file.text : "");
+		if (parsed.ok !== true) {
+			skipped.push({ name: path, error: parsed.error });
+			continue;
+		}
+		used++;
+		const folder = useFolder ? folderPathOf(path) : "";
+		for (const entry of parsed.entries) {
+			const hasGroup = typeof entry.group === "string" && entry.group !== "";
+			entries.push(folder !== "" && !hasGroup ? { ...entry, group: folder } : entry);
+		}
+	}
+	return { entries, files: jsonFiles, used, skipped };
+}
+
 /**
  * Decide what an import would do, without doing any of it.
  *
@@ -236,10 +300,15 @@ function planImport(existing, incoming, deletedKeys, options) {
 	// Opting in does not empty the `deleted` bucket by accident: it moves those entries into
 	// `accepted`, and the bucket is then genuinely empty, so the report says "0 you deleted" and
 	// means it.
+	//
+	// `revived` names the accepted entries that were previously DELETED, separately from the ones that are
+	// simply new. The caller must not treat the two the same: a new term is a write, while a deleted term is
+	// a RESTORATION — a decision that has to beat the tombstone, not an edit that hopes to. Running both
+	// through the same write is how "a term that was collected and then deleted cannot be restored" happened.
 	const retract = options?.includeDeleted === true;
 	return retract
-		? { accepted: [...accepted, ...wasDeleted], existing: alreadyHave, deleted: [], duplicates }
-		: { accepted, existing: alreadyHave, deleted: wasDeleted, duplicates };
+		? { accepted: [...accepted, ...wasDeleted], revived: wasDeleted, existing: alreadyHave, deleted: [], duplicates }
+		: { accepted, revived: [], existing: alreadyHave, deleted: wasDeleted, duplicates };
 }
 
 /**
@@ -301,6 +370,7 @@ module.exports = {
 	buildExport,
 	buildFeedbackReport,
 	parseImport,
+	collectFolderImport,
 	planImport,
 	domainsIn,
 	toRecord,