@zxyycom/vibe-check 0.0.1 → 0.0.3

package/src/package-checks/secret-detection/input-preparation.ts

@@ -0,0 +1,290 @@
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readSync,
+  type BigIntStats
+} from "node:fs";
+import { resolve } from "node:path";
+
+import type { CheckExecutionContext } from "../../check/check.ts";
+import {
+  classifySecretDetectionBytes,
+  type SecretDetectionCoverageGapReason
+} from "./classification.ts";
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+
+/** Private, already-classified text passed to this Check's private detector adapter. */
+export interface ApprovedTextInput {
+  readonly content: string;
+  readonly path: string;
+}
+
+/** A safe explanation for an exact selected input that did not receive detector coverage. */
+export interface SecretCoverageGap {
+  readonly path: string;
+  readonly reason: SecretDetectionCoverageGapReason;
+}
+
+export type PreparedSecretDetectionInputs = Readonly<
+  | { readonly kind: "cancelled" }
+  | { readonly kind: "unavailable" }
+  | {
+      readonly coverageGaps: readonly SecretCoverageGap[];
+      readonly inputs: readonly ApprovedTextInput[];
+      readonly kind: "complete";
+    }
+>;
+
+/** Reads and classifies the already-selected paths before the detector can receive text. */
+export function prepareSecretDetectionInputs(
+  context: CheckExecutionContext<ResolvedSecretDetectionOptions>,
+  selectedPaths: readonly string[]
+): PreparedSecretDetectionInputs {
+  const coverageGaps: SecretCoverageGap[] = [];
+  const inputs: ApprovedTextInput[] = [];
+  let consumedBytes = 0;
+
+  for (const [index, path] of selectedPaths.entries()) {
+    if (context.signal.aborted) return Object.freeze({ kind: "cancelled" });
+    const selectionLimit = selectionLimitGaps(
+      context.options.maximumFileCount,
+      selectedPaths,
+      index
+    );
+    if (selectionLimit !== undefined) {
+      coverageGaps.push(...selectionLimit);
+      break;
+    }
+    const prepared = prepareSelectedInput(context, path, consumedBytes);
+    if (prepared.kind === "cancelled" || prepared.kind === "unavailable") return prepared;
+    if (prepared.kind === "coverage-gap") {
+      consumedBytes += prepared.consumedBytes;
+      coverageGaps.push(Object.freeze({ path, reason: prepared.reason }));
+      if (prepared.stop) {
+        coverageGaps.push(...coverageGapsFor(selectedPaths.slice(index + 1), "total-byte-limit"));
+        break;
+      }
+      continue;
+    }
+    consumedBytes += prepared.byteLength;
+    inputs.push(prepared.input);
+  }
+  return Object.freeze({
+    coverageGaps: Object.freeze(coverageGaps),
+    inputs: Object.freeze(inputs),
+    kind: "complete"
+  });
+}
+
+type PreparedSelectedInput = Readonly<
+  | { readonly kind: "cancelled" }
+  | { readonly kind: "unavailable" }
+  | {
+      readonly consumedBytes: number;
+      readonly kind: "coverage-gap";
+      readonly reason: SecretDetectionCoverageGapReason;
+      readonly stop: boolean;
+    }
+  | { readonly byteLength: number; readonly input: ApprovedTextInput; readonly kind: "approved" }
+>;
+
+type BoundedRegularFileRead = Readonly<
+  | { readonly kind: "unavailable" }
+  | {
+      readonly kind: "coverage-gap";
+      readonly reason: Extract<
+        SecretDetectionCoverageGapReason,
+        "file-byte-limit" | "total-byte-limit"
+      >;
+    }
+  | { readonly bytes: Uint8Array; readonly kind: "complete" }
+>;
+
+function selectionLimitGaps(
+  maximumFileCount: number,
+  selectedPaths: readonly string[],
+  index: number
+): readonly SecretCoverageGap[] | undefined {
+  if (index < maximumFileCount) return undefined;
+  return coverageGapsFor(selectedPaths.slice(index), "file-count-limit");
+}
+
+function prepareSelectedInput(
+  context: CheckExecutionContext<ResolvedSecretDetectionOptions>,
+  path: string,
+  consumedBytes: number
+): PreparedSelectedInput {
+  if (context.signal.aborted) return Object.freeze({ kind: "cancelled" });
+  const read = readBoundedRegularFile({
+    consumedBytes,
+    filePath: resolve(context.project.root, path),
+    options: context.options
+  });
+  if (read.kind === "unavailable") return read;
+  if (read.kind === "coverage-gap") {
+    return Object.freeze({
+      consumedBytes: 0,
+      kind: "coverage-gap",
+      reason: read.reason,
+      stop: read.reason === "total-byte-limit"
+    });
+  }
+  if (context.signal.aborted) return Object.freeze({ kind: "cancelled" });
+
+  const classification = classifySecretDetectionBytes(read.bytes, context.options.maximumFileBytes);
+  if (classification.kind === "coverage-gap") {
+    return Object.freeze({
+      consumedBytes: read.bytes.byteLength,
+      kind: "coverage-gap",
+      reason: classification.reason,
+      stop: false
+    });
+  }
+  return Object.freeze({
+    byteLength: read.bytes.byteLength,
+    input: Object.freeze({ content: classification.content, path }),
+    kind: "approved"
+  });
+}
+
+function readBoundedRegularFile(input: {
+  readonly consumedBytes: number;
+  readonly filePath: string;
+  readonly options: ResolvedSecretDetectionOptions;
+}): BoundedRegularFileRead {
+  const descriptor = openIdentityCheckedRegularFile(input.filePath);
+  if (descriptor === undefined) return Object.freeze({ kind: "unavailable" });
+  try {
+    const byteLength = regularFileByteLength(descriptor);
+    if (byteLength === undefined) return Object.freeze({ kind: "unavailable" });
+    const limit = resourceLimitReason(input.options, byteLength, input.consumedBytes);
+    if (limit !== undefined) return Object.freeze({ kind: "coverage-gap", reason: limit });
+
+    const bytes = readExactBoundedBytes(descriptor, byteLength);
+    if (bytes === undefined || regularFileByteLength(descriptor) !== byteLength) {
+      return Object.freeze({ kind: "unavailable" });
+    }
+    return Object.freeze({ bytes, kind: "complete" });
+  } catch {
+    return Object.freeze({ kind: "unavailable" });
+  } finally {
+    closeDescriptor(descriptor);
+  }
+}
+
+function closeDescriptor(descriptor: number): void {
+  try {
+    closeSync(descriptor);
+  } catch {
+    // The descriptor cannot carry source bytes into a public result; preserve the completed read fact.
+  }
+}
+
+interface RegularFileIdentity {
+  readonly device: bigint;
+  readonly inode: bigint;
+}
+
+function openIdentityCheckedRegularFile(filePath: string): number | undefined {
+  const expectedIdentity = regularFileIdentityAtPath(filePath);
+  if (expectedIdentity === undefined) return undefined;
+  const openFlags = finalLeafOpenFlags();
+  if (openFlags === undefined) return undefined;
+
+  let descriptor: number;
+  try {
+    descriptor = openSync(filePath, openFlags);
+  } catch {
+    return undefined;
+  }
+
+  const openedIdentity = regularFileIdentityOnDescriptor(descriptor);
+  if (openedIdentity !== undefined && sameRegularFileIdentity(expectedIdentity, openedIdentity)) {
+    return descriptor;
+  }
+  closeDescriptor(descriptor);
+  return undefined;
+}
+
+function finalLeafOpenFlags(): number | undefined {
+  if (process.platform === "win32") return constants.O_RDONLY;
+  return typeof constants.O_NOFOLLOW === "number" && constants.O_NOFOLLOW !== 0
+    ? constants.O_RDONLY | constants.O_NOFOLLOW
+    : undefined;
+}
+
+function regularFileIdentityAtPath(filePath: string): RegularFileIdentity | undefined {
+  try {
+    return regularFileIdentity(lstatSync(filePath, { bigint: true }));
+  } catch {
+    return undefined;
+  }
+}
+
+function regularFileIdentityOnDescriptor(descriptor: number): RegularFileIdentity | undefined {
+  try {
+    return regularFileIdentity(fstatSync(descriptor, { bigint: true }));
+  } catch {
+    return undefined;
+  }
+}
+
+function regularFileIdentity(details: BigIntStats): RegularFileIdentity | undefined {
+  return details.isFile() && details.dev > 0n && details.ino > 0n
+    ? Object.freeze({ device: details.dev, inode: details.ino })
+    : undefined;
+}
+
+function sameRegularFileIdentity(
+  expected: RegularFileIdentity,
+  opened: RegularFileIdentity
+): boolean {
+  return expected.device === opened.device && expected.inode === opened.inode;
+}
+
+function regularFileByteLength(descriptor: number): number | undefined {
+  try {
+    const details = fstatSync(descriptor);
+    return details.isFile() && Number.isSafeInteger(details.size) && details.size >= 0
+      ? details.size
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readExactBoundedBytes(descriptor: number, byteLength: number): Uint8Array | undefined {
+  const bytes = new Uint8Array(byteLength);
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    const read = readSync(
+      descriptor,
+      bytes,
+      offset,
+      Math.min(65_536, bytes.byteLength - offset),
+      null
+    );
+    if (read <= 0) return undefined;
+    offset += read;
+  }
+  return bytes;
+}
+
+function resourceLimitReason(
+  options: ResolvedSecretDetectionOptions,
+  byteLength: number,
+  consumedBytes: number
+): Extract<SecretDetectionCoverageGapReason, "file-byte-limit" | "total-byte-limit"> | undefined {
+  if (byteLength > options.maximumFileBytes) return "file-byte-limit";
+  return consumedBytes + byteLength > options.maximumTotalBytes ? "total-byte-limit" : undefined;
+}
+
+function coverageGapsFor(
+  paths: readonly string[],
+  reason: SecretDetectionCoverageGapReason
+): readonly SecretCoverageGap[] {
+  return Object.freeze(paths.map((path) => Object.freeze({ path, reason })));
+}

package/src/package-checks/secret-detection/options-resolution.ts

@@ -0,0 +1,65 @@
+import { snapshotClosedPolicyRecord } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import { resolveFindingWaiverAuthoring } from "../code-quality-findings/finding-waiver-authoring.ts";
+import {
+  snapshotProjectFileSelection,
+  validProjectFileSelection
+} from "../project-files/configuration.ts";
+import { resolveSecretDetectionFindingIdentity } from "./finding-waiver-identity.ts";
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+import { validSecretDetectionOptions } from "./options-validation.ts";
+
+export const DEFAULT_SECRET_DETECTION_MAXIMUM_FILE_BYTES = 1_048_576;
+export const DEFAULT_SECRET_DETECTION_MAXIMUM_TOTAL_BYTES = 8_388_608;
+export const DEFAULT_SECRET_DETECTION_MAXIMUM_FILE_COUNT = 2_048;
+
+/** 将 required exact file policy 和有限资源策略物化为完整、冻结 options。 */
+export function resolveSecretDetectionOptions(
+  value: unknown
+): ResolvedSecretDetectionOptions | undefined {
+  const input = snapshotClosedPolicyRecord(value, {
+    optional: ["findingWaivers", "maximumFileBytes", "maximumFileCount", "maximumTotalBytes"],
+    required: ["files"]
+  });
+  if (input === undefined || !validProjectFileSelection(input.files)) return undefined;
+
+  const limits = resolveSecretDetectionResourceLimits(input);
+  const findingWaivers = resolveFindingWaiverAuthoring(
+    input.findingWaivers,
+    resolveSecretDetectionFindingIdentity
+  );
+  if (limits === undefined || findingWaivers === undefined) return undefined;
+
+  const options = Object.freeze({
+    files: snapshotProjectFileSelection(input.files),
+    findingWaivers,
+    ...limits
+  });
+  return validSecretDetectionOptions(options) ? options : undefined;
+}
+
+function resolveSecretDetectionResourceLimits(
+  input: Readonly<{
+    readonly maximumFileBytes?: unknown;
+    readonly maximumFileCount?: unknown;
+    readonly maximumTotalBytes?: unknown;
+  }>
+):
+  | Readonly<{
+      readonly maximumFileBytes: number;
+      readonly maximumFileCount: number;
+      readonly maximumTotalBytes: number;
+    }>
+  | undefined {
+  const maximumFileBytes = input.maximumFileBytes ?? DEFAULT_SECRET_DETECTION_MAXIMUM_FILE_BYTES;
+  const maximumFileCount = input.maximumFileCount ?? DEFAULT_SECRET_DETECTION_MAXIMUM_FILE_COUNT;
+  const maximumTotalBytes = input.maximumTotalBytes ?? DEFAULT_SECRET_DETECTION_MAXIMUM_TOTAL_BYTES;
+  if (
+    !isPositiveSafeInteger(maximumFileBytes) ||
+    !isPositiveSafeInteger(maximumFileCount) ||
+    !isPositiveSafeInteger(maximumTotalBytes)
+  ) {
+    return undefined;
+  }
+  return Object.freeze({ maximumFileBytes, maximumFileCount, maximumTotalBytes });
+}

package/src/package-checks/secret-detection/options-validation.ts

@@ -0,0 +1,27 @@
+import { snapshotExactClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import { validResolvedFindingWaivers } from "../code-quality-findings/finding-waiver-authoring.ts";
+import { validProjectFileSelection } from "../project-files/configuration.ts";
+import { resolveSecretDetectionFindingIdentity } from "./finding-waiver-identity.ts";
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+
+/** Guards prepared options before a Run invokes a detector. */
+export function validSecretDetectionOptions(
+  value: unknown
+): value is ResolvedSecretDetectionOptions {
+  const options = snapshotExactClosedRecord(value, [
+    "files",
+    "findingWaivers",
+    "maximumFileBytes",
+    "maximumFileCount",
+    "maximumTotalBytes"
+  ]);
+  return (
+    options !== undefined &&
+    validProjectFileSelection(options.files) &&
+    validResolvedFindingWaivers(options.findingWaivers, resolveSecretDetectionFindingIdentity) &&
+    isPositiveSafeInteger(options.maximumFileBytes) &&
+    isPositiveSafeInteger(options.maximumFileCount) &&
+    isPositiveSafeInteger(options.maximumTotalBytes)
+  );
+}

package/src/package-checks/secret-detection/options.ts

@@ -0,0 +1,39 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
+import type { ProjectFileSelection } from "../project-files/configuration.ts";
+
+/** `secretDetection(options)` 的明确 authoring policy。 */
+export interface SecretDetectionOptions<
+  Id extends string = string
+> extends PackageCheckAuthoringOptions<Id> {
+  /** 必填的完整 project-file policy；只有它选中的 path 可以被读取或传给 detector。 */
+  readonly files: ProjectFileSelection;
+  /** 单个输入允许的最大 raw byte 数；超过时形成不可豁免的 coverage gap。 */
+  readonly maximumFileBytes?: number;
+  /** 一次 invocation 中允许读取和检测的累计 raw byte 数；超过时形成 coverage gap。 */
+  readonly maximumTotalBytes?: number;
+  /** 一次 invocation 中允许处理的 selected file 数；超过时形成 coverage gap。 */
+  readonly maximumFileCount?: number;
+  /** 对安全 finding identity 的精确、可审计误报豁免。 */
+  readonly findingWaivers?: readonly FindingWaiver<SecretDetectionFindingIdentity>[];
+}
+
+/** 不含 raw value、message、hash 或 location 的 secret finding 身份。 */
+export interface SecretDetectionFindingIdentity {
+  readonly ordinal: number;
+  readonly path: string;
+  readonly ruleId: "@secretlint/secretlint-rule-privatekey";
+  readonly structuralClass: "text-document";
+}
+
+/** `secretDetection` execution 消费的完整冻结 options。 */
+export interface ResolvedSecretDetectionOptions {
+  readonly files: ProjectFileSelection;
+  readonly findingWaivers: readonly FindingWaiver<SecretDetectionFindingIdentity>[];
+  readonly maximumFileBytes: number;
+  readonly maximumFileCount: number;
+  readonly maximumTotalBytes: number;
+}
+
+/** `findingWaivers` 的 public authoring alias。 */
+export type SecretDetectionFindingWaiver = FindingWaiver<SecretDetectionFindingIdentity>;

package/src/package-checks/secret-detection/records.ts

@@ -0,0 +1,77 @@
+import type { MaterializedFindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
+import type {
+  FindingWaiverRecordAudit,
+  FindingWaiverAuditRecordData
+} from "../code-quality-findings/finding-waiver-evidence.ts";
+import { buildFindingWaiverAuditRecordData } from "../code-quality-findings/finding-waiver-evidence.ts";
+import type { SecretDetectionCoverageGapReason } from "./classification.ts";
+import type { SecretDetectionIssue } from "./secretlint/adapter.ts";
+import type { SecretDetectionFindingIdentity } from "./options.ts";
+import { resolveSecretDetectionFindingIdentity } from "./finding-waiver-identity.ts";
+
+/** An actionable or waived high-confidence secret finding. No detector value or message is retained. */
+export interface SecretDetectionFindingRecordData {
+  readonly blocking: boolean;
+  readonly kind: "secret-finding";
+  readonly location: SecretDetectionIssue["location"];
+  readonly ordinal: number;
+  readonly path: string;
+  readonly ruleId: "@secretlint/secretlint-rule-privatekey";
+  readonly structuralClass: "text-document";
+  readonly waiver?: Readonly<{ readonly reason: string }>;
+}
+
+/** A deterministic exact-input coverage gap. It is never reconciled through finding waiver policy. */
+export interface SecretDetectionCoverageGapRecordData {
+  readonly blocking: true;
+  readonly kind: "coverage-gap";
+  readonly path: string;
+  readonly reason: SecretDetectionCoverageGapReason;
+}
+
+/** Unused or overmatched safe secret finding waiver evidence. */
+export type SecretDetectionFindingWaiverAuditRecordData =
+  FindingWaiverAuditRecordData<SecretDetectionFindingIdentity>;
+
+/** `secretDetection` 发布的全部补充 Record data。 */
+export type SecretDetectionRecordData =
+  | SecretDetectionCoverageGapRecordData
+  | SecretDetectionFindingRecordData
+  | SecretDetectionFindingWaiverAuditRecordData;
+
+export function secretFindingIdentity(issue: SecretDetectionIssue): SecretDetectionFindingIdentity {
+  return Object.freeze({
+    ordinal: issue.ordinal,
+    path: issue.path,
+    ruleId: issue.ruleId,
+    structuralClass: issue.structuralClass
+  });
+}
+
+export function secretFindingRecordId(identity: SecretDetectionFindingIdentity): string {
+  return `/secret-finding/${identity.path}/${identity.ordinal}`;
+}
+
+export function secretCoverageGapRecordId(path: string): string {
+  return `/coverage-gap/${path}`;
+}
+
+export function secretDetectionWaiverAuditRecord(
+  audit: FindingWaiverRecordAudit
+): Readonly<{ readonly data: SecretDetectionFindingWaiverAuditRecordData; readonly id: string }> {
+  const identity = secretDetectionWaiverIdentity(audit.waiver);
+  return Object.freeze({
+    data: buildFindingWaiverAuditRecordData(identity, audit),
+    id: `/finding-waiver-audit/${identity.path}/${identity.ordinal}`
+  });
+}
+
+function secretDetectionWaiverIdentity(
+  waiver: MaterializedFindingWaiver
+): SecretDetectionFindingIdentity {
+  const identity = resolveSecretDetectionFindingIdentity(waiver.identity);
+  if (identity === undefined) {
+    throw new TypeError("secretDetection waiver identity must be a safe finding identity");
+  }
+  return identity;
+}

package/src/package-checks/secret-detection/secretlint/adapter.ts

@@ -0,0 +1,122 @@
+import { snapshotClosedRecord } from "../../../data-boundary/closed-values.ts";
+import { lintSource } from "@secretlint/core";
+import { creator as privateKeyRule } from "@secretlint/secretlint-rule-privatekey";
+
+import {
+  secretDetectionPrivateKeyRuleId,
+  secretDetectionTextDocumentStructuralClass
+} from "../finding-waiver-identity.ts";
+
+/** The only detector result shape allowed to leave this private adapter. */
+export interface SecretDetectionIssue {
+  readonly location: Readonly<{
+    readonly endColumn: number;
+    readonly endLine: number;
+    readonly startColumn: number;
+    readonly startLine: number;
+  }>;
+  readonly ordinal: number;
+  readonly path: string;
+  readonly ruleId: "@secretlint/secretlint-rule-privatekey";
+  readonly structuralClass: "text-document";
+}
+
+export type SecretlintDetectionResult = Readonly<
+  | { readonly issues: readonly SecretDetectionIssue[]; readonly kind: "complete" }
+  | { readonly kind: "protocol-failed" }
+  | { readonly kind: "unavailable" }
+>;
+
+/**
+ * Runs the fixed local Secretlint rule set against already-approved in-memory text.
+ * Third-party result, message text, data, error, and source content never leave this module.
+ */
+export async function detectSecretlintIssues(
+  content: string,
+  projectRelativePath: string
+): Promise<SecretlintDetectionResult> {
+  try {
+    const result = await lintSource({
+      source: { content, contentType: "text", filePath: projectRelativePath },
+      options: {
+        config: {
+          rules: [{ id: secretDetectionPrivateKeyRuleId, rule: privateKeyRule, severity: "error" }]
+        },
+        maskSecrets: true,
+        noPhysicFilePath: true
+      }
+    });
+    return adaptSecretlintMessages(result.messages, projectRelativePath);
+  } catch {
+    return Object.freeze({ kind: "unavailable" });
+  }
+}
+
+/** Converts only allowlisted Secretlint message fields to the safe Check-local issue DTO. */
+export function adaptSecretlintMessages(
+  messages: unknown,
+  projectRelativePath: string
+): SecretlintDetectionResult {
+  if (!Array.isArray(messages)) return Object.freeze({ kind: "protocol-failed" });
+
+  const issues: SecretDetectionIssue[] = [];
+  for (const message of messages) {
+    const location = safeLocation(message);
+    if (location === undefined || !isPrivateKeyMessage(message)) {
+      return Object.freeze({ kind: "protocol-failed" });
+    }
+    issues.push(
+      Object.freeze({
+        location,
+        ordinal: issues.length + 1,
+        path: projectRelativePath,
+        ruleId: secretDetectionPrivateKeyRuleId,
+        structuralClass: secretDetectionTextDocumentStructuralClass
+      })
+    );
+  }
+  return Object.freeze({ issues: Object.freeze(issues), kind: "complete" });
+}
+
+function isPrivateKeyMessage(value: unknown): boolean {
+  const message = snapshotClosedRecord(value);
+  return (
+    message?.type === "message" &&
+    message?.ruleId === secretDetectionPrivateKeyRuleId &&
+    message?.severity === "error"
+  );
+}
+
+function safeLocation(value: unknown): SecretDetectionIssue["location"] | undefined {
+  const message = snapshotClosedRecord(value);
+  if (message === undefined) return undefined;
+  const loc = snapshotClosedRecord(message.loc);
+  if (loc === undefined) return undefined;
+  const start = loc.start;
+  const end = loc.end;
+  if (!isPosition(start) || !isPosition(end)) return undefined;
+  if (end.line < start.line || (end.line === start.line && end.column < start.column)) {
+    return undefined;
+  }
+  return Object.freeze({
+    endColumn: end.column + 1,
+    endLine: end.line,
+    startColumn: start.column + 1,
+    startLine: start.line
+  });
+}
+
+function isPosition(
+  value: unknown
+): value is Readonly<{ readonly column: number; readonly line: number }> {
+  const position = snapshotClosedRecord(value);
+  return (
+    position !== undefined &&
+    typeof position.column === "number" &&
+    Number.isSafeInteger(position.column) &&
+    position.column >= 0 &&
+    typeof position.line === "number" &&
+    Number.isSafeInteger(position.line) &&
+    position.line >= 1
+  );
+}

package/src/package-tools/admission-policy/define-admission-policy.ts

@@ -0,0 +1,54 @@
+import type {
+  AdmissionPolicy,
+  CustomAdmissionPreparationContext,
+  CustomAdmissionStrategy,
+  PreparedCustomAdmissionStrategy
+} from "../../project-definition/scheduler-policy.ts";
+
+type ExactAdmissionPolicy<T extends AdmissionPolicy> =
+  T extends Readonly<{ readonly kind: "static" }>
+    ? T & Record<Exclude<keyof T, "kind">, never>
+    : T extends Readonly<{ readonly kind: "custom" }>
+      ? T &
+          Record<Exclude<keyof T, "kind" | "strategy">, never> &
+          Readonly<{
+            readonly strategy: ExactCustomAdmissionStrategy<T["strategy"]>;
+          }>
+      : never;
+
+type ExactCustomAdmissionStrategy<T extends CustomAdmissionStrategy> =
+  T extends Readonly<{ readonly kind: "simple" }>
+    ? T & Record<Exclude<keyof T, "kind" | "decide">, never>
+    : T extends Readonly<{ readonly kind: "prepared" }>
+      ? T &
+          Record<Exclude<keyof T, "kind" | "prepare">, never> &
+          Readonly<{ readonly prepare: ExactCustomPreparation<T["prepare"]> }>
+      : never;
+
+type ExactCustomPreparation<T> = T extends (
+  this: void,
+  context: CustomAdmissionPreparationContext
+) => infer Result
+  ? (this: void, context: CustomAdmissionPreparationContext) => ExactCustomPreparationResult<Result>
+  : never;
+
+type ExactCustomPreparationResult<T> =
+  T extends Promise<unknown>
+    ? Promise<ExactPreparedCustomAdmissionStrategy<Awaited<T>>>
+    : ExactPreparedCustomAdmissionStrategy<T>;
+
+type ExactPreparedCustomAdmissionStrategy<T> = T extends PreparedCustomAdmissionStrategy
+  ? T & Record<Exclude<keyof T, "decide" | "terminalEffect">, never>
+  : never;
+
+/**
+ * 保留 closed admission policy literal 的 TypeScript inference，不创建额外运行语义。
+ *
+ * @remarks inline policy 与此 helper 的结果完全等价。custom simple `decide` 同步运行；prepared
+ * strategy 为每个 graph-ready Run 解析独立 closure，调用方负责其 trusted host callback 的可重入性。
+ */
+export function defineAdmissionPolicy<const T extends AdmissionPolicy>(
+  policy: ExactAdmissionPolicy<T>
+): T {
+  return policy;
+}