@agjs/tsforge 0.1.0

package/src/meta-rules/context.ts

@@ -0,0 +1,195 @@
+import { join, extname } from "node:path";
+import { readdirSync, statSync, readFileSync } from "node:fs";
+import type { IMetaRuleContext } from "./meta-rules.types";
+
+/** Narrow `unknown` to a record without a type assertion. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Directories to skip during recursive file walks. */
+const IGNORE_SEGMENTS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  ".next",
+  ".turbo",
+  ".cache",
+  ".vite",
+  "coverage",
+]);
+
+/** Source files: .ts and .tsx under src/, tests/, scripts/. */
+function collectSourceFiles(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) {
+      const full = join(dir, entry);
+      const rel = join(relBase, entry);
+
+      // Skip ignored directories
+      if (IGNORE_SEGMENTS.has(entry)) {
+        continue;
+      }
+
+      try {
+        const stat = statSync(full);
+
+        if (stat.isDirectory()) {
+          scanDir(full, rel);
+        } else if (stat.isFile()) {
+          const ext = extname(entry);
+
+          if (ext === ".ts" || ext === ".tsx") {
+            out.push(rel);
+          }
+        }
+      } catch {
+        // Skip unreadable entries
+      }
+    }
+  };
+
+  for (const baseDir of ["src", "tests", "scripts"]) {
+    scanDir(join(root, baseDir), baseDir);
+  }
+
+  return out.sort();
+}
+
+/** Config files: tsconfig*, eslint*, package.json, *.config.* at root. */
+function collectConfigFiles(root: string): string[] {
+  const out: string[] = [];
+
+  try {
+    const entries = readdirSync(root);
+
+    for (const entry of entries) {
+      const full = join(root, entry);
+
+      try {
+        const stat = statSync(full);
+
+        if (!stat.isFile()) {
+          continue;
+        }
+
+        // Match tsconfig.*, eslint.*, package.json, *.config.*
+        if (
+          entry.startsWith("tsconfig") ||
+          entry.startsWith("eslint") ||
+          entry === "package.json" ||
+          entry.includes(".config.")
+        ) {
+          out.push(entry);
+        }
+      } catch {
+        // Skip unreadable entries
+      }
+    }
+  } catch {
+    // Root doesn't exist or is unreadable
+  }
+
+  return out.sort();
+}
+
+/** GitHub workflow files: .github/workflows/*.yml|yaml. */
+function collectWorkflowFiles(root: string): string[] {
+  const out: string[] = [];
+  const workflowDir = join(root, ".github", "workflows");
+
+  try {
+    const entries = readdirSync(workflowDir);
+
+    for (const entry of entries) {
+      const ext = extname(entry);
+
+      if (ext === ".yml" || ext === ".yaml") {
+        out.push(join(".github", "workflows", entry));
+      }
+    }
+  } catch {
+    // Workflows dir doesn't exist
+  }
+
+  return out.sort();
+}
+
+/** Parse package.json, returning null on error. */
+function parsePackageJson(root: string): Record<string, unknown> | null {
+  const pkgPath = join(root, "package.json");
+
+  try {
+    const stat = statSync(pkgPath);
+
+    if (!stat.isFile()) {
+      return null;
+    }
+
+    const text = readFileSync(pkgPath, "utf8");
+    const parsed: unknown = JSON.parse(text);
+
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the rule context: list source/config/workflow files, parse package.json,
+ * set up a cached file reader.
+ */
+export function buildMetaRuleContext(
+  root: string,
+  activePacks: readonly string[]
+): IMetaRuleContext {
+  const fileCache = new Map<string, string | null>();
+
+  const readFile = (relPath: string): string | null => {
+    if (fileCache.has(relPath)) {
+      return fileCache.get(relPath) ?? null;
+    }
+
+    try {
+      const full = join(root, relPath);
+      const stat = statSync(full);
+
+      if (!stat.isFile()) {
+        fileCache.set(relPath, null);
+
+        return null;
+      }
+
+      const text = readFileSync(full, "utf8");
+
+      fileCache.set(relPath, text);
+
+      return text;
+    } catch {
+      fileCache.set(relPath, null);
+
+      return null;
+    }
+  };
+
+  return {
+    root,
+    packageJson: parsePackageJson(root),
+    sourceFiles: collectSourceFiles(root),
+    configFiles: collectConfigFiles(root),
+    workflowFiles: collectWorkflowFiles(root),
+    activePacks,
+    readFile,
+  };
+}

package/src/meta-rules/index.ts

@@ -0,0 +1,9 @@
+export type {
+  IMetaRule,
+  IMetaRuleContext,
+  IMetaRuleViolation,
+  MetaRuleCategory,
+} from "./meta-rules.types";
+export { buildMetaRuleContext } from "./context";
+export { runMetaRules } from "./runner";
+export { META_RULES } from "./registry";

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

@@ -0,0 +1,47 @@
+/**
+ * Meta-rules: project structure & config guardrails that ESLint cannot express.
+ * Categories align with risk domains: supply-chain (deps), config (tsconfig/eslint),
+ * source-text (inline suppressions), testing (coverage), stack-layout (dirs),
+ * and ci (workflows).
+ */
+export type MetaRuleCategory =
+  | "supply-chain"
+  | "config"
+  | "source-text"
+  | "testing"
+  | "stack-layout"
+  | "ci";
+
+/** A single rule violation (file, rule, message). */
+export interface IMetaRuleViolation {
+  readonly file: string; // repo-relative path
+  readonly ruleId: string;
+  readonly severity: "error" | "warn";
+  readonly message: string;
+}
+
+/**
+ * Context for a rule run: the project root, parsed package.json, file lists,
+ * active packs from stack detection, and a cached file reader.
+ */
+export interface IMetaRuleContext {
+  readonly root: string;
+  readonly packageJson: Record<string, unknown> | null;
+  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 activePacks: readonly string[]; // pack ids from stack detection
+  readonly readFile: (relPath: string) => string | null; // cached, safe
+}
+
+/** A single meta-rule that checks project invariants. */
+export interface IMetaRule {
+  readonly id: string;
+  readonly category: MetaRuleCategory;
+  readonly description: string;
+  /** Pack IDs this rule applies to; undefined = always applies. */
+  readonly appliesTo?: readonly string[];
+  readonly severity: "error" | "warn";
+  /** Synchronous rule run. */
+  readonly run: (ctx: IMetaRuleContext) => IMetaRuleViolation[];
+}

package/src/meta-rules/parsers/package-json-parser.ts

@@ -0,0 +1,51 @@
+export interface IPackageJsonDeps {
+  readonly dependencies?: Record<string, string>;
+  readonly devDependencies?: Record<string, string>;
+}
+
+/** Narrow `unknown` to a record without a type assertion. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Extract string-valued dependency map from a package.json object. */
+function toStringRecord(value: unknown): Record<string, string> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const out: Record<string, string> = {};
+
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === "string") {
+      out[key] = entry;
+    }
+  }
+
+  return out;
+}
+
+/** Parse package.json JSON object, returning null on error. */
+export function parsePackageJsonObject(
+  parsed: unknown
+): IPackageJsonDeps | null {
+  if (!isRecord(parsed)) {
+    return null;
+  }
+
+  let dependencies: Record<string, string> | undefined;
+  let devDependencies: Record<string, string> | undefined;
+
+  const depsValue = parsed.dependencies;
+  const devDepsValue = parsed.devDependencies;
+
+  if (depsValue !== undefined) {
+    dependencies = toStringRecord(depsValue);
+  }
+
+  if (devDepsValue !== undefined) {
+    devDependencies = toStringRecord(devDepsValue);
+  }
+
+  return { dependencies, devDependencies };
+}

package/src/meta-rules/registry.ts

@@ -0,0 +1,37 @@
+import type { IMetaRule } from "./meta-rules.types";
+import { packageExactDepsRule } from "./rules/supply-chain/package-exact-deps";
+import { noOverlappingLibsRule } from "./rules/supply-chain/no-overlapping-libs";
+import { noEslintDisableCommentsRule } from "./rules/source-text/no-eslint-disable-comments";
+import { noTsSuppressionRule } from "./rules/source-text/no-ts-suppressions";
+import { tsconfigPathsExistRule } from "./rules/config/tsconfig-paths-exist";
+import { tsconfigStrictRule } from "./rules/config/tsconfig-strict";
+import { testSiblingRequiredRule } from "./rules/testing/test-sibling-required";
+import { workflowActionsPinnedRule } from "./rules/ci/workflow-actions-pinned";
+import { workflowRunnerPinnedRule } from "./rules/ci/workflow-runner-pinned";
+import { workflowTimeoutRequiredRule } from "./rules/ci/workflow-timeout-required";
+
+/**
+ * All available meta-rules, ordered by category for readability.
+ * Apply-filtering (appliesTo) happens in the runner per context.
+ */
+export const META_RULES: readonly IMetaRule[] = [
+  // Supply chain
+  packageExactDepsRule,
+  noOverlappingLibsRule,
+
+  // Source text
+  noEslintDisableCommentsRule,
+  noTsSuppressionRule,
+
+  // Config
+  tsconfigPathsExistRule,
+  tsconfigStrictRule,
+
+  // Testing
+  testSiblingRequiredRule,
+
+  // CI
+  workflowActionsPinnedRule,
+  workflowRunnerPinnedRule,
+  workflowTimeoutRequiredRule,
+];

package/src/meta-rules/rules/ci/workflow-actions-pinned.ts

@@ -0,0 +1,59 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+/**
+ * GitHub Actions `uses:` directive must pin to either:
+ * - A full SHA (e.g. uses: actions/checkout@a1b2c3d...)
+ * - A version tag (e.g. uses: actions/checkout@v3)
+ *
+ * Floating refs (e.g. uses: actions/checkout@main) are not allowed.
+ */
+const USES_PATTERN = /uses:\s*(.+?)(?:\s*#.*)?$/u;
+const VALID_PIN_PATTERN = /^[\w./-]+@(?:[a-f0-9]{40}|v?\d+(?:\.\d+)*)$/u;
+
+export const workflowActionsPinnedRule: IMetaRule = {
+  id: "workflow-actions-pinned",
+  category: "ci",
+  description:
+    "GitHub Actions `uses:` directives must pin to a version tag (v1, v2, etc.) or full SHA, not floating refs like @main.",
+  severity: "warn",
+  run({ workflowFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const file of workflowFiles) {
+      const text = readFile(file);
+
+      if (text === null) {
+        continue;
+      }
+
+      const lines = text.split("\n");
+
+      for (const line of lines) {
+        const match = USES_PATTERN.exec(line);
+
+        if (match?.[1] === undefined) {
+          continue;
+        }
+
+        const usesValue = match[1].trim().replace(/['"]/gu, "");
+
+        // Skip composite actions and local actions (./...)
+        if (usesValue.startsWith("./")) {
+          continue;
+        }
+
+        // Check if pinned to version or SHA
+        if (!VALID_PIN_PATTERN.test(usesValue)) {
+          violations.push({
+            file,
+            ruleId: "workflow-actions-pinned",
+            severity: "warn",
+            message: `Action \`${usesValue}\` is not pinned to a version tag or SHA — pin to a stable release (e.g. @v3) or full commit SHA.`,
+          });
+        }
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/ci/workflow-runner-pinned.ts

@@ -0,0 +1,57 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+/**
+ * GitHub runner images should pin to an explicit OS version (e.g. ubuntu-24.04)
+ * instead of floating tags (ubuntu-latest). Floating tags can change between
+ * runs with no repo diff, causing non-deterministic CI behavior.
+ */
+const RUNS_ON_PATTERN = /^\s*runs-on:\s*(?<label>\S+)\s*(?:#.*)?$/u;
+
+export const workflowRunnerPinnedRule: IMetaRule = {
+  id: "workflow-runner-pinned",
+  category: "ci",
+  description:
+    "Workflows must pin runner images to an explicit OS version (e.g. ubuntu-24.04) instead of floating *-latest labels.",
+  severity: "warn",
+  run({ workflowFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const file of workflowFiles) {
+      const text = readFile(file);
+
+      if (text === null) {
+        continue;
+      }
+
+      const lines = text.split("\n");
+
+      for (const line of lines) {
+        const match = RUNS_ON_PATTERN.exec(line);
+        const label = match?.groups?.label;
+
+        if (label === undefined) {
+          continue;
+        }
+
+        // Skip matrix variables (start with $)
+        if (label.startsWith("$")) {
+          continue;
+        }
+
+        // Check if the label ends with -latest (floating)
+        const normalized = label.replace(/['"]/gu, "");
+
+        if (normalized.endsWith("-latest")) {
+          violations.push({
+            file,
+            ruleId: "workflow-runner-pinned",
+            severity: "warn",
+            message: `runs-on: ${normalized} floats with GitHub's runner image migrations — tool versions change between runs with no repo diff. Pin an explicit OS version (e.g. ubuntu-24.04).`,
+          });
+        }
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/ci/workflow-timeout-required.ts

@@ -0,0 +1,114 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+/**
+ * GitHub Actions jobs should declare a timeout-minutes so a hung step fails fast
+ * instead of occupying a runner for GitHub's 6-hour default.
+ * Reusable workflow calls (job uses: ...) are exempt since they set timeouts internally.
+ */
+const JOB_KEY_PATTERN = /^ {2}([\w-]+):\s*(?:#.*)?$/u;
+
+interface IJobBlock {
+  readonly name: string;
+  readonly lines: readonly string[];
+}
+
+function collectJobBlocks(text: string): IJobBlock[] {
+  const lines = text.split("\n");
+  const blocks: IJobBlock[] = [];
+  let inJobs = false;
+  let current: { name: string; lines: string[] } | null = null;
+
+  for (const line of lines) {
+    // Start of jobs: section
+    if (/^jobs:\s*(?:#.*)?$/u.test(line)) {
+      inJobs = true;
+      continue;
+    }
+
+    if (!inJobs) {
+      continue;
+    }
+
+    // End of jobs: section (top-level key)
+    if (/^\S/u.test(line)) {
+      inJobs = false;
+
+      if (current !== null) {
+        blocks.push(current);
+        current = null;
+      }
+
+      continue;
+    }
+
+    // Job definition line
+    const jobMatch = JOB_KEY_PATTERN.exec(line);
+
+    if (jobMatch?.[1] !== undefined) {
+      if (current !== null) {
+        blocks.push(current);
+      }
+
+      current = { name: jobMatch[1], lines: [] };
+      continue;
+    }
+
+    if (current !== null) {
+      current.lines.push(line);
+    }
+  }
+
+  if (current !== null) {
+    blocks.push(current);
+  }
+
+  return blocks;
+}
+
+export const workflowTimeoutRequiredRule: IMetaRule = {
+  id: "workflow-timeout-required",
+  category: "ci",
+  description:
+    "GitHub Actions jobs require an explicit timeout-minutes (reusable-workflow calls exempt).",
+  severity: "warn",
+  run({ workflowFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const file of workflowFiles) {
+      const text = readFile(file);
+
+      if (text === null) {
+        continue;
+      }
+
+      const jobs = collectJobBlocks(text);
+
+      for (const job of jobs) {
+        // Check if this is a reusable workflow call
+        const isReusableCall = job.lines.some((line) =>
+          /^ {4}uses:\s*\S/u.test(line)
+        );
+
+        if (isReusableCall) {
+          continue;
+        }
+
+        // Check for timeout-minutes
+        const hasTimeout = job.lines.some((line) =>
+          /^ {4}timeout-minutes:\s*[1-9]\d*\s*(?:#.*)?$/u.test(line)
+        );
+
+        if (!hasTimeout) {
+          violations.push({
+            file,
+            ruleId: "workflow-timeout-required",
+            severity: "warn",
+            message: `Job "${job.name}" has no job-level \`timeout-minutes:\` — a hung step runs for GitHub's 6h default and blocks the PR check.`,
+          });
+        }
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/config/tsconfig-paths-exist.ts

@@ -0,0 +1,117 @@
+import { join, dirname } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+/** Narrow `unknown` to a record without a type assertion. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+const GLOB_CHARS_REGEX = /[*?{}]/u;
+
+/** Strip block and line comments from JSON before parsing. */
+function stripJsonComments(text: string): string {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//gu, "")
+    .replace(/^\s*\/\/.*$/gmu, "")
+    .replace(/,\s*([\]}])/gu, "$1");
+}
+
+/**
+ * Extract literal (non-glob) entries from tsconfig include/files that should
+ * point to real files on disk.
+ */
+function readLiteralEntries(tsconfigPath: string): string[] {
+  let parsed: unknown;
+
+  try {
+    const text = readFileSync(tsconfigPath, "utf8");
+
+    parsed = JSON.parse(stripJsonComments(text));
+  } catch {
+    return [];
+  }
+
+  if (!isRecord(parsed)) {
+    return [];
+  }
+
+  const entries: string[] = [];
+  const candidates: unknown[] = [];
+
+  if ("include" in parsed) {
+    const includeValue = parsed.include;
+
+    if (Array.isArray(includeValue)) {
+      candidates.push(includeValue);
+    }
+  }
+
+  if ("files" in parsed) {
+    const filesValue = parsed.files;
+
+    if (Array.isArray(filesValue)) {
+      candidates.push(filesValue);
+    }
+  }
+
+  for (const candidate of candidates) {
+    if (!Array.isArray(candidate)) {
+      continue;
+    }
+
+    for (const item of candidate) {
+      if (typeof item !== "string" || GLOB_CHARS_REGEX.test(item)) {
+        continue;
+      }
+
+      // Skip entries under hidden dirs (.astro/types.d.ts) — build-generated
+      const normalized = item.replace(/^\.\//u, "");
+
+      if (normalized.startsWith(".")) {
+        continue;
+      }
+
+      entries.push(item);
+    }
+  }
+
+  return entries;
+}
+
+export const tsconfigPathsExistRule: IMetaRule = {
+  id: "tsconfig-paths-exist",
+  category: "config",
+  description:
+    "Literal tsconfig include/files entries must point to files that exist on disk (glob patterns exempt).",
+  severity: "error",
+  run({ root }) {
+    const violations: IMetaRuleViolation[] = [];
+    const tsconfigPath = join(root, "tsconfig.json");
+
+    // Check if tsconfig.json exists
+    try {
+      statSync(tsconfigPath);
+    } catch {
+      return violations;
+    }
+
+    const entries = readLiteralEntries(tsconfigPath);
+    const baseDir = dirname(tsconfigPath);
+
+    for (const entry of entries) {
+      const fullPath = join(baseDir, entry);
+
+      if (!existsSync(fullPath)) {
+        violations.push({
+          file: "tsconfig.json",
+          ruleId: "tsconfig-paths-exist",
+          severity: "error",
+          message: `include/files entry \`${entry}\` does not exist on disk — stale config references misdocument the project shape (globs are exempt).`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};