@kentcdodds/lineage

import { deleteCommentary, listCommentaries, upsertCommentary } from './storage.ts'

/**
 * List, add, update, or delete graph commentaries stored in package storage.
 * Use after ingesting a commit that deserves a short label and longer narrative.
 *
 * @param input - Omit fields to list; pass sha/label/narrative to upsert; pass id+remove to delete
 * @returns The commentary list, or the written/removed record
 *
 * @example
 * import commentary from 'kody:@kentcdodds/lineage/commentary'
 *
 * const saved = await commentary({
 *   sha: 'abc123',
 *   label: 'Worker split',
 *   narrative: 'The monolith was carved into the first dedicated worker package.',
 * })
 */
export default async function commentary(
	input: {
		id?: string
		sha?: string
		label?: string
		narrative?: string
		remove?: boolean
	} = {},
) {
	if (input.remove && input.id) {
		const removed = await deleteCommentary(input.id)
		return { ok: true, removed, id: input.id }
	}
	if (input.sha && input.label && input.narrative) {
		const saved = await upsertCommentary({
			id: input.id,
			sha: input.sha,
			label: input.label,
			narrative: input.narrative,
		})
		return { ok: true, commentary: saved, commentaries: await listCommentaries() }
	}
	return { ok: true, commentaries: await listCommentaries() }
}