@zxyycom/vibe-check 0.0.1

package/src/package-checks/file-metrics/options.ts

@@ -0,0 +1,91 @@
+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";
+
+/** `fileMetrics` 构造函数可省略的 SCC 可执行文件策略。 */
+export interface FileMetricsScannerOptions {
+  /** 省略时直接执行 `scc`；显式命令必须直接接受 adapter 拥有的 SCC 参数。 */
+  readonly executable?: string;
+}
+
+/** file-metrics 区域可省略并由构造函数补齐的文件策略。 */
+export type FileMetricsFileOptions = ProjectFileSelectionOptions;
+
+/** SCC decision-token 数较低的文件可使用的代码行宽限策略。 */
+export interface FileMetricsLowDecisionTokenAllowanceOptions {
+  /** 省略时为 `600`；必须严格大于同一区域的普通代码行上限。 */
+  readonly maximumCodeLines?: number;
+  /** 省略时为 `12`；decision-token measurement 不大于此值时应用宽限上限。 */
+  readonly maximumDecisionTokens?: number;
+}
+
+/** 一个区域可省略的文件代码行策略。 */
+export interface FileMetricsCodeLineOptions {
+  /** 省略时为 `360`；只有严格超过此值才产生 finding。 */
+  readonly maximum?: number;
+  /** 省略时使用完整默认宽限策略。 */
+  readonly lowDecisionTokenAllowance?: FileMetricsLowDecisionTokenAllowanceOptions;
+}
+
+/** 可独立选择文件并定义代码行与 finding policy 的 file-metrics 区域。 */
+export interface FileMetricsCodeAreaOptions {
+  /** 显式区域必须声明本字段；其中各子字段可省略并使用 package 默认值。 */
+  readonly files: FileMetricsFileOptions;
+  /** 省略时继承顶层 `findingPolicy`。 */
+  readonly findingPolicy?: FindingPolicy;
+  /** 省略时使用 package 默认代码行策略。 */
+  readonly codeLines?: FileMetricsCodeLineOptions;
+}
+
+/** file-metrics 用于识别可豁免 finding 的稳定语义字段。 */
+export interface FileMetricsFindingIdentity {
+  /** file-metrics 当前只产生文件代码行 finding。 */
+  readonly metric: "code-lines";
+  /** 已 normalized 的 project-root-relative slash path；不得为绝对、含反斜杠或含 `.`/`..` 的路径。 */
+  readonly path: string;
+}
+
+/** 一项 file-metrics finding 的声明式豁免；执行时仍会扫描并发布该 finding。 */
+export type FileMetricsFindingWaiver = FindingWaiver<FileMetricsFindingIdentity>;
+
+/** `fileMetrics(options?)` 接受并补齐默认值的公开策略。 */
+export interface FileMetricsOptions {
+  /** 省略时建立默认 `project` 区域；显式映射必须非空。 */
+  readonly codeAreas?: Readonly<Record<string, FileMetricsCodeAreaOptions>>;
+  /** 省略时为 `non-blocking`；区域可局部覆盖。 */
+  readonly findingPolicy?: FindingPolicy;
+  /** 省略时没有豁免；每项以 `{ metric, path }` 精确匹配，并必须提供非空理由。 */
+  readonly findingWaivers?: readonly FileMetricsFindingWaiver[];
+  /** 省略时直接执行 `scc`；CLI 协议由 owning adapter 固定。 */
+  readonly scanner?: FileMetricsScannerOptions;
+}
+
+/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+export interface ResolvedFileMetricsOptions {
+  readonly codeAreas: Readonly<Record<string, ResolvedFileMetricsCodeAreaOptions>>;
+  readonly findingWaivers: readonly FileMetricsFindingWaiver[];
+  readonly scanner: ResolvedFileMetricsScannerOptions;
+}
+
+export interface ResolvedFileMetricsCodeAreaOptions {
+  readonly codeLines: ResolvedFileMetricsCodeLineOptions;
+  readonly files: ProjectFileSelection;
+  readonly findingPolicy: FindingPolicy;
+}
+
+export interface ResolvedFileMetricsCodeLineOptions {
+  readonly lowDecisionTokenAllowance: ResolvedFileMetricsLowDecisionTokenAllowanceOptions;
+  readonly maximum: number;
+}
+
+export interface ResolvedFileMetricsLowDecisionTokenAllowanceOptions {
+  readonly maximumCodeLines: number;
+  readonly maximumDecisionTokens: number;
+}
+
+export interface ResolvedFileMetricsScannerOptions {
+  readonly executable: string;
+}

package/src/package-checks/file-metrics/records.ts

@@ -0,0 +1,182 @@
+import type { FileMetric } from "./measurement-model.ts";
+import type { FileMetricsFindingIdentity, ResolvedFileMetricsCodeAreaOptions } from "./options.ts";
+import { isBlockingFinding } from "../code-quality-findings/policy.ts";
+import { isNormalizedProjectRelativePath } from "../host-environment/path.ts";
+import type {
+  FindingWaiverAudit,
+  MaterializedFindingWaiver
+} from "../../finding-waivers/reconciliation.ts";
+import type {
+  CanonicalJsonObject,
+  CanonicalJsonValue
+} from "../../data-boundary/canonical-data.ts";
+
+const FILE_CODE_LINES_METRIC = "code-lines" as const;
+const FINDING_WAIVER_AUDIT_RECORD_ID_PREFIX = "/finding-waiver-audit/";
+
+interface FileMetricsAreaPolicyContext {
+  readonly areaIdsByPath: ReadonlyMap<string, readonly string[]>;
+  readonly codeAreas: Readonly<Record<string, ResolvedFileMetricsCodeAreaOptions>>;
+}
+
+interface EffectiveFileRecordPolicy {
+  readonly areaIds: readonly string[];
+  readonly blocking: boolean;
+  readonly limit: number;
+}
+
+/** 一条超出文件代码行上限的 supplemental Record data。 */
+export type FileMetricsFindingRecordData = Readonly<{
+  readonly blocking: boolean;
+  readonly codeAreas: readonly string[];
+  readonly codeLines: number;
+  readonly limit: number;
+  readonly metric: "code-lines";
+  readonly path: string;
+  /** 精确匹配 waiver 时保留理由，并令该 finding 不再参与 actionable settlement。 */
+  readonly waiver?: Readonly<{ readonly reason: string }>;
+}>;
+
+/** 未使用或过宽 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";
+}>;
+
+/** file-metrics 发布的 finding 或 waiver-audit supplemental Record data。 */
+export type FileMetricsRecordData =
+  | FileMetricsFindingRecordData
+  | FileMetricsFindingWaiverAuditRecordData;
+
+export interface FileRecordCandidate {
+  readonly data: FileMetricsFindingRecordData;
+  readonly id: string;
+}
+
+/** 仅为未使用和过宽 waiver 构造补充 audit Record；正常 applied waiver 由 finding Record 自己保留。 */
+export function fileMetricsWaiverAuditRecord(
+  audit: FindingWaiverAudit
+):
+  | Readonly<{ readonly data: FileMetricsFindingWaiverAuditRecordData; readonly id: string }>
+  | undefined {
+  if (audit.status === "applied") return undefined;
+  const identity = fileMetricsWaiverIdentity(audit.waiver);
+  return Object.freeze({
+    data: Object.freeze({
+      identity,
+      kind: "finding-waiver-audit",
+      matchCount: audit.matchCount,
+      reason: audit.waiver.reason,
+      status: audit.status
+    }),
+    id: `${FINDING_WAIVER_AUDIT_RECORD_ID_PREFIX}${identity.path}`
+  });
+}
+
+export function fileMetricsWaiverIdentity(
+  waiver: MaterializedFindingWaiver
+): FileMetricsFindingIdentity {
+  const identity = waiver.identity;
+  if (
+    !isCanonicalObject(identity) ||
+    identity.metric !== "code-lines" ||
+    typeof identity.path !== "string" ||
+    !isNormalizedProjectRelativePath(identity.path)
+  ) {
+    throw new TypeError("fileMetrics waiver identity must retain a normalized code-lines path");
+  }
+  return Object.freeze({ metric: "code-lines", path: identity.path });
+}
+
+function isCanonicalObject(value: CanonicalJsonValue): value is CanonicalJsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Converts trusted scanner metrics into area-policy-owned supplemental facts. */
+export function buildFileRecordCandidates(
+  metrics: readonly FileMetric[],
+  areaPolicy: FileMetricsAreaPolicyContext
+): readonly FileRecordCandidate[] | undefined {
+  const seenPaths = new Set<string>();
+  const candidates: FileRecordCandidate[] = [];
+  for (const metric of metrics) {
+    if (!isValidUniqueFileMetric(metric, seenPaths)) return undefined;
+    seenPaths.add(metric.path);
+
+    const recordPolicy = effectiveFileRecordPolicy(metric, areaPolicy);
+    if (recordPolicy === undefined) return undefined;
+    if (metric.codeLines <= recordPolicy.limit) continue;
+    candidates.push(createFileRecordCandidate(metric, recordPolicy));
+  }
+  candidates.sort((left, right) => compareText(left.id, right.id));
+  return Object.freeze(candidates);
+}
+
+function isValidUniqueFileMetric(metric: FileMetric, seenPaths: ReadonlySet<string>): boolean {
+  return (
+    typeof metric.path === "string" &&
+    metric.path.length > 0 &&
+    Number.isSafeInteger(metric.codeLines) &&
+    metric.codeLines >= 0 &&
+    !seenPaths.has(metric.path)
+  );
+}
+
+function effectiveFileRecordPolicy(
+  metric: FileMetric,
+  areaPolicy: FileMetricsAreaPolicyContext
+): EffectiveFileRecordPolicy | undefined {
+  const areaIds = areaPolicy.areaIdsByPath.get(metric.path);
+  if (areaIds === undefined || areaIds.length === 0) return undefined;
+  const matchingAreas: ResolvedFileMetricsCodeAreaOptions[] = [];
+  let strictestMaximum: number | undefined;
+  for (const areaId of areaIds) {
+    const codeArea = areaPolicy.codeAreas[areaId];
+    if (codeArea === undefined) return undefined;
+    matchingAreas.push(codeArea);
+    const maximum = fileCodeLineMaximum(metric, codeArea);
+    strictestMaximum =
+      strictestMaximum === undefined ? maximum : Math.min(strictestMaximum, maximum);
+  }
+  return strictestMaximum === undefined
+    ? undefined
+    : Object.freeze({
+        areaIds,
+        blocking: isBlockingFinding(matchingAreas.map((area) => area.findingPolicy)),
+        limit: strictestMaximum
+      });
+}
+
+function createFileRecordCandidate(
+  metric: FileMetric,
+  recordPolicy: EffectiveFileRecordPolicy
+): FileRecordCandidate {
+  return Object.freeze({
+    id: metric.path,
+    data: Object.freeze({
+      blocking: recordPolicy.blocking,
+      codeAreas: Object.freeze([...recordPolicy.areaIds]),
+      codeLines: metric.codeLines,
+      limit: recordPolicy.limit,
+      metric: FILE_CODE_LINES_METRIC,
+      path: metric.path
+    })
+  });
+}
+
+function fileCodeLineMaximum(metric: FileMetric, area: ResolvedFileMetricsCodeAreaOptions): number {
+  const allowance = area.codeLines.lowDecisionTokenAllowance;
+  const decisionTokens = metric.decisionTokens.value;
+  return decisionTokens !== null && decisionTokens <= allowance.maximumDecisionTokens
+    ? allowance.maximumCodeLines
+    : area.codeLines.maximum;
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

package/src/package-checks/file-metrics/scc/availability.ts

@@ -0,0 +1,100 @@
+import { errorMessage } from "../../host-environment/error-message.ts";
+import { processFailure, runProcess } from "../../host-environment/process/command.ts";
+import type { ResolvedFileMetricsScannerOptions } from "../options.ts";
+import { SCC_VERSION_OUTPUT } from "./parser.ts";
+
+const SCC_VERSION_ARGUMENTS = Object.freeze(["--version"]);
+
+type SccAvailability = Readonly<
+  | {
+      readonly available: true;
+      readonly error: null;
+      readonly name: "scc";
+      readonly reason: null;
+      readonly source: "configured command";
+      readonly version: string;
+    }
+  | {
+      readonly available: false;
+      readonly error: string;
+      readonly name: "scc";
+      readonly reason: "contract-error" | "execution-error" | "tool-unavailable";
+      readonly source: "configured command";
+      readonly version: null;
+    }
+>;
+
+type SccVersionCommandResult = Awaited<ReturnType<typeof runProcess>>;
+
+export async function checkScc(
+  rootDir: string,
+  scanner: ResolvedFileMetricsScannerOptions
+): Promise<SccAvailability> {
+  try {
+    const commandResult = await runProcess({
+      args: SCC_VERSION_ARGUMENTS,
+      command: scanner.executable,
+      cwd: rootDir
+    });
+    return availabilityFromVersionResult(commandResult);
+  } catch (error: unknown) {
+    return unavailableScc(`scc version error: ${errorMessage(error)}`, "execution-error");
+  }
+}
+
+function availabilityFromVersionResult(commandResult: SccVersionCommandResult): SccAvailability {
+  if (commandResult.error) return processErrorAvailability(commandResult.error);
+  const version = commandOutput(commandResult);
+  if (commandResult.status !== 0) {
+    return unavailableScc(
+      `scc --version failed, ${processTermination(commandResult)}${version ? `: ${version}` : ""}`,
+      "execution-error"
+    );
+  }
+  if (version !== SCC_VERSION_OUTPUT) {
+    return unavailableScc(
+      `expected ${SCC_VERSION_OUTPUT}, got "${version || "unknown"}"`,
+      "contract-error"
+    );
+  }
+  return {
+    name: "scc",
+    available: true,
+    version,
+    error: null,
+    source: "configured command",
+    reason: null
+  };
+}
+
+function processErrorAvailability(error: Error): SccAvailability {
+  const isMissingTool = processFailure(error).code === "ENOENT";
+  return unavailableScc(
+    isMissingTool ? `scc not installed: ${error.message}` : `scc version error: ${error.message}`,
+    isMissingTool ? "tool-unavailable" : "execution-error"
+  );
+}
+
+function unavailableScc(
+  error: string,
+  reason: Exclude<SccAvailability["reason"], null>
+): SccAvailability {
+  return {
+    name: "scc",
+    available: false,
+    version: null,
+    error,
+    source: "configured command",
+    reason
+  };
+}
+
+function commandOutput(commandResult: SccVersionCommandResult): string {
+  return (commandResult.stdout || "").trim() || (commandResult.stderr || "").trim();
+}
+
+function processTermination(commandResult: SccVersionCommandResult): string {
+  return typeof commandResult.status === "number"
+    ? `exit ${commandResult.status}`
+    : `signal ${commandResult.signal || "unknown"}`;
+}

package/src/package-checks/file-metrics/scc/csv.ts

@@ -0,0 +1,20 @@
+import { parse } from "csv-parse/sync";
+
+export function parseCsvRows(csv: string): string[][] {
+  const records: unknown = parse(csv, {
+    bom: true,
+    relax_column_count: true,
+    skip_empty_lines: true,
+    trim: true
+  });
+
+  if (!Array.isArray(records) || !records.every(isStringRow)) {
+    throw new Error("CSV parser returned non-string rows");
+  }
+
+  return records;
+}
+
+function isStringRow(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}

package/src/package-checks/file-metrics/scc/parser.ts

@@ -0,0 +1,223 @@
+import type { ExactInputMeasurement } from "../../project-files/exact-input-measurement.ts";
+import { errorMessage } from "../../host-environment/error-message.ts";
+import { normalizeScannerReportedPath } from "../../project-files/reported-path.ts";
+import type { FileMetric } from "../measurement-model.ts";
+import { parseCsvRows } from "./csv.ts";
+
+export const SCC_VERSION = "3.7.0";
+export const SCC_VERSION_OUTPUT = `scc version ${SCC_VERSION}`;
+export const SCC_BY_FILE_CSV_HEADER =
+  "Language,Provider,Filename,Lines,Code,Comments,Blanks,Complexity,Bytes,ULOC";
+
+export type SccScanResult =
+  | {
+      readonly measurements: readonly ExactInputMeasurement<FileMetric>[];
+      readonly ok: true;
+    }
+  | {
+      readonly error: string;
+      readonly ok: false;
+      readonly reason: "execution" | "invalid-result";
+    };
+
+interface SccColumnIndexes {
+  blanks: number;
+  code: number;
+  comments: number;
+  complexity: number;
+  filename: number;
+  lines: number;
+  provider: number;
+}
+
+interface ParsedSccRow {
+  readonly codeLines: number;
+  readonly complexity: number | null;
+  readonly path: string;
+}
+
+interface SccRawRow {
+  readonly blankLines: string;
+  readonly codeLines: string;
+  readonly commentLines: string;
+  readonly complexity: string;
+  readonly filename: string;
+  readonly lineCount: string;
+  readonly providerPath: string;
+}
+
+/**
+ * 解析 scc CSV 输出。
+ *
+ * scc 3.7.0 `--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
+ */
+export function parseSccCSV(csv: string, cwd: string): SccScanResult {
+  try {
+    const rows = parseCsvRows(csv);
+    const headerIndex = findSccHeaderIndex(rows);
+    if (headerIndex < 0) {
+      return {
+        ok: false,
+        error: `expected scc ${SCC_VERSION} by-file CSV header "${SCC_BY_FILE_CSV_HEADER}", got "${observedSccHeader(rows)}"`,
+        reason: "invalid-result"
+      };
+    }
+
+    const columns = sccColumnIndexes(rows[headerIndex] ?? []);
+    const measurements = parseSccMetrics(
+      rows.slice(headerIndex + 1),
+      columns,
+      headerIndex + 2,
+      cwd
+    );
+    return {
+      ok: true,
+      measurements
+    };
+  } catch (error: unknown) {
+    return {
+      ok: false,
+      error: `Failed to parse scc CSV: ${errorMessage(error)}`,
+      reason: "invalid-result"
+    };
+  }
+}
+
+function findSccHeaderIndex(rows: string[][]): number {
+  const expectedHeader = SCC_BY_FILE_CSV_HEADER.split(",");
+  return rows.findIndex((row) => isCsvRow(row, expectedHeader));
+}
+
+function observedSccHeader(rows: string[][]): string {
+  return rows.find((row) => row[0] === "Language")?.join(",") ?? rows[0]?.join(",") ?? "";
+}
+
+function sccColumnIndexes(headerColumns: string[]): SccColumnIndexes {
+  return {
+    provider: headerColumns.indexOf("Provider"),
+    filename: headerColumns.indexOf("Filename"),
+    lines: headerColumns.indexOf("Lines"),
+    code: headerColumns.indexOf("Code"),
+    comments: headerColumns.indexOf("Comments"),
+    blanks: headerColumns.indexOf("Blanks"),
+    complexity: headerColumns.indexOf("Complexity")
+  };
+}
+
+function parseSccMetrics(
+  rows: string[][],
+  columns: SccColumnIndexes,
+  firstRowNumber: number,
+  cwd: string
+): ExactInputMeasurement<FileMetric>[] {
+  const measurements: ExactInputMeasurement<FileMetric>[] = [];
+
+  for (const [index, row] of rows.entries()) {
+    const measurement = parseSccFileMetric(row, columns, firstRowNumber + index, cwd);
+    measurements.push(measurement);
+  }
+
+  measurements.sort((left, right) => compareText(left.payload.path, right.payload.path));
+  return measurements;
+}
+
+function parseSccFileMetric(
+  rowValues: string[],
+  columns: SccColumnIndexes,
+  rowNumber: number,
+  cwd: string
+): ExactInputMeasurement<FileMetric> {
+  const row = parseSccRow(rowValues, columns, rowNumber);
+  const sourcePath = normalizeScannerReportedPath(row.path, cwd);
+  return {
+    sourcePaths: [sourcePath],
+    payload: {
+      path: sourcePath,
+      codeLines: row.codeLines,
+      decisionTokens: {
+        value: row.complexity,
+        source: "scc"
+      }
+    }
+  };
+}
+
+function parseSccRow(
+  rowValues: string[],
+  columns: SccColumnIndexes,
+  rowNumber: number
+): ParsedSccRow {
+  const expectedColumnCount = SCC_BY_FILE_CSV_HEADER.split(",").length;
+  if (rowValues.length !== expectedColumnCount) {
+    throw new Error(
+      `row ${rowNumber} has ${rowValues.length} columns; expected ${expectedColumnCount}`
+    );
+  }
+  const rawRow = sccRawRow(rowValues, columns);
+  if (!rawRow.filename) {
+    throw new Error(`row ${rowNumber} field Filename must not be empty`);
+  }
+  validateSccRowCounts(rawRow, rowNumber);
+
+  return {
+    path: rawRow.providerPath || rawRow.filename,
+    codeLines: parseRequiredInteger(rawRow.codeLines, "Code", rowNumber),
+    complexity: parseOptionalInteger(rawRow.complexity, "Complexity", rowNumber)
+  };
+}
+
+function validateSccRowCounts(row: SccRawRow, rowNumber: number): void {
+  parseRequiredInteger(row.lineCount, "Lines", rowNumber);
+  parseRequiredInteger(row.commentLines, "Comments", rowNumber);
+  parseRequiredInteger(row.blankLines, "Blanks", rowNumber);
+}
+
+function sccRawRow(rowValues: string[], columns: SccColumnIndexes): SccRawRow {
+  return {
+    blankLines: sccColumnValue(rowValues, columns.blanks),
+    codeLines: sccColumnValue(rowValues, columns.code),
+    commentLines: sccColumnValue(rowValues, columns.comments),
+    complexity: sccColumnValue(rowValues, columns.complexity),
+    filename: sccColumnValue(rowValues, columns.filename),
+    lineCount: sccColumnValue(rowValues, columns.lines),
+    providerPath: sccColumnValue(rowValues, columns.provider)
+  };
+}
+
+function parseRequiredInteger(value: string, field: string, rowNumber: number): number {
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`row ${rowNumber} field ${field} must be a non-negative integer`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new Error(`row ${rowNumber} field ${field} exceeds the supported integer range`);
+  }
+  return parsed;
+}
+
+function parseOptionalInteger(value: string, field: string, rowNumber: number): number | null {
+  return value === "" ? null : parseRequiredInteger(value, field, rowNumber);
+}
+
+function sccColumnValue(rowValues: string[], index: number): string {
+  return index >= 0 ? (rowValues[index] ?? "") : "";
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function isCsvRow(row: string[], expectedValues: string[]): boolean {
+  return (
+    row.length === expectedValues.length &&
+    row.every((value, index) => value === expectedValues[index])
+  );
+}

package/src/package-checks/file-metrics/scc/scanner.ts

@@ -0,0 +1,68 @@
+/**
+ * scc 文件级 code-line 指标 wrapper。
+ *
+ * 封装 adapter-owned CLI 调用，输出 exact-path code lines 与 decision-token count。
+ */
+
+import { errorMessage } from "../../host-environment/error-message.ts";
+import { runProcessSync } from "../../host-environment/process/command.ts";
+import type { ResolvedFileMetricsScannerOptions } from "../options.ts";
+import { parseSccCSV, type SccScanResult } from "./parser.ts";
+
+const SCC_BY_FILE_ARGUMENTS = Object.freeze(["--by-file", "--format", "csv"]);
+const SCC_SCAN_TIMEOUT_MS = 300_000;
+
+interface ScanWithSccOptions {
+  readonly cwd: string;
+  readonly includePaths: readonly string[];
+  readonly scanner: ResolvedFileMetricsScannerOptions;
+}
+
+export function scanWithScc({ cwd, includePaths, scanner }: ScanWithSccOptions): SccScanResult {
+  try {
+    if (includePaths.length === 0) return { ok: true, measurements: [] };
+
+    const scanArguments = buildSccArgs(includePaths);
+
+    const commandResult = runProcessSync({
+      args: scanArguments,
+      command: scanner.executable,
+      cwd,
+      timeout: SCC_SCAN_TIMEOUT_MS
+    });
+
+    if (commandResult.error) {
+      return {
+        ok: false,
+        error: `scc process error: ${commandResult.error.message}`,
+        reason: "execution"
+      };
+    }
+
+    if (commandResult.status !== 0) {
+      const stderr = (commandResult.stderr || "").trim();
+      const stdout = (commandResult.stdout || "").trim();
+      const termination =
+        commandResult.status === null
+          ? `signal ${commandResult.signal ?? "unknown"}`
+          : `exit ${commandResult.status}`;
+      return {
+        ok: false,
+        error: `scc ${termination}: ${stderr || stdout || "no output"}`,
+        reason: "execution"
+      };
+    }
+
+    return parseSccCSV(commandResult.stdout || "", cwd);
+  } catch (error: unknown) {
+    return {
+      ok: false,
+      error: `scc adapter error: ${errorMessage(error)}`,
+      reason: "execution"
+    };
+  }
+}
+
+function buildSccArgs(includePaths: readonly string[]): string[] {
+  return [...SCC_BY_FILE_ARGUMENTS, ...includePaths];
+}