@zxyycom/vibe-check 0.0.1 → 0.0.3

package/types/check-settlement/session.d.ts

@@ -1,7 +1,7 @@
 import type { CheckDescriptor } from "../check/descriptor.ts";
 import type { CheckOutcome } from "../check/check.ts";
 import { type RecordSubmissionResult } from "./record-store.ts";
-import type { CoreSnapshot } from "./facts.ts";
+import type { CoreRecord, CoreSnapshot } from "./facts.ts";
 export type { RecordSubmissionResult } from "./record-store.ts";
 export interface CoreCheckRegistration {
     readonly definition: CheckDescriptor;
@@ -26,6 +26,8 @@ export interface AuthorCheckSettlement {
 export interface CoreCheckSession {
     openCheckScope(checkId: string): TrustedCheckScope;
     readSettledCheckOutcome(checkId: string): CheckOutcome;
+    /** Product-private readback used only after this Check's terminal settlement. */
+    readSettledCheckRecords(checkId: string): readonly CoreRecord[];
     closeUnresolvedAsCancelled(): readonly CancelledCheckClosure[];
     freeze(): CoreSnapshot;
 }

package/types/data-boundary/canonical-data.d.ts

@@ -1,13 +1,36 @@
 import type { CanonicalJsonObject, CanonicalJsonValue } from "./canonical-json.ts";
 export type { CanonicalJsonObject, CanonicalJsonPrimitive, CanonicalJsonValue } from "./canonical-json.ts";
 /**
- * Materializes arbitrary author data without property reads or JSON hooks.
- * The returned graph is detached, prototype-safe, and deeply frozen before it
- * becomes a Core fact. Canonical text order is applied explicitly at serialization.
+ * 将输入规范化为独立且递归冻结的 canonical JSON 对象副本。
+ *
+ * 递归内容只接受普通对象或 null-prototype 对象、标准无空洞数组和有限 JSON 基本值；仅当顶层结果是
+ * 非数组对象时返回该副本。输出对象使用 null prototype，输出对象和数组均独立于输入且递归冻结。不调用
+ * getter 或 `toJSON`；无效输入、循环引用或反射失败返回 `undefined`。反射 Proxy 时仍可能执行其 trap，
+ * 不隔离 trap 的副作用。
  */
 export declare function canonicalizeJsonObject(value: unknown): CanonicalJsonObject | undefined;
+/**
+ * 将输入规范化为独立且递归冻结的 canonical JSON 值副本。
+ *
+ * 接受 `null`、boolean、string、有限 number、普通对象或 null-prototype 对象，以及标准无空洞数组；
+ * `-0` 转换为 `0`，输出对象使用 null prototype。拒绝存取器、稀疏数组、不可枚举的自有属性、非有限
+ * number 和其它 prototype。不调用 getter 或 `toJSON`；无效输入、循环引用或反射失败返回 `undefined`。
+ * 反射 Proxy 时仍可能执行其 trap，不隔离 trap 的副作用。`CanonicalJsonPrimitive` 的 `number` 在
+ * TypeScript 中仍可表示 `NaN`，有限性只能由本函数在运行时检查。
+ */
 export declare function canonicalizeJsonValue(value: unknown): CanonicalJsonValue | undefined;
-/** Serializes detached canonical JSON with explicit lexical object-key ordering. */
+/**
+ * 规范化输入后生成确定性的无额外空白 JSON 文本。
+ *
+ * 对象键按固定的 lexical `<` 顺序输出，不承诺遵循外部 canonical-JSON 标准。即使同一对象已经过
+ * 规范化，`JSON.stringify` 仍按 ECMAScript 的整数索引键顺序输出，不能替代本函数。输入规则与 Proxy
+ * 边界同 `canonicalizeJsonValue`；无效输入或无法反射的 Proxy 均抛出 `TypeError`。
+ */
 export declare function canonicalJsonText(value: unknown): string;
-/** Emits canonical UTF-8 JSON without invoking author getters or `toJSON`. */
+/**
+ * 规范化输入后生成与 `canonicalJsonText` 相同的确定性 UTF-8 JSON 字节。
+ *
+ * 函数自行完成规范化与固定键排序，不要求调用方先取得 canonical JSON 值。输入规则、Proxy 边界和
+ * `TypeError` 失败方式与 `canonicalJsonText` 相同。
+ */
 export declare function canonicalJsonBytes(value: unknown): Uint8Array;

package/types/data-boundary/canonical-json.d.ts

@@ -1,6 +1,23 @@
-/** Package-private static shape for Product's detached canonical JSON facts. */
+/**
+ * Canonical JSON 基本值的静态结构类型。
+ *
+ * TypeScript 的 `number` 无法在静态层区分有限值与 `NaN` / `Infinity`；因此此类型不能证明值已经由
+ * canonical API 规范化。运行时只接受有限 number，并将 `-0` 转换为 `0`。
+ */
 export type CanonicalJsonPrimitive = boolean | null | number | string;
+/**
+ * Canonical JSON 值的递归只读静态结构类型。
+ *
+ * 它描述基本值、数组和对象能够如何组合，便于声明参数和结果；不证明值已经通过 canonical API 的
+ * 运行时规范化、递归冻结或循环检查。
+ */
 export type CanonicalJsonValue = CanonicalJsonPrimitive | readonly CanonicalJsonValue[] | CanonicalJsonObject;
+/**
+ * Canonical JSON 对象的只读静态结构类型。
+ *
+ * 该类型不证明值来自 canonical API。API 实际返回的对象使用 null prototype，没有继承的对象方法；
+ * 检查属性时使用 `Object.hasOwn`，不要调用 `value.hasOwnProperty`。
+ */
 export interface CanonicalJsonObject {
     readonly [key: string]: CanonicalJsonValue;
 }

package/types/data-boundary/closed-values.d.ts

@@ -1,8 +1,32 @@
 export declare function snapshotPlainRecord(value: unknown): Readonly<Record<string, unknown>> | undefined;
 export declare function snapshotClosedRecord(value: unknown): Readonly<Record<string, unknown>> | undefined;
+/**
+ * 取得字段集合恰好匹配调用方字段表的闭合普通记录外层浅快照。
+ *
+ * 输入必须是使用 `Object.prototype` 或 null prototype 的非数组对象，且每个自有属性都是可枚举数据属性。
+ * 调用方持有的 `keys` 必须是稳定、无重复的字符串列表；缺字段、多字段、symbol 键、存取器或不可枚举属性
+ * 均返回 `undefined`。成功结果是使用 `Object.prototype` 的冻结浅副本：只固定外层字段，保留 callback、
+ * `undefined` 与嵌套对象或数组的原引用，调用方仍须逐字段验证。这不是 JSON 验证器；不调用 getter，
+ * 但反射 Proxy 可能执行其 trap，反射失败时返回 `undefined`。
+ */
+export declare function snapshotExactClosedRecord(value: unknown, keys: readonly string[]): Readonly<Record<string, unknown>> | undefined;
+/**
+ * 取得标准无空洞数组的外层浅快照。
+ *
+ * 输入必须使用 `Array.prototype`，除标准 `length` 和可枚举索引外没有其它自有属性，也不能包含存取器；
+ * 稀疏数组、额外属性或其它不符合条件的输入返回 `undefined`。成功结果是冻结浅副本，只固定数组结构，
+ * 保留 callback、`undefined` 与嵌套值的原引用，不检查元素的业务类型或 JSON 合法性。不调用存取器，
+ * 但反射 Proxy 可能执行其 trap，反射失败时返回 `undefined`。
+ */
 export declare function snapshotClosedArray(value: unknown): readonly unknown[] | undefined;
 export declare function hasExactPlainRecordKeys(value: Readonly<Record<string, unknown>>, keys: readonly string[]): boolean;
 export declare function hasRequiredAndOptionalRecordKeys(value: Readonly<Record<string, unknown>>, keys: Readonly<{
     readonly optional: readonly string[];
     readonly required: readonly string[];
 }>): boolean;
+export interface ClosedPolicyRecordKeys {
+    readonly optional?: readonly string[];
+    readonly required?: readonly string[];
+}
+/** Snapshots an authoring record whose keys are limited to one required/optional policy. */
+export declare function snapshotClosedPolicyRecord(value: unknown, keys: ClosedPolicyRecordKeys): Readonly<Record<string, unknown>> | undefined;

package/types/data-boundary/config-glob.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Product config glob's single matcher boundary. Candidates use slash form;
+ * dot paths participate only when an explicit glob matches them.
+ */
+export declare function matchesAnyConfigGlob(candidatePath: string, configGlobs: readonly string[]): boolean;

package/types/data-boundary/project-path.d.ts

@@ -0,0 +1,4 @@
+/** Converts a host path spelling to the Product's slash-path form. */
+export declare function toSlashPath(filePath: string): string;
+/** Recognizes one stable project-root-relative slash path. */
+export declare function isNormalizedProjectRelativePath(value: unknown): value is string;

package/types/data-boundary/value-shapes.d.ts

@@ -2,3 +2,6 @@ export declare function isRecord(value: unknown): value is Record<string, unknow
 export declare function isNonArrayRecord(value: unknown): value is Record<string, unknown>;
 export declare function isUnknownArray(value: unknown): value is unknown[];
 export declare function isStringArray(value: unknown): value is string[];
+export declare function isNonEmptyString(value: unknown): value is string;
+export declare function isPositiveSafeInteger(value: unknown): value is number;
+export declare function isNonNegativeSafeInteger(value: unknown): value is number;

package/types/index.d.ts

@@ -1,13 +1,19 @@
 /**
- * Vibe Check 是由项目在 Bun runtime 中调用的 TypeScript API，用于定义并执行项目质量 Check。
+ * Vibe Check 是由项目在 Node runtime 中调用的 TypeScript API，用于定义并执行项目质量 Check。
  * 所有公开能力从 package root 导入；package `README.md` 说明 consumer authoring、结果读取和分发范围。
  *
  * @packageDocumentation
  */
+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 { DuplicateDetectionOptions, ResolvedDuplicateDetectionOptions } from "./package-checks/duplicate-detection/options.ts";
+export type { DuplicateDetectionFindingIdentity, DuplicateDetectionFindingLocation, DuplicateDetectionFindingWaiver, DuplicateDetectionOptions, ResolvedDuplicateDetectionOptions } from "./package-checks/duplicate-detection/options.ts";
 export type { DuplicateDetectionUnavailableReasonCode } from "./package-checks/duplicate-detection/execution.ts";
 export type { DuplicateDetectionRecordData } from "./package-checks/duplicate-detection/records.ts";
 export { fileMetrics } from "./package-checks/file-metrics/constructor.ts";
@@ -19,23 +25,37 @@ export type { FileMetricsRecordData } from "./package-checks/file-metrics/record
 export { functionMetrics } from "./package-checks/function-metrics/constructor.ts";
 export { parseFunctionMetricsData } from "./package-checks/function-metrics/final-data.ts";
 export type { FunctionMetricsFinalData } from "./package-checks/function-metrics/final-data.ts";
-export type { FunctionMetricsOptions, ResolvedFunctionMetricsOptions } from "./package-checks/function-metrics/options.ts";
+export type { FunctionMetricsFindingIdentity, FunctionMetricsFindingMetric, FunctionMetricsFindingWaiver, FunctionMetricsOptions, ResolvedFunctionMetricsOptions } from "./package-checks/function-metrics/options.ts";
 export type { FunctionMetricsUnavailableReasonCode } from "./package-checks/function-metrics/execution.ts";
 export type { FunctionMetricsRecordData } from "./package-checks/function-metrics/records.ts";
+export { secretDetection } from "./package-checks/secret-detection/default-check.ts";
+export { parseSecretDetectionData } from "./package-checks/secret-detection/final-data.ts";
+export type { SecretDetectionFinalData } from "./package-checks/secret-detection/final-data.ts";
+export type { ResolvedSecretDetectionOptions, SecretDetectionFindingIdentity, SecretDetectionFindingWaiver, SecretDetectionOptions } from "./package-checks/secret-detection/options.ts";
+export type { SecretDetectionUnavailableReasonCode } from "./package-checks/secret-detection/execution.ts";
+export type { SecretDetectionRecordData } from "./package-checks/secret-detection/records.ts";
 export { jsonSchemaValidation } from "./package-checks/json-schema-validation/default-check.ts";
 export { parseJsonSchemaValidationData } from "./package-checks/json-schema-validation/final-data.ts";
 export type { JsonSchemaValidationFinalData } from "./package-checks/json-schema-validation/final-data.ts";
-export type { JsonSchemaValidationOptions, ResolvedJsonSchemaValidationOptions } from "./package-checks/json-schema-validation/options.ts";
+export type { JsonSchemaIdentity, JsonSchemaIdentityMode, JsonSchemaInstanceBinding, JsonSchemaReferenceResolution, JsonSchemaReferenceSource, JsonSchemaValidationOptions, RegisteredJsonSchema, ResolvedJsonSchemaValidationOptions } from "./package-checks/json-schema-validation/options.ts";
 export type { JsonSchemaDocumentReason, JsonSchemaValidationRecordData, JsonSchemaValidationRecordReason, JsonSchemaValidationUnavailableCode } from "./package-checks/json-schema-validation/json-schema-validation.ts";
 export { jsonValidation } from "./package-checks/json-validation/default-check.ts";
 export { parseJsonValidationData } from "./package-checks/json-validation/final-data.ts";
 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";
@@ -44,14 +64,25 @@ 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 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, CheckExecution, CheckExecutionContext, CheckPreflight, CheckPreflightResult, CheckOutcome, CheckResult, CheckUnavailableReason, InheritableCheckCollection } from "./check/check.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 type { ProjectOutputs, ProjectDefinition, SchedulerPolicy } 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, 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";
 export type { RunResult } from "./project-run/result.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

@@ -0,0 +1,7 @@
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
+/**
+ * Snapshots the shared closed waiver envelope while leaving identity grammar to the producing Check.
+ */
+export declare function resolveFindingWaiverAuthoring<Identity>(value: unknown, resolveIdentity: (value: unknown) => Identity | undefined): readonly FindingWaiver<Identity>[] | undefined;
+/** Validates the complete resolved waiver list through the same authoring boundary. */
+export declare function validResolvedFindingWaivers<Identity>(value: unknown, resolveIdentity: (value: unknown) => Identity | undefined): value is readonly FindingWaiver<Identity>[];

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

@@ -0,0 +1,34 @@
+import type { CheckExecutionContext } from "../../check/check.ts";
+import type { FindingWaiverAudit, FindingWaiverReconciliation } from "../../package-tools/finding-waivers/reconciliation.ts";
+interface CodeQualityFindingCandidate {
+    readonly data: Readonly<{
+        readonly blocking: boolean;
+    }>;
+    readonly id: string;
+}
+type FindingRecordContext = Pick<CheckExecutionContext<object>, "records">;
+export type FindingWaiverRecordAudit = Readonly<Omit<FindingWaiverAudit, "status"> & {
+    readonly status: "overmatched" | "unused";
+}>;
+export type FindingWaiverAuditRecordData<Identity> = Readonly<{
+    readonly identity: Identity;
+    readonly kind: "finding-waiver-audit";
+    readonly matchCount: number;
+    readonly reason: string;
+    readonly status: "overmatched" | "unused";
+}>;
+/** Builds the common immutable data shared by Check-owned waiver audit Records. */
+export declare function buildFindingWaiverAuditRecordData<Identity>(identity: Identity, audit: FindingWaiverRecordAudit): FindingWaiverAuditRecordData<Identity>;
+/** Builds the shared hash-addressed audit Record used by structured identities. */
+export declare function buildHashedFindingWaiverAuditRecord<Identity>(identity: Identity, audit: FindingWaiverRecordAudit): Readonly<{
+    readonly data: FindingWaiverAuditRecordData<Identity>;
+    readonly id: string;
+}>;
+/** Publishes every reconciled metric Finding while preserving applied waiver evidence. */
+export declare function reportReconciledCodeQualityFindingRecords<Finding extends CodeQualityFindingCandidate>(context: FindingRecordContext, reconciliation: FindingWaiverReconciliation<Finding>): void;
+/** Publishes only unused/overmatched audit rows built by the identity-owning Check. */
+export declare function reportFindingWaiverAudits<Finding, AuditData extends object>(context: FindingRecordContext, reconciliation: FindingWaiverReconciliation<Finding>, buildRecord: (audit: FindingWaiverRecordAudit) => Readonly<{
+    readonly data: AuditData;
+    readonly id: string;
+}>): void;
+export {};

package/types/package-checks/code-quality-findings/policy.d.ts

@@ -5,7 +5,9 @@ export type FindingPolicy = (typeof FINDING_POLICIES)[number];
 export declare const DEFAULT_FINDING_POLICY: FindingPolicy;
 /** 三个代码质量 Check 正常完成时返回的精确 finding 计数。 */
 export interface FindingSummary {
+    /** 仍可处置且采用 blocking policy 的 finding 数；waived finding 不计入。 */
     readonly blockingFindingCount: number;
+    /** Check 发现的全部 finding 数，包括已 waived 或 non-blocking 的 finding。 */
     readonly findingCount: number;
 }
 /** 一项 finding 在 Check 自己结算前的领域中性处置。 */
@@ -16,5 +18,7 @@ export interface FindingSettlement {
 }
 export declare function resolveFindingPolicy(value: unknown, fallback?: FindingPolicy): FindingPolicy | undefined;
 export declare function validFindingPolicy(value: unknown): value is FindingPolicy;
+/** Resolves the closed, non-empty named area map shared by code-quality Checks. */
+export declare function resolveCodeAreaPolicyMap<Area>(value: unknown, defaultArea: () => Area, resolveArea: (candidate: unknown) => Area | undefined): Readonly<Record<string, Area>> | undefined;
 export declare function isBlockingFinding(policies: readonly FindingPolicy[]): boolean;
 export declare function settleFindings(findings: readonly FindingSettlement[]): CheckResult<FindingSummary>;

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/area-policy.d.ts

@@ -1,3 +1,3 @@
 import type { DuplicateCodeFragment, DuplicateDetectionAreaInput } from "./measurement-model.ts";
-/** Restores every matching code area and applies the strictest involved policy. */
+/** Retains fragments whose locations share an area and applies its strictest policy. */
 export declare function applyDuplicateAreaPolicy(fragments: readonly DuplicateCodeFragment[], areas: readonly DuplicateDetectionAreaInput[]): readonly DuplicateCodeFragment[] | undefined;

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

@@ -0,0 +1,7 @@
+import type { CheckMessage } from "../../check/check.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[];
+/** 将每项 duplicate-detection waiver audit 投影为可行动的 terminal message。 */
+export declare function duplicateWaiverMessages(reconciliation: FindingWaiverReconciliation<DuplicateRecordCandidate>): readonly CheckMessage[];

package/types/package-checks/duplicate-detection/finding-waiver-identity.d.ts

@@ -0,0 +1,3 @@
+import type { DuplicateDetectionFindingIdentity, DuplicateDetectionFindingLocation } from "./options.ts";
+export declare function resolveDuplicateDetectionFindingIdentity(value: unknown): DuplicateDetectionFindingIdentity | undefined;
+export declare function compareDuplicateFindingLocations(left: DuplicateDetectionFindingLocation, right: DuplicateDetectionFindingLocation): number;

package/types/package-checks/duplicate-detection/jscpd/command-resolution.d.ts

@@ -13,7 +13,7 @@ export type ResolvedJscpdCommand = Readonly<{
 }>;
 /**
  * package-provided scanner 的可移植 marker。真实 executable 只由私有 jscpd adapter 解析，避免公共
- * Definition 与 fingerprint 保存 consumer-specific Bun 或 package path。
+ * Definition 与 fingerprint 保存 consumer-specific runtime 或 package path。
  */
 export declare const DEFAULT_JSCPD_COMMAND: DuplicateDetectionScannerCommand;
 export declare function isPackageJscpdCommand(command: DuplicateDetectionScannerCommand): command is Extract<DuplicateDetectionScannerCommand, {