pastoralist 1.7.2 → 1.7.4

package/README.md

@@ -294,6 +294,171 @@ For detailed information about using Pastoralist in workspace/monorepo environme
 
 ---
 
+## Configuration
+
+Pastoralist supports multiple configuration methods to fit your project's needs. Configuration can be defined in external files or directly in your `package.json`.
+
+### Configuration Files
+
+Pastoralist searches for configuration files in this order (first found wins):
+
+1. `.pastoralistrc` (JSON format)
+2. `.pastoralistrc.json`
+3. `pastoralist.json`
+4. `pastoralist.config.js`
+5. `pastoralist.config.ts`
+
+**Example `.pastoralistrc.json`:**
+
+```json
+{
+  "checkSecurity": true,
+  "depPaths": "workspaces",
+  "security": {
+    "provider": "osv",
+    "severityThreshold": "medium"
+  }
+}
+```
+
+**Example `pastoralist.config.js`:**
+
+```js
+module.exports = {
+  checkSecurity: true,
+  depPaths: ["packages/*/package.json", "apps/*/package.json"],
+  security: {
+    provider: "osv",
+    severityThreshold: "high",
+    excludePackages: ["@types/*"]
+  }
+};
+```
+
+**Example `pastoralist.config.ts`:**
+
+```ts
+import { PastoralistConfig } from 'pastoralist';
+
+const config: PastoralistConfig = {
+  checkSecurity: true,
+  depPaths: "workspaces",
+  security: {
+    provider: "osv",
+    severityThreshold: "critical"
+  }
+};
+
+export default config;
+```
+
+### Configuration Priority
+
+When both external config files and `package.json` configuration exist:
+
+1. **External config** provides base settings
+2. **`package.json`** overrides top-level fields
+3. **Nested objects** (like `security`) are deep merged
+
+**Example:**
+
+```js
+// .pastoralistrc.json
+{
+  "checkSecurity": true,
+  "depPaths": "workspaces",
+  "security": {
+    "provider": "osv",
+    "severityThreshold": "medium"
+  }
+}
+
+// package.json
+{
+  "pastoralist": {
+    "security": {
+      "severityThreshold": "high"  // Overrides "medium" from .pastoralistrc.json
+    }
+  }
+}
+
+// Effective config:
+{
+  "checkSecurity": true,
+  "depPaths": "workspaces",
+  "security": {
+    "provider": "osv",
+    "severityThreshold": "high"  // From package.json
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `checkSecurity` | `boolean` | Enable security vulnerability scanning |
+| `depPaths` | `"workspace"` \| `"workspaces"` \| `string[]` | Paths to scan for dependencies in monorepos |
+| `appendix` | `object` | Auto-generated dependency tracking (managed by Pastoralist) |
+| `overridePaths` | `object` | Manual override tracking for specific paths |
+| `resolutionPaths` | `object` | Manual resolution tracking for specific paths |
+| `security` | `object` | Security scanning configuration (see below) |
+
+#### Security Configuration
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled` | `boolean` | Enable/disable security checks |
+| `provider` | `"osv"` \| `"github"` \| `"snyk"` \| `"npm"` \| `"socket"` | Security provider (currently only OSV) |
+| `autoFix` | `boolean` | Automatically apply security fixes |
+| `interactive` | `boolean` | Use interactive mode for security fixes |
+| `securityProviderToken` | `string` | API token for providers that require auth |
+| `severityThreshold` | `"low"` \| `"medium"` \| `"high"` \| `"critical"` | Minimum severity level to report |
+| `excludePackages` | `string[]` | Packages to exclude from security checks |
+| `hasWorkspaceSecurityChecks` | `boolean` | Include workspace packages in scans |
+
+### Security Tracking in Appendix
+
+When security vulnerabilities are detected and fixed, Pastoralist tracks this information in the appendix ledger:
+
+```js
+"pastoralist": {
+  "appendix": {
+    "lodash@4.17.21": {
+      "dependents": {
+        "my-app": "lodash@^4.17.0"
+      },
+      "ledger": {
+        "addedDate": "2024-01-15T10:30:00.000Z",
+        "reason": "Security vulnerability CVE-2021-23337",
+        "securityChecked": true,
+        "securityCheckDate": "2024-01-15T10:30:00.000Z",
+        "securityProvider": "osv"
+      }
+    }
+  }
+}
+```
+
+The ledger tracks:
+- `addedDate`: When the override was first added
+- `reason`: Why the override was needed (e.g., security issue description)
+- `securityChecked`: Whether a security check was performed
+- `securityCheckDate`: When the last security check occurred
+- `securityProvider`: Which provider detected the vulnerability
+
+This allows you to see at a glance which packages were overridden due to security issues and when they were last verified.
+
+### Best Practices
+
+1. **Use external config files** for shared settings across teams
+2. **Use `package.json`** for project-specific overrides
+3. **Commit config files** to version control
+4. **Use `depPaths: "workspaces"`** for most monorepos
+5. **Enable security checks** in CI/CD pipelines with `--checkSecurity`
+
+---
+
 ## Setup
 
 > #### Okay! Hopefully the breakdowns above were clear enough on why you might want to use Pastoralist!

package/dist/config/constants.d.ts

@@ -0,0 +1 @@
+export declare const CONFIG_FILES: readonly [".pastoralistrc", ".pastoralistrc.json", "pastoralist.json", "pastoralist.config.js", "pastoralist.config.ts"];

package/dist/config/index.d.ts

@@ -0,0 +1,158 @@
+import { z } from "zod";
+export declare const AppendixItemSchema: z.ZodObject<{
+    rootDeps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dependents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    patches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ledger: z.ZodOptional<z.ZodObject<{
+        addedDate: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+        securityChecked: z.ZodOptional<z.ZodBoolean>;
+        securityCheckDate: z.ZodOptional<z.ZodString>;
+        securityProvider: z.ZodOptional<z.ZodEnum<{
+            npm: "npm";
+            osv: "osv";
+            github: "github";
+            snyk: "snyk";
+            socket: "socket";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const AppendixSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    rootDeps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dependents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    patches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ledger: z.ZodOptional<z.ZodObject<{
+        addedDate: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+        securityChecked: z.ZodOptional<z.ZodBoolean>;
+        securityCheckDate: z.ZodOptional<z.ZodString>;
+        securityProvider: z.ZodOptional<z.ZodEnum<{
+            npm: "npm";
+            osv: "osv";
+            github: "github";
+            snyk: "snyk";
+            socket: "socket";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare const SecurityProviderSchema: z.ZodEnum<{
+    npm: "npm";
+    osv: "osv";
+    github: "github";
+    snyk: "snyk";
+    socket: "socket";
+}>;
+export declare const SeverityThresholdSchema: z.ZodEnum<{
+    high: "high";
+    medium: "medium";
+    low: "low";
+    critical: "critical";
+}>;
+export declare const SecurityConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodOptional<z.ZodEnum<{
+        npm: "npm";
+        osv: "osv";
+        github: "github";
+        snyk: "snyk";
+        socket: "socket";
+    }>>;
+    autoFix: z.ZodOptional<z.ZodBoolean>;
+    interactive: z.ZodOptional<z.ZodBoolean>;
+    securityProviderToken: z.ZodOptional<z.ZodString>;
+    severityThreshold: z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+        critical: "critical";
+    }>>;
+    excludePackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hasWorkspaceSecurityChecks: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const PastoralistConfigSchema: z.ZodObject<{
+    appendix: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        rootDeps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        dependents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        patches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ledger: z.ZodOptional<z.ZodObject<{
+            addedDate: z.ZodString;
+            reason: z.ZodOptional<z.ZodString>;
+            securityChecked: z.ZodOptional<z.ZodBoolean>;
+            securityCheckDate: z.ZodOptional<z.ZodString>;
+            securityProvider: z.ZodOptional<z.ZodEnum<{
+                npm: "npm";
+                osv: "osv";
+                github: "github";
+                snyk: "snyk";
+                socket: "socket";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    depPaths: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"workspace">, z.ZodLiteral<"workspaces">, z.ZodArray<z.ZodString>]>>;
+    checkSecurity: z.ZodOptional<z.ZodBoolean>;
+    overridePaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+        rootDeps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        dependents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        patches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ledger: z.ZodOptional<z.ZodObject<{
+            addedDate: z.ZodString;
+            reason: z.ZodOptional<z.ZodString>;
+            securityChecked: z.ZodOptional<z.ZodBoolean>;
+            securityCheckDate: z.ZodOptional<z.ZodString>;
+            securityProvider: z.ZodOptional<z.ZodEnum<{
+                npm: "npm";
+                osv: "osv";
+                github: "github";
+                snyk: "snyk";
+                socket: "socket";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>>;
+    resolutionPaths: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+        rootDeps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        dependents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        patches: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ledger: z.ZodOptional<z.ZodObject<{
+            addedDate: z.ZodString;
+            reason: z.ZodOptional<z.ZodString>;
+            securityChecked: z.ZodOptional<z.ZodBoolean>;
+            securityCheckDate: z.ZodOptional<z.ZodString>;
+            securityProvider: z.ZodOptional<z.ZodEnum<{
+                npm: "npm";
+                osv: "osv";
+                github: "github";
+                snyk: "snyk";
+                socket: "socket";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>>;
+    security: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        provider: z.ZodOptional<z.ZodEnum<{
+            npm: "npm";
+            osv: "osv";
+            github: "github";
+            snyk: "snyk";
+            socket: "socket";
+        }>>;
+        autoFix: z.ZodOptional<z.ZodBoolean>;
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        securityProviderToken: z.ZodOptional<z.ZodString>;
+        severityThreshold: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+            critical: "critical";
+        }>>;
+        excludePackages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        hasWorkspaceSecurityChecks: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AppendixItem = z.infer<typeof AppendixItemSchema>;
+export type Appendix = z.infer<typeof AppendixSchema>;
+export type SecurityProvider = z.infer<typeof SecurityProviderSchema>;
+export type SeverityThreshold = z.infer<typeof SeverityThresholdSchema>;
+export type SecurityConfig = z.infer<typeof SecurityConfigSchema>;
+export type PastoralistConfig = z.infer<typeof PastoralistConfigSchema>;
+export declare function validateConfig(config: unknown): PastoralistConfig;
+export declare function safeValidateConfig(config: unknown): PastoralistConfig | undefined;

package/dist/config/loader.d.ts

@@ -0,0 +1,4 @@
+import { PastoralistConfig } from "./index";
+export declare const loadExternalConfig: (root?: string, validate?: boolean) => Promise<PastoralistConfig | undefined>;
+export declare const mergeConfigs: (externalConfig: PastoralistConfig | undefined, packageJsonConfig: PastoralistConfig | undefined) => PastoralistConfig | undefined;
+export declare const loadConfig: (root?: string, packageJsonConfig?: PastoralistConfig, validate?: boolean) => Promise<PastoralistConfig | undefined>;