@zxyycom/vibe-check 0.0.1

package/types/package-checks/maintenance-reminders/measurement.d.ts

@@ -0,0 +1,10 @@
+import type { FirstParentHistory, MaintenanceReminder, ReminderMeasurement } from "./maintenance-reminders.ts";
+export declare function measureReminder(input: {
+    readonly entry: Readonly<MaintenanceReminder>;
+    readonly executable: string;
+    readonly history: FirstParentHistory;
+    readonly projectRoot: string;
+    readonly signal: AbortSignal;
+}): Promise<ReminderMeasurement>;
+export declare function parseCommitId(stdout: string): string | null;
+export declare function parseFirstParentHistory(stdout: string, headCommit: string): FirstParentHistory | undefined;

package/types/package-checks/maintenance-reminders/options-validation.d.ts

@@ -0,0 +1,3 @@
+export declare function validEntries(value: unknown): boolean;
+export declare function validGit(value: unknown): boolean;
+export declare function exactRecord(value: unknown, keys: readonly string[]): Readonly<Record<string, unknown>> | undefined;

package/types/package-checks/markdown-link-validation/default-check.d.ts

@@ -0,0 +1,27 @@
+import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { parseMarkdownLinkValidationData } from "./final-data.ts";
+import type { MarkdownLinkValidationOptions, ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+/**
+ * 使用可省略的 source、target 与 work-limit policy 构造离线 Markdown 引用 Check。
+ *
+ * @param options - 省略字段由 package 补齐；files 数组是完整替换值，limits fields 可分别省略。
+ * @returns 固定 `markdown-link-validation` identity、完整冻结 options、parser 与执行逻辑。
+ * @throws {TypeError} input 含未知字段、非法 target policy 或非法 work limit 时抛出。
+ * @example 离线 Markdown 本地链接完整性
+ * ```ts
+ * import { defineConfig, markdownLinkValidation, run } from "@zxyycom/vibe-check";
+ *
+ * const definition = defineConfig({
+ *   checks: [markdownLinkValidation()],
+ *   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}`);
+ * ```
+ */
+export declare function markdownLinkValidation(options?: MarkdownLinkValidationOptions): TypedCheckWithOptions<"markdown-link-validation", ResolvedMarkdownLinkValidationOptions, typeof parseMarkdownLinkValidationData>;

package/types/package-checks/markdown-link-validation/execution.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import { type MarkdownLocalResolutionReason, type MarkdownSourceReadFailureReason } from "./local-resolver.ts";
+import type { MarkdownLinkValidationFinalData } from "./final-data.ts";
+export declare const MARKDOWN_LINK_VALIDATION_CHECK_DEFINITION: {
+    readonly checkId: "markdown-link-validation";
+    readonly displayName: "Markdown link validation";
+};
+/** `markdown-link-validation` whole-Check unavailable outcome 的稳定 reason code。 */
+export type MarkdownLinkValidationUnavailableReason = "invalid-options" | "cancelled" | "occurrence-limit-exceeded" | "project-root-unavailable" | MarkdownLocalResolutionReason | MarkdownSourceReadFailureReason;
+/** 验证本 Check 选中的 Markdown source 的离线本地链接完整性。 */
+export declare function executeMarkdownLinkValidation(context: CheckExecutionContext<ResolvedMarkdownLinkValidationOptions>): Promise<CheckResult<MarkdownLinkValidationFinalData>>;

package/types/package-checks/markdown-link-validation/filesystem-probes.d.ts

@@ -0,0 +1,10 @@
+import { type EndpointProbe, type RootProbe } from "./local-resolution.ts";
+export declare function probeRootContainedPath(canonicalProjectRoot: string, candidatePath: string): Promise<RootProbe>;
+export declare function probeEndpoint(targetPath: string): Promise<EndpointProbe>;
+export declare function readRegularFile(filePath: string, maxBytes: number): Promise<Readonly<{
+    readonly ok: true;
+    readonly bytes: Uint8Array;
+}> | Readonly<{
+    readonly ok: false;
+    readonly reason: "too-large" | "unavailable";
+}>>;

package/types/package-checks/markdown-link-validation/final-data.d.ts

@@ -0,0 +1,10 @@
+/** `markdown-link-validation` 在 passed/failed outcome 中发布的主数据。 */
+export interface MarkdownLinkValidationFinalData {
+    readonly sourceFileCount: number;
+    readonly occurrenceCount: number;
+    readonly targetReadCount: number;
+    readonly findingCount: number;
+    readonly rejectedInputCount: number;
+}
+/** 验证计数不变量并脱离一份 canonical final-data object。 */
+export declare function parseMarkdownLinkValidationData(data: unknown): MarkdownLinkValidationFinalData;

package/types/package-checks/markdown-link-validation/local-resolution.d.ts

@@ -0,0 +1,92 @@
+import type { MarkdownHeading, ParsedMarkdownLinkFacts } from "./markdown-parser.ts";
+type RootExternalTargetMode = "ignore" | "report" | "validate";
+/** Markdown local-link finding Record 的稳定 reason。 */
+export type MarkdownLinkFindingReason = "anchor-on-directory" | "anchor-target-not-markdown" | "empty-directory" | "missing-anchor" | "missing-target" | "target-outside-project-root" | "unsupported-target-type";
+type MarkdownLocalResolutionReason = "invalid-local-destination" | "target-read-limit-exceeded" | "target-unavailable";
+type MarkdownSourceReadFailureReason = "markdown-parse-failed" | "source-unavailable" | "source-too-large";
+interface MarkdownLinkSource {
+    readonly path: string;
+    readonly facts: ParsedMarkdownLinkFacts;
+}
+interface MarkdownLocalResolver {
+    readSource(rootRelativePath: string, maxMarkdownBytes: number): Promise<MarkdownSourceReadResult>;
+    resolve(request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
+    readonly targetReadCount: number;
+}
+interface MarkdownLocalResolutionRequest {
+    readonly source: MarkdownLinkSource;
+    readonly rawDestination: string;
+    readonly rootExternalTargetMode: RootExternalTargetMode;
+    readonly requireExistingTargets: boolean;
+    readonly requireNonEmptyDirectories: boolean;
+    readonly validateSameDocumentAnchors: boolean;
+    readonly validateCrossDocumentAnchors: boolean;
+    readonly maxMarkdownBytes: number;
+}
+type MarkdownLocalResolverCreation = Readonly<{
+    readonly ok: true;
+    readonly resolver: MarkdownLocalResolver;
+}> | Readonly<{
+    readonly ok: false;
+    readonly reason: "project-root-unavailable";
+}>;
+type MarkdownSourceReadResult = Readonly<{
+    readonly ok: true;
+    readonly source: MarkdownLinkSource;
+}> | Readonly<{
+    readonly ok: false;
+    readonly reason: MarkdownSourceReadFailureReason;
+}>;
+type MarkdownLocalResolution = Readonly<{
+    readonly kind: "not-local" | "ignored";
+}> | Readonly<{
+    readonly kind: "valid";
+    readonly target: MarkdownSafeTargetDescriptor;
+}> | Readonly<{
+    readonly kind: "finding";
+    readonly reason: MarkdownLinkFindingReason;
+    readonly target: MarkdownSafeTargetDescriptor;
+}> | Readonly<{
+    readonly kind: "unavailable";
+    readonly reason: MarkdownLocalResolutionReason;
+}>;
+type MarkdownSafeTargetDescriptor = Readonly<{
+    readonly kind: "same-document" | "project-file" | "project-directory" | "project-path";
+    readonly path: string;
+    readonly fragment: string | null;
+}> | Readonly<{
+    readonly kind: "outside-project-root";
+}>;
+interface ParsedLocalDestination {
+    readonly path: string;
+    readonly fragment: string | null;
+    readonly isAbsolute: boolean;
+}
+interface RootContainedPath {
+    readonly kind: "contained" | "missing";
+    readonly absolutePath: string;
+}
+type RootProbe = RootContainedPath | Readonly<{
+    readonly kind: "outside";
+}> | Readonly<{
+    readonly kind: "unavailable";
+}>;
+type EndpointProbe = Readonly<{
+    readonly kind: "missing";
+}> | Readonly<{
+    readonly kind: "directory" | "file" | "unsupported" | "unavailable";
+}>;
+export declare function parseLocalDestination(rawDestination: string): ParsedLocalDestination | "not-local" | null;
+export declare function anchorResolution(headings: readonly MarkdownHeading[], fragment: string, target: MarkdownSafeTargetDescriptor): MarkdownLocalResolution;
+export declare function isRootRelativePath(canonicalProjectRoot: string, rootRelativePath: string): boolean;
+export declare function isWithinRoot(root: string, candidate: string): boolean;
+export declare function relativeSegments(root: string, candidate: string): string[];
+export declare function sameRootRelativePath(rootRelativePath: string, targetPath: string, canonicalProjectRoot: string): boolean;
+export declare function isMarkdownPath(targetPath: string): boolean;
+export declare function toSlashPath(filePath: string): string;
+export declare function isNotFound(error: unknown): boolean;
+export declare function sourceUnavailable(): MarkdownSourceReadResult;
+export declare function valid(target: MarkdownSafeTargetDescriptor): MarkdownLocalResolution;
+export declare function finding(reason: MarkdownLinkFindingReason, target: MarkdownSafeTargetDescriptor): MarkdownLocalResolution;
+export declare function unavailable(reason: MarkdownLocalResolutionReason): MarkdownLocalResolution;
+export type { MarkdownLinkSource, MarkdownLocalResolution, MarkdownLocalResolutionReason, MarkdownLocalResolver, MarkdownLocalResolverCreation, MarkdownLocalResolutionRequest, MarkdownSafeTargetDescriptor, MarkdownSourceReadResult, MarkdownSourceReadFailureReason, RootProbe, EndpointProbe, RootExternalTargetMode };

package/types/package-checks/markdown-link-validation/local-resolver.d.ts

@@ -0,0 +1,5 @@
+import type { MarkdownLocalResolverCreation } from "./local-resolution.ts";
+/** Link-private, per-invocation state for source reads and direct local targets. */
+export declare function createMarkdownLocalResolver(projectRoot: string, maxTargetReads: number): Promise<MarkdownLocalResolverCreation>;
+export { anchorResolution, finding, isMarkdownPath, isNotFound, isRootRelativePath, isWithinRoot, parseLocalDestination, relativeSegments, sameRootRelativePath, sourceUnavailable, toSlashPath, unavailable, valid } from "./local-resolution.ts";
+export type { EndpointProbe, MarkdownLinkFindingReason, MarkdownLinkSource, MarkdownLocalResolution, MarkdownLocalResolutionReason, MarkdownLocalResolutionRequest, MarkdownLocalResolver, MarkdownLocalResolverCreation, MarkdownSafeTargetDescriptor, MarkdownSourceReadFailureReason, MarkdownSourceReadResult, RootExternalTargetMode, RootProbe } from "./local-resolution.ts";

package/types/package-checks/markdown-link-validation/markdown-parser.d.ts

@@ -0,0 +1,37 @@
+type MarkdownOccurrenceKind = "image" | "link";
+interface MarkdownSourcePosition {
+    readonly line: number;
+    readonly column: number;
+}
+interface MarkdownSourceRange {
+    readonly startOffset: number;
+    readonly endOffset: number;
+    readonly start: MarkdownSourcePosition;
+    readonly end: MarkdownSourcePosition;
+}
+interface MarkdownLinkOccurrence {
+    readonly kind: MarkdownOccurrenceKind;
+    readonly rawDestination: string;
+    readonly range: MarkdownSourceRange;
+}
+interface MarkdownHeading {
+    readonly slug: string;
+    readonly range: MarkdownSourceRange;
+}
+interface ParsedMarkdownLinkFacts {
+    readonly occurrences: readonly MarkdownLinkOccurrence[];
+    readonly headings: readonly MarkdownHeading[];
+}
+type MarkdownLinkParseResult = Readonly<{
+    readonly ok: true;
+    readonly facts: ParsedMarkdownLinkFacts;
+}> | Readonly<{
+    readonly ok: false;
+    readonly reason: "markdown-parse-failure";
+}>;
+/**
+ * Link-private Markdown grammar adapter. It deliberately exposes facts rather
+ * than the dependency AST, so resolver ownership starts after parsing.
+ */
+export declare function parseMarkdownLinkFacts(markdown: string): MarkdownLinkParseResult;
+export type { MarkdownHeading, MarkdownLinkOccurrence, MarkdownLinkParseResult, MarkdownOccurrenceKind, MarkdownSourcePosition, MarkdownSourceRange, ParsedMarkdownLinkFacts };

package/types/package-checks/markdown-link-validation/options-resolution.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+/** 将可省略 Markdown link policy 物化为完整、冻结的 execution options。 */
+export declare function resolveMarkdownLinkValidationOptions(value: unknown): ResolvedMarkdownLinkValidationOptions | undefined;

package/types/package-checks/markdown-link-validation/options-validation.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+export declare function validMarkdownLinkValidationOptions(value: unknown): value is ResolvedMarkdownLinkValidationOptions;

package/types/package-checks/markdown-link-validation/options.d.ts

@@ -0,0 +1,43 @@
+import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
+import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+export type MarkdownRootExternalTargetMode = "ignore" | "report" | "validate";
+/** 可省略的 Markdown validation work limits。 */
+export interface MarkdownLinkValidationLimitOptions {
+    readonly maxMarkdownBytes?: number;
+    readonly maxOccurrences?: number;
+    readonly maxTargetReads?: number;
+}
+/** `markdownLinkValidation(options?)` 接受的可省略 authoring policy。 */
+export interface MarkdownLinkValidationOptions {
+    /** 参与本 Check 的 Markdown source selection；省略字段使用 package defaults。 */
+    readonly files?: ProjectFileSelectionOptions;
+    /** local-reference finding 是否使本 Check failed；省略时为 non-blocking。 */
+    readonly findingPolicy?: FindingPolicy;
+    /** `false` 时缺失的本地文件或目录不构成 finding。 */
+    readonly requireExistingTargets?: boolean;
+    /** 是否检查 `#anchor` 对当前 Markdown 文档标题的引用。 */
+    readonly validateSameDocumentAnchors?: boolean;
+    /** 是否检查直接指向的 Markdown 文件中的 `#anchor`。 */
+    readonly validateCrossDocumentAnchors?: boolean;
+    /** root 外本机目标的授权模式；不授权网络请求。 */
+    readonly rootExternalTargetMode?: MarkdownRootExternalTargetMode;
+    /** 是否将空目录目标视为 finding。 */
+    readonly requireNonEmptyDirectories?: boolean;
+    /** 每次运行的 Markdown 内容、occurrence 和 direct target work 上限。 */
+    readonly limits?: MarkdownLinkValidationLimitOptions;
+}
+/** `markdown-link-validation` execution 消费的完整、冻结 options。 */
+export interface ResolvedMarkdownLinkValidationOptions {
+    readonly files: ProjectFileSelection;
+    readonly findingPolicy: FindingPolicy;
+    readonly requireExistingTargets: boolean;
+    readonly validateSameDocumentAnchors: boolean;
+    readonly validateCrossDocumentAnchors: boolean;
+    readonly rootExternalTargetMode: MarkdownRootExternalTargetMode;
+    readonly requireNonEmptyDirectories: boolean;
+    readonly limits: Readonly<{
+        readonly maxMarkdownBytes: number;
+        readonly maxOccurrences: number;
+        readonly maxTargetReads: number;
+    }>;
+}

package/types/package-checks/markdown-link-validation/records.d.ts

@@ -0,0 +1,37 @@
+import type { MarkdownLinkFindingReason, MarkdownLocalResolution, MarkdownSafeTargetDescriptor } from "./local-resolver.ts";
+import type { MarkdownLinkOccurrence } from "./markdown-parser.ts";
+/** 一条本地 Markdown link finding supplemental Record 的 data。 */
+export type MarkdownLinkFindingRecordData = Readonly<{
+    readonly occurrenceKind: "link" | "image";
+    readonly range: Readonly<{
+        readonly end: Readonly<{
+            readonly column: number;
+            readonly line: number;
+        }>;
+        readonly start: Readonly<{
+            readonly column: number;
+            readonly line: number;
+        }>;
+    }>;
+    readonly reason: MarkdownLinkFindingReason;
+    readonly sourcePath: string;
+    readonly target: MarkdownSafeTargetDescriptor;
+}>;
+/** 一条 files policy 已选中但不受 Markdown Link 支持的输入 Finding。 */
+export type MarkdownLinkInputRejectedRecordData = Readonly<{
+    readonly blocking: false;
+    readonly kind: "input-rejected";
+    readonly path: string;
+    readonly reason: "unsupported-file-type";
+}>;
+/** Markdown Link 发布的 link 或 input-rejection Record data。 */
+export type MarkdownLinkValidationRecordData = MarkdownLinkFindingRecordData | MarkdownLinkInputRejectedRecordData;
+export interface MarkdownLinkRecordCandidate {
+    readonly data: MarkdownLinkFindingRecordData;
+    readonly id: string;
+}
+export declare function buildMarkdownLinkRecordCandidate(sourcePath: string, occurrenceIndex: number, occurrence: MarkdownLinkOccurrence, resolution: MarkdownLocalResolution): MarkdownLinkRecordCandidate | undefined;
+export declare function buildMarkdownInputRejectedRecord(path: string): Readonly<{
+    readonly data: MarkdownLinkInputRejectedRecordData;
+    readonly id: string;
+}>;

package/types/package-checks/markdown-link-validation/resolver-engine.d.ts

@@ -0,0 +1,15 @@
+import { type MarkdownLocalResolution, type MarkdownLocalResolutionRequest, type MarkdownLocalResolver, type MarkdownSafeTargetDescriptor, type MarkdownSourceReadResult } from "./local-resolution.ts";
+export declare class LinkLocalResolver implements MarkdownLocalResolver {
+    #private;
+    constructor(canonicalProjectRoot: string, maxTargetReads: number);
+    get targetReadCount(): number;
+    readSource(rootRelativePath: string, maxMarkdownBytes: number): Promise<MarkdownSourceReadResult>;
+    resolve(request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
+    resolveRootContainedTarget(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
+    resolveExternalTarget(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution>;
+    resolveEndpoint(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
+    resolveFile(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
+    resolveDirectory(targetPath: string, fragment: string | null, request: MarkdownLocalResolutionRequest, target: MarkdownSafeTargetDescriptor): Promise<MarkdownLocalResolution>;
+    beginTargetValidation(): boolean;
+    resolveSameDocument(fragment: string | null, request: MarkdownLocalResolutionRequest): MarkdownLocalResolution;
+}

package/types/package-checks/markdown-link-validation/target-descriptor.d.ts

@@ -0,0 +1,5 @@
+import { type MarkdownSafeTargetDescriptor } from "./local-resolution.ts";
+export declare function projectTarget(canonicalProjectRoot: string, targetPath: string, fragment: string | null, kind?: "project-directory" | "project-file" | "project-path"): MarkdownSafeTargetDescriptor;
+export declare function outsideProjectRootTarget(): MarkdownSafeTargetDescriptor;
+export declare function fileTargetDescriptor(target: MarkdownSafeTargetDescriptor): MarkdownSafeTargetDescriptor;
+export declare function directoryTarget(target: MarkdownSafeTargetDescriptor): MarkdownSafeTargetDescriptor;

package/types/package-checks/markdown-link-validation/traversal-result.d.ts

@@ -0,0 +1,12 @@
+import type { CheckResult } from "../../check/check.ts";
+import type { MarkdownLinkValidationFinalData } from "./final-data.ts";
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
+/** Materializes one completed source traversal into its Check-owned final result. */
+export declare function settledMarkdownTraversalResult(input: Readonly<{
+    readonly findingCount: number;
+    readonly findingPolicy: ResolvedMarkdownLinkValidationOptions["findingPolicy"];
+    readonly occurrenceCount: number;
+    readonly rejectedInputCount: number;
+    readonly sourceFileCount: number;
+    readonly targetReadCount: number;
+}>): CheckResult<MarkdownLinkValidationFinalData>;

package/types/package-checks/project-files/collection.d.ts

@@ -0,0 +1,9 @@
+/** Project-root file discovery and selection helpers. */
+import type { ProjectFileSelection } from "./configuration.ts";
+/**
+ * Resolves multiple named file sets while enumerating each distinct candidate source once.
+ */
+export declare function collectProjectFileSets(rootDir: string, selections: Readonly<Record<string, ProjectFileSelection>>): ReadonlyMap<string, readonly string[]>;
+export declare function collectProjectFiles(rootDir: string, selection: ProjectFileSelection): string[];
+/** 返回已收集的命名文件集合；缺失表示收集完整性失效，不能解释为空集合。 */
+export declare function requireProjectFileSet(fileSets: ReadonlyMap<string, readonly string[]>, selectionId: string): readonly string[];

package/types/package-checks/project-files/config-glob.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Product config glob 的唯一 matcher boundary。
+ * Candidate 使用 slash form；dot path 只由显式 glob 决定，不附加隐式忽略规则。
+ */
+export declare function matchesAnyConfigGlob(candidatePath: string, configGlobs: readonly string[]): boolean;

package/types/package-checks/project-files/configuration.d.ts

@@ -0,0 +1,31 @@
+export declare const PROJECT_FILE_SOURCES: readonly ["filesystem", "git-worktree"];
+/** 文件选择可使用的显式候选来源。 */
+export type ProjectFileSource = (typeof PROJECT_FILE_SOURCES)[number];
+/** 读取项目文件的 Check 所拥有的文件选择输入。 */
+export interface ProjectFileSelectionOptions {
+    /** 候选文件来源；省略时使用 owning Check 的来源默认值，当前随包 Check 均为 `filesystem`。 */
+    readonly source?: ProjectFileSource;
+    /** 相对项目根目录且使用 `/` 的 glob；省略时使用 owning Check 的 include 默认值，显式数组完整替换。 */
+    readonly include?: readonly string[];
+    /** 优先于 `include` 的 glob；省略时使用 owning Check 的 exclude 默认值，显式数组完整替换。 */
+    readonly exclude?: readonly string[];
+}
+/** Check execution 消费的完整项目文件选择。 */
+export interface ProjectFileSelection {
+    readonly exclude: readonly string[];
+    readonly include: readonly string[];
+    readonly source: ProjectFileSource;
+}
+/**
+ * Package-provided Checks 共用的通用文件选择基线。
+ *
+ * 对象与数组均不可变；需要保留默认排除并追加项目规则时，使用对象与数组 spread 建立新值。
+ * 个别 Check 会从此 baseline 派生更精准的默认 include；显式组合此 value 仍表示通配全部路径。
+ */
+export declare const defaultProjectFileSelection: ProjectFileSelection;
+/** 按 owning Check 提供的可信完整 defaults 解析并冻结一份 authoring selection。 */
+export declare function resolveProjectFileSelection(value: unknown, defaults?: ProjectFileSelection): ProjectFileSelection | undefined;
+export declare function snapshotDefaultProjectFileSelection(): ProjectFileSelection;
+/** 为 owning Check 对可信的完整 selection 建立 detached、冻结快照。 */
+export declare function snapshotProjectFileSelection(selection: ProjectFileSelection): ProjectFileSelection;
+export declare function validProjectFileSelection(value: unknown): value is ProjectFileSelection;

package/types/package-checks/project-files/exact-input-measurement.d.ts

@@ -0,0 +1,12 @@
+export type ExactInputMeasurement<T> = {
+    readonly payload: T;
+    readonly sourcePaths: readonly string[];
+};
+export type ExactInputMeasurementAcceptance<T> = {
+    readonly ok: true;
+    readonly payloads: readonly T[];
+} | {
+    readonly error: string;
+    readonly ok: false;
+};
+export declare function acceptExactInputMeasurements<T>(measurements: readonly ExactInputMeasurement<T>[], approvedExactPaths: readonly string[]): ExactInputMeasurementAcceptance<T>;

package/types/package-checks/project-files/file-fingerprint.d.ts

@@ -0,0 +1,7 @@
+export interface FileInputFingerprint {
+    readonly fileCount: number;
+    readonly fileList: readonly string[];
+    readonly fingerprint: string;
+}
+/** Fingerprints one exact path set from stable path order and normalized current file content. */
+export declare function fingerprintProjectFiles(rootDir: string, paths: readonly string[]): FileInputFingerprint;

package/types/package-checks/project-files/gitlink-revision.d.ts

@@ -0,0 +1,9 @@
+/** Reads canonical gitlink entries from a named Git tree revision. */
+export type Gitlink = Readonly<{
+    readonly path: string;
+    readonly sha: string;
+}>;
+export declare function gitlinksAtRevision({ repository, revision }: Readonly<{
+    readonly repository: string;
+    readonly revision: string;
+}>): readonly Gitlink[];

package/types/package-checks/project-files/gitlink-worktree.d.ts

@@ -0,0 +1,26 @@
+/** Canonical Git worktree checks for gitlink traversal. */
+export type GitlinkWorktreeInspection = {
+    readonly kind: "initialized";
+    readonly repository: string;
+} | {
+    readonly kind: "inspection-failed";
+    readonly error: string;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "not-independent";
+};
+export declare function canonicalRepositoryPath(repository: string): string;
+export declare function inspectGitlinkWorktree({ gitlinkPath, repository }: Readonly<{
+    readonly gitlinkPath: string;
+    readonly repository: string;
+}>): GitlinkWorktreeInspection;
+export declare function resolveDescendableGitlinkRepository({ gitlinkPath, repository, visitedRepositories }: Readonly<{
+    readonly gitlinkPath: string;
+    readonly repository: string;
+    readonly visitedRepositories: ReadonlySet<string>;
+}>): string | null;
+export declare function visitRepository({ repository, visitedRepositories }: Readonly<{
+    readonly repository: string;
+    readonly visitedRepositories: ReadonlySet<string>;
+}>): ReadonlySet<string>;

package/types/package-checks/project-files/input-eligibility.d.ts

@@ -0,0 +1,7 @@
+/** 一个 Check 对完整 selected path set 做 eligibility 分类后的结果。 */
+export interface ProjectFileEligibilityPartition {
+    readonly acceptedPaths: readonly string[];
+    readonly rejectedPaths: readonly string[];
+}
+/** 保持输入顺序，将每个 selected path 恰好分配给 accepted 或 rejected。 */
+export declare function partitionProjectFilesByEligibility(selectedPaths: readonly string[], accepts: (path: string) => boolean): ProjectFileEligibilityPartition;

package/types/package-checks/project-files/reported-path.d.ts

@@ -0,0 +1 @@
+export declare function normalizeScannerReportedPath(reportedPath: string, projectRoot: string): string;

package/types/package-checks/project-files/revision-paths.d.ts

@@ -0,0 +1,12 @@
+/** Path and Git-output projections shared by revision traversal helpers. */
+export declare function uniqueSortedPaths(files: readonly string[]): string[];
+export declare function prefixAndFilter({ files, prefix, scanInputPaths }: Readonly<{
+    readonly files: readonly string[];
+    readonly prefix: string;
+    readonly scanInputPaths: readonly string[];
+}>): string[];
+export declare function joinSlash({ path, prefix }: Readonly<{
+    readonly path: string;
+    readonly prefix: string;
+}>): string;
+export declare function nonEmptyGitOutput(stdout: string | null | undefined): string | null;

package/types/package-checks/project-files/revision-worktree-files.d.ts

@@ -0,0 +1,5 @@
+/** Enumerates files from initialized, non-cyclic submodule working trees. */
+export declare function collectSubmoduleWorktreeFiles({ repository, scanInputPaths }: Readonly<{
+    readonly repository: string;
+    readonly scanInputPaths: readonly string[];
+}>): string[];

package/types/project-definition/check-tree/authoring.d.ts

@@ -0,0 +1,41 @@
+import type { CheckDescriptor } from "../../check/descriptor.ts";
+import { type CheckVisibility, type CheckExecution, type CheckPreflight } from "../../check/check.ts";
+type TrustedDataParser = (this: void, ...parameters: never[]) => unknown;
+export type ParsedCheckCollection = Readonly<{
+    readonly kind: "exact";
+    readonly values: readonly string[];
+} | {
+    readonly kind: "inherit";
+    readonly add: readonly string[];
+    readonly remove: readonly string[];
+}>;
+export interface ParsedCheck {
+    readonly checkId: string;
+    readonly checks: readonly ParsedCheck[];
+    readonly definition: CheckDescriptor | null;
+    readonly dependsOn: ParsedCheckCollection | undefined;
+    readonly displayName: string;
+    readonly execution: CheckExecution | null;
+    readonly maxParallel: number | undefined;
+    readonly mutex: ParsedCheckCollection | undefined;
+    readonly options: object | null;
+    readonly path: string;
+    readonly parseData: TrustedDataParser | null;
+    readonly preflight: CheckPreflight | null;
+    readonly visibility: CheckVisibility | null;
+}
+export interface ParsedCheckTree {
+    readonly checks: readonly ParsedCheck[];
+    readonly warnings: readonly MeaninglessCheckWarning[];
+}
+export interface MeaninglessCheckWarning {
+    readonly code: "meaningless-check";
+    readonly path: string;
+    readonly checkId: string;
+}
+/**
+ * Parses only the closed recursive authoring grammar. Execution callbacks are
+ * trusted project code, while every declarative field is copied and validated.
+ */
+export declare function parseCheckTreeAuthoring(value: unknown): ParsedCheckTree | undefined;
+export {};

package/types/project-definition/check-tree/materialization.d.ts

@@ -0,0 +1,4 @@
+import { type Check } from "../../check/check.ts";
+import type { ParsedCheckTree } from "./authoring.ts";
+/** Rebuilds the validated public authoring shape without retaining untyped input. */
+export declare function materializeCheckTreeAuthoring(parsed: ParsedCheckTree): readonly Check[];

package/types/project-definition/check-tree/resolution.d.ts

@@ -0,0 +1,25 @@
+import type { CheckDescriptor } from "../../check/descriptor.ts";
+import type { CheckExecution, CheckPreflight, CheckVisibility } from "../../check/check.ts";
+import { type MeaninglessCheckWarning, type ParsedCheckTree } from "./authoring.ts";
+export type { Check, InheritableCheckCollection } from "../../check/check.ts";
+export interface ResolvedCheckTreeLeaf {
+    readonly definition: CheckDescriptor;
+    readonly dependsOn: readonly string[];
+    readonly execution: CheckExecution;
+    readonly maxParallel: number;
+    readonly mutex: readonly string[];
+    readonly options: object;
+    readonly preflight?: CheckPreflight;
+    readonly visibility: CheckVisibility;
+}
+export interface ResolvedCheckTree {
+    readonly leaves: readonly ResolvedCheckTreeLeaf[];
+    readonly warnings: readonly MeaninglessCheckWarning[];
+}
+/**
+ * Traverses the recursive authoring tree. Containment only passes scheduling
+ * values to descendants; it never creates an execution dependency or output
+ * hierarchy.
+ */
+export declare function resolveCheckTree(value: unknown, rootMaxParallel: number): ResolvedCheckTree | undefined;
+export declare function resolveParsedCheckTree(parsed: ParsedCheckTree, rootMaxParallel: number): ResolvedCheckTree | undefined;

package/types/project-definition/output-defaults.d.ts

@@ -0,0 +1,14 @@
+/** Default Run-owned output values applied when a Project Definition omits an override. */
+export declare const DEFAULT_PROJECT_OUTPUTS: Readonly<{
+    readonly machinePublication: Readonly<{
+        directory: "artifacts/vibe-check";
+        enabled: true;
+    }>;
+    readonly progressRendering: Readonly<{
+        enabled: true;
+    }>;
+    readonly diagnosticLogging: Readonly<{
+        directory: ".log/vibe-check";
+        enabled: false;
+    }>;
+}>;

package/types/project-definition/output-validation.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectOutputs } from "./project-definition.ts";
+export declare function parseOutputs(value: unknown): ProjectOutputs | undefined;
+export declare function isContainedRelativeDirectory(directory: string): boolean;

package/types/project-definition/project-definition-validation.d.ts

@@ -0,0 +1,6 @@
+import { type ProjectDefinitionValidationResult } from "./project-definition.ts";
+/**
+ * Validates one closed Definition before Run can invoke any project callback.
+ * Successful validation carries information-only Check warnings separately.
+ */
+export declare function validateProjectDefinition(value: unknown): ProjectDefinitionValidationResult;