repopo 0.7.0 → 0.8.0

package/esm/policies/PackagePrivateField.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Configuration for the PackagePrivateField policy.
+ *
+ * This policy enforces that packages are correctly marked as private or public based on
+ * their scope or name. This is essential for monorepos where some packages should be
+ * published to npm while others should remain internal.
+ *
+ * All pattern matching uses glob patterns via picomatch.
+ *
+ * @example
+ * ```typescript
+ * const config: PackagePrivateFieldConfig = {
+ *   // Packages in myorg scope must be published (private: false or absent)
+ *   mustPublish: ["@myorg/*"],
+ *   // Packages in internal scope must be private
+ *   mustBePrivate: ["@internal/*"],
+ *   // Packages in experimental scope can choose
+ *   mayPublish: ["@experimental/*"],
+ * };
+ * ```
+ *
+ * @alpha
+ */
+export interface PackagePrivateFieldConfig {
+    /**
+     * A list of glob patterns for packages that must be published.
+     *
+     * Packages matching these patterns must NOT have `private: true` in their package.json.
+     * If they do, the policy will fail and can auto-fix by removing the private field.
+     *
+     * @remarks
+     *
+     * Uses glob patterns via picomatch. Use "@scope/*" to match all packages in a scope,
+     * or use exact package names.
+     *
+     * @example
+     * ```typescript
+     * mustPublish: ["@fluidframework/*", "@fluid-tools/*", "tinylicious"]
+     * ```
+     */
+    mustPublish?: string[];
+    /**
+     * A list of glob patterns for packages that must be private.
+     *
+     * Packages matching these patterns must have `private: true` in their package.json.
+     * If they don't, the policy will fail and can auto-fix by adding `private: true`.
+     *
+     * @remarks
+     *
+     * Uses glob patterns via picomatch (see mustPublish for pattern examples).
+     *
+     * @example
+     * ```typescript
+     * mustBePrivate: ["@fluid-internal/*", "@fluid-private/*"]
+     * ```
+     */
+    mustBePrivate?: string[];
+    /**
+     * A list of glob patterns for packages that may optionally be published.
+     *
+     * Packages matching these patterns can choose whether to be private or public.
+     * The policy will not enforce either state for these packages.
+     *
+     * @remarks
+     *
+     * Uses glob patterns via picomatch (see mustPublish for pattern examples).
+     * Packages not matching any list default to requiring `private: true`.
+     *
+     * @example
+     * ```typescript
+     * mayPublish: ["@fluid-experimental/*"]
+     * ```
+     */
+    mayPublish?: string[];
+    /**
+     * Default behavior for packages that don't match any of the above lists.
+     *
+     * - `"private"` (default): Unmatched packages must have `private: true`
+     * - `"public"`: Unmatched packages must NOT have `private: true`
+     * - `"ignore"`: No enforcement for unmatched packages
+     *
+     * @defaultValue "private"
+     */
+    unmatchedPackages?: "private" | "public" | "ignore";
+}
+/**
+ * A policy that enforces the `private` field in package.json based on package scope or name.
+ *
+ * This policy is essential for monorepos where publishing control is important:
+ *
+ * - Prevent accidental publishing of internal packages
+ * - Ensure public packages don't have `private: true` blocking publishing
+ * - Allow experimental packages to choose their own publishing status
+ *
+ * @remarks
+ *
+ * The policy evaluates packages in the following order:
+ *
+ * 1. If the package matches `mustPublish`, it must NOT have `private: true`
+ * 2. If the package matches `mustBePrivate`, it MUST have `private: true`
+ * 3. If the package matches `mayPublish`, no enforcement is applied
+ * 4. Otherwise, the `unmatchedPackages` setting determines behavior (defaults to requiring private)
+ *
+ * @example
+ * ```typescript
+ * import { makePolicy } from "repopo";
+ * import { PackagePrivateField } from "repopo/policies";
+ *
+ * const config: RepopoConfig = {
+ *   policies: [
+ *     makePolicy(PackagePrivateField, {
+ *       mustPublish: ["@myorg/*"],
+ *       mustBePrivate: ["@internal/*"],
+ *       mayPublish: ["@experimental/*"],
+ *       unmatchedPackages: "private",
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @alpha
+ */
+export declare const PackagePrivateField: import("../policy.js").PolicyDefinition<PackagePrivateFieldConfig | undefined>;
+//# sourceMappingURL=PackagePrivateField.d.ts.map

package/esm/policies/PackagePrivateField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackagePrivateField.d.ts","sourceRoot":"","sources":["../../src/policies/PackagePrivateField.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,yBAAyB;IACzC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACpD;AA+DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,mBAAmB,gFA0E9B,CAAC"}

package/esm/policies/PackagePrivateField.js

@@ -0,0 +1,155 @@
+import jsonfile from "jsonfile";
+import picomatch from "picomatch";
+import { definePackagePolicy } from "../policyDefiners/definePackagePolicy.js";
+const { writeFile: writeJson } = jsonfile;
+/**
+ * Sentinel value indicating that the package's private status should not be enforced.
+ * This is more explicit than using `undefined` to represent "ignore".
+ */
+const IGNORE_PRIVATE_STATE = "ignore";
+/**
+ * Check if a package name matches any pattern in the list.
+ *
+ * Supports glob patterns via picomatch. Use patterns like:
+ * - "@myorg/\*" - matches all packages in the myorg scope
+ * - "my-package" - exact match
+ * - "my-*" - matches my-foo, my-bar, etc.
+ *
+ * @param packageName - The package name to check (e.g., `@myorg/foo`)
+ * @param patterns - List of glob patterns or exact package names
+ * @returns `true` if the package matches any pattern
+ */
+function matchesAnyPattern(packageName, patterns) {
+    if (patterns === undefined || patterns.length === 0) {
+        return false;
+    }
+    return picomatch.isMatch(packageName, patterns);
+}
+/**
+ * Determine what the private field should be for a package.
+ *
+ * @returns `true` if package must be private, `false` if must be public, `"ignore"` if either is ok
+ */
+function getRequiredPrivateState(packageName, config) {
+    // Check mustPublish first - these packages must NOT be private
+    if (matchesAnyPattern(packageName, config.mustPublish)) {
+        return false;
+    }
+    // Check mustBePrivate - these packages MUST be private
+    if (matchesAnyPattern(packageName, config.mustBePrivate)) {
+        return true;
+    }
+    // Check mayPublish - these packages can be either
+    if (matchesAnyPattern(packageName, config.mayPublish)) {
+        return IGNORE_PRIVATE_STATE;
+    }
+    // Default behavior for unmatched packages
+    const unmatchedBehavior = config.unmatchedPackages ?? "private";
+    switch (unmatchedBehavior) {
+        case "private":
+            return true;
+        case "public":
+            return false;
+        case "ignore":
+            return IGNORE_PRIVATE_STATE;
+        default:
+            throw new Error(`Unknown unmatchedPackages value: ${unmatchedBehavior}`);
+    }
+}
+/**
+ * A policy that enforces the `private` field in package.json based on package scope or name.
+ *
+ * This policy is essential for monorepos where publishing control is important:
+ *
+ * - Prevent accidental publishing of internal packages
+ * - Ensure public packages don't have `private: true` blocking publishing
+ * - Allow experimental packages to choose their own publishing status
+ *
+ * @remarks
+ *
+ * The policy evaluates packages in the following order:
+ *
+ * 1. If the package matches `mustPublish`, it must NOT have `private: true`
+ * 2. If the package matches `mustBePrivate`, it MUST have `private: true`
+ * 3. If the package matches `mayPublish`, no enforcement is applied
+ * 4. Otherwise, the `unmatchedPackages` setting determines behavior (defaults to requiring private)
+ *
+ * @example
+ * ```typescript
+ * import { makePolicy } from "repopo";
+ * import { PackagePrivateField } from "repopo/policies";
+ *
+ * const config: RepopoConfig = {
+ *   policies: [
+ *     makePolicy(PackagePrivateField, {
+ *       mustPublish: ["@myorg/*"],
+ *       mustBePrivate: ["@internal/*"],
+ *       mayPublish: ["@experimental/*"],
+ *       unmatchedPackages: "private",
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @alpha
+ */
+export const PackagePrivateField = definePackagePolicy("PackagePrivateField", async (json, { file, config, resolve }) => {
+    // If no config provided, skip validation
+    if (config === undefined) {
+        return true;
+    }
+    const packageName = json.name;
+    // Skip packages without a name (shouldn't happen in practice)
+    if (packageName === undefined) {
+        return true;
+    }
+    // Skip the root package (typically named "root" in monorepos)
+    if (packageName === "root") {
+        return true;
+    }
+    const requiredState = getRequiredPrivateState(packageName, config);
+    // If "ignore", the package can be either private or public
+    if (requiredState === IGNORE_PRIVATE_STATE) {
+        return true;
+    }
+    const currentlyPrivate = json.private === true;
+    // Check if the current state matches the required state
+    if (requiredState === currentlyPrivate) {
+        return true;
+    }
+    // State mismatch - build error message
+    const errorMessage = requiredState === true
+        ? `Package "${packageName}" must be marked private. Add "private": true to package.json.`
+        : `Package "${packageName}" must not be marked private. Remove "private": true from package.json to allow publishing.`;
+    const failResult = {
+        name: PackagePrivateField.name,
+        file,
+        autoFixable: true,
+        errorMessages: [errorMessage],
+    };
+    if (resolve) {
+        const fixResult = {
+            ...failResult,
+            resolved: false,
+        };
+        try {
+            if (requiredState === true) {
+                // Add private: true
+                json.private = true;
+            }
+            else {
+                // Remove private field
+                delete json.private;
+            }
+            await writeJson(file, json, { spaces: "\t" });
+            fixResult.resolved = true;
+        }
+        catch {
+            fixResult.resolved = false;
+            fixResult.errorMessages = [`Failed to update ${file}`];
+        }
+        return fixResult;
+    }
+    return failResult;
+});
+//# sourceMappingURL=PackagePrivateField.js.map

package/esm/policies/PackagePrivateField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackagePrivateField.js","sourceRoot":"","sources":["../../src/policies/PackagePrivateField.ts"],"names":[],"mappings":"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","sourcesContent":["import jsonfile from \"jsonfile\";\nimport picomatch from \"picomatch\";\nimport type { PackageJson } from \"type-fest\";\nimport type { PolicyFailure, PolicyFixResult } from \"../policy.js\";\nimport { definePackagePolicy } from \"../policyDefiners/definePackagePolicy.js\";\n\nconst { writeFile: writeJson } = jsonfile;\n\n/**\n * Sentinel value indicating that the package's private status should not be enforced.\n * This is more explicit than using `undefined` to represent \"ignore\".\n */\nconst IGNORE_PRIVATE_STATE = \"ignore\" as const;\n\n/**\n * The required private state for a package.\n * - `true`: Package must have `private: true`\n * - `false`: Package must NOT have `private: true`\n * - `\"ignore\"`: No enforcement - package can be either private or public\n */\ntype RequiredPrivateState = boolean | typeof IGNORE_PRIVATE_STATE;\n\n/**\n * Configuration for the PackagePrivateField policy.\n *\n * This policy enforces that packages are correctly marked as private or public based on\n * their scope or name. This is essential for monorepos where some packages should be\n * published to npm while others should remain internal.\n *\n * All pattern matching uses glob patterns via picomatch.\n *\n * @example\n * ```typescript\n * const config: PackagePrivateFieldConfig = {\n *   // Packages in myorg scope must be published (private: false or absent)\n *   mustPublish: [\"@myorg/*\"],\n *   // Packages in internal scope must be private\n *   mustBePrivate: [\"@internal/*\"],\n *   // Packages in experimental scope can choose\n *   mayPublish: [\"@experimental/*\"],\n * };\n * ```\n *\n * @alpha\n */\nexport interface PackagePrivateFieldConfig {\n\t/**\n\t * A list of glob patterns for packages that must be published.\n\t *\n\t * Packages matching these patterns must NOT have `private: true` in their package.json.\n\t * If they do, the policy will fail and can auto-fix by removing the private field.\n\t *\n\t * @remarks\n\t *\n\t * Uses glob patterns via picomatch. Use \"@scope/*\" to match all packages in a scope,\n\t * or use exact package names.\n\t *\n\t * @example\n\t * ```typescript\n\t * mustPublish: [\"@fluidframework/*\", \"@fluid-tools/*\", \"tinylicious\"]\n\t * ```\n\t */\n\tmustPublish?: string[];\n\n\t/**\n\t * A list of glob patterns for packages that must be private.\n\t *\n\t * Packages matching these patterns must have `private: true` in their package.json.\n\t * If they don't, the policy will fail and can auto-fix by adding `private: true`.\n\t *\n\t * @remarks\n\t *\n\t * Uses glob patterns via picomatch (see mustPublish for pattern examples).\n\t *\n\t * @example\n\t * ```typescript\n\t * mustBePrivate: [\"@fluid-internal/*\", \"@fluid-private/*\"]\n\t * ```\n\t */\n\tmustBePrivate?: string[];\n\n\t/**\n\t * A list of glob patterns for packages that may optionally be published.\n\t *\n\t * Packages matching these patterns can choose whether to be private or public.\n\t * The policy will not enforce either state for these packages.\n\t *\n\t * @remarks\n\t *\n\t * Uses glob patterns via picomatch (see mustPublish for pattern examples).\n\t * Packages not matching any list default to requiring `private: true`.\n\t *\n\t * @example\n\t * ```typescript\n\t * mayPublish: [\"@fluid-experimental/*\"]\n\t * ```\n\t */\n\tmayPublish?: string[];\n\n\t/**\n\t * Default behavior for packages that don't match any of the above lists.\n\t *\n\t * - `\"private\"` (default): Unmatched packages must have `private: true`\n\t * - `\"public\"`: Unmatched packages must NOT have `private: true`\n\t * - `\"ignore\"`: No enforcement for unmatched packages\n\t *\n\t * @defaultValue \"private\"\n\t */\n\tunmatchedPackages?: \"private\" | \"public\" | \"ignore\";\n}\n\n/**\n * Check if a package name matches any pattern in the list.\n *\n * Supports glob patterns via picomatch. Use patterns like:\n * - \"@myorg/\\*\" - matches all packages in the myorg scope\n * - \"my-package\" - exact match\n * - \"my-*\" - matches my-foo, my-bar, etc.\n *\n * @param packageName - The package name to check (e.g., `@myorg/foo`)\n * @param patterns - List of glob patterns or exact package names\n * @returns `true` if the package matches any pattern\n */\nfunction matchesAnyPattern(\n\tpackageName: string,\n\tpatterns: string[] | undefined,\n): boolean {\n\tif (patterns === undefined || patterns.length === 0) {\n\t\treturn false;\n\t}\n\n\treturn picomatch.isMatch(packageName, patterns);\n}\n\n/**\n * Determine what the private field should be for a package.\n *\n * @returns `true` if package must be private, `false` if must be public, `\"ignore\"` if either is ok\n */\nfunction getRequiredPrivateState(\n\tpackageName: string,\n\tconfig: PackagePrivateFieldConfig,\n): RequiredPrivateState {\n\t// Check mustPublish first - these packages must NOT be private\n\tif (matchesAnyPattern(packageName, config.mustPublish)) {\n\t\treturn false;\n\t}\n\n\t// Check mustBePrivate - these packages MUST be private\n\tif (matchesAnyPattern(packageName, config.mustBePrivate)) {\n\t\treturn true;\n\t}\n\n\t// Check mayPublish - these packages can be either\n\tif (matchesAnyPattern(packageName, config.mayPublish)) {\n\t\treturn IGNORE_PRIVATE_STATE;\n\t}\n\n\t// Default behavior for unmatched packages\n\tconst unmatchedBehavior = config.unmatchedPackages ?? \"private\";\n\tswitch (unmatchedBehavior) {\n\t\tcase \"private\":\n\t\t\treturn true;\n\t\tcase \"public\":\n\t\t\treturn false;\n\t\tcase \"ignore\":\n\t\t\treturn IGNORE_PRIVATE_STATE;\n\t\tdefault:\n\t\t\tthrow new Error(`Unknown unmatchedPackages value: ${unmatchedBehavior}`);\n\t}\n}\n\n/**\n * A policy that enforces the `private` field in package.json based on package scope or name.\n *\n * This policy is essential for monorepos where publishing control is important:\n *\n * - Prevent accidental publishing of internal packages\n * - Ensure public packages don't have `private: true` blocking publishing\n * - Allow experimental packages to choose their own publishing status\n *\n * @remarks\n *\n * The policy evaluates packages in the following order:\n *\n * 1. If the package matches `mustPublish`, it must NOT have `private: true`\n * 2. If the package matches `mustBePrivate`, it MUST have `private: true`\n * 3. If the package matches `mayPublish`, no enforcement is applied\n * 4. Otherwise, the `unmatchedPackages` setting determines behavior (defaults to requiring private)\n *\n * @example\n * ```typescript\n * import { makePolicy } from \"repopo\";\n * import { PackagePrivateField } from \"repopo/policies\";\n *\n * const config: RepopoConfig = {\n *   policies: [\n *     makePolicy(PackagePrivateField, {\n *       mustPublish: [\"@myorg/*\"],\n *       mustBePrivate: [\"@internal/*\"],\n *       mayPublish: [\"@experimental/*\"],\n *       unmatchedPackages: \"private\",\n *     }),\n *   ],\n * };\n * ```\n *\n * @alpha\n */\nexport const PackagePrivateField = definePackagePolicy<\n\tPackageJson,\n\tPackagePrivateFieldConfig | undefined\n>(\"PackagePrivateField\", async (json, { file, config, resolve }) => {\n\t// If no config provided, skip validation\n\tif (config === undefined) {\n\t\treturn true;\n\t}\n\n\tconst packageName = json.name;\n\n\t// Skip packages without a name (shouldn't happen in practice)\n\tif (packageName === undefined) {\n\t\treturn true;\n\t}\n\n\t// Skip the root package (typically named \"root\" in monorepos)\n\tif (packageName === \"root\") {\n\t\treturn true;\n\t}\n\n\tconst requiredState = getRequiredPrivateState(packageName, config);\n\n\t// If \"ignore\", the package can be either private or public\n\tif (requiredState === IGNORE_PRIVATE_STATE) {\n\t\treturn true;\n\t}\n\n\tconst currentlyPrivate = json.private === true;\n\n\t// Check if the current state matches the required state\n\tif (requiredState === currentlyPrivate) {\n\t\treturn true;\n\t}\n\n\t// State mismatch - build error message\n\tconst errorMessage =\n\t\trequiredState === true\n\t\t\t? `Package \"${packageName}\" must be marked private. Add \"private\": true to package.json.`\n\t\t\t: `Package \"${packageName}\" must not be marked private. Remove \"private\": true from package.json to allow publishing.`;\n\n\tconst failResult: PolicyFailure = {\n\t\tname: PackagePrivateField.name,\n\t\tfile,\n\t\tautoFixable: true,\n\t\terrorMessages: [errorMessage],\n\t};\n\n\tif (resolve) {\n\t\tconst fixResult: PolicyFixResult = {\n\t\t\t...failResult,\n\t\t\tresolved: false,\n\t\t};\n\n\t\ttry {\n\t\t\tif (requiredState === true) {\n\t\t\t\t// Add private: true\n\t\t\t\tjson.private = true;\n\t\t\t} else {\n\t\t\t\t// Remove private field\n\t\t\t\tdelete json.private;\n\t\t\t}\n\n\t\t\tawait writeJson(file, json, { spaces: \"\\t\" });\n\t\t\tfixResult.resolved = true;\n\t\t} catch {\n\t\t\tfixResult.resolved = false;\n\t\t\tfixResult.errorMessages = [`Failed to update ${file}`];\n\t\t}\n\n\t\treturn fixResult;\n\t}\n\n\treturn failResult;\n});\n"]}

package/esm/policies/PackageReadme.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Policy settings for the PackageReadme repo policy.
+ *
+ * @alpha
+ */
+export interface PackageReadmeSettings {
+    /**
+     * Whether to skip validation for private packages.
+     *
+     * @defaultValue true
+     *
+     * @remarks
+     *
+     * Private packages are typically not published and may not need a README file.
+     * Set to `false` to require README files for all packages.
+     */
+    skipPrivate?: boolean;
+    /**
+     * Whether to require the README title to match the package name.
+     *
+     * @defaultValue true
+     *
+     * @remarks
+     *
+     * When enabled, the first line of the README must be `# package-name`.
+     * This ensures consistency and helps users identify the package.
+     */
+    requireMatchingTitle?: boolean;
+    /**
+     * A string that must appear in the README content.
+     *
+     * @remarks
+     *
+     * Useful for ensuring all READMEs include required content like trademark
+     * notices, disclaimers, or standard documentation sections.
+     *
+     * @example
+     * ```typescript
+     * requiredContent: "## Trademark"
+     * ```
+     */
+    requiredContent?: string;
+}
+/**
+ * A repo policy that ensures each package has a README.md file with proper content.
+ *
+ * @remarks
+ *
+ * This policy validates that packages have documentation and can enforce:
+ * 1. README.md file exists
+ * 2. README title matches the package name
+ * 3. README contains required content (e.g., trademark notices)
+ *
+ * The policy supports auto-fixing by creating a basic README with the package name as title.
+ *
+ * @example
+ * ```typescript
+ * import { makePolicy } from "repopo";
+ * import { PackageReadme } from "repopo/policies";
+ *
+ * const config: RepopoConfig = {
+ *   policies: [
+ *     // Basic README validation
+ *     makePolicy(PackageReadme),
+ *
+ *     // Require trademark notice in all READMEs
+ *     makePolicy(PackageReadme, {
+ *       requiredContent: "## Trademark",
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @alpha
+ */
+export declare const PackageReadme: import("../policy.js").PolicyDefinition<PackageReadmeSettings | undefined>;
+//# sourceMappingURL=PackageReadme.d.ts.map

package/esm/policies/PackageReadme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackageReadme.d.ts","sourceRoot":"","sources":["../../src/policies/PackageReadme.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACrC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAkMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,aAAa,4EAuCxB,CAAC"}

package/esm/policies/PackageReadme.js

@@ -0,0 +1,209 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "pathe";
+import { definePackagePolicy } from "../policyDefiners/definePackagePolicy.js";
+// Pre-compiled regex for performance
+const LINE_SPLIT_REGEX = /\r?\n/;
+const HEADING_REGEX = /^#\s+(.+)$/;
+/**
+ * Extract the title from a README file (first markdown H1 heading).
+ *
+ * @param content - The README content
+ * @returns The title text (without the `# ` prefix) or `undefined` if not found
+ */
+function extractReadmeTitle(content) {
+    const lines = content.split(LINE_SPLIT_REGEX);
+    for (const line of lines) {
+        const match = HEADING_REGEX.exec(line);
+        if (match?.[1]) {
+            return match[1].trim();
+        }
+    }
+    return undefined;
+}
+/**
+ * Create a basic README content with package name as title.
+ */
+function createReadmeContent(packageName, requiredContent) {
+    let content = `# ${packageName}\n`;
+    if (requiredContent) {
+        content += `\n${requiredContent}\n`;
+    }
+    return content;
+}
+/**
+ * Handle case when README is missing.
+ */
+async function handleMissingReadme(readmePath, packageName, file, resolve, requiredContent) {
+    if (resolve) {
+        try {
+            await writeFile(readmePath, createReadmeContent(packageName, requiredContent));
+            return {
+                name: "PackageReadme",
+                file,
+                resolved: true,
+                autoFixable: true,
+                errorMessages: [`Created README.md for package "${packageName}"`],
+            };
+        }
+        catch {
+            return {
+                name: "PackageReadme",
+                file,
+                resolved: false,
+                autoFixable: true,
+                errorMessages: [
+                    `Failed to create README.md for package "${packageName}"`,
+                ],
+            };
+        }
+    }
+    return {
+        name: "PackageReadme",
+        file,
+        autoFixable: true,
+        errorMessages: [`README.md missing for package "${packageName}"`],
+    };
+}
+/**
+ * Validate README title against package name.
+ *
+ * @returns `true` if valid, or an error message string if invalid
+ */
+function validateTitle(readmeContent, packageName) {
+    const title = extractReadmeTitle(readmeContent);
+    if (title !== packageName) {
+        return `README title "${title ?? "(none)"}" doesn't match package name "${packageName}"`;
+    }
+    return true;
+}
+/**
+ * Handle required content validation and auto-fix.
+ */
+async function handleRequiredContent(readmePath, readmeContent, requiredContent, resolve) {
+    if (readmeContent.includes(requiredContent)) {
+        return { fixed: false };
+    }
+    if (resolve) {
+        try {
+            const newContent = readmeContent.endsWith("\n")
+                ? `${readmeContent}${requiredContent}\n`
+                : `${readmeContent}\n${requiredContent}\n`;
+            await writeFile(readmePath, newContent);
+            return {
+                error: `README missing required content: "${requiredContent}"`,
+                fixed: true,
+            };
+        }
+        catch {
+            // Fall through to report error
+        }
+    }
+    return {
+        error: `README missing required content: "${requiredContent}"`,
+        fixed: false,
+    };
+}
+/**
+ * Validate existing README content.
+ */
+async function validateExistingReadme(ctx) {
+    const errors = [];
+    let wasFixed = false;
+    // Check title matches package name
+    if (ctx.requireMatchingTitle) {
+        const titleResult = validateTitle(ctx.readmeContent, ctx.packageName);
+        if (titleResult !== true) {
+            errors.push(titleResult);
+        }
+    }
+    // Check required content
+    if (ctx.requiredContent) {
+        const contentResult = await handleRequiredContent(ctx.readmePath, ctx.readmeContent, ctx.requiredContent, ctx.resolve);
+        if (contentResult.error) {
+            errors.push(contentResult.error);
+        }
+        if (contentResult.fixed) {
+            wasFixed = true;
+        }
+    }
+    if (errors.length === 0) {
+        return true;
+    }
+    if (wasFixed) {
+        return {
+            name: "PackageReadme",
+            file: ctx.file,
+            resolved: true,
+            autoFixable: true,
+            errorMessages: [errors.join("; ")],
+        };
+    }
+    return {
+        name: "PackageReadme",
+        file: ctx.file,
+        autoFixable: ctx.requiredContent !== undefined &&
+            !ctx.readmeContent.includes(ctx.requiredContent),
+        errorMessages: [errors.join("; ")],
+    };
+}
+/**
+ * A repo policy that ensures each package has a README.md file with proper content.
+ *
+ * @remarks
+ *
+ * This policy validates that packages have documentation and can enforce:
+ * 1. README.md file exists
+ * 2. README title matches the package name
+ * 3. README contains required content (e.g., trademark notices)
+ *
+ * The policy supports auto-fixing by creating a basic README with the package name as title.
+ *
+ * @example
+ * ```typescript
+ * import { makePolicy } from "repopo";
+ * import { PackageReadme } from "repopo/policies";
+ *
+ * const config: RepopoConfig = {
+ *   policies: [
+ *     // Basic README validation
+ *     makePolicy(PackageReadme),
+ *
+ *     // Require trademark notice in all READMEs
+ *     makePolicy(PackageReadme, {
+ *       requiredContent: "## Trademark",
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @alpha
+ */
+export const PackageReadme = definePackagePolicy("PackageReadme", async (json, { file, resolve, config }) => {
+    const skipPrivate = config?.skipPrivate ?? true;
+    const requireMatchingTitle = config?.requireMatchingTitle ?? true;
+    const requiredContent = config?.requiredContent;
+    // Skip private packages if configured to do so
+    if (skipPrivate && json.private === true) {
+        return true;
+    }
+    const packageName = json.name ?? "unknown";
+    const packageDir = path.dirname(file);
+    const readmePath = path.join(packageDir, "README.md");
+    // Check if README exists
+    if (!existsSync(readmePath)) {
+        return await handleMissingReadme(readmePath, packageName, file, resolve, requiredContent);
+    }
+    // README exists, validate content
+    const readmeContent = await readFile(readmePath, "utf-8");
+    return await validateExistingReadme({
+        readmePath,
+        readmeContent,
+        packageName,
+        file,
+        resolve,
+        requireMatchingTitle,
+        requiredContent,
+    });
+});
+//# sourceMappingURL=PackageReadme.js.map

package/esm/policies/PackageReadme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackageReadme.js","sourceRoot":"","sources":["../../src/policies/PackageReadme.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from \"node:fs\";\nimport { readFile, writeFile } from \"node:fs/promises\";\nimport path from \"pathe\";\nimport type { PackageJson } from \"type-fest\";\nimport type { PolicyFailure, PolicyFixResult } from \"../policy.js\";\nimport { definePackagePolicy } from \"../policyDefiners/definePackagePolicy.js\";\n\n// Pre-compiled regex for performance\nconst LINE_SPLIT_REGEX = /\\r?\\n/;\nconst HEADING_REGEX = /^#\\s+(.+)$/;\n\n/**\n * Policy settings for the PackageReadme repo policy.\n *\n * @alpha\n */\nexport interface PackageReadmeSettings {\n\t/**\n\t * Whether to skip validation for private packages.\n\t *\n\t * @defaultValue true\n\t *\n\t * @remarks\n\t *\n\t * Private packages are typically not published and may not need a README file.\n\t * Set to `false` to require README files for all packages.\n\t */\n\tskipPrivate?: boolean;\n\n\t/**\n\t * Whether to require the README title to match the package name.\n\t *\n\t * @defaultValue true\n\t *\n\t * @remarks\n\t *\n\t * When enabled, the first line of the README must be `# package-name`.\n\t * This ensures consistency and helps users identify the package.\n\t */\n\trequireMatchingTitle?: boolean;\n\n\t/**\n\t * A string that must appear in the README content.\n\t *\n\t * @remarks\n\t *\n\t * Useful for ensuring all READMEs include required content like trademark\n\t * notices, disclaimers, or standard documentation sections.\n\t *\n\t * @example\n\t * ```typescript\n\t * requiredContent: \"## Trademark\"\n\t * ```\n\t */\n\trequiredContent?: string;\n}\n\n/**\n * Extract the title from a README file (first markdown H1 heading).\n *\n * @param content - The README content\n * @returns The title text (without the `# ` prefix) or `undefined` if not found\n */\nfunction extractReadmeTitle(content: string): string | undefined {\n\tconst lines = content.split(LINE_SPLIT_REGEX);\n\tfor (const line of lines) {\n\t\tconst match = HEADING_REGEX.exec(line);\n\t\tif (match?.[1]) {\n\t\t\treturn match[1].trim();\n\t\t}\n\t}\n\treturn undefined;\n}\n\n/**\n * Create a basic README content with package name as title.\n */\nfunction createReadmeContent(\n\tpackageName: string,\n\trequiredContent?: string,\n): string {\n\tlet content = `# ${packageName}\\n`;\n\tif (requiredContent) {\n\t\tcontent += `\\n${requiredContent}\\n`;\n\t}\n\treturn content;\n}\n\n/**\n * Handle case when README is missing.\n */\nasync function handleMissingReadme(\n\treadmePath: string,\n\tpackageName: string,\n\tfile: string,\n\tresolve: boolean,\n\trequiredContent?: string,\n): Promise<PolicyFailure | PolicyFixResult> {\n\tif (resolve) {\n\t\ttry {\n\t\t\tawait writeFile(\n\t\t\t\treadmePath,\n\t\t\t\tcreateReadmeContent(packageName, requiredContent),\n\t\t\t);\n\t\t\treturn {\n\t\t\t\tname: \"PackageReadme\",\n\t\t\t\tfile,\n\t\t\t\tresolved: true,\n\t\t\t\tautoFixable: true,\n\t\t\t\terrorMessages: [`Created README.md for package \"${packageName}\"`],\n\t\t\t};\n\t\t} catch {\n\t\t\treturn {\n\t\t\t\tname: \"PackageReadme\",\n\t\t\t\tfile,\n\t\t\t\tresolved: false,\n\t\t\t\tautoFixable: true,\n\t\t\t\terrorMessages: [\n\t\t\t\t\t`Failed to create README.md for package \"${packageName}\"`,\n\t\t\t\t],\n\t\t\t};\n\t\t}\n\t}\n\n\treturn {\n\t\tname: \"PackageReadme\",\n\t\tfile,\n\t\tautoFixable: true,\n\t\terrorMessages: [`README.md missing for package \"${packageName}\"`],\n\t};\n}\n\n/**\n * Validate README title against package name.\n *\n * @returns `true` if valid, or an error message string if invalid\n */\nfunction validateTitle(\n\treadmeContent: string,\n\tpackageName: string,\n): true | string {\n\tconst title = extractReadmeTitle(readmeContent);\n\tif (title !== packageName) {\n\t\treturn `README title \"${title ?? \"(none)\"}\" doesn't match package name \"${packageName}\"`;\n\t}\n\treturn true;\n}\n\n/**\n * Handle required content validation and auto-fix.\n */\nasync function handleRequiredContent(\n\treadmePath: string,\n\treadmeContent: string,\n\trequiredContent: string,\n\tresolve: boolean,\n): Promise<{ error?: string; fixed: boolean }> {\n\tif (readmeContent.includes(requiredContent)) {\n\t\treturn { fixed: false };\n\t}\n\n\tif (resolve) {\n\t\ttry {\n\t\t\tconst newContent = readmeContent.endsWith(\"\\n\")\n\t\t\t\t? `${readmeContent}${requiredContent}\\n`\n\t\t\t\t: `${readmeContent}\\n${requiredContent}\\n`;\n\t\t\tawait writeFile(readmePath, newContent);\n\t\t\treturn {\n\t\t\t\terror: `README missing required content: \"${requiredContent}\"`,\n\t\t\t\tfixed: true,\n\t\t\t};\n\t\t} catch {\n\t\t\t// Fall through to report error\n\t\t}\n\t}\n\n\treturn {\n\t\terror: `README missing required content: \"${requiredContent}\"`,\n\t\tfixed: false,\n\t};\n}\n\ninterface ValidationContext {\n\treadmePath: string;\n\treadmeContent: string;\n\tpackageName: string;\n\tfile: string;\n\tresolve: boolean;\n\trequireMatchingTitle: boolean;\n\trequiredContent: string | undefined;\n}\n\n/**\n * Validate existing README content.\n */\nasync function validateExistingReadme(\n\tctx: ValidationContext,\n): Promise<true | PolicyFailure | PolicyFixResult> {\n\tconst errors: string[] = [];\n\tlet wasFixed = false;\n\n\t// Check title matches package name\n\tif (ctx.requireMatchingTitle) {\n\t\tconst titleResult = validateTitle(ctx.readmeContent, ctx.packageName);\n\t\tif (titleResult !== true) {\n\t\t\terrors.push(titleResult);\n\t\t}\n\t}\n\n\t// Check required content\n\tif (ctx.requiredContent) {\n\t\tconst contentResult = await handleRequiredContent(\n\t\t\tctx.readmePath,\n\t\t\tctx.readmeContent,\n\t\t\tctx.requiredContent,\n\t\t\tctx.resolve,\n\t\t);\n\t\tif (contentResult.error) {\n\t\t\terrors.push(contentResult.error);\n\t\t}\n\t\tif (contentResult.fixed) {\n\t\t\twasFixed = true;\n\t\t}\n\t}\n\n\tif (errors.length === 0) {\n\t\treturn true;\n\t}\n\n\tif (wasFixed) {\n\t\treturn {\n\t\t\tname: \"PackageReadme\",\n\t\t\tfile: ctx.file,\n\t\t\tresolved: true,\n\t\t\tautoFixable: true,\n\t\t\terrorMessages: [errors.join(\"; \")],\n\t\t};\n\t}\n\n\treturn {\n\t\tname: \"PackageReadme\",\n\t\tfile: ctx.file,\n\t\tautoFixable:\n\t\t\tctx.requiredContent !== undefined &&\n\t\t\t!ctx.readmeContent.includes(ctx.requiredContent),\n\t\terrorMessages: [errors.join(\"; \")],\n\t};\n}\n\n/**\n * A repo policy that ensures each package has a README.md file with proper content.\n *\n * @remarks\n *\n * This policy validates that packages have documentation and can enforce:\n * 1. README.md file exists\n * 2. README title matches the package name\n * 3. README contains required content (e.g., trademark notices)\n *\n * The policy supports auto-fixing by creating a basic README with the package name as title.\n *\n * @example\n * ```typescript\n * import { makePolicy } from \"repopo\";\n * import { PackageReadme } from \"repopo/policies\";\n *\n * const config: RepopoConfig = {\n *   policies: [\n *     // Basic README validation\n *     makePolicy(PackageReadme),\n *\n *     // Require trademark notice in all READMEs\n *     makePolicy(PackageReadme, {\n *       requiredContent: \"## Trademark\",\n *     }),\n *   ],\n * };\n * ```\n *\n * @alpha\n */\nexport const PackageReadme = definePackagePolicy<\n\tPackageJson,\n\tPackageReadmeSettings | undefined\n>(\"PackageReadme\", async (json, { file, resolve, config }) => {\n\tconst skipPrivate = config?.skipPrivate ?? true;\n\tconst requireMatchingTitle = config?.requireMatchingTitle ?? true;\n\tconst requiredContent = config?.requiredContent;\n\n\t// Skip private packages if configured to do so\n\tif (skipPrivate && json.private === true) {\n\t\treturn true;\n\t}\n\n\tconst packageName = json.name ?? \"unknown\";\n\tconst packageDir = path.dirname(file);\n\tconst readmePath = path.join(packageDir, \"README.md\");\n\n\t// Check if README exists\n\tif (!existsSync(readmePath)) {\n\t\treturn await handleMissingReadme(\n\t\t\treadmePath,\n\t\t\tpackageName,\n\t\t\tfile,\n\t\t\tresolve,\n\t\t\trequiredContent,\n\t\t);\n\t}\n\n\t// README exists, validate content\n\tconst readmeContent = await readFile(readmePath, \"utf-8\");\n\treturn await validateExistingReadme({\n\t\treadmePath,\n\t\treadmeContent,\n\t\tpackageName,\n\t\tfile,\n\t\tresolve,\n\t\trequireMatchingTitle,\n\t\trequiredContent,\n\t});\n});\n"]}