appease 0.0.2 → 0.0.3

package/README.md

@@ -144,18 +144,21 @@ indent_style = tab
 
 ## Modes
 
-Every mode prints at the end **which files it created or modified**.
+Every command prints at the end **which files it created or modified**.
 
-| Mode | Reads | Writes | Destructive |
+Each command takes the directory to process as an optional positional argument
+(`appease <command> [dir]`; defaults to the current directory).
+
+| Command | Reads | Writes | Destructive |
 |---|---|---|---|
-| `--audit` | existing configs (or the defaults it would propose) + the files | nothing, only **reports** what is out of spec | no |
-| `--add-config-defaults` | — | the configs with **pure defaults** (without looking at reality) | no (only creates config) |
-| `--adapt-configs` | configs + audit | creates or **adapts** the configs to reflect what was found | does not touch source code |
-| `--fix-format` | configs | **modifies the files** (BOM, trailing, newline; EOL via Git) honoring the configs | yes (Git reverts) |
+| `audit` | existing configs (or the defaults it would propose) + the files | nothing, only **reports** what is out of spec | no |
+| `add-config-defaults` | — | the configs with **pure defaults** (without looking at reality) | no (only creates config) |
+| `adapt-configs` | configs + audit | creates or **adapts** the configs to reflect what was found | does not touch source code |
+| `fix-format` | configs | **modifies the files** (BOM, trailing, newline; EOL via Git) honoring the configs | yes (Git reverts) |
 
-### `--audit`: report format
+### `audit`: report format
 
-`--audit` prints canonical JSON with **two** lists. The key point is that conforming files
+`audit` prints canonical JSON with **two** lists. The key point is that conforming files
 **appear in neither**: only the ones that need attention and the ones that couldn't be
 evaluated are listed. A clean repo yields both lists empty:
 
@@ -176,16 +179,16 @@ evaluated are listed. A clean repo yields both lists empty:
 This format is **provisional**: today the output is the direct serialization of the
 `AuditResult` type, meant to be easy to parse and test. It may grow if the value justifies it.
 
-### `--adapt-configs`: records every deviation as an exception
+### `adapt-configs`: records every deviation as an exception
 
-`--adapt-configs` records **every** deviation it finds as an explicit exception, across all
+`adapt-configs` records **every** deviation it finds as an explicit exception, across all
 axes equally (without classifying or guessing intent). This gives a safety invariant: **right
-after `--adapt-configs`, a `--fix-format` changes nothing**, because the config describes
-reality 100%. Only when you **prune** (delete) exceptions does `--fix-format` touch *that and
+after `adapt-configs`, a `fix-format` changes nothing**, because the config describes
+reality 100%. Only when you **prune** (delete) exceptions does `fix-format` touch *that and
 only that*.
 
 So, "everything is wrong and I want to fix it all at once" is solved by deleting the block of
-exceptions: everything falls back to the default → `--fix-format` rewrites whatever is needed.
+exceptions: everything falls back to the default → `fix-format` rewrites whatever is needed.
 
 Behavior details:
 
@@ -206,13 +209,13 @@ by hand.
 
 ## Suggested workflow
 
-0. *(optional)* `--add-config-defaults` → **commit**. Versions the "north star" (the pure
+0. *(optional)* `add-config-defaults` → **commit**. Versions the "north star" (the pure
    norm), so that in step 1 deviations stand out in the diff against that norm.
-1. `--adapt-configs` → the `git diff` of the configs shows **every added exception = every
+1. `adapt-configs` → the `git diff` of the configs shows **every added exception = every
    deviation**. That diff is the real report.
 2. Review those exceptions: keep the ones that were on purpose, **delete** by hand the ones
    that were junk (if almost everything is wrong, delete the whole block).
-3. `--fix-format` → normalizes everything no longer protected by an exception.
+3. `fix-format` → normalizes everything no longer protected by an exception.
 
 Since Git reverts anything, the destructive steps are safe to try.
 
@@ -252,12 +255,12 @@ Strongly typed, `strict`, no `any`. Errors are handled, not ignored.
 
 ### `cli.ts`
 
-Maps the switches (`--audit`, `--add-config-defaults`, `--adapt-configs`, `--fix-format`) to
+Maps the commands (`audit`, `add-config-defaults`, `adapt-configs`, `fix-format`) to
 TS calls and orchestrates the effects:
 
 1. Discovers files (`git ls-files`), skips binaries and the ones marked `-text`.
 2. Reads `.gitattributes` and `.editorconfig` to resolve the per-file options.
-3. Depending on the mode: only reports, generates/adapts configs, or reads each file, calls
+3. Depending on the command: only reports, generates/adapts configs, or reads each file, calls
    the pure function and rewrites if it changed.
 4. Prints the summary of created/modified files.
 
@@ -267,7 +270,7 @@ TS calls and orchestrates the effects:
 ## To be defined at implementation time
 
 - Default value for `indent_size` (probably detected per project/language).
-- Exact format of the `--audit` report (provisional today, documented above).
+- Exact format of the `audit` report (provisional today, documented above).
 - Binary detection and handling of files in encodings other than UTF-8.
 - Concrete `--tabs-*` switches.
 

package/dist/cli.d.ts

@@ -1,5 +1,9 @@
 #!/usr/bin/env node
 import type { RunOptions } from "./core/types.js";
-/** Parse argv into resolved RunOptions, or throw on invalid input (never fail silently). */
-export declare function parseArgs(argv: string[]): RunOptions;
+/**
+ * Parse argv into resolved RunOptions. cleye is the single source of truth: each RunMode is a
+ * subcommand (`appease <command> [dir]`), so the modes are mutually exclusive by construction and
+ * each gets its own `--help`. cleye prints usage and exits on unknown flags and on `--help`.
+ */
+export declare function parseArgs(argv?: string[]): RunOptions;
 export declare function main(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -1,43 +1,49 @@
 #!/usr/bin/env node
 // CLI entry point. Maps switches to the public API and orchestrates the effects.
 import { resolve } from "node:path";
-import { parseArgs as nodeParseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
+import { cli, command } from "cleye";
 import { runAppease } from "./index.js";
-const MODES = ["audit", "add-config-defaults", "adapt-configs", "fix-format"];
-/** Parse argv into resolved RunOptions, or throw on invalid input (never fail silently). */
+/** `--dry-run`, shared by the commands that write to disk (not by `audit`, which never writes). */
+const dryRunFlag = {
+    dryRun: { type: Boolean, description: "Simulate writes; report what would change but touch nothing" },
+};
+/**
+ * Parse argv into resolved RunOptions. cleye is the single source of truth: each RunMode is a
+ * subcommand (`appease <command> [dir]`), so the modes are mutually exclusive by construction and
+ * each gets its own `--help`. cleye prints usage and exits on unknown flags and on `--help`.
+ */
 export function parseArgs(argv) {
-    const { values } = nodeParseArgs({
-        args: argv,
-        strict: true,
-        allowPositionals: false,
-        options: {
-            audit: { type: "boolean" },
-            "add-config-defaults": { type: "boolean" },
-            "adapt-configs": { type: "boolean" },
-            "fix-format": { type: "boolean" },
-            yes: { type: "boolean" },
-            "dry-run": { type: "boolean" },
-            verbose: { type: "boolean" },
-            dir: { type: "string" },
-        },
-    });
-    const modes = MODES.filter((mode) => values[mode] === true);
-    if (modes.length !== 1) {
-        throw new Error("Specify exactly one mode: --audit | --add-config-defaults | --adapt-configs | --fix-format");
+    const parsed = cli({
+        name: "appease",
+        help: { description: "Normalize a repo's text files to its .editorconfig / .gitattributes. One command is required." },
+        commands: [
+            command({ name: "audit", parameters: ["[dir]"], strictFlags: true, help: { description: "Report deviations only (no writes)" } }),
+            command({ name: "add-config-defaults", parameters: ["[dir]"], strictFlags: true, flags: dryRunFlag, help: { description: "Write pure-default configs (only the ones that do not exist yet)" } }),
+            command({ name: "adapt-configs", parameters: ["[dir]"], strictFlags: true, flags: dryRunFlag, help: { description: "Write/adapt configs to reflect the repo's current reality" } }),
+            command({ name: "fix-format", parameters: ["[dir]"], strictFlags: true, flags: dryRunFlag, help: { description: "Normalize files (BOM / EOL / trailing whitespace / final newline)" } }),
+        ],
+    }, undefined, argv);
+    if (parsed.command === undefined) {
+        parsed.showHelp();
+        process.stderr.write("\nSpecify a command: audit | add-config-defaults | adapt-configs | fix-format\n");
+        process.exit(1);
     }
+    const dir = parsed._.dir;
     return {
-        mode: modes[0],
-        cwd: values.dir !== undefined ? resolve(values.dir) : process.cwd(),
-        dryRun: values["dry-run"] ?? false,
-        yes: values.yes ?? false,
-        verbose: values.verbose ?? false,
+        mode: parsed.command,
+        cwd: dir !== undefined ? resolve(dir) : process.cwd(),
+        dryRun: parsed.command === "audit" ? false : parsed.flags.dryRun ?? false,
     };
 }
+/** Drop empty `unresolved` arrays from the audit JSON (an empty list carries no information). */
+function omitEmptyUnresolved(key, value) {
+    return key === "unresolved" && Array.isArray(value) && value.length === 0 ? undefined : value;
+}
 export async function main(argv) {
     const report = await runAppease(parseArgs(argv));
     if (report.audit !== undefined)
-        process.stdout.write(`${JSON.stringify(report.audit, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify(report.audit, omitEmptyUnresolved, 2)}\n`);
     for (const path of report.created)
         process.stdout.write(`${report.dryRun ? "would create" : "created"}: ${path}\n`);
     for (const path of report.modified)

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -87,10 +87,6 @@ export interface RunOptions {
     cwd: string;
     /** Simulate writes; report what would change but touch nothing. */
     dryRun: boolean;
-    /** Skip interactive confirmations for destructive operations. */
-    yes: boolean;
-    /** Verbose logging. */
-    verbose: boolean;
 }
 /** Outcome of a run: which files were created/modified, plus mode-specific payload. */
 export interface RunReport {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appease",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Make pease in this app.",
   "license": "MIT",
   "author": "Emilio Platzer",
@@ -24,7 +24,7 @@
     "build": "tsc",
     "build:test": "tsc -p test/tsconfig.json",
     "pretest": "npm run build:test",
-    "test": "mocha",
+    "test": "npm run && npm run build:test && mocha",
     "precoverage": "npm run build:test",
     "coverage": "c8 mocha",
     "prepublishOnly": "npm run build"
@@ -35,6 +35,7 @@
     "uuid": ">=14.0.0"
   },
   "dependencies": {
+    "cleye": "^2.6.0",
     "picomatch": "^4.0.4"
   },
   "devDependencies": {