repopo 0.10.0 → 0.13.0

package/esm/policyExecution.js

@@ -0,0 +1,224 @@
+import { types } from "node:util";
+import { ExecutionContractError } from "./executionContractError.js";
+import { fileCache } from "./fileCache.js";
+import { runWithPerf } from "./perf.js";
+import { settlePolicyPromise } from "./settlePolicyPromise.js";
+const windowsAbsolutePath = /^[A-Za-z]:/;
+function* execute(handler) {
+    const execution = handler();
+    if (execution instanceof Promise) {
+        return yield* settlePolicyPromise(execution);
+    }
+    if (typeof execution === "object" &&
+        execution !== null &&
+        Symbol.iterator in execution &&
+        !Array.isArray(execution)) {
+        return yield* execution;
+    }
+    throw new ExecutionContractError("Handlers and resolvers must be async functions or Effection generators.");
+}
+function validPath(path) {
+    return (typeof path === "string" &&
+        path.length > 0 &&
+        !path.includes("\\") &&
+        !path.includes("\0") &&
+        !path.startsWith("/") &&
+        !windowsAbsolutePath.test(path) &&
+        path
+            .split("/")
+            .every((part) => part !== "" && part !== "." && part !== ".."));
+}
+function validateResult(result, repository, fix) {
+    const invalid = () => new ExecutionContractError("Policy handlers and resolvers must return readonly PolicyFinding[] with message, optional manualFix, fixStatus and repository-only files; legacy results are not supported.");
+    if (!Array.isArray(result)) {
+        throw invalid();
+    }
+    for (const finding of result) {
+        if (typeof finding !== "object" ||
+            finding === null ||
+            Array.isArray(finding) ||
+            Reflect.ownKeys(finding).some((key) => typeof key !== "string" ||
+                !["message", "manualFix", "fixStatus", "files"].includes(key)) ||
+            !("message" in finding) ||
+            typeof finding.message !== "string" ||
+            finding.message.length === 0 ||
+            ("manualFix" in finding &&
+                finding.manualFix !== undefined &&
+                typeof finding.manualFix !== "string") ||
+            ("fixStatus" in finding &&
+                finding.fixStatus !== undefined &&
+                !["available", "fixed", "failed"].includes(finding.fixStatus)) ||
+            (!fix &&
+                (finding.fixStatus === "fixed" || finding.fixStatus === "failed")) ||
+            ("files" in finding &&
+                !(repository &&
+                    (finding.files === undefined ||
+                        (Array.isArray(finding.files) && finding.files.every(validPath)))))) {
+            throw invalid();
+        }
+    }
+}
+function mergeFindings(checked, resolved) {
+    // Omission is not resolution; messages identify independent findings.
+    const merged = [...checked];
+    const used = new Set();
+    for (const finding of resolved) {
+        const index = checked.findIndex((previous, candidateIndex) => !used.has(candidateIndex) && previous.message === finding.message);
+        if (index === -1) {
+            merged.push(finding);
+        }
+        else if (merged[index]?.fixStatus !== "fixed") {
+            merged[index] = { ...merged[index], ...finding };
+            used.add(index);
+        }
+    }
+    return merged;
+}
+function nativeErrorMessage(cause) {
+    let current = cause;
+    while (current && !types.isProxy(current)) {
+        const descriptor = Object.getOwnPropertyDescriptor(current, "message");
+        if (descriptor) {
+            return "value" in descriptor && typeof descriptor.value === "string"
+                ? descriptor.value
+                : undefined;
+        }
+        current = Object.getPrototypeOf(current);
+    }
+    return undefined;
+}
+/** Describe thrown values without allowing hostile coercion to discard a run. */
+export function executionMessage(cause) {
+    try {
+        if (cause === null ||
+            (typeof cause !== "object" && typeof cause !== "function")) {
+            return String(cause);
+        }
+        const message = !types.isProxy(cause) && types.isNativeError(cause)
+            ? nativeErrorMessage(cause)
+            : undefined;
+        return message ?? "Policy threw a non-Error or uninspectable value.";
+    }
+    catch {
+        return "Policy threw a value that cannot be inspected.";
+    }
+}
+function errorKind(cause) {
+    try {
+        if (cause === null ||
+            (typeof cause !== "object" && typeof cause !== "function")) {
+            return "exception";
+        }
+        let current = cause;
+        while (current && !types.isProxy(current)) {
+            if (current === ExecutionContractError.prototype) {
+                return "contract";
+            }
+            current = Object.getPrototypeOf(current);
+        }
+        return "exception";
+    }
+    catch {
+        return "exception";
+    }
+}
+/** Internal single-policy execution; engines own matching and scheduling. */
+export class PolicyExecutor {
+    root;
+    fix;
+    constructor(root, fix) {
+        this.root = root;
+        this.fix = fix;
+    }
+    *repository(policy, eligible, output) {
+        try {
+            const findings = yield* runWithPerf(policy.instanceId, "handle", output.perfStats, () => execute(() => policy.handler({
+                files: eligible,
+                root: this.root,
+                resolve: this.fix,
+                config: policy.config,
+            })));
+            validateResult(findings, true, this.fix);
+            for (const finding of findings) {
+                output.findings.push({
+                    ...finding,
+                    scope: "repository",
+                    policy: policy.name,
+                    policyId: policy.instanceId,
+                });
+            }
+        }
+        catch (cause) {
+            output.errors.push({
+                scope: "repository",
+                files: eligible,
+                policy: policy.name,
+                policyId: policy.instanceId,
+                phase: "handle",
+                kind: errorKind(cause),
+                message: executionMessage(cause),
+                cause,
+            });
+            return this.fix;
+        }
+        return false;
+    }
+    *file(file, policy, output, cache) {
+        let stopped = false;
+        let phase = "handle";
+        let checked = [];
+        try {
+            const args = {
+                file,
+                root: this.root,
+                resolve: this.fix,
+                config: policy.config,
+                [fileCache]: cache,
+            };
+            checked = yield* runWithPerf(policy.instanceId, "handle", output.perfStats, () => execute(() => policy.handler(args)));
+            validateResult(checked, false, this.fix);
+            if (this.fix &&
+                checked.length > 0 &&
+                policy.resolver &&
+                !checked.some((finding) => finding.fixStatus === "fixed" || finding.fixStatus === "failed")) {
+                phase = "resolve";
+                const resolver = policy.resolver;
+                const resolved = yield* runWithPerf(policy.instanceId, "resolve", output.perfStats, () => execute(() => resolver({
+                    file,
+                    root: args.root,
+                    config: args.config,
+                    findings: checked.map((finding) => ({ ...finding })),
+                })));
+                validateResult(resolved, false, true);
+                checked = mergeFindings(checked, resolved);
+            }
+        }
+        catch (cause) {
+            output.errors.push({
+                scope: "file",
+                file,
+                policy: policy.name,
+                policyId: policy.instanceId,
+                phase,
+                kind: errorKind(cause),
+                message: executionMessage(cause),
+                cause,
+            });
+            stopped = this.fix;
+            if (phase === "handle") {
+                checked = [];
+            }
+        }
+        for (const { files: _files, ...finding } of checked) {
+            output.findings.push({
+                ...finding,
+                scope: "file",
+                file,
+                policy: policy.name,
+                policyId: policy.instanceId,
+            });
+        }
+        return stopped;
+    }
+}
+//# sourceMappingURL=policyExecution.js.map

package/esm/policyExecution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policyExecution.js","sourceRoot":"","sources":["../src/policyExecution.ts"],"names":[],"mappings":"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","sourcesContent":["import { types } from \"node:util\";\nimport type { Operation } from \"effection\";\nimport { ExecutionContractError } from \"./executionContractError.js\";\nimport { fileCache, type ParsedFileCache } from \"./fileCache.js\";\nimport { runWithPerf } from \"./perf.js\";\nimport type { IdentifiedPolicy, PolicyResult } from \"./policy.js\";\nimport type { PolicyRunResults } from \"./runner.js\";\nimport { settlePolicyPromise } from \"./settlePolicyPromise.js\";\n\nconst windowsAbsolutePath = /^[A-Za-z]:/;\n\nfunction* execute<T>(handler: () => Promise<T> | Operation<T>): Operation<T> {\n\tconst execution = handler();\n\tif (execution instanceof Promise) {\n\t\treturn yield* settlePolicyPromise(execution);\n\t}\n\tif (\n\t\ttypeof execution === \"object\" &&\n\t\texecution !== null &&\n\t\tSymbol.iterator in execution &&\n\t\t!Array.isArray(execution)\n\t) {\n\t\treturn yield* execution;\n\t}\n\tthrow new ExecutionContractError(\n\t\t\"Handlers and resolvers must be async functions or Effection generators.\",\n\t);\n}\n\nfunction validPath(path: unknown): path is string {\n\treturn (\n\t\ttypeof path === \"string\" &&\n\t\tpath.length > 0 &&\n\t\t!path.includes(\"\\\\\") &&\n\t\t!path.includes(\"\\0\") &&\n\t\t!path.startsWith(\"/\") &&\n\t\t!windowsAbsolutePath.test(path) &&\n\t\tpath\n\t\t\t.split(\"/\")\n\t\t\t.every((part) => part !== \"\" && part !== \".\" && part !== \"..\")\n\t);\n}\n\nfunction validateResult(\n\tresult: unknown,\n\trepository: boolean,\n\tfix: boolean,\n): asserts result is PolicyResult {\n\tconst invalid = () =>\n\t\tnew ExecutionContractError(\n\t\t\t\"Policy handlers and resolvers must return readonly PolicyFinding[] with message, optional manualFix, fixStatus and repository-only files; legacy results are not supported.\",\n\t\t);\n\tif (!Array.isArray(result)) {\n\t\tthrow invalid();\n\t}\n\tfor (const finding of result) {\n\t\tif (\n\t\t\ttypeof finding !== \"object\" ||\n\t\t\tfinding === null ||\n\t\t\tArray.isArray(finding) ||\n\t\t\tReflect.ownKeys(finding).some(\n\t\t\t\t(key) =>\n\t\t\t\t\ttypeof key !== \"string\" ||\n\t\t\t\t\t![\"message\", \"manualFix\", \"fixStatus\", \"files\"].includes(key),\n\t\t\t) ||\n\t\t\t!(\"message\" in finding) ||\n\t\t\ttypeof finding.message !== \"string\" ||\n\t\t\tfinding.message.length === 0 ||\n\t\t\t(\"manualFix\" in finding &&\n\t\t\t\tfinding.manualFix !== undefined &&\n\t\t\t\ttypeof finding.manualFix !== \"string\") ||\n\t\t\t(\"fixStatus\" in finding &&\n\t\t\t\tfinding.fixStatus !== undefined &&\n\t\t\t\t![\"available\", \"fixed\", \"failed\"].includes(finding.fixStatus)) ||\n\t\t\t(!fix &&\n\t\t\t\t(finding.fixStatus === \"fixed\" || finding.fixStatus === \"failed\")) ||\n\t\t\t(\"files\" in finding &&\n\t\t\t\t!(\n\t\t\t\t\trepository &&\n\t\t\t\t\t(finding.files === undefined ||\n\t\t\t\t\t\t(Array.isArray(finding.files) && finding.files.every(validPath)))\n\t\t\t\t))\n\t\t) {\n\t\t\tthrow invalid();\n\t\t}\n\t}\n}\n\nfunction mergeFindings(\n\tchecked: PolicyResult,\n\tresolved: PolicyResult,\n): PolicyResult {\n\t// Omission is not resolution; messages identify independent findings.\n\tconst merged = [...checked];\n\tconst used = new Set<number>();\n\tfor (const finding of resolved) {\n\t\tconst index = checked.findIndex(\n\t\t\t(previous, candidateIndex) =>\n\t\t\t\t!used.has(candidateIndex) && previous.message === finding.message,\n\t\t);\n\t\tif (index === -1) {\n\t\t\tmerged.push(finding);\n\t\t} else if (merged[index]?.fixStatus !== \"fixed\") {\n\t\t\tmerged[index] = { ...merged[index], ...finding };\n\t\t\tused.add(index);\n\t\t}\n\t}\n\treturn merged;\n}\n\nfunction nativeErrorMessage(cause: object): string | undefined {\n\tlet current: object | null = cause;\n\twhile (current && !types.isProxy(current)) {\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(current, \"message\");\n\t\tif (descriptor) {\n\t\t\treturn \"value\" in descriptor && typeof descriptor.value === \"string\"\n\t\t\t\t? descriptor.value\n\t\t\t\t: undefined;\n\t\t}\n\t\tcurrent = Object.getPrototypeOf(current);\n\t}\n\treturn undefined;\n}\n\n/** Describe thrown values without allowing hostile coercion to discard a run. */\nexport function executionMessage(cause: unknown): string {\n\ttry {\n\t\tif (\n\t\t\tcause === null ||\n\t\t\t(typeof cause !== \"object\" && typeof cause !== \"function\")\n\t\t) {\n\t\t\treturn String(cause);\n\t\t}\n\t\tconst message =\n\t\t\t!types.isProxy(cause) && types.isNativeError(cause)\n\t\t\t\t? nativeErrorMessage(cause)\n\t\t\t\t: undefined;\n\t\treturn message ?? \"Policy threw a non-Error or uninspectable value.\";\n\t} catch {\n\t\treturn \"Policy threw a value that cannot be inspected.\";\n\t}\n}\n\nfunction errorKind(cause: unknown): \"contract\" | \"exception\" {\n\ttry {\n\t\tif (\n\t\t\tcause === null ||\n\t\t\t(typeof cause !== \"object\" && typeof cause !== \"function\")\n\t\t) {\n\t\t\treturn \"exception\";\n\t\t}\n\t\tlet current: object | null = cause;\n\t\twhile (current && !types.isProxy(current)) {\n\t\t\tif (current === ExecutionContractError.prototype) {\n\t\t\t\treturn \"contract\";\n\t\t\t}\n\t\t\tcurrent = Object.getPrototypeOf(current);\n\t\t}\n\t\treturn \"exception\";\n\t} catch {\n\t\treturn \"exception\";\n\t}\n}\n\n/** Internal single-policy execution; engines own matching and scheduling. */\nexport class PolicyExecutor {\n\tpublic constructor(\n\t\tprivate readonly root: string,\n\t\tprivate readonly fix: boolean,\n\t) {}\n\n\tpublic *repository(\n\t\tpolicy: Extract<IdentifiedPolicy, { scope: \"repository\" }>,\n\t\teligible: readonly string[],\n\t\toutput: PolicyRunResults,\n\t): Operation<boolean> {\n\t\ttry {\n\t\t\tconst findings = yield* runWithPerf(\n\t\t\t\tpolicy.instanceId,\n\t\t\t\t\"handle\",\n\t\t\t\toutput.perfStats,\n\t\t\t\t() =>\n\t\t\t\t\texecute(() =>\n\t\t\t\t\t\tpolicy.handler({\n\t\t\t\t\t\t\tfiles: eligible,\n\t\t\t\t\t\t\troot: this.root,\n\t\t\t\t\t\t\tresolve: this.fix,\n\t\t\t\t\t\t\tconfig: policy.config,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t);\n\t\t\tvalidateResult(findings, true, this.fix);\n\t\t\tfor (const finding of findings) {\n\t\t\t\toutput.findings.push({\n\t\t\t\t\t...finding,\n\t\t\t\t\tscope: \"repository\",\n\t\t\t\t\tpolicy: policy.name,\n\t\t\t\t\tpolicyId: policy.instanceId,\n\t\t\t\t});\n\t\t\t}\n\t\t} catch (cause: unknown) {\n\t\t\toutput.errors.push({\n\t\t\t\tscope: \"repository\",\n\t\t\t\tfiles: eligible,\n\t\t\t\tpolicy: policy.name,\n\t\t\t\tpolicyId: policy.instanceId,\n\t\t\t\tphase: \"handle\",\n\t\t\t\tkind: errorKind(cause),\n\t\t\t\tmessage: executionMessage(cause),\n\t\t\t\tcause,\n\t\t\t});\n\t\t\treturn this.fix;\n\t\t}\n\t\treturn false;\n\t}\n\n\tpublic *file(\n\t\tfile: string,\n\t\tpolicy: Exclude<IdentifiedPolicy, { scope: \"repository\" }>,\n\t\toutput: PolicyRunResults,\n\t\tcache: ParsedFileCache | undefined,\n\t): Operation<boolean> {\n\t\tlet stopped = false;\n\t\tlet phase: \"handle\" | \"resolve\" = \"handle\";\n\t\tlet checked: PolicyResult = [];\n\t\ttry {\n\t\t\tconst args = {\n\t\t\t\tfile,\n\t\t\t\troot: this.root,\n\t\t\t\tresolve: this.fix,\n\t\t\t\tconfig: policy.config,\n\t\t\t\t[fileCache]: cache,\n\t\t\t};\n\t\t\tchecked = yield* runWithPerf(\n\t\t\t\tpolicy.instanceId,\n\t\t\t\t\"handle\",\n\t\t\t\toutput.perfStats,\n\t\t\t\t() => execute(() => policy.handler(args)),\n\t\t\t);\n\t\t\tvalidateResult(checked, false, this.fix);\n\t\t\tif (\n\t\t\t\tthis.fix &&\n\t\t\t\tchecked.length > 0 &&\n\t\t\t\tpolicy.resolver &&\n\t\t\t\t!checked.some(\n\t\t\t\t\t(finding) =>\n\t\t\t\t\t\tfinding.fixStatus === \"fixed\" || finding.fixStatus === \"failed\",\n\t\t\t\t)\n\t\t\t) {\n\t\t\t\tphase = \"resolve\";\n\t\t\t\tconst resolver = policy.resolver;\n\t\t\t\tconst resolved = yield* runWithPerf(\n\t\t\t\t\tpolicy.instanceId,\n\t\t\t\t\t\"resolve\",\n\t\t\t\t\toutput.perfStats,\n\t\t\t\t\t() =>\n\t\t\t\t\t\texecute(() =>\n\t\t\t\t\t\t\tresolver({\n\t\t\t\t\t\t\t\tfile,\n\t\t\t\t\t\t\t\troot: args.root,\n\t\t\t\t\t\t\t\tconfig: args.config,\n\t\t\t\t\t\t\t\tfindings: checked.map((finding) => ({ ...finding })),\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tvalidateResult(resolved, false, true);\n\t\t\t\tchecked = mergeFindings(checked, resolved);\n\t\t\t}\n\t\t} catch (cause: unknown) {\n\t\t\toutput.errors.push({\n\t\t\t\tscope: \"file\",\n\t\t\t\tfile,\n\t\t\t\tpolicy: policy.name,\n\t\t\t\tpolicyId: policy.instanceId,\n\t\t\t\tphase,\n\t\t\t\tkind: errorKind(cause),\n\t\t\t\tmessage: executionMessage(cause),\n\t\t\t\tcause,\n\t\t\t});\n\t\t\tstopped = this.fix;\n\t\t\tif (phase === \"handle\") {\n\t\t\t\tchecked = [];\n\t\t\t}\n\t\t}\n\t\tfor (const { files: _files, ...finding } of checked) {\n\t\t\toutput.findings.push({\n\t\t\t\t...finding,\n\t\t\t\tscope: \"file\",\n\t\t\t\tfile,\n\t\t\t\tpolicy: policy.name,\n\t\t\t\tpolicyId: policy.instanceId,\n\t\t\t});\n\t\t}\n\t\treturn stopped;\n\t}\n}\n"]}

package/esm/repositoryFiles.d.ts

@@ -0,0 +1,4 @@
+import type { SimpleGit } from "simple-git";
+/** Git's cached inventory includes unstaged deletions; those are not live files. */
+export declare function readRepositoryFiles(git: SimpleGit): Promise<string[]>;
+//# sourceMappingURL=repositoryFiles.d.ts.map

package/esm/repositoryFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repositoryFiles.d.ts","sourceRoot":"","sources":["../src/repositoryFiles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,oFAAoF;AACpF,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAQ3E"}

package/esm/repositoryFiles.js

@@ -0,0 +1,8 @@
+import { parseFilePaths } from "./filePaths.js";
+/** Git's cached inventory includes unstaged deletions; those are not live files. */
+export async function readRepositoryFiles(git) {
+    const files = parseFilePaths(await git.raw("ls-files", "-co", "-z", "--exclude-standard", "--full-name"));
+    const deleted = new Set(parseFilePaths(await git.raw("ls-files", "--deleted", "-z", "--full-name")));
+    return files.filter((file) => !deleted.has(file));
+}
+//# sourceMappingURL=repositoryFiles.js.map

package/esm/repositoryFiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repositoryFiles.js","sourceRoot":"","sources":["../src/repositoryFiles.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAc;IACvD,MAAM,KAAK,GAAG,cAAc,CAC3B,MAAM,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,aAAa,CAAC,CAC3E,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,GAAG,CACtB,cAAc,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAC3E,CAAC;IACF,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACnD,CAAC","sourcesContent":["import type { SimpleGit } from \"simple-git\";\nimport { parseFilePaths } from \"./filePaths.js\";\n\n/** Git's cached inventory includes unstaged deletions; those are not live files. */\nexport async function readRepositoryFiles(git: SimpleGit): Promise<string[]> {\n\tconst files = parseFilePaths(\n\t\tawait git.raw(\"ls-files\", \"-co\", \"-z\", \"--exclude-standard\", \"--full-name\"),\n\t);\n\tconst deleted = new Set(\n\t\tparseFilePaths(await git.raw(\"ls-files\", \"--deleted\", \"-z\", \"--full-name\")),\n\t);\n\treturn files.filter((file) => !deleted.has(file));\n}\n"]}

package/esm/runner.d.ts

@@ -0,0 +1,85 @@
+import { type Operation } from "effection";
+import { type PolicyHandlerPerfStats } from "./perf.js";
+import type { ConfiguredPolicy, PolicyFinding } from "./policy.js";
+/** A finding with runner-owned identity and scope-safe location. @public */
+export type PolicyRunFinding = (Omit<PolicyFinding, "files"> & {
+    scope: "file";
+    file: string;
+    files?: never;
+    policy: string;
+    policyId: string;
+}) | (PolicyFinding & {
+    scope: "repository";
+    file?: never;
+    policy: string;
+    policyId: string;
+});
+/** An execution failure, separate from ordinary policy findings. @public */
+export type PolicyExecutionError = {
+    policy: string;
+    policyId: string;
+    phase: "handle" | "resolve";
+    kind: "contract" | "exception";
+    message: string;
+    cause: unknown;
+} & ({
+    scope: "file";
+    file: string;
+    files?: never;
+} | {
+    scope: "repository";
+    files: readonly string[];
+    file?: never;
+});
+/** A unit that was not executed. @public */
+export type PolicySkippedWork = {
+    policy: string;
+    policyId: string;
+    reason: "excluded" | "file-fix-error" | "repository-fix-error";
+} & ({
+    scope: "file";
+    file: string;
+} | {
+    scope: "repository";
+    file?: never;
+});
+/** Findings, failures, skipped units, and file/per-instance timing statistics. @public */
+export interface PolicyRunResults {
+    findings: PolicyRunFinding[];
+    errors: PolicyExecutionError[];
+    skipped: PolicySkippedWork[];
+    perfStats: PolicyHandlerPerfStats;
+}
+/** Full repository inventory, never inferred from a file selection. @public */
+export type RepositoryInventory = readonly string[] | (() => Promise<readonly string[]>);
+/** Shared Promise and Effection runner options. @public */
+export interface PolicyRunnerOptions {
+    policies: readonly ConfiguredPolicy[];
+    root: string;
+    inventory?: RepositoryInventory | undefined;
+    /** Selection limits only file policies. Defaults to inventory when supplied. */
+    files?: readonly string[] | undefined;
+    exclude?: readonly (string | RegExp)[] | undefined;
+    fix?: boolean | undefined;
+    concurrency?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+/** Effection runner; cancellation unwinds active generator handlers and resolvers. @public */
+export declare class PolicyRunner {
+    private readonly options;
+    private readonly policies;
+    private readonly exclusions;
+    private readonly policyExclusions;
+    private readonly concurrency;
+    constructor(options: PolicyRunnerOptions);
+    run(): Operation<PolicyRunResults>;
+    private runInternal;
+    private runReadOnlyFiles;
+    private runRepositories;
+    private loadInventory;
+    private excluded;
+    private runFile;
+}
+/** Promise entry point sharing the Effection runner's contracts and cancellation. @public */
+export declare function runPolicies(options: PolicyRunnerOptions): Promise<PolicyRunResults>;
+//# sourceMappingURL=runner.d.ts.map

package/esm/runner.d.ts.map

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

package/esm/runner.js

@@ -0,0 +1,189 @@
+import { all, call, run, spawn } from "effection";
+import { DEFAULT_CONCURRENCY, validateConcurrency } from "./concurrency.js";
+import { createExcludedPolicyFileMap, exclusionRegex, } from "./context.js";
+import { ParsedFileCache } from "./fileCache.js";
+import { identifyPolicyInstances } from "./makePolicy.js";
+import { newPerfStats } from "./perf.js";
+import { PolicyExecutor } from "./policyExecution.js";
+function matches(regex, file) {
+    const index = regex.lastIndex;
+    try {
+        regex.lastIndex = 0;
+        return regex.test(file);
+    }
+    finally {
+        regex.lastIndex = index;
+    }
+}
+/** Effection runner; cancellation unwinds active generator handlers and resolvers. @public */
+export class PolicyRunner {
+    options;
+    policies;
+    exclusions;
+    policyExclusions;
+    concurrency;
+    constructor(options) {
+        this.options = options;
+        this.policies = identifyPolicyInstances(options.policies.map((policy) => ({
+            ...policy,
+            config: policy.config === undefined ? policy.defaultConfig : policy.config,
+        })));
+        this.exclusions = (options.exclude ?? []).map(exclusionRegex);
+        this.policyExclusions = createExcludedPolicyFileMap(this.policies);
+        this.concurrency = validateConcurrency(options.concurrency ?? DEFAULT_CONCURRENCY);
+        if (this.policies.some((policy) => policy.scope === "repository") &&
+            options.inventory === undefined) {
+            throw new TypeError("Repository policies require an explicit inventory array or loader; files is only a selection.");
+        }
+        for (const policy of this.policies) {
+            if (policy.scope === "repository" && policy.resolver !== undefined) {
+                throw new TypeError("Repository policies support inline fixes only; remove resolver.");
+            }
+            if (policy.requiresConfig &&
+                policy.config === undefined &&
+                policy.defaultConfig === undefined) {
+                throw new TypeError(`Policy '${policy.name}' requires config.`);
+            }
+        }
+    }
+    *run() {
+        const signal = this.options.signal;
+        if (signal?.aborted) {
+            throw signal.reason;
+        }
+        const task = yield* spawn(() => this.runInternal());
+        // halt() is lazy; consuming it initiates teardown. The task retains any teardown error.
+        const abort = () => {
+            task.halt().catch(() => undefined);
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        try {
+            if (signal?.aborted) {
+                abort();
+            }
+            return yield* task;
+        }
+        finally {
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    *runInternal() {
+        const result = {
+            findings: [],
+            errors: [],
+            skipped: [],
+            perfStats: newPerfStats(),
+        };
+        const fix = this.options.fix ?? false;
+        const cache = fix ? undefined : new ParsedFileCache();
+        let inventory;
+        if (this.options.files === undefined) {
+            inventory = yield* this.loadInventory();
+        }
+        const files = this.options.files ?? inventory ?? [];
+        let fileFixError = false;
+        try {
+            if (fix) {
+                for (const file of files) {
+                    if (yield* this.runFile(file, result, cache)) {
+                        fileFixError = true;
+                    }
+                }
+            }
+            else {
+                yield* this.runReadOnlyFiles(files, result, cache);
+            }
+        }
+        finally {
+            cache?.clear();
+        }
+        yield* this.runRepositories(result, inventory, fileFixError);
+        return result;
+    }
+    *runReadOnlyFiles(files, result, cache) {
+        const entries = files.entries();
+        const outputs = [];
+        const runner = this;
+        yield* all(Array.from({ length: Math.min(this.concurrency, files.length) }, function* () {
+            for (let entry = entries.next(); !entry.done; entry = entries.next()) {
+                const [index, file] = entry.value;
+                const local = {
+                    findings: [],
+                    errors: [],
+                    skipped: [],
+                    perfStats: result.perfStats,
+                };
+                yield* runner.runFile(file, local, cache);
+                outputs[index] = local;
+            }
+        }));
+        for (const output of outputs) {
+            result.findings.push(...output.findings);
+            result.errors.push(...output.errors);
+            result.skipped.push(...output.skipped);
+        }
+    }
+    *runRepositories(result, initialInventory, fileFixError) {
+        let inventory = initialInventory;
+        const fix = this.options.fix ?? false;
+        let repositoryFixError = false;
+        for (const policy of this.policies) {
+            if (policy.scope !== "repository") {
+                continue;
+            }
+            if (fileFixError || repositoryFixError) {
+                result.skipped.push({
+                    scope: "repository",
+                    policy: policy.name,
+                    policyId: policy.instanceId,
+                    reason: fileFixError ? "file-fix-error" : "repository-fix-error",
+                });
+                continue;
+            }
+            if (inventory === undefined || fix) {
+                inventory = yield* this.loadInventory();
+            }
+            const eligible = (inventory ?? []).filter((file) => !this.excluded(file, policy));
+            repositoryFixError = yield* new PolicyExecutor(this.options.root, fix).repository(policy, eligible, result);
+        }
+    }
+    *loadInventory() {
+        const inventory = this.options.inventory;
+        return typeof inventory === "function" ? yield* call(inventory) : inventory;
+    }
+    excluded(file, policy) {
+        return (this.exclusions.some((regex) => matches(regex, file)) ||
+            (this.policyExclusions.get(policy.instanceId) ?? []).some((regex) => matches(regex, file)));
+    }
+    *runFile(file, output, cache) {
+        output.perfStats.count++;
+        const globallyExcluded = this.exclusions.some((regex) => matches(regex, file));
+        if (!globallyExcluded) {
+            output.perfStats.processed++;
+        }
+        let stopped = false;
+        for (const policy of this.policies) {
+            if (policy.scope === "repository" || !matches(policy.match, file)) {
+                continue;
+            }
+            if (stopped || this.excluded(file, policy)) {
+                output.skipped.push({
+                    scope: "file",
+                    file,
+                    policy: policy.name,
+                    policyId: policy.instanceId,
+                    reason: stopped ? "file-fix-error" : "excluded",
+                });
+                continue;
+            }
+            stopped = yield* new PolicyExecutor(this.options.root, this.options.fix ?? false).file(file, policy, output, cache);
+        }
+        return stopped;
+    }
+}
+/** Promise entry point sharing the Effection runner's contracts and cancellation. @public */
+export async function runPolicies(options) {
+    const runner = new PolicyRunner(options);
+    return await run(() => runner.run());
+}
+//# sourceMappingURL=runner.js.map

package/esm/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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","sourcesContent":["import { all, call, type Operation, run, spawn } from \"effection\";\nimport { DEFAULT_CONCURRENCY, validateConcurrency } from \"./concurrency.js\";\nimport {\n\tcreateExcludedPolicyFileMap,\n\ttype ExcludedPolicyFileMap,\n\texclusionRegex,\n} from \"./context.js\";\nimport { ParsedFileCache } from \"./fileCache.js\";\nimport { identifyPolicyInstances } from \"./makePolicy.js\";\nimport { newPerfStats, type PolicyHandlerPerfStats } from \"./perf.js\";\nimport type {\n\tConfiguredPolicy,\n\tIdentifiedPolicy,\n\tPolicyFinding,\n} from \"./policy.js\";\nimport { PolicyExecutor } from \"./policyExecution.js\";\n\n/** A finding with runner-owned identity and scope-safe location. @public */\nexport type PolicyRunFinding =\n\t| (Omit<PolicyFinding, \"files\"> & {\n\t\t\tscope: \"file\";\n\t\t\tfile: string;\n\t\t\tfiles?: never;\n\t\t\tpolicy: string;\n\t\t\tpolicyId: string;\n\t  })\n\t| (PolicyFinding & {\n\t\t\tscope: \"repository\";\n\t\t\tfile?: never;\n\t\t\tpolicy: string;\n\t\t\tpolicyId: string;\n\t  });\n\n/** An execution failure, separate from ordinary policy findings. @public */\nexport type PolicyExecutionError = {\n\tpolicy: string;\n\tpolicyId: string;\n\tphase: \"handle\" | \"resolve\";\n\tkind: \"contract\" | \"exception\";\n\tmessage: string;\n\tcause: unknown;\n} & (\n\t| { scope: \"file\"; file: string; files?: never }\n\t| { scope: \"repository\"; files: readonly string[]; file?: never }\n);\n\n/** A unit that was not executed. @public */\nexport type PolicySkippedWork = {\n\tpolicy: string;\n\tpolicyId: string;\n\treason: \"excluded\" | \"file-fix-error\" | \"repository-fix-error\";\n} & ({ scope: \"file\"; file: string } | { scope: \"repository\"; file?: never });\n\n/** Findings, failures, skipped units, and file/per-instance timing statistics. @public */\nexport interface PolicyRunResults {\n\tfindings: PolicyRunFinding[];\n\terrors: PolicyExecutionError[];\n\tskipped: PolicySkippedWork[];\n\tperfStats: PolicyHandlerPerfStats;\n}\n\n/** Full repository inventory, never inferred from a file selection. @public */\nexport type RepositoryInventory =\n\t| readonly string[]\n\t| (() => Promise<readonly string[]>);\n\n/** Shared Promise and Effection runner options. @public */\nexport interface PolicyRunnerOptions {\n\tpolicies: readonly ConfiguredPolicy[];\n\troot: string;\n\tinventory?: RepositoryInventory | undefined;\n\t/** Selection limits only file policies. Defaults to inventory when supplied. */\n\tfiles?: readonly string[] | undefined;\n\texclude?: readonly (string | RegExp)[] | undefined;\n\tfix?: boolean | undefined;\n\tconcurrency?: number | undefined;\n\tsignal?: AbortSignal | undefined;\n}\n\nfunction matches(regex: RegExp, file: string): boolean {\n\tconst index = regex.lastIndex;\n\ttry {\n\t\tregex.lastIndex = 0;\n\t\treturn regex.test(file);\n\t} finally {\n\t\tregex.lastIndex = index;\n\t}\n}\n\n/** Effection runner; cancellation unwinds active generator handlers and resolvers. @public */\nexport class PolicyRunner {\n\tprivate readonly policies: IdentifiedPolicy[];\n\tprivate readonly exclusions: RegExp[];\n\tprivate readonly policyExclusions: ExcludedPolicyFileMap;\n\tprivate readonly concurrency: number;\n\n\tpublic constructor(private readonly options: PolicyRunnerOptions) {\n\t\tthis.policies = identifyPolicyInstances(\n\t\t\toptions.policies.map((policy) => ({\n\t\t\t\t...policy,\n\t\t\t\tconfig:\n\t\t\t\t\tpolicy.config === undefined ? policy.defaultConfig : policy.config,\n\t\t\t})),\n\t\t);\n\t\tthis.exclusions = (options.exclude ?? []).map(exclusionRegex);\n\t\tthis.policyExclusions = createExcludedPolicyFileMap(this.policies);\n\t\tthis.concurrency = validateConcurrency(\n\t\t\toptions.concurrency ?? DEFAULT_CONCURRENCY,\n\t\t);\n\t\tif (\n\t\t\tthis.policies.some((policy) => policy.scope === \"repository\") &&\n\t\t\toptions.inventory === undefined\n\t\t) {\n\t\t\tthrow new TypeError(\n\t\t\t\t\"Repository policies require an explicit inventory array or loader; files is only a selection.\",\n\t\t\t);\n\t\t}\n\t\tfor (const policy of this.policies) {\n\t\t\tif (policy.scope === \"repository\" && policy.resolver !== undefined) {\n\t\t\t\tthrow new TypeError(\n\t\t\t\t\t\"Repository policies support inline fixes only; remove resolver.\",\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (\n\t\t\t\tpolicy.requiresConfig &&\n\t\t\t\tpolicy.config === undefined &&\n\t\t\t\tpolicy.defaultConfig === undefined\n\t\t\t) {\n\t\t\t\tthrow new TypeError(`Policy '${policy.name}' requires config.`);\n\t\t\t}\n\t\t}\n\t}\n\n\tpublic *run(): Operation<PolicyRunResults> {\n\t\tconst signal = this.options.signal;\n\t\tif (signal?.aborted) {\n\t\t\tthrow signal.reason;\n\t\t}\n\t\tconst task = yield* spawn(() => this.runInternal());\n\t\t// halt() is lazy; consuming it initiates teardown. The task retains any teardown error.\n\t\tconst abort = () => {\n\t\t\ttask.halt().catch(() => undefined);\n\t\t};\n\t\tsignal?.addEventListener(\"abort\", abort, { once: true });\n\t\ttry {\n\t\t\tif (signal?.aborted) {\n\t\t\t\tabort();\n\t\t\t}\n\t\t\treturn yield* task;\n\t\t} finally {\n\t\t\tsignal?.removeEventListener(\"abort\", abort);\n\t\t}\n\t}\n\n\tprivate *runInternal(): Operation<PolicyRunResults> {\n\t\tconst result: PolicyRunResults = {\n\t\t\tfindings: [],\n\t\t\terrors: [],\n\t\t\tskipped: [],\n\t\t\tperfStats: newPerfStats(),\n\t\t};\n\t\tconst fix = this.options.fix ?? false;\n\t\tconst cache = fix ? undefined : new ParsedFileCache();\n\t\tlet inventory: readonly string[] | undefined;\n\t\tif (this.options.files === undefined) {\n\t\t\tinventory = yield* this.loadInventory();\n\t\t}\n\t\tconst files = this.options.files ?? inventory ?? [];\n\t\tlet fileFixError = false;\n\t\ttry {\n\t\t\tif (fix) {\n\t\t\t\tfor (const file of files) {\n\t\t\t\t\tif (yield* this.runFile(file, result, cache)) {\n\t\t\t\t\t\tfileFixError = true;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tyield* this.runReadOnlyFiles(files, result, cache);\n\t\t\t}\n\t\t} finally {\n\t\t\tcache?.clear();\n\t\t}\n\t\tyield* this.runRepositories(result, inventory, fileFixError);\n\t\treturn result;\n\t}\n\n\tprivate *runReadOnlyFiles(\n\t\tfiles: readonly string[],\n\t\tresult: PolicyRunResults,\n\t\tcache: ParsedFileCache | undefined,\n\t): Operation<void> {\n\t\tconst entries = files.entries();\n\t\tconst outputs: PolicyRunResults[] = [];\n\t\tconst runner = this;\n\t\tyield* all(\n\t\t\tArray.from(\n\t\t\t\t{ length: Math.min(this.concurrency, files.length) },\n\t\t\t\tfunction* () {\n\t\t\t\t\tfor (\n\t\t\t\t\t\tlet entry = entries.next();\n\t\t\t\t\t\t!entry.done;\n\t\t\t\t\t\tentry = entries.next()\n\t\t\t\t\t) {\n\t\t\t\t\t\tconst [index, file] = entry.value;\n\t\t\t\t\t\tconst local: PolicyRunResults = {\n\t\t\t\t\t\t\tfindings: [],\n\t\t\t\t\t\t\terrors: [],\n\t\t\t\t\t\t\tskipped: [],\n\t\t\t\t\t\t\tperfStats: result.perfStats,\n\t\t\t\t\t\t};\n\t\t\t\t\t\tyield* runner.runFile(file, local, cache);\n\t\t\t\t\t\toutputs[index] = local;\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t),\n\t\t);\n\t\tfor (const output of outputs) {\n\t\t\tresult.findings.push(...output.findings);\n\t\t\tresult.errors.push(...output.errors);\n\t\t\tresult.skipped.push(...output.skipped);\n\t\t}\n\t}\n\n\tprivate *runRepositories(\n\t\tresult: PolicyRunResults,\n\t\tinitialInventory: readonly string[] | undefined,\n\t\tfileFixError: boolean,\n\t): Operation<void> {\n\t\tlet inventory = initialInventory;\n\t\tconst fix = this.options.fix ?? false;\n\t\tlet repositoryFixError = false;\n\t\tfor (const policy of this.policies) {\n\t\t\tif (policy.scope !== \"repository\") {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (fileFixError || repositoryFixError) {\n\t\t\t\tresult.skipped.push({\n\t\t\t\t\tscope: \"repository\",\n\t\t\t\t\tpolicy: policy.name,\n\t\t\t\t\tpolicyId: policy.instanceId,\n\t\t\t\t\treason: fileFixError ? \"file-fix-error\" : \"repository-fix-error\",\n\t\t\t\t});\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (inventory === undefined || fix) {\n\t\t\t\tinventory = yield* this.loadInventory();\n\t\t\t}\n\t\t\tconst eligible = (inventory ?? []).filter(\n\t\t\t\t(file) => !this.excluded(file, policy),\n\t\t\t);\n\t\t\trepositoryFixError = yield* new PolicyExecutor(\n\t\t\t\tthis.options.root,\n\t\t\t\tfix,\n\t\t\t).repository(policy, eligible, result);\n\t\t}\n\t}\n\n\tprivate *loadInventory(): Operation<readonly string[] | undefined> {\n\t\tconst inventory = this.options.inventory;\n\t\treturn typeof inventory === \"function\" ? yield* call(inventory) : inventory;\n\t}\n\n\tprivate excluded(file: string, policy: IdentifiedPolicy): boolean {\n\t\treturn (\n\t\t\tthis.exclusions.some((regex) => matches(regex, file)) ||\n\t\t\t(this.policyExclusions.get(policy.instanceId) ?? []).some((regex) =>\n\t\t\t\tmatches(regex, file),\n\t\t\t)\n\t\t);\n\t}\n\n\tprivate *runFile(\n\t\tfile: string,\n\t\toutput: PolicyRunResults,\n\t\tcache: ParsedFileCache | undefined,\n\t): Operation<boolean> {\n\t\toutput.perfStats.count++;\n\t\tconst globallyExcluded = this.exclusions.some((regex) =>\n\t\t\tmatches(regex, file),\n\t\t);\n\t\tif (!globallyExcluded) {\n\t\t\toutput.perfStats.processed++;\n\t\t}\n\t\tlet stopped = false;\n\t\tfor (const policy of this.policies) {\n\t\t\tif (policy.scope === \"repository\" || !matches(policy.match, file)) {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (stopped || this.excluded(file, policy)) {\n\t\t\t\toutput.skipped.push({\n\t\t\t\t\tscope: \"file\",\n\t\t\t\t\tfile,\n\t\t\t\t\tpolicy: policy.name,\n\t\t\t\t\tpolicyId: policy.instanceId,\n\t\t\t\t\treason: stopped ? \"file-fix-error\" : \"excluded\",\n\t\t\t\t});\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tstopped = yield* new PolicyExecutor(\n\t\t\t\tthis.options.root,\n\t\t\t\tthis.options.fix ?? false,\n\t\t\t).file(file, policy, output, cache);\n\t\t}\n\t\treturn stopped;\n\t}\n}\n\n/** Promise entry point sharing the Effection runner's contracts and cancellation. @public */\nexport async function runPolicies(\n\toptions: PolicyRunnerOptions,\n): Promise<PolicyRunResults> {\n\tconst runner = new PolicyRunner(options);\n\treturn await run(() => runner.run());\n}\n"]}

package/esm/settlePolicyPromise.d.ts

@@ -0,0 +1,4 @@
+import { type Operation } from "effection";
+/** Keep arbitrary rejected values out of Effection's error normalization. */
+export declare function settlePolicyPromise<T>(promise: Promise<T>): Operation<T>;
+//# sourceMappingURL=settlePolicyPromise.d.ts.map

package/esm/settlePolicyPromise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlePolicyPromise.d.ts","sourceRoot":"","sources":["../src/settlePolicyPromise.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAEjD,6EAA6E;AAC7E,wBAAiB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAWzE"}

package/esm/settlePolicyPromise.js

@@ -0,0 +1,10 @@
+import { call } from "effection";
+/** Keep arbitrary rejected values out of Effection's error normalization. */
+export function* settlePolicyPromise(promise) {
+    const settled = yield* call(() => promise.then((value) => ({ ok: true, value }), (cause) => ({ ok: false, cause })));
+    if (!settled.ok) {
+        throw settled.cause;
+    }
+    return settled.value;
+}
+//# sourceMappingURL=settlePolicyPromise.js.map

package/esm/settlePolicyPromise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlePolicyPromise.js","sourceRoot":"","sources":["../src/settlePolicyPromise.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAkB,MAAM,WAAW,CAAC;AAEjD,6EAA6E;AAC7E,MAAM,SAAS,CAAC,CAAC,mBAAmB,CAAI,OAAmB;IAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAChC,OAAO,CAAC,IAAI,CACX,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAU,EACzC,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAU,CACnD,CACD,CAAC;IACF,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,OAAO,CAAC,KAAK,CAAC;IACrB,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC;AACtB,CAAC","sourcesContent":["import { call, type Operation } from \"effection\";\n\n/** Keep arbitrary rejected values out of Effection's error normalization. */\nexport function* settlePolicyPromise<T>(promise: Promise<T>): Operation<T> {\n\tconst settled = yield* call(() =>\n\t\tpromise.then(\n\t\t\t(value) => ({ ok: true, value }) as const,\n\t\t\t(cause: unknown) => ({ ok: false, cause }) as const,\n\t\t),\n\t);\n\tif (!settled.ok) {\n\t\tthrow settled.cause;\n\t}\n\treturn settled.value;\n}\n"]}

package/esm/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.56.0"
+      "packageVersion": "7.59.4"
     }
   ]
 }

package/esm/utils/safePaths.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolves a candidate file path against the repository root and verifies it does not escape that root.
+ */
+export declare function resolveRepoFilePath(root: string, filePath: string): string;
+/**
+ * Converts an input path into a normalized repository-relative path after validating root containment.
+ */
+export declare function normalizeRepoRelativeFilePath(root: string, filePath: string): string;
+//# sourceMappingURL=safePaths.d.ts.map