@cosmicdrift/kumiko-guards 0.374.0 → 0.377.0

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 = [