@jskit-ai/kernel 0.1.4

package/shared/validators/resourceRequiredMetadata.test.js

@@ -0,0 +1,49 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Type } from "typebox";
+import {
+  normalizeRequiredFieldList,
+  deriveRequiredFieldsFromSchema,
+  deriveResourceRequiredMetadata
+} from "./resourceRequiredMetadata.js";
+
+test("normalizeRequiredFieldList trims, dedupes, and drops empty entries", () => {
+  assert.deepEqual(
+    normalizeRequiredFieldList([" name ", "color", "name", "", null]),
+    ["name", "color"]
+  );
+  assert.deepEqual(normalizeRequiredFieldList(undefined), []);
+});
+
+test("deriveRequiredFieldsFromSchema reads schema.required", () => {
+  const schema = Type.Object({
+    name: Type.String(),
+    color: Type.String(),
+    optionalField: Type.Optional(Type.String())
+  });
+
+  assert.deepEqual(deriveRequiredFieldsFromSchema(schema), ["name", "color"]);
+  assert.deepEqual(deriveRequiredFieldsFromSchema(Type.Partial(schema)), []);
+});
+
+test("deriveResourceRequiredMetadata reads create/replace/patch operation body schemas", () => {
+  const fullSchema = Type.Object({
+    name: Type.String(),
+    color: Type.String(),
+    invitesEnabled: Type.Boolean()
+  });
+  const patchSchema = Type.Partial(fullSchema);
+  const resource = {
+    operations: {
+      create: { bodyValidator: { schema: fullSchema } },
+      replace: { bodyValidator: { schema: fullSchema } },
+      patch: { bodyValidator: { schema: patchSchema } }
+    }
+  };
+
+  assert.deepEqual(deriveResourceRequiredMetadata(resource), {
+    create: ["name", "color", "invitesEnabled"],
+    replace: ["name", "color", "invitesEnabled"],
+    patch: []
+  });
+});

package/test/barrelExposure.test.js

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+
+const BARREL_EXPECTATIONS = Object.freeze([
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "server", "runtime", "index.js"),
+    expectedExports: Object.freeze([
+      "AppError",
+      "createValidationError",
+      "installServiceRegistrationApi",
+      "parsePositiveInteger",
+      "requireAuth",
+      "resolveServiceRegistrations",
+      "registerDomainEventListener",
+      "registerBootstrapPayloadContributor"
+    ])
+  }),
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "shared", "support", "index.js"),
+    expectedExports: Object.freeze([
+      "appendQueryString",
+      "formatDateTime",
+      "hasPermission",
+      "isRecord",
+      "isTransientQueryError",
+      "normalizePermissionList",
+      "normalizeReturnToPath",
+      "pickOwnProperties",
+      "resolveAllowedOriginsFromPlacementContext",
+      "shouldRetryTransientQueryFailure",
+      "transientQueryRetryDelay"
+    ])
+  }),
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "shared", "actions", "index.js"),
+    expectedExports: Object.freeze([
+      "normalizeActionDefinition",
+      "withActionDefaults"
+    ])
+  }),
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "client", "index.js"),
+    expectedExports: Object.freeze([
+      "bootstrapClientShellApp",
+      "createComponentInteractionEmitter",
+      "createShellRouter",
+      "getClientAppConfig",
+      "resolveClientBootstrapDebugEnabled"
+    ])
+  }),
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "shared", "index.js"),
+    expectedExports: Object.freeze([
+      "normalizePathname",
+      "resolveLinkPath"
+    ])
+  }),
+  Object.freeze({
+    filePath: path.join(REPO_ROOT, "packages", "kernel", "server", "http", "index.js"),
+    expectedExports: Object.freeze([
+      "registerRouteVisibilityResolver"
+    ])
+  })
+]);
+
+function collectBarrelNamedExports(filePath) {
+  const source = fs.readFileSync(filePath, "utf8");
+  const exportMatches = [...source.matchAll(/export\s*\{([\s\S]*?)\}\s*from\s*["'][^"']+["']/g)];
+  const names = [];
+
+  for (const match of exportMatches) {
+    const body = String(match[1] || "");
+    for (const item of body.split(",")) {
+      const entry = String(item || "").trim();
+      if (!entry) {
+        continue;
+      }
+
+      const alias = entry.split(/\sas\s/i).pop().trim();
+      if (!alias) {
+        continue;
+      }
+      names.push(alias);
+    }
+  }
+
+  return [...new Set(names)].sort((left, right) => left.localeCompare(right));
+}
+
+test("kernel barrel exports stay intentionally minimal", () => {
+  for (const expectation of BARREL_EXPECTATIONS) {
+    const observed = collectBarrelNamedExports(expectation.filePath);
+    const expected = [...expectation.expectedExports].sort((left, right) => left.localeCompare(right));
+    assert.deepEqual(
+      observed,
+      expected,
+      `Unexpected barrel exports in ${path.relative(REPO_ROOT, expectation.filePath)}`
+    );
+  }
+});

package/test/dynamicImportPolicy.test.js

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const KERNEL_ROOT = path.resolve(TEST_DIRECTORY, "..");
+const SCANNED_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx"]);
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".git", "dist", "coverage"]);
+const NON_DETERMINISTIC_IMPORT_PATTERN = /(Date\.now\s*\(|Math\.random\s*\()/;
+
+function normalizeSlash(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function shouldScanFile(filePath) {
+  return SCANNED_EXTENSIONS.has(path.extname(filePath));
+}
+
+function walkFiles(directoryPath) {
+  const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (IGNORED_DIRECTORIES.has(entry.name)) {
+      continue;
+    }
+
+    const absolutePath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkFiles(absolutePath));
+      continue;
+    }
+
+    if (entry.isFile() && shouldScanFile(absolutePath)) {
+      files.push(absolutePath);
+    }
+  }
+
+  return files;
+}
+
+function resolveLineNumberFromIndex(source, index) {
+  if (index <= 0) {
+    return 1;
+  }
+  return source.slice(0, index).split(/\r?\n/).length;
+}
+
+function resolveImportStatementSlice(source, importStartIndex) {
+  const semicolonIndex = source.indexOf(";", importStartIndex);
+  if (semicolonIndex === -1) {
+    return source.slice(importStartIndex, importStartIndex + 400);
+  }
+  return source.slice(importStartIndex, semicolonIndex + 1);
+}
+
+function collectNonDeterministicDynamicImportViolations() {
+  const kernelFiles = walkFiles(KERNEL_ROOT);
+  const violations = [];
+
+  for (const filePath of kernelFiles) {
+    const source = fs.readFileSync(filePath, "utf8");
+    const relativePath = normalizeSlash(path.relative(KERNEL_ROOT, filePath));
+    const dynamicImportPattern = /\bimport\s*\(/g;
+    let match = null;
+
+    while ((match = dynamicImportPattern.exec(source))) {
+      const importStartIndex = match.index;
+      const importStatement = resolveImportStatementSlice(source, importStartIndex);
+      if (!NON_DETERMINISTIC_IMPORT_PATTERN.test(importStatement)) {
+        continue;
+      }
+      violations.push(`${relativePath}:${resolveLineNumberFromIndex(source, importStartIndex)}`);
+    }
+  }
+
+  return violations.sort();
+}
+
+test("kernel dynamic imports do not use Date.now or Math.random cache busting", () => {
+  const violations = collectNonDeterministicDynamicImportViolations();
+  assert.deepEqual(
+    violations,
+    [],
+    `Kernel dynamic imports must be deterministic. Remove Date.now/Math.random from: ${violations.join(", ")}`
+  );
+});

package/test/exportsContract.test.js

@@ -0,0 +1,168 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+const KERNEL_PACKAGE_JSON_PATH = path.join(
+  REPO_ROOT,
+  "packages",
+  "kernel",
+  "package.json"
+);
+const SCAN_ROOTS = [
+  path.join(REPO_ROOT, "packages"),
+  path.join(REPO_ROOT, "tooling", "create-app", "templates")
+];
+const SCANNED_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".vue"]);
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".git", "dist", "coverage"]);
+const EXCLUDED_USAGE_PATH_SEGMENTS = new Set(["test", "tests", "__tests__", "test-support"]);
+const TEST_FILENAME_PATTERN = /\.(test|spec)\.[A-Za-z0-9]+$/;
+const EXPORTED_UNUSED_ALLOWLIST = new Set(["./_testable"]);
+
+function normalizeSlash(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function shouldScanFile(filePath) {
+  return SCANNED_EXTENSIONS.has(path.extname(filePath));
+}
+
+function walkFiles(directoryPath) {
+  const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (IGNORED_DIRECTORIES.has(entry.name)) {
+      continue;
+    }
+
+    const absolutePath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkFiles(absolutePath));
+      continue;
+    }
+
+    if (entry.isFile() && shouldScanFile(absolutePath)) {
+      files.push(absolutePath);
+    }
+  }
+
+  return files;
+}
+
+function toExportKey(importSubpath) {
+  const normalizedSubpath = String(importSubpath || "").replace(/\/+$/g, "");
+  if (!normalizedSubpath) {
+    return ".";
+  }
+  return `./${normalizedSubpath}`;
+}
+
+function collectScanFiles() {
+  const files = [];
+  for (const rootPath of SCAN_ROOTS) {
+    if (!fs.existsSync(rootPath)) {
+      continue;
+    }
+    files.push(...walkFiles(rootPath));
+  }
+  return files;
+}
+
+function isProductionOrTemplateUsageFile(filePath) {
+  const relativePath = normalizeSlash(path.relative(REPO_ROOT, filePath));
+  if (relativePath.startsWith("packages/kernel/")) {
+    return false;
+  }
+
+  const relativeSegments = relativePath.split("/");
+  if (relativeSegments.some((segment) => EXCLUDED_USAGE_PATH_SEGMENTS.has(segment))) {
+    return false;
+  }
+
+  const baseName = path.posix.basename(relativePath);
+  if (TEST_FILENAME_PATTERN.test(baseName)) {
+    return false;
+  }
+
+  return true;
+}
+
+function collectKernelImportUsages() {
+  const candidateFiles = collectScanFiles().filter((filePath) => isProductionOrTemplateUsageFile(filePath));
+
+  const moduleSpecifierPatterns = [
+    /\bimport\s+(?:[^"'`]+?\s+from\s+)?["'`]([^"'`]+)["'`]/g,
+    /\bexport\s+[^"'`]+?\s+from\s+["'`]([^"'`]+)["'`]/g,
+    /\bimport\s*\(\s*["'`]([^"'`]+)["'`]\s*\)/g
+  ];
+  const usages = [];
+
+  for (const filePath of candidateFiles) {
+    const fileContent = fs.readFileSync(filePath, "utf8");
+    const relativePath = normalizeSlash(path.relative(REPO_ROOT, filePath));
+    for (const pattern of moduleSpecifierPatterns) {
+      let match = null;
+      while ((match = pattern.exec(fileContent))) {
+        const specifier = String(match[1] || "");
+        if (!specifier.startsWith("@jskit-ai/kernel")) {
+          continue;
+        }
+        const importSubpath = specifier.startsWith("@jskit-ai/kernel/")
+          ? specifier.slice("@jskit-ai/kernel/".length)
+          : "";
+        usages.push({
+          filePath: relativePath,
+          specifier,
+          exportKey: toExportKey(importSubpath)
+        });
+      }
+    }
+  }
+
+  return usages;
+}
+
+function describeMissingExports(usages, exportsMap) {
+  const missing = usages
+    .filter((usage) => !Object.prototype.hasOwnProperty.call(exportsMap, usage.exportKey))
+    .map((usage) => `${usage.exportKey} <- ${usage.filePath} (${usage.specifier})`)
+    .sort();
+
+  return missing;
+}
+
+test("kernel exports are explicit and aligned with repository usage", () => {
+  const packageJson = JSON.parse(fs.readFileSync(KERNEL_PACKAGE_JSON_PATH, "utf8"));
+  const exportsMap = packageJson.exports || {};
+  const exportKeys = Object.keys(exportsMap).sort();
+
+  const wildcardExports = exportKeys.filter((key) => key.includes("*"));
+  assert.deepEqual(
+    wildcardExports,
+    [],
+    `Kernel exports must be explicit. Remove wildcard keys: ${wildcardExports.join(", ")}`
+  );
+
+  const usages = collectKernelImportUsages();
+  const missingExports = describeMissingExports(usages, exportsMap);
+  assert.deepEqual(
+    missingExports,
+    [],
+    `Kernel imports missing from package exports:\n${missingExports.join("\n")}`
+  );
+
+  const usedExportKeys = new Set(usages.map((usage) => usage.exportKey));
+  const staleExports = exportKeys
+    .filter((key) => !usedExportKeys.has(key))
+    .filter((key) => !EXPORTED_UNUSED_ALLOWLIST.has(key));
+
+  assert.deepEqual(
+    staleExports,
+    [],
+    `Stale kernel exports found. Remove or allowlist with rationale: ${staleExports.join(", ")}`
+  );
+});

package/test/routeInputContractGuard.test.js

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const REPO_ROOT = path.resolve(PACKAGE_ROOT, "..", "..");
+const PACKAGES_ROOT = path.join(REPO_ROOT, "packages");
+const SOURCE_SCOPE_MARKERS = ["/src/server/", "/templates/src/local-package/server/"];
+const JS_EXTENSIONS = new Set([".js", ".mjs", ".cjs"]);
+const DISALLOWED_PATTERNS = [
+  {
+    description: "spread pass-through from request.input",
+    regex: /\.{3}\s*request\.input\.(body|query|params)\b/g
+  },
+  {
+    description: "whole-section pass-through from request.input",
+    regex: /\binput\s*:\s*request\.input\.(body|query|params)\b/g
+  }
+];
+
+async function listFilesRecursive(directoryPath) {
+  const entries = await readdir(directoryPath, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const absolutePath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listFilesRecursive(absolutePath)));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(absolutePath);
+    }
+  }
+
+  return files;
+}
+
+function isRouteServerSourceFile(absolutePath) {
+  const normalizedPath = absolutePath.split(path.sep).join("/");
+  if (!SOURCE_SCOPE_MARKERS.some((marker) => normalizedPath.includes(marker))) {
+    return false;
+  }
+  return JS_EXTENSIONS.has(path.extname(absolutePath));
+}
+
+function findLineNumber(sourceText, index) {
+  return sourceText.slice(0, index).split("\n").length;
+}
+
+test("server route handlers do not pass through request.input sections", async () => {
+  const allFiles = await listFilesRecursive(PACKAGES_ROOT);
+  const targetFiles = allFiles.filter((absolutePath) => isRouteServerSourceFile(absolutePath));
+  const violations = [];
+
+  for (const absolutePath of targetFiles) {
+    const sourceText = await readFile(absolutePath, "utf8");
+    for (const { regex, description } of DISALLOWED_PATTERNS) {
+      regex.lastIndex = 0;
+      let match = regex.exec(sourceText);
+      while (match) {
+        const line = findLineNumber(sourceText, match.index);
+        violations.push(
+          `${path.relative(REPO_ROOT, absolutePath)}:${line} ${description}: ${match[0]}`
+        );
+        match = regex.exec(sourceText);
+      }
+    }
+  }
+
+  assert.deepEqual(
+    violations,
+    [],
+    `Found request.input pass-through patterns:\n${violations.join("\n")}`
+  );
+});

package/test/surfaceIndependence.test.js

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+const KERNEL_ROOT = path.join(REPO_ROOT, "packages", "kernel");
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".git", "dist", "coverage"]);
+const DISALLOWED_SURFACE_LITERALS = new Set(["app", "admin", "console", "home"]);
+const ALLOWED_PUBLIC_LITERAL_FILES = new Set([
+  "packages/kernel/shared/support/policies.js"
+]);
+
+function walkFiles(directoryPath) {
+  const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (IGNORED_DIRECTORIES.has(entry.name)) {
+      continue;
+    }
+    const absolutePath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkFiles(absolutePath));
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    if (!absolutePath.endsWith(".js") || absolutePath.endsWith(".test.js")) {
+      continue;
+    }
+    files.push(absolutePath);
+  }
+
+  return files;
+}
+
+function toRelativePath(filePath) {
+  return path.relative(REPO_ROOT, filePath).replace(/\\/g, "/");
+}
+
+function collectExactStringLiteralHits(source, values) {
+  const hits = [];
+  const pattern = /(["'])([^"'\\]*(?:\\.[^"'\\]*)*)\1/g;
+  let match = null;
+
+  while ((match = pattern.exec(source))) {
+    const literal = String(match[2] || "");
+    if (!values.has(literal)) {
+      continue;
+    }
+    hits.push({
+      literal,
+      index: match.index
+    });
+  }
+
+  return hits;
+}
+
+test("kernel non-test code stays surface-id agnostic", () => {
+  const files = walkFiles(KERNEL_ROOT);
+  const forbiddenHits = [];
+
+  for (const filePath of files) {
+    const source = fs.readFileSync(filePath, "utf8");
+    const relativePath = toRelativePath(filePath);
+    const literalHits = collectExactStringLiteralHits(source, DISALLOWED_SURFACE_LITERALS);
+
+    for (const hit of literalHits) {
+      forbiddenHits.push(`${relativePath}:${hit.index} -> "${hit.literal}"`);
+    }
+  }
+
+  assert.deepEqual(
+    forbiddenHits,
+    [],
+    `Kernel must not hardcode concrete surface ids:\n${forbiddenHits.join("\n")}`
+  );
+});
+
+test("kernel uses \"public\" literal only in policy files", () => {
+  const files = walkFiles(KERNEL_ROOT);
+  const disallowedPublicHits = [];
+
+  for (const filePath of files) {
+    const source = fs.readFileSync(filePath, "utf8");
+    const relativePath = toRelativePath(filePath);
+    const publicHits = collectExactStringLiteralHits(source, new Set(["public"]));
+    if (publicHits.length < 1) {
+      continue;
+    }
+    if (ALLOWED_PUBLIC_LITERAL_FILES.has(relativePath)) {
+      continue;
+    }
+    for (const hit of publicHits) {
+      disallowedPublicHits.push(`${relativePath}:${hit.index} -> "public"`);
+    }
+  }
+
+  assert.deepEqual(
+    disallowedPublicHits,
+    [],
+    `Kernel must not treat "public" as a hardcoded surface default:\n${disallowedPublicHits.join("\n")}`
+  );
+});