@agjs/tsforge 0.1.0

package/src/render/stream-markdown.ts

@@ -0,0 +1,128 @@
+import { formatTables, highlightCode, styleInline } from "./markdown";
+
+/**
+ * Incremental markdown renderer for the live-streamed answer (token channel
+ * `content`). Append-only — no cursor tricks, so scrollback is never corrupted:
+ * prose flushes as each line completes; fenced ```code``` and GFM `|` tables are
+ * held and emitted fully formatted the moment their block closes, producing the
+ * same output the settled renderMarkdown pass would. Pure string→string (no
+ * I/O), so it is unit-testable and reusable by any front end.
+ */
+export class StreamingMarkdown {
+  /** Trailing text of the current, not-yet-complete line. */
+  private partial = "";
+  /** Completed lines held while inside a fence or table block. */
+  private held: string[] = [];
+  private fenceLang = "";
+  private mode: "prose" | "fence" | "table" = "prose";
+  private streamed = false;
+
+  /** True once any content streamed since the last reset() — the settled
+   *  `message` event uses this to skip its (duplicate) full render. */
+  get sawContent(): boolean {
+    return this.streamed;
+  }
+
+  /** Feed a streamed chunk; returns whatever is ready to print NOW. */
+  push(text: string, color: boolean): string {
+    // First content of a turn opens with a blank separator, matching the
+    // leading "\n" the settled message render used to add.
+    let out = this.streamed ? "" : "\n";
+
+    this.streamed = true;
+    this.partial += text;
+
+    let nl = this.partial.indexOf("\n");
+
+    while (nl !== -1) {
+      const line = this.partial.slice(0, nl);
+
+      this.partial = this.partial.slice(nl + 1);
+      out += this.takeLine(line, color);
+      nl = this.partial.indexOf("\n");
+    }
+
+    return out;
+  }
+
+  /** Emit anything still held — the closing table/fence of an answer, or the
+   *  partial last line on abort — and clear the buffers (not the latch). */
+  flush(color: boolean): string {
+    let out = "";
+
+    if (this.mode === "fence" && this.held.length > 0) {
+      out += `${highlightCode(this.held.join("\n"), this.fenceLang, color)}\n`;
+    } else if (this.mode === "table") {
+      out += `${formatTables(this.held.join("\n"), color)}\n`;
+    }
+
+    if (this.partial.length > 0) {
+      out += `${styleInline(this.partial, color)}\n`;
+    }
+
+    this.mode = "prose";
+    this.held = [];
+    this.partial = "";
+
+    return out;
+  }
+
+  /** Forget everything, including the streamed latch (turn fully consumed). */
+  reset(): void {
+    this.flush(false);
+    this.streamed = false;
+  }
+
+  /** Consume one completed line according to the current block mode. */
+  private takeLine(line: string, color: boolean): string {
+    if (this.mode === "fence") {
+      if (/^\s*```\s*$/.test(line)) {
+        const code = highlightCode(this.held.join("\n"), this.fenceLang, color);
+
+        this.mode = "prose";
+        this.held = [];
+
+        return `${code}\n`;
+      }
+
+      this.held.push(line);
+
+      return "";
+    }
+
+    if (this.mode === "table") {
+      if (line.includes("|")) {
+        this.held.push(line);
+
+        return "";
+      }
+
+      const block = `${formatTables(this.held.join("\n"), color)}\n`;
+
+      this.mode = "prose";
+      this.held = [];
+
+      // The line that ended the table is a fresh prose/fence-opener line.
+      return block + this.takeLine(line, color);
+    }
+
+    const fence = /^\s*```([\w-]*)\s*$/.exec(line);
+
+    if (fence !== null) {
+      this.mode = "fence";
+      this.fenceLang =
+        fence[1] !== undefined && fence[1].length > 0 ? fence[1] : "typescript";
+
+      return "";
+    }
+
+    if (line.includes("|")) {
+      this.mode = "table";
+      this.held = [line];
+
+      return "";
+    }
+
+    return `${styleInline(line, color)}\n`;
+  }
+}

package/src/render/style.ts

@@ -0,0 +1,26 @@
+/** Terminal ANSI styling — shared by the event renderer and the welcome banner.
+ *  ESC is built via fromCharCode so the control byte is unambiguous in source.
+ *  Brand truecolor codes mirror apps/docs/src/styles/custom.css (--tf-brand-*). */
+const ESC = String.fromCharCode(27);
+
+export const RESET = `${ESC}[0m`;
+
+export const STYLE = {
+  dim: `${ESC}[2m`,
+  bold: `${ESC}[1m`,
+  red: `${ESC}[31m`,
+  green: `${ESC}[32m`,
+  yellow: `${ESC}[33m`,
+  magenta: `${ESC}[35m`,
+  /** #3b82f6 — primary brand */
+  brand: `${ESC}[38;2;59;130;246m`,
+  /** #60a5fa — lighter accent */
+  brandLight: `${ESC}[38;2;96;165;250m`,
+  /** #2563eb — darker accent */
+  brandDark: `${ESC}[38;2;37;99;235m`,
+} as const;
+
+/** Wrap `text` in an ANSI code when color is on; otherwise return it untouched. */
+export function paint(text: string, code: string, color: boolean): string {
+  return color ? `${code}${text}${RESET}` : text;
+}

package/src/rule-packs/bullmq/index.ts

@@ -0,0 +1,39 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { jobNameMustBeConstantRule } from "./rules/job-name-must-be-constant";
+import { jobOptionsMustSetAttemptsRule } from "./rules/job-options-must-set-attempts";
+import { noBlockingConcurrencyZeroRule } from "./rules/no-blocking-concurrency-zero";
+import { queueOptionsMustSetRemoveOnCompleteRule } from "./rules/queue-options-must-set-removeoncomplete";
+import { queueOptionsMustSetRemoveOnFailRule } from "./rules/queue-options-must-set-removeonfail";
+import { workerMustImplementCloseRule } from "./rules/worker-must-implement-close";
+import { workerMustListenFailedRule } from "./rules/worker-must-listen-failed";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "job-name-must-be-constant": jobNameMustBeConstantRule,
+  "job-options-must-set-attempts": jobOptionsMustSetAttemptsRule,
+  "no-blocking-concurrency-zero": noBlockingConcurrencyZeroRule,
+  "queue-options-must-set-removeoncomplete":
+    queueOptionsMustSetRemoveOnCompleteRule,
+  "queue-options-must-set-removeonfail": queueOptionsMustSetRemoveOnFailRule,
+  "worker-must-implement-close": workerMustImplementCloseRule,
+  "worker-must-listen-failed": workerMustListenFailedRule,
+};
+
+export const bullmqPack: IRulePack = {
+  id: "bullmq",
+  description:
+    "Job queue patterns with BullMQ (queue options, worker lifecycle, job naming)",
+  rules,
+  rulesConfig: {
+    "job-name-must-be-constant": "warn",
+    "job-options-must-set-attempts": "error",
+    "no-blocking-concurrency-zero": "error",
+    "queue-options-must-set-removeoncomplete": "error",
+    "queue-options-must-set-removeonfail": "error",
+    "worker-must-implement-close": "error",
+    "worker-must-listen-failed": "error",
+  },
+};
+
+export default bullmqPack;

package/src/rule-packs/bullmq/rules/index.ts

@@ -0,0 +1,7 @@
+export { jobNameMustBeConstantRule } from "./job-name-must-be-constant";
+export { jobOptionsMustSetAttemptsRule } from "./job-options-must-set-attempts";
+export { noBlockingConcurrencyZeroRule } from "./no-blocking-concurrency-zero";
+export { queueOptionsMustSetRemoveOnCompleteRule } from "./queue-options-must-set-removeoncomplete";
+export { queueOptionsMustSetRemoveOnFailRule } from "./queue-options-must-set-removeonfail";
+export { workerMustImplementCloseRule } from "./worker-must-implement-close";
+export { workerMustListenFailedRule } from "./worker-must-listen-failed";

package/src/rule-packs/bullmq/rules/job-name-must-be-constant.ts

@@ -0,0 +1,141 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import {
+  analyzeBullmqImports,
+  collectQueueDefinitions,
+  getCallReceiverKey,
+  isQueueAddCall,
+  isQueueLikeReceiverName,
+  type BullmqImports,
+  type QueueDefinition,
+} from "../utils";
+
+export const RULE_NAME = "job-name-must-be-constant";
+
+export interface JobNameMustBeConstantOptions {
+  readonly queueNamePattern?: string;
+}
+
+type RuleOptions = [JobNameMustBeConstantOptions];
+type MessageIds = "literalJobName";
+
+const DEFAULT_QUEUE_NAME_PATTERN = "Queue$";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    queueNamePattern: { type: "string", minLength: 1 },
+  },
+};
+
+export const jobNameMustBeConstantRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow string-literal job names in `<queue>.add(name, ...)` calls — use a constant identifier so all consumers share one source of truth.",
+    },
+    schema: [optionSchema],
+    messages: {
+      literalJobName:
+        "Job name `{{value}}` is an inline string literal — pass a constant identifier (e.g., `JOB_NAMES.foo`) so producers, workers, and dashboards share one source of truth.",
+    },
+  },
+  defaultOptions: [{ queueNamePattern: DEFAULT_QUEUE_NAME_PATTERN }],
+  create(context, [options]) {
+    const queuePattern = compilePattern(
+      options.queueNamePattern ?? DEFAULT_QUEUE_NAME_PATTERN
+    );
+
+    let imports: BullmqImports = {
+      hasBullmqImport: false,
+      workerLocalNames: new Set(),
+      queueLocalNames: new Set(),
+      queueEventsLocalNames: new Set(),
+    };
+    let knownQueues = new Map<string, QueueDefinition>();
+
+    return {
+      Program(program) {
+        imports = analyzeBullmqImports(program);
+        knownQueues = collectQueueDefinitions(program, imports);
+      },
+      CallExpression(node) {
+        if (!isQueueAddCall(node)) {
+          return;
+        }
+
+        if (!receiverIsQueueLike(node, knownQueues, queuePattern)) {
+          return;
+        }
+
+        const nameArg = node.arguments[0];
+
+        if (!nameArg) {
+          return;
+        }
+
+        if (
+          nameArg.type === AST_NODE_TYPES.Literal &&
+          typeof nameArg.value === "string"
+        ) {
+          context.report({
+            node: nameArg,
+            messageId: "literalJobName",
+            data: { value: nameArg.value },
+          });
+
+          return;
+        }
+
+        if (
+          nameArg.type === AST_NODE_TYPES.TemplateLiteral &&
+          nameArg.expressions.length === 0 &&
+          nameArg.quasis.length > 0
+        ) {
+          context.report({
+            node: nameArg,
+            messageId: "literalJobName",
+            data: { value: nameArg.quasis[0]?.value.cooked ?? "" },
+          });
+        }
+      },
+    };
+  },
+});
+
+function receiverIsQueueLike(
+  call: TSESTree.CallExpression,
+  knownQueues: ReadonlyMap<string, QueueDefinition>,
+  queuePattern: RegExp | null
+): boolean {
+  const key = getCallReceiverKey(call);
+
+  if (!key) {
+    return false;
+  }
+
+  if (knownQueues.has(key)) {
+    return true;
+  }
+
+  if (!queuePattern) {
+    return false;
+  }
+
+  const last = key.includes(".") ? (key.split(".").pop() ?? key) : key;
+
+  return queuePattern.test(last) || isQueueLikeReceiverName(last);
+}
+
+function compilePattern(source: string): RegExp | null {
+  try {
+    return new RegExp(source);
+  } catch {
+    return null;
+  }
+}

package/src/rule-packs/bullmq/rules/job-options-must-set-attempts.ts

@@ -0,0 +1,174 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import {
+  analyzeBullmqImports,
+  collectQueueDefinitions,
+  findObjectProperty,
+  getCallReceiverKey,
+  getOptionsObjectArg,
+  isQueueAddCall,
+  isQueueLikeReceiverName,
+  type BullmqImports,
+  type QueueDefinition,
+} from "../utils";
+
+export const RULE_NAME = "job-options-must-set-attempts";
+
+export interface JobOptionsMustSetAttemptsOptions {
+  readonly requireBackoff?: boolean;
+}
+
+type RuleOptions = [JobOptionsMustSetAttemptsOptions];
+type MessageIds = "missingAttempts" | "missingBackoff";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    requireBackoff: { type: "boolean" },
+  },
+};
+
+export const jobOptionsMustSetAttemptsRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Every `<queue>.add(...)` must configure `attempts` (per-call or via `defaultJobOptions`); when `attempts > 1`, also require `backoff`.",
+    },
+    schema: [optionSchema],
+    messages: {
+      missingAttempts:
+        "Job has no `attempts` configuration — failed jobs will not retry. Set `attempts` per-call or via `defaultJobOptions` on the Queue.",
+      missingBackoff:
+        "Job has `attempts > 1` but no `backoff` configuration — retries will fire back-to-back without delay, likely re-failing for the same reason. Add a `backoff` (e.g., `{ type: 'exponential', delay: 1000 }`).",
+    },
+  },
+  defaultOptions: [{ requireBackoff: true }],
+  create(context, [options]) {
+    const requireBackoff = options.requireBackoff !== false;
+
+    let imports: BullmqImports = {
+      hasBullmqImport: false,
+      workerLocalNames: new Set(),
+      queueLocalNames: new Set(),
+      queueEventsLocalNames: new Set(),
+    };
+    let knownQueues = new Map<string, QueueDefinition>();
+
+    return {
+      Program(program) {
+        imports = analyzeBullmqImports(program);
+        knownQueues = collectQueueDefinitions(program, imports);
+      },
+      CallExpression(node) {
+        if (!isQueueAddCall(node)) {
+          return;
+        }
+
+        if (!receiverIsQueueLike(node, knownQueues)) {
+          return;
+        }
+
+        const attemptsValue = getEffectiveOptionValue(
+          node,
+          knownQueues,
+          "attempts"
+        );
+
+        if (!attemptsValue) {
+          context.report({ node, messageId: "missingAttempts" });
+
+          return;
+        }
+
+        if (!requireBackoff) {
+          return;
+        }
+
+        if (isAttemptsLiteralOne(attemptsValue)) {
+          return;
+        }
+
+        const backoffValue = getEffectiveOptionValue(
+          node,
+          knownQueues,
+          "backoff"
+        );
+
+        if (!backoffValue) {
+          context.report({ node, messageId: "missingBackoff" });
+        }
+      },
+    };
+  },
+});
+
+function getEffectiveOptionValue(
+  call: TSESTree.CallExpression,
+  knownQueues: ReadonlyMap<string, QueueDefinition>,
+  name: string
+): TSESTree.Property["value"] | null {
+  const opts = getOptionsObjectArg(call, 2);
+
+  if (opts) {
+    const property = findObjectProperty(opts, name);
+
+    if (property) {
+      return property.value;
+    }
+  }
+
+  const key = getCallReceiverKey(call);
+
+  if (!key) {
+    return null;
+  }
+
+  const def = knownQueues.get(key);
+
+  if (!def?.defaultJobOptions) {
+    return null;
+  }
+
+  const defaultProperty = findObjectProperty(def.defaultJobOptions, name);
+
+  if (!defaultProperty) {
+    return null;
+  }
+
+  return defaultProperty.value;
+}
+
+function isAttemptsLiteralOne(value: TSESTree.Property["value"]): boolean {
+  return (
+    value.type === AST_NODE_TYPES.Literal &&
+    typeof value.value === "number" &&
+    value.value === 1
+  );
+}
+
+function receiverIsQueueLike(
+  call: TSESTree.CallExpression,
+  knownQueues: ReadonlyMap<string, QueueDefinition>
+): boolean {
+  const key = getCallReceiverKey(call);
+
+  if (!key) {
+    return false;
+  }
+
+  if (knownQueues.has(key)) {
+    return true;
+  }
+
+  const last = key.includes(".") ? (key.split(".").pop() ?? key) : key;
+
+  return isQueueLikeReceiverName(last);
+}

package/src/rule-packs/bullmq/rules/no-blocking-concurrency-zero.ts

@@ -0,0 +1,103 @@
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import {
+  analyzeBullmqImports,
+  findObjectProperty,
+  getOptionsObjectArg,
+  isNewWorker,
+  type BullmqImports,
+} from "../utils";
+
+export const RULE_NAME = "no-blocking-concurrency-zero";
+
+type RuleOptions = [];
+type MessageIds = "invalidConcurrency";
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {},
+};
+
+export const noBlockingConcurrencyZeroRule = createRule<
+  RuleOptions,
+  MessageIds
+>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow `new Worker(name, processor, { concurrency: <numericLiteral ≤ 0> })` — non-positive concurrency blocks job processing.",
+    },
+    schema: [optionSchema],
+    messages: {
+      invalidConcurrency:
+        "Worker concurrency must be ≥ 1 — `{{value}}` would block job processing entirely. Use a positive integer or read from configuration.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    let imports: BullmqImports = {
+      hasBullmqImport: false,
+      workerLocalNames: new Set(),
+      queueLocalNames: new Set(),
+      queueEventsLocalNames: new Set(),
+    };
+
+    return {
+      Program(program) {
+        imports = analyzeBullmqImports(program);
+      },
+      NewExpression(node) {
+        if (!isNewWorker(node, imports)) {
+          return;
+        }
+
+        const opts = getOptionsObjectArg(node, 2);
+
+        if (!opts) {
+          return;
+        }
+
+        const concurrency = findObjectProperty(opts, "concurrency");
+
+        if (!concurrency) {
+          return;
+        }
+
+        const value = concurrency.value;
+
+        if (
+          value.type === AST_NODE_TYPES.Literal &&
+          typeof value.value === "number" &&
+          value.value <= 0
+        ) {
+          context.report({
+            node: value,
+            messageId: "invalidConcurrency",
+            data: { value: String(value.value) },
+          });
+
+          return;
+        }
+
+        if (
+          value.type === AST_NODE_TYPES.UnaryExpression &&
+          value.operator === "-" &&
+          value.argument.type === AST_NODE_TYPES.Literal &&
+          typeof value.argument.value === "number" &&
+          value.argument.value > 0
+        ) {
+          context.report({
+            node: value,
+            messageId: "invalidConcurrency",
+            data: { value: `-${value.argument.value}` },
+          });
+        }
+      },
+    };
+  },
+});