@amityco/social-plus-vise 0.8.1 → 0.12.2

package/dist/capabilities.js

@@ -0,0 +1,447 @@
+/**
+ * Feature-completeness assessment — ADVISORY ONLY.
+ *
+ * Boundary (see the validation-boundaries principle): completeness is a "this is
+ * missing" claim — a universal-negative over open-ended correct implementations.
+ * It is structurally false-positive-prone and therefore NEVER a hard gate. This
+ * module only surfaces nudges; `vise check`'s status/exit code are untouched.
+ *
+ * Memory-independence comes from inversion: VISE authors the canonical capability
+ * set per outcome; the agent must OPT OUT of a capability with a recorded reason
+ * (`// vise: scope-omit <id> <reason>`), which `check` reads and reports. The
+ * agent subtracts with justification — it doesn't have to remember the set.
+ *
+ * Gate-eligibility (not used here — these stay advisory): a capability could only
+ * ever graduate to a gate if it has a named SDK-call anchor AND a no-fire fixture.
+ * Every capability below is anchored on SDK symbols for exactly that reason, but
+ * the output is advisory regardless.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+// Canonical, Vise-authored capability set — the SDK feature surface (grounded in
+// rules/*.yaml + SKILL.md, not guessed). Anchored on SDK symbol names (consistent
+// enough across TS/Flutter/Android/iOS to match cross-platform). All advisory.
+export const CAPABILITIES = [
+    // ── add-feed: post dataTypes (a feed parent is usually 'text'; rich content
+    //    rides on child posts — render each type the feed can return) ──────────
+    {
+        id: "post-image",
+        label: "Image posts",
+        outcomes: ["add-feed"],
+        symbols: [/\bgetImageInfo\b/, /AmityImage/i, /['"]image['"]/, /childrenPosts/i, /getChildren/i],
+        hint: "resolve image posts via getImageInfo from the parent or a child post (parent is usually dataType 'text')",
+    },
+    {
+        id: "post-video",
+        label: "Video posts",
+        outcomes: ["add-feed"],
+        // Native idioms differ from TS: Android matches a sealed-class case
+        // `AmityPost.Data.VIDEO`, Flutter an enum `AmityDataType.VIDEO`, both expose
+        // getVideo()/videoData. Without these the catalog false-reports video as missing
+        // on Kotlin/Dart even when the agent handles it (found on Netflix native builds).
+        symbols: [/\bgetVideo\w*/, /AmityVideo/i, /['"]video['"]/, /Data(?:Type)?\.VIDEO\b/, /\bvideoData\b/],
+        hint: "resolve video posts via getVideo / the VIDEO dataType from the parent or a child post",
+    },
+    {
+        id: "post-file",
+        label: "File posts",
+        outcomes: ["add-feed"],
+        symbols: [/\bgetFileInfo\b/, /AmityFile(?:Info|Data)?/i, /['"]file['"]/],
+        hint: "render file posts (getFileInfo); upload via AmityFileRepository to get a fileId, never an external URL",
+    },
+    {
+        id: "post-poll",
+        label: "Poll posts",
+        outcomes: ["add-feed"],
+        symbols: [/\bgetPollInfo\b/, /\bvotePoll\b/, /\bunvotePoll\b/, /AmityPoll/i, /PollRepository/i],
+        hint: "resolve polls via getPollInfo; read answer.text + answer.image, support votePoll/unvotePoll, show closedAt",
+    },
+    {
+        id: "post-livestream",
+        label: "Livestream / room posts",
+        outcomes: ["add-feed"],
+        symbols: [/livestream/i, /liveStream/, /getLiveStream/i, /AmityStream/i, /['"](?:liveStream|room)['"]/, /getRoomInfo/i],
+        hint: "render livestream/room posts by title/status — never the raw roomId",
+    },
+    {
+        id: "post-custom",
+        label: "Custom post types",
+        outcomes: ["add-feed"],
+        symbols: [/dataType\s*[:=]\s*['"]custom/i, /['"]custom\.[\w-]+['"]/, /customDataType/i],
+        hint: "render custom-dataType posts (declare dataType on create so the SDK routes them, not a JSON blob)",
+    },
+    {
+        id: "mentions",
+        label: "@mention rendering",
+        outcomes: ["add-feed", "add-comments", "add-chat"],
+        symbols: [/\bmentionees\b/, /\bmentionedUsers\b/, /metadata.*mention/i, /['"]mention['"]/],
+        hint: "wrap @mention spans from metadata offsets and resolve userId→name; pass mentionees on create to notify",
+    },
+    // ── add-feed: broader social.plus content surfaces (advisory — opt out if a
+    //    plain post feed; these are distinct social.plus features) ─────────────
+    {
+        id: "story",
+        label: "Stories (ephemeral image/video)",
+        outcomes: ["add-feed"],
+        symbols: [/AmityStoryRepository/i, /createImageStory/i, /createVideoStory/i, /getActiveStories/i, /AmityStoryTarget/i, /\bAmityStory\b/],
+        hint: "stories via AmityStoryRepository (createImageStory/createVideoStory) — render the story tray, support reactions/comments, and mark stories seen for impression analytics",
+    },
+    {
+        id: "event",
+        label: "Community events",
+        outcomes: ["add-feed"],
+        symbols: [/AmityEventRepository/i, /\bgetEvents\b/, /\bcreateEvent\b/, /AmityEvent(?:Type|Status|QueryBuilder)?\b/],
+        hint: "community events via AmityEventRepository (getEvents/createEvent) — render an events list/detail",
+    },
+    {
+        id: "livestream-broadcast",
+        label: "Livestream rooms / broadcasting",
+        outcomes: ["add-feed"],
+        symbols: [/AmityRoomRepository/i, /\bcreateRoom\b/, /createRoomAndStartStreaming/i, /getBroadcastData/i, /createLiveStreamPost/i, /\bgoLive\b/i, /startPublish/i],
+        hint: "live rooms/broadcasting via AmityRoomRepository (createRoom, go-live, live-viewing); post the stream with createLiveStreamPost (distinct from rendering a livestream post in the feed)",
+    },
+    // ── add-feed: engagement surfaces ─────────────────────────────────────────
+    {
+        id: "comments",
+        label: "Comment thread (list + composer)",
+        outcomes: ["add-feed"],
+        symbols: [/\bgetComments\b/, /\bcreateComment\b/, /CommentRepository/i],
+        hint: "pair getComments (list) with createComment (composer), gated by the user's ban state",
+    },
+    {
+        id: "reactions",
+        label: "Reactions",
+        outcomes: ["add-feed", "add-comments"],
+        symbols: [/\baddReaction\b/, /\bremoveReaction\b/, /ReactionRepository/i, /\bmyReactions\b/],
+        hint: "addReaction/removeReaction with a tenant-configured reaction name (not a hardcoded literal)",
+    },
+    {
+        id: "pagination",
+        label: "Pagination / load-more",
+        outcomes: ["add-feed", "add-comments", "add-chat"],
+        symbols: [/\bloadMore\b/, /\bonNextPage\b/, /\bnextPage\b/, /\bhasNextPage\b/, /\bloadNext\b/],
+        hint: "drive the collection's loadMore/nextPage (opaque cursors); never numeric page math",
+    },
+    {
+        id: "composer",
+        label: "Post composer (create)",
+        outcomes: ["add-feed"],
+        symbols: [/\bcreatePost\b/, /PostRepository[\s\S]{0,20}create/i],
+        hint: "createPost with a dynamic targetType (not a hardcoded literal)",
+    },
+    {
+        id: "pinned-posts",
+        label: "Pinned / announcement posts",
+        outcomes: ["add-feed"],
+        symbols: [/getPinnedPosts/i, /AmityPinnedPost/i, /\bpinnedPost/i, /\bpinPost\b/i, /\bisPinned\b/i, /AmityPinPlacement/i],
+        hint: "surface pinned/announcement posts (getPinnedPosts) above the feed",
+    },
+    {
+        id: "post-impressions",
+        label: "Post impressions / reach analytics",
+        outcomes: ["add-feed"],
+        symbols: [/markAsViewed/i, /markPostAsViewed/i, /\bimpression/i, /\breach\b/i, /AmityViewedType/i],
+        hint: "mark posts viewed (markAsViewed) so reach/impression analytics are recorded",
+    },
+    {
+        id: "moderation",
+        label: "Moderation affordance (report/flag)",
+        outcomes: ["add-feed", "add-comments", "add-chat"],
+        symbols: [/\bflagPost\b/, /\bflagComment\b/, /\bflagMessage\b/, /\.report\(\)/, /\bflaggedByMe\b/, /\bisFlagged/i],
+        hint: "show report/flag for non-authors; gate moderator-only actions by role",
+    },
+    // ── add-comments: depth ───────────────────────────────────────────────────
+    {
+        id: "comment-composer",
+        label: "Comment composer (write)",
+        outcomes: ["add-comments"],
+        symbols: [/\bcreateComment\b/],
+        hint: "a comment surface needs a composer (createComment), not just a read-only list",
+    },
+    {
+        id: "replies",
+        label: "Comment replies (threads)",
+        outcomes: ["add-comments"],
+        symbols: [/parentId/i, /\bchildrenNumber\b/],
+        hint: "render replies via getComments({ parentId }) when childrenNumber > 0",
+    },
+    {
+        id: "comment-edit-delete",
+        label: "Comment edit / delete (author)",
+        outcomes: ["add-comments"],
+        symbols: [/\bupdateComment\b/, /\beditComment\b/, /\bdeleteComment\b/],
+        hint: "show edit (updateComment) / delete (deleteComment) for the author of a comment",
+    },
+    {
+        id: "comment-moderation",
+        label: "Comment moderation (flag)",
+        outcomes: ["add-comments"],
+        symbols: [/\bflagComment\b/, /\.report\(\)/, /\bflaggedByMe\b/],
+        hint: "show flag/report on comments for non-authors",
+    },
+    // ── add-chat: depth ───────────────────────────────────────────────────────
+    {
+        id: "send-message",
+        label: "Send message",
+        outcomes: ["add-chat"],
+        symbols: [/\bcreateMessage\b/, /\bsendMessage\b/, /MessageRepository/i],
+        hint: "createMessage; observe each message's syncState for failed sends",
+    },
+    {
+        id: "message-types",
+        label: "Message types (image / video / file / custom)",
+        outcomes: ["add-chat"],
+        symbols: [/createImageMessage/i, /createVideoMessage/i, /createFileMessage/i, /createCustomMessage/i, /messageType/i, /AmityMessageType/i],
+        hint: "support non-text message types (image/video/file/custom), not just text",
+    },
+    {
+        id: "message-sync-state",
+        label: "Message delivery state",
+        outcomes: ["add-chat"],
+        symbols: [/\bsyncState\b/, /\bdeleteFailedMessages\b/],
+        hint: "surface failed (error) syncState with a retry/delete affordance",
+    },
+    {
+        id: "message-edit-delete",
+        label: "Message edit / delete (author)",
+        outcomes: ["add-chat"],
+        symbols: [/\bupdateMessage\b/, /\beditMessage\b/, /\bdeleteMessage\b/, /\bsoftDeleteMessage\b/],
+        hint: "let the author edit (updateMessage) and delete (softDeleteMessage) their messages",
+    },
+    {
+        id: "read-state",
+        label: "Read state / unread count",
+        outcomes: ["add-chat"],
+        symbols: [/\bmarkRead\b/, /\bmarkAsRead\b/, /startMessageReceiptSync/i, /\bunreadCount\b/],
+        hint: "mark channel/messages read so the server's unread count decrements",
+    },
+    {
+        id: "typing-indicator",
+        label: "Typing indicator",
+        outcomes: ["add-chat"],
+        symbols: [/startTyping/i, /stopTyping/i, /\bisTyping\b/, /typingPreview/i],
+        hint: "start/stop typing and render others' typing state",
+    },
+    {
+        id: "channel-members",
+        label: "Channel membership",
+        outcomes: ["add-chat"],
+        symbols: [/getMembers/i, /ChannelMember/i, /\bmembership\b/i, /\bgetChannelMembers\b/i],
+        hint: "list/observe channel members; handle join/leave",
+    },
+    // ── add-community ─────────────────────────────────────────────────────────
+    {
+        id: "community-create",
+        label: "Create community",
+        outcomes: ["add-community"],
+        symbols: [/\bcreateCommunity\b/, /AmityCommunityRepository[\s\S]{0,20}create/i, /AmityCommunityCreateOptions/i],
+        hint: "create communities via AmityCommunityRepository (createCommunity) with a chosen privacy model",
+    },
+    {
+        id: "community-join-leave",
+        label: "Join / leave community",
+        outcomes: ["add-community"],
+        symbols: [/\bjoinCommunity\b/, /\bleaveCommunity\b/, /AmityCommunityRepository/i],
+        hint: "joinCommunity/leaveCommunity for public communities",
+    },
+    {
+        id: "community-join-requests",
+        label: "Join requests (private communities)",
+        outcomes: ["add-community"],
+        symbols: [/\bjoinRequest/i, /AmityJoinRequest/i, /joinRequestStatus/i],
+        hint: "private communities use the join-request approval flow (AmityJoinRequest) — handle pending/approve/decline",
+    },
+    {
+        id: "community-members",
+        label: "Member list",
+        outcomes: ["add-community"],
+        symbols: [/\bgetMembers\b/, /AmityCommunityMembership/i, /AmityCommunityMembershipFilter/i],
+        hint: "list/observe members via getMembers (a Live Collection), with membership filters",
+    },
+    {
+        id: "community-roles",
+        label: "Member roles / moderation",
+        outcomes: ["add-community"],
+        symbols: [/\baddRole/i, /\bremoveRole/i, /\bbanMember\b/i, /\bremoveMember\b/i, /\.roles?\b/],
+        hint: "manage moderator roles / ban-remove members, gated by a role check",
+    },
+    {
+        id: "community-invitation",
+        label: "Invitations",
+        outcomes: ["add-community"],
+        symbols: [/createInvitation/i, /AmityInvitation/i, /AmityMembershipAcceptanceType/i],
+        hint: "invite members via createInvitation; handle accept/decline (AmityInvitationStatus)",
+    },
+    {
+        id: "community-categories",
+        label: "Categories",
+        outcomes: ["add-community"],
+        symbols: [/AmityCommunityCategory/i, /getCategories/i, /categoryIds?/i],
+        hint: "organize communities by category (AmityCommunityCategory)",
+    },
+    // ── add-moderation: depth ─────────────────────────────────────────────────
+    {
+        id: "report-flow",
+        label: "Report / flag flow",
+        outcomes: ["add-moderation"],
+        symbols: [/\bflagPost\b/, /\bflagComment\b/, /\bflagMessage\b/, /\.report\(\)/, /\bunflag\b/],
+        hint: "flag/unflag with a confirmation affordance",
+    },
+    {
+        id: "ban-mute",
+        label: "Ban / mute members",
+        outcomes: ["add-moderation"],
+        symbols: [/\bbanUser\b/, /\bunbanUser\b/, /\bmuteChannel\b/, /\bmuteMember\b/, /\bglobalBan\b/i],
+        hint: "ban/unban or mute members (gated by moderator role)",
+    },
+    {
+        id: "review-queue",
+        label: "Post review queue (ADMIN_REVIEW)",
+        outcomes: ["add-moderation"],
+        symbols: [/\bapprovePost\b/, /\bdeclinePost\b/, /reviewing/i, /REVIEW_COMMUNITY_POST/i],
+        hint: "for a moderator surface with review enabled, query feedType 'reviewing' and wire approve/decline (gated on REVIEW_COMMUNITY_POST)",
+    },
+    {
+        id: "hidden-content",
+        label: "Hidden / flagged content rendering",
+        outcomes: ["add-moderation"],
+        symbols: [/isDeleted/i, /\bisFlagged/i, /hasFlaggedComment/i, /blockedContent/i, /\bhidden\b/i],
+        hint: "render a placeholder for deleted/flagged content rather than hiding it silently",
+    },
+    // ── add-follow (social graph) ─────────────────────────────────────────────
+    {
+        id: "follow-unfollow",
+        label: "Follow / unfollow",
+        outcomes: ["add-follow"],
+        symbols: [/\bfollow\b/i, /\bunfollow\b/i, /AmityUserRepository/i],
+        hint: "follow/unfollow via AmityUserRepository; reflect the live follow state on the button",
+    },
+    {
+        id: "followers-following",
+        label: "Follower / following lists",
+        outcomes: ["add-follow"],
+        symbols: [/getFollowers/i, /getFollowings/i, /getFollowerList/i, /followRelationship/i],
+        hint: "list/observe followers and following as a Live Collection (getFollowers/getFollowings)",
+    },
+    {
+        id: "follow-status",
+        label: "Follow-request status",
+        outcomes: ["add-follow"],
+        symbols: [/AmityFollowStatusFilter/i, /followStatus/i, /\bpending\b/i, /acceptFollow/i, /declineFollow/i],
+        hint: "handle the follow-request pending/accept/decline flow when following is not automatic",
+    },
+    {
+        id: "block-unblock",
+        label: "Block / unblock user",
+        outcomes: ["add-follow"],
+        symbols: [/\bblockUser\b/i, /\bunblockUser\b/i, /\bunBlockUser\b/i],
+        hint: "block/unblock a user (blockUser/unblockUser)",
+    },
+    {
+        id: "blocked-users",
+        label: "Blocked-users list",
+        outcomes: ["add-follow"],
+        symbols: [/getBlockedUsers/i, /blockedUsers/i],
+        hint: "surface a managed blocked-users list (getBlockedUsers)",
+    },
+    // ── add-notifications (in-app tray) ───────────────────────────────────────
+    {
+        id: "notification-tray",
+        label: "Notification tray / inbox",
+        outcomes: ["add-notifications"],
+        symbols: [/notificationTray/i, /getNotificationTraySeen/i, /NotificationTrayManager/i, /NotificationTray/],
+        hint: "observe the notification tray (getNotificationTraySeen / tray Live Object) and render the inbox",
+    },
+    {
+        id: "notification-seen",
+        label: "Mark tray seen (unseen badge)",
+        outcomes: ["add-notifications"],
+        symbols: [/markAsSeen/i, /\bmarkSeen\b/i, /\bisSeen\b/i, /unseenCount/i],
+        hint: "mark the tray/items seen (markAsSeen) so the unseen badge clears server-side",
+    },
+    {
+        id: "notification-settings",
+        label: "Notification settings / preferences",
+        outcomes: ["add-notifications"],
+        symbols: [/getSettings/i, /notificationSettings?/i, /notificationPreference/i, /notifications\(\)/],
+        hint: "respect Amity's server-side notification settings/preferences (getSettings)",
+    },
+];
+const ADVISORY_NOTE = "Advisory completeness — NEVER fails `vise check`. Build each missing capability, or opt out with a recorded reason: `// vise: scope-omit <id> <reason>`.";
+/** The Vise-authored capability checklist for an outcome (for `vise plan` feed-forward). */
+export function capabilityChecklist(outcome) {
+    return CAPABILITIES.filter((c) => c.outcomes.includes(outcome)).map((c) => ({ id: c.id, label: c.label, hint: c.hint }));
+}
+/** Pure assessment over already-read source text. */
+export function assessCompleteness(source, outcome) {
+    const caps = CAPABILITIES.filter((c) => c.outcomes.includes(outcome));
+    const optOuts = new Map();
+    const omitPattern = /vise:\s*scope-omit\s+([a-z][\w-]*)\s*(?:[—:|-]+\s*(.*))?/gi;
+    let match;
+    while ((match = omitPattern.exec(source)) !== null) {
+        optOuts.set(match[1].toLowerCase(), (match[2] ?? "").trim() || "no reason given");
+    }
+    const present = [];
+    const missing = [];
+    const optedOut = [];
+    for (const cap of caps) {
+        if (optOuts.has(cap.id)) {
+            optedOut.push({ id: cap.id, reason: optOuts.get(cap.id) });
+        }
+        else if (cap.symbols.some((symbol) => symbol.test(source))) {
+            present.push({ id: cap.id, label: cap.label });
+        }
+        else {
+            missing.push({ id: cap.id, label: cap.label, hint: cap.hint });
+        }
+    }
+    return { outcome, present, missing, optedOut, note: ADVISORY_NOTE };
+}
+// ── Bounded source read (advisory; perf-bounded like the design check scan) ──
+const SCAN_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".dart", ".kt", ".java", ".swift", ".vue"]);
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "out", "coverage", "vendor", ".dart_tool", "pods", "macos", "windows", "linux"]);
+const MAX_FILES = 1500;
+const MAX_FILE_BYTES = 1_000_000;
+export async function assessProjectCompleteness(root, outcome) {
+    if (CAPABILITIES.every((c) => !c.outcomes.includes(outcome))) {
+        return null; // outcome has no completeness checklist
+    }
+    const resolved = path.resolve(root);
+    const parts = [];
+    const stack = [resolved];
+    let count = 0;
+    while (stack.length > 0 && count < MAX_FILES) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (count >= MAX_FILES) {
+                break;
+            }
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".") && entry.name !== "sp-vise") {
+                    stack.push(full);
+                }
+            }
+            else if (entry.isFile() && SCAN_EXTS.has(path.extname(entry.name).toLowerCase())) {
+                count += 1;
+                try {
+                    const info = await stat(full);
+                    if (info.size <= MAX_FILE_BYTES) {
+                        parts.push(await readFile(full, "utf8"));
+                    }
+                }
+                catch {
+                    // skip unreadable
+                }
+            }
+        }
+    }
+    return assessCompleteness(parts.join("\n"), outcome);
+}