canship 0.7.1 → 0.8.0

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+/** 稳定诊断代码独立于展示文本；跳过文件继续使用现有 reason 字段。 */
+
+type DiagnosticCode = 'RULE_EXECUTION_FAILED' | 'ANALYSIS_INCOMPLETE' | 'GIT_CHECK_INCOMPLETE' | 'ROUTE_UNRESOLVED' | 'FINDINGS_LIMIT' | 'INVALID_ARGUMENT' | 'CONFIG_INVALID' | 'BASELINE_INVALID' | 'GIT_REFERENCE_INVALID' | 'SCAN_ROOT_UNAVAILABLE' | 'OUTPUT_WRITE_FAILED' | 'INTERNAL_ERROR' | 'SCAN_CANCELLED' | 'PROGRESS_CALLBACK_FAILED' | 'REPORT_COMPARISON_INVALID' | 'WORKSPACE_INVALID' | 'WORKSPACE_UNAVAILABLE' | 'WORKSPACE_SCAN_FAILED' | (string & {});
+
 /** 扫描器的核心数据结构。 */
 /** 严重度：P0 为高影响凭据或权限问题，P1 为访问控制问题，P2 为其他配置问题。 */
 type Severity = 'P0' | 'P1' | 'P2';
@@ -52,6 +56,12 @@ type SkipReason =
  | 'nested-repository';
 /** 按对外规则 ID 或命名空间选择规则。 */
 interface ScanOptions$1 {
+    /** 项目相对文件或目录路径，按字面值匹配。 */
+    exclude?: string[];
+    /** 在同步分析批次和规则边界检查取消，不中断正在执行的同步系统调用。 */
+    signal?: AbortSignal;
+    /** 只提供阶段和计数；回调失败会中止扫描。 */
+    onProgress?: (progress: Readonly<ScanProgress>) => void | Promise<void>;
     /** 仅执行匹配规则；与 skip 互斥。 */
     only?: string[];
     /** 排除匹配规则。 */
@@ -59,6 +69,13 @@ interface ScanOptions$1 {
     /** 是否遵从被扫描项目中的忽略标记；默认遵从，扫描不可信项目时应关闭。 */
     honorIgnoreMarkers?: boolean;
 }
+interface ScanProgress {
+    phase: 'discovery' | 'files' | 'history' | 'project' | 'finalize' | 'complete';
+    filesCompleted: number;
+    filesTotal: number | null;
+    projectRulesCompleted: number;
+    projectRulesTotal: number | null;
+}
 /** 规则筛选条件及过滤统计。 */
 interface RuleSelection {
     only: string[];
@@ -89,6 +106,8 @@ interface ScanError {
     message: string;
     /** 区分执行异常与已知扫描缺口。 */
     kind: 'crashed' | 'incomplete';
+    /** 稳定诊断代码；旧报告可能没有此字段。 */
+    code?: DiagnosticCode;
 }
 /** 变更视图的比较基准、隐藏数量及完整扫描统计。 */
 interface ChangeView {
@@ -102,6 +121,11 @@ interface ChangeView {
 }
 /** 扫描汇总；结果为空时仍需保留完整性信息。 */
 interface ScanResult {
+    /** 显式文件范围限制；matched 是匹配到的请求路径，不是文件数量。 */
+    exclusions?: {
+        requested: string[];
+        matched: string[];
+    };
     /** 仅筛选展示；统计和退出码仍基于完整扫描。 */
     changeView?: ChangeView;
     findings: Finding[];
@@ -125,6 +149,13 @@ interface ScanResult {
     partial: boolean;
 }
 
+interface FixExample {
+    context: string;
+    before: string;
+    after: string;
+    limitation: string;
+}
+
 /** 规则目录说明检测范围与证据边界，不执行扫描。 */
 
 interface RuleDescription {
@@ -135,25 +166,64 @@ interface RuleDescription {
     scope: string;
     limitation: string;
     reportsFindings: boolean;
+    example?: FixExample;
 }
 
-interface ScanOptions extends ScanOptions$1 {
-    /** 移除结果摘录；路径、标题及说明仍需在分享前审阅。 */
-    noExcerpts?: boolean;
-}
+/** CLI 与公共 API 共享结果判定；展示过滤不改变完整扫描结论。 */
+
 interface ScanSummary {
     findings: number;
     blocking: number;
     likely: number;
     partial: boolean;
-    /** 与 CLI 默认策略一致；不自动设置 process.exitCode。 */
     exitCode: 0 | 1 | 2 | 3;
 }
+declare function summarize(result: ScanResult): ScanSummary;
+
+/** 扫描控制不包含路径或源码；取消原因不进入诊断文本。 */
+
+declare class ScanCancelledError extends Error {
+    readonly code = "SCAN_CANCELLED";
+    constructor();
+}
+declare class ScanProgressError extends Error {
+    readonly code = "PROGRESS_CALLBACK_FAILED";
+    constructor(cause: unknown);
+}
+
+/** 构建身份只包含公开版本与提交摘要，不读取运行机器或扫描项目的信息。 */
+interface BuildInfo {
+    version: string;
+    channel: 'development' | 'prerelease' | 'release';
+    revision: string | null;
+    dirty: boolean | null;
+}
+declare function getBuildInfo(): BuildInfo;
+/** 能力声明与边界测试配套；未来联网模式不得继承静态扫描的默认授权。 */
+declare function getCapabilities(): {
+    staticScan: {
+        network: boolean;
+        projectCodeExecution: boolean;
+        projectWrites: boolean;
+    };
+    fileOutputs: string;
+    onlineValidation: boolean;
+    onlineValidationPolicy: {
+        cliOnly: boolean;
+        defaultEnabled: boolean;
+        confirmation: string;
+        credentials: boolean;
+        responseBodiesRetained: boolean;
+    };
+};
+
+interface ScanOptions extends ScanOptions$1 {
+    /** 移除结果摘录；路径、标题及说明仍需在分享前审阅。 */
+    noExcerpts?: boolean;
+}
 /** 返回独立副本，避免调用方修改内部规则目录。 */
 declare function listRules(): RuleDescription[];
-/** 统计全部结果；结果退出码优先，完整性始终单独保留。 */
-declare function summarize(result: ScanResult): ScanSummary;
 /** 扫描指定目录，返回全部置信度结果；不自动应用基线或项目配置。 */
 declare function scan(root: string, options?: ScanOptions): Promise<ScanResult>;
 
-export { type ChangeView, type Confidence, type EvidenceStep, type Finding, type RuleDescription, type RuleSelection, type ScanError, type ScanOptions, type ScanResult, type ScanSummary, type Severity, type SkippedFile, listRules, scan, summarize };
+export { type BuildInfo, type ChangeView, type Confidence, type DiagnosticCode, type EvidenceStep, type Finding, type RuleDescription, type RuleSelection, ScanCancelledError, type ScanError, type ScanOptions, type ScanProgress, ScanProgressError, type ScanResult, type ScanSummary, type Severity, type SkippedFile, getBuildInfo, getCapabilities, listRules, scan, summarize };