repopo 0.7.1 → 0.9.0

package/esm/policy.d.ts

@@ -1,3 +1,5 @@
+import type { Operation } from "effection";
+import type { RequireExactlyOne } from "type-fest";
 /**
  * A type representing a policy name.
  *
@@ -30,17 +32,31 @@ export interface PolicyFunctionArguments<C> {
     config?: C | undefined;
 }
 /**
- * A policy handler is a function that is called to check policy against a file.
+ * A policy handler function that is called to check policy against a file.
+ *
+ * @remarks
+ * Policy handlers can be implemented in two ways:
+ * - As an async function returning a Promise
+ * - As an Effection generator function returning an Operation
+ *
+ * Both styles are supported to allow gradual migration and flexibility.
  *
  * @alpha
  */
-export type PolicyHandler<C = unknown | undefined> = (args: PolicyFunctionArguments<C>) => Promise<PolicyHandlerResult>;
+export type PolicyHandler<C = unknown | undefined> = ((args: PolicyFunctionArguments<C>) => Promise<PolicyHandlerResult>) | ((args: PolicyFunctionArguments<C>) => Operation<PolicyHandlerResult>);
 /**
  * A standalone function that can be called to resolve a policy failure.
  *
+ * @remarks
+ * Resolvers can be implemented in two ways:
+ * - As an async function returning a Promise
+ * - As an Effection generator function returning an Operation
+ *
+ * Both styles are supported to allow gradual migration and flexibility.
+ *
  * @alpha
  */
-export type PolicyStandaloneResolver<C = undefined> = (args: Omit<PolicyFunctionArguments<C>, "resolve">) => Promise<PolicyFixResult>;
+export type PolicyStandaloneResolver<C = undefined> = (args: Omit<PolicyFunctionArguments<C>, "resolve">) => Promise<PolicyFixResult> | Operation<PolicyFixResult>;
 /**
  * A RepoPolicyDefinition checks and applies policies to files in the repository.
  *
@@ -62,7 +78,7 @@ export interface PolicyDefinition<C = undefined> {
     /**
      * A more detailed description of the policy and its intended function.
      */
-    description?: string | undefined;
+    description: string;
     /**
      * A regular expression that is used to match files in the repo.
      */
@@ -108,7 +124,7 @@ export interface PolicyInstanceSettings<C> {
 /**
  * @alpha
  */
-export type PolicyInstance<C = undefined> = PolicyDefinition<C> & PolicyInstanceSettings<C>;
+export type PolicyInstance<C = undefined> = RequireExactlyOne<PolicyDefinition<C> & PolicyInstanceSettings<C>, "handler">;
 /**
  * A policy failure.
  *
@@ -130,7 +146,11 @@ export interface PolicyFailure {
     /**
      * An optional error message accompanying the failure.
      */
-    errorMessage?: string | undefined;
+    errorMessages: string[];
+    /**
+     * An optional string that tells the user how to fix the failure(s).
+     */
+    manualFix?: string;
 }
 /**
  * The result of an automatic fix for a failing policy.
@@ -154,13 +174,22 @@ export declare function isPolicyFixResult(toCheck: any): toCheck is PolicyFixRes
  * @alpha
  */
 export declare const DefaultPolicies: PolicyDefinition<any>[];
+/**
+ * Abstract base class for creating policies with object-based construction.
+ *
+ * @remarks
+ * This class accepts a {@link PolicyDefinition} object in its constructor,
+ * making it easier to add new optional properties in the future without breaking changes.
+ *
+ * @alpha
+ */
 export declare abstract class Policy<C> implements PolicyDefinition<C> {
     readonly name: string;
+    readonly description: string;
     readonly match: RegExp;
     readonly handler: PolicyHandler<C>;
-    readonly description?: string | undefined;
     readonly defaultConfig?: C | undefined;
     readonly resolver?: PolicyStandaloneResolver<C> | undefined;
-    constructor(name: string, match: RegExp, handler: PolicyHandler<C>, description?: string | undefined, defaultConfig?: C | undefined, resolver?: PolicyStandaloneResolver<C> | undefined);
+    constructor(definition: PolicyDefinition<C>);
 }
 //# sourceMappingURL=policy.d.ts.map

package/esm/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC;;;;GAIG;AAEH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACzC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;CACvB;AAED;;;;GAIG;AAEH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,GAAG,SAAS,IAAI,CACpD,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAC5B,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAOlC;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,GAAG,SAAS,IAAI,CACrD,IAAI,EAAE,IAAI,CAAC,uBAAuB,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,KAC7C,OAAO,CAAC,eAAe,CAAC,CAAC;AAI9B;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,SAAS;IAC9C;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEjC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;OAOG;IAEH,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAE1B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAEnD;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACxC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAEnC;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,SAAS,IAAI,gBAAgB,CAAC,CAAC,CAAC,GAC9D,sBAAsB,CAAC,CAAC,CAAC,CAAC;AAE3B;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAElC;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACrD;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,aAAa,GAAG,eAAe,CAAC;AAGzE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,IAAI,eAAe,CAK1E;AAED;;;;GAIG;AAGH,eAAO,MAAM,eAAe,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAKzC,CAAC;AAEX,8BAAsB,MAAM,CAAC,CAAC,CAAE,YAAW,gBAAgB,CAAC,CAAC,CAAC;aAE5C,IAAI,EAAE,MAAM;aACZ,KAAK,EAAE,MAAM;aACb,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;aACzB,WAAW,CAAC,EAAE,MAAM;aACpB,aAAa,CAAC,EAAE,CAAC;aACjB,QAAQ,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC;gBALtC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,WAAW,CAAC,EAAE,MAAM,YAAA,EACpB,aAAa,CAAC,EAAE,CAAC,YAAA,EACjB,QAAQ,CAAC,EAAE,wBAAwB,CAAC,CAAC,CAAC,YAAA;CAEvD"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/esm/policy.js

@@ -4,7 +4,7 @@ import { PackageJsonSorted } from "./policies/PackageJsonSorted.js";
 import { PackageScripts } from "./policies/PackageScripts.js";
 // biome-ignore lint/suspicious/noExplicitAny: type guard
 export function isPolicyFixResult(toCheck) {
-    if (typeof toCheck !== "object") {
+    if (typeof toCheck !== "object" || toCheck === null) {
         return false;
     }
     return "resolved" in toCheck;
@@ -21,20 +21,29 @@ export const DefaultPolicies = [
     PackageJsonSorted,
     PackageScripts,
 ];
+/**
+ * Abstract base class for creating policies with object-based construction.
+ *
+ * @remarks
+ * This class accepts a {@link PolicyDefinition} object in its constructor,
+ * making it easier to add new optional properties in the future without breaking changes.
+ *
+ * @alpha
+ */
 export class Policy {
     name;
+    description;
     match;
     handler;
-    description;
     defaultConfig;
     resolver;
-    constructor(name, match, handler, description, defaultConfig, resolver) {
-        this.name = name;
-        this.match = match;
-        this.handler = handler;
-        this.description = description;
-        this.defaultConfig = defaultConfig;
-        this.resolver = resolver;
+    constructor(definition) {
+        this.name = definition.name;
+        this.description = definition.description;
+        this.match = definition.match;
+        this.handler = definition.handler;
+        this.defaultConfig = definition.defaultConfig;
+        this.resolver = definition.resolver;
     }
 }
 //# sourceMappingURL=policy.js.map

package/esm/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,gCAAgC,EAAE,MAAM,gDAAgD,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AA4L9D,yDAAyD;AACzD,MAAM,UAAU,iBAAiB,CAAC,OAAY;IAC7C,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,UAAU,IAAI,OAAO,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AAEH,oDAAoD;AACpD,MAAM,CAAC,MAAM,eAAe,GAA4B;IACvD,kBAAkB;IAClB,gCAAgC;IAChC,iBAAiB;IACjB,cAAc;CACL,CAAC;AAEX,MAAM,OAAgB,MAAM;IAEV;IACA;IACA;IACA;IACA;IACA;IANjB,YACiB,IAAY,EACZ,KAAa,EACb,OAAyB,EACzB,WAAoB,EACpB,aAAiB,EACjB,QAAsC;QALtC,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAQ;QACb,YAAO,GAAP,OAAO,CAAkB;QACzB,gBAAW,GAAX,WAAW,CAAS;QACpB,kBAAa,GAAb,aAAa,CAAI;QACjB,aAAQ,GAAR,QAAQ,CAA8B;IACpD,CAAC;CACJ","sourcesContent":["import { NoJsFileExtensions } from \"./policies/NoJsFileExtensions.js\";\nimport { PackageJsonRepoDirectoryProperty } from \"./policies/PackageJsonRepoDirectoryProperty.js\";\nimport { PackageJsonSorted } from \"./policies/PackageJsonSorted.js\";\nimport { PackageScripts } from \"./policies/PackageScripts.js\";\n\n/**\n * A type representing a policy name.\n *\n * @alpha\n */\nexport type PolicyName = string;\n\n/**\n * Arguments passed to policy functions.\n *\n * @alpha\n */\n\nexport interface PolicyFunctionArguments<C> {\n\t/**\n\t * Path to the file, relative to the repo root.\n\t */\n\tfile: string;\n\n\t/**\n\t * Absolute path to the root of the repo.\n\t */\n\troot: string;\n\n\t/**\n\t * If true, the handler should resolve any violations automatically if possible.\n\t */\n\tresolve: boolean;\n\n\t/**\n\t * @remarks\n\t *\n\t * Note that the handler function receives the config as an argument.\n\t */\n\tconfig?: C | undefined;\n}\n\n/**\n * A policy handler is a function that is called to check policy against a file.\n *\n * @alpha\n */\n\nexport type PolicyHandler<C = unknown | undefined> = (\n\targs: PolicyFunctionArguments<C>,\n) => Promise<PolicyHandlerResult>;\n\n// export type PolicyCheckOnly = (\n// \tfile: string,\n// \troot: string,\n// ) => Promise<PolicyHandlerResult>;\n\n/**\n * A standalone function that can be called to resolve a policy failure.\n *\n * @alpha\n */\nexport type PolicyStandaloneResolver<C = undefined> = (\n\targs: Omit<PolicyFunctionArguments<C>, \"resolve\">,\n) => Promise<PolicyFixResult>;\n\n// function isPolicyHandler(input: PolicyHandler | PolicyCheckOnly): input is PolicyHandler\n\n/**\n * A RepoPolicyDefinition checks and applies policies to files in the repository.\n *\n * Each policy has a name and a match regex for matching which files it should apply to. Every file in th repo is\n * enumerated and if it matches the regex for a policy, that policy is applied.\n *\n * Each policy includes a handler function that checks a file against the policy and can optionally resolve any problems\n * (automated resolutions depend on the policy implementation).\n *\n * @typeParam C - type of configuration object used by the policy\n *\n * @alpha\n */\nexport interface PolicyDefinition<C = undefined> {\n\t/**\n\t * The name of the policy; displayed in UI and used in settings.\n\t */\n\tname: PolicyName;\n\n\t/**\n\t * A more detailed description of the policy and its intended function.\n\t */\n\tdescription?: string | undefined;\n\n\t/**\n\t * A regular expression that is used to match files in the repo.\n\t */\n\tmatch: RegExp;\n\n\t/**\n\t * A handler function that checks if a file is compliant with the policy.\n\t *\n\t * @param file - Repo-relative path to the file to check.\n\t * @param root - Absolute path to the root of the repo.\n\t * @param resolve - If true, automated policy fixes will be applied. Not all policies support automated fixes.\n\t * @returns True if the file passed the policy; otherwise a PolicyFailure object will be returned.\n\t */\n\n\thandler: PolicyHandler<C>;\n\n\t/**\n\t * A resolver function that can be used to automatically address the policy violation.\n\t *\n\t * @param file - Repo-relative path to the file to check.\n\t * @param root - Absolute path to the root of the repo.\n\t * @returns true if the file passed the policy; otherwise a PolicyFailure object will be returned.\n\t */\n\tresolver?: PolicyStandaloneResolver<C> | undefined;\n\n\t/**\n\t * A default config that will be used if none is provided.\n\t */\n\tdefaultConfig?: C | undefined;\n}\n\n/**\n * @alpha\n */\nexport interface PolicyInstanceSettings<C> {\n\t/**\n\t * An array of strings/regular expressions. File paths that match any of these expressions will be completely excluded\n\t * from policy.\n\t *\n\t * Paths will be matched relative to the root of the repo.\n\t */\n\texcludeFiles?: (string | RegExp)[];\n\n\t/**\n\t * The config that is applied to the policy instance.\n\t */\n\tconfig?: C | undefined;\n}\n\n/**\n * @alpha\n */\nexport type PolicyInstance<C = undefined> = PolicyDefinition<C> &\n\tPolicyInstanceSettings<C>;\n\n/**\n * A policy failure.\n *\n * @alpha\n */\nexport interface PolicyFailure {\n\t/**\n\t * Name of the policy that failed.\n\t */\n\tname: PolicyName;\n\n\t/**\n\t * Path to the file that failed the policy.\n\t */\n\tfile: string;\n\n\t/**\n\t * Set to `true` if the policy can be fixed automatically.\n\t */\n\tautoFixable?: boolean | undefined;\n\n\t/**\n\t * An optional error message accompanying the failure.\n\t */\n\terrorMessage?: string | undefined;\n}\n\n/**\n * The result of an automatic fix for a failing policy.\n *\n * @alpha\n */\nexport interface PolicyFixResult extends PolicyFailure {\n\t/**\n\t * Set to true if the failure was resolved by the automated fixer.\n\t */\n\tresolved: boolean;\n}\n\n/**\n * @alpha\n */\nexport type PolicyHandlerResult = true | PolicyFailure | PolicyFixResult;\n\n// biome-ignore lint/suspicious/noExplicitAny: type guard\nexport function isPolicyFixResult(toCheck: any): toCheck is PolicyFixResult {\n\tif (typeof toCheck !== \"object\") {\n\t\treturn false;\n\t}\n\treturn \"resolved\" in toCheck;\n}\n\n/**\n * Default policies included with repopo.\n *\n * @alpha\n */\n\n// biome-ignore lint/suspicious/noExplicitAny: FIXME\nexport const DefaultPolicies: PolicyDefinition<any>[] = [\n\tNoJsFileExtensions,\n\tPackageJsonRepoDirectoryProperty,\n\tPackageJsonSorted,\n\tPackageScripts,\n] as const;\n\nexport abstract class Policy<C> implements PolicyDefinition<C> {\n\tpublic constructor(\n\t\tpublic readonly name: string,\n\t\tpublic readonly match: RegExp,\n\t\tpublic readonly handler: PolicyHandler<C>,\n\t\tpublic readonly description?: string,\n\t\tpublic readonly defaultConfig?: C,\n\t\tpublic readonly resolver?: PolicyStandaloneResolver<C>,\n\t) {}\n}\n"]}
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,gCAAgC,EAAE,MAAM,gDAAgD,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAyM9D,yDAAyD;AACzD,MAAM,UAAU,iBAAiB,CAAC,OAAY;IAC7C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,UAAU,IAAI,OAAO,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AAEH,oDAAoD;AACpD,MAAM,CAAC,MAAM,eAAe,GAA4B;IACvD,kBAAkB;IAClB,gCAAgC;IAChC,iBAAiB;IACjB,cAAc;CACL,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,OAAgB,MAAM;IACX,IAAI,CAAS;IACb,WAAW,CAAS;IACpB,KAAK,CAAS;IACd,OAAO,CAAmB;IAC1B,aAAa,CAAiB;IAC9B,QAAQ,CAA2C;IAEnE,YAAmB,UAA+B;QACjD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;QAC1C,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC;QAClC,IAAI,CAAC,aAAa,GAAG,UAAU,CAAC,aAAa,CAAC;QAC9C,IAAI,CAAC,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC;IACrC,CAAC;CACD","sourcesContent":["import type { Operation } from \"effection\";\nimport type { RequireExactlyOne } from \"type-fest\";\nimport { NoJsFileExtensions } from \"./policies/NoJsFileExtensions.js\";\nimport { PackageJsonRepoDirectoryProperty } from \"./policies/PackageJsonRepoDirectoryProperty.js\";\nimport { PackageJsonSorted } from \"./policies/PackageJsonSorted.js\";\nimport { PackageScripts } from \"./policies/PackageScripts.js\";\n\n/**\n * A type representing a policy name.\n *\n * @alpha\n */\nexport type PolicyName = string;\n\n/**\n * Arguments passed to policy functions.\n *\n * @alpha\n */\n\nexport interface PolicyFunctionArguments<C> {\n\t/**\n\t * Path to the file, relative to the repo root.\n\t */\n\tfile: string;\n\n\t/**\n\t * Absolute path to the root of the repo.\n\t */\n\troot: string;\n\n\t/**\n\t * If true, the handler should resolve any violations automatically if possible.\n\t */\n\tresolve: boolean;\n\n\t/**\n\t * @remarks\n\t *\n\t * Note that the handler function receives the config as an argument.\n\t */\n\tconfig?: C | undefined;\n}\n\n/**\n * A policy handler function that is called to check policy against a file.\n *\n * @remarks\n * Policy handlers can be implemented in two ways:\n * - As an async function returning a Promise\n * - As an Effection generator function returning an Operation\n *\n * Both styles are supported to allow gradual migration and flexibility.\n *\n * @alpha\n */\nexport type PolicyHandler<C = unknown | undefined> =\n\t| ((args: PolicyFunctionArguments<C>) => Promise<PolicyHandlerResult>)\n\t| ((args: PolicyFunctionArguments<C>) => Operation<PolicyHandlerResult>);\n\n/**\n * A standalone function that can be called to resolve a policy failure.\n *\n * @remarks\n * Resolvers can be implemented in two ways:\n * - As an async function returning a Promise\n * - As an Effection generator function returning an Operation\n *\n * Both styles are supported to allow gradual migration and flexibility.\n *\n * @alpha\n */\nexport type PolicyStandaloneResolver<C = undefined> = (\n\targs: Omit<PolicyFunctionArguments<C>, \"resolve\">,\n) => Promise<PolicyFixResult> | Operation<PolicyFixResult>;\n\n/**\n * A RepoPolicyDefinition checks and applies policies to files in the repository.\n *\n * Each policy has a name and a match regex for matching which files it should apply to. Every file in th repo is\n * enumerated and if it matches the regex for a policy, that policy is applied.\n *\n * Each policy includes a handler function that checks a file against the policy and can optionally resolve any problems\n * (automated resolutions depend on the policy implementation).\n *\n * @typeParam C - type of configuration object used by the policy\n *\n * @alpha\n */\nexport interface PolicyDefinition<C = undefined> {\n\t/**\n\t * The name of the policy; displayed in UI and used in settings.\n\t */\n\tname: PolicyName;\n\n\t/**\n\t * A more detailed description of the policy and its intended function.\n\t */\n\tdescription: string;\n\n\t/**\n\t * A regular expression that is used to match files in the repo.\n\t */\n\tmatch: RegExp;\n\n\t/**\n\t * A handler function that checks if a file is compliant with the policy.\n\t *\n\t * @param file - Repo-relative path to the file to check.\n\t * @param root - Absolute path to the root of the repo.\n\t * @param resolve - If true, automated policy fixes will be applied. Not all policies support automated fixes.\n\t * @returns True if the file passed the policy; otherwise a PolicyFailure object will be returned.\n\t */\n\n\thandler: PolicyHandler<C>;\n\n\t/**\n\t * A resolver function that can be used to automatically address the policy violation.\n\t *\n\t * @param file - Repo-relative path to the file to check.\n\t * @param root - Absolute path to the root of the repo.\n\t * @returns true if the file passed the policy; otherwise a PolicyFailure object will be returned.\n\t */\n\tresolver?: PolicyStandaloneResolver<C> | undefined;\n\n\t/**\n\t * A default config that will be used if none is provided.\n\t */\n\tdefaultConfig?: C | undefined;\n}\n\n/**\n * @alpha\n */\nexport interface PolicyInstanceSettings<C> {\n\t/**\n\t * An array of strings/regular expressions. File paths that match any of these expressions will be completely excluded\n\t * from policy.\n\t *\n\t * Paths will be matched relative to the root of the repo.\n\t */\n\texcludeFiles?: (string | RegExp)[];\n\n\t/**\n\t * The config that is applied to the policy instance.\n\t */\n\tconfig?: C | undefined;\n}\n\n/**\n * @alpha\n */\nexport type PolicyInstance<C = undefined> = RequireExactlyOne<\n\tPolicyDefinition<C> & PolicyInstanceSettings<C>,\n\t\"handler\"\n>;\n\n/**\n * A policy failure.\n *\n * @alpha\n */\nexport interface PolicyFailure {\n\t/**\n\t * Name of the policy that failed.\n\t */\n\tname: PolicyName;\n\n\t/**\n\t * Path to the file that failed the policy.\n\t */\n\tfile: string;\n\n\t/**\n\t * Set to `true` if the policy can be fixed automatically.\n\t */\n\tautoFixable?: boolean | undefined;\n\n\t/**\n\t * An optional error message accompanying the failure.\n\t */\n\terrorMessages: string[];\n\n\t/**\n\t * An optional string that tells the user how to fix the failure(s).\n\t */\n\tmanualFix?: string;\n}\n\n/**\n * The result of an automatic fix for a failing policy.\n *\n * @alpha\n */\nexport interface PolicyFixResult extends PolicyFailure {\n\t/**\n\t * Set to true if the failure was resolved by the automated fixer.\n\t */\n\tresolved: boolean;\n}\n\n/**\n * @alpha\n */\nexport type PolicyHandlerResult = true | PolicyFailure | PolicyFixResult;\n\n// biome-ignore lint/suspicious/noExplicitAny: type guard\nexport function isPolicyFixResult(toCheck: any): toCheck is PolicyFixResult {\n\tif (typeof toCheck !== \"object\" || toCheck === null) {\n\t\treturn false;\n\t}\n\treturn \"resolved\" in toCheck;\n}\n\n/**\n * Default policies included with repopo.\n *\n * @alpha\n */\n\n// biome-ignore lint/suspicious/noExplicitAny: FIXME\nexport const DefaultPolicies: PolicyDefinition<any>[] = [\n\tNoJsFileExtensions,\n\tPackageJsonRepoDirectoryProperty,\n\tPackageJsonSorted,\n\tPackageScripts,\n] as const;\n\n/**\n * Abstract base class for creating policies with object-based construction.\n *\n * @remarks\n * This class accepts a {@link PolicyDefinition} object in its constructor,\n * making it easier to add new optional properties in the future without breaking changes.\n *\n * @alpha\n */\nexport abstract class Policy<C> implements PolicyDefinition<C> {\n\tpublic readonly name: string;\n\tpublic readonly description: string;\n\tpublic readonly match: RegExp;\n\tpublic readonly handler: PolicyHandler<C>;\n\tpublic readonly defaultConfig?: C | undefined;\n\tpublic readonly resolver?: PolicyStandaloneResolver<C> | undefined;\n\n\tpublic constructor(definition: PolicyDefinition<C>) {\n\t\tthis.name = definition.name;\n\t\tthis.description = definition.description;\n\t\tthis.match = definition.match;\n\t\tthis.handler = definition.handler;\n\t\tthis.defaultConfig = definition.defaultConfig;\n\t\tthis.resolver = definition.resolver;\n\t}\n}\n"]}

package/esm/policyDefiners/defineFileHeaderPolicy.d.ts

@@ -13,9 +13,16 @@ export interface FileHeaderPolicyConfig {
     autoGenText?: string;
 }
 /**
+ * Configuration for generating file headers with specific formatting rules.
+ *
+ * @remarks
+ * This interface extends FileHeaderPolicyConfig and adds formatting-specific
+ * properties to control how headers are inserted into different file types.
+ *
  * @alpha
  */
 export interface FileHeaderGeneratorConfig extends Partial<FileHeaderPolicyConfig> {
+    /** Regular expression that matches files this header generator applies to */
     match: RegExp;
     /**
      * Regex matching header prefix (e.g. `/*!\r?\n`)
@@ -33,13 +40,48 @@ export interface FileHeaderGeneratorConfig extends Partial<FileHeaderPolicyConfi
      * Regex matching the header postfix.
      */
     headerEnd?: RegExp;
+    /**
+     * Function that generates the properly formatted header content for insertion into files.
+     *
+     * @param content - The original file content
+     * @param config - The file header policy configuration
+     * @returns The formatted header string to insert
+     */
     replacer: (content: string, config: FileHeaderPolicyConfig) => string;
 }
+/**
+ * Input arguments for defining a file header policy.
+ *
+ * @alpha
+ */
+export interface DefineFileHeaderPolicyArgs {
+    /**
+     * The name of the policy.
+     */
+    name: string;
+    /**
+     * A description of the policy's purpose.
+     */
+    description: string;
+    /**
+     * Configuration for how headers are detected and inserted.
+     */
+    config: FileHeaderGeneratorConfig;
+}
 /**
  * Given a {@link FileHeaderPolicyConfig}, produces a function that detects correct file headers
  * and returns an error string if the header is missing or incorrect.
  *
+ * @example
+ * ```typescript
+ * const MyHeaderPolicy = defineFileHeaderPolicy({
+ *   name: "MyHeaderPolicy",
+ *   description: "Ensures files have required headers",
+ *   config: { match: /\.ts$/, lineStart: /\/\/ /, lineEnd: /\r?\n/, replacer: ... },
+ * });
+ * ```
+ *
  * @alpha
  */
-export declare function defineFileHeaderPolicy(name: string, config: FileHeaderGeneratorConfig): PolicyDefinition<FileHeaderPolicyConfig>;
+export declare function defineFileHeaderPolicy(args: DefineFileHeaderPolicyArgs): PolicyDefinition<FileHeaderPolicyConfig>;
 //# sourceMappingURL=defineFileHeaderPolicy.d.ts.map

package/esm/policyDefiners/defineFileHeaderPolicy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineFileHeaderPolicy.d.ts","sourceRoot":"","sources":["../../src/policyDefiners/defineFileHeaderPolicy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,gBAAgB,EAGhB,MAAM,cAAc,CAAC;AAItB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,yBAChB,SAAQ,OAAO,CAAC,sBAAsB,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,KAAK,MAAM,CAAC;CACtE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,yBAAyB,GAC/B,gBAAgB,CAAC,sBAAsB,CAAC,CAiE1C"}
+{"version":3,"file":"defineFileHeaderPolicy.d.ts","sourceRoot":"","sources":["../../src/policyDefiners/defineFileHeaderPolicy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACX,gBAAgB,EAGhB,MAAM,cAAc,CAAC;AAItB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAChB,SAAQ,OAAO,CAAC,sBAAsB,CAAC;IACvC,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,KAAK,MAAM,CAAC;CACtE;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IAC1C;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,yBAAyB,CAAC;CAClC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,0BAA0B,GAC9B,gBAAgB,CAAC,sBAAsB,CAAC,CAoE1C"}

package/esm/policyDefiners/defineFileHeaderPolicy.js

@@ -1,14 +1,25 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { EOL as newline } from "node:os";
+import { call } from "effection";
 import { extname } from "pathe";
 const trailingSpaces = /\s*\\r\?\\n/;
 /**
  * Given a {@link FileHeaderPolicyConfig}, produces a function that detects correct file headers
  * and returns an error string if the header is missing or incorrect.
  *
+ * @example
+ * ```typescript
+ * const MyHeaderPolicy = defineFileHeaderPolicy({
+ *   name: "MyHeaderPolicy",
+ *   description: "Ensures files have required headers",
+ *   config: { match: /\.ts$/, lineStart: /\/\/ /, lineEnd: /\r?\n/, replacer: ... },
+ * });
+ * ```
+ *
  * @alpha
  */
-export function defineFileHeaderPolicy(name, config) {
+export function defineFileHeaderPolicy(args) {
+    const { name, description, config } = args;
     const pre = config.headerStart?.source ?? "";
     const start = config.lineStart.source;
     const end = config.lineEnd.source;
@@ -25,8 +36,9 @@ export function defineFileHeaderPolicy(name, config) {
     const regex = new RegExp(`^${pre}${toRegex(config.headerText ?? "")}(${toRegex(config.autoGenText ?? "")})?${post}`);
     return {
         name,
+        description,
         match: config.match,
-        handler: async ({ file, resolve, config: policyConfig }) => {
+        handler: function* ({ file, resolve, config: policyConfig }) {
             if (policyConfig === undefined) {
                 return true;
             }
@@ -34,18 +46,19 @@ export function defineFileHeaderPolicy(name, config) {
                 name,
                 file,
                 autoFixable: true,
+                errorMessages: [],
             };
             // TODO: Consider reading only the first 512B or so since headers are typically
             // at the beginning of the file.
-            const content = await readFile(file, { encoding: "utf8" });
+            const content = yield* call(() => readFile(file, { encoding: "utf8" }));
             const failed = !regex.test(content);
             if (failed) {
-                failResult.errorMessage = `${extname(file)} file missing header`;
+                failResult.errorMessages.push(`${extname(file)} file missing header`);
             }
             if (failed) {
                 if (resolve) {
                     const newContent = config.replacer(content, policyConfig);
-                    await writeFile(file, newContent);
+                    yield* call(() => writeFile(file, newContent));
                     const fixResult = {
                         ...failResult,
                         resolved: true,

package/esm/policyDefiners/defineFileHeaderPolicy.js.map

@@ -1 +1 @@
-{"version":3,"file":"defineFileHeaderPolicy.js","sourceRoot":"","sources":["../../src/policyDefiners/defineFileHeaderPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,GAAG,IAAI,OAAO,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAOhC,MAAM,cAAc,GAAG,aAAa,CAAC;AA+CrC;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACrC,IAAY,EACZ,MAAiC;IAEjC,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,EAAE,MAAM,IAAI,EAAE,CAAC;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;IACtC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,EAAE,MAAM,IAAI,EAAE,CAAC;IAE5C,2EAA2E;IAC3E,mGAAmG;IACnG,MAAM,OAAO,GAAG,CAAC,IAAY,EAAU,EAAE,CACxC,IAAI;SACF,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CACH,CAAC,IAAI,EAAE,EAAE,CACR,GAAG,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,GAAG,GAAG,EAAE,CAC/D;SACA,IAAI,CAAC,EAAE,CAAC;SACR,OAAO,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC,uCAAuC;IAE9E,wFAAwF;IACxF,0FAA0F;IAC1F,MAAM,KAAK,GAAG,IAAI,MAAM,CACvB,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE,CAC1F,CAAC;IAEF,OAAO;QACN,IAAI;QACJ,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,EAAE;YAC1D,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;gBAChC,OAAO,IAAI,CAAC;YACb,CAAC;YAED,MAAM,UAAU,GAAkB;gBACjC,IAAI;gBACJ,IAAI;gBACJ,WAAW,EAAE,IAAI;aACjB,CAAC;YAEF,+EAA+E;YAC/E,gCAAgC;YAChC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YAC3D,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAEpC,IAAI,MAAM,EAAE,CAAC;gBACZ,UAAU,CAAC,YAAY,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,sBAAsB,CAAC;YAClE,CAAC;YAED,IAAI,MAAM,EAAE,CAAC;gBACZ,IAAI,OAAO,EAAE,CAAC;oBACb,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;oBAC1D,MAAM,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;oBAElC,MAAM,SAAS,GAAoB;wBAClC,GAAG,UAAU;wBACb,QAAQ,EAAE,IAAI;qBACd,CAAC;oBAEF,OAAO,SAAS,CAAC;gBAClB,CAAC;gBACD,OAAO,UAAU,CAAC;YACnB,CAAC;YAED,OAAO,IAAI,CAAC;QACb,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["import { readFile, writeFile } from \"node:fs/promises\";\nimport { EOL as newline } from \"node:os\";\nimport { extname } from \"pathe\";\nimport type {\n\tPolicyDefinition,\n\tPolicyFailure,\n\tPolicyFixResult,\n} from \"../policy.js\";\n\nconst trailingSpaces = /\\s*\\\\r\\?\\\\n/;\n\n/**\n * @alpha\n */\nexport interface FileHeaderPolicyConfig {\n\t/**\n\t * The text to use as the header.\n\t */\n\theaderText: string;\n\n\t/**\n\t * An optional string that will be appended to the headerText.\n\t */\n\tautoGenText?: string;\n}\n\n/**\n * @alpha\n */\nexport interface FileHeaderGeneratorConfig\n\textends Partial<FileHeaderPolicyConfig> {\n\tmatch: RegExp;\n\n\t/**\n\t * Regex matching header prefix (e.g. `/*!\\r?\\n`)\n\t */\n\theaderStart?: RegExp;\n\n\t/**\n\t * Regex matching beginning of each line (e.g. ' * ')\n\t */\n\tlineStart: RegExp;\n\n\t/**\n\t * Regex matching the end of each line (e.g., `\\r?\\n`)\n\t */\n\tlineEnd: RegExp;\n\n\t/**\n\t * Regex matching the header postfix.\n\t */\n\theaderEnd?: RegExp;\n\n\treplacer: (content: string, config: FileHeaderPolicyConfig) => string;\n}\n\n/**\n * Given a {@link FileHeaderPolicyConfig}, produces a function that detects correct file headers\n * and returns an error string if the header is missing or incorrect.\n *\n * @alpha\n */\nexport function defineFileHeaderPolicy(\n\tname: string,\n\tconfig: FileHeaderGeneratorConfig,\n): PolicyDefinition<FileHeaderPolicyConfig> {\n\tconst pre = config.headerStart?.source ?? \"\";\n\tconst start = config.lineStart.source;\n\tconst end = config.lineEnd.source;\n\tconst post = config.headerEnd?.source ?? \"\";\n\n\t// Helper which constructs a matching RegExp from a given multiline string.\n\t// (See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping)\n\tconst toRegex = (text: string): string =>\n\t\ttext\n\t\t\t.split(newline)\n\t\t\t.map(\n\t\t\t\t(line) =>\n\t\t\t\t\t`${start}${line.replace(/[$()*+.?[\\\\\\]^{|}]/g, \"\\\\$&\")}${end}`,\n\t\t\t)\n\t\t\t.join(\"\")\n\t\t\t.replace(trailingSpaces, \"\\\\r?\\\\n\"); // Trim trailing spaces at end-of-line.\n\n\t// Detection regex matches the header start (if any), followed by lines in 'headerText',\n\t// optionally followed by lines in the 'autoGenText', and finally the header end (if any).\n\tconst regex = new RegExp(\n\t\t`^${pre}${toRegex(config.headerText ?? \"\")}(${toRegex(config.autoGenText ?? \"\")})?${post}`,\n\t);\n\n\treturn {\n\t\tname,\n\t\tmatch: config.match,\n\t\thandler: async ({ file, resolve, config: policyConfig }) => {\n\t\t\tif (policyConfig === undefined) {\n\t\t\t\treturn true;\n\t\t\t}\n\n\t\t\tconst failResult: PolicyFailure = {\n\t\t\t\tname,\n\t\t\t\tfile,\n\t\t\t\tautoFixable: true,\n\t\t\t};\n\n\t\t\t// TODO: Consider reading only the first 512B or so since headers are typically\n\t\t\t// at the beginning of the file.\n\t\t\tconst content = await readFile(file, { encoding: \"utf8\" });\n\t\t\tconst failed = !regex.test(content);\n\n\t\t\tif (failed) {\n\t\t\t\tfailResult.errorMessage = `${extname(file)} file missing header`;\n\t\t\t}\n\n\t\t\tif (failed) {\n\t\t\t\tif (resolve) {\n\t\t\t\t\tconst newContent = config.replacer(content, policyConfig);\n\t\t\t\t\tawait writeFile(file, newContent);\n\n\t\t\t\t\tconst fixResult: PolicyFixResult = {\n\t\t\t\t\t\t...failResult,\n\t\t\t\t\t\tresolved: true,\n\t\t\t\t\t};\n\n\t\t\t\t\treturn fixResult;\n\t\t\t\t}\n\t\t\t\treturn failResult;\n\t\t\t}\n\n\t\t\treturn true;\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"defineFileHeaderPolicy.js","sourceRoot":"","sources":["../../src/policyDefiners/defineFileHeaderPolicy.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile, writeFile } from \"node:fs/promises\";\nimport { EOL as newline } from \"node:os\";\nimport { call } from \"effection\";\nimport { extname } from \"pathe\";\nimport type {\n\tPolicyDefinition,\n\tPolicyFailure,\n\tPolicyFixResult,\n} from \"../policy.js\";\n\nconst trailingSpaces = /\\s*\\\\r\\?\\\\n/;\n\n/**\n * @alpha\n */\nexport interface FileHeaderPolicyConfig {\n\t/**\n\t * The text to use as the header.\n\t */\n\theaderText: string;\n\n\t/**\n\t * An optional string that will be appended to the headerText.\n\t */\n\tautoGenText?: string;\n}\n\n/**\n * Configuration for generating file headers with specific formatting rules.\n *\n * @remarks\n * This interface extends FileHeaderPolicyConfig and adds formatting-specific\n * properties to control how headers are inserted into different file types.\n *\n * @alpha\n */\nexport interface FileHeaderGeneratorConfig\n\textends Partial<FileHeaderPolicyConfig> {\n\t/** Regular expression that matches files this header generator applies to */\n\tmatch: RegExp;\n\n\t/**\n\t * Regex matching header prefix (e.g. `/*!\\r?\\n`)\n\t */\n\theaderStart?: RegExp;\n\n\t/**\n\t * Regex matching beginning of each line (e.g. ' * ')\n\t */\n\tlineStart: RegExp;\n\n\t/**\n\t * Regex matching the end of each line (e.g., `\\r?\\n`)\n\t */\n\tlineEnd: RegExp;\n\n\t/**\n\t * Regex matching the header postfix.\n\t */\n\theaderEnd?: RegExp;\n\n\t/**\n\t * Function that generates the properly formatted header content for insertion into files.\n\t *\n\t * @param content - The original file content\n\t * @param config - The file header policy configuration\n\t * @returns The formatted header string to insert\n\t */\n\treplacer: (content: string, config: FileHeaderPolicyConfig) => string;\n}\n\n/**\n * Input arguments for defining a file header policy.\n *\n * @alpha\n */\nexport interface DefineFileHeaderPolicyArgs {\n\t/**\n\t * The name of the policy.\n\t */\n\tname: string;\n\n\t/**\n\t * A description of the policy's purpose.\n\t */\n\tdescription: string;\n\n\t/**\n\t * Configuration for how headers are detected and inserted.\n\t */\n\tconfig: FileHeaderGeneratorConfig;\n}\n\n/**\n * Given a {@link FileHeaderPolicyConfig}, produces a function that detects correct file headers\n * and returns an error string if the header is missing or incorrect.\n *\n * @example\n * ```typescript\n * const MyHeaderPolicy = defineFileHeaderPolicy({\n *   name: \"MyHeaderPolicy\",\n *   description: \"Ensures files have required headers\",\n *   config: { match: /\\.ts$/, lineStart: /\\/\\/ /, lineEnd: /\\r?\\n/, replacer: ... },\n * });\n * ```\n *\n * @alpha\n */\nexport function defineFileHeaderPolicy(\n\targs: DefineFileHeaderPolicyArgs,\n): PolicyDefinition<FileHeaderPolicyConfig> {\n\tconst { name, description, config } = args;\n\tconst pre = config.headerStart?.source ?? \"\";\n\tconst start = config.lineStart.source;\n\tconst end = config.lineEnd.source;\n\tconst post = config.headerEnd?.source ?? \"\";\n\n\t// Helper which constructs a matching RegExp from a given multiline string.\n\t// (See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping)\n\tconst toRegex = (text: string): string =>\n\t\ttext\n\t\t\t.split(newline)\n\t\t\t.map(\n\t\t\t\t(line) =>\n\t\t\t\t\t`${start}${line.replace(/[$()*+.?[\\\\\\]^{|}]/g, \"\\\\$&\")}${end}`,\n\t\t\t)\n\t\t\t.join(\"\")\n\t\t\t.replace(trailingSpaces, \"\\\\r?\\\\n\"); // Trim trailing spaces at end-of-line.\n\n\t// Detection regex matches the header start (if any), followed by lines in 'headerText',\n\t// optionally followed by lines in the 'autoGenText', and finally the header end (if any).\n\tconst regex = new RegExp(\n\t\t`^${pre}${toRegex(config.headerText ?? \"\")}(${toRegex(config.autoGenText ?? \"\")})?${post}`,\n\t);\n\n\treturn {\n\t\tname,\n\t\tdescription,\n\t\tmatch: config.match,\n\t\thandler: function* ({ file, resolve, config: policyConfig }) {\n\t\t\tif (policyConfig === undefined) {\n\t\t\t\treturn true;\n\t\t\t}\n\n\t\t\tconst failResult: PolicyFailure = {\n\t\t\t\tname,\n\t\t\t\tfile,\n\t\t\t\tautoFixable: true,\n\t\t\t\terrorMessages: [],\n\t\t\t};\n\n\t\t\t// TODO: Consider reading only the first 512B or so since headers are typically\n\t\t\t// at the beginning of the file.\n\t\t\tconst content = yield* call(() => readFile(file, { encoding: \"utf8\" }));\n\t\t\tconst failed = !regex.test(content);\n\n\t\t\tif (failed) {\n\t\t\t\tfailResult.errorMessages.push(`${extname(file)} file missing header`);\n\t\t\t}\n\n\t\t\tif (failed) {\n\t\t\t\tif (resolve) {\n\t\t\t\t\tconst newContent = config.replacer(content, policyConfig);\n\t\t\t\t\tyield* call(() => writeFile(file, newContent));\n\n\t\t\t\t\tconst fixResult: PolicyFixResult = {\n\t\t\t\t\t\t...failResult,\n\t\t\t\t\t\tresolved: true,\n\t\t\t\t\t};\n\n\t\t\t\t\treturn fixResult;\n\t\t\t\t}\n\t\t\t\treturn failResult;\n\t\t\t}\n\n\t\t\treturn true;\n\t\t},\n\t};\n}\n"]}

package/esm/policyDefiners/definePackagePolicy.d.ts

@@ -1,15 +1,56 @@
+import { type Operation } from "effection";
 import type { PackageJson } from "type-fest";
 import type { PolicyDefinition, PolicyFunctionArguments, PolicyHandlerResult } from "../policy.js";
 /**
  * A policy handler especially for policies that target package.json.
  *
+ * @remarks
+ * Package JSON handlers can be implemented in two ways:
+ * - As an async function returning a Promise
+ * - As an Effection generator function returning an Operation
+ *
+ * Both styles are supported to allow gradual migration and flexibility.
+ *
  * @alpha
  */
-export type PackageJsonHandler<J, C> = (json: J, args: PolicyFunctionArguments<C>) => Promise<PolicyHandlerResult>;
+export type PackageJsonHandler<J, C> = (json: J, args: PolicyFunctionArguments<C>) => Operation<PolicyHandlerResult> | Promise<PolicyHandlerResult>;
+/**
+ * Input arguments for defining a package.json policy.
+ *
+ * @alpha
+ */
+export interface DefinePackagePolicyArgs<J, C> {
+    /**
+     * The name of the policy.
+     */
+    name: string;
+    /**
+     * A description of the policy's purpose.
+     */
+    description: string;
+    /**
+     * The handler function that receives the parsed package.json and policy arguments.
+     */
+    handler: PackageJsonHandler<J, C>;
+}
 /**
  * Define a repo policy for package.json files.
  *
+ * @example
+ * ```typescript
+ * const MyPackagePolicy = definePackagePolicy({
+ *   name: "MyPackagePolicy",
+ *   description: "Ensures package.json has required fields",
+ *   handler: function* (json, { file }) {
+ *     if (!json.name) {
+ *       return { name: "MyPackagePolicy", file, errorMessages: ["Missing name"] };
+ *     }
+ *     return true;
+ *   },
+ * });
+ * ```
+ *
  * @alpha
  */
-export declare function definePackagePolicy<J = PackageJson, C = undefined>(name: string, packagePolicy: PackageJsonHandler<J, C>): PolicyDefinition<C>;
+export declare function definePackagePolicy<J = PackageJson, C = undefined>(args: DefinePackagePolicyArgs<J, C>): PolicyDefinition<C>;
 //# sourceMappingURL=definePackagePolicy.d.ts.map

package/esm/policyDefiners/definePackagePolicy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definePackagePolicy.d.ts","sourceRoot":"","sources":["../../src/policyDefiners/definePackagePolicy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,EACX,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,MAAM,cAAc,CAAC;AAItB;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,EAAE,CAAC,IAAI,CACtC,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAC5B,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,WAAW,EAAE,CAAC,GAAG,SAAS,EACjE,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,GAErC,gBAAgB,CAAC,CAAC,CAAC,CAUrB"}
+{"version":3,"file":"definePackagePolicy.d.ts","sourceRoot":"","sources":["../../src/policyDefiners/definePackagePolicy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,EACX,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,EACnB,MAAM,cAAc,CAAC;AAItB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,EAAE,CAAC,IAAI,CACtC,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAC5B,SAAS,CAAC,mBAAmB,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAcnE;;;;GAIG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,EAAE,CAAC;IAC5C;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,WAAW,EAAE,CAAC,GAAG,SAAS,EACjE,IAAI,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,GACjC,gBAAgB,CAAC,CAAC,CAAC,CAwBrB"}

package/esm/policyDefiners/definePackagePolicy.js

@@ -1,19 +1,55 @@
+import { call } from "effection";
 import jsonfile from "jsonfile";
+import { resolve } from "pathe";
 import { PackageJsonRegexMatch } from "../policies/constants.js";
 const { readFile: readJson } = jsonfile;
+/**
+ * Type guard to check if a value is an Effection Operation (generator).
+ */
+function isOperation(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "next" in value &&
+        typeof value.next === "function");
+}
 /**
  * Define a repo policy for package.json files.
  *
+ * @example
+ * ```typescript
+ * const MyPackagePolicy = definePackagePolicy({
+ *   name: "MyPackagePolicy",
+ *   description: "Ensures package.json has required fields",
+ *   handler: function* (json, { file }) {
+ *     if (!json.name) {
+ *       return { name: "MyPackagePolicy", file, errorMessages: ["Missing name"] };
+ *     }
+ *     return true;
+ *   },
+ * });
+ * ```
+ *
  * @alpha
  */
-export function definePackagePolicy(name, packagePolicy) {
-    // const func = () => handler(json, args);
+export function definePackagePolicy(args) {
+    const { name, description, handler: packagePolicy } = args;
     return {
         name,
+        description,
         match: PackageJsonRegexMatch,
-        handler: async (innerArgs) => {
-            const json = await readJson(innerArgs.file);
-            return packagePolicy(json, innerArgs);
+        handler: function* (innerArgs) {
+            const json = yield* call(() => readJson(resolve(innerArgs.root, innerArgs.file)));
+            const result = packagePolicy(json, innerArgs);
+            // Handle both Operation (generator) and Promise return types
+            if (result instanceof Promise) {
+                return yield* call(() => result);
+            }
+            // Check if it's an Effection Operation (generator)
+            if (isOperation(result)) {
+                return yield* result;
+            }
+            // This should never happen with proper handler typing
+            throw new Error(`Unexpected handler result type: ${typeof result}`);
         },
     };
 }

package/esm/policyDefiners/definePackagePolicy.js.map

@@ -1 +1 @@
-{"version":3,"file":"definePackagePolicy.js","sourceRoot":"","sources":["../../src/policyDefiners/definePackagePolicy.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAOjE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC;AAYxC;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAClC,IAAY,EACZ,aAAuC;IAGvC,0CAA0C;IAC1C,OAAO;QACN,IAAI;QACJ,KAAK,EAAE,qBAAqB;QAC5B,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE;YAC5B,MAAM,IAAI,GAAM,MAAM,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC/C,OAAO,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACvC,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["import jsonfile from \"jsonfile\";\nimport type { PackageJson } from \"type-fest\";\nimport { PackageJsonRegexMatch } from \"../policies/constants.js\";\nimport type {\n\tPolicyDefinition,\n\tPolicyFunctionArguments,\n\tPolicyHandlerResult,\n} from \"../policy.js\";\n\nconst { readFile: readJson } = jsonfile;\n\n/**\n * A policy handler especially for policies that target package.json.\n *\n * @alpha\n */\nexport type PackageJsonHandler<J, C> = (\n\tjson: J,\n\targs: PolicyFunctionArguments<C>,\n) => Promise<PolicyHandlerResult>;\n\n/**\n * Define a repo policy for package.json files.\n *\n * @alpha\n */\nexport function definePackagePolicy<J = PackageJson, C = undefined>(\n\tname: string,\n\tpackagePolicy: PackageJsonHandler<J, C>,\n\t// args: PolicyFunctionArguments<C>,\n): PolicyDefinition<C> {\n\t// const func = () => handler(json, args);\n\treturn {\n\t\tname,\n\t\tmatch: PackageJsonRegexMatch,\n\t\thandler: async (innerArgs) => {\n\t\t\tconst json: J = await readJson(innerArgs.file);\n\t\t\treturn packagePolicy(json, innerArgs);\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"definePackagePolicy.js","sourceRoot":"","sources":["../../src/policyDefiners/definePackagePolicy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAkB,MAAM,WAAW,CAAC;AACjD,OAAO,QAAQ,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEhC,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAOjE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC;AAmBxC;;GAEG;AACH,SAAS,WAAW,CAAI,KAAc;IACrC,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,OAAQ,KAA2B,CAAC,IAAI,KAAK,UAAU,CACvD,CAAC;AACH,CAAC;AAwBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CAClC,IAAmC;IAEnC,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IAC3D,OAAO;QACN,IAAI;QACJ,WAAW;QACX,KAAK,EAAE,qBAAqB;QAC5B,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS;YAC5B,MAAM,IAAI,GAAM,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAChC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CACjD,CAAC;YACF,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YAE9C,6DAA6D;YAC7D,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;gBAC/B,OAAO,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;YAClC,CAAC;YACD,mDAAmD;YACnD,IAAI,WAAW,CAAsB,MAAM,CAAC,EAAE,CAAC;gBAC9C,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC;YACtB,CAAC;YACD,sDAAsD;YACtD,MAAM,IAAI,KAAK,CAAC,mCAAmC,OAAO,MAAM,EAAE,CAAC,CAAC;QACrE,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["import { call, type Operation } from \"effection\";\nimport jsonfile from \"jsonfile\";\nimport { resolve } from \"pathe\";\nimport type { PackageJson } from \"type-fest\";\nimport { PackageJsonRegexMatch } from \"../policies/constants.js\";\nimport type {\n\tPolicyDefinition,\n\tPolicyFunctionArguments,\n\tPolicyHandlerResult,\n} from \"../policy.js\";\n\nconst { readFile: readJson } = jsonfile;\n\n/**\n * A policy handler especially for policies that target package.json.\n *\n * @remarks\n * Package JSON handlers can be implemented in two ways:\n * - As an async function returning a Promise\n * - As an Effection generator function returning an Operation\n *\n * Both styles are supported to allow gradual migration and flexibility.\n *\n * @alpha\n */\nexport type PackageJsonHandler<J, C> = (\n\tjson: J,\n\targs: PolicyFunctionArguments<C>,\n) => Operation<PolicyHandlerResult> | Promise<PolicyHandlerResult>;\n\n/**\n * Type guard to check if a value is an Effection Operation (generator).\n */\nfunction isOperation<T>(value: unknown): value is Operation<T> {\n\treturn (\n\t\ttypeof value === \"object\" &&\n\t\tvalue !== null &&\n\t\t\"next\" in value &&\n\t\ttypeof (value as { next: unknown }).next === \"function\"\n\t);\n}\n\n/**\n * Input arguments for defining a package.json policy.\n *\n * @alpha\n */\nexport interface DefinePackagePolicyArgs<J, C> {\n\t/**\n\t * The name of the policy.\n\t */\n\tname: string;\n\n\t/**\n\t * A description of the policy's purpose.\n\t */\n\tdescription: string;\n\n\t/**\n\t * The handler function that receives the parsed package.json and policy arguments.\n\t */\n\thandler: PackageJsonHandler<J, C>;\n}\n\n/**\n * Define a repo policy for package.json files.\n *\n * @example\n * ```typescript\n * const MyPackagePolicy = definePackagePolicy({\n *   name: \"MyPackagePolicy\",\n *   description: \"Ensures package.json has required fields\",\n *   handler: function* (json, { file }) {\n *     if (!json.name) {\n *       return { name: \"MyPackagePolicy\", file, errorMessages: [\"Missing name\"] };\n *     }\n *     return true;\n *   },\n * });\n * ```\n *\n * @alpha\n */\nexport function definePackagePolicy<J = PackageJson, C = undefined>(\n\targs: DefinePackagePolicyArgs<J, C>,\n): PolicyDefinition<C> {\n\tconst { name, description, handler: packagePolicy } = args;\n\treturn {\n\t\tname,\n\t\tdescription,\n\t\tmatch: PackageJsonRegexMatch,\n\t\thandler: function* (innerArgs) {\n\t\t\tconst json: J = yield* call(() =>\n\t\t\t\treadJson(resolve(innerArgs.root, innerArgs.file)),\n\t\t\t);\n\t\t\tconst result = packagePolicy(json, innerArgs);\n\n\t\t\t// Handle both Operation (generator) and Promise return types\n\t\t\tif (result instanceof Promise) {\n\t\t\t\treturn yield* call(() => result);\n\t\t\t}\n\t\t\t// Check if it's an Effection Operation (generator)\n\t\t\tif (isOperation<PolicyHandlerResult>(result)) {\n\t\t\t\treturn yield* result;\n\t\t\t}\n\t\t\t// This should never happen with proper handler typing\n\t\t\tthrow new Error(`Unexpected handler result type: ${typeof result}`);\n\t\t},\n\t};\n}\n"]}

package/esm/tsdoc-metadata.json

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

package/esm/utils/indentation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Represents detected indentation style.
+ *
+ * - `"\t"` - Tab character
+ * - `number` - Number of spaces (e.g., 2, 4)
+ */
+export type IndentationStyle = "\t" | number;
+/**
+ * Default indentation style used when detection fails or no indentation is found.
+ *
+ * @alpha
+ */
+export declare const DEFAULT_INDENTATION: IndentationStyle;
+/**
+ * Detect the indentation style used in a file.
+ *
+ * Analyzes the file content to determine whether tabs or spaces are used
+ * for indentation. This is useful when writing files to preserve
+ * the existing formatting style.
+ *
+ * @param filePath - Path to the file
+ * @param defaultIndentation - Indentation to use if detection fails (default: tab)
+ * @returns The detected indentation (tab character or number of spaces)
+ *
+ * @example
+ * ```typescript
+ * const indent = await detectIndentation("/path/to/package.json");
+ * // Returns "\t" for tabs, or a number like 2 or 4 for spaces
+ *
+ * // With custom default
+ * const indent = await detectIndentation("/path/to/file.yaml", 2);
+ * ```
+ *
+ * @alpha
+ */
+export declare function detectIndentation(filePath: string, defaultIndentation?: IndentationStyle): Promise<IndentationStyle>;
+/**
+ * Detect the indentation style used in text content.
+ *
+ * Analyzes the content string to determine whether tabs or spaces are used
+ * for indentation. This is a pure function useful for testing and for
+ * cases where the content is already in memory.
+ *
+ * The detection algorithm:
+ * 1. Splits content into lines
+ * 2. Finds the first line that starts with whitespace
+ * 3. If it starts with a tab, returns tab
+ * 4. If it starts with spaces, returns the count of leading spaces
+ * 5. If no indented lines found, returns the default
+ *
+ * @param content - The file content as a string
+ * @param defaultIndentation - Indentation to use if no indented lines found (default: tab)
+ * @returns The detected indentation (tab character or number of spaces)
+ *
+ * @example
+ * ```typescript
+ * // JSON with 2-space indentation
+ * const json = '{\n  "name": "test"\n}';
+ * detectIndentationFromContent(json); // Returns 2
+ *
+ * // YAML with tab indentation
+ * const yaml = 'root:\n\tchild: value';
+ * detectIndentationFromContent(yaml); // Returns "\t"
+ *
+ * // No indentation found - uses default
+ * detectIndentationFromContent('no indent'); // Returns "\t"
+ * detectIndentationFromContent('no indent', 4); // Returns 4
+ * ```
+ *
+ * @alpha
+ */
+export declare function detectIndentationFromContent(content: string, defaultIndentation?: IndentationStyle): IndentationStyle;
+//# sourceMappingURL=indentation.d.ts.map

package/esm/utils/indentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indentation.d.ts","sourceRoot":"","sources":["../../src/utils/indentation.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,MAAM,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,gBAAuB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,iBAAiB,CACtC,QAAQ,EAAE,MAAM,EAChB,kBAAkB,GAAE,gBAAsC,GACxD,OAAO,CAAC,gBAAgB,CAAC,CAQ3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,MAAM,EACf,kBAAkB,GAAE,gBAAsC,GACxD,gBAAgB,CAmBlB"}