patdown 0.3.1 → 0.5.0

package/dist/patdown-github-actions-output.js

@@ -0,0 +1,52 @@
+import { Console, Effect, FileSystem, Layer, Ref } from 'effect';
+import { readPatdownGitHubStepSummaryPath } from '#src/patdown-github-actions-env';
+import { formatPatdownGitHubActionsAnnotations, formatPatdownGitHubActionsSummary, } from '#src/patdown-github-actions-summary';
+import { PatdownOutput, patdownStreamingHumanOutput, } from '#src/patdown-output';
+/**
+ * Human stdout plus GitHub annotations and a step-summary heatmap. Intended when GITHUB_ACTIONS and
+ * GITHUB_STEP_SUMMARY are set.
+ */
+export const PatdownGitHubActionsOutputLive = Layer.effect(PatdownOutput, Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const state = yield* Ref.make({ results: [] });
+    const appendSummary = (markdown) => Effect.gen(function* () {
+        const summaryPath = yield* readPatdownGitHubStepSummaryPath;
+        if (summaryPath === null)
+            return;
+        yield* fileSystem.writeFileString(summaryPath, markdown, { flag: 'a' }).pipe(Effect.catch(() => Effect.sync(() => {
+            process.stderr.write('patdown: failed to write GitHub step summary\n');
+        })));
+    });
+    const publish = (failed, elapsedMs, results) => Effect.gen(function* () {
+        for (const line of formatPatdownGitHubActionsAnnotations(results)) {
+            yield* Console.error(line);
+        }
+        yield* appendSummary(formatPatdownGitHubActionsSummary({
+            failed,
+            elapsedMs: elapsedMs ?? 0,
+            results,
+        }));
+    });
+    const writers = {
+        writeAnswer: patdownStreamingHumanOutput.writeAnswer,
+        writeRulesDocument: patdownStreamingHumanOutput.writeRulesDocument,
+        writeNoFilesMatched: patdownStreamingHumanOutput.writeNoFilesMatched,
+        writeLintResult: (result, verbose) => Effect.gen(function* () {
+            yield* patdownStreamingHumanOutput.writeLintResult(result, verbose);
+            yield* Ref.update(state, (current) => ({
+                results: [...current.results, result],
+            }));
+        }),
+        writeLintOk: (elapsedMs) => Effect.gen(function* () {
+            const current = yield* Ref.get(state);
+            yield* patdownStreamingHumanOutput.writeLintOk(elapsedMs);
+            yield* publish(false, elapsedMs, current.results);
+        }),
+        writeLintFailed: (elapsedMs) => Effect.gen(function* () {
+            const current = yield* Ref.get(state);
+            yield* patdownStreamingHumanOutput.writeLintFailed(elapsedMs);
+            yield* publish(true, elapsedMs, current.results);
+        }),
+    };
+    return writers;
+}));

package/dist/patdown-github-actions-summary.d.ts

@@ -0,0 +1,19 @@
+import type { PatdownLintResult } from '#src/patdown-output';
+/** GitHub only shows about ten workflow-command annotations per step. */
+export declare const patdownGitHubActionsAnnotationLimit = 10;
+/** How far below the cutoff still counts as a near miss in the summary. */
+export declare const patdownGitHubActionsNearMissWindow = 0.2;
+export type PatdownGitHubActionsSummaryInput = {
+    readonly failed: boolean;
+    readonly elapsedMs: number;
+    readonly results: ReadonlyArray<PatdownLintResult>;
+};
+/** Rule definition text for annotations and failure details. */
+export declare function formatPatdownRuleGuidance(result: PatdownLintResult): string;
+/** Near misses are below the cutoff but close enough to show in the heatmap. */
+export declare function patdownLintResultIsNearMiss(result: PatdownLintResult): boolean;
+/** Workflow commands for the PR Files tab. Failures only; capped. */
+export declare function formatPatdownGitHubActionsAnnotations(results: ReadonlyArray<PatdownLintResult>): ReadonlyArray<string>;
+/** Markdown for $GITHUB_STEP_SUMMARY. Hottest files first. */
+export declare function formatPatdownGitHubActionsSummary(input: PatdownGitHubActionsSummaryInput): string;
+//# sourceMappingURL=patdown-github-actions-summary.d.ts.map

package/dist/patdown-github-actions-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patdown-github-actions-summary.d.ts","sourceRoot":"","sources":["../src/patdown-github-actions-summary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAG5D,yEAAyE;AACzE,eAAO,MAAM,mCAAmC,KAAK,CAAA;AAErD,2EAA2E;AAC3E,eAAO,MAAM,kCAAkC,MAAM,CAAA;AAErD,MAAM,MAAM,gCAAgC,GAAG;IAC9C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAA;CAClD,CAAA;AA+BD,gEAAgE;AAChE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAI3E;AAED,gFAAgF;AAChF,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAM9E;AAgCD,qEAAqE;AACrE,wBAAgB,qCAAqC,CACpD,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,GACvC,aAAa,CAAC,MAAM,CAAC,CA+BvB;AAsGD,8DAA8D;AAC9D,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,gCAAgC,GAAG,MAAM,CAiCjG"}

package/dist/patdown-github-actions-summary.js

@@ -0,0 +1,171 @@
+import { patdownEvidenceMinConfidence } from '#src/patdown-evidence-regions';
+import { formatPatdownProbabilityBar } from '#src/patdown-probability-bar';
+/** GitHub only shows about ten workflow-command annotations per step. */
+export const patdownGitHubActionsAnnotationLimit = 10;
+/** How far below the cutoff still counts as a near miss in the summary. */
+export const patdownGitHubActionsNearMissWindow = 0.2;
+function escapePatdownGitHubActionsData(value) {
+    return value.replace(/%/gu, '%25').replace(/\r/gu, '%0D').replace(/\n/gu, '%0A');
+}
+function escapePatdownGitHubActionsProperty(value) {
+    return escapePatdownGitHubActionsData(value).replace(/:/gu, '%3A').replace(/,/gu, '%2C');
+}
+function formatPatdownElapsedLabel(elapsedMs) {
+    if (elapsedMs >= 10_000)
+        return `${(elapsedMs / 1000).toFixed(1)}s`;
+    return `${String(elapsedMs)}ms`;
+}
+function formatPatdownProbabilityCell(result) {
+    const bar = formatPatdownProbabilityBar(result.violationProbability);
+    const score = result.violationProbability.toFixed(2);
+    if (result.violated)
+        return `${bar} **${score}** ❌`;
+    return `${bar} ${score}`;
+}
+/** Rule definition text for annotations and failure details. */
+export function formatPatdownRuleGuidance(result) {
+    const globs = result.ruleGlobs.length === 0 ? '*' : result.ruleGlobs.join(' ');
+    return [`# ${result.ruleTitle}`, `globs: ${globs}`, '', result.ruleBody].join('\n');
+}
+/** Near misses are below the cutoff but close enough to show in the heatmap. */
+export function patdownLintResultIsNearMiss(result) {
+    if (result.violated)
+        return false;
+    const floor = Math.max(0, result.yesThreshold - patdownGitHubActionsNearMissWindow);
+    return result.violationProbability >= floor;
+}
+function patdownLintResultHeat(result) {
+    if (result.violated)
+        return 2 + result.violationProbability;
+    if (patdownLintResultIsNearMiss(result))
+        return 1 + result.violationProbability;
+    return result.violationProbability;
+}
+function comparePatdownLintResultsHottestFirst(left, right) {
+    if (left.violated !== right.violated)
+        return left.violated ? -1 : 1;
+    const leftNear = patdownLintResultIsNearMiss(left);
+    const rightNear = patdownLintResultIsNearMiss(right);
+    if (leftNear !== rightNear)
+        return leftNear ? -1 : 1;
+    if (right.violationProbability !== left.violationProbability) {
+        return right.violationProbability - left.violationProbability;
+    }
+    const byFile = left.filePath.localeCompare(right.filePath);
+    if (byFile !== 0)
+        return byFile;
+    return left.ruleTitle.localeCompare(right.ruleTitle);
+}
+/** Workflow commands for the PR Files tab. Failures only; capped. */
+export function formatPatdownGitHubActionsAnnotations(results) {
+    const failures = results
+        .filter((result) => result.violated)
+        .toSorted(comparePatdownLintResultsHottestFirst)
+        .slice(0, patdownGitHubActionsAnnotationLimit);
+    return failures.map((result) => {
+        const bar = formatPatdownProbabilityBar(result.violationProbability);
+        const evidence = result.evidence !== undefined && result.evidence.confidence >= patdownEvidenceMinConfidence
+            ? result.evidence
+            : undefined;
+        const span = evidence === undefined
+            ? ''
+            : ` lines ${String(evidence.startLine)}-${String(evidence.endLine)}`;
+        const headline = `${bar} P(yes) ${String(result.violationProbability)} exceeds cutoff >${String(result.yesThreshold)}${span}`;
+        const message = `${headline}\n\n${formatPatdownRuleGuidance(result)}`;
+        const file = escapePatdownGitHubActionsProperty(result.filePath);
+        const title = escapePatdownGitHubActionsProperty(`patdown: ${result.ruleTitle}`);
+        const line = evidence === undefined
+            ? 'line=1'
+            : `line=${String(evidence.startLine)},endLine=${String(evidence.endLine)}`;
+        return `::error file=${file},${line},title=${title}::${escapePatdownGitHubActionsData(message)}`;
+    });
+}
+function collectPatdownSummaryAxes(results) {
+    const files = [...new Set(results.map((result) => result.filePath))].toSorted();
+    const rules = [...new Set(results.map((result) => result.ruleTitle))].toSorted();
+    const byFileRule = new Map();
+    for (const result of results) {
+        byFileRule.set(`${result.filePath}\0${result.ruleTitle}`, result);
+    }
+    return { files, rules, byFileRule };
+}
+function hottestPatdownFileScore(results, filePath) {
+    let hottest = 0;
+    for (const result of results) {
+        if (result.filePath !== filePath)
+            continue;
+        hottest = Math.max(hottest, patdownLintResultHeat(result));
+    }
+    return hottest;
+}
+function patdownFileRowFailed(byFileRule, filePath, rules) {
+    for (const ruleTitle of rules) {
+        const result = byFileRule.get(`${filePath}\0${ruleTitle}`);
+        if (result?.violated === true)
+            return true;
+    }
+    return false;
+}
+function formatPatdownHeatmapTable(results) {
+    const { files, rules, byFileRule } = collectPatdownSummaryAxes(results);
+    if (files.length === 0 || rules.length === 0)
+        return '_No judgments._';
+    const header = `| file | status | ${rules.map((rule) => rule.replace(/\|/gu, '\\|')).join(' | ')} |`;
+    const divider = `|---|---|${rules.map(() => '---').join('|')}|`;
+    const fileOrder = [...files].toSorted((left, right) => {
+        const leftHot = hottestPatdownFileScore(results, left);
+        const rightHot = hottestPatdownFileScore(results, right);
+        if (rightHot !== leftHot)
+            return rightHot - leftHot;
+        return left.localeCompare(right);
+    });
+    const rows = fileOrder.map((filePath) => {
+        const failed = patdownFileRowFailed(byFileRule, filePath, rules);
+        const cells = rules.map((ruleTitle) => {
+            const result = byFileRule.get(`${filePath}\0${ruleTitle}`);
+            if (result === undefined)
+                return '—';
+            return formatPatdownProbabilityCell(result);
+        });
+        return `| \`${filePath.replace(/\|/gu, '\\|')}\` | ${failed ? '❌' : '✅'} | ${cells.join(' | ')} |`;
+    });
+    return [header, divider, ...rows].join('\n');
+}
+function formatPatdownFailureDetails(results) {
+    const failures = results
+        .filter((result) => result.violated)
+        .toSorted(comparePatdownLintResultsHottestFirst);
+    if (failures.length === 0)
+        return '';
+    const lines = ['## Failures', ''];
+    for (const result of failures) {
+        const bar = formatPatdownProbabilityBar(result.violationProbability);
+        lines.push(`### \`${result.filePath}\` · ${result.ruleTitle}`, '', `${bar} estimated P(yes) **${String(result.violationProbability)}** exceeds cutoff \`>${String(result.yesThreshold)}\` · ${formatPatdownElapsedLabel(result.elapsedMs)}`, '', formatPatdownRuleGuidance(result), '');
+    }
+    return lines.join('\n');
+}
+/** Markdown for $GITHUB_STEP_SUMMARY. Hottest files first. */
+export function formatPatdownGitHubActionsSummary(input) {
+    const failedCount = input.results.filter((result) => result.violated).length;
+    const passedCount = input.results.length - failedCount;
+    const status = input.failed || failedCount > 0 ? 'failed' : 'passed';
+    const lines = [
+        `# patdown ${status}`,
+        '',
+        `${String(passedCount)} passed · ${String(failedCount)} failed · ${formatPatdownElapsedLabel(input.elapsedMs)}`,
+        '',
+        '## Heatmap',
+        '',
+        formatPatdownHeatmapTable(input.results),
+        '',
+    ];
+    const failureDetails = formatPatdownFailureDetails(input.results);
+    if (failureDetails.length > 0) {
+        lines.push(failureDetails);
+    }
+    const omitted = failedCount - patdownGitHubActionsAnnotationLimit;
+    if (omitted > 0) {
+        lines.push('', `_${String(omitted)} more failure(s) are in this summary only; GitHub caps workflow annotations per step._`, '');
+    }
+    return lines.join('\n');
+}

package/dist/patdown-glob.d.ts

@@ -0,0 +1,9 @@
+/** Directories skipped for every rule glob and every --files path. */
+export declare const patdownGlobExcludes: readonly ['**/.git/**', '**/.turbo/**', '**/coverage/**', '**/dist/**', '**/node_modules/**'];
+/** Empty rule globs mean the whole tree. */
+export declare function patdownGlobPatterns(globs: ReadonlyArray<string>): ReadonlyArray<string>;
+/** True when a cwd-relative path is under a skipped directory. */
+export declare function patdownPathIsExcluded(relativePath: string): boolean;
+/** True when a cwd-relative path matches any rule glob after the empty-glob default. */
+export declare function patdownPathMatchesRuleGlobs(relativePath: string, globs: ReadonlyArray<string>): boolean;
+//# sourceMappingURL=patdown-glob.d.ts.map

package/dist/patdown-glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patdown-glob.d.ts","sourceRoot":"","sources":["../src/patdown-glob.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,YAC/B,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,CACX,CAAA;AAEV,4CAA4C;AAC5C,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAEvF;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,wFAAwF;AACxF,wBAAgB,2BAA2B,CAC1C,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAC1B,OAAO,CAET"}

package/dist/patdown-glob.js

@@ -0,0 +1,21 @@
+import { matchesGlob } from 'node:path';
+/** Directories skipped for every rule glob and every --files path. */
+export const patdownGlobExcludes = [
+    '**/.git/**',
+    '**/.turbo/**',
+    '**/coverage/**',
+    '**/dist/**',
+    '**/node_modules/**',
+];
+/** Empty rule globs mean the whole tree. */
+export function patdownGlobPatterns(globs) {
+    return globs.length === 0 ? ['**/*'] : globs;
+}
+/** True when a cwd-relative path is under a skipped directory. */
+export function patdownPathIsExcluded(relativePath) {
+    return patdownGlobExcludes.some((pattern) => matchesGlob(relativePath, pattern));
+}
+/** True when a cwd-relative path matches any rule glob after the empty-glob default. */
+export function patdownPathMatchesRuleGlobs(relativePath, globs) {
+    return patdownGlobPatterns(globs).some((pattern) => matchesGlob(relativePath, pattern));
+}

package/dist/patdown-judge.d.ts

@@ -6,6 +6,23 @@ export declare const PatdownJudgmentSchema: Schema.Struct<{
 }>;
 /** A judge estimates the probability that the question is true of the supplied text. */
 export type PatdownJudgment = typeof PatdownJudgmentSchema.Type;
+/** A validated judgment plus how long the judge call took. */
+export type PatdownTimedJudgment = {
+    readonly judgment: PatdownJudgment;
+    readonly elapsedMs: number;
+};
+/** Region picked by a FAIL-only evidence Choice. Line numbers come from our slice map. */
+export type PatdownEvidenceChoice = {
+    readonly regionId: string;
+    readonly confidence: number;
+};
+/** Resolved line span after mapping a Choice label onto a known region. */
+export type PatdownEvidenceLocation = {
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly regionId: string;
+    readonly confidence: number;
+};
 declare const PatdownJudgeFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
     readonly _tag: "PatdownJudgeFailed";
 } & Readonly<A>;
@@ -16,6 +33,11 @@ export declare class PatdownJudgeFailed extends PatdownJudgeFailed_base<{
 }
 declare const PatdownJudge_base: Context.ServiceClass<PatdownJudge, "@patdown/cli/PatdownJudge", {
     readonly ask: (question: string, inputText: string) => Effect.Effect<PatdownJudgment, PatdownJudgeFailed>;
+    /**
+     * Optional FAIL-only locator. Returns a line span when the provider can choose among candidate
+     * regions. Missing method means file-level annotations only.
+     */
+    readonly locateEvidence?: (question: string, inputText: string, criteria: Readonly<Record<string, string>>) => Effect.Effect<PatdownEvidenceChoice | null, PatdownJudgeFailed>;
 }>;
 /** Swappable judge service. Providers supply their own transport dependencies internally. */
 export declare class PatdownJudge extends PatdownJudge_base {
@@ -25,6 +47,14 @@ export declare const patdownYesThreshold = 0.85;
 /** Applies a cutoff to a validated probability. Equality is not yes. */
 export declare function patdownJudgmentIsYes(judgment: PatdownJudgment, yesThreshold?: PatdownYesThreshold): boolean;
 /** Validates custom judge responses at the service boundary before applying policy or printing. */
-export declare function askPatdownJudge(question: string, inputText: string): Effect.Effect<PatdownJudgment, PatdownJudgeFailed, PatdownJudge>;
+export declare function askPatdownJudge(question: string, inputText: string): Effect.Effect<PatdownTimedJudgment, PatdownJudgeFailed, PatdownJudge>;
+/**
+ * Asks the optional evidence locator. Returns null when the judge has no locator, chooses noMatch,
+ * or returns an unknown region id.
+ */
+export declare function locatePatdownEvidence(question: string, inputText: string, criteria: Readonly<Record<string, string>>, regionsById: ReadonlyMap<string, {
+    readonly startLine: number;
+    readonly endLine: number;
+}>): Effect.Effect<PatdownEvidenceLocation | null, PatdownJudgeFailed, PatdownJudge>;
 export {};
 //# sourceMappingURL=patdown-judge.d.ts.map

package/dist/patdown-judge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patdown-judge.d.ts","sourceRoot":"","sources":["../src/patdown-judge.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,mBAAmB,EACxB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,OAAO,EAAQ,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEtD,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB;;EAEhC,CAAA;AAEF,wFAAwF;AACxF,MAAM,MAAM,eAAe,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA;;;;AAE/D,2EAA2E;AAC3E,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB,CAAC;CAAG;;kBAMW,CACb,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,KACb,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,kBAAkB,CAAC;;AAPzD,6FAA6F;AAC7F,qBAAa,YAAa,SAAQ,iBAQF;CAAG;AAEnC,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,OAA6B,CAAA;AAE7D,wEAAwE;AACxE,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,eAAe,EACzB,YAAY,GAAE,mBAAgD,GAC5D,OAAO,CAET;AAED,mGAAmG;AACnG,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,kBAAkB,EAAE,YAAY,CAAC,CAYlE"}
+{"version":3,"file":"patdown-judge.d.ts","sourceRoot":"","sources":["../src/patdown-judge.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,mBAAmB,EACxB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAS,OAAO,EAAQ,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE7D,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB;;EAEhC,CAAA;AAEF,wFAAwF;AACxF,MAAM,MAAM,eAAe,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA;AAE/D,8DAA8D;AAC9D,MAAM,MAAM,oBAAoB,GAAG;IAClC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED,0FAA0F;AAC1F,MAAM,MAAM,qBAAqB,GAAG;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,2EAA2E;AAC3E,MAAM,MAAM,uBAAuB,GAAG;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC3B,CAAA;;;;AAED,2EAA2E;AAC3E,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACxB,CAAC;CAAG;;kBAMW,CACb,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,KACb,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,kBAAkB,CAAC;IACvD;;;OAGG;8BACuB,CACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KACtC,MAAM,CAAC,MAAM,CAAC,qBAAqB,GAAG,IAAI,EAAE,kBAAkB,CAAC;;AAhBtE,6FAA6F;AAC7F,qBAAa,YAAa,SAAQ,iBAiBF;CAAG;AAEnC,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,OAA6B,CAAA;AAE7D,wEAAwE;AACxE,wBAAgB,oBAAoB,CACnC,QAAQ,EAAE,eAAe,EACzB,YAAY,GAAE,mBAAgD,GAC5D,OAAO,CAET;AAED,mGAAmG;AACnG,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,YAAY,CAAC,CAmBvE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC1C,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACxF,MAAM,CAAC,MAAM,CAAC,uBAAuB,GAAG,IAAI,EAAE,kBAAkB,EAAE,YAAY,CAAC,CAqBjF"}

package/dist/patdown-judge.js

@@ -1,5 +1,5 @@
 import { defaultPatdownYesThreshold, patdownJudgmentIsYes as comparePatdownYesProbability, } from '@patdown/rules';
-import { Context, Data, Effect, Schema } from 'effect';
+import { Clock, Context, Data, Effect, Schema } from 'effect';
 /** Provider-neutral estimate. This is P(yes), not confidence in whichever answer wins. */
 export const PatdownJudgmentSchema = Schema.Struct({
     yesProbability: Schema.Finite.check(Schema.isBetween({ minimum: 0, maximum: 1 })),
@@ -20,7 +20,36 @@ export function patdownJudgmentIsYes(judgment, yesThreshold = defaultPatdownYesT
 export function askPatdownJudge(question, inputText) {
     return Effect.gen(function* () {
         const judge = yield* PatdownJudge;
+        const startedAt = yield* Clock.currentTimeMillis;
         const answer = yield* judge.ask(question, inputText);
-        return yield* Schema.decodeEffect(PatdownJudgmentSchema)(answer).pipe(Effect.mapError(() => new PatdownJudgeFailed({ message: 'patdown: judge returned an invalid yes probability' })));
+        const finishedAt = yield* Clock.currentTimeMillis;
+        const judgment = yield* Schema.decodeEffect(PatdownJudgmentSchema)(answer).pipe(Effect.mapError(() => new PatdownJudgeFailed({ message: 'patdown: judge returned an invalid yes probability' })));
+        return {
+            judgment,
+            elapsedMs: Math.max(0, finishedAt - startedAt),
+        };
+    });
+}
+/**
+ * Asks the optional evidence locator. Returns null when the judge has no locator, chooses noMatch,
+ * or returns an unknown region id.
+ */
+export function locatePatdownEvidence(question, inputText, criteria, regionsById) {
+    return Effect.gen(function* () {
+        const judge = yield* PatdownJudge;
+        if (judge.locateEvidence === undefined)
+            return null;
+        const chosen = yield* judge.locateEvidence(question, inputText, criteria);
+        if (chosen === null)
+            return null;
+        const region = regionsById.get(chosen.regionId);
+        if (region === undefined)
+            return null;
+        return {
+            startLine: region.startLine,
+            endLine: region.endLine,
+            regionId: chosen.regionId,
+            confidence: chosen.confidence,
+        };
     });
 }

package/dist/patdown-lint-files.d.ts

@@ -0,0 +1,14 @@
+import { Effect, FileSystem, Option } from 'effect';
+import { PatdownJudgeFailed } from '#src/patdown-judge';
+/** Explicit path list from --files and/or --files-from, already cwd-relative and deduped. */
+export type PatdownLintFileSelection = {
+    readonly relativePaths: ReadonlyArray<string>;
+};
+/**
+ * Builds the optional lint path list. --files and --files-from may be combined. Missing
+ * --files-from paths fail. Empty selections stay empty and still succeed.
+ */
+export declare function resolvePatdownLintFileSelection(cwd: string, files: ReadonlyArray<string>, filesFrom: Option.Option<string>): Effect.Effect<PatdownLintFileSelection | null, PatdownJudgeFailed, FileSystem.FileSystem>;
+/** Intersects an explicit path list with one rule's globs. Absolute paths are for reading. */
+export declare function selectPatdownRuleFiles(cwd: string, selection: PatdownLintFileSelection | null, globs: ReadonlyArray<string>, globbedAbsolutePaths: ReadonlyArray<string>): ReadonlyArray<string>;
+//# sourceMappingURL=patdown-lint-files.d.ts.map

package/dist/patdown-lint-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patdown-lint-files.d.ts","sourceRoot":"","sources":["../src/patdown-lint-files.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAGnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAEvD,6FAA6F;AAC7F,MAAM,MAAM,wBAAwB,GAAG;IACtC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAC7C,CAAA;AAqCD;;;GAGG;AACH,wBAAgB,+BAA+B,CAC9C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,EAC5B,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,GAC9B,MAAM,CAAC,MAAM,CAAC,wBAAwB,GAAG,IAAI,EAAE,kBAAkB,EAAE,UAAU,CAAC,UAAU,CAAC,CAqC3F;AAED,8FAA8F;AAC9F,wBAAgB,sBAAsB,CACrC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,wBAAwB,GAAG,IAAI,EAC1C,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,EAC5B,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAAC,GACzC,aAAa,CAAC,MAAM,CAAC,CAcvB"}

package/dist/patdown-lint-files.js

@@ -0,0 +1,75 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { Effect, FileSystem, Option } from 'effect';
+import { patdownPathIsExcluded, patdownPathMatchesRuleGlobs } from '#src/patdown-glob';
+import { PatdownJudgeFailed } from '#src/patdown-judge';
+function normalizePatdownRelativePath(cwd, rawPath) {
+    const trimmed = rawPath.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (trimmed.startsWith('#'))
+        return null;
+    const absolutePath = isAbsolute(trimmed) ? resolve(trimmed) : resolve(cwd, trimmed);
+    const relativePath = relative(cwd, absolutePath).split(sep).join('/');
+    if (relativePath === '')
+        return null;
+    if (relativePath === '..' || relativePath.startsWith('../')) {
+        return null;
+    }
+    if (patdownPathIsExcluded(relativePath))
+        return null;
+    return relativePath;
+}
+function parsePatdownFilesFromText(cwd, text) {
+    const paths = [];
+    for (const line of text.split(/\r?\n/u)) {
+        const relativePath = normalizePatdownRelativePath(cwd, line);
+        if (relativePath === null)
+            continue;
+        paths.push(relativePath);
+    }
+    return [...new Set(paths)].toSorted();
+}
+/**
+ * Builds the optional lint path list. --files and --files-from may be combined. Missing
+ * --files-from paths fail. Empty selections stay empty and still succeed.
+ */
+export function resolvePatdownLintFileSelection(cwd, files, filesFrom) {
+    return Effect.gen(function* () {
+        if (files.length === 0 && Option.isNone(filesFrom))
+            return null;
+        const paths = [];
+        for (const file of files) {
+            const relativePath = normalizePatdownRelativePath(cwd, file);
+            if (relativePath === null)
+                continue;
+            paths.push(relativePath);
+        }
+        if (Option.isSome(filesFrom)) {
+            const fileSystem = yield* FileSystem.FileSystem;
+            const listPath = isAbsolute(filesFrom.value)
+                ? resolve(filesFrom.value)
+                : resolve(cwd, filesFrom.value);
+            const text = yield* fileSystem.readFileString(listPath).pipe(Effect.mapError(() => new PatdownJudgeFailed({
+                message: `patdown: failed to read --files-from ${relative(cwd, listPath).split(sep).join('/') || filesFrom.value}`,
+            })));
+            paths.push(...parsePatdownFilesFromText(cwd, text));
+        }
+        return {
+            relativePaths: [...new Set(paths)].toSorted(),
+        };
+    });
+}
+/** Intersects an explicit path list with one rule's globs. Absolute paths are for reading. */
+export function selectPatdownRuleFiles(cwd, selection, globs, globbedAbsolutePaths) {
+    if (selection === null)
+        return globbedAbsolutePaths;
+    const absolutePaths = [];
+    for (const relativePath of selection.relativePaths) {
+        if (!patdownPathMatchesRuleGlobs(relativePath, globs))
+            continue;
+        if (patdownPathIsExcluded(relativePath))
+            continue;
+        absolutePaths.push(resolve(cwd, relativePath));
+    }
+    return absolutePaths.toSorted();
+}

package/dist/patdown-lint.d.ts

@@ -1,7 +1,11 @@
 import { PatdownYesThresholdInvalid, type PatdownRulesDocument, type PatdownYesThreshold } from '@patdown/rules';
 import { Effect, FileSystem, Path } from 'effect';
 import { PatdownJudge, PatdownJudgeFailed } from '#src/patdown-judge';
+import { type PatdownLintFileSelection } from '#src/patdown-lint-files';
 import { PatdownOutput } from '#src/patdown-output';
 /** Lint files matched by each rule's globs. A yes judgment means a violation. */
-export declare function runPatdownLint(document: PatdownRulesDocument, verbose?: boolean, yesThreshold?: PatdownYesThreshold): Effect.Effect<boolean, PatdownJudgeFailed | PatdownYesThresholdInvalid, FileSystem.FileSystem | PatdownJudge | Path.Path | PatdownOutput>;
+export declare function runPatdownLint(document: PatdownRulesDocument, verbose?: boolean, yesThreshold?: PatdownYesThreshold, selection?: PatdownLintFileSelection | null): Effect.Effect<{
+    readonly failed: boolean;
+    readonly elapsedMs: number;
+}, PatdownJudgeFailed | PatdownYesThresholdInvalid, FileSystem.FileSystem | PatdownJudge | Path.Path | PatdownOutput>;
 //# sourceMappingURL=patdown-lint.d.ts.map

package/dist/patdown-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patdown-lint.d.ts","sourceRoot":"","sources":["../src/patdown-lint.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,0BAA0B,EAE1B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAEjD,OAAO,EACN,YAAY,EACZ,kBAAkB,EAGlB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AA0InD,iFAAiF;AACjF,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,GAAE,OAAe,EACxB,YAAY,GAAE,mBAAgD,GAC5D,MAAM,CAAC,MAAM,CACf,OAAO,EACP,kBAAkB,GAAG,0BAA0B,EAC/C,UAAU,CAAC,UAAU,GAAG,YAAY,GAAG,IAAI,CAAC,IAAI,GAAG,aAAa,CAChE,CAaA"}
+{"version":3,"file":"patdown-lint.d.ts","sourceRoot":"","sources":["../src/patdown-lint.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,0BAA0B,EAE1B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAS,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AASxD,OAAO,EACN,YAAY,EACZ,kBAAkB,EAIlB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAA0B,KAAK,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AAC/F,OAAO,EAAE,aAAa,EAAgC,MAAM,qBAAqB,CAAA;AA+LjF,iFAAiF;AACjF,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,GAAE,OAAe,EACxB,YAAY,GAAE,mBAAgD,EAC9D,SAAS,GAAE,wBAAwB,GAAG,IAAW,GAC/C,MAAM,CAAC,MAAM,CACf;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EACxD,kBAAkB,GAAG,0BAA0B,EAC/C,UAAU,CAAC,UAAU,GAAG,YAAY,GAAG,IAAI,CAAC,IAAI,GAAG,aAAa,CAChE,CAyBA"}

package/dist/patdown-lint.js

@@ -1,18 +1,11 @@
 import { defaultPatdownYesThreshold, PatdownYesThresholdInvalid, } from '@patdown/rules';
-import { Effect, FileSystem, Path } from 'effect';
-import { PatdownJudge, PatdownJudgeFailed, askPatdownJudge, patdownJudgmentIsYes, } from '#src/patdown-judge';
+import { Clock, Effect, FileSystem, Path } from 'effect';
+import { formatPatdownEvidenceChoiceState, patdownEvidenceChoiceCriteria, patdownEvidenceChoiceInstructions, splitPatdownEvidenceCandidates, } from '#src/patdown-evidence-regions';
+import { patdownGlobExcludes, patdownGlobPatterns } from '#src/patdown-glob';
+import { PatdownJudge, PatdownJudgeFailed, askPatdownJudge, locatePatdownEvidence, patdownJudgmentIsYes, } from '#src/patdown-judge';
+import { selectPatdownRuleFiles } from '#src/patdown-lint-files';
 import { PatdownOutput } from '#src/patdown-output';
 import { decodePatdownRuleYesThreshold } from '#src/patdown-yes-threshold-config';
-const patdownGlobExcludes = [
-    '**/.git/**',
-    '**/.turbo/**',
-    '**/coverage/**',
-    '**/dist/**',
-    '**/node_modules/**',
-];
-function patdownGlobPatterns(globs) {
-    return globs.length === 0 ? ['**/*'] : globs;
-}
 function patdownViolationInstructions(rule) {
     return [
         'Does this file violate the following patdown rule? Answer yes only if there is a clear violation.',
@@ -51,39 +44,88 @@ function lintPatdownRuleFile(rule, filePath, options) {
         const contents = yield* fileSystem.readFileString(filePath).pipe(Effect.mapError(() => new PatdownJudgeFailed({
             message: `patdown: failed to read ${relativePath}`,
         })));
-        const answer = yield* askPatdownJudge(patdownViolationInstructions(rule), patdownFileState(relativePath, contents));
-        const failed = patdownJudgmentIsYes(answer, options.yesThreshold);
-        yield* output.writeLintResult({
+        const timed = yield* askPatdownJudge(patdownViolationInstructions(rule), patdownFileState(relativePath, contents));
+        const failed = patdownJudgmentIsYes(timed.judgment, options.yesThreshold);
+        let evidence;
+        let elapsedMs = timed.elapsedMs;
+        if (failed) {
+            const evidenceStartedAt = yield* Clock.currentTimeMillis;
+            const candidates = splitPatdownEvidenceCandidates(contents);
+            const candidatesById = new Map(candidates.map((candidate) => [
+                candidate.id,
+                { startLine: candidate.startLine, endLine: candidate.endLine },
+            ]));
+            const located = yield* locatePatdownEvidence(patdownEvidenceChoiceInstructions(), formatPatdownEvidenceChoiceState({
+                relativePath,
+                ruleTitle: rule.patdownRuleTitle,
+                ruleBody: rule.patdownRuleBody,
+                violationProbability: timed.judgment.yesProbability,
+                contents,
+                candidates,
+            }), patdownEvidenceChoiceCriteria(candidates), candidatesById).pipe(Effect.catchTag('PatdownJudgeFailed', () => Effect.succeed(null)));
+            const evidenceFinishedAt = yield* Clock.currentTimeMillis;
+            elapsedMs += Math.max(0, evidenceFinishedAt - evidenceStartedAt);
+            if (located !== null) {
+                evidence = {
+                    startLine: located.startLine,
+                    endLine: located.endLine,
+                    confidence: located.confidence,
+                };
+            }
+        }
+        const lintResult = {
             violated: failed,
             ruleTitle: rule.patdownRuleTitle,
+            ruleBody: rule.patdownRuleBody,
+            ruleGlobs: rule.patdownRuleGlobs,
             filePath: relativePath,
-            violationProbability: answer.yesProbability,
+            violationProbability: timed.judgment.yesProbability,
             yesThreshold: options.yesThreshold,
-        }, options.verbose);
+            elapsedMs,
+        };
+        yield* output.writeLintResult(evidence === undefined ? lintResult : { ...lintResult, evidence }, options.verbose);
         return failed;
     });
 }
-function lintPatdownRule(rule, cwd, verbose, defaultYesThreshold) {
+function lintPatdownRule(rule, options) {
     return Effect.gen(function* () {
         const output = yield* PatdownOutput;
-        const files = yield* globPatdownRuleFiles(cwd, rule.patdownRuleGlobs);
+        const files = selectPatdownRuleFiles(options.cwd, options.selection, rule.patdownRuleGlobs, options.selection === null
+            ? yield* globPatdownRuleFiles(options.cwd, rule.patdownRuleGlobs)
+            : []);
         const yesThreshold = rule.patdownRuleYesThreshold === undefined
-            ? defaultYesThreshold
+            ? options.defaultYesThreshold
             : yield* decodePatdownRuleYesThreshold(rule.patdownRuleYesThreshold, rule.patdownRuleTitle);
         if (files.length === 0) {
-            yield* output.writeNoFilesMatched(rule.patdownRuleTitle);
+            if (options.selection === null) {
+                yield* output.writeNoFilesMatched(rule.patdownRuleTitle);
+            }
             return false;
         }
-        const failures = yield* Effect.forEach(files, (filePath) => lintPatdownRuleFile(rule, filePath, { cwd, verbose, yesThreshold }), { concurrency: 1 });
+        const failures = yield* Effect.forEach(files, (filePath) => lintPatdownRuleFile(rule, filePath, {
+            cwd: options.cwd,
+            verbose: options.verbose,
+            yesThreshold,
+        }), { concurrency: 1 });
         return failures.some((failed) => failed);
     });
 }
 /** Lint files matched by each rule's globs. A yes judgment means a violation. */
-export function runPatdownLint(document, verbose = false, yesThreshold = defaultPatdownYesThreshold) {
+export function runPatdownLint(document, verbose = false, yesThreshold = defaultPatdownYesThreshold, selection = null) {
     return Effect.gen(function* () {
         const path = yield* Path.Path;
         const cwd = path.resolve('.');
-        const failures = yield* Effect.forEach(document.patdownRules, (rule) => lintPatdownRule(rule, cwd, verbose, yesThreshold), { concurrency: 1 });
-        return failures.some((failed) => failed);
+        const startedAt = yield* Clock.currentTimeMillis;
+        const failures = yield* Effect.forEach(document.patdownRules, (rule) => lintPatdownRule(rule, {
+            cwd,
+            verbose,
+            defaultYesThreshold: yesThreshold,
+            selection,
+        }), { concurrency: 1 });
+        const finishedAt = yield* Clock.currentTimeMillis;
+        return {
+            failed: failures.some((failed) => failed),
+            elapsedMs: Math.max(0, finishedAt - startedAt),
+        };
     });
 }