load-populate-files 1.0.3 → 1.1.0

package/README.md

@@ -8,13 +8,15 @@ Load and dynamically populate file content based on a single file's config.
 
 </div>
 
+Guides and the full reference are on the [docs site](https://jacobley.github.io/leyman/populate-files/guides/config-modules).
+
 ## Contents
 
 - [Install](#install)
 - [Example](#example)
 - [Usage](#usage)
 - [API](#api)
-  - [loadAndPopulateFiles](#loadandpopulatefilesfilepath-options)
+  - [loadAndPopulateFiles](#loadandpopulatefilesparams-options)
 - [Types](#types)
   - [PopulateFileParams](#populatefileparams)
 - [Also See](#also-see)
@@ -45,7 +47,7 @@ export default [
 // index.ts
 import { loadAndPopulateFiles } from 'load-populate-files';
 
-await loadAndPopulateFiles('./config.js');
+await loadAndPopulateFiles({ filePath: './config.js' });
 ```
 
 ## Usage
@@ -63,18 +65,18 @@ pnpx load-populate-files --file-path ./config.js
 
 ## API
 
-### `loadAndPopulateFiles(filePath, options?)`
+### `loadAndPopulateFiles(params, options?)`
 
-Loads the config exported at `filePath` and passes it to [`populateFiles()`](https://www.npmjs.com/package/populate-files#populatefilesparams-options).
+Loads the config exported at `params.filePath` and passes it to [`populateFiles()`](https://www.npmjs.com/package/populate-files#populatefilesparams-options).
 
 **Parameters**
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `filePath` | `string` | — | Required. Path to the config module. When using the CLI, pass as `--file-path`. |
+| `params.filePath` | `string` | — | Required. Path to the config module, resolved from `options.cwd`. When using the CLI, pass as `--file-path`. |
 | `options` | `object` | `{}` | Optional. See [options](#options) below. |
 
-**Returns** `Promise<void>`
+**Returns** `Promise<PopulationResponse[]>`, from `populateFiles()`.
 
 #### `options`
 
@@ -86,7 +88,9 @@ Options are passed through to the underlying `populateFiles()` call. They are al
 | `dryRun` | `--dry-run` | `boolean` | `false` | If `true`, does not write any files regardless of changes. Can still fail if `check` is `true`. |
 | `cwd` | `--cwd` | `string \| URL` | `process.env.PWD` | Used as the current working directory for `filePath` and re-used for relative `filePath`s in the loaded config. |
 | `targetDir` | `--target-dir`, `-t` | `string` | `'.'` | Target directory for resolving output file paths. Resolved relative to `cwd`. |
-| `clean` | `--clean` | `boolean` | `false` | If `true`, removes files in `targetDir` that were not generated. In `--ci` mode, fails instead of removing. |
+| `clean` | `--clean` | `boolean` | `false` | If `true`, removes files in `targetDir` that were not generated (with `manifest`, only files it lists). In `--ci` mode, fails instead of removing. |
+| `force` | `--force` | `boolean` | `false` | Applies to `signed` files and the `manifest`. If `true`, overwrites files that were edited, are not signed or not listed, or are malformed. See [`populate-files`](https://www.npmjs.com/package/populate-files#signed-files). |
+| `manifest` | `--manifest` | `string` | — | Path of a manifest (relative to `cwd`) recording the generated files, to detect edits to any file type and `clean` only files it lists. See [`populate-files`](https://www.npmjs.com/package/populate-files#manifest). |
 
 ## Types
 
@@ -105,6 +109,8 @@ export default {
 
 This type can also be imported directly from [`populate-files`](https://www.npmjs.com/package/populate-files).
 
+Configs may set `signed: true` (with string content) to sign the file and keep its manual sections, see [signed files](https://www.npmjs.com/package/populate-files#signed-files).
+
 ## Also See
 
 - [`populate-files`](https://www.npmjs.com/package/populate-files) — the underlying package that writes files; use directly when you don't need a separate config file

package/dist/commands/load-populate-files-command.d.ts

@@ -4,6 +4,8 @@ interface LoadPopulateFilesCommandExtendedInput extends LoadPopulateFilesCommand
     ci: boolean;
     dryRun: boolean;
     clean: boolean;
+    force: boolean;
+    manifest: string | undefined;
 }
 /**
  * Main `load-populate-files` command

package/dist/commands/load-populate-files-command.js

@@ -29,6 +29,15 @@ export const loadPopulateFilesCommand = {
                 describe: 'Remove files in --target-dir that were not generated. In --ci mode, fail instead of removing.',
                 type: 'boolean',
                 default: false
+            },
+            force: {
+                describe: 'Overwrite signed files even if they were edited, are not signed, or would lose manual sections',
+                type: 'boolean',
+                default: false
+            },
+            manifest: {
+                describe: 'Record generated files in this manifest (relative to --cwd), to detect edits to them and only --clean files it lists',
+                type: 'string'
             }
         }).strict(),
     handler: async (options)=>{
@@ -39,7 +48,9 @@ export const loadPopulateFilesCommand = {
             targetDir: options.targetDir,
             check: options.ci,
             dryRun: options.dryRun,
-            clean: options.clean
+            clean: options.clean,
+            force: options.force,
+            manifest: options.manifest
         });
     }
 };

package/dist/lib/lib/populate-files-validator.d.ts

@@ -1,8 +1,3 @@
-export declare const isPopulateFileParams: (x: unknown) => x is {
-    filePath: string;
-    content: (Promise<import("populate-files").FileContent> | import("populate-files").FileContent | undefined) & (Promise<import("populate-files").FileContent> | import("populate-files").FileContent);
-}[] | {
-    filePath: string;
-    content: (Promise<import("populate-files").FileContent> | import("populate-files").FileContent | undefined) & (Promise<import("populate-files").FileContent> | import("populate-files").FileContent);
-};
+import type { PopulateFileParams } from 'populate-files';
+export declare const isPopulateFileParams: (x: unknown) => x is PopulateFileParams[] | PopulateFileParams;
 //# sourceMappingURL=populate-files-validator.d.ts.map

package/dist/lib/lib/populate-files-validator.js

@@ -1,15 +1,16 @@
-import { arraySchema, mergeSchema, objectSchema, stringSchema } from 'juniper';
+import { arraySchema, booleanSchema, mergeSchema, objectSchema, stringSchema } from 'juniper';
 import { makeValidator } from 'juniper-validator';
 const populateFileParam = objectSchema({
     properties: {
         filePath: stringSchema(),
-        content: mergeSchema().cast()
+        content: mergeSchema().cast(),
+        signed: booleanSchema()
     },
     required: [
         'filePath',
         'content'
     ]
-});
+}).cast();
 const populateFileParams = mergeSchema().oneOf([
     populateFileParam,
     arraySchema({

package/dist/lib/normalize.js

@@ -9,7 +9,9 @@ export const normalizeParams = async (params, options = {})=>{
             check: options.check,
             dryRun: options.dryRun,
             targetDir: options.targetDir,
-            clean: options.clean
+            clean: options.clean,
+            force: options.force,
+            manifest: options.manifest
         }
     };
 };

package/dist/lib/types.d.ts

@@ -8,6 +8,8 @@ export interface RawOptions {
     check?: boolean | null | undefined;
     dryRun?: boolean | null | undefined;
     clean?: boolean | null | undefined;
+    force?: boolean | null | undefined;
+    manifest?: string | null | undefined;
 }
 export interface NormalizedParams {
     filePath: string;
@@ -17,6 +19,8 @@ export interface NormalizedParams {
         check?: boolean | null | undefined;
         dryRun?: boolean | null | undefined;
         clean?: boolean | null | undefined;
+        force?: boolean | null | undefined;
+        manifest?: string | null | undefined;
     };
 }
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "load-populate-files",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Load and dynamically populate file content",
   "engines": {
     "node": ">=24"
@@ -42,10 +42,10 @@
     "entry-script": "^4.1.0",
     "haywire": "^2.0.0",
     "haywire-launcher": "^1.0.2",
-    "juniper": "^2.2.1",
+    "juniper": "^2.3.0",
     "juniper-validator": "^0.3.0",
     "parse-cwd": "^2.0.2",
-    "populate-files": "^1.0.2",
+    "populate-files": "^1.1.0",
     "unknown-error": "^0.1.0",
     "yargs": "^18.2.0"
   },
@@ -61,8 +61,10 @@
     "@typescript/native": "npm:typescript@^7.0.2",
     "c8": "^12.0.0",
     "eslint": "^10.12.0",
+    "generated-signature": "^0.1.0",
     "mocha": "^12.0.2",
     "mocha-chain": "^1.0.1",
+    "tmp-promise": "^3.0.3",
     "typescript": "npm:@typescript/typescript6@^6.0.2"
   },
   "imports": {