@agjs/tsforge 0.4.0 → 0.5.0

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 },
+      ],
     },
   }
 );