@geekity/cms 0.3.0 → 0.4.0

package/dist/comments/records.d.ts

@@ -0,0 +1,266 @@
+import type { AdminStore, CommentRecord, PostComment } from '../admin/store.ts';
+import type { CommentChecker } from './submission.ts';
+/**
+ * Native comments as the files that hold them, and the one door into them.
+ *
+ * decision-9 makes the filesystem the source of truth for everything durable,
+ * and a comment somebody typed into this site is exactly that: nothing else
+ * holds it, and no other server can be asked for it again. So it lives under
+ * `content/_data/comments/`, one JSON file per post, which puts it in git
+ * beside the posts, hands it to an Eleventy build of the same directory, and
+ * leaves SQLite holding nothing but an index — one rebuilt from these files on
+ * every boot and deletable at rest.
+ *
+ * The two rules `federation/records.ts` follows apply here for the same
+ * reasons, and are why every writer in this module goes through
+ * {@link withFileLock}:
+ *
+ * - **The file first, the index inside the same step.** Two comments arriving
+ *   at once cannot leave the index saying something the file does not.
+ * - **The index is derived, never told.** A row is built from a file entry by
+ *   {@link commentFrom} whether it is being written for the first time or
+ *   rebuilt at boot.
+ *
+ * The entry shape is deliberately wider than a form submission. A webmention
+ * (TASK-51) is somebody else's post pointing at this one: it has a `url` and no
+ * email, it may be a like rather than a reply, and it belongs in the same file
+ * and the same thread. So every entry says its `source` and its `kind`, and
+ * nothing here assumes a person filled in a form.
+ *
+ * Three things write comments — the form under a post, the webmention endpoint
+ * and a moderator's reply on the admin screen — and they all go through
+ * {@link intakeComment}, which is the whole of what happens between a proposed
+ * comment and a comment existing: the address hashed, the approved-author rule,
+ * the {@link CommentChecker}, one verdict-to-status rule, the write, and the
+ * message to whoever was waiting to hear. What the callers keep is what is
+ * really theirs — parsing a form and its cheap defences, fetching and verifying
+ * a source, and knowing who is signed in.
+ */
+/** Where the comment files live, relative to the content directory. */
+export declare const COMMENTS_DATA_DIRECTORY = "_data/comments";
+/** The absolute path of one site's `content/_data/comments`. */
+export declare function commentsDirectory(contentDir: string): string;
+/**
+ * The absolute path of one post's comment file.
+ *
+ * Named by the post's slug, which is what a post keeps for its whole life: the
+ * editor gives an existing document the slug it already has, so the file that
+ * holds a post's comments never has to move. A slug carrying anything a
+ * filename should not is refused rather than sanitised, because two slugs that
+ * sanitised to one name would silently share a thread.
+ */
+export declare function commentsFile(contentDir: string, slug: string): string;
+/** A {@link CommentRecord} on its way in, before the store has named it. */
+export type NewComment = Omit<CommentRecord, 'id'> & {
+    /** The post it is on. */
+    slug: string;
+    /** That post's permalink, which the file records and the feeds link to. */
+    permalink: string;
+    /** Its id, when a caller has one. Minted when it does not. */
+    id?: string | undefined;
+};
+/** What every writer here needs: the files it owns, and the index over them. */
+export interface CommentRecords {
+    /** The index the files are rebuilt into. */
+    readonly admin: AdminStore;
+    /** The content directory the files live under. */
+    readonly contentDir: string;
+}
+/**
+ * One post's comments, as its file says them, oldest first.
+ *
+ * A missing file is no comments, which is what almost every post has. Unlike
+ * `followers.json`, an entry that will not parse is dropped rather than
+ * throwing: a comment file is public, in git and editable by hand, and a typo
+ * in one post's file should cost that entry rather than take the whole site
+ * down on the next boot. Nothing irreplaceable is at stake — a comment that
+ * cannot be read is one nobody could have shown either way.
+ */
+export declare function readComments(contentDir: string, slug: string): CommentRecord[];
+/**
+ * Record a comment: append it to its post's file and index it.
+ *
+ * The id is minted here unless the caller brought one, and it is a UUID rather
+ * than a counter so two comments written at once on two machines holding the
+ * same content directory can never be given the same name.
+ */
+export declare function addComment(records: CommentRecords, comment: NewComment): Promise<PostComment>;
+/** Who is proposing a comment, which is the one thing the rules differ on. */
+export type CommentOrigin = 
+/** Somebody filled in the form under a post (doc-6). */
+'form'
+/** Another page said it links here, and it was verified (doc-7). */
+ | 'webmention'
+/** A moderator answered from the admin screen. */
+ | 'moderator';
+/**
+ * A comment as its writer proposes it: everything but the three things the
+ * intake decides — its name, where it stands, and where it came from.
+ */
+export type ProposedComment = Omit<PostComment, 'id' | 'status' | 'addressHash'>;
+/**
+ * Whoever is told about a comment that has just been written.
+ *
+ * Structural rather than the notifier's own type, so this module does not have
+ * to know how a message is rendered or sent; `CommentNotifier` satisfies it.
+ */
+export interface CommentNotices {
+    /** Something is waiting for a moderator. */
+    pending(comment: PostComment): void;
+    /** A reply is on the page, so whoever it answers may want to know. */
+    replyApproved(reply: PostComment): void;
+}
+/** What {@link intakeComment} needs around a proposed comment. */
+export interface IntakeCommentOptions {
+    /** The files it is written into, and the index over them. */
+    records: CommentRecords;
+    /** Who is proposing it. */
+    origin: CommentOrigin;
+    /** The comment itself, as its writer proposes it. */
+    comment: ProposedComment;
+    /**
+     * The post, as a checker is told it.
+     *
+     * The URL is passed rather than derived because the two callers know
+     * different truths about it: a form knows the post's permalink against the
+     * site's base URL, and a webmention knows the exact target its sender named.
+     */
+    post?: {
+        title: string;
+        url: string;
+    } | undefined;
+    /** Where the address salt lives. */
+    dataDir: string;
+    /** The site's public origin. */
+    baseUrl: string;
+    /** The checker, when the site named one. */
+    checker?: CommentChecker | undefined;
+    /** Who to tell, when there is anybody to tell (TASK-55). */
+    notices?: CommentNotices | undefined;
+    /** Where the submission came from, **unhashed**. Only the checker sees it. */
+    address?: string | undefined;
+    /** The `User-Agent` it arrived with, for the checker. */
+    userAgent?: string | undefined;
+    /** The `Referer` it arrived with, for the checker. */
+    referrer?: string | undefined;
+    /** Where a checker that will not answer is reported. Defaults to `console`. */
+    logger?: {
+        warn(message: string): void;
+    } | undefined;
+}
+/** What became of one proposed comment. */
+export type CommentIntakeOutcome = 
+/**
+ * It is in the file. `created` says whether it is new: a page re-sending its
+ * webmention rewrites the entry it already made, which is not news.
+ */
+{
+    readonly kind: 'stored';
+    readonly comment: PostComment;
+    readonly created: boolean;
+}
+/**
+ * Nothing was stored, because a checker said to throw it away. `removed`
+ * says whether it took a webmention this site was already holding with it.
+ */
+ | {
+    readonly kind: 'discarded';
+    readonly removed: boolean;
+}
+/** The entry it was going to rewrite went while this was deciding. */
+ | {
+    readonly kind: 'gone';
+};
+/**
+ * The one door into `content/_data/comments/`.
+ *
+ * Everything between a proposed comment and a comment existing happens here,
+ * so the form, the webmention endpoint and the admin screen cannot drift into
+ * three different answers to the same four questions.
+ *
+ * **Where the site would put it, before anybody judged it.** A form comment
+ * whose name and email together have been approved before is approved again —
+ * WordPress's rule, and the whole of the auto-approval decision. A webmention
+ * waits, because a page linking here is as much a stranger's words as a form
+ * submission is. A moderator's reply is approved, because the person writing it
+ * is the person who would have approved it.
+ *
+ * **What the checker says.** Everything but a moderator's own words goes
+ * through {@link CommentChecker}; a checker that is down or throws is no
+ * opinion, so a service having a bad afternoon never stops a site taking
+ * comments. A moderator's reply is not offered to it at all: a spam service has
+ * no say in what the owner of the site says.
+ *
+ * **The one verdict-to-status rule.**
+ *
+ * | Verdict   | A new comment                        | A webmention sent again              |
+ * | --------- | ------------------------------------ | ------------------------------------ |
+ * | `discard` | Nothing is stored.                   | The held entry is deleted.           |
+ * | `spam`    | Filed as spam.                       | Filed as spam.                       |
+ * | `ham`     | Approved.                            | The moderator's decision stands.     |
+ * | `unknown` | Where the site would have put it.    | The moderator's decision stands.     |
+ *
+ * A source re-sending its webmention must not take an approved mention back
+ * into the queue, and must not quietly let a spam one out. A checker that has
+ * changed its mind to `spam` is the one thing that moves it, because that is a
+ * new fact about the content rather than a repeat of an old one.
+ *
+ * **Who hears about it.** A new entry that is waiting sends the moderation
+ * notice, once. A webmention that was merely rewritten sends nothing — the
+ * moderators heard the first time and it has been in the queue ever since —
+ * and neither does one that was approved or filed as spam, because neither is
+ * waiting for anybody. A new comment that is approved instead tells whoever it
+ * answers, when they asked to be told.
+ */
+export declare function intakeComment(options: IntakeCommentOptions): Promise<CommentIntakeOutcome>;
+/**
+ * The webmention this site already holds from that page, if any.
+ *
+ * The source URL is a webmention's identity (doc-7), so this is what stops a
+ * blog post that is edited and re-sent adding a second entry — and what the
+ * endpoint asks before it fetches, so a source that has stopped linking here
+ * knows what to take away.
+ */
+export declare function heldWebmention(records: CommentRecords, slug: string, source: string | null): PostComment | undefined;
+/**
+ * Move a stored comment: approve it, mark it spam, put it back, or rewrite
+ * what it says.
+ *
+ * The rewrite is what a webmention needs (TASK-51): a page that links here and
+ * is then edited sends its webmention again, and what this site shows should
+ * be what that page says now rather than what it said last month. Its id, the
+ * post it is on and the source it came from never move, which is what makes it
+ * the same comment.
+ *
+ * Returns the comment as it now stands, or `undefined` when the index has no
+ * such comment. The index is what says which post's file to open, which is the
+ * one thing an id alone does not carry.
+ */
+export declare function updateComment(records: CommentRecords, id: string, change: Partial<Pick<CommentRecord, 'status' | 'content' | 'author' | 'kind' | 'submitted'>>): Promise<PostComment | undefined>;
+/**
+ * Forget a comment altogether.
+ *
+ * Returns whether there was anything to forget. The index is emptied of the id
+ * whether or not the file held it, so a row left over from a file somebody
+ * edited by hand cannot go on being shown.
+ */
+export declare function deleteComment(records: CommentRecords, id: string): Promise<boolean>;
+/** What a rebuild put in the index. */
+export interface CommentIndexReport {
+    /** How many comments the files held. */
+    comments: number;
+}
+/**
+ * Rebuild the comment index from the files.
+ *
+ * This is what makes `data/geekity.db` disposable for comments (decision-9):
+ * the table holds nothing but what these files say, so every boot throws away
+ * what it holds and reads them again. Editing a comment file by hand and
+ * restarting is therefore a supported thing to do, and a database deleted at
+ * rest costs a site nothing.
+ *
+ * Exported so `geekity rebuild` can call the very function boot calls, and
+ * synchronous because both callers are.
+ */
+export declare function rebuildCommentIndexes(records: CommentRecords): CommentIndexReport;
+//# sourceMappingURL=records.d.ts.map

package/dist/comments/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/comments/records.ts"],"names":[],"mappings":"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"}