@fraction12/deepclean 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## Unreleased
+
+- Added repo-specific verification inference so generated candidates and plans point at real local checks such as Makefile targets, frontend package scripts, and admin package scripts instead of generic commands.
+- Added explicit `reportPath`, `markdownPath`, `jsonPath`, and `planPath` fields to JSON output for automation.
+- Improved Markdown reports with a focused `Agent Queue`, bounded themes before too-broad themes, and a capped candidate appendix while preserving full raw records in JSON.
+
+## 0.1.0-alpha.0 - 2026-05-24
+
+- Added the public-alpha CLI package surface with installable `deepclean` binary metadata.
+- Added global flag parsing before or after commands, including `deepclean --root ./repo scan --synthesize`.
+- Added configurable local candidate caps, broad-theme splitting, and too-broad theme warnings.
+- Added report recommendations with `Start Here`, suggested plan targets, theme warnings, and machine-readable recommendation data.
+- Added configurable reviewer packs with built-in reviewer selection and source-safe custom reviewer path loading.
+- Added privacy/trust and troubleshooting docs.
+- Added package smoke testing from the packed tarball.
+- Added CI and release checks that reject private/local artifacts from the package tarball.
+- Added SARIF ingestion and optional `jscpd` external duplicate evidence.
+- Removed self-dogfood state from the repo working tree and tightened ignore rules for local artifacts.
+- Added a vendored MIT-licensed Matt Pocock skills reference snapshot and distilled reviewer rubrics for deep module discipline, feedback loops, and agent-ready cleanup slices.
+- Hardened Clawpatch-style deslop mapping: TS/JS `.js` source specifiers now resolve to local TS source files, dynamic imports and `require(...)` are included in graph evidence, optional Semgrep orchestration is supported, report recommendations prefer strong synthesized findings over weak metric noise, and generated plans dedupe repeated file references.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# deepclean
+
+Clawpatch-style cleanup reports for working-but-sloppy codebases.
+
+`deepclean` is intended to help after a few days of AI-assisted coding: the app works, but the codebase needs architecture tightening, duplication removal, complexity reduction, better seams, stronger tests, and clearer domain language.
+
+## Status
+
+Public-alpha ready local CLI. Product planning lives in `openspec/`.
+
+## Install
+
+```bash
+npm install -g @fraction12/deepclean
+deepclean --version
+```
+
+From a fresh repo:
+
+```bash
+deepclean init
+deepclean scan --json
+deepclean report
+deepclean next
+deepclean plan candidate-001
+```
+
+With local Codex synthesis:
+
+```bash
+deepclean scan --synthesize --json
+deepclean report
+deepclean plan theme-001
+```
+
+Global flags work before or after the command:
+
+```bash
+deepclean --root ./some-repo scan --synthesize
+deepclean scan --root ./some-repo --synthesize
+```
+
+## Intended Flow
+
+```bash
+deepclean init
+deepclean scan
+deepclean scan --synthesize
+deepclean report
+deepclean cluster
+deepclean plan theme-001 --format codex
+deepclean next
+deepclean show <candidate-id>
+deepclean triage <candidate-id> --status ignored --note "intentional boundary"
+deepclean handoff <candidate-id> --format codex
+```
+
+## Principles
+
+- Report first; no source mutation in the MVP.
+- Structured local evidence before model review.
+- Durable state under `.deepclean/`.
+- Local code stays local unless the user explicitly enables researched context.
+- Architecture review is one reviewer, not the whole product.
+
+## Agent UX
+
+All core commands support `--json` for machine-readable output.
+
+```bash
+deepclean scan --json
+deepclean scan --synthesize --json
+deepclean report --json
+deepclean cluster --json
+deepclean plan theme-001 --json
+deepclean next --json
+deepclean show candidate-001 --json
+deepclean handoff candidate-001 --json
+```
+
+Useful global flags:
+
+- `--root <path>`
+- `--state-dir <path>`
+- `--config <path>`
+- `--no-input`
+- `--quiet`
+- `--debug`
+
+## Codex Synthesis
+
+`deepclean scan --synthesize` runs the local `codex` CLI in read-only mode over the collected evidence bundle. The model is asked to return strict JSON, and candidates without valid evidence IDs are rejected.
+
+Synthesis uses a built-in reviewer pack rather than whatever agent skills happen to be installed locally. That keeps runs reproducible. The current pack covers architecture deepening, deep module discipline, conceptual duplication, dependency graph blast radius, testability, feedback loop discipline, domain language drift, agent-ready cleanup slices, AI-slop patterns, and a critic pass that rejects weak one-metric findings.
+
+The reviewer pack is informed by a vendored MIT-licensed snapshot of Matt Pocock's engineering skills. Deepclean uses those skills as reference material and distills the useful principles into stable built-in rubrics instead of loading the full upstream skill text dynamically on every run.
+
+Reviewer packs can be configured in `.deepclean/config.json`:
+
+```json
+{
+  "reviewers": {
+    "enabled": ["architecture-deepening", "testability", "critic-pass"],
+    "customPaths": ["./deepclean-reviewers/security.md"]
+  }
+}
+```
+
+Before prompting Codex, Deepclean also maps evidence and existing local candidates into bounded cleanup surfaces. This is the Clawpatch-inspired part: the model reviews mapped repo areas and graph-connected themes rather than a loose pile of metrics.
+
+Source samples are redacted from the synthesis prompt by default. Use `--allow-source-in-model` only when the target repository and provider configuration make that acceptable.
+
+See [Reviewer References](docs/reviewer-references.md), [Privacy And Trust](docs/privacy-and-trust.md), and [Troubleshooting](docs/troubleshooting.md) before using synthesis on private repos.
+
+## Themes And Plans
+
+`deepclean cluster` groups related candidates into cleanup themes using shared files, shared evidence, module areas, title language, and the local import graph. Themes are persisted under `.deepclean/clusters/` and use stable `theme-001` style IDs for agent workflows. Individual cleanup candidates use `candidate-001` style IDs. Broad themes are split where possible and marked `too-broad` when they should not be handed to an agent as a single plan.
+
+`deepclean plan <candidate-or-theme-id>` writes a Codex-ready cleanup plan under `.deepclean/plans/`. Use theme plans when the report points at a larger cleanup area such as a tangled Next.js app area or a backend service boundary; use candidate plans for narrow local cleanup.
+
+Deepclean currently collects TypeScript, JavaScript, and Python source evidence. The local graph supports TS/JS relative imports and Python module imports, with cache/build/output directories excluded by default.
+For TS/JS projects using NodeNext-style source imports, Deepclean resolves emitted `.js` specifiers back to local `.ts`, `.tsx`, `.mts`, and `.cts` files so the graph maps source boundaries instead of falsely reporting an empty graph.
+
+## Evidence Engines
+
+Deepclean runs local evidence first and model synthesis second. The built-in layer includes:
+
+- file metrics
+- normalized line-window duplication
+- source/import graph summaries
+- TypeScript/JavaScript function and wrapper structure
+- Python import graph support
+- git churn signals
+- nearby test discovery
+- SARIF ingestion from Semgrep or similar tools
+- optional Semgrep SARIF orchestration when configured
+- optional `jscpd` duplicate ingestion when configured
+
+To use external analyzer evidence:
+
+```json
+{
+  "enabledAdapters": ["file-metrics", "sarif-ingest", "jscpd", "code-graph"],
+  "externalAnalyzers": {
+    "semgrep": {
+      "enabled": true,
+      "command": "semgrep",
+      "config": "auto",
+      "timeoutMs": 120000,
+      "maxFindings": 80
+    },
+    "jscpd": {
+      "enabled": true,
+      "command": "jscpd",
+      "minTokens": 80,
+      "maxFindings": 20
+    },
+    "sarifPaths": ["semgrep.sarif", ".semgrep/semgrep.sarif"]
+  }
+}
+```
+
+## Release Checks
+
+```bash
+npm run ci
+npm run spec:validate
+npm run release:check
+```
+
+The release check builds the package, runs tests, validates OpenSpec locally when available, packs the tarball, and rejects private/local artifacts such as `.deepclean/`, `.codex/`, `node_modules/`, source files, and local reports.

package/dist/args.d.ts

@@ -0,0 +1,9 @@
+export interface ParsedArgs {
+    command?: string;
+    positional: string[];
+    flags: Record<string, string | boolean>;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function legacyParseArgs(argv: string[]): ParsedArgs;
+export declare function flagString(flags: Record<string, string | boolean>, key: string): string | undefined;
+export declare function flagBoolean(flags: Record<string, string | boolean>, key: string): boolean;

package/dist/args.js

@@ -0,0 +1,105 @@
+export function parseArgs(argv) {
+    let command;
+    const positional = [];
+    const flags = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token) {
+            continue;
+        }
+        if (token.startsWith("--")) {
+            const withoutPrefix = token.slice(2);
+            const equalsIndex = withoutPrefix.indexOf("=");
+            if (equalsIndex >= 0) {
+                const key = withoutPrefix.slice(0, equalsIndex);
+                const value = withoutPrefix.slice(equalsIndex + 1);
+                flags[key] = value;
+                continue;
+            }
+            const next = argv[index + 1];
+            if (valueFlags.has(withoutPrefix)) {
+                if (next && !next.startsWith("-")) {
+                    flags[withoutPrefix] = next;
+                    index += 1;
+                }
+                else {
+                    flags[withoutPrefix] = "";
+                }
+            }
+            else {
+                flags[withoutPrefix] = true;
+            }
+            continue;
+        }
+        if (token.startsWith("-") && token.length > 1) {
+            const shortFlags = token.slice(1).split("");
+            for (const flag of shortFlags) {
+                flags[flag] = true;
+            }
+            continue;
+        }
+        if (!command) {
+            command = token;
+        }
+        else {
+            positional.push(token);
+        }
+    }
+    return command ? { command, positional, flags } : { positional, flags };
+}
+const valueFlags = new Set([
+    "root",
+    "state-dir",
+    "config",
+    "model",
+    "status",
+    "note",
+    "format",
+]);
+export function legacyParseArgs(argv) {
+    const [command, ...rest] = argv;
+    const positional = [];
+    const flags = {};
+    for (let index = 0; index < rest.length; index += 1) {
+        const token = rest[index];
+        if (!token) {
+            continue;
+        }
+        if (token.startsWith("--")) {
+            const withoutPrefix = token.slice(2);
+            const equalsIndex = withoutPrefix.indexOf("=");
+            if (equalsIndex >= 0) {
+                const key = withoutPrefix.slice(0, equalsIndex);
+                const value = withoutPrefix.slice(equalsIndex + 1);
+                flags[key] = value;
+                continue;
+            }
+            const next = rest[index + 1];
+            if (next && !next.startsWith("-")) {
+                flags[withoutPrefix] = next;
+                index += 1;
+            }
+            else {
+                flags[withoutPrefix] = true;
+            }
+            continue;
+        }
+        if (token.startsWith("-") && token.length > 1) {
+            const shortFlags = token.slice(1).split("");
+            for (const flag of shortFlags) {
+                flags[flag] = true;
+            }
+            continue;
+        }
+        positional.push(token);
+    }
+    return command ? { command, positional, flags } : { positional, flags };
+}
+export function flagString(flags, key) {
+    const value = flags[key];
+    return typeof value === "string" ? value : undefined;
+}
+export function flagBoolean(flags, key) {
+    return flags[key] === true;
+}
+//# sourceMappingURL=args.js.map

package/dist/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}

package/dist/candidates.d.ts

@@ -0,0 +1,6 @@
+import { type VerificationProfile } from "./verification.js";
+import { type CandidateRecord, type DeepcleanConfig, type EvidenceRecord } from "./types.js";
+export type CandidateCaps = DeepcleanConfig["candidateCaps"];
+export declare function candidatesFromEvidence(runId: string, evidence: EvidenceRecord[], createdAt: string, caps?: CandidateCaps, verificationProfile?: VerificationProfile): CandidateRecord[];
+export declare function rankCandidates(candidates: CandidateRecord[]): CandidateRecord[];
+export declare function reassignCandidateIds(candidates: CandidateRecord[]): CandidateRecord[];

package/dist/candidates.js

@@ -0,0 +1,319 @@
+import { candidateId, } from "./ids.js";
+import { commandsForFiles } from "./verification.js";
+import { schemaVersion, } from "./types.js";
+const priorityScore = {
+    P0: 0,
+    P1: 1,
+    P2: 2,
+    P3: 3,
+};
+export function candidatesFromEvidence(runId, evidence, createdAt, caps, verificationProfile) {
+    const sortedEvidence = [...evidence].sort(compareEvidence);
+    const candidates = [];
+    const kindCounts = new Map();
+    const areaKindCounts = new Map();
+    for (const record of sortedEvidence) {
+        if (!shouldCreateLocalCandidate(record, kindCounts, areaKindCounts, caps)) {
+            continue;
+        }
+        const candidate = candidateForEvidence(record, runId, createdAt, candidates.length, verificationProfile);
+        if (!candidate) {
+            continue;
+        }
+        candidates.push(candidate);
+        kindCounts.set(record.kind, (kindCounts.get(record.kind) ?? 0) + 1);
+        for (const area of candidateAreas(candidate)) {
+            const key = `${record.kind}:${area}`;
+            areaKindCounts.set(key, (areaKindCounts.get(key) ?? 0) + 1);
+        }
+    }
+    return reassignCandidateIds(rankCandidates(candidates));
+}
+export function rankCandidates(candidates) {
+    return [...candidates].sort((a, b) => {
+        const priorityDelta = priorityScore[a.priority] - priorityScore[b.priority];
+        if (priorityDelta !== 0) {
+            return priorityDelta;
+        }
+        const provenanceDelta = provenanceScore(b) - provenanceScore(a);
+        if (provenanceDelta !== 0) {
+            return provenanceDelta;
+        }
+        const impactDelta = impactScore(b.impact) - impactScore(a.impact);
+        if (impactDelta !== 0) {
+            return impactDelta;
+        }
+        const confidenceDelta = confidenceScore(b.confidence) - confidenceScore(a.confidence);
+        if (confidenceDelta !== 0) {
+            return confidenceDelta;
+        }
+        return a.id.localeCompare(b.id);
+    });
+}
+function shouldCreateLocalCandidate(evidence, kindCounts, areaKindCounts, caps) {
+    const kindLimit = localCandidateKindLimit(evidence.kind, caps);
+    if (kindLimit !== undefined && (kindCounts.get(evidence.kind) ?? 0) >= kindLimit) {
+        return false;
+    }
+    const areaLimit = localCandidateAreaLimit(evidence.kind, caps);
+    if (areaLimit === undefined) {
+        return true;
+    }
+    const areas = evidence.files.length > 0
+        ? [...new Set(evidence.files.map((file) => candidateArea(file.path)))]
+        : [evidence.kind];
+    return areas.some((area) => (areaKindCounts.get(`${evidence.kind}:${area}`) ?? 0) < areaLimit);
+}
+function localCandidateKindLimit(kind, caps) {
+    const configured = caps?.byKind[kind];
+    if (configured !== undefined) {
+        return configured;
+    }
+    switch (kind) {
+        case "duplicate-cluster":
+            return 16;
+        case "dependency-hotspot":
+            return 24;
+        case "large-function":
+            return 24;
+        case "large-file":
+            return 24;
+        case "test-gap":
+            return 24;
+        case "churn-hotspot":
+            return 12;
+        case "shallow-wrapper-cluster":
+            return 16;
+        default:
+            return undefined;
+    }
+}
+function localCandidateAreaLimit(kind, caps) {
+    const configured = caps?.byKindAndArea[kind];
+    if (configured !== undefined) {
+        return configured;
+    }
+    switch (kind) {
+        case "duplicate-cluster":
+            return 4;
+        case "dependency-hotspot":
+        case "large-function":
+        case "large-file":
+        case "test-gap":
+            return 8;
+        default:
+            return undefined;
+    }
+}
+export function reassignCandidateIds(candidates) {
+    return candidates.map((candidate, index) => ({
+        ...candidate,
+        id: candidateId(index),
+    }));
+}
+function candidateForEvidence(evidence, runId, createdAt, index, verificationProfile) {
+    const verification = commandsForFiles(verificationProfile ?? {
+        defaultCommands: ["npm test", "npm run typecheck"],
+        pythonCommands: ["npm test", "npm run typecheck"],
+        frontendCommands: ["npm test", "npm run typecheck"],
+        adminCommands: ["npm test", "npm run typecheck"],
+    }, evidence.files, ["npm test", "npm run typecheck"]);
+    const base = {
+        schemaVersion,
+        recordType: "candidate",
+        id: candidateId(index),
+        runId,
+        status: "open",
+        files: evidence.files,
+        evidenceIds: [evidence.id],
+        provenance: {
+            source: "local-evidence",
+        },
+        createdAt,
+        updatedAt: createdAt,
+    };
+    switch (evidence.kind) {
+        case "duplicate-cluster":
+        case "external-duplicate":
+            return {
+                ...base,
+                title: evidence.title,
+                category: "duplication",
+                priority: evidence.confidence === "high" ? "P1" : "P2",
+                confidence: evidence.confidence,
+                impact: evidence.files.length >= 3 ? "cross-cutting" : "feature",
+                effort: "medium",
+                risk: "moderate",
+                whyItMatters: "Repeated code paths tend to drift after later AI edits, creating inconsistent behavior that tests may not cover.",
+                likelyRootCause: "Similar behavior was implemented in multiple places instead of being pulled into one domain-level module or shared component.",
+                suggestedDirection: "Inspect the duplicated call sites and decide whether the shared concept should become a single module, helper, component, or explicit abstraction.",
+                verification,
+            };
+        case "sarif-finding":
+            return {
+                ...base,
+                title: evidence.title,
+                category: "diagnostic",
+                priority: evidence.confidence === "high" ? "P1" : "P2",
+                confidence: evidence.confidence,
+                impact: evidence.files.length >= 3 ? "cross-cutting" : "feature",
+                effort: "medium",
+                risk: "moderate",
+                whyItMatters: "External analyzer findings can point at maintainability, correctness, or policy issues that local Deepclean heuristics should preserve as evidence.",
+                likelyRootCause: "A specialized analyzer found a source-level issue that needs human or agent review before structural cleanup.",
+                suggestedDirection: "Inspect the analyzer finding, decide whether it is real, and either address it directly or triage it with a note before deeper cleanup.",
+                verification,
+            };
+        case "dependency-hotspot":
+            return {
+                ...base,
+                title: evidence.title,
+                category: "architecture",
+                priority: evidence.confidence === "high" ? "P1" : "P2",
+                confidence: evidence.confidence,
+                impact: "cross-cutting",
+                effort: "medium",
+                risk: "design-needed",
+                whyItMatters: "Files with high fan-in or fan-out become expensive to change because unrelated features may depend on their shape.",
+                likelyRootCause: "Responsibilities may be concentrated in a broad helper, orchestration module, or feature file that needs clearer boundaries.",
+                suggestedDirection: "Review callers and imports, then separate stable domain logic from feature-specific coordination if the coupling is accidental.",
+                verification,
+            };
+        case "large-file":
+        case "large-function":
+            return {
+                ...base,
+                title: evidence.title,
+                category: "complexity",
+                priority: evidence.confidence === "high" ? "P1" : "P2",
+                confidence: evidence.confidence,
+                impact: "feature",
+                effort: evidence.confidence === "high" ? "large" : "medium",
+                risk: "moderate",
+                whyItMatters: "Large units are harder for agents and humans to review, test, and change without accidentally mixing concerns.",
+                likelyRootCause: "Fetching, state, validation, rendering, or orchestration logic may have accumulated in one place during fast implementation.",
+                suggestedDirection: "Map the responsibilities in this unit, extract stable domain logic first, and leave UI or orchestration behavior thin.",
+                verification,
+            };
+        case "test-gap":
+            return {
+                ...base,
+                title: evidence.title,
+                category: "testability",
+                priority: "P2",
+                confidence: evidence.confidence,
+                impact: "feature",
+                effort: "small",
+                risk: "safe",
+                whyItMatters: "Cleanup work is riskier when feature logic has weak nearby tests or no obvious verification path.",
+                likelyRootCause: "The feature may have been implemented before test seams or source-to-test structure were established.",
+                suggestedDirection: "Add targeted tests around the behavior before significant refactoring, especially for validation, state transitions, and edge cases.",
+                verification,
+            };
+        case "churn-hotspot":
+            return {
+                ...base,
+                title: evidence.title,
+                category: "architecture",
+                priority: evidence.confidence === "high" ? "P1" : "P2",
+                confidence: evidence.confidence,
+                impact: "feature",
+                effort: "medium",
+                risk: "design-needed",
+                whyItMatters: "High-churn files are often where messy abstractions and changing product behavior collide.",
+                likelyRootCause: "The module may be absorbing multiple concerns or serving as the easiest place for repeated agent edits.",
+                suggestedDirection: "Compare the churn history with current responsibilities and look for concepts that should move closer to their owners.",
+                verification,
+            };
+        case "shallow-wrapper-cluster":
+            return {
+                ...base,
+                title: evidence.title,
+                category: "ai-slop",
+                priority: "P2",
+                confidence: evidence.confidence,
+                impact: "feature",
+                effort: "small",
+                risk: "moderate",
+                whyItMatters: "Clusters of shallow wrappers create indirection without leverage and make agents chase names instead of concepts.",
+                likelyRootCause: "Fast AI-assisted implementation may have introduced wrapper helpers to make code look organized without creating real boundaries.",
+                suggestedDirection: "Review the cluster and keep only wrappers that name real domain concepts, centralize policy, or provide stable seams.",
+                verification,
+            };
+        default:
+            return undefined;
+    }
+}
+function compareEvidence(a, b) {
+    const kindDelta = evidenceKindScore(b.kind) - evidenceKindScore(a.kind);
+    if (kindDelta !== 0) {
+        return kindDelta;
+    }
+    const confidenceDelta = confidenceScore(b.confidence) - confidenceScore(a.confidence);
+    if (confidenceDelta !== 0) {
+        return confidenceDelta;
+    }
+    return a.id.localeCompare(b.id);
+}
+function evidenceKindScore(kind) {
+    switch (kind) {
+        case "duplicate-cluster":
+            return 80;
+        case "dependency-hotspot":
+            return 75;
+        case "large-function":
+            return 70;
+        case "large-file":
+            return 65;
+        case "churn-hotspot":
+            return 60;
+        case "test-gap":
+            return 45;
+        case "shallow-wrapper-cluster":
+            return 20;
+        default:
+            return 0;
+    }
+}
+function confidenceScore(confidence) {
+    switch (confidence) {
+        case "high":
+            return 3;
+        case "medium":
+            return 2;
+        case "low":
+            return 1;
+    }
+}
+function impactScore(impact) {
+    switch (impact) {
+        case "cross-cutting":
+            return 3;
+        case "feature":
+            return 2;
+        case "local":
+            return 1;
+    }
+}
+function provenanceScore(candidate) {
+    return candidate.provenance.source === "model-synthesis" ? 2 : 1;
+}
+function candidateAreas(candidate) {
+    return [...new Set(candidate.files.map((file) => candidateArea(file.path)))];
+}
+function candidateArea(filePath) {
+    const parts = filePath.split("/").filter(Boolean);
+    if (parts.length === 0) {
+        return ".";
+    }
+    const srcIndex = parts.indexOf("src");
+    if (srcIndex >= 0) {
+        const end = Math.min(parts.length - 1, srcIndex + 3);
+        return parts.slice(0, end).join("/") || (parts[0] ?? ".");
+    }
+    if (parts.length <= 2) {
+        return parts.length === 1 ? "." : parts[0] ?? ".";
+    }
+    return parts.slice(0, 2).join("/");
+}
+//# sourceMappingURL=candidates.js.map