@dungarees/bin-audit-comments-domain 0.11.6

package/behavior.d.ts

@@ -0,0 +1,16 @@
+import type { AuditCommentsEvent } from './events.ts';
+import type { CliCommands } from '@dungarees/cli-command/service.ts';
+import { type Observable } from 'rxjs';
+export type AuditCommentsFeatureOutput = {
+    events$: Observable<AuditCommentsEvent>;
+};
+export type AuditCommentsBehavior = {
+    audit: (args: {
+        ref: string;
+        dir: string;
+    }) => AuditCommentsFeatureOutput;
+};
+export type CreateAuditCommentsBehaviorOptions = {
+    cliCommands: CliCommands;
+};
+export declare const createAuditCommentsBehavior: ({ cliCommands: { git }, }: CreateAuditCommentsBehaviorOptions) => AuditCommentsBehavior;

package/behavior.js

@@ -0,0 +1,14 @@
+import { getAddedComments, getAuditStartEvent, reportAddedComments } from './operations.js';
+import { concat } from 'rxjs';
+export const createAuditCommentsBehavior = ({ cliCommands: { git }, }) => {
+    const audit = ({ ref, dir }) => {
+        const startEvent$ = getAuditStartEvent({ ref });
+        const audit$ = getAddedComments({
+            getDiff: () => git.diff({ ref, cwd: dir }).output$,
+        }).pipe(reportAddedComments());
+        return {
+            events$: concat(startEvent$, audit$),
+        };
+    };
+    return { audit };
+};

package/events.d.ts

@@ -0,0 +1,20 @@
+import { type DomainEventOf } from '@dungarees/core/event.ts';
+export type AddedComment = {
+    file: string;
+    line: number;
+    comment: string;
+    context: string[];
+};
+type AuditCommentsEventPayloads = {
+    'comment-audit-start': {
+        ref: string;
+    };
+    'comment-added': AddedComment;
+    'no-comments-added': undefined;
+    'comments-need-review': {
+        count: number;
+    };
+};
+export type AuditCommentsEvent = DomainEventOf<AuditCommentsEventPayloads>;
+export declare const eventCreators: any;
+export {};

package/events.js

@@ -0,0 +1,2 @@
+import { createEventCreators } from '@dungarees/core/event.ts';
+export const eventCreators = createEventCreators();

package/judged-files.d.ts

@@ -0,0 +1 @@
+export declare const isJudgedFile: (file: string) => boolean;

package/judged-files.js

@@ -0,0 +1,4 @@
+// Only languages whose comments this can recognise without guessing: a `//` in markdown or YAML is
+// prose or a value, not a comment.
+const JUDGED_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+export const isJudgedFile = (file) => JUDGED_EXTENSIONS.some((extension) => file.endsWith(extension));

package/operations.d.ts

@@ -0,0 +1,12 @@
+import { type AddedComment, type AuditCommentsEvent } from './events.ts';
+import { type Observable, type OperatorFunction } from 'rxjs';
+export declare const parseAddedComments: (diff: string) => AddedComment[];
+export declare const reportAddedComments: () => OperatorFunction<AddedComment[], AuditCommentsEvent>;
+export declare const getAuditStartEvent: ({ ref }: {
+    ref: string;
+}) => Observable<AuditCommentsEvent>;
+export declare const getAddedComments: ({ getDiff, }: {
+    getDiff: () => Observable<{
+        stdout: string;
+    }>;
+}) => Observable<AddedComment[]>;

package/operations.js

@@ -0,0 +1,72 @@
+import { eventCreators } from './events.js';
+import { isJudgedFile } from './judged-files.js';
+import { concat, from, of } from 'rxjs';
+import { map, mergeMap } from 'rxjs/operators';
+const isComment = (line) => /^(\/\/|\/\*|\*)/.test(line.trim());
+const CONTEXT_LINES = 2;
+const FILE_HEADER = /^\+\+\+ b\/(.*)$/;
+const HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+// A removal is absent from the new file and a header occupies no line of it, so only these two
+// advance the line number.
+const isNewFileLine = (raw) => raw.startsWith('+') || raw.startsWith(' ');
+// A unified diff carries the new-file line number only in its hunk headers, so the numbers have to
+// be counted forward from there.
+const scanDiffLine = (scan, raw) => {
+    const file = FILE_HEADER.exec(raw)?.[1];
+    if (file !== undefined) {
+        return { ...scan, file };
+    }
+    const hunkStart = HUNK_HEADER.exec(raw)?.[1];
+    if (hunkStart !== undefined) {
+        return { ...scan, line: Number(hunkStart) };
+    }
+    if (!isNewFileLine(raw)) {
+        return scan;
+    }
+    return {
+        ...scan,
+        line: scan.line + 1,
+        lines: [
+            ...scan.lines,
+            { file: scan.file, line: scan.line, text: raw.slice(1), added: raw.startsWith('+') },
+        ],
+    };
+};
+const toDiffLines = (diff) => diff.split('\n').reduce(scanDiffLine, { file: '', line: 0, lines: [] }).lines;
+const continuesBlock = (entry, first) => entry !== undefined && entry.file === first.file && entry.added && isComment(entry.text);
+const isBlockStart = (lines, index, first) => !continuesBlock(lines[index - 1], first);
+const takeBlock = (lines, index, first) => {
+    const fromBlockStart = lines.slice(index);
+    const end = fromBlockStart.findIndex((entry) => !continuesBlock(entry, first));
+    return end === -1 ? fromBlockStart : fromBlockStart.slice(0, end);
+};
+const getContext = (lines, first) => lines
+    .filter((next) => next.file === first.file)
+    .filter((next) => next.text.trim() !== '' && !isComment(next.text))
+    .slice(0, CONTEXT_LINES)
+    .map((next) => next.text.trim());
+export const parseAddedComments = (diff) => {
+    const lines = toDiffLines(diff);
+    return lines.flatMap((entry, index) => {
+        if (!entry.added || !isJudgedFile(entry.file) || !isComment(entry.text)) {
+            return [];
+        }
+        if (!isBlockStart(lines, index, entry)) {
+            return [];
+        }
+        const block = takeBlock(lines, index, entry);
+        return [
+            {
+                file: entry.file,
+                line: entry.line,
+                comment: block.map(({ text }) => text.trim()).join('\n'),
+                context: getContext(lines.slice(index + block.length), entry),
+            },
+        ];
+    });
+};
+export const reportAddedComments = () => mergeMap((comments) => comments.length === 0
+    ? of(eventCreators.noCommentsAdded())
+    : concat(from(comments).pipe(map((comment) => eventCreators.commentAdded(comment))), of(eventCreators.commentsNeedReview({ count: comments.length }))));
+export const getAuditStartEvent = ({ ref }) => of(eventCreators.commentAuditStart({ ref }));
+export const getAddedComments = ({ getDiff, }) => getDiff().pipe(map(({ stdout }) => parseAddedComments(stdout)));

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dungarees/bin-audit-comments-domain",
+  "engines": {
+    "node": ">=25.0.0"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "type": "module",
+  "dependencies": {
+    "@dungarees/cli-command": "*",
+    "@dungarees/core": "*",
+    "rxjs": "^7.8.1",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@dungarees/rxjs": "*",
+    "@dungarees/sub-process": "*",
+    "vitest": "^3.0.2"
+  },
+  "author": "info@productkind.com",
+  "license": "MIT",
+  "version": "0.11.6",
+  "exports": {
+    "./behavior.ts": {
+      "import": "./behavior.js",
+      "types": "./behavior.d.ts"
+    },
+    "./events.ts": {
+      "import": "./events.js",
+      "types": "./events.d.ts"
+    },
+    "./judged-files.ts": {
+      "import": "./judged-files.js",
+      "types": "./judged-files.d.ts"
+    },
+    "./operations.ts": {
+      "import": "./operations.js",
+      "types": "./operations.d.ts"
+    }
+  }
+}