@fantastic.dev/repo-gates 0.2.1-bootstrap.0

package/dist/config.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Per-repo policy for @fantastic.dev/repo-gates.
+ *
+ * The engine is repo-agnostic; everything that varies between repos lives
+ * here. A consumer repo drops a partial `repo-gates.config.json` at its
+ * root; anything it omits falls back to {@link DEFAULT_CONFIG} (tuned for
+ * a pnpm + turbo + vitest monorepo). The loader always resolves policy
+ * relative to the *consumer* repo root (default `process.cwd()`), never
+ * the package's own location — that is the whole point of extracting this
+ * into a package.
+ */
+type GateSpec = {
+    /** The package.json script name, e.g. "typecheck" or "check:size". */
+    name: string;
+    /** Conditional gates run only when the consumer's package.json defines
+     *  them; non-conditional gates in the selected manifest run even when the
+     *  consumer does not define a matching script, so a missing required gate
+     *  fails loudly. Consumers that replace the default manifest own that
+     *  policy (for example, a coverage-backed test gate may replace `test`). */
+    conditional: boolean;
+};
+type RepoGatesConfig = {
+    /** How a gate script is invoked, e.g. "pnpm run" or "bun run". */
+    runner: string;
+    /** Ordered gate manifest — cheap gates first, the CI-parity meta-gate last. */
+    gates: GateSpec[];
+    /** Roots the file-size and debt-marker guards walk. */
+    scanRoots: string[];
+    /** Directory names pruned during scans (matched as a path segment). */
+    excludeDirSegments: string[];
+    /** Repo-relative posix path prefixes excluded from scans. */
+    excludePathPrefixes: string[];
+    /** Extensions the size/debt guards treat as source. */
+    sourceExtensions: string[];
+    fileSize: {
+        /** Default per-file line ceiling for files without an explicit budget. */
+        threshold: number;
+        /** Repo-relative path to the grandfathered per-file budgets JSON. */
+        budgetsPath: string;
+    };
+    debt: {
+        /** Repo-relative path to the grandfathered untracked-marker allowlist. */
+        allowlistPath: string;
+        /** Marker tokens that require a tracker reference on the same line. */
+        markerTokens: string[];
+        /** Source strings for the RegExps that count as a "tracker reference". */
+        trackerPatterns: string[];
+    };
+    circular: {
+        /** Repo-relative path to the grandfathered circular-import allowlist. */
+        allowlistPath: string;
+    };
+    secrets: {
+        /** Repo-relative path to the grandfathered secret-finding allowlist. */
+        allowlistPath: string;
+        /** Source strings for the RegExps matched against every git-tracked
+         *  line (well-known credential shapes — AWS/GitHub/Slack/Stripe/npm/
+         *  Google API keys, PEM private-key headers). Findings are reported as
+         *  a redacted fingerprint, never the matched text. */
+        patterns: string[];
+        /** File extensions (with the dot) skipped as binary/non-text. */
+        binaryExtensions: string[];
+    };
+    coverage: {
+        /** Repo-relative path to the coverage floor JSON. */
+        budgetsPath: string;
+        /** Globs (repo-relative) matching each package's vitest
+         *  `coverage-summary.json`. */
+        summaryGlobs: string[];
+    };
+    ciParity: {
+        /** Repo-relative path to the parity escape-hatch config. */
+        configPath: string;
+        /** The root gate every CI invocation must be reachable from. */
+        rootGate: string;
+        /** Entry points seeded into the reachability walk alongside the gates. */
+        entryGates: string[];
+        /** Only workflow files whose basename starts with this are gate workflows. */
+        workflowPrefix: string;
+    };
+    bundleSize: {
+        /** Repo-relative path to the bundle-size budgets JSON. */
+        budgetsPath: string;
+        /** Build+measure targets. Empty → the gate is a no-op (nothing to measure). */
+        targets: {
+            /** Budget key + display name, e.g. "web". */
+            name: string;
+            /** turbo `--filter` selector to build before measuring, e.g. "@x/web". */
+            filter: string;
+            /** Repo-relative dir of built assets to scan (hashed filenames ok). */
+            distDir: string;
+            /** Bucket name → file extensions, e.g. { "js": [".js"], "css": [".css"] }. */
+            buckets: Record<string, string[]>;
+        }[];
+    };
+    report: {
+        /** Globs matching per-package junit XML (report:test-timing). Empty ⇒ no-op. */
+        junitGlobs: string[];
+        /** How many slowest tests to list. */
+        topN: number;
+    };
+    agents: {
+        /** Repo-relative agent-doc files to validate (e.g. ["AGENTS.md"]). Empty ⇒ no-op. */
+        targets: string[];
+        /** Backticked paths in the docs that intentionally don't exist on disk
+         *  (generated artifacts, runtime files, illustrative names). */
+        knownMissingPaths: string[];
+        /** Package-manager command whose script invocations are validated (e.g. "pnpm"). */
+        runnerCommand: string;
+        /** Subcommands of runnerCommand that are builtins, not scripts (ignored). */
+        ignoredSubcommands: string[];
+    };
+    docsCoverage: {
+        /** Globs (repo-relative) a PR must touch for a triggered surface to
+         *  count as documented. Empty `surfaces` ⇒ the gate is a no-op. */
+        docsGlobs: string[];
+        /** User-facing surfaces that require docs when changed. */
+        surfaces: {
+            /** Human-readable label shown in the failure/notice output. */
+            label: string;
+            /** Glob matched against the PR's changed-file paths. */
+            glob: string;
+            /** "added" — only a brand-new file triggers; "changed" — added,
+             *  modified, renamed, or copied all trigger. */
+            on: "added" | "changed";
+        }[];
+        /** Globs removed from BOTH surface and docs matching (tests, fixtures). */
+        exclude: string[];
+    };
+};
+declare const DEFAULT_CONFIG: RepoGatesConfig;
+declare const CONFIG_FILENAMES: readonly ["repo-gates.config.json"];
+type Ctx = {
+    repoRoot: string;
+    config: RepoGatesConfig;
+};
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/** One-level-deep merge: overlay's top-level object sections are merged
+ *  key-by-key over the base; scalars and arrays replace wholesale. */
+declare function mergeConfig(base: RepoGatesConfig, overlay: DeepPartial<RepoGatesConfig>): RepoGatesConfig;
+declare function findConfigFile(repoRoot: string): string | undefined;
+declare function loadConfig(repoRoot?: string): RepoGatesConfig;
+declare function loadContext(repoRoot?: string): Ctx;
+
+export { CONFIG_FILENAMES, type Ctx, DEFAULT_CONFIG, type GateSpec, type RepoGatesConfig, findConfigFile, loadConfig, loadContext, mergeConfig };

package/dist/config.js

@@ -0,0 +1,178 @@
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+var DEFAULT_CONFIG = {
+  runner: "pnpm run",
+  gates: [
+    { name: "lint", conditional: false },
+    { name: "check:design-system", conditional: true },
+    { name: "format:check", conditional: false },
+    { name: "typecheck", conditional: false },
+    { name: "check:scripts", conditional: true },
+    { name: "check:deps", conditional: true },
+    { name: "check:dups", conditional: true },
+    { name: "check:size", conditional: false },
+    { name: "check:debt", conditional: false },
+    { name: "check:circular", conditional: true },
+    { name: "check:secrets", conditional: true },
+    { name: "check:agents", conditional: true },
+    { name: "check:shadscan", conditional: true },
+    { name: "check:docs-coverage", conditional: true },
+    { name: "check:bundle-size", conditional: true },
+    { name: "test", conditional: false },
+    { name: "check:coverage", conditional: true },
+    { name: "check:ci-parity", conditional: false }
+  ],
+  scanRoots: ["apps", "packages", "scripts"],
+  excludeDirSegments: [
+    "node_modules",
+    "dist",
+    "dist-e2e",
+    "out",
+    ".turbo",
+    ".wrangler",
+    "__golden__",
+    "_generated",
+    "coverage"
+  ],
+  excludePathPrefixes: [],
+  sourceExtensions: [".ts", ".tsx"],
+  fileSize: { threshold: 600, budgetsPath: "gates/file-size-budgets.json" },
+  debt: {
+    allowlistPath: "gates/debt-marker-allowlist.json",
+    markerTokens: ["TODO", "FIXME", "HACK", "XXX"],
+    trackerPatterns: ["\\b[A-Z]{2,}-\\d+\\b", "#\\d+\\b", "https?:\\/\\/\\S+"]
+  },
+  circular: { allowlistPath: "gates/circular-imports-allowlist.json" },
+  secrets: {
+    allowlistPath: "gates/secrets-allowlist.json",
+    patterns: [
+      "\\bAKIA[0-9A-Z]{16}\\b",
+      // AWS access key
+      "\\bASIA[0-9A-Z]{16}\\b",
+      // AWS temporary access key
+      "\\bgh[pousr]_[A-Za-z0-9]{36,}\\b",
+      // GitHub personal/OAuth/app/refresh token
+      "\\bxox[baprs]-[A-Za-z0-9-]{10,}\\b",
+      // Slack token
+      "\\bsk_(?:live|test)_[A-Za-z0-9]{16,}\\b",
+      // Stripe secret key
+      "\\bnpm_[A-Za-z0-9]{36}\\b",
+      // npm access token
+      "\\bAIza[0-9A-Za-z_-]{35}\\b",
+      // Google API key
+      "-----BEGIN(?: RSA| EC| OPENSSH| DSA)? PRIVATE KEY-----",
+      // PEM private key
+      "://[^/\\s:@]+:[^/\\s:@]+@"
+      // credentials embedded in a URL
+    ],
+    binaryExtensions: [
+      ".png",
+      ".jpg",
+      ".jpeg",
+      ".gif",
+      ".ico",
+      ".webp",
+      ".pdf",
+      ".zip",
+      ".gz",
+      ".woff",
+      ".woff2",
+      ".ttf",
+      ".eot",
+      ".mp4",
+      ".mp3",
+      ".wasm"
+    ]
+  },
+  coverage: {
+    budgetsPath: "gates/coverage-budgets.json",
+    summaryGlobs: [
+      "apps/*/coverage/coverage-summary.json",
+      "packages/*/coverage/coverage-summary.json"
+    ]
+  },
+  ciParity: {
+    configPath: "gates/ci-parity-config.json",
+    rootGate: "check:all",
+    entryGates: ["check:all", "verify"],
+    workflowPrefix: "ci"
+  },
+  bundleSize: { budgetsPath: "gates/bundle-size-budgets.json", targets: [] },
+  report: { junitGlobs: [], topN: 20 },
+  agents: {
+    targets: [],
+    knownMissingPaths: [],
+    runnerCommand: "pnpm",
+    ignoredSubcommands: [
+      "run",
+      "install",
+      "i",
+      "add",
+      "remove",
+      "rm",
+      "up",
+      "update",
+      "exec",
+      "dlx",
+      "why",
+      "store",
+      "prune",
+      "audit",
+      "outdated",
+      "list",
+      "ls",
+      "link",
+      "unlink",
+      "publish",
+      "pack",
+      "rebuild",
+      "approve-builds",
+      "config",
+      "dedupe",
+      "fetch",
+      "import",
+      "patch",
+      "setup",
+      "create"
+    ]
+  },
+  docsCoverage: { docsGlobs: [], surfaces: [], exclude: [] }
+};
+var CONFIG_FILENAMES = ["repo-gates.config.json"];
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function mergeConfig(base, overlay) {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    if (value === void 0) continue;
+    const baseValue = base[key];
+    out[key] = isPlainObject(baseValue) && isPlainObject(value) ? { ...baseValue, ...value } : value;
+  }
+  return out;
+}
+function findConfigFile(repoRoot) {
+  for (const name of CONFIG_FILENAMES) {
+    const candidate = resolve(repoRoot, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return void 0;
+}
+function loadConfig(repoRoot = process.cwd()) {
+  const file = findConfigFile(repoRoot);
+  if (!file) return DEFAULT_CONFIG;
+  const overlay = JSON.parse(readFileSync(file, "utf8"));
+  return mergeConfig(DEFAULT_CONFIG, overlay);
+}
+function loadContext(repoRoot = process.cwd()) {
+  return { repoRoot, config: loadConfig(repoRoot) };
+}
+export {
+  CONFIG_FILENAMES,
+  DEFAULT_CONFIG,
+  findConfigFile,
+  loadConfig,
+  loadContext,
+  mergeConfig
+};

package/dist/design-system.d.ts

@@ -0,0 +1,17 @@
+/** Shared policy for consumer ESLint and Oxlint configs. No linter runtime dependency. */
+declare const designSystemRules: {
+    readonly "shadcn/no-restyle": readonly ["error", {
+        readonly allow: readonly ["layout"];
+    }];
+    readonly "shadcn/no-raw-colors": "error";
+    readonly "shadcn/no-arbitrary-values": "error";
+    readonly "shadcn/no-inline-styles": "error";
+    readonly "shadcn/no-unknown-classes": "error";
+    readonly "shadcn/require-static-classes": "error";
+};
+/** Component implementations may define their own styling. Other checks still apply. */
+declare const componentDefinitionRules: {
+    readonly "shadcn/no-restyle": "off";
+};
+
+export { componentDefinitionRules, designSystemRules };

package/dist/design-system.js

@@ -0,0 +1,14 @@
+// src/design-system.ts
+var designSystemRules = {
+  "shadcn/no-restyle": ["error", { allow: ["layout"] }],
+  "shadcn/no-raw-colors": "error",
+  "shadcn/no-arbitrary-values": "error",
+  "shadcn/no-inline-styles": "error",
+  "shadcn/no-unknown-classes": "error",
+  "shadcn/require-static-classes": "error"
+};
+var componentDefinitionRules = { "shadcn/no-restyle": "off" };
+export {
+  componentDefinitionRules,
+  designSystemRules
+};

package/dist/eslint-boundaries.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Import-boundary → ESLint flat-config generator (repo-agnostic).
+ *
+ * The *rules* (which import specifiers are forbidden in which files) are
+ * DATA the consumer supplies from its own `repo-gates.config.json`; this
+ * module only shapes that data into `@typescript-eslint/no-restricted-imports`
+ * flat-config entries. repo-gates never learns any repo's specific packages.
+ *
+ * IMPORTANT — ESLint flat config does NOT merge rule options across matching
+ * configs; the LAST matching config wins outright. So a file must get ALL its
+ * forbidden patterns from a SINGLE config. Hence each boundary is ONE file
+ * scope carrying a LIST of pattern groups (each with its own `allowTypeImports`
+ * / message). When scopes nest (e.g. `apps/x/renderer/**` ⊂ `apps/x/**`), the
+ * narrower boundary must carry the broader patterns too. Rather than copy-paste
+ * them, give it `extends: ["<broader-boundary>"]` — this module merges the named
+ * boundaries' patterns in ahead of its own, so each rule is authored ONCE.
+ */
+type BoundaryPattern = {
+    /** Forbidden import-specifier glob patterns (minimatch on the specifier). */
+    forbid: string[];
+    /** Allow `import type { … }` through (blocks only value imports). */
+    allowTypeImports?: boolean;
+    /** Custom violation message for this group. */
+    message?: string;
+};
+type Boundary = {
+    /** Stable id, surfaced in the ESLint config name. */
+    name: string;
+    /** File globs the rule applies to (ESLint `files`). */
+    files: string[];
+    /** File globs excluded from this boundary (ESLint `ignores`) — e.g. test
+     *  files, which run in Node and may touch anything for setup. */
+    ignores?: string[];
+    /** One or more forbidden-pattern groups applied to those files. */
+    patterns: BoundaryPattern[];
+    /** Names of other boundaries whose `patterns` are merged in ahead of this
+     *  boundary's own. Lets a nested scope inherit a broader scope's rules
+     *  without copy-pasting them (only `patterns` are inherited, never `files`). */
+    extends?: string[];
+};
+type BoundaryEslintConfig = {
+    name: string;
+    files: string[];
+    ignores?: string[];
+    rules: Record<string, unknown>;
+};
+declare function boundariesToEslintConfigs(boundaries: Boundary[]): BoundaryEslintConfig[];
+
+export { type Boundary, type BoundaryEslintConfig, type BoundaryPattern, boundariesToEslintConfigs };

package/dist/eslint-boundaries.js

@@ -0,0 +1,40 @@
+// src/eslint-boundaries.ts
+function resolvePatterns(b, byName, seen) {
+  if (seen.has(b.name)) {
+    throw new Error(
+      `repo-gates boundaries: circular \`extends\` involving "${b.name}" (${[...seen, b.name].join(" \u2192 ")}).`
+    );
+  }
+  const inherited = [];
+  for (const parentName of b.extends ?? []) {
+    const parent = byName.get(parentName);
+    if (!parent) {
+      throw new Error(`repo-gates boundary "${b.name}" extends unknown boundary "${parentName}".`);
+    }
+    inherited.push(...resolvePatterns(parent, byName, /* @__PURE__ */ new Set([...seen, b.name])));
+  }
+  return [...inherited, ...b.patterns];
+}
+function boundariesToEslintConfigs(boundaries) {
+  const byName = new Map(boundaries.map((b) => [b.name, b]));
+  return boundaries.map((b) => ({
+    name: `repo-gates/boundary/${b.name}`,
+    files: b.files,
+    ...b.ignores ? { ignores: b.ignores } : {},
+    rules: {
+      "@typescript-eslint/no-restricted-imports": [
+        "error",
+        {
+          patterns: resolvePatterns(b, byName, /* @__PURE__ */ new Set()).map((p) => ({
+            group: p.forbid,
+            allowTypeImports: p.allowTypeImports ?? false,
+            message: p.message ?? `Import boundary "${b.name}" violated.`
+          }))
+        }
+      ]
+    }
+  }));
+}
+export {
+  boundariesToEslintConfigs
+};