@agjs/tsforge 0.1.0

package/src/rule-packs/code-flow/utils/prefer-early-return.ts

@@ -0,0 +1,132 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+import type { SourceCode } from "@typescript-eslint/utils/ts-eslint";
+
+const FLIPPABLE_OPERATORS = new Map<string, string>([
+  ["===", "!=="],
+  ["!==", "==="],
+  ["==", "!="],
+  ["!=", "=="],
+  ["<", ">="],
+  [">", "<="],
+  ["<=", ">"],
+  [">=", "<"],
+]);
+
+const MIN_CONSEQUENT_STATEMENTS = 2;
+
+export function getFunctionBlockBody(
+  node:
+    | TSESTree.FunctionDeclaration
+    | TSESTree.FunctionExpression
+    | TSESTree.ArrowFunctionExpression
+): TSESTree.BlockStatement | null {
+  if (node.body.type !== AST_NODE_TYPES.BlockStatement) {
+    return null;
+  }
+
+  return node.body;
+}
+
+export function findWrappedHappyPathIf(
+  body: TSESTree.BlockStatement
+): TSESTree.IfStatement | null {
+  if (body.body.length === 0) {
+    return null;
+  }
+
+  const lastStatement = body.body[body.body.length - 1];
+
+  if (lastStatement?.type !== AST_NODE_TYPES.IfStatement) {
+    return null;
+  }
+
+  if (lastStatement.alternate !== null) {
+    return null;
+  }
+
+  if (lastStatement.consequent.type !== AST_NODE_TYPES.BlockStatement) {
+    return null;
+  }
+
+  if (lastStatement.consequent.body.length < MIN_CONSEQUENT_STATEMENTS) {
+    return null;
+  }
+
+  return lastStatement;
+}
+
+export function negateTestExpression(
+  sourceCode: SourceCode,
+  test: TSESTree.Expression
+): string {
+  if (test.type === AST_NODE_TYPES.UnaryExpression && test.operator === "!") {
+    return sourceCode.getText(test.argument);
+  }
+
+  if (
+    test.type === AST_NODE_TYPES.Identifier ||
+    test.type === AST_NODE_TYPES.MemberExpression ||
+    test.type === "ChainExpression"
+  ) {
+    return `!${sourceCode.getText(test)}`;
+  }
+
+  if (test.type === AST_NODE_TYPES.BinaryExpression) {
+    const flipped = FLIPPABLE_OPERATORS.get(test.operator);
+
+    if (flipped !== undefined) {
+      return `${sourceCode.getText(test.left)} ${flipped} ${sourceCode.getText(test.right)}`;
+    }
+  }
+
+  if (test.type === AST_NODE_TYPES.LogicalExpression) {
+    if (test.operator === "&&") {
+      return `${negateOperand(sourceCode, test.left)} || ${negateOperand(sourceCode, test.right)}`;
+    }
+
+    if (test.operator === "||") {
+      return `${negateOperand(sourceCode, test.left)} && ${negateOperand(sourceCode, test.right)}`;
+    }
+  }
+
+  return `!(${sourceCode.getText(test)})`;
+}
+
+function negateOperand(
+  sourceCode: SourceCode,
+  node: TSESTree.Expression
+): string {
+  const negated = negateTestExpression(sourceCode, node);
+
+  if (needsParentheses(node)) {
+    return `(${negated})`;
+  }
+
+  return negated;
+}
+
+function needsParentheses(node: TSESTree.Expression): boolean {
+  return (
+    node.type === AST_NODE_TYPES.BinaryExpression ||
+    node.type === AST_NODE_TYPES.LogicalExpression ||
+    node.type === AST_NODE_TYPES.ConditionalExpression ||
+    node.type === AST_NODE_TYPES.AssignmentExpression
+  );
+}
+
+export function buildGuardClauseReplacement(
+  sourceCode: SourceCode,
+  ifStatement: TSESTree.IfStatement
+): string | null {
+  if (ifStatement.consequent.type !== AST_NODE_TYPES.BlockStatement) {
+    return null;
+  }
+
+  const invertedTest = negateTestExpression(sourceCode, ifStatement.test);
+  const guardClause = `if (${invertedTest}) {\n  return;\n}\n`;
+  const hoistedBody = ifStatement.consequent.body
+    .map((statement) => sourceCode.getText(statement))
+    .join("\n");
+
+  return `${guardClause}\n${hoistedBody}`;
+}

package/src/rule-packs/comment-hygiene/index.ts

@@ -0,0 +1,25 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { noHistoricalCommentsRule } from "./rules/no-historical-comments";
+import { noNarrationCommentsRule } from "./rules/no-narration-comments";
+import { noPrReferenceCommentsRule } from "./rules/no-pr-reference-comments";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "no-historical-comments": noHistoricalCommentsRule,
+  "no-narration-comments": noNarrationCommentsRule,
+  "no-pr-reference-comments": noPrReferenceCommentsRule,
+};
+
+export const commentHygienePack: IRulePack = {
+  id: "comment-hygiene",
+  description: "Meaningful comments and documentation standards",
+  rules,
+  rulesConfig: {
+    "no-historical-comments": "error",
+    "no-narration-comments": "error",
+    "no-pr-reference-comments": "error",
+  },
+};
+
+export default commentHygienePack;

package/src/rule-packs/comment-hygiene/rules/index.ts

@@ -0,0 +1,3 @@
+export { noHistoricalCommentsRule } from "./no-historical-comments";
+export { noNarrationCommentsRule } from "./no-narration-comments";
+export { noPrReferenceCommentsRule } from "./no-pr-reference-comments";

package/src/rule-packs/comment-hygiene/rules/no-historical-comments.ts

@@ -0,0 +1,102 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-historical-comments";
+
+type MessageIds = "historicalComment";
+
+/*
+ * Patterns that frame code relative to what it USED TO be or to a past
+ * incident, instead of describing the current invariant. Each entry is
+ * deliberately narrow — bare "now" / "legacy" / "previously" appear in
+ * legitimate technical prose, so the rule only matches the specific
+ * historical-narration constructions that have to come out.
+ */
+const HISTORICAL_PATTERNS: readonly RegExp[] = [
+  /\bcodex\s+flagged\b/iu,
+  /\bbefore\s+the\s+fix\b/iu,
+  /\bafter\s+the\s+fix\b/iu,
+  /\bbefore\s+the\s+refactor\b/iu,
+  /\bafter\s+the\s+refactor\b/iu,
+  /\bthe\s+[a-z][\w-]*\s+refactor\b/iu,
+  /\bwe\s+used\s+to\b/iu,
+  /\bthis\s+used\s+to\b/iu,
+  /\bused\s+to\s+be\b/iu,
+  /\bno\s+longer\b/iu,
+  /\bkept\s+for\s+(?:backwards|backward|legacy|compat)\b/iu,
+  /\b(?:was|were)\s+a\s+(?:footgun|bug)\b/iu,
+  /\bhistorical(?:ly)?\b/iu,
+  /\balpine[-\s]?era\b/iu,
+];
+
+function commentText(comment: TSESTree.Comment): string {
+  if (comment.type === "Line") {
+    return comment.value.trim();
+  }
+
+  return comment.value
+    .split("\n")
+    .map((line) => line.replace(/^\s*\*?/u, ""))
+    .join(" ")
+    .trim();
+}
+
+function looksLikeJsDoc(comment: TSESTree.Comment): boolean {
+  return comment.type === "Block" && comment.value.startsWith("*");
+}
+
+export const noHistoricalCommentsRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow comments that frame code relative to what it used to do or to a past incident ('Codex flagged X', 'before the fix', 'after the refactor', 'we used to', 'no longer'). Source comments must describe the current invariant; history belongs in the commit message or PR description, where it doesn't rot when the code changes again.",
+    },
+    schema: [],
+    messages: {
+      historicalComment:
+        "Historical narration ({{snippet}}). Source comments describe the current invariant, not what the code used to do — move the history to the commit message or delete the comment.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      Program() {
+        const comments = context.sourceCode.getAllComments();
+
+        for (const comment of comments) {
+          if (looksLikeJsDoc(comment)) {
+            continue;
+          }
+
+          const text = commentText(comment);
+
+          if (text === "") {
+            continue;
+          }
+
+          for (const pattern of HISTORICAL_PATTERNS) {
+            const match = pattern.exec(text);
+
+            if (match !== null) {
+              const matchedPhrase = match[0];
+              const snippet =
+                matchedPhrase.length > 40
+                  ? `${matchedPhrase.slice(0, 40)}…`
+                  : matchedPhrase;
+
+              context.report({
+                loc: comment.loc,
+                messageId: "historicalComment",
+                data: { snippet },
+              });
+              break;
+            }
+          }
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/comment-hygiene/rules/no-narration-comments.ts

@@ -0,0 +1,83 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-narration-comments";
+
+type MessageIds = "narrationComment";
+
+const NARRATION_PATTERNS: readonly RegExp[] = [
+  /^here\s+we\b/iu,
+  /^now\s+we\b/iu,
+  /^first[,]?\s+(?:we\b|[a-z])/iu,
+  /^then[,]?\s+(?:we\b|[a-z])/iu,
+  /^next[,]?\s+(?:we\b|[a-z])/iu,
+  /^finally[,]?\s+(?:we\b|[a-z])/iu,
+  /^let's\b/iu,
+  /^let\s+me\b/iu,
+];
+
+function commentText(comment: TSESTree.Comment): string {
+  if (comment.type === "Line") {
+    return comment.value.trim();
+  }
+
+  return comment.value
+    .split("\n")
+    .map((line) => line.replace(/^\s*\*?/u, ""))
+    .join(" ")
+    .trim();
+}
+
+function looksLikeJsDoc(comment: TSESTree.Comment): boolean {
+  return comment.type === "Block" && comment.value.startsWith("*");
+}
+
+export const noNarrationCommentsRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow narrative comments like 'Here we...', 'Now we...', 'First, we...'. These read as step-by-step prose and add no information a future reader can't get from the code itself. Often a tell that the comment was generated by an agent describing its own changes.",
+    },
+    schema: [],
+    messages: {
+      narrationComment:
+        "Narrative comment ({{snippet}}). Describe the WHY, not the sequence of operations — or delete the comment.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      Program() {
+        const comments = context.sourceCode.getAllComments();
+
+        for (const comment of comments) {
+          if (looksLikeJsDoc(comment)) {
+            continue;
+          }
+
+          const text = commentText(comment);
+
+          if (text === "") {
+            continue;
+          }
+
+          for (const pattern of NARRATION_PATTERNS) {
+            if (pattern.test(text)) {
+              const snippet = text.length > 40 ? `${text.slice(0, 40)}…` : text;
+
+              context.report({
+                loc: comment.loc,
+                messageId: "narrationComment",
+                data: { snippet },
+              });
+              break;
+            }
+          }
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/comment-hygiene/rules/no-pr-reference-comments.ts

@@ -0,0 +1,90 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+
+export const RULE_NAME = "no-pr-reference-comments";
+
+type MessageIds = "prReferenceComment";
+
+interface IPrPattern {
+  readonly pattern: RegExp;
+  readonly label: string;
+}
+
+const PR_PATTERNS: readonly IPrPattern[] = [
+  {
+    pattern: /https?:\/\/github\.com\/[^\s)]+\/(?:pull|issues)\/\d+/iu,
+    label: "GitHub PR/issue URL",
+  },
+  {
+    pattern: /\b(?:see|closes?|fixes|fixed|addresses|resolves?|refs?)\s+#\d+/iu,
+    label: "issue/PR reference",
+  },
+  {
+    pattern: /\bPRs?\s+#?\d+/iu,
+    label: "PR number",
+  },
+  {
+    pattern: /(?:^|[\s(])#\d+\b/u,
+    label: "issue/PR number",
+  },
+];
+
+function commentText(comment: TSESTree.Comment): string {
+  if (comment.type === "Line") {
+    return comment.value;
+  }
+
+  return comment.value;
+}
+
+export const noPrReferenceCommentsRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow PR/issue references in comments. They belong in commit messages and PR descriptions — leaving them in source rots when the repo moves, the issue tracker migrates, or the numbering changes.",
+    },
+    schema: [],
+    messages: {
+      prReferenceComment:
+        "Comment contains {{label}} ({{snippet}}). Move it to the commit message or PR description — the git log is the canonical place for repo-history references.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      Program() {
+        const comments = context.sourceCode.getAllComments();
+
+        for (const comment of comments) {
+          const text = commentText(comment);
+
+          if (text.trim() === "") {
+            continue;
+          }
+
+          for (const { pattern, label } of PR_PATTERNS) {
+            const match = pattern.exec(text);
+
+            if (match === null) {
+              continue;
+            }
+
+            const matched = match[0].trim();
+            const snippet =
+              matched.length > 40 ? `${matched.slice(0, 40)}…` : matched;
+
+            context.report({
+              loc: comment.loc,
+              messageId: "prReferenceComment",
+              data: { label, snippet },
+            });
+            break;
+          }
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/create-rule.ts

@@ -0,0 +1,9 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
+
+/**
+ * RuleCreator for tsforge rules. Generates docs URLs pointing to GitHub.
+ */
+export const createRule = ESLintUtils.RuleCreator(
+  (ruleName) =>
+    `https://github.com/tsforge/tsforge/blob/main/docs/rules/${ruleName}.md`
+);

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

@@ -0,0 +1,41 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { accountScopedTablesRequireWhereRule } from "./rules/account-scoped-tables-require-where";
+import { noNestedDbTransactionRule } from "./rules/no-nested-db-transaction";
+import { noRawSqlOutsideAllowlistRule } from "./rules/no-raw-sql-outside-allowlist";
+import { relationsMustCoverFksRule } from "./rules/relations-must-cover-fks";
+import { schemaFilesMustNotImportDriverRule } from "./rules/schema-files-must-not-import-driver";
+import { schemaFilesMustOnlyExportSchemaRule } from "./rules/schema-files-must-only-export-schema";
+import { tablesMustHaveTimestampsRule } from "./rules/tables-must-have-timestamps";
+import { timestampMustSpecifyModeRule } from "./rules/timestamp-must-specify-mode";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "account-scoped-tables-require-where": accountScopedTablesRequireWhereRule,
+  "no-nested-db-transaction": noNestedDbTransactionRule,
+  "no-raw-sql-outside-allowlist": noRawSqlOutsideAllowlistRule,
+  "relations-must-cover-fks": relationsMustCoverFksRule,
+  "schema-files-must-not-import-driver": schemaFilesMustNotImportDriverRule,
+  "schema-files-must-only-export-schema": schemaFilesMustOnlyExportSchemaRule,
+  "tables-must-have-timestamps": tablesMustHaveTimestampsRule,
+  "timestamp-must-specify-mode": timestampMustSpecifyModeRule,
+};
+
+export const drizzlePack: IRulePack = {
+  id: "drizzle",
+  description:
+    "Database access patterns using Drizzle ORM (schema safety, query scoping, transaction safety)",
+  rules,
+  rulesConfig: {
+    "account-scoped-tables-require-where": "error",
+    "no-nested-db-transaction": "error",
+    "no-raw-sql-outside-allowlist": "error",
+    "relations-must-cover-fks": "error",
+    "schema-files-must-not-import-driver": "error",
+    "schema-files-must-only-export-schema": "warn",
+    "tables-must-have-timestamps": "warn",
+    "timestamp-must-specify-mode": "error",
+  },
+};
+
+export default drizzlePack;