@cosmicdrift/kumiko-guards 0.374.0 → 0.378.0

package/src/pre-push.sh

@@ -24,13 +24,6 @@
 # Extension point: a tracked, executable scripts/pre-push-extra.sh runs
 # before the main check in every branch above, with KUMIKO_PUSH_REPO_ROOT
 # and KUMIKO_PUSH_PARENT_DIR available inline (never exported).
-#
-# Override: set PRE_PUSH_SKIP=1 to bypass (use sparingly).
-
-if [ "${PRE_PUSH_SKIP:-0}" = "1" ]; then
-  echo "[pre-push] PRE_PUSH_SKIP=1 — hook skipped"
-  exit 0
-fi
 
 # Git exports GIT_DIR & co. to hooks; nothing this hook starts may inherit them,
 # or a test's fixture git calls write into this repo.
@@ -142,7 +135,9 @@ fi
 # canonical sibling path instead of this worktree — checking the wrong
 # code. Run the worktree-local check only when scripts/check-wt.sh is
 # tracked and executable (untracked/symlink stubs must not hijack push).
-if [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ] \
+# A check-wt.sh that wraps this hook sets KUMIKO_CHECK_WT=1 so it is not re-entered.
+if [ "${KUMIKO_CHECK_WT:-0}" != "1" ] \
+   && [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ] \
    && git -C "$REPO_ROOT" ls-files --error-unmatch scripts/check-wt.sh >/dev/null 2>&1 \
    && [ -x "$REPO_ROOT/scripts/check-wt.sh" ]; then
   echo "[pre-push] worktree detected — worktree check (see scripts/check-wt.sh)…"
@@ -178,7 +173,7 @@ if [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ]
   echo "[pre-push] worktree without scripts/check-wt.sh — running this worktree's package.json scripts (typecheck, lint, test, test:dom) and guards (guards, checks, comment-lang)…"
   if ! has_package_script test; then
     echo "[pre-push] FATAL: worktree without a package.json \"test\" script — nothing to run, refusing push." >&2
-    echo "Add a \"test\" script to package.json, or set PRE_PUSH_SKIP=1 to bypass (use sparingly)." >&2
+    echo "Add a \"test\" script to package.json." >&2
     exit 1
   fi
   FAILED=""
@@ -218,7 +213,7 @@ else
   # "Script not found" — check it up front with a clear, actionable message.
   if ! has_package_script test; then
     echo "[pre-push] FATAL: standalone clone without a package.json \"test\" script — nothing to run, refusing push." >&2
-    echo "Add a \"test\" script to package.json, or set PRE_PUSH_SKIP=1 to bypass (use sparingly)." >&2
+    echo "Add a \"test\" script to package.json." >&2
     exit 1
   fi
   cd "$REPO_ROOT" && bun run test

package/src/repo-manifest/app-ports/index.ts

@@ -0,0 +1,13 @@
+export { listAppPorts } from "@cosmicdrift/kumiko-framework/config";
+export {
+  findPortCollisions,
+  type PortClaim,
+  type PortCollision,
+  type ScannedApp,
+  scanWorkspaceApps,
+} from "./port-registry.ts";
+export {
+  parseStaticAppConfig,
+  readStaticAppConfig,
+  type StaticAppConfig,
+} from "./static-app-config.ts";

package/src/repo-manifest/app-ports/port-registry.ts

@@ -0,0 +1,45 @@
+// Port registry across the apps of a workspace: every app declares its ports
+// in kumiko.config.ts, and two apps (or two roles of one app) must never claim
+// the same port, otherwise their local dev and E2E runs block each other.
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import {
+  APP_CONFIG_FILE,
+  type AppPortRole,
+  listAppPorts,
+} from "@cosmicdrift/kumiko-framework/config";
+import { readStaticAppConfig, type StaticAppConfig } from "./static-app-config.ts";
+
+export type ScannedApp = { readonly app: string; readonly config: StaticAppConfig };
+
+export type PortClaim = { readonly app: string; readonly role: AppPortRole };
+
+export type PortCollision = { readonly port: number; readonly claims: readonly PortClaim[] };
+
+/** Direct children of `root` with a kumiko.config.ts; worktrees and dot-dirs are skipped. */
+export function scanWorkspaceApps(root: string): readonly ScannedApp[] {
+  return readdirSync(root, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules",
+    )
+    .filter((entry) => existsSync(join(root, entry.name, APP_CONFIG_FILE)))
+    .map((entry) => ({ app: entry.name, config: readStaticAppConfig(join(root, entry.name)) }))
+    .sort((a, b) => a.app.localeCompare(b.app));
+}
+
+export function findPortCollisions(apps: readonly ScannedApp[]): readonly PortCollision[] {
+  const claimsByPort = new Map<number, PortClaim[]>();
+  for (const { app, config } of apps) {
+    if (config.kind !== "defined") continue;
+    for (const { role, port } of listAppPorts(config.ports)) {
+      const claims = claimsByPort.get(port) ?? [];
+      claims.push({ app, role });
+      claimsByPort.set(port, claims);
+    }
+  }
+  return [...claimsByPort.entries()]
+    .filter(([, claims]) => claims.length > 1)
+    .map(([port, claims]) => ({ port, claims }))
+    .sort((a, b) => a.port - b.port);
+}

package/src/repo-manifest/app-ports/static-app-config.ts

@@ -0,0 +1,121 @@
+// Reads the ports out of kumiko.config.ts without importing it: importing
+// would execute every feature module of the app, and the port registry scans
+// sibling apps whose dependencies may not even be installed.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  APP_CONFIG_FILE,
+  type AppInfraPorts,
+  type AppPorts,
+  findAppPortProblems,
+} from "@cosmicdrift/kumiko-framework/config";
+import { type Node, type ObjectLiteralExpression, Project, SyntaxKind } from "ts-morph";
+
+export type StaticAppConfig =
+  | { readonly kind: "missing" }
+  /** A config without defineAppConfig: the app has not adopted the standard yet. */
+  | { readonly kind: "legacy" }
+  | { readonly kind: "invalid"; readonly message: string }
+  | { readonly kind: "defined"; readonly ports: AppPorts };
+
+const INFRA_KEYS = [
+  "postgres",
+  "redis",
+  "meilisearch",
+  "s3",
+] as const satisfies readonly (keyof AppInfraPorts)[];
+
+type InfraKey = (typeof INFRA_KEYS)[number];
+
+function isInfraKey(name: string): name is InfraKey {
+  return INFRA_KEYS.some((key) => key === name);
+}
+
+class StaticConfigError extends Error {}
+
+function propertyName(node: Node): string | undefined {
+  if (node.isKind(SyntaxKind.PropertyAssignment)) return node.getName().replace(/^["']|["']$/g, "");
+  return undefined;
+}
+
+function objectProperty(object: ObjectLiteralExpression, name: string): Node | undefined {
+  for (const property of object.getProperties()) {
+    if (
+      property.isKind(SyntaxKind.SpreadAssignment) ||
+      property.isKind(SyntaxKind.ShorthandPropertyAssignment)
+    ) {
+      throw new StaticConfigError(
+        `${name}: spread and shorthand properties cannot be read statically`,
+      );
+    }
+    if (propertyName(property) === name && property.isKind(SyntaxKind.PropertyAssignment)) {
+      return property.getInitializerOrThrow();
+    }
+  }
+  return undefined;
+}
+
+function numericLiteral(node: Node | undefined, path: string): number {
+  if (node === undefined) throw new StaticConfigError(`${path} is missing`);
+  if (!node.isKind(SyntaxKind.NumericLiteral)) {
+    throw new StaticConfigError(
+      `${path} must be a number literal so tooling can read it, got "${node.getText()}"`,
+    );
+  }
+  return node.getLiteralValue();
+}
+
+function objectLiteral(node: Node | undefined, path: string): ObjectLiteralExpression {
+  if (node === undefined) throw new StaticConfigError(`${path} is missing`);
+  if (!node.isKind(SyntaxKind.ObjectLiteralExpression)) {
+    throw new StaticConfigError(`${path} must be an object literal, got "${node.getText()}"`);
+  }
+  return node;
+}
+
+function readInfraPorts(node: Node | undefined): AppInfraPorts | undefined {
+  if (node === undefined) return undefined;
+  const object = objectLiteral(node, "ports.infra");
+  const infra: Partial<Record<InfraKey, number>> = {};
+  for (const property of object.getProperties()) {
+    const name = propertyName(property);
+    if (name === undefined || !isInfraKey(name)) {
+      throw new StaticConfigError(
+        `ports.infra: unknown entry "${property.getText()}", expected ${INFRA_KEYS.join(", ")}`,
+      );
+    }
+    infra[name] = numericLiteral(objectProperty(object, name), `ports.infra.${name}`);
+  }
+  return infra;
+}
+
+export function parseStaticAppConfig(source: string): StaticAppConfig {
+  const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+  const file = project.createSourceFile(APP_CONFIG_FILE, source);
+  const call = file
+    .getDescendantsOfKind(SyntaxKind.CallExpression)
+    .find((candidate) => candidate.getExpression().getText() === "defineAppConfig");
+  if (call === undefined) return { kind: "legacy" };
+  try {
+    const config = objectLiteral(call.getArguments()[0], "defineAppConfig argument");
+    const ports = objectLiteral(objectProperty(config, "ports"), "ports");
+    const infra = readInfraPorts(objectProperty(ports, "infra"));
+    const parsed: AppPorts = {
+      dev: numericLiteral(objectProperty(ports, "dev"), "ports.dev"),
+      e2e: numericLiteral(objectProperty(ports, "e2e"), "ports.e2e"),
+      ...(infra === undefined ? {} : { infra }),
+    };
+    const problems = findAppPortProblems(parsed);
+    if (problems.length > 0) return { kind: "invalid", message: problems.join("; ") };
+    return { kind: "defined", ports: parsed };
+  } catch (error) {
+    if (error instanceof StaticConfigError) return { kind: "invalid", message: error.message };
+    throw error;
+  }
+}
+
+export function readStaticAppConfig(appRoot: string): StaticAppConfig {
+  const path = join(appRoot, APP_CONFIG_FILE);
+  if (!existsSync(path)) return { kind: "missing" };
+  return parseStaticAppConfig(readFileSync(path, "utf-8"));
+}

package/src/repo-manifest/index.ts

@@ -0,0 +1,262 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import * as z from "zod";
+
+export const REPO_MANIFEST_FILE = "kumiko.json";
+
+// "tooling" is a repo with no product code (infra, Pulumi, build tooling) — guards default to skipping it, see scan-scope.ts.
+export const repoKindSchema = z.enum(["framework", "library", "app", "tooling"]);
+export type RepoKind = z.infer<typeof repoKindSchema>;
+
+const DRIVE_LETTER_RE = /^[A-Za-z]:/;
+
+function isBlank(value: string): boolean {
+  return value.trim().length === 0;
+}
+
+function patternViolation(value: string): string | undefined {
+  if (isBlank(value)) return `must not be empty: "${value}"`;
+  if (value.includes("\0")) return `must not contain a NUL character: "${value}"`;
+  if (value.startsWith("/") || DRIVE_LETTER_RE.test(value)) {
+    return `must be relative to the repo root: "${value}"`;
+  }
+  if (value.includes("\\")) return `must use forward slashes, not backslashes: "${value}"`;
+  if (value.startsWith("!")) return `must not start with "!": "${value}"`;
+  if (value.split("/").some((segment) => segment === "..")) {
+    return `must not traverse outside the repo root: "${value}"`;
+  }
+  return undefined;
+}
+
+const pattern = z.string().superRefine((value, ctx) => {
+  const violation = patternViolation(value);
+  if (violation !== undefined) {
+    ctx.addIssue({ code: "custom", message: violation });
+  }
+});
+
+export const repoManifestSchema = z.strictObject({
+  kind: repoKindSchema,
+  sourceRoots: z.array(pattern).min(1),
+  testGlobs: z.array(pattern).min(1),
+  uiRoots: z.array(pattern).optional(),
+  excludes: z.array(pattern).optional(),
+});
+export type RepoManifest = z.infer<typeof repoManifestSchema>;
+
+export type RepoManifestSource = "file" | "derived";
+
+export type LoadedRepoManifest = {
+  readonly manifest: RepoManifest;
+  readonly source: RepoManifestSource;
+  readonly manifestPath: string;
+};
+
+export class RepoManifestError extends Error {
+  readonly manifestPath: string;
+
+  constructor(manifestPath: string, message: string) {
+    super(`${manifestPath}: ${message}`);
+    this.name = "RepoManifestError";
+    this.manifestPath = manifestPath;
+  }
+}
+
+export type LoadRepoManifestOptions = {
+  readonly warn?: (message: string) => void;
+};
+
+function isDirectory(path: string): boolean {
+  return existsSync(path) && statSync(path).isDirectory();
+}
+
+function isWithinRoot(candidateReal: string, rootReal: string): boolean {
+  return candidateReal === rootReal || candidateReal.startsWith(rootReal + sep);
+}
+
+const GLOB_METACHARACTER_RE = /[*?[\]{}]/;
+const GLOBSTAR_SEGMENT = "**";
+
+// Only `*` and `?` are matched exactly; any other metacharacter matches every entry, which can over-reject but never lets a symlink slip through.
+const UNSUPPORTED_GLOB_CHARACTER_RE = /[[\]{}]/;
+
+function segmentMatcher(segment: string): RegExp {
+  if (UNSUPPORTED_GLOB_CHARACTER_RE.test(segment)) return /^.*$/;
+  const source = [...segment]
+    .map((char) => {
+      if (char === "*") return "[^/]*";
+      if (char === "?") return "[^/]";
+      return char.replace(/[.+^$()|\\]/g, "\\$&");
+    })
+    .join("");
+  return new RegExp(`^${source}$`);
+}
+
+// Walks the pattern segment by segment: a symlink can escape before the full path exists on disk (e.g. "linked/src" whose target has no "src"), and a wildcard segment ("packages/*/src") can match a symlinked directory. Segments below a "**" are not walked, so a symlink inside such a tree is the glob consumer's responsibility.
+function assertSegmentsWithinRoot(
+  manifestPath: string,
+  rootReal: string,
+  pattern: string,
+  dirAbs: string,
+  segments: readonly string[],
+): void {
+  for (const [index, segment] of segments.entries()) {
+    // skip: segments below "**" are the glob consumer's responsibility (see above)
+    if (segment === GLOBSTAR_SEGMENT) return;
+    if (!GLOB_METACHARACTER_RE.test(segment)) {
+      dirAbs = join(dirAbs, segment);
+      // skip: a path that does not exist yet cannot be a symlink out of the root
+      if (!existsSync(dirAbs)) return;
+      if (!isWithinRoot(realpathSync(dirAbs), rootReal)) {
+        throw new RepoManifestError(manifestPath, `"${pattern}" resolves outside the repo root`);
+      }
+      continue;
+    }
+    const matcher = segmentMatcher(segment);
+    // skip: a wildcard below a non-directory matches nothing
+    if (!isDirectory(dirAbs)) return;
+    const rest = segments.slice(index + 1);
+    for (const entry of readdirSync(dirAbs)) {
+      if (!matcher.test(entry)) continue;
+      const entryAbs = join(dirAbs, entry);
+      if (!existsSync(entryAbs)) continue;
+      if (!isWithinRoot(realpathSync(entryAbs), rootReal)) {
+        throw new RepoManifestError(manifestPath, `"${pattern}" resolves outside the repo root`);
+      }
+      if (rest.length > 0 && isDirectory(entryAbs)) {
+        assertSegmentsWithinRoot(manifestPath, rootReal, pattern, entryAbs, rest);
+      }
+    }
+    // The wildcard branch recursed into the remaining segments itself.
+    break;
+  }
+}
+
+function assertPatternsResolveWithinRoot(
+  manifestPath: string,
+  rootAbs: string,
+  rootReal: string,
+  manifest: RepoManifest,
+): void {
+  const patterns = [
+    ...manifest.sourceRoots,
+    ...manifest.testGlobs,
+    ...(manifest.uiRoots ?? []),
+    ...(manifest.excludes ?? []),
+  ];
+  for (const value of patterns) {
+    assertSegmentsWithinRoot(manifestPath, rootReal, value, rootAbs, value.split("/"));
+  }
+}
+
+function loadManifestFile(
+  manifestPath: string,
+  rootAbs: string,
+  rootReal: string,
+): LoadedRepoManifest {
+  const manifestReal = realpathSync(manifestPath);
+  if (!isWithinRoot(manifestReal, rootReal)) {
+    throw new RepoManifestError(manifestPath, "resolves outside the repo root");
+  }
+
+  const raw = readFileSync(manifestPath, "utf8");
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new RepoManifestError(manifestPath, `invalid JSON — ${message}`);
+  }
+
+  const result = repoManifestSchema.safeParse(json);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map(
+        (issue) => `${issue.path.length > 0 ? issue.path.join(".") : "<root>"}: ${issue.message}`,
+      )
+      .join("; ");
+    throw new RepoManifestError(manifestPath, `invalid repo manifest — ${issues}`);
+  }
+
+  assertPatternsResolveWithinRoot(manifestPath, rootAbs, rootReal, result.data);
+
+  return { manifest: result.data, source: "file", manifestPath };
+}
+
+function hasPackagesSrcLayout(rootAbs: string): boolean {
+  const packagesDir = join(rootAbs, "packages");
+  if (!isDirectory(packagesDir)) return false;
+  return readdirSync(packagesDir, { withFileTypes: true }).some(
+    (entry) => entry.isDirectory() && isDirectory(join(packagesDir, entry.name, "src")),
+  );
+}
+
+type DerivedLayout = { readonly layout: string; readonly manifest: RepoManifest };
+
+function derivedLayoutFor(rootAbs: string): DerivedLayout | undefined {
+  if (hasPackagesSrcLayout(rootAbs)) {
+    return {
+      layout: "packages/*/src",
+      manifest: {
+        kind: "library",
+        sourceRoots: ["packages/*/src"],
+        testGlobs: ["packages/*/src/**/*.{test,integration}.{ts,tsx}"],
+      },
+    };
+  }
+  if (isDirectory(join(rootAbs, "src"))) {
+    return {
+      layout: "src",
+      manifest: {
+        kind: "app",
+        sourceRoots: ["src"],
+        testGlobs: ["src/**/*.{test,integration}.{ts,tsx}"],
+      },
+    };
+  }
+  return undefined;
+}
+
+function deriveManifest(
+  manifestPath: string,
+  rootAbs: string,
+  warn: (message: string) => void,
+): LoadedRepoManifest {
+  const derived = derivedLayoutFor(rootAbs);
+
+  if (!derived) {
+    throw new RepoManifestError(
+      manifestPath,
+      "not found and no packages/*/src or src/ layout to derive one from",
+    );
+  }
+
+  warn(
+    `${manifestPath} not found — derived "${derived.layout}" layout (kind "${derived.manifest.kind}"); ` +
+      "add a kumiko.json to declare the repo layout explicitly",
+  );
+
+  return { manifest: derived.manifest, source: "derived", manifestPath };
+}
+
+function defaultWarn(message: string): void {
+  console.warn(message);
+}
+
+export function loadRepoManifest(
+  root: string,
+  options: LoadRepoManifestOptions = {},
+): LoadedRepoManifest {
+  const rootAbs = resolve(root);
+  const manifestPath = join(rootAbs, REPO_MANIFEST_FILE);
+
+  if (!isDirectory(rootAbs)) {
+    throw new RepoManifestError(manifestPath, "repo root does not exist or is not a directory");
+  }
+
+  if (existsSync(manifestPath)) {
+    return loadManifestFile(manifestPath, rootAbs, realpathSync(rootAbs));
+  }
+
+  return deriveManifest(manifestPath, rootAbs, options.warn ?? defaultWarn);
+}

package/src/run-guards.ts

@@ -57,6 +57,7 @@ import { guard as tenantEscalation } from "./guard-tenant-escalation";
 import { guard as testTemplateDrift } from "./guard-test-template-drift";
 import { guard as testTimeouts } from "./guard-test-timeouts";
 import { guard as textFieldStance } from "./guard-text-field-stance";
+import { guard as unsafeAppendEvent } from "./guard-unsafe-append-event";
 import { guard as unsafeJsonParse } from "./guard-unsafe-json-parse";
 import { guard as writeHandlerQns } from "./guard-write-handler-qns";
 
@@ -101,6 +102,7 @@ export const GUARDS = [
   libTestCoverage,
   testTimeouts,
   testTemplateDrift,
+  unsafeAppendEvent,
 ];
 
 export const GUARD_FLAGS = [