@agjs/tsforge 0.1.5 → 0.1.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/src/loop/rule-docs.generated.json

@@ -289,6 +289,16 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-import-build-output": {
+    "what": "Disallow importing from build/output directories within the project. Source must import source, not compiled artifacts, to avoid stale-code drift and broken module boundaries.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-import-test-from-source": {
+    "what": "Disallow production/source files from importing test files. Tests may depend on source, never the reverse — test code must not ship in the production graph.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/pkce-required-for-oidc": {
     "what": "OIDC providers must use PKCE: `buildAuthorizationURL` must call `generateCodeVerifier()` and pass it to `createAuthorizationURL`.",
     "bad": "// Example that violates the rule",

package/src/loop/run.ts

@@ -1,3 +1,4 @@
+import { join } from "node:path";
 import type { ITask } from "../spec";
 import type { IChatMessage, IModelResponse, IProvider } from "../inference";
 import { validate, type ErrorParser } from "../validate";
@@ -8,7 +9,7 @@ import type { IRunResult, IRunOptions, Reporter } from "./loop.types";
 import { flags } from "../config";
 import { SYSTEM, seedPrompt } from "./prompt";
 import { detectStack } from "../stack-detection";
-import { TtsrManager } from "./ttsr";
+import { TtsrManager, parseProjectRules, type ITtsrRule } from "./ttsr";
 import { DEFAULT_TTSR_RULES } from "./ttsr-defaults";
 import {
   type ILoopCtx,
@@ -65,8 +66,27 @@ function handleDegeneration(
   };
 }
 
-/** Build and configure a TTSR manager if enabled. Returns null if disabled. */
-function initTtsrManager(): TtsrManager | null {
+/** Read and parse `<cwd>/.tsforge/rules.json` if present. Missing or invalid
+ *  files yield no rules (parseProjectRules tolerates malformed JSON). */
+export async function loadProjectTtsrRules(cwd: string): Promise<ITtsrRule[]> {
+  const file = Bun.file(join(cwd, ".tsforge", "rules.json"));
+
+  if (!(await file.exists())) {
+    return [];
+  }
+
+  return parseProjectRules(await file.text());
+}
+
+/** Build and configure a TTSR manager if enabled. Returns null if disabled.
+ *  Built-in defaults register first, then optional project rules from
+ *  `<cwd>/.tsforge/rules.json`; `addRule` ignores duplicate names, so a
+ *  built-in safety rule always wins over a same-named project rule. */
+export async function initTtsrManager(
+  cwd: string,
+  report: Reporter,
+  taskId: string
+): Promise<TtsrManager | null> {
   if (!flags.ttsr()) {
     return null;
   }
@@ -77,6 +97,22 @@ function initTtsrManager(): TtsrManager | null {
     manager.addRule(rule);
   }
 
+  let added = 0;
+
+  for (const rule of await loadProjectTtsrRules(cwd)) {
+    if (manager.addRule(rule)) {
+      added += 1;
+    }
+  }
+
+  if (added > 0) {
+    report({
+      kind: "ttsr",
+      task: taskId,
+      message: `loaded ${added} custom TTSR rule(s) from .tsforge/rules.json`,
+    });
+  }
+
   return manager;
 }
 
@@ -262,7 +298,7 @@ export async function runTask(
     thinkingTokenBudget ??
     (hasExistingCode ? undefined : LOOP_LIMITS.scratchThinkingBudget);
 
-  const ttsrManager = initTtsrManager();
+  const ttsrManager = await initTtsrManager(cwd, report, task.id);
 
   const ctx: ILoopCtx = {
     task,

package/src/rule-packs/index.ts

@@ -8,6 +8,7 @@ import { elysiaPack } from "./elysia";
 import { envAccessPack } from "./env-access";
 import { i18nKeysPack } from "./i18n-keys";
 import { jwtCookiesPack } from "./jwt-cookies";
+import { moduleBoundariesPack } from "./module-boundaries";
 import { oauthSecurityPack } from "./oauth-security";
 import { reactComponentArchitecturePack } from "./react-component-architecture";
 import { structuredLoggingPack } from "./structured-logging";
@@ -25,6 +26,7 @@ export const RULE_PACKS = {
   "env-access": envAccessPack,
   "i18n-keys": i18nKeysPack,
   "jwt-cookies": jwtCookiesPack,
+  "module-boundaries": moduleBoundariesPack,
   "oauth-security": oauthSecurityPack,
   "react-component-architecture": reactComponentArchitecturePack,
   "structured-logging": structuredLoggingPack,

package/src/rule-packs/module-boundaries/index.ts

@@ -0,0 +1,23 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { noImportBuildOutputRule } from "./rules/no-import-build-output";
+import { noImportTestFromSourceRule } from "./rules/no-import-test-from-source";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "no-import-build-output": noImportBuildOutputRule,
+  "no-import-test-from-source": noImportTestFromSourceRule,
+};
+
+export const moduleBoundariesPack: IRulePack = {
+  id: "module-boundaries",
+  description:
+    "Module boundary hygiene: keep the test/production and source/build-output boundaries clean so the dependency graph stays sound.",
+  rules,
+  rulesConfig: {
+    "no-import-build-output": "error",
+    "no-import-test-from-source": "error",
+  },
+};
+
+export default moduleBoundariesPack;

package/src/rule-packs/module-boundaries/rules/no-import-build-output.ts

@@ -0,0 +1,71 @@
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import { hasDirSegment, isRelativeImport } from "../utils";
+
+export const RULE_NAME = "no-import-build-output";
+
+export interface NoImportBuildOutputOptions {
+  readonly outputDirs?: readonly string[];
+}
+
+type RuleOptions = [NoImportBuildOutputOptions];
+type MessageIds = "buildOutputImported";
+
+const DEFAULT_OUTPUT_DIRS: readonly string[] = [
+  "dist",
+  "build",
+  "out",
+  ".next",
+  "coverage",
+];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    outputDirs: {
+      type: "array",
+      uniqueItems: true,
+      items: { type: "string" },
+    },
+  },
+};
+
+export const noImportBuildOutputRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow importing from build/output directories within the project. Source must import source, not compiled artifacts, to avoid stale-code drift and broken module boundaries.",
+    },
+    schema: [optionSchema],
+    messages: {
+      buildOutputImported:
+        "Do not import from build output ('{{source}}'). Import the source module directly so the build graph stays the single source of truth.",
+    },
+  },
+  defaultOptions: [{ outputDirs: [...DEFAULT_OUTPUT_DIRS] }],
+  create(context, [options]) {
+    const outputDirs = new Set(options.outputDirs ?? DEFAULT_OUTPUT_DIRS);
+
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+
+        if (typeof source !== "string" || !isRelativeImport(source)) {
+          return;
+        }
+
+        if (hasDirSegment(source, outputDirs)) {
+          context.report({
+            node: node.source,
+            messageId: "buildOutputImported",
+            data: { source },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/module-boundaries/rules/no-import-test-from-source.ts

@@ -0,0 +1,74 @@
+import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
+
+import { createRule } from "../../create-rule";
+import { hasDirSegment, isRelativeImport, isTestFileName } from "../utils";
+
+export const RULE_NAME = "no-import-test-from-source";
+
+export interface NoImportTestFromSourceOptions {
+  readonly testDirNames?: readonly string[];
+}
+
+type RuleOptions = [NoImportTestFromSourceOptions];
+type MessageIds = "testImportedFromSource";
+
+const DEFAULT_TEST_DIR_NAMES: readonly string[] = ["__tests__", "__mocks__"];
+
+const optionSchema: JSONSchema4 = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    testDirNames: {
+      type: "array",
+      uniqueItems: true,
+      items: { type: "string" },
+    },
+  },
+};
+
+export const noImportTestFromSourceRule = createRule<RuleOptions, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow production/source files from importing test files. Tests may depend on source, never the reverse — test code must not ship in the production graph.",
+    },
+    schema: [optionSchema],
+    messages: {
+      testImportedFromSource:
+        "Source files must not import test files ('{{source}}'). Move shared helpers into a non-test module so production code never depends on tests.",
+    },
+  },
+  defaultOptions: [{ testDirNames: [...DEFAULT_TEST_DIR_NAMES] }],
+  create(context, [options]) {
+    const testDirs = new Set(options.testDirNames ?? DEFAULT_TEST_DIR_NAMES);
+
+    // A test file may freely import other test files; only enforce the
+    // boundary when the importing file is itself non-test.
+    if (
+      isTestFileName(context.filename) ||
+      hasDirSegment(context.filename, testDirs)
+    ) {
+      return {};
+    }
+
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+
+        if (typeof source !== "string" || !isRelativeImport(source)) {
+          return;
+        }
+
+        if (isTestFileName(source) || hasDirSegment(source, testDirs)) {
+          context.report({
+            node: node.source,
+            messageId: "testImportedFromSource",
+            data: { source },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/module-boundaries/utils.ts

@@ -0,0 +1,29 @@
+/** True for relative import specifiers (`./x`, `../x`) — i.e. paths inside the
+ *  project, as opposed to bare package specifiers (`react`, `@scope/pkg`). */
+export function isRelativeImport(source: string): boolean {
+  return source.startsWith("./") || source.startsWith("../");
+}
+
+/** Path segments of a "/"-separated specifier, dropping "", ".", "..". */
+export function pathSegments(specifier: string): string[] {
+  return specifier
+    .split("/")
+    .filter((seg) => seg.length > 0 && seg !== "." && seg !== "..");
+}
+
+/** True if any directory segment of the specifier is in `dirs`. */
+export function hasDirSegment(
+  specifier: string,
+  dirs: ReadonlySet<string>
+): boolean {
+  return pathSegments(specifier).some((seg) => dirs.has(seg));
+}
+
+/** True if the specifier's final segment names a test/spec module
+ *  (`foo.test`, `foo.test.ts`, `foo.spec.tsx`, …). */
+export function isTestFileName(specifier: string): boolean {
+  const segments = specifier.split("/");
+  const base = segments[segments.length - 1] ?? "";
+
+  return /\.(?:test|spec)(?:\.[^.]+)?$/.test(base);
+}