@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -1,5 +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 "../../package-tools/finding-waivers/reconciliation.ts";
 export type DuplicateDetectionScannerCommand = 
 /** 使用随 `@zxyycom/vibe-check` 安装的 jscpd。 */
 Readonly<{
@@ -23,9 +25,22 @@ export interface DuplicateDetectionScannerOptions {
     /** 省略时使用随 `@zxyycom/vibe-check` 安装的 jscpd。 */
     readonly command?: DuplicateDetectionScannerCommand;
 }
+/** duplicate-detection identity 的 locations 数组中的一段 project-relative range。 */
+export interface DuplicateDetectionFindingLocation {
+    readonly endLine: number;
+    readonly path: string;
+    readonly startLine: number;
+}
+/** duplicate-detection 用于精确识别一条可豁免 finding 的稳定字段。 */
+export interface DuplicateDetectionFindingIdentity {
+    readonly locations: readonly DuplicateDetectionFindingLocation[];
+    readonly metric: "duplicate-tokens";
+}
+/** 一项 duplicate-detection finding 的声明式豁免。 */
+export type DuplicateDetectionFindingWaiver = FindingWaiver<DuplicateDetectionFindingIdentity>;
 /** 重复代码区域可省略并由构造函数补齐的文件策略。 */
 export type DuplicateDetectionFileOptions = ProjectFileSelectionOptions;
-/** 可独立选择文件、阈值和 finding policy 的重复代码区域。 */
+/** 同时拥有文件选择、比较边界、阈值和 finding policy 的重复代码区域。 */
 export interface DuplicateDetectionCodeAreaOptions {
     /** 显式区域必须声明本字段；其中各子字段可省略并使用 package 默认值。 */
     readonly files: DuplicateDetectionFileOptions;
@@ -37,21 +52,24 @@ 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;
     /** 省略时为 `non-blocking`；区域可局部覆盖。 */
     readonly findingPolicy?: FindingPolicy;
+    /** 省略时没有豁免；identity 使用 Finding 发布的完整排序 location ranges。 */
+    readonly findingWaivers?: readonly DuplicateDetectionFindingWaiver[];
     readonly scanner?: DuplicateDetectionScannerOptions;
 }
-/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+/** 构造函数生成并由 Check preparation/execution 消费的完整 options。 */
 export interface ResolvedDuplicateDetectionOptions {
     readonly cache: Readonly<{
         readonly directory: string;
         readonly enabled: boolean;
     }>;
     readonly codeAreas: Readonly<Record<string, ResolvedDuplicateDetectionCodeAreaOptions>>;
+    readonly findingWaivers: readonly DuplicateDetectionFindingWaiver[];
     readonly scanner: ResolvedDuplicateDetectionScannerOptions;
 }
 export interface ResolvedDuplicateDetectionCodeAreaOptions {

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

@@ -1,7 +1,9 @@
+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 { ResolvedDuplicateDetectionOptions } from "./options.ts";
+import type { DuplicateDetectionFindingIdentity, ResolvedDuplicateDetectionOptions } from "./options.ts";
 /** 一条可信重复片段 supplemental Record 的 data。 */
-export type DuplicateDetectionRecordData = Readonly<{
+export type DuplicateDetectionFindingRecordData = Readonly<{
     readonly blocking: boolean;
     readonly codeAreas: readonly string[];
     readonly lineCount: number;
@@ -12,11 +14,26 @@ export type DuplicateDetectionRecordData = Readonly<{
     }>[];
     readonly metric: "duplicate-tokens";
     readonly tokenCount: number;
+    /** 精确匹配 waiver 时保留理由，并令该 finding 不再参与 actionable settlement。 */
+    readonly waiver?: Readonly<{
+        readonly reason: string;
+    }>;
 }>;
+/** 未使用或过宽 duplicate-detection waiver 的 supplemental audit Record data。 */
+export type DuplicateDetectionFindingWaiverAuditRecordData = FindingWaiverAuditRecordData<DuplicateDetectionFindingIdentity>;
+/** duplicateDetection 发布的 normal finding 或 waiver-audit Record data。 */
+export type DuplicateDetectionRecordData = DuplicateDetectionFindingRecordData | DuplicateDetectionFindingWaiverAuditRecordData;
 export interface DuplicateRecordCandidate {
-    readonly data: DuplicateDetectionRecordData;
+    readonly data: DuplicateDetectionFindingRecordData;
     readonly id: string;
 }
+export declare function duplicateDetectionFindingIdentity(candidate: DuplicateRecordCandidate): DuplicateDetectionFindingIdentity;
+export declare function duplicateDetectionWaiverIdentity(waiver: MaterializedFindingWaiver): DuplicateDetectionFindingIdentity;
+/** 为一项未使用或过宽 waiver 构造 Check-owned audit Record。 */
+export declare function duplicateDetectionWaiverAuditRecord(audit: FindingWaiverRecordAudit): Readonly<{
+    readonly data: DuplicateDetectionFindingWaiverAuditRecordData;
+    readonly id: string;
+}>;
 /** Builds Check-owned supplemental facts without adding a Product record catalog. */
 export declare function buildDuplicateRecordCandidates(fragments: readonly DuplicateCodeFragment[], codeAreas: ResolvedDuplicateDetectionOptions["codeAreas"]): readonly DuplicateRecordCandidate[] | undefined;
 export declare function isValidDuplicateFragment(fragment: DuplicateCodeFragment): boolean;

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/finding-messages.d.ts

@@ -0,0 +1,4 @@
+import type { CheckMessage } from "../../check/check.ts";
+import type { FileRecordCandidate } from "./records.ts";
+/** Projects actionable file-metric Records into bounded terminal summaries. */
+export declare function fileMetricFindingMessages(findings: readonly FileRecordCandidate[]): readonly CheckMessage[];

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,7 @@
 import type { FileMetric } from "./measurement-model.ts";
 import type { FileMetricsFindingIdentity, ResolvedFileMetricsCodeAreaOptions } from "./options.ts";
-import type { FindingWaiverAudit, 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[]>;
     readonly codeAreas: Readonly<Record<string, ResolvedFileMetricsCodeAreaOptions>>;
@@ -19,13 +20,7 @@ export type FileMetricsFindingRecordData = Readonly<{
     }>;
 }>;
 /** 未使用或过宽 file-metrics waiver 的 supplemental audit Record data。 */
-export type FileMetricsFindingWaiverAuditRecordData = Readonly<{
-    readonly identity: FileMetricsFindingIdentity;
-    readonly kind: "finding-waiver-audit";
-    readonly matchCount: number;
-    readonly reason: string;
-    readonly status: "overmatched" | "unused";
-}>;
+export type FileMetricsFindingWaiverAuditRecordData = FindingWaiverAuditRecordData<FileMetricsFindingIdentity>;
 /** file-metrics 发布的 finding 或 waiver-audit supplemental Record data。 */
 export type FileMetricsRecordData = FileMetricsFindingRecordData | FileMetricsFindingWaiverAuditRecordData;
 export interface FileRecordCandidate {
@@ -33,10 +28,10 @@ export interface FileRecordCandidate {
     readonly id: string;
 }
 /** 仅为未使用和过宽 waiver 构造补充 audit Record；正常 applied waiver 由 finding Record 自己保留。 */
-export declare function fileMetricsWaiverAuditRecord(audit: FindingWaiverAudit): Readonly<{
+export declare function fileMetricsWaiverAuditRecord(audit: FindingWaiverRecordAudit): Readonly<{
     readonly data: FileMetricsFindingWaiverAuditRecordData;
     readonly id: string;
-}> | undefined;
+}>;
 export declare function fileMetricsWaiverIdentity(waiver: MaterializedFindingWaiver): FileMetricsFindingIdentity;
 /** Converts trusted scanner metrics into area-policy-owned supplemental facts. */
 export declare function buildFileRecordCandidates(metrics: readonly FileMetric[], areaPolicy: FileMetricsAreaPolicyContext): readonly FileRecordCandidate[] | undefined;

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/file-metrics/scc/parser.d.ts

@@ -1,7 +1,7 @@
 import type { ExactInputMeasurement } from "../../project-files/exact-input-measurement.ts";
 import type { FileMetric } from "../measurement-model.ts";
-export declare const SCC_VERSION = "3.7.0";
-export declare const SCC_VERSION_OUTPUT = "scc version 3.7.0";
+export declare const SCC_VERSION = "4.0.0";
+export declare const SCC_VERSION_OUTPUT = "scc version 4.0.0";
 export declare const SCC_BY_FILE_CSV_HEADER = "Language,Provider,Filename,Lines,Code,Comments,Blanks,Complexity,Bytes,ULOC";
 export type SccScanResult = {
     readonly measurements: readonly ExactInputMeasurement<FileMetric>[];
@@ -14,12 +14,12 @@ export type SccScanResult = {
 /**
  * 解析 scc CSV 输出。
  *
- * scc 3.7.0 `--by-file --format csv` 列：
+ * scc 4.0.0 `--no-config --by-file --format csv` 列：
  * Language,Provider,Filename,Lines,Code,Comments,Blanks,Complexity,Bytes,ULOC
  *
  * - Lines 包含所有行（code + comments + blanks）
  * - Code 是文件级代码行数，用于 code-line finding
  * - Complexity 是 scc complexitychecks token 命中数，用于 low-decision-token allowance，不是函数级 CC
- * - ULOC (Usable Lines of Code) 由 3.7.0 输出，但首期不进入稳定 metrics
+ * - ULOC (Usable Lines of Code) 由 4.0.0 输出，但首期不进入稳定 metrics
  */
 export declare function parseSccCSV(csv: string, cwd: string): SccScanResult;

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

@@ -6,5 +6,5 @@ export interface FunctionMetricInstance {
 export interface FunctionMetricAnalysis {
     readonly instances: readonly FunctionMetricInstance[];
 }
-export declare function analyzeFunctionMetrics(metrics: readonly FunctionMetric[]): FunctionMetricAnalysis | undefined;
+export declare function analyzeFunctionMetrics(metrics: readonly unknown[]): FunctionMetricAnalysis | undefined;
 export declare function isStableFunctionName(name: string): boolean;

package/types/package-checks/function-metrics/analyzer/analysis-context.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Derived from terryyin/lizard 1.24.0.
+ * Sources: lizard.py nesting stack and FileInfoBuilder lifecycle;
+ * lizard_ext/lizardnd.py typed FileInfoBuilder lifecycle seam.
+ * Upstream revision: 308b1c3efd8c1c69bcc3eb82deeaec64fd3662ec.
+ * SPDX-License-Identifier: Apache-2.0 AND MIT
+ * Modified: mutable analysis context isolated from result models and pipeline.
+ */
+import { FunctionInfo, FileInformation, Nesting } from "./analysis-model.ts";
+export interface NestingStackLike {
+    withNamespace(name: string): string;
+    addBareNesting(): void;
+    addNamespace(token: string): void;
+    startNewFunctionNesting(functionInfo: FunctionInfo): void;
+    popNesting(): Nesting | undefined;
+    readonly currentNestingLevel: number;
+    readonly lastFunction: FunctionInfo | undefined;
+}
+/**
+ * The source spelling exposed by Python's FileInfoBuilder.__getattr__.
+ *
+ * A translated extension may only implement the methods it decorates, as
+ * lizardduplicate's NestingStackWithUnifiedTokens does. The adapter below
+ * supplies all remaining names from its wrapped stack just like __getattr__.
+ */
+export interface SourceNestingStackLike {
+    nesting_stack: Nesting[];
+    pending_function: FunctionInfo | undefined;
+    with_namespace(name: string): string;
+    add_bare_nesting(): void;
+    add_namespace(token: string): void;
+    start_new_function_nesting(functionInfo: FunctionInfo): void;
+    pop_nesting(): Nesting | undefined;
+    readonly current_nesting_level: number;
+    readonly last_function: FunctionInfo | undefined;
+}
+/** The complete spelling bridge passed to source-aligned nesting decorators. */
+export interface NestingStackAdapter extends NestingStackLike, SourceNestingStackLike {
+}
+/** A source-aligned nesting-stack decorator constructor. */
+export interface NestingStackDecorator<Decorated extends object = NestingStackLike> {
+    new (decorated: NestingStackAdapter): Decorated;
+}
+/** The nesting stack that readers use to qualify and complete functions. */
+export declare class NestingStack implements NestingStackAdapter {
+    private nestingStack;
+    private pendingFunction;
+    /** Source-name aliases retain the mutable stack storage for decorators. */
+    get nesting_stack(): Nesting[];
+    set nesting_stack(value: Nesting[]);
+    get pending_function(): FunctionInfo | undefined;
+    set pending_function(value: FunctionInfo | undefined);
+    withNamespace(name: string): string;
+    with_namespace(name: string): string;
+    addBareNesting(): void;
+    add_bare_nesting(): void;
+    addNamespace(token: string): void;
+    add_namespace(token: string): void;
+    startNewFunctionNesting(functionInfo: FunctionInfo): void;
+    start_new_function_nesting(functionInfo: FunctionInfo): void;
+    popNesting(): Nesting | undefined;
+    pop_nesting(): Nesting | undefined;
+    get currentNestingLevel(): number;
+    get current_nesting_level(): number;
+    get lastFunction(): FunctionInfo | undefined;
+    get last_function(): FunctionInfo | undefined;
+    private createNesting;
+}
+/**
+ * The reader context used to build one file and its function list.  It keeps
+ * the mutable state that upstream readers intentionally share across stages.
+ */
+export declare class FileInfoBuilder {
+    fileinfo: FileInformation;
+    currentLine: number;
+    forgive: boolean;
+    forgiveGlobal: boolean;
+    newline: boolean;
+    globalPseudoFunction: FunctionInfo;
+    currentFunction: FunctionInfo;
+    stackedFunctions: FunctionInfo[];
+    private nestingStack;
+    private readonly decoratedStackFallbacks;
+    constructor(filename: string);
+    /**
+     * These aliases preserve the source extension/context protocol while keeping
+     * a single mutable storage location for each analyzer value.
+     */
+    get current_line(): number;
+    set current_line(value: number);
+    get forgive_global(): boolean;
+    set forgive_global(value: boolean);
+    get global_pseudo_function(): FunctionInfo;
+    set global_pseudo_function(value: FunctionInfo);
+    get current_function(): FunctionInfo;
+    set current_function(value: FunctionInfo);
+    get stacked_functions(): FunctionInfo[];
+    set stacked_functions(value: FunctionInfo[]);
+    get _nesting_stack(): object;
+    set _nesting_stack(value: object);
+    withNamespace(name: string): string;
+    with_namespace(name: string): string;
+    addBareNesting(): void;
+    add_bare_nesting(): void;
+    addNamespace(token: string): void;
+    add_namespace(token: string): void;
+    startNewFunctionNesting(functionInfo: FunctionInfo): void;
+    start_new_function_nesting(functionInfo: FunctionInfo): void;
+    get currentNestingLevel(): number;
+    get current_nesting_level(): number;
+    get lastFunction(): FunctionInfo | undefined;
+    get last_function(): FunctionInfo | undefined;
+    /** Equivalent to Python's decorate_nesting_stack extension seam. */
+    decorateNestingStack<Decorated extends object>(decorateClass: NestingStackDecorator<Decorated>): Decorated;
+    decorate_nesting_stack<Decorated extends object>(decorateClass: NestingStackDecorator<Decorated>): Decorated;
+    popNesting(): void;
+    pop_nesting(): void;
+    private finishPoppedNesting;
+    addNloc(count: number): void;
+    add_nloc(count: number): void;
+    tryNewFunction(name: string): void;
+    try_new_function(name: string): void;
+    confirmNewFunction(): void;
+    confirm_new_function(): void;
+    restartNewFunction(name: string): void;
+    restart_new_function(name: string): void;
+    pushNewFunction(name: string): void;
+    push_new_function(name: string): void;
+    addCondition(increment?: number): void;
+    add_condition(increment?: number): void;
+    /** Source lizardnd.py's monkey-patched FileInfoBuilder method surface. */
+    addNdCondition(increment?: number): number;
+    add_nd_condition(increment?: number): number;
+    resetNdComplexity(): void;
+    reset_nd_complexity(): void;
+    addHiddenBracketCondition(increment?: number): void;
+    add_hidden_bracket_condition(increment?: number): void;
+    getHiddenBracket(): number;
+    get_hidden_bracket(): number;
+    loopBracketStatus(): void;
+    loop_bracket_status(): void;
+    getLoopStatus(): boolean;
+    get_loop_status(): boolean;
+    setInCondition(inCondition: boolean): void;
+    set_in_condition(inCondition: boolean): void;
+    getInCondition(): boolean;
+    get_in_condition(): boolean;
+    incrementConditionDepth(): void;
+    increment_condition_depth(): void;
+    decrementConditionDepth(): void;
+    decrement_condition_depth(): void;
+    getConditionDepth(): number;
+    get_condition_depth(): number;
+    resetConditionTracking(): void;
+    reset_condition_tracking(): void;
+    setLogicalOperatorAdded(added: boolean): void;
+    set_logical_operator_added(added: boolean): void;
+    getLogicalOperatorAdded(): boolean;
+    get_logical_operator_added(): boolean;
+    setPrevWasElse(value: boolean): void;
+    set_prev_was_else(value: boolean): void;
+    getPrevWasElse(): boolean;
+    get_prev_was_else(): boolean;
+    clearPrevWasElse(): void;
+    clear_prev_was_else(): void;
+    addToLongFunctionName(appended: string): void;
+    add_to_long_function_name(appended: string): void;
+    addToFunctionName(appended: string): void;
+    add_to_function_name(appended: string): void;
+    parameter(token: string): void;
+    endOfFunction(): void;
+    end_of_function(): void;
+    private get nestingStackAdapter();
+}

package/types/package-checks/function-metrics/analyzer/analysis-model.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Derived from terryyin/lizard 1.24.0.
+ * Sources: lizard.py FunctionInfo and FileInformation; lizard_ext/lizardcomplextags.py
+ * and lizard_ext/lizardnd.py FunctionInfo lifecycle seams.
+ * Upstream revision: 308b1c3efd8c1c69bcc3eb82deeaec64fd3662ec.
+ * SPDX-License-Identifier: Apache-2.0 AND MIT
+ * Modified: mutable analysis result state isolated from execution and reporting.
+ */
+export declare class AttributeError extends Error {
+    constructor(targetName: string, attributeName: string);
+}
+/** One lexical nesting level. */
+export declare class Nesting {
+    get nameInSpace(): string;
+    get name_in_space(): string;
+}
+export declare const BARE_NESTING: Nesting;
+/** A named namespace/class scope in a function name. */
+export declare class Namespace extends Nesting {
+    readonly name: string;
+    constructor(name: string);
+    get nameInSpace(): string;
+}
+/** Lizard's mutable per-function metrics model. */
+export declare class FunctionInfo extends Nesting {
+    name: string;
+    filename: string;
+    startLine: number;
+    cyclomaticComplexity: number;
+    nloc: number;
+    tokenCount: number;
+    longName: string;
+    endLine: number;
+    fullParameters: string[];
+    topNestingLevel: number;
+    fanIn: number;
+    fanOut: number;
+    generalFanOut: number;
+    maxNestingDepth: number;
+    /** Source lizardcomplextags.py storage; absent until its processor observes a token. */
+    complexTags: [string, number][] | undefined;
+    /** Source lizardnd.py's per-function mutable processor state. */
+    nestingDepth: number;
+    hiddenBracket: number;
+    bracketLoop: boolean;
+    inCondition: boolean;
+    conditionDepth: number;
+    logicalOperatorAdded: boolean;
+    prevWasElse: boolean;
+    forgivenMetrics: Set<string>;
+    constructor(name: string, filename: string, startLine?: number, ccn?: number);
+    /**
+     * Source-name aliases share the camel-case storage above.  They are an
+     * analyzer-internal translation seam for extension bodies, not a Product API.
+     */
+    get cyclomatic_complexity(): number;
+    set cyclomatic_complexity(value: number);
+    get token_count(): number;
+    set token_count(value: number);
+    get long_name(): string;
+    set long_name(value: string);
+    get start_line(): number;
+    set start_line(value: number);
+    get end_line(): number;
+    set end_line(value: number);
+    get full_parameters(): string[];
+    set full_parameters(value: string[]);
+    get top_nesting_level(): number;
+    set top_nesting_level(value: number);
+    get fan_in(): number;
+    set fan_in(value: number);
+    get fan_out(): number;
+    set fan_out(value: number);
+    get general_fan_out(): number;
+    set general_fan_out(value: number);
+    get max_nesting_depth(): number;
+    set max_nesting_depth(value: number);
+    get complex_tags(): [string, number][] | undefined;
+    set complex_tags(value: [string, number][] | undefined);
+    get nesting_depth(): number;
+    set nesting_depth(value: number);
+    get hidden_bracket(): number;
+    set hidden_bracket(value: number);
+    get bracket_loop(): boolean;
+    set bracket_loop(value: boolean);
+    get in_condition(): boolean;
+    set in_condition(value: boolean);
+    get condition_depth(): number;
+    set condition_depth(value: number);
+    get logical_operator_added(): boolean;
+    set logical_operator_added(value: boolean);
+    get prev_was_else(): boolean;
+    set prev_was_else(value: boolean);
+    get forgiven_metrics(): Set<string>;
+    set forgiven_metrics(value: Set<string>);
+    get nameInSpace(): string;
+    get unqualifiedName(): string;
+    get unqualified_name(): string;
+    get location(): string;
+    get parameterCount(): number;
+    get parameter_count(): number;
+    get parameters(): string[];
+    get length(): number;
+    addToFunctionName(appended: string): void;
+    add_to_function_name(appended: string): void;
+    addToLongName(appended: string): void;
+    add_to_long_name(appended: string): void;
+    addParameter(token: string): void;
+    add_parameter(token: string): void;
+}
+/** Lizard's mutable aggregate for a single source file. */
+export declare class FileInformation {
+    filename: string;
+    nloc: number;
+    functionList: FunctionInfo[];
+    tokenCount: number;
+    constructor(filename: string, nloc: number, functionList?: FunctionInfo[]);
+    /** Source-name aliases share the camel-case storage for internal extensions. */
+    get function_list(): FunctionInfo[];
+    set function_list(value: FunctionInfo[]);
+    get token_count(): number;
+    set token_count(value: number);
+    get averageNloc(): number;
+    get average_nloc(): number;
+    get averageTokenCount(): number;
+    get average_token_count(): number;
+    get averageCyclomaticComplexity(): number;
+    get average_cyclomatic_complexity(): number;
+    get ccn(): number;
+    get CCN(): number;
+    get nestingDepth(): number;
+    get ND(): number;
+    functionsAverage(attribute: string): number;
+    functions_average(attribute: string): number;
+}

package/types/package-checks/function-metrics/analyzer/contracts.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Analyzer-internal TypeScript contracts for reader and token-processor composition.
+ * This type-only host seam is erased at runtime: it neither copies nor implements
+ * translated Lizard behavior and is intentionally outside translated-source provenance.
+ */
+import type { FileInfoBuilder } from "./analysis-context.ts";
+import type { LizardExtension } from "./extensions/protocol.ts";
+export type TokenStream = Iterable<string>;
+/** The minimum reader contract used by the in-memory Lizard pipeline. */
+export interface AnalyzerReader {
+    readonly conditions: ReadonlySet<string>;
+    readonly controlFlowKeywords: ReadonlySet<string>;
+    readonly logicalOperators: ReadonlySet<string>;
+    readonly caseKeywords: ReadonlySet<string>;
+    readonly ternaryOperators: ReadonlySet<string>;
+    readonly control_flow_keywords: ReadonlySet<string>;
+    readonly logical_operators: ReadonlySet<string>;
+    readonly case_keywords: ReadonlySet<string>;
+    readonly ternary_operators: ReadonlySet<string>;
+    readonly ext: readonly string[];
+    readonly languages: unknown;
+    readonly languageNames: readonly string[];
+    /** Source `language_names` alias used by translated internal extensions. */
+    readonly language_names: readonly string[];
+    readonly extraSubclasses: ReadonlySet<unknown>;
+    readonly extra_subclasses: ReadonlySet<unknown>;
+    readonly parallelStates: readonly unknown[];
+    readonly parallel_states: readonly unknown[];
+    readonly context: FileInfoBuilder;
+    /** Optional source reader attributes consumed by lizardnd.py. */
+    readonly loops?: readonly string[] | ReadonlySet<string>;
+    readonly bracket?: string;
+    readonly loop_indicator?: string;
+    readonly indent_indicator?: string;
+    __call__(tokens: TokenStream, reader: AnalyzerReader): TokenStream;
+    getCommentFromToken(token: string): string | undefined;
+    process(tokens: TokenStream): TokenStream;
+    preprocess?(tokens: TokenStream): TokenStream;
+}
+/** A concrete reader supplies its tokenizer and receives a per-file context. */
+export interface ReaderConstructor<Reader extends AnalyzerReader = AnalyzerReader> {
+    new (context: FileInfoBuilder): Reader;
+    generateTokens(sourceCode: string): TokenStream;
+}
+/** One source-aligned stage between tokenization and reader state processing. */
+export type TokenProcessor = (tokens: TokenStream, reader: AnalyzerReader) => TokenStream;
+/** A core processor or one internal Lizard extension processor. */
+export type AnalyzerProcessor = TokenProcessor | LizardExtension;

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

@@ -0,0 +1,13 @@
+/**
+ * Derived from terryyin/lizard 1.24.0.
+ * Source: lizard_ext/lizardcomplextags.py.
+ * Upstream revision: 308b1c3efd8c1c69bcc3eb82deeaec64fd3662ec.
+ * SPDX-License-Identifier: MIT
+ * Modified: mechanically translated to the Check-private TypeScript port.
+ */
+import type { AnalyzerReader, TokenStream } from "../contracts.ts";
+import type { LizardExtension as LizardExtensionProtocol } from "./protocol.ts";
+/** Records every source reader condition token with its current source line. */
+export declare class LizardExtension implements LizardExtensionProtocol {
+    __call__(tokens: TokenStream, reader: AnalyzerReader): Generator<string>;
+}