@agjs/tsforge 0.4.0 → 0.5.1

package/src/loop/tools/execute-tool.ts

@@ -30,6 +30,7 @@ const HANDLERS: Record<ToolName, ToolHandler> = {
   [TOOL_NAME.typeAt]: (a, c) => doLsp(TOOL_NAME.typeAt, a, c),
   [TOOL_NAME.diagnostics]: (a, c) => doLsp(TOOL_NAME.diagnostics, a, c),
   [TOOL_NAME.renameSymbol]: (a, c) => doLsp(TOOL_NAME.renameSymbol, a, c),
+  [TOOL_NAME.moveFile]: (a, c) => doLsp(TOOL_NAME.moveFile, a, c),
   [TOOL_NAME.organizeImports]: (a, c) => doLsp(TOOL_NAME.organizeImports, a, c),
   [TOOL_NAME.scaffoldUi]: doScaffoldUi,
   [TOOL_NAME.scaffoldRoutes]: doScaffoldRoutes,

package/src/loop/tools/lsp-ops.ts

@@ -1,7 +1,7 @@
 import { relative } from "node:path";
 import { fileArg, TOOL_NAME, type ToolName } from "../../agent";
 import { runArgvCommand } from "../../lib/fs";
-import { writable } from "../../lib/scope";
+import { writable, isVendored } from "../../lib/scope";
 import { LOOP_LIMITS } from "../loop.constants";
 import { str, reject, type IToolContext } from "./tool-context";
 
@@ -137,10 +137,57 @@ export function doLsp(
     return `organize_imports: ${n} change(s) in ${file}`;
   }
 
+  // move_file takes {from, to} (not {file, symbol}) — handle before doSymbolLsp's
+  // symbol guard. Scope-enforced: a move rewrites importers across the project; it
+  // must NOT touch read-only/out-of-scope/vendored files.
+  if (name === TOOL_NAME.moveFile) {
+    return doMoveFile(svc, args, ctx, rel);
+  }
+
   // The remaining tools address a symbol by name within a file.
   return doSymbolLsp(name, svc, file, args, ctx, rel);
 }
 
+/** move_file: relocate a file and rewrite every importer's specifier. */
+function doMoveFile(
+  svc: LspService,
+  args: Record<string, unknown>,
+  ctx: IToolContext,
+  rel: (abs: string) => string
+): string {
+  const from = str(args, "from");
+  const to = str(args, "to");
+
+  if (from.length === 0 || to.length === 0) {
+    return "move_file: need {from, to}";
+  }
+
+  const targets = svc.moveTargets(from, to).map(rel);
+  const blocked = targets.filter(
+    (t) => !writable(t, ctx.files) || isVendored(t, ctx.vendored ?? [])
+  );
+
+  if (blocked.length > 0) {
+    return reject(
+      ctx,
+      "move_file",
+      `move '${from}' → '${to}' REJECTED: would touch out-of-scope/read-only file(s): ${blocked.join(", ")}. Move files only when the source, destination, and every importer are in your editable scope.`
+    );
+  }
+
+  const changed = svc.moveFile(from, to);
+
+  ctx.report({
+    kind: "tool",
+    task: ctx.task,
+    message: `move_file ${from}→${to} (${changed ?? 0})`,
+  });
+
+  return changed === null
+    ? `move_file: source '${from}' not found`
+    : `moved '${from}' → '${to}', updated imports across ${changed} file(s)`;
+}
+
 type LspService = NonNullable<IToolContext["tsService"]>;
 
 /** The LSP tools that resolve a symbol position first (type_at, find_references,

package/src/lsp/service.ts

@@ -1,4 +1,5 @@
-import { join, isAbsolute } from "node:path";
+import { join, isAbsolute, dirname } from "node:path";
+import { mkdirSync, rmSync } from "node:fs";
 import ts from "typescript";
 import type {
   ITsDiagnostic,
@@ -451,6 +452,73 @@ export class TsService {
     return [...new Set((locs ?? []).map((l) => l.fileName))];
   }
 
+  /** Edits a file move would produce (rewriting importers + the file's own
+   *  relative imports). Absolute paths. */
+  private moveEdits(
+    fromAbs: string,
+    toAbs: string
+  ): readonly ts.FileTextChanges[] {
+    return this.service.getEditsForFileRename(
+      fromAbs,
+      toAbs,
+      ts.getDefaultFormatCodeSettings("\n"),
+      {}
+    );
+  }
+
+  /** Which files a move would touch — every importer plus the source and
+   *  destination — for scope-checking BEFORE applying. Absolute paths. */
+  moveTargets(fromRel: string, toRel: string): string[] {
+    const fromAbs = this.toAbs(fromRel);
+    const toAbs = this.toAbs(toRel);
+    const touched = new Set(
+      this.moveEdits(fromAbs, toAbs).map((e) => e.fileName)
+    );
+
+    touched.add(fromAbs);
+    touched.add(toAbs);
+
+    return [...touched];
+  }
+
+  /**
+   * Move a file and rewrite every import that points at it (and its own relative
+   * imports), compiler-accurately via getEditsForFileRename. Returns the number
+   * of files changed (incl. the moved file), or null if the source can't be read.
+   * Callers MUST enforce scope first (a move can touch read-only files).
+   */
+  moveFile(fromRel: string, toRel: string): number | null {
+    const fromAbs = this.toAbs(fromRel);
+    const toAbs = this.toAbs(toRel);
+    const original = ts.sys.readFile(fromAbs);
+
+    if (original === undefined) {
+      return null;
+    }
+
+    const edits = this.moveEdits(fromAbs, toAbs);
+
+    // Apply the import rewrites (importers + the moved file's own imports) while
+    // the file still lives at its old path, THEN relocate the edited content.
+    this.applyChanges(edits);
+
+    const moved = ts.sys.readFile(fromAbs) ?? original;
+
+    mkdirSync(dirname(toAbs), { recursive: true });
+    ts.sys.writeFile(toAbs, moved);
+    rmSync(fromAbs, { force: true });
+
+    const stale = this.files.indexOf(fromAbs);
+
+    if (stale >= 0) {
+      this.files.splice(stale, 1);
+    }
+
+    this.refresh(toRel);
+
+    return new Set([...edits.map((e) => e.fileName), fromAbs]).size;
+  }
+
   /** Organize imports (dedupe/sort/drop unused) for one file. Returns edits made. */
   organizeImports(file: string): number {
     const changes = this.service.organizeImports(

package/src/meta-rules/registry.ts

@@ -28,6 +28,8 @@ import { noGithubContextInShellRule } from "./rules/ci/no-github-context-in-shel
 import { dockerfileBaseImagePinnedRule } from "./rules/docker/dockerfile-base-image-pinned";
 import { dockerfileNonRootUserRule } from "./rules/docker/dockerfile-non-root-user";
 import { dockerfileNoSecretsInEnvArgRule } from "./rules/docker/dockerfile-no-secrets-in-env-arg";
+import { noUndeclaredDependenciesRule } from "./rules/supply-chain/no-undeclared-dependencies";
+import { noCircularImportsRule } from "./rules/structure/no-circular-imports";
 
 /**
  * All available meta-rules, ordered by category for readability.
@@ -45,6 +47,7 @@ export const META_RULES: readonly IMetaRule[] = [
   dependencyOverridesRequireCommentRule,
   productionMustNotUseDrizzlePushRule,
   migrationsMustBeCheckedInRule,
+  noUndeclaredDependenciesRule,
 
   // Source text
   noEslintDisableCommentsRule,
@@ -74,4 +77,7 @@ export const META_RULES: readonly IMetaRule[] = [
   dockerfileBaseImagePinnedRule,
   dockerfileNonRootUserRule,
   dockerfileNoSecretsInEnvArgRule,
+
+  // Structure (cross-file)
+  noCircularImportsRule,
 ];

package/src/meta-rules/rules/structure/no-circular-imports.ts

@@ -0,0 +1,195 @@
+import { dirname, join, normalize } from "node:path";
+import type {
+  IMetaRule,
+  IMetaRuleContext,
+  IMetaRuleViolation,
+} from "../../meta-rules.types";
+
+/**
+ * Circular imports (A → B → A) are a cross-file smell that per-file ESLint cannot
+ * see: they cause partially-initialized modules (TDZ/`undefined` at import time),
+ * defeat tree-shaking, and make refactors brittle. We build the module graph from
+ * the project's own relative imports and report each cyclic group once.
+ *
+ * Only RELATIVE imports (`./`, `../`) are followed — alias/bare specifiers need a
+ * resolver and would risk false positives. That keeps this high-precision: every
+ * reported cycle is real, in-project, and the model's to break.
+ */
+const IMPORT_FROM = /(?:import|export)[^'"]*?from\s*['"](?<spec>[^'"]+)['"]/gu;
+const DYNAMIC_IMPORT = /\bimport\s*\(\s*['"](?<spec>[^'"]+)['"]\s*\)/gu;
+
+/** Relative import specifiers (`./x`, `../y`) found in one file's text. */
+function relativeSpecifiers(text: string): string[] {
+  const out: string[] = [];
+
+  for (const re of [IMPORT_FROM, DYNAMIC_IMPORT]) {
+    re.lastIndex = 0;
+
+    for (const m of text.matchAll(re)) {
+      const spec = m.groups?.spec;
+
+      if (spec?.startsWith(".") === true) {
+        out.push(spec);
+      }
+    }
+  }
+
+  return out;
+}
+
+/** Resolve a relative specifier to a known source file, or null. */
+function resolveToSourceFile(
+  fromFile: string,
+  spec: string,
+  fileSet: ReadonlySet<string>
+): string | null {
+  const base = normalize(join(dirname(fromFile), spec))
+    .split("\\")
+    .join("/");
+  const candidates =
+    base.endsWith(".ts") || base.endsWith(".tsx")
+      ? [base]
+      : [`${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`];
+
+  for (const candidate of candidates) {
+    if (fileSet.has(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/** Adjacency list of in-project module edges. */
+function buildGraph(ctx: IMetaRuleContext): Map<string, string[]> {
+  const fileSet = new Set(ctx.sourceFiles);
+  const graph = new Map<string, string[]>();
+
+  for (const file of ctx.sourceFiles) {
+    const text = ctx.readFile(file);
+    const edges: string[] = [];
+
+    if (text !== null) {
+      for (const spec of relativeSpecifiers(text)) {
+        const target = resolveToSourceFile(file, spec, fileSet);
+
+        if (target !== null && target !== file) {
+          edges.push(target);
+        }
+      }
+    }
+
+    graph.set(file, edges);
+  }
+
+  return graph;
+}
+
+interface ITarjanState {
+  readonly index: Map<string, number>;
+  readonly low: Map<string, number>;
+  readonly onStack: Set<string>;
+  readonly stack: string[];
+  readonly components: string[][];
+  counter: number;
+}
+
+/** Tarjan's strongly-connected-components — each SCC with >1 node (or a self-loop)
+ *  is an import cycle. Iterative-free recursion is fine for project-sized graphs. */
+function strongConnect(
+  node: string,
+  graph: Map<string, string[]>,
+  state: ITarjanState
+): void {
+  state.index.set(node, state.counter);
+  state.low.set(node, state.counter);
+  state.counter += 1;
+  state.stack.push(node);
+  state.onStack.add(node);
+
+  for (const next of graph.get(node) ?? []) {
+    if (!state.index.has(next)) {
+      strongConnect(next, graph, state);
+      state.low.set(
+        node,
+        Math.min(state.low.get(node) ?? 0, state.low.get(next) ?? 0)
+      );
+    } else if (state.onStack.has(next)) {
+      state.low.set(
+        node,
+        Math.min(state.low.get(node) ?? 0, state.index.get(next) ?? 0)
+      );
+    }
+  }
+
+  if (state.low.get(node) === state.index.get(node)) {
+    const component: string[] = [];
+
+    for (;;) {
+      const popped = state.stack.pop();
+
+      if (popped === undefined) {
+        break;
+      }
+
+      state.onStack.delete(popped);
+      component.push(popped);
+
+      if (popped === node) {
+        break;
+      }
+    }
+
+    state.components.push(component);
+  }
+}
+
+/** All cyclic groups: SCCs of size > 1, plus single nodes that import themselves. */
+function findCycles(graph: Map<string, string[]>): string[][] {
+  const state: ITarjanState = {
+    index: new Map(),
+    low: new Map(),
+    onStack: new Set(),
+    stack: [],
+    components: [],
+    counter: 0,
+  };
+
+  for (const node of graph.keys()) {
+    if (!state.index.has(node)) {
+      strongConnect(node, graph, state);
+    }
+  }
+
+  return state.components.filter((c) => {
+    if (c.length > 1) {
+      return true;
+    }
+
+    const only = c[0];
+
+    return only !== undefined && (graph.get(only) ?? []).includes(only);
+  });
+}
+
+export const noCircularImportsRule: IMetaRule = {
+  id: "no-circular-imports",
+  category: "stack-layout",
+  description:
+    "Project modules must not form import cycles (A → B → A) — they cause partial-initialization bugs and defeat tree-shaking.",
+  severity: "error",
+  run(ctx) {
+    const cycles = findCycles(buildGraph(ctx));
+
+    return cycles.map((cycle): IMetaRuleViolation => {
+      const ordered = [...cycle].sort();
+
+      return {
+        file: ordered[0] ?? "src",
+        ruleId: "no-circular-imports",
+        severity: "error",
+        message: `Import cycle between ${ordered.length} modules: ${ordered.join(" ↔ ")}. Break it by extracting the shared piece into a third module both can import.`,
+      };
+    });
+  },
+};

package/src/meta-rules/rules/supply-chain/no-undeclared-dependencies.ts

@@ -0,0 +1,180 @@
+import { builtinModules } from "node:module";
+import type {
+  IMetaRule,
+  IMetaRuleContext,
+  IMetaRuleViolation,
+} from "../../meta-rules.types";
+
+/**
+ * Every bare `import` must resolve to a DECLARED dependency. A classic AI mistake
+ * is importing a package it never added to package.json — it works locally via a
+ * hoisted/transitive copy, then breaks on a clean install in CI or for a teammate.
+ * We compare each imported package against package.json's declared deps (+ Node
+ * builtins, `bun:` specifiers, tsconfig path aliases, and the project's own name).
+ */
+const IMPORT_FROM = /(?:import|export)[^'"]*?from\s*['"](?<spec>[^'"]+)['"]/gu;
+const DYNAMIC_IMPORT = /\bimport\s*\(\s*['"](?<spec>[^'"]+)['"]\s*\)/gu;
+const NODE_BUILTINS = new Set([
+  ...builtinModules,
+  ...builtinModules.map((m) => `node:${m}`),
+]);
+
+/** Bare specifiers (packages), skipping relative/absolute paths. */
+function bareSpecifiers(text: string): string[] {
+  const out: string[] = [];
+
+  for (const re of [IMPORT_FROM, DYNAMIC_IMPORT]) {
+    re.lastIndex = 0;
+
+    for (const m of text.matchAll(re)) {
+      const spec = m.groups?.spec;
+
+      if (
+        spec !== undefined &&
+        !spec.startsWith(".") &&
+        !spec.startsWith("/")
+      ) {
+        out.push(spec);
+      }
+    }
+  }
+
+  return out;
+}
+
+/** The package name a specifier belongs to (`@scope/pkg/sub` → `@scope/pkg`). */
+function packageName(spec: string): string {
+  const parts = spec.split("/");
+
+  if (spec.startsWith("@")) {
+    return parts.slice(0, 2).join("/");
+  }
+
+  return parts[0] ?? spec;
+}
+
+/** Collect declared dependency names from every dependency field. */
+function declaredDeps(pkg: Record<string, unknown> | null): Set<string> {
+  const names = new Set<string>();
+  const fields = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+  ];
+
+  for (const field of fields) {
+    const map = pkg?.[field];
+
+    if (typeof map === "object" && map !== null) {
+      for (const name of Object.keys(map)) {
+        names.add(name);
+      }
+    }
+  }
+
+  return names;
+}
+
+/** Read a string-keyed property as `unknown` without surfacing `any`. */
+function prop(value: unknown, key: string): unknown {
+  if (typeof value !== "object" || value === null || !(key in value)) {
+    return undefined;
+  }
+
+  const record: Record<string, unknown> = { ...value };
+
+  return record[key];
+}
+
+/** tsconfig `compilerOptions.paths` alias prefixes (e.g. `@/*` → `@/`). */
+function aliasPrefixes(ctx: IMetaRuleContext): string[] {
+  const raw = ctx.readFile("tsconfig.json");
+
+  if (raw === null) {
+    return [];
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    const paths = prop(prop(parsed, "compilerOptions"), "paths");
+
+    if (typeof paths !== "object" || paths === null) {
+      return [];
+    }
+
+    return Object.keys(paths).map((k) => k.replace(/\*$/u, ""));
+  } catch {
+    return [];
+  }
+}
+
+/** True when an import is satisfied without a runtime dep declaration. */
+function isAllowed(
+  pkg: string,
+  spec: string,
+  declared: ReadonlySet<string>,
+  aliases: readonly string[],
+  ownName: string
+): boolean {
+  if (spec.startsWith("bun:") || pkg === "bun") {
+    return true;
+  }
+
+  if (NODE_BUILTINS.has(pkg) || NODE_BUILTINS.has(spec)) {
+    return true;
+  }
+
+  if (pkg === ownName || declared.has(pkg) || declared.has(`@types/${pkg}`)) {
+    return true;
+  }
+
+  return aliases.some((prefix) => prefix.length > 0 && spec.startsWith(prefix));
+}
+
+export const noUndeclaredDependenciesRule: IMetaRule = {
+  id: "no-undeclared-dependencies",
+  category: "supply-chain",
+  description:
+    "Every imported package must be declared in package.json — an undeclared import works via hoisting locally but breaks on a clean install.",
+  severity: "error",
+  run(ctx) {
+    if (ctx.packageJson === null) {
+      return []; // no manifest to check against
+    }
+
+    const declared = declaredDeps(ctx.packageJson);
+    const aliases = aliasPrefixes(ctx);
+    const ownNameRaw = prop(ctx.packageJson, "name");
+    const ownName = typeof ownNameRaw === "string" ? ownNameRaw : "";
+    const violations: IMetaRuleViolation[] = [];
+    const seen = new Set<string>();
+
+    for (const file of ctx.sourceFiles) {
+      const text = ctx.readFile(file);
+
+      if (text === null) {
+        continue;
+      }
+
+      for (const spec of bareSpecifiers(text)) {
+        const pkg = packageName(spec);
+        const key = `${file}::${pkg}`;
+
+        if (isAllowed(pkg, spec, declared, aliases, ownName) || seen.has(key)) {
+          continue;
+        }
+
+        seen.add(key);
+        violations.push({
+          file,
+          ruleId: "no-undeclared-dependencies",
+          severity: "error",
+          message: `Imports \`${pkg}\` but it is not in package.json — add it to dependencies (or devDependencies) so a clean install resolves it.`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/strict.type-aware.eslint.config.mjs

@@ -1,7 +1,21 @@
 // Optional type-aware ESLint overlay — enabled only when the target has a
-// compiling tsconfig (see detect-gate.ts). Adds async correctness rules that
-// require parserOptions.project; kept separate from strict.eslint.config.mjs
-// so the syntactic gate still runs on any .ts file without type info.
+// compiling tsconfig (see detect-gate.ts). These rules need full type info
+// (parserOptions.project) and are kept separate from strict.eslint.config.mjs so
+// the syntactic gate still runs on any .ts file without type info.
+//
+// Two jobs:
+//   1. Async correctness — floating/misused promises (a dropped `await` is silent
+//      data loss / unhandled rejection).
+//   2. IMPLICIT-`any` containment — the `no-unsafe-*` family. `no-explicit-any`
+//      (in the syntactic config) bans the literal `any` token, but it CANNOT see
+//      `any` that leaks in from an untyped boundary: `JSON.parse(s)`, `await
+//      res.json()`, an untyped dependency. `tsc --strict` propagates that `any`
+//      silently. These rules are the only thing that catches it — they make the
+//      generated-code gate enforce what tsforge already enforces on its OWN source
+//      via strictTypeChecked. Curated to the HIGH-SIGNAL, low-thrash subset;
+//      narrative rules (strict-boolean-expressions, no-unnecessary-condition,
+//      restrict-template-expressions) are deliberately left off until a sweep
+//      shows they don't thrash the local model.
 import tseslint from "typescript-eslint";
 
 export default tseslint.config(
@@ -19,6 +33,7 @@ export default tseslint.config(
       "@typescript-eslint": tseslint.plugin,
     },
     rules: {
+      // Async correctness.
       "@typescript-eslint/no-floating-promises": "error",
       "@typescript-eslint/no-misused-promises": [
         "error",
@@ -28,6 +43,24 @@ export default tseslint.config(
           },
         },
       ],
+      "@typescript-eslint/await-thenable": "error",
+
+      // Implicit-`any` containment: stop untyped boundary data from flowing
+      // through the program unchecked.
+      "@typescript-eslint/no-unsafe-assignment": "error",
+      "@typescript-eslint/no-unsafe-member-access": "error",
+      "@typescript-eslint/no-unsafe-call": "error",
+      "@typescript-eslint/no-unsafe-return": "error",
+      "@typescript-eslint/no-unsafe-argument": "error",
+
+      // Cheap, high-signal correctness rules that need type info.
+      "@typescript-eslint/no-for-in-array": "error",
+      "@typescript-eslint/no-base-to-string": "error",
+      "@typescript-eslint/restrict-plus-operands": "error",
+      "@typescript-eslint/switch-exhaustiveness-check": [
+        "error",
+        { considerDefaultExhaustiveForUnions: true },
+      ],
     },
   }
 );