@zxyycom/vibe-check 0.0.2 → 0.0.3

package/types/index.d.ts

@@ -4,9 +4,13 @@
  *
  * @packageDocumentation
  */
-export { cacheJsonByKey } from "./cache/cache-json-by-key.ts";
-export type { CacheJsonByKeyOptions, CacheJsonByKeyResult } from "./cache/cache-json-by-key.ts";
+export { cacheJsonByKey } from "./package-tools/cache/cache-json-by-key.ts";
+export type { CacheJsonByKeyOptions, CacheJsonByKeyResult } from "./package-tools/cache/cache-json-by-key.ts";
+export { canonicalizeJsonObject, canonicalizeJsonValue, canonicalJsonBytes, canonicalJsonText } from "./data-boundary/canonical-data.ts";
+export type { CanonicalJsonObject, CanonicalJsonPrimitive, CanonicalJsonValue } from "./data-boundary/canonical-data.ts";
+export { snapshotClosedArray, snapshotExactClosedRecord } from "./data-boundary/closed-values.ts";
 export { duplicateDetection } from "./package-checks/duplicate-detection/default-check.ts";
+export type { PackageCheckAuthoringOptions } from "./package-checks/check-authoring.ts";
 export { parseDuplicateDetectionData } from "./package-checks/duplicate-detection/final-data.ts";
 export type { DuplicateDetectionFinalData } from "./package-checks/duplicate-detection/final-data.ts";
 export type { DuplicateDetectionFindingIdentity, DuplicateDetectionFindingLocation, DuplicateDetectionFindingWaiver, DuplicateDetectionOptions, ResolvedDuplicateDetectionOptions } from "./package-checks/duplicate-detection/options.ts";
@@ -40,10 +44,18 @@ export { parseJsonValidationData } from "./package-checks/json-validation/final-
 export type { JsonValidationFinalData } from "./package-checks/json-validation/final-data.ts";
 export type { JsonValidationOptions, ResolvedJsonValidationOptions } from "./package-checks/json-validation/options.ts";
 export type { JsonValidationRecordData, JsonValidationRecordReason, JsonValidationUnavailableCode } from "./package-checks/json-validation/json-validation.ts";
+export { commandCheck } from "./package-checks/command-check/command-check.ts";
+export type { AfterCommand, AfterCommandContext, AfterCommandExecution, CommandCheck, CommandCheckEnvironment, CommandCheckWithAfterCommand, CommandEnvironmentContext, CommandEnvironmentResolver, CompletedCommand, CommandCheckFinalData, CommandCheckInput, CommandCheckOutput, CommandCheckUnavailableReasonCode, TypedCommandCheck } from "./package-checks/command-check/command-check.ts";
 export { maintenanceReminders } from "./package-checks/maintenance-reminders/maintenance-reminders.ts";
-export type { MaintenanceReminder, MaintenanceReminderOptions, MaintenanceRemindersUnavailableCode } from "./package-checks/maintenance-reminders/maintenance-reminders.ts";
+export type { MaintenanceReminder, MaintenanceReminderOptions, MaintenanceRemindersInput, MaintenanceRemindersUnavailableCode } from "./package-checks/maintenance-reminders/maintenance-reminders.ts";
 export { parseMaintenanceRemindersData } from "./package-checks/maintenance-reminders/final-data.ts";
 export type { MaintenanceReminderAssessment, MaintenanceReminderUnavailableReason, MaintenanceRemindersFinalData } from "./package-checks/maintenance-reminders/final-data.ts";
+export { markdownLint } from "./package-checks/markdown-lint/default-check.ts";
+export { parseMarkdownLintData } from "./package-checks/markdown-lint/final-data.ts";
+export type { MarkdownLintFinalData } from "./package-checks/markdown-lint/final-data.ts";
+export type { MarkdownLintFindingIdentity, MarkdownLintFindingWaiver, MarkdownLintOptions, MarkdownLintRuleName, ResolvedMarkdownLintOptions } from "./package-checks/markdown-lint/options.ts";
+export type { MarkdownLintFindingWaiverAuditRecordData, MarkdownLintRecordData } from "./package-checks/markdown-lint/records.ts";
+export type { MarkdownLintUnavailableReason } from "./package-checks/markdown-lint/execution.ts";
 export { markdownLinkValidation } from "./package-checks/markdown-link-validation/default-check.ts";
 export { parseMarkdownLinkValidationData } from "./package-checks/markdown-link-validation/final-data.ts";
 export type { MarkdownLinkValidationFinalData } from "./package-checks/markdown-link-validation/final-data.ts";
@@ -52,20 +64,24 @@ export type { MarkdownLinkValidationUnavailableReason } from "./package-checks/m
 export type { MarkdownLinkValidationRecordData } from "./package-checks/markdown-link-validation/records.ts";
 export type { MarkdownLinkFindingReason } from "./package-checks/markdown-link-validation/local-resolver.ts";
 export type { FindingPolicy } from "./package-checks/code-quality-findings/policy.ts";
-export { reconcileFindingWaivers } from "./finding-waivers/reconciliation.ts";
-export { presentCheckFindings } from "./check/finding-presentation.ts";
-export type { FindingWaiver, FindingWaiverAudit, FindingWaiverReconciliation, MaterializedFindingWaiver, ReconciledFinding, ReconcileFindingWaiversOptions } from "./finding-waivers/reconciliation.ts";
+export { reconcileFindingWaivers } from "./package-tools/finding-waivers/reconciliation.ts";
+export { presentCheckFindings } from "./package-tools/finding-presentation/finding-presentation.ts";
+export type { FindingWaiver, FindingWaiverAudit, FindingWaiverReconciliation, MaterializedFindingWaiver, ReconciledFinding, ReconcileFindingWaiversOptions } from "./package-tools/finding-waivers/reconciliation.ts";
 export { defaultProjectFileSelection } from "./package-checks/project-files/configuration.ts";
 export { collectProjectFiles } from "./package-checks/project-files/public-collection.ts";
 export type { CollectProjectFilesOptions } from "./package-checks/project-files/public-collection.ts";
 export type { ProjectFileSelection, ProjectFileSelectionOptions, ProjectFileSource } from "./package-checks/project-files/configuration.ts";
 export { defineCheck, inherit } from "./check/check.ts";
-export type { Check, CheckDependencies, CheckExecution, CheckExecutionContext, CheckPreflight, CheckPreflightResult, CheckResourceClaims, CheckOutcome, CheckResult, CheckUnavailableReason, InheritableCheckCollection } from "./check/check.ts";
-export { defineAdmissionPolicy, defineConfig } from "./project-definition/project-definition.ts";
-export { createLearnedCriticalPathStrategy } from "./learned-critical-path/strategy.ts";
-export type { LearnedCriticalPathObservation, LearnedCriticalPathStrategyOptions } from "./learned-critical-path/strategy.ts";
+export { all, any, changeFlag, exactlyOne, none, not, notAll } from "./check/flag-enablement.ts";
+export type { Check, CheckDependencies, CheckExecution, CheckExecutionContext, CheckFlagCondition, CheckFlagEnablement, CheckPreparation, CheckPreparationResult, CheckProjectContext, CheckResourceClaims, CheckOutcome, ProjectChanges, CheckResult, CheckUnavailableReason, InheritableCheckCollection } from "./check/check.ts";
+export { defineAdmissionPolicy } from "./package-tools/admission-policy/define-admission-policy.ts";
+export { defineConfig } from "./project-definition/project-definition.ts";
+export { createLearnedCriticalPathStrategy } from "./package-tools/learned-critical-path/strategy.ts";
+export type { LearnedCriticalPathObservation, LearnedCriticalPathStrategyOptions } from "./package-tools/learned-critical-path/strategy.ts";
 export { createAdmissionGraph } from "./project-run/task-scheduler/admission-core/core.ts";
-export type { AdmissionPolicy, AdmissionPolicyContext, AdmissionPolicyMeasurement, AdmissionProposal, AdmissionCatalog, AdmissionGraph, AdmissionGraphInput, AdmissionInspection, AdmissionNonSelectableTask, AdmissionRejectionReason, AdmissionScopeLifecycle, AdmissionSelectionRejectionReason, AdmissionSelectionValidation, AdmissionSelectionValidationRejectionReason, AdmissionSettlementOutcome, AdmissionSettledTask, AdmissionState, AdmissionTransitionResult, CustomAdmissionPreparationContext, CustomAdmissionStrategy, PreparedCustomAdmissionStrategy, ProgressPreviewFormatter, ProjectOutputs, ProjectDefinition, SchedulerDecisionMeasurementCumulative, SchedulerGraphSnapshot, SchedulerMeasurementContext, SchedulerMeasurementHook, SchedulerMeasurementIntervalContribution, SchedulerMeasurementActionObservationInterval, SchedulerMeasurementActionObservation, SchedulerMeasurementEffect, SchedulerRawMeasurement, SchedulerPolicy } from "./project-definition/project-definition.ts";
+export type { AdmissionPolicy, AdmissionPolicyContext, AdmissionPolicyMeasurement, AdmissionProposal, AdmissionCatalog, AdmissionGraph, AdmissionGraphInput, AdmissionInspection, AdmissionNonSelectableTask, AdmissionRejectionReason, AdmissionScopeLifecycle, AdmissionSelectionRejectionReason, AdmissionSelectionValidation, AdmissionSelectionValidationRejectionReason, AdmissionSettlementOutcome, AdmissionSettledTask, AdmissionState, AdmissionTransitionResult, CustomAdmissionPreparationContext, CustomAdmissionStrategy, PreparedCustomAdmissionStrategy, ProgressPreviewFormatter, ProjectOutputs, ProjectDefinition, SchedulerDecisionMeasurementCumulative, SchedulerGraphSnapshot, SchedulerMeasurementContext, SchedulerTerminalEffect, SchedulerMeasurementIntervalContribution, SchedulerMeasurementActionObservationInterval, SchedulerMeasurementActionObservation, SchedulerMeasurementEffect, SchedulerRawMeasurement, SchedulerPolicy } from "./project-definition/project-definition.ts";
+export type { ProjectChangeFlagRegion, ProjectChangeSource, ProjectChangesConfiguration } from "./project-definition/project-changes.ts";
+export type { CoreCheck } from "./check-settlement/facts.ts";
 export type { CheckAggregate, CheckAggregation, RunControls } from "./project-run/controls/contract.ts";
 export { run } from "./project-run/run.ts";
 export type { RunOutputStatus, RunOutputStatuses } from "./project-run/outputs/status.ts";

package/types/package-checks/check-authoring.d.ts

@@ -0,0 +1,45 @@
+import type { Check, CheckFlagEnablement, CheckResourceClaims, InheritableCheckCollection } from "../check/check.ts";
+/** 固定身份随包 Check 构造器与领域 policy 并列接收的项目声明字段；Project Definition 保留语义校验所有权。 */
+export interface PackageCheckAuthoringOptions<Id extends string = string> {
+    /** Overrides the constructor's package default identity. */
+    readonly checkId?: Id;
+    /** Overrides the constructor's package default presentation name. */
+    readonly displayName?: string;
+    readonly enabledByFlags?: CheckFlagEnablement;
+    readonly checks?: readonly Check[];
+    readonly dependsOn?: InheritableCheckCollection<string>;
+    readonly observes?: InheritableCheckCollection<string>;
+    readonly maxParallel?: number;
+    readonly admissionPriority?: number;
+    readonly mutex?: InheritableCheckCollection<string>;
+    readonly resourceClaims?: CheckResourceClaims;
+    /** `false` explicitly restores the package default of rendering quiet passed rows. */
+    readonly omitQuietPassedRow?: boolean;
+}
+/** 自定义随包 Check identity 时必须声明与返回类型一致的 runtime `checkId`。 */
+export type PackageCheckIdentityInput<Id extends string> = Readonly<{
+    readonly checkId: Id;
+}>;
+type PackageCheckDefinition<Id extends string> = Readonly<{
+    readonly checkId: Id;
+    readonly displayName: string;
+    readonly enabledByFlags?: CheckFlagEnablement;
+    readonly checks?: readonly Check[];
+    readonly dependsOn?: InheritableCheckCollection<string>;
+    readonly observes?: InheritableCheckCollection<string>;
+    readonly maxParallel?: number;
+    readonly admissionPriority?: number;
+    readonly mutex?: InheritableCheckCollection<string>;
+    readonly resourceClaims?: CheckResourceClaims;
+    readonly omitQuietPassedRow?: true;
+}>;
+/** 对一个 closed 构造输入执行安全 shape 校验，并分流领域 policy 与普通 Check 声明字段。 */
+export declare function resolvePackageCheckAuthoringInput<const Id extends string>(input: PackageCheckAuthoringOptions<Id> & object, domainKeys: readonly string[], defaults: Readonly<{
+    readonly checkId: string;
+    readonly displayName: string;
+    readonly omitQuietPassedRow?: true;
+}>): Readonly<{
+    readonly definition: PackageCheckDefinition<Id>;
+    readonly domainOptions: Readonly<Record<string, unknown>>;
+}> | undefined;
+export {};

package/types/package-checks/code-quality-findings/finding-waiver-authoring.d.ts

@@ -1,4 +1,4 @@
-import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 /**
  * Snapshots the shared closed waiver envelope while leaving identity grammar to the producing Check.
  */

package/types/package-checks/code-quality-findings/finding-waiver-evidence.d.ts

@@ -1,5 +1,5 @@
 import type { CheckExecutionContext } from "../../check/check.ts";
-import type { FindingWaiverAudit, FindingWaiverReconciliation } from "../../finding-waivers/reconciliation.ts";
+import type { FindingWaiverAudit, FindingWaiverReconciliation } from "../../package-tools/finding-waivers/reconciliation.ts";
 interface CodeQualityFindingCandidate {
     readonly data: Readonly<{
         readonly blocking: boolean;

package/types/package-checks/command-check/command-check.d.ts

@@ -0,0 +1,48 @@
+import type { CheckDataParser } from "../../check/check.ts";
+import type { AfterCommandExecution, CommandCheck, CommandCheckInput, CommandCheckWithAfterCommand, TypedCommandCheck } from "./contract.ts";
+export type { AfterCommand, AfterCommandContext, AfterCommandExecution, CommandCheckWithAfterCommand, CommandEnvironmentContext, CommandEnvironmentResolver, CompletedCommand, CommandCheck, CommandCheckEnvironment, CommandCheckFinalData, CommandCheckInput, CommandCheckOutput, CommandCheckUnavailableReasonCode, TypedCommandCheck } from "./contract.ts";
+/**
+ * 构造一个单一 no-shell executable 的 ordinary Check。
+ *
+ * @remarks constructor 会闭合并冻结 command-owned options；ordinary selection、relation 与 scheduling fields 仍按普通 Check lifecycle 传递。默认 exact-empty environment 与 discard output 不会把 ambient variables、child stdout/stderr 或 native error text 发布到 Check facts。`output: { mode: "transcript" }` 仅在 invocation 授予此 Check artifact directory 时，将 raw stdout/stderr 写入固定 `process.log`。
+ * @example 以 process.execPath 构造无 shell command Check
+ * ```ts
+ * import { commandCheck, defineConfig, run } from "@zxyycom/vibe-check";
+ *
+ * const nodeProbe = commandCheck({
+ *   checkId: "node-probe",
+ *   displayName: "Node probe",
+ *   executable: process.execPath,
+ *   arguments: ["--eval", "process.exit(0)"],
+ *   timeoutMs: 5_000,
+ *   outputByteLimit: 64 * 1024
+ * });
+ *
+ * const definition = defineConfig({
+ *   checks: [nodeProbe],
+ *   outputs: {
+ *     diagnosticLogging: { enabled: false },
+ *     machinePublication: { enabled: false },
+ *     progressRendering: { enabled: false }
+ *   }
+ * });
+ *
+ * const result = await run(definition);
+ * if (result.kind !== "completed") throw new Error(`Run did not complete: ${result.kind}`);
+ * const outcome = result.snapshot.checks.find(
+ *   ({ checkId }) => checkId === nodeProbe.checkId
+ * )?.outcome;
+ * if (outcome?.status !== "passed" || outcome.data.exitCode !== 0) {
+ *   throw new Error("Node probe did not produce the expected passed outcome");
+ * }
+ * ```
+ */
+export declare function commandCheck<const Id extends string, const FinalData extends object>(input: CommandCheckInput<Id, Readonly<{
+    readonly execute: AfterCommandExecution<FinalData>;
+    readonly parseData?: never;
+}>>): CommandCheckWithAfterCommand<Id, FinalData>;
+export declare function commandCheck<const Id extends string, const Parser extends CheckDataParser>(input: CommandCheckInput<Id, Readonly<{
+    readonly execute: AfterCommandExecution<NoInfer<ReturnType<Parser>>>;
+    readonly parseData: Parser;
+}>>): TypedCommandCheck<Id, Parser>;
+export declare function commandCheck<const Id extends string>(input: CommandCheckInput<Id>): CommandCheck<Id>;

package/types/package-checks/command-check/contract.d.ts

@@ -0,0 +1,108 @@
+import type { Check, CheckDataParser, CheckDependencies, CheckExecutionContext, CheckFlagEnablement, CheckProjectContext, CheckResourceClaims, CheckResult, CheckWithOptions, DeepReadonly, InheritableCheckCollection, TypedCheckWithOptions } from "../../check/check.ts";
+/** command Check 的显式环境策略；默认 exact-empty，避免定义时读取 ambient environment。 */
+export type CommandCheckEnvironment = Readonly<{
+    readonly mode: "exact";
+    readonly variables?: Readonly<Record<string, string>>;
+}> | Readonly<{
+    readonly mode: "inherit";
+    readonly overrides?: Readonly<Record<string, string | null>>;
+}>;
+/** child stdout/stderr 的处理边界；默认 discard。 */
+export type CommandCheckOutput = Readonly<{
+    readonly mode: "discard" | "transcript";
+}>;
+/** command 以 numeric exit status 结束时发布的唯一 final data。 */
+export interface CommandCheckFinalData {
+    /** child process 的 numeric exit status。 */
+    readonly exitCode: number;
+}
+/** 已完整结束且只在 invocation-local callback 中可见的 child material。 */
+export interface CompletedCommand {
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly stdout: string;
+}
+/** spawn 前 environment resolver 可读取的最小 invocation context。 */
+export interface CommandEnvironmentContext {
+    readonly dependencies: CheckDependencies;
+    readonly options: DeepReadonly<ResolvedCommandCheckOptions>;
+    readonly project: CheckProjectContext;
+    readonly signal: AbortSignal;
+}
+/** 完整 command 后 caller-owned settlement 可读取的 context。 */
+export type AfterCommandContext = CheckExecutionContext<ResolvedCommandCheckOptions> & Readonly<{
+    readonly command: CompletedCommand;
+}>;
+/** 完整 command 的 caller-owned settlement callback。 */
+export type AfterCommandExecution<FinalData extends object = object> = (this: void, context: AfterCommandContext) => CheckResult<FinalData> | Promise<CheckResult<FinalData>>;
+/** command 完成后的可选 caller-owned settlement 与 typed-provider parser。 */
+export type AfterCommand<FinalData extends object = object> = Readonly<{
+    readonly execute: AfterCommandExecution<FinalData>;
+    readonly parseData?: CheckDataParser | undefined;
+}>;
+/** spawn 前解析此次 command closed environment policy 的 callback。 */
+export type CommandEnvironmentResolver = (this: void, context: CommandEnvironmentContext) => CommandCheckEnvironment | Promise<CommandCheckEnvironment>;
+/** command Check 自己产生的 stable unavailable reason code。 */
+export type CommandCheckUnavailableReasonCode = "command-environment-resolution-failed" | "command-output-limit-exceeded" | "command-start-failed" | "command-terminated-by-signal" | "command-timeout" | "command-transcript-unavailable" | "invalid-options";
+/** `commandCheck` 的 closed authoring input；ordinary Check composition fields 原样交由 Core 处理。 */
+interface CommandCheckBaseInput<Id extends string> {
+    readonly checkId: Id;
+    readonly displayName: string;
+    readonly executable: string;
+    readonly arguments?: readonly string[];
+    readonly workingDirectory?: string;
+    readonly timeoutMs: number;
+    readonly outputByteLimit: number;
+    readonly output?: CommandCheckOutput;
+    readonly enabledByFlags?: CheckFlagEnablement;
+    readonly checks?: readonly Check[];
+    readonly dependsOn?: InheritableCheckCollection<string>;
+    readonly observes?: InheritableCheckCollection<string>;
+    readonly maxParallel?: number;
+    readonly admissionPriority?: number;
+    readonly mutex?: InheritableCheckCollection<string>;
+    readonly resourceClaims?: CheckResourceClaims;
+    readonly omitQuietPassedRow?: true;
+}
+/** Static environment 与 invocation-time resolver 互斥；两者都省略时使用 exact-empty。 */
+export type CommandCheckInput<Id extends string = string, After extends AfterCommand | undefined = undefined> = CommandCheckBaseInput<Id> & (Readonly<{
+    readonly environment?: CommandCheckEnvironment;
+    readonly resolveEnvironment?: never;
+}> | Readonly<{
+    readonly environment?: never;
+    readonly resolveEnvironment: CommandEnvironmentResolver;
+}>) & (After extends undefined ? Readonly<{
+    readonly afterCommand?: undefined;
+}> : Readonly<{
+    readonly afterCommand: After;
+}>);
+/** command constructor materializes、冻结并在 preparation 再次验证的内部完整 options。 */
+export interface ResolvedCommandCheckOptions {
+    readonly arguments: readonly string[];
+    readonly environment: Readonly<{
+        readonly mode: "exact";
+        readonly variables: Readonly<Record<string, string>>;
+    }> | Readonly<{
+        readonly mode: "inherit";
+        readonly overrides: Readonly<Record<string, string | null>>;
+    }>;
+    readonly executable: string;
+    readonly output: Readonly<{
+        readonly mode: "discard" | "transcript";
+    }>;
+    readonly outputByteLimit: number;
+    readonly timeoutMs: number;
+    /** `null` 表示 execution 时使用 invocation project root。 */
+    readonly workingDirectory: string | null;
+}
+/** 可放入普通 Project Definition 的 process-backed Check。 */
+export type CommandCheck<Id extends string = string> = CheckWithOptions<Id, ResolvedCommandCheckOptions> & Readonly<{
+    execute(this: void, context: CheckExecutionContext<ResolvedCommandCheckOptions>): CheckResult<CommandCheckFinalData> | Promise<CheckResult<CommandCheckFinalData>>;
+}>;
+/** 带 caller-owned completion callback 的 ordinary command Check。 */
+export type CommandCheckWithAfterCommand<Id extends string, FinalData extends object> = Omit<CheckWithOptions<Id, ResolvedCommandCheckOptions>, "execute"> & Readonly<{
+    execute(this: void, context: CheckExecutionContext<ResolvedCommandCheckOptions>): CheckResult<FinalData> | Promise<CheckResult<FinalData>>;
+}>;
+/** 带 caller-owned completion callback 与 parser 的 typed-provider command Check。 */
+export type TypedCommandCheck<Id extends string, Parser extends CheckDataParser> = TypedCheckWithOptions<Id, ResolvedCommandCheckOptions, Parser>;
+export {};

package/types/package-checks/command-check/execution.d.ts

@@ -0,0 +1,7 @@
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import type { AfterCommand, CommandEnvironmentResolver, ResolvedCommandCheckOptions } from "./contract.ts";
+/** Executes one validated no-shell command and releases all child material after optional transcript persistence. */
+export declare function executeCommandCheck(context: CheckExecutionContext<ResolvedCommandCheckOptions>, executionExtensions?: Readonly<{
+    readonly afterCommand?: AfterCommand | undefined;
+    readonly resolveEnvironment?: CommandEnvironmentResolver | undefined;
+}>): Promise<CheckResult>;

package/types/package-checks/command-check/options.d.ts

@@ -0,0 +1,11 @@
+import type { AfterCommand, CommandEnvironmentResolver, ResolvedCommandCheckOptions } from "./contract.ts";
+/** Snapshots one closed constructor input and materializes every command-owned omission. */
+export declare function resolveCommandCheckInput(input: unknown): Readonly<{
+    readonly afterCommand: AfterCommand | undefined;
+    readonly options: ResolvedCommandCheckOptions;
+    readonly resolveEnvironment: CommandEnvironmentResolver | undefined;
+}> | undefined;
+/** Resolves one callback-produced environment to the same complete closed shape as static input. */
+export declare function resolveCommandCheckEnvironment(value: unknown): ResolvedCommandCheckOptions["environment"] | undefined;
+/** Revalidates the complete resolved shape before execution. */
+export declare function isValidResolvedCommandCheckOptions(value: unknown): value is ResolvedCommandCheckOptions;

package/types/package-checks/command-check/transcript.d.ts

@@ -0,0 +1,8 @@
+/** Atomically replaces this Check-local fixed transcript without exposing command inputs or native errors. */
+export declare function writeCommandTranscript(artifactDirectory: string, contents: string): Promise<boolean>;
+export declare function runningTranscript(): string;
+export declare function closedTranscript(input: {
+    readonly status: "passed" | "failed" | "unavailable";
+    readonly stderr: string;
+    readonly stdout: string;
+}): string;

package/types/package-checks/duplicate-detection/default-check.d.ts

@@ -1,11 +1,14 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
 import { parseDuplicateDetectionData } from "./final-data.ts";
 import type { DuplicateDetectionOptions, ResolvedDuplicateDetectionOptions } from "./options.ts";
 /**
  * 使用可省略的区域、cache 与 scanner policy 构造一个完整 duplicate-detection Check。
  *
  * @param options - 省略字段由 package 补齐；显式 files 数组作为对应字段的完整替换值。
- * @returns 固定 `duplicate-detection` identity、完整冻结 options、preflight 与 execution。
+ * @returns 固定 `duplicate-detection` identity、完整冻结 options、preparation 与 execution。
  * @throws {TypeError} input 含未知字段、空 area、非法阈值、非法 cache 或 scanner policy 时抛出。
  */
-export declare function duplicateDetection(options?: DuplicateDetectionOptions): TypedCheckWithOptions<"duplicate-detection", ResolvedDuplicateDetectionOptions, typeof parseDuplicateDetectionData>;
+export declare function duplicateDetection(options?: DuplicateDetectionOptions<"duplicate-detection">): TypedCheckWithOptions<"duplicate-detection", ResolvedDuplicateDetectionOptions, typeof parseDuplicateDetectionData>;
+export declare function duplicateDetection<const Id extends string>(options: DuplicateDetectionOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedDuplicateDetectionOptions, typeof parseDuplicateDetectionData>;
+export declare function duplicateDetection(options: DuplicateDetectionOptions): TypedCheckWithOptions<string, ResolvedDuplicateDetectionOptions, typeof parseDuplicateDetectionData>;

package/types/package-checks/duplicate-detection/finding-messages.d.ts

@@ -1,5 +1,5 @@
 import type { CheckMessage } from "../../check/check.ts";
-import type { FindingWaiverReconciliation } from "../../finding-waivers/reconciliation.ts";
+import type { FindingWaiverReconciliation } from "../../package-tools/finding-waivers/reconciliation.ts";
 import { type DuplicateRecordCandidate } from "./records.ts";
 /** Projects duplicate Records into bounded, project-relative terminal summaries. */
 export declare function duplicateFindingMessages(candidates: readonly DuplicateRecordCandidate[]): readonly CheckMessage[];

package/types/package-checks/duplicate-detection/options.d.ts

@@ -1,6 +1,7 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
 import type { FindingPolicy } from "../code-quality-findings/policy.ts";
-import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 export type DuplicateDetectionScannerCommand = 
 /** 使用随 `@zxyycom/vibe-check` 安装的 jscpd。 */
 Readonly<{
@@ -51,7 +52,7 @@ export interface DuplicateDetectionCodeAreaOptions {
     readonly minimumTokens?: number;
 }
 /** `duplicateDetection(options?)` 接受并补齐默认值的公开策略。 */
-export interface DuplicateDetectionOptions {
+export interface DuplicateDetectionOptions<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
     /** 省略时建立默认 `project` 区域；显式映射必须非空。 */
     readonly codeAreas?: Readonly<Record<string, DuplicateDetectionCodeAreaOptions>>;
     readonly cache?: DuplicateDetectionCacheOptions;
@@ -61,7 +62,7 @@ export interface DuplicateDetectionOptions {
     readonly findingWaivers?: readonly DuplicateDetectionFindingWaiver[];
     readonly scanner?: DuplicateDetectionScannerOptions;
 }
-/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+/** 构造函数生成并由 Check preparation/execution 消费的完整 options。 */
 export interface ResolvedDuplicateDetectionOptions {
     readonly cache: Readonly<{
         readonly directory: string;

package/types/package-checks/duplicate-detection/records.d.ts

@@ -1,4 +1,4 @@
-import type { MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { MaterializedFindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 import { type FindingWaiverAuditRecordData, type FindingWaiverRecordAudit } from "../code-quality-findings/finding-waiver-evidence.ts";
 import type { DuplicateCodeFragment } from "./measurement-model.ts";
 import type { DuplicateDetectionFindingIdentity, ResolvedDuplicateDetectionOptions } from "./options.ts";

package/types/package-checks/file-metrics/constructor.d.ts

@@ -1,11 +1,14 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
 import { parseFileMetricsData } from "./final-data.ts";
 import type { FileMetricsOptions, ResolvedFileMetricsOptions } from "./options.ts";
 /**
  * 使用可省略的区域、代码行与 scanner policy 构造一个完整 file-metrics Check。
  *
  * @param options - 省略字段由 package 补齐；显式 files 数组作为对应字段的完整替换值。
- * @returns 固定 `file-metrics` identity、完整冻结 options、preflight 与 execution。
+ * @returns 固定 `file-metrics` identity、完整冻结 options、preparation 与 execution。
  * @throws {TypeError} input 含未知字段、空 area、非法代码行 policy、非法 waiver 或空 executable 时抛出。
  */
-export declare function fileMetrics(options?: FileMetricsOptions): TypedCheckWithOptions<"file-metrics", ResolvedFileMetricsOptions, typeof parseFileMetricsData>;
+export declare function fileMetrics(options?: FileMetricsOptions<"file-metrics">): TypedCheckWithOptions<"file-metrics", ResolvedFileMetricsOptions, typeof parseFileMetricsData>;
+export declare function fileMetrics<const Id extends string>(options: FileMetricsOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedFileMetricsOptions, typeof parseFileMetricsData>;
+export declare function fileMetrics(options: FileMetricsOptions): TypedCheckWithOptions<string, ResolvedFileMetricsOptions, typeof parseFileMetricsData>;

package/types/package-checks/file-metrics/options.d.ts

@@ -1,6 +1,7 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
 import type { FindingPolicy } from "../code-quality-findings/policy.ts";
-import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 /** `fileMetrics` 构造函数可省略的 SCC 可执行文件策略。 */
 export interface FileMetricsScannerOptions {
     /** 省略时直接执行 `scc`；显式命令必须直接接受 adapter 拥有的 SCC 参数。 */
@@ -41,7 +42,7 @@ export interface FileMetricsFindingIdentity {
 /** 一项 file-metrics finding 的声明式豁免；执行时仍会扫描并发布该 finding。 */
 export type FileMetricsFindingWaiver = FindingWaiver<FileMetricsFindingIdentity>;
 /** `fileMetrics(options?)` 接受并补齐默认值的公开策略。 */
-export interface FileMetricsOptions {
+export interface FileMetricsOptions<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
     /** 省略时建立默认 `project` 区域；显式映射必须非空。 */
     readonly codeAreas?: Readonly<Record<string, FileMetricsCodeAreaOptions>>;
     /** 省略时为 `non-blocking`；区域可局部覆盖。 */
@@ -51,7 +52,7 @@ export interface FileMetricsOptions {
     /** 省略时直接执行 `scc`；CLI 协议由 owning adapter 固定。 */
     readonly scanner?: FileMetricsScannerOptions;
 }
-/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+/** 构造函数生成并由 Check preparation/execution 消费的完整 options。 */
 export interface ResolvedFileMetricsOptions {
     readonly codeAreas: Readonly<Record<string, ResolvedFileMetricsCodeAreaOptions>>;
     readonly findingWaivers: readonly FileMetricsFindingWaiver[];

package/types/package-checks/file-metrics/records.d.ts

@@ -1,6 +1,6 @@
 import type { FileMetric } from "./measurement-model.ts";
 import type { FileMetricsFindingIdentity, ResolvedFileMetricsCodeAreaOptions } from "./options.ts";
-import type { MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { MaterializedFindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 import { type FindingWaiverAuditRecordData, type FindingWaiverRecordAudit } from "../code-quality-findings/finding-waiver-evidence.ts";
 interface FileMetricsAreaPolicyContext {
     readonly areaIdsByPath: ReadonlyMap<string, readonly string[]>;

package/types/package-checks/file-metrics/scc/batch-planner.d.ts

@@ -0,0 +1,18 @@
+/** SCC adapter 的私有 Windows argv 传输上限；不属于 scanner options。 */
+export declare const SCC_BATCH_COMMAND_LINE_CEILING = 28000;
+export type SccBatchPlan = {
+    readonly batches: readonly (readonly string[])[];
+    readonly ok: true;
+} | {
+    readonly error: string;
+    readonly ok: false;
+};
+/**
+ * 返回 Windows command-line serialization 的保守 UTF-16 code-unit 上界。
+ *
+ * 每个 argument 都按最多双倍转义并保留一对引号，arguments 之间保留一个分隔符，
+ * 最后保留 CreateProcessW 所需的终止 NUL。
+ */
+export declare function estimateSccCommandLineCodeUnits(argumentsToEstimate: readonly string[]): number;
+/** 将已批准的 exact paths 按固定 SCC protocol 稳定地切为可传输 batches。 */
+export declare function planSccBatches(executable: string, fixedArguments: readonly string[], includePaths: readonly string[], ceiling?: number): SccBatchPlan;

package/types/package-checks/file-metrics/scc/logical-scan-resources.d.ts

@@ -0,0 +1,14 @@
+export declare const SCC_LOGICAL_SCAN_TIMEOUT_MS = 300000;
+export interface SccLogicalScanResources {
+    readonly deadlineNanoseconds: bigint;
+    stderrRemainingBytes: number;
+    stdoutRemainingBytes: number;
+}
+/** 为一次 logical SCC scan 建立共享 deadline 与 stdout/stderr 预算。 */
+export declare function beginSccLogicalScanResources(startedNanoseconds: bigint, timeoutMilliseconds?: number, outputBudgetBytes?: number): SccLogicalScanResources;
+/** 计算下一个 batch 可使用的完整毫秒数；deadline 到期时不再启动 process。 */
+export declare function remainingSccBatchTimeoutMs(resources: SccLogicalScanResources, nowNanoseconds: bigint): number | null;
+/** 以两个 stream 中较小的余量限制本次 process 的 maxBuffer。 */
+export declare function remainingSccBatchMaxBuffer(resources: SccLogicalScanResources): number | null;
+/** 记录一次 process 的 UTF-8 output；任一 stream 超出完整 logical-scan 预算即失败。 */
+export declare function consumeSccProcessOutput(resources: SccLogicalScanResources, stdout: string, stderr: string): boolean;

package/types/package-checks/function-metrics/analyzer/extensions/protocol.d.ts

@@ -61,9 +61,9 @@ export interface LizardExtension {
 }
 /** Python resolves extension class attributes and static methods through instances. */
 export interface LizardExtensionClassMetadata {
-    readonly ordering_index?: number;
-    readonly FUNCTION_INFO?: FunctionInfoDefinitions;
-    readonly silent_all_others?: boolean;
+    readonly ordering_index?: number | undefined;
+    readonly FUNCTION_INFO?: FunctionInfoDefinitions | undefined;
+    readonly silent_all_others?: boolean | undefined;
 }
 /** A directly registered class is an opaque descriptor, not a constructor to invoke at load time. */
 export type LizardExtensionConstructor = LizardExtensionClassMetadata & {

package/types/package-checks/function-metrics/constructor.d.ts

@@ -1,11 +1,14 @@
 import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { type PackageCheckIdentityInput } from "../check-authoring.ts";
 import { parseFunctionMetricsData } from "./final-data.ts";
 import type { FunctionMetricsOptions, ResolvedFunctionMetricsOptions } from "./options.ts";
 /**
  * 使用可省略的区域、阈值与 finding policy 构造一个完整 function-metrics Check。
  *
  * @param options - 省略字段由 package 补齐；显式 files 数组完整替换对应字段的默认数组。
- * @returns 固定 `function-metrics` identity、完整冻结 options、preflight 与 execution。
+ * @returns 固定 `function-metrics` identity、完整冻结 options、preparation 与 execution。
  * @throws {TypeError} input 含未知字段、空 area、非法 finding policy/waiver 或非法 limit 时抛出。
  */
-export declare function functionMetrics(options?: FunctionMetricsOptions): TypedCheckWithOptions<"function-metrics", ResolvedFunctionMetricsOptions, typeof parseFunctionMetricsData>;
+export declare function functionMetrics(options?: FunctionMetricsOptions<"function-metrics">): TypedCheckWithOptions<"function-metrics", ResolvedFunctionMetricsOptions, typeof parseFunctionMetricsData>;
+export declare function functionMetrics<const Id extends string>(options: FunctionMetricsOptions<Id> & PackageCheckIdentityInput<Id>): TypedCheckWithOptions<Id, ResolvedFunctionMetricsOptions, typeof parseFunctionMetricsData>;
+export declare function functionMetrics(options: FunctionMetricsOptions): TypedCheckWithOptions<string, ResolvedFunctionMetricsOptions, typeof parseFunctionMetricsData>;

package/types/package-checks/function-metrics/finding-messages.d.ts

@@ -1,5 +1,5 @@
 import type { CheckMessage } from "../../check/check.ts";
-import type { FindingWaiverReconciliation } from "../../finding-waivers/reconciliation.ts";
+import type { FindingWaiverReconciliation } from "../../package-tools/finding-waivers/reconciliation.ts";
 import { type FunctionInputRejectedCandidate, type FunctionRecordCandidate } from "./records.ts";
 type FunctionFindingCandidate = FunctionRecordCandidate | FunctionInputRejectedCandidate;
 /** Projects metric and rejected-input Records into bounded terminal summaries. */

package/types/package-checks/function-metrics/options.d.ts

@@ -1,6 +1,7 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
 import type { FindingPolicy } from "../code-quality-findings/policy.ts";
-import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 /** `functionMetrics` 构造函数可省略的文件选择策略。 */
 export type FunctionMetricsFileOptions = ProjectFileSelectionOptions;
 /** `functionMetrics` 构造函数可省略的函数指标上限。 */
@@ -51,7 +52,7 @@ export interface FunctionMetricsFindingIdentity {
 /** 一项 function-metrics metric finding 的声明式豁免。 */
 export type FunctionMetricsFindingWaiver = FindingWaiver<FunctionMetricsFindingIdentity>;
 /** `functionMetrics(options?)` 接受并补齐默认值的公开策略。 */
-export interface FunctionMetricsOptions {
+export interface FunctionMetricsOptions<Id extends string = string> extends PackageCheckAuthoringOptions<Id> {
     /** 省略时建立默认 `project` 区域；显式映射必须非空，且每个区域必须声明 `files`。 */
     readonly codeAreas?: Readonly<Record<string, FunctionMetricsCodeAreaOptions>>;
     /** 省略时为 `non-blocking`；区域可局部覆盖。 */
@@ -59,7 +60,7 @@ export interface FunctionMetricsOptions {
     /** 省略时没有豁免；只匹配 normal metric finding，不匹配 input rejection。 */
     readonly findingWaivers?: readonly FunctionMetricsFindingWaiver[];
 }
-/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+/** 构造函数生成并由 Check preparation/execution 消费的完整 options。 */
 export interface ResolvedFunctionMetricsOptions {
     readonly codeAreas: Readonly<Record<string, ResolvedFunctionMetricsCodeAreaOptions>>;
     readonly findingWaivers: readonly FunctionMetricsFindingWaiver[];

package/types/package-checks/function-metrics/records.d.ts

@@ -1,5 +1,5 @@
 import { type FunctionMetricAnalysis } from "./analysis.ts";
-import type { MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { MaterializedFindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 import { type FindingWaiverAuditRecordData, type FindingWaiverRecordAudit } from "../code-quality-findings/finding-waiver-evidence.ts";
 import type { FunctionMetricsAreaInput } from "./measurement-model.ts";
 import type { FunctionMetricsFindingIdentity, FunctionMetricsFindingMetric } from "./options.ts";

package/types/package-checks/host-environment/git.d.ts

@@ -5,6 +5,8 @@ export type GitCommitOptions = {
     readonly sha: string;
 };
 export declare function runGit(options: RunGitOptions): ProcessResult;
+/** Renders the actionable failure evidence shared by Git operation boundaries. */
+export declare function gitFailureDetail(result: ProcessResult): string;
 export declare function gitHeadSha(cwd: string): string | null;
 export declare function gitCommitDate(options: GitCommitOptions): string | null;
 export declare function gitCommitTitle(options: GitCommitOptions): string | null;

package/types/package-checks/host-environment/path.d.ts

@@ -1,3 +1 @@
-export declare function toSlashPath(filePath: string): string;
-/** 判断值是否已是跨平台可稳定发布的 project-root-relative slash path。 */
-export declare function isNormalizedProjectRelativePath(value: unknown): value is string;
+export { isNormalizedProjectRelativePath, toSlashPath } from "../../data-boundary/project-path.ts";