@agjs/tsforge 0.1.0

package/src/meta-rules/rules/config/tsconfig-strict.ts

@@ -0,0 +1,91 @@
+import { join } from "node:path";
+import { 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;
+}
+
+/** 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");
+}
+
+/**
+ * Check if tsconfig has strict: true or all individual strict flags enabled.
+ */
+function isStrictEnabled(parsed: unknown): boolean {
+  if (!isRecord(parsed)) {
+    return false;
+  }
+
+  const compilerOptions = parsed.compilerOptions;
+
+  if (!isRecord(compilerOptions)) {
+    return false;
+  }
+
+  // If strict: true is set, all strict flags are implicitly enabled
+  if (compilerOptions.strict === true) {
+    return true;
+  }
+
+  // Otherwise, check individual strict flags
+  const strictFlags = [
+    "alwaysStrict",
+    "strictBindCallApply",
+    "strictFunctionTypes",
+    "strictNullChecks",
+    "strictPropertyInitialization",
+    "noImplicitAny",
+    "noImplicitThis",
+    "useUnknownInCatchVariables",
+  ];
+
+  return strictFlags.every((flag) => {
+    const flagValue = compilerOptions[flag];
+
+    return flagValue === true;
+  });
+}
+
+export const tsconfigStrictRule: IMetaRule = {
+  id: "tsconfig-strict",
+  category: "config",
+  description:
+    "tsconfig.json should enable strict mode for type safety (strict: true or all individual strict flags).",
+  severity: "warn",
+  run({ root }) {
+    const violations: IMetaRuleViolation[] = [];
+    const tsconfigPath = join(root, "tsconfig.json");
+
+    try {
+      statSync(tsconfigPath);
+    } catch {
+      return violations;
+    }
+
+    try {
+      const text = readFileSync(tsconfigPath, "utf8");
+      const parsed: unknown = JSON.parse(stripJsonComments(text));
+
+      if (!isStrictEnabled(parsed)) {
+        violations.push({
+          file: "tsconfig.json",
+          ruleId: "tsconfig-strict",
+          severity: "warn",
+          message:
+            'tsconfig.json should enable strict mode via "strict": true in compilerOptions for full type safety.',
+        });
+      }
+    } catch {
+      // Invalid JSON or file read error — skip this check
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/source-text/no-eslint-disable-comments.ts

@@ -0,0 +1,34 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+const ESLINT_DISABLE_PATTERN = /\beslint-disable(?:-next-line|-line)?\b/u;
+
+export const noEslintDisableCommentsRule: IMetaRule = {
+  id: "no-eslint-disable-comments",
+  category: "source-text",
+  description:
+    "Source files must not contain inline eslint-disable directives.",
+  severity: "error",
+  run({ sourceFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const file of sourceFiles) {
+      const text = readFile(file);
+
+      if (text === null) {
+        continue;
+      }
+
+      if (ESLINT_DISABLE_PATTERN.test(text)) {
+        violations.push({
+          file,
+          ruleId: "no-eslint-disable-comments",
+          severity: "error",
+          message:
+            "Inline ESLint disables are not allowed. Fix the rule or add a scoped config override.",
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/source-text/no-ts-suppressions.ts

@@ -0,0 +1,38 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+const TS_SUPPRESS_PATTERN = /@ts-(?:ignore|nocheck|expect-error)/u;
+
+/**
+ * TypeScript suppression comments (@ts-ignore, @ts-nocheck, @ts-expect-error)
+ * are not allowed without a trailing justification comment.
+ */
+export const noTsSuppressionRule: IMetaRule = {
+  id: "no-ts-suppressions",
+  category: "source-text",
+  description:
+    "TypeScript suppression comments (@ts-ignore, @ts-nocheck, @ts-expect-error) are not allowed.",
+  severity: "error",
+  run({ sourceFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const file of sourceFiles) {
+      const text = readFile(file);
+
+      if (text === null) {
+        continue;
+      }
+
+      if (TS_SUPPRESS_PATTERN.test(text)) {
+        violations.push({
+          file,
+          ruleId: "no-ts-suppressions",
+          severity: "error",
+          message:
+            "TypeScript suppression comments are not allowed. Narrow the type instead.",
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/supply-chain/no-overlapping-libs.ts

@@ -0,0 +1,57 @@
+import { parsePackageJsonObject } from "../../parsers/package-json-parser";
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+/**
+ * Library pairs that should not coexist in the same project.
+ * Each pair is [lib1, lib2] (order-insensitive).
+ */
+const FORBID_DEP_PAIRS: readonly (readonly [string, string])[] = [
+  // Overlapping HTTP clients
+  ["axios", "node-fetch"],
+  // Overlapping toast/notification libraries
+  ["react-hot-toast", "sonner"],
+  // Overlapping date libraries
+  ["dayjs", "date-fns"],
+  ["moment", "dayjs"],
+  // Overlapping utility libraries
+  ["lodash", "ramda"],
+];
+
+export const noOverlappingLibsRule: IMetaRule = {
+  id: "no-overlapping-libs",
+  category: "supply-chain",
+  description:
+    "package.json must not list forbidden overlapping library pairs (e.g. axios + node-fetch).",
+  severity: "warn",
+  run({ packageJson }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    if (packageJson === null) {
+      return violations;
+    }
+
+    const parsed = parsePackageJsonObject(packageJson);
+
+    if (parsed === null) {
+      return violations;
+    }
+
+    const merged: Record<string, string> = {
+      ...(parsed.dependencies ?? {}),
+      ...(parsed.devDependencies ?? {}),
+    };
+
+    for (const [firstLib, secondLib] of FORBID_DEP_PAIRS) {
+      if (merged[firstLib] !== undefined && merged[secondLib] !== undefined) {
+        violations.push({
+          file: "package.json",
+          ruleId: "no-overlapping-libs",
+          severity: "warn",
+          message: `Both "${firstLib}" and "${secondLib}" are listed — pick one (forbidden overlapping library stacks).`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/supply-chain/package-exact-deps.ts

@@ -0,0 +1,55 @@
+import { parsePackageJsonObject } from "../../parsers/package-json-parser";
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+const NON_EXACT_DEP_PATTERN = /(^[~^])|([<>=*xX])|(\s)|(\|\|)/u;
+
+/**
+ * Check that dependencies and devDependencies use exact versions (no ^, ~, ranges).
+ * peerDependencies are allowed to use ranges.
+ */
+export const packageExactDepsRule: IMetaRule = {
+  id: "package-exact-deps",
+  category: "supply-chain",
+  description:
+    "dependencies and devDependencies must use exact versions (no ^ or ~ ranges).",
+  severity: "warn",
+  run({ packageJson }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    if (packageJson === null) {
+      return violations;
+    }
+
+    const parsed = parsePackageJsonObject(packageJson);
+
+    if (parsed === null) {
+      return violations;
+    }
+
+    const sections = [
+      ["dependencies", parsed.dependencies],
+      ["devDependencies", parsed.devDependencies],
+    ] as const;
+
+    for (const [section, entries] of sections) {
+      if (entries === undefined) {
+        continue;
+      }
+
+      for (const [name, spec] of Object.entries(entries)) {
+        if (!NON_EXACT_DEP_PATTERN.test(spec)) {
+          continue;
+        }
+
+        violations.push({
+          file: "package.json",
+          ruleId: "package-exact-deps",
+          severity: "warn",
+          message: `${section}.${name} is "${spec}" — dependencies and devDependencies must be exact versions; only peerDependencies should use ranges.`,
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/testing/test-sibling-required.ts

@@ -0,0 +1,110 @@
+import { join } from "node:path";
+import { statSync } from "node:fs";
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+/**
+ * File suffixes that indicate logic files requiring tests.
+ */
+const LOGIC_FILE_SUFFIXES = /\.(service|utils|helpers|handler)\.ts$/u;
+
+/**
+ * Directories that are logic-heavy by definition.
+ */
+const LOGIC_DIRS = new Set(["lib"]);
+
+/**
+ * Check if a source file looks like a logic module that should have a test.
+ * Excludes test files, type-only modules, and barrel exports.
+ */
+function isLogicFile(file: string): boolean {
+  // Exclude existing test files
+  if (file.includes(".test.ts") || file.includes(".spec.ts")) {
+    return false;
+  }
+
+  // Exclude barrel exports and type-only modules
+  if (file.endsWith("/index.ts") || file.endsWith(".types.ts")) {
+    return false;
+  }
+
+  // Check for logic file suffix
+  if (LOGIC_FILE_SUFFIXES.test(file)) {
+    return true;
+  }
+
+  // Check if in a logic directory
+  for (const logicDir of LOGIC_DIRS) {
+    if (
+      file.includes(`/lib/${logicDir}/`) ||
+      file.includes(`\\lib\\${logicDir}\\`)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export const testSiblingRequiredRule: IMetaRule = {
+  id: "test-sibling-required",
+  category: "testing",
+  description:
+    "Logic modules (*.service.ts, *.utils.ts, etc.) should have a co-located *.test.ts sibling.",
+  severity: "warn",
+  run({ root, sourceFiles }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const file of sourceFiles) {
+      if (!isLogicFile(file)) {
+        continue;
+      }
+
+      // Expected test location: src/foo/bar.ts → tests/foo/bar.test.ts
+      const normalized = file.replace(/\\/g, "/");
+
+      let expectedTest: string;
+
+      if (normalized.startsWith("src/")) {
+        const relativePath = normalized.slice(4); // Remove "src/"
+
+        expectedTest = join(
+          root,
+          "tests",
+          relativePath.replace(/\.ts$/, ".test.ts")
+        );
+      } else if (normalized.startsWith("scripts/")) {
+        const relativePath = normalized.slice(8); // Remove "scripts/"
+
+        expectedTest = join(
+          root,
+          "tests",
+          "scripts",
+          relativePath.replace(/\.ts$/, ".test.ts")
+        );
+      } else {
+        continue; // Unrecognized directory
+      }
+
+      try {
+        const stat = statSync(expectedTest);
+
+        if (stat.isFile()) {
+          continue; // Test exists
+        }
+      } catch {
+        // Test does not exist
+      }
+
+      const relativeExpectedTest = expectedTest.slice(root.length + 1);
+
+      violations.push({
+        file,
+        ruleId: "test-sibling-required",
+        severity: "warn",
+        message: `Missing unit-test sibling. Expected \`${relativeExpectedTest}\` to exist alongside this logic module.`,
+      });
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/runner.ts

@@ -0,0 +1,64 @@
+import type {
+  IMetaRule,
+  IMetaRuleContext,
+  IMetaRuleViolation,
+} from "./meta-rules.types";
+
+/**
+ * Run applicable meta-rules and return violations sorted deterministically
+ * (by file, then rule ID). Severity overrides can silence rules ("off") or
+ * change their severity (rule ID mapped to "error" | "warn" | "off").
+ */
+export function runMetaRules(
+  rules: readonly IMetaRule[],
+  ctx: IMetaRuleContext,
+  severityOverrides?: Readonly<Record<string, "error" | "warn" | "off">>
+): IMetaRuleViolation[] {
+  const violations: IMetaRuleViolation[] = [];
+
+  for (const rule of rules) {
+    // Check if rule is silenced via overrides
+    if (severityOverrides?.[rule.id] === "off") {
+      continue;
+    }
+
+    // Check if rule applies to this project's active packs
+    if (rule.appliesTo !== undefined && rule.appliesTo.length > 0) {
+      const applies = rule.appliesTo.some((pack) =>
+        ctx.activePacks.includes(pack)
+      );
+
+      if (!applies) {
+        continue;
+      }
+    }
+
+    const ruleViolations = rule.run(ctx);
+    const override = severityOverrides?.[rule.id];
+
+    // Apply severity override if present (and not "off")
+    if (override !== undefined && override !== "off") {
+      for (const v of ruleViolations) {
+        violations.push({
+          ...v,
+          severity: override,
+        });
+      }
+    } else {
+      violations.push(...ruleViolations);
+    }
+  }
+
+  // Deterministic ordering: file path, then rule ID
+  violations.sort((a, b) => {
+    const fileCmp = a.file.localeCompare(b.file);
+
+    if (fileCmp !== 0) {
+      return fileCmp;
+    }
+
+    return a.ruleId.localeCompare(b.ruleId);
+  });
+
+  return violations;
+}

package/src/models-config.ts

@@ -0,0 +1,196 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
+import { isRecord } from "./lib/guards";
+import { PROVIDER_DEFAULTS } from "./inference/inference.constants";
+
+/**
+ * The model registry — `~/.tsforge/models.json`, the central place a user
+ * configures N model endpoints and switches between them with `/model`. Mirrors
+ * the sessions/logs layout (under `$TSFORGE_HOME` if set, else the home dir).
+ * Loading is read-only and falls back to the built-in local-qwen default when no
+ * file exists, so behaviour is identical to the env-driven path until the user
+ * writes a registry.
+ */
+export interface IModelEntry {
+  /** Root of the OpenAI-compatible API, e.g. https://api.deepseek.com/v1 */
+  baseUrl: string;
+  /** Model id sent in the request, e.g. deepseek-reasoner */
+  model: string;
+  /** Inline API key. Prefer `apiKeyEnv` so the secret stays out of the file. */
+  apiKey?: string;
+  /** Name of an env var holding the key — resolved at use time. Used when
+   *  `apiKey` is unset, so the registry can be shared/committed without secrets. */
+  apiKeyEnv?: string;
+  /** Context window (tokens) for the status line + auto-compaction. */
+  contextWindow?: number;
+  /** Default thinking mode for this model. */
+  thinking?: boolean;
+  /** Per-response token cap override. */
+  maxTokens?: number;
+}
+
+export interface IModelsConfig {
+  /** Name of the active entry — always a key of `models`. */
+  active: string;
+  models: Record<string, IModelEntry>;
+}
+
+/** The built-in local-qwen entry — matches PROVIDER_DEFAULTS so an absent
+ *  registry behaves exactly like the current env-default path. */
+const QWEN_LOCAL: IModelEntry = {
+  baseUrl: PROVIDER_DEFAULTS.baseUrl,
+  model: PROVIDER_DEFAULTS.model,
+  thinking: true,
+};
+
+/** The default registry used when no models.json exists yet. */
+export function defaultModelsConfig(): IModelsConfig {
+  return { active: "qwen-local", models: { "qwen-local": QWEN_LOCAL } };
+}
+
+/** The registry path: `$TSFORGE_HOME`/.tsforge/models.json, else under home. */
+export function modelsConfigPath(): string {
+  return join(process.env.TSFORGE_HOME ?? homedir(), ".tsforge", "models.json");
+}
+
+function isModelEntry(value: unknown): value is IModelEntry {
+  return (
+    isRecord(value) &&
+    typeof value.baseUrl === "string" &&
+    typeof value.model === "string"
+  );
+}
+
+/** Validate a parsed object into a registry, with actionable errors — the file is
+ *  hand-edited, so a clear message beats a silent fallback. */
+export function parseModelsConfig(raw: unknown): IModelsConfig {
+  if (
+    !isRecord(raw) ||
+    typeof raw.active !== "string" ||
+    !isRecord(raw.models)
+  ) {
+    throw new Error(
+      "models.json: expected { active: string, models: { <name>: { baseUrl, model } } }"
+    );
+  }
+
+  const models: Record<string, IModelEntry> = {};
+
+  for (const [name, entry] of Object.entries(raw.models)) {
+    if (!isModelEntry(entry)) {
+      throw new Error(
+        `models.json: model "${name}" needs at least { baseUrl, model }`
+      );
+    }
+
+    models[name] = entry;
+  }
+
+  if (models[raw.active] === undefined) {
+    throw new Error(
+      `models.json: active "${raw.active}" is not one of: ${Object.keys(models).join(", ")}`
+    );
+  }
+
+  return { active: raw.active, models };
+}
+
+/** Read the registry (read-only). Missing file → the built-in default (no write);
+ *  malformed file/JSON → a clear error naming the path. */
+export async function loadModelsConfig(): Promise<IModelsConfig> {
+  let text: string;
+
+  try {
+    text = await readFile(modelsConfigPath(), "utf8");
+  } catch {
+    return defaultModelsConfig();
+  }
+
+  let raw: unknown;
+
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    throw new Error(`models.json: invalid JSON at ${modelsConfigPath()}`);
+  }
+
+  return parseModelsConfig(raw);
+}
+
+/** Write the registry: dir 0700, file 0600 (it may hold an inline key). */
+export async function saveModelsConfig(cfg: IModelsConfig): Promise<void> {
+  const dir = join(process.env.TSFORGE_HOME ?? homedir(), ".tsforge");
+
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const path = modelsConfigPath();
+
+  await writeFile(path, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+/** Switch the active model and persist. Throws (listing the options) on an
+ *  unknown name so `/model <typo>` gets a helpful message, not a silent no-op. */
+export async function setActiveModel(name: string): Promise<IModelsConfig> {
+  const cfg = await loadModelsConfig();
+
+  if (cfg.models[name] === undefined) {
+    throw new Error(
+      `unknown model "${name}" — configured: ${Object.keys(cfg.models).join(", ")}`
+    );
+  }
+
+  const next: IModelsConfig = { active: name, models: cfg.models };
+
+  await saveModelsConfig(next);
+
+  return next;
+}
+
+/** The API key for an entry: inline `apiKey` wins, else the env var named by
+ *  `apiKeyEnv`. Undefined when neither is set (local endpoints need none). */
+export function resolveApiKey(entry: IModelEntry): string | undefined {
+  if (entry.apiKey !== undefined && entry.apiKey.length > 0) {
+    return entry.apiKey;
+  }
+
+  if (entry.apiKeyEnv !== undefined) {
+    return process.env[entry.apiKeyEnv];
+  }
+
+  return undefined;
+}
+
+/** An ad-hoc entry built from TSFORGE_* env, or undefined when none are set.
+ *  Explicit env is the escape hatch that overrides the registry on startup. */
+export function envModelEntry(): IModelEntry | undefined {
+  const baseUrl = process.env.TSFORGE_BASE_URL;
+  const model = process.env.TSFORGE_MODEL;
+
+  if (baseUrl === undefined && model === undefined) {
+    return undefined;
+  }
+
+  return {
+    baseUrl: baseUrl ?? PROVIDER_DEFAULTS.baseUrl,
+    model: model ?? PROVIDER_DEFAULTS.model,
+    apiKey: process.env.TSFORGE_API_KEY,
+  };
+}
+
+/** Resolve the model to use NOW: explicit TSFORGE_* env wins (escape hatch),
+ *  else the registry's active entry. Returns the display name + the entry. */
+export async function resolveActiveModel(): Promise<{
+  name: string;
+  entry: IModelEntry;
+}> {
+  const env = envModelEntry();
+
+  if (env !== undefined) {
+    return { name: "env", entry: env };
+  }
+
+  const cfg = await loadModelsConfig();
+
+  return { name: cfg.active, entry: cfg.models[cfg.active] ?? QWEN_LOCAL };
+}