0
# Patch Creation
1

2
Core functionality for creating patch files from modified node_modules. The patch creation system generates git-style diff patches, handles file filtering, manages patch sequences, and integrates with GitHub issue creation workflows.
3

4
## Capabilities
5

6
### Main Patch Creation Function
7

8
Creates patch files based on package modifications in node_modules.
9

10
```typescript { .api }
11
/**
12
 * Create patch files based on package modifications
13
 * @param options - Configuration for patch creation
14
 */
15
function makePatch(options: MakePatchOptions): void;
16

17
interface MakePatchOptions {
18
  /** Package identifier (e.g., "lodash", "@types/node") */
19
  packagePathSpecifier: string;
20
  /** Application root path */
21
  appPath: string;
22
  /** Package manager type */
23
  packageManager: PackageManager;
24
  /** Files to include (regexp pattern) */
25
  includePaths: RegExp;
26
  /** Files to exclude (regexp pattern) */
27
  excludePaths: RegExp;
28
  /** Output directory for patches */
29
  patchDir: string;
30
  /** Open GitHub issue creation link */
31
  createIssue: boolean;
32
  /** Patch creation mode */
33
  mode: PatchMode;
34
}
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { makePatch } from "patch-package/dist/makePatch";
41
import { detectPackageManager } from "patch-package/dist/detectPackageManager";
42

43
// Basic patch creation
44
makePatch({
45
  packagePathSpecifier: "lodash",
46
  appPath: process.cwd(),
47
  packageManager: detectPackageManager(process.cwd(), null),
48
  includePaths: /.*/,
49
  excludePaths: /^package\.json$/,
50
  patchDir: "patches",
51
  createIssue: false,
52
  mode: { type: "overwrite_last" }
53
});
54

55
// Create patch with custom filtering
56
makePatch({
57
  packagePathSpecifier: "react",
58
  appPath: "/path/to/app",
59
  packageManager: "yarn",
60
  includePaths: /src\/.*\.js$/,
61
  excludePaths: /(test|spec)\/.*$/,
62
  patchDir: "custom-patches",
63
  createIssue: true,
64
  mode: { type: "append", name: "performance-fix" }
65
});
66
```
67

68
### Patch Creation Modes
69

70
Controls how new patches are handled relative to existing patches.
71

72
```typescript { .api }
73
type PatchMode = 
74
  | { type: "overwrite_last" }
75
  | { type: "append", name?: string };
76
```
77

78
- **Overwrite Mode**: Replaces the most recent patch for the package
79
- **Append Mode**: Adds a new patch to the sequence, optionally with a descriptive name
80

81
### Error Handling
82

83
Specialized error handling for patch sequence failures.
84

85
```typescript { .api }
86
/**
87
 * Log error messages for patch sequence failures
88
 * @param patchDetails - Details of the failed patch
89
 */
90
function logPatchSequenceError(patchDetails: PatchedPackageDetails): void;
91
```
92

93
## Package Details Integration
94

95
### Package Resolution
96

97
The patch creation system integrates with package resolution to identify target packages.
98

99
```typescript { .api }
100
/**
101
 * Parse package details from CLI string
102
 * @param specifier - Package specifier string
103
 * @returns Package details or null if invalid
104
 */
105
function getPatchDetailsFromCliString(specifier: string): PackageDetails | null;
106

107
/**
108
 * Parse package name and version from string
109
 * @param str - String containing package info
110
 * @returns Parsed name and version info
111
 */
112
function parseNameAndVersion(str: string): ParsedNameVersion | null;
113

114
interface ParsedNameVersion {
115
  packageName: string;
116
  version: string;
117
  sequenceName?: string;
118
  sequenceNumber?: number;
119
}
120
```
121

122
### File Filtering
123

124
Advanced file filtering for precise control over what gets included in patches.
125

126
```typescript { .api }
127
/**
128
 * Remove files matching exclude patterns from directory
129
 * @param dir - Directory to filter
130
 * @param includePaths - RegExp for files to include
131
 * @param excludePaths - RegExp for files to exclude
132
 */
133
function removeIgnoredFiles(
134
  dir: string, 
135
  includePaths: RegExp, 
136
  excludePaths: RegExp
137
): void;
138

139
/**
140
 * Create RegExp with error handling and validation
141
 * @param reString - Regular expression string
142
 * @param name - Name for error reporting
143
 * @param defaultValue - Default regex if parsing fails
144
 * @param caseSensitive - Case sensitivity flag
145
 * @returns Compiled regular expression
146
 */
147
function makeRegExp(
148
  reString: string, 
149
  name: string, 
150
  defaultValue: RegExp, 
151
  caseSensitive: boolean
152
): RegExp;
153
```
154

155
**Filtering Examples:**
156

157
```typescript
158
// Include only TypeScript files
159
const includePaths = makeRegExp(
160
  ".*\\.ts$", 
161
  "include", 
162
  /.*/, 
163
  false
164
);
165

166
// Exclude test and build directories
167
const excludePaths = makeRegExp(
168
  "(test|build|dist)/.*", 
169
  "exclude", 
170
  /^package\.json$/, 
171
  false
172
);
173

174
makePatch({
175
  packagePathSpecifier: "my-package",
176
  appPath: process.cwd(),
177
  packageManager: "npm",
178
  includePaths,
179
  excludePaths,
180
  patchDir: "patches",
181
  createIssue: false,
182
  mode: { type: "overwrite_last" }
183
});
184
```
185

186
## GitHub Integration
187

188
### Issue Creation
189

190
Automatic GitHub issue creation to encourage upstream contribution.
191

192
```typescript { .api }
193
/**
194
 * Extract VCS details from package
195
 * @param packageDetails - Package details
196
 * @returns VCS details or null if not available
197
 */
198
function getPackageVCSDetails(packageDetails: PackageDetails): VCSDetails | null;
199

200
interface VCSDetails {
201
  repo: string;
202
  org: string;
203
  provider: "GitHub";
204
}
205

206
/**
207
 * Determine if issue creation should be recommended
208
 * @param vcsDetails - Version control system details
209
 * @returns Whether to recommend issue creation
210
 */
211
function shouldRecommendIssue(vcsDetails: VCSDetails | null): boolean;
212

213
/**
214
 * Print issue creation prompt if appropriate
215
 * @param vcs - VCS details
216
 * @param packageDetails - Package details
217
 * @param packageManager - Package manager type
218
 */
219
function maybePrintIssueCreationPrompt(
220
  vcs: VCSDetails, 
221
  packageDetails: PackageDetails, 
222
  packageManager: PackageManager
223
): void;
224

225
/**
226
 * Open GitHub issue creation link in browser
227
 * @param options - Issue creation configuration
228
 */
229
function openIssueCreationLink(options: IssueCreationOptions): void;
230

231
interface IssueCreationOptions {
232
  packageDetails: PackageDetails;
233
  patchDetails: PatchedPackageDetails;
234
  vcsDetails: VCSDetails;
235
  packageManager: PackageManager;
236
}
237
```
238

239
## Advanced Features
240

241
### Development Dependency Detection
242

243
Automatically detects if a patched package is a development dependency to optimize patch application.
244

245
```typescript { .api }
246
/**
247
 * Check if package is development dependency
248
 * @param options - Development dependency check options
249
 * @returns True if package is dev dependency
250
 */
251
function packageIsDevDependency(options: DevDepOptions): boolean;
252

253
interface DevDepOptions {
254
  appPath: string;
255
  patchDetails: PatchedPackageDetails;
256
}
257
```
258

259
### File Hashing
260

261
Content hashing for patch validation and integrity checking.
262

263
```typescript { .api }
264
/**
265
 * Generate SHA-256 hash of file content
266
 * @param filePath - Path to file to hash
267
 * @returns SHA-256 hash string
268
 */
269
function hashFile(filePath: string): string;
270
```
271

272
### Cross-Platform Path Handling
273

274
Utilities for cross-platform path operations during patch creation.
275

276
```typescript { .api }
277
// Cross-platform path utilities
278
function join(...args: string[]): string;
279
function resolve(...args: string[]): string;
280
function relative(from: string, to: string): string;
281
function dirname(path: string): string;
282
```
283

284
## Patch Creation Workflow
285

286
The typical patch creation workflow involves:
287

288
1. **Package Detection**: Identify the target package in node_modules
289
2. **Change Detection**: Compare current state with original package
290
3. **File Filtering**: Apply include/exclude patterns
291
4. **Diff Generation**: Create git-style diff patches
292
5. **Sequence Management**: Handle patch ordering and naming
293
6. **Validation**: Verify patch integrity and completeness
294
7. **GitHub Integration**: Optionally prompt for upstream issue creation
295

296
**Complete Example:**
297

298
```typescript
299
import { makePatch } from "patch-package/dist/makePatch";
300
import { detectPackageManager } from "patch-package/dist/detectPackageManager";
301
import { makeRegExp } from "patch-package/dist/makeRegExp";
302

303
// Create patch with comprehensive configuration
304
const packageManager = detectPackageManager(process.cwd(), null);
305
const includePaths = makeRegExp("src/.*\\.(js|ts)$", "include", /.*/, false);
306
const excludePaths = makeRegExp("(test|spec)/.*", "exclude", /^package\.json$/, false);
307

308
makePatch({
309
  packagePathSpecifier: "problematic-package",
310
  appPath: process.cwd(),
311
  packageManager,
312
  includePaths,
313
  excludePaths,
314
  patchDir: "patches",
315
  createIssue: true,
316
  mode: { type: "append", name: "fix-memory-leak" }
317
});
318
```