@agjs/tsforge 0.3.4 → 0.5.0

package/src/meta-rules/context.ts

@@ -133,6 +133,55 @@ function collectWorkflowFiles(root: string): string[] {
   return out.sort();
 }
 
+/** True for a Dockerfile-shaped name: `Dockerfile`, `Dockerfile.<x>`, `<x>.Dockerfile`. */
+function isDockerfileName(entry: string): boolean {
+  return (
+    entry === "Dockerfile" ||
+    entry.startsWith("Dockerfile.") ||
+    entry.endsWith(".Dockerfile")
+  );
+}
+
+/** Dockerfiles at the root and one directory level down (e.g. docker/, apps/*). */
+function collectDockerfiles(root: string): string[] {
+  const out: string[] = [];
+
+  const scanDir = (dir: string, relBase: string): void => {
+    let entries: string[];
+
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (IGNORE_SEGMENTS.has(entry)) {
+        continue;
+      }
+
+      const full = join(dir, entry);
+      const rel = relBase === "" ? entry : join(relBase, entry);
+
+      try {
+        const stat = statSync(full);
+
+        if (stat.isFile() && isDockerfileName(entry)) {
+          out.push(rel);
+        } else if (stat.isDirectory() && relBase === "") {
+          scanDir(full, entry); // one level only
+        }
+      } catch {
+        // Skip unreadable entries
+      }
+    }
+  };
+
+  scanDir(root, "");
+
+  return out.sort();
+}
+
 /** Parse package.json, returning null on error. */
 function parsePackageJson(root: string): Record<string, unknown> | null {
   const pkgPath = join(root, "package.json");
@@ -196,6 +245,7 @@ export function buildMetaRuleContext(
     sourceFiles: collectSourceFiles(root),
     configFiles: collectConfigFiles(root),
     workflowFiles: collectWorkflowFiles(root),
+    dockerfiles: collectDockerfiles(root),
     activePacks,
     readFile,
   };

package/src/meta-rules/meta-rules.types.ts

@@ -10,7 +10,8 @@ export type MetaRuleCategory =
   | "source-text"
   | "testing"
   | "stack-layout"
-  | "ci";
+  | "ci"
+  | "container";
 
 /** A single rule violation (file, rule, message). */
 export interface IMetaRuleViolation {
@@ -30,6 +31,7 @@ export interface IMetaRuleContext {
   readonly sourceFiles: readonly string[]; // repo-relative .ts/.tsx
   readonly configFiles: readonly string[]; // tsconfig*, eslint*, package.json, *.config.*
   readonly workflowFiles: readonly string[]; // .github/workflows/*.yml|yaml
+  readonly dockerfiles: readonly string[]; // Dockerfile, Dockerfile.*, *.Dockerfile (root + 1 level)
   readonly activePacks: readonly string[]; // pack ids from stack detection
   readonly readFile: (relPath: string) => string | null; // cached, safe
 }

package/src/meta-rules/registry.ts

@@ -25,6 +25,11 @@ import { workflowPermissionsExplicitRule } from "./rules/ci/workflow-permissions
 import { workflowPermissionsLeastPrivilegeRule } from "./rules/ci/workflow-permissions-least-privilege";
 import { noPullRequestTargetUntrustedCheckoutRule } from "./rules/ci/no-pull-request-target-untrusted-checkout";
 import { noGithubContextInShellRule } from "./rules/ci/no-github-context-in-shell";
+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.
@@ -42,6 +47,7 @@ export const META_RULES: readonly IMetaRule[] = [
   dependencyOverridesRequireCommentRule,
   productionMustNotUseDrizzlePushRule,
   migrationsMustBeCheckedInRule,
+  noUndeclaredDependenciesRule,
 
   // Source text
   noEslintDisableCommentsRule,
@@ -66,4 +72,12 @@ export const META_RULES: readonly IMetaRule[] = [
   workflowPermissionsLeastPrivilegeRule,
   noPullRequestTargetUntrustedCheckoutRule,
   noGithubContextInShellRule,
+
+  // Container
+  dockerfileBaseImagePinnedRule,
+  dockerfileNonRootUserRule,
+  dockerfileNoSecretsInEnvArgRule,
+
+  // Structure (cross-file)
+  noCircularImportsRule,
 ];

package/src/meta-rules/rules/docker/dockerfile-base-image-pinned.ts

@@ -0,0 +1,73 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+import { dockerInstructionLines } from "./utils";
+
+/**
+ * Every `FROM` must pin its base image to an explicit, non-floating tag (or a
+ * digest). `latest` (or no tag) changes underneath you between builds with no
+ * diff — non-reproducible images and silent base-image drift.
+ */
+const FROM_PATTERN = /^(?<ref>\S+)(?:\s+[Aa][Ss]\s+(?<stage>\S+))?/u;
+
+/** The tag of an image ref, or null when untagged. Splits on the LAST `/` so a
+ *  registry host:port (which also contains `:`) is not mistaken for a tag. */
+function imageTag(ref: string): string | null {
+  const lastSlash = ref.lastIndexOf("/");
+  const finalSegment = lastSlash === -1 ? ref : ref.slice(lastSlash + 1);
+  const colon = finalSegment.indexOf(":");
+
+  return colon === -1 ? null : finalSegment.slice(colon + 1);
+}
+
+export const dockerfileBaseImagePinnedRule: IMetaRule = {
+  id: "dockerfile-base-image-pinned",
+  category: "container",
+  description:
+    "Dockerfile FROM instructions must pin an explicit non-latest tag (or a digest) so image builds are reproducible.",
+  severity: "error",
+  run(ctx) {
+    const violations: IMetaRuleViolation[] = [];
+    const stages = new Set<string>();
+
+    for (const line of dockerInstructionLines(ctx)) {
+      if (line.instruction !== "FROM") {
+        continue;
+      }
+
+      const match = FROM_PATTERN.exec(line.args);
+      const ref = match?.groups?.ref;
+      const stage = match?.groups?.stage;
+
+      if (stage !== undefined) {
+        stages.add(stage.toLowerCase());
+      }
+
+      if (ref === undefined) {
+        continue;
+      }
+
+      // Skip references to an earlier build stage and the empty `scratch` base.
+      if (stages.has(ref.toLowerCase()) || ref.toLowerCase() === "scratch") {
+        continue;
+      }
+
+      const pinnedByDigest = ref.includes("@sha256:");
+      const tag = imageTag(ref);
+
+      if (pinnedByDigest || (tag !== null && tag !== "latest")) {
+        continue;
+      }
+
+      const reason =
+        tag === "latest" ? "uses the floating `latest` tag" : "has no tag";
+
+      violations.push({
+        file: line.file,
+        ruleId: "dockerfile-base-image-pinned",
+        severity: "error",
+        message: `Line ${line.lineNo}: \`FROM ${ref}\` ${reason} — pin an explicit version (e.g. \`node:24.3.0-bookworm\`) or a \`@sha256:\` digest for reproducible builds.`,
+      });
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/docker/dockerfile-no-secrets-in-env-arg.ts

@@ -0,0 +1,67 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+import { dockerInstructionLines } from "./utils";
+
+/**
+ * Secrets must not be baked into the image via `ENV`/`ARG` literals — they
+ * persist in every image layer and `docker history`, readable by anyone who
+ * pulls the image. Inject them at runtime (`--env-file`, a secret manager, or
+ * BuildKit `--secret`) instead.
+ */
+const SECRET_NAME =
+  /(^|_)(KEY|TOKEN|SECRET|SECRETS|PASSWORD|PASSWD|CREDENTIAL|CREDENTIALS)(_|$)/u;
+
+/** The `NAME=value` (or `NAME value`) pairs declared on one ENV/ARG line. */
+function declaredName(args: string): string | null {
+  const eq = args.indexOf("=");
+  const name = eq === -1 ? args.split(/\s+/u)[0] : args.slice(0, eq);
+
+  return name === undefined || name.length === 0 ? null : name.trim();
+}
+
+/** True when the line actually assigns a value (vs. a bare build-time `ARG`). */
+function hasAssignedValue(instruction: string, args: string): boolean {
+  if (args.includes("=")) {
+    const value = args.slice(args.indexOf("=") + 1).trim();
+
+    return value.length > 0;
+  }
+
+  // `ENV NAME value` form assigns; bare `ARG NAME` does not.
+  return instruction === "ENV" && /\S+\s+\S/u.test(args);
+}
+
+export const dockerfileNoSecretsInEnvArgRule: IMetaRule = {
+  id: "dockerfile-no-secrets-in-env-arg",
+  category: "container",
+  description:
+    "Dockerfiles must not assign secret-looking ENV/ARG values (KEY/TOKEN/SECRET/PASSWORD) — they bake into image layers. Inject secrets at runtime.",
+  severity: "error",
+  run(ctx) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const line of dockerInstructionLines(ctx)) {
+      if (line.instruction !== "ENV" && line.instruction !== "ARG") {
+        continue;
+      }
+
+      const name = declaredName(line.args);
+
+      if (
+        name === null ||
+        !SECRET_NAME.test(name.toUpperCase()) ||
+        !hasAssignedValue(line.instruction, line.args)
+      ) {
+        continue;
+      }
+
+      violations.push({
+        file: line.file,
+        ruleId: "dockerfile-no-secrets-in-env-arg",
+        severity: "error",
+        message: `Line ${line.lineNo}: \`${line.instruction} ${name}=…\` bakes a secret into the image layers (visible in \`docker history\`). Inject it at runtime via \`--env-file\`/secret manager or a BuildKit \`--secret\` mount.`,
+      });
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/docker/dockerfile-non-root-user.ts

@@ -0,0 +1,58 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+import { dockerInstructionLines } from "./utils";
+
+/**
+ * A Dockerfile must drop privileges with a non-root `USER` instruction. Running
+ * the container process as root is the default and a standard container-escape
+ * amplifier; a single `USER app` (after install steps) closes it.
+ */
+const ROOT_USERS = new Set(["root", "0", "0:0"]);
+
+/** The user name/uid from a `USER` arg (`USER node` / `USER node:node`). */
+function userName(args: string): string {
+  return args.trim().toLowerCase();
+}
+
+export const dockerfileNonRootUserRule: IMetaRule = {
+  id: "dockerfile-non-root-user",
+  category: "container",
+  description:
+    "Dockerfiles must declare a non-root USER so the container process does not run as root.",
+  severity: "error",
+  run(ctx) {
+    const violations: IMetaRuleViolation[] = [];
+    const lines = dockerInstructionLines(ctx);
+    const byFile = new Map<string, boolean>();
+
+    // Seed every READABLE Dockerfile as "no non-root USER seen yet" (readFile is
+    // cached, so this does not re-hit disk).
+    for (const file of ctx.dockerfiles) {
+      if (ctx.readFile(file) !== null) {
+        byFile.set(file, false);
+      }
+    }
+
+    for (const line of lines) {
+      if (line.instruction !== "USER") {
+        continue;
+      }
+
+      if (!ROOT_USERS.has(userName(line.args))) {
+        byFile.set(line.file, true);
+      }
+    }
+
+    for (const [file, hasNonRoot] of byFile) {
+      if (!hasNonRoot) {
+        violations.push({
+          file,
+          ruleId: "dockerfile-non-root-user",
+          severity: "error",
+          message: `${file} never drops to a non-root USER — add \`USER <non-root>\` after the install steps so the container does not run as root.`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/docker/utils.ts

@@ -0,0 +1,58 @@
+import type { IMetaRuleContext } from "../../meta-rules.types";
+
+/** One meaningful Dockerfile instruction line (comments + blanks stripped). */
+export interface IDockerLine {
+  readonly file: string;
+  readonly lineNo: number; // 1-based
+  readonly instruction: string; // upper-cased keyword, e.g. "FROM"
+  readonly args: string; // everything after the keyword, trimmed
+  readonly raw: string;
+}
+
+const INSTRUCTION_PATTERN = /^\s*(?<keyword>[A-Za-z]+)\s+(?<args>.*\S)\s*$/u;
+
+/** Parse every Dockerfile in the context into instruction lines. Continuation
+ *  lines (`\` at EOL) and comments are skipped — good enough for the textual
+ *  hardening checks (base-image pin, USER, secret literals). */
+export function dockerInstructionLines(
+  ctx: Pick<IMetaRuleContext, "dockerfiles" | "readFile">
+): IDockerLine[] {
+  const out: IDockerLine[] = [];
+
+  for (const file of ctx.dockerfiles) {
+    const text = ctx.readFile(file);
+
+    if (text === null) {
+      continue;
+    }
+
+    const lines = text.split("\n");
+
+    for (let i = 0; i < lines.length; i += 1) {
+      const raw = lines[i] ?? "";
+      const trimmed = raw.trim();
+
+      if (trimmed.length === 0 || trimmed.startsWith("#")) {
+        continue;
+      }
+
+      const match = INSTRUCTION_PATTERN.exec(raw);
+      const keyword = match?.groups?.keyword;
+      const args = match?.groups?.args;
+
+      if (keyword === undefined || args === undefined) {
+        continue;
+      }
+
+      out.push({
+        file,
+        lineNo: i + 1,
+        instruction: keyword.toUpperCase(),
+        args: args.trim(),
+        raw,
+      });
+    }
+  }
+
+  return out;
+}

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