@venizia/dev-configs 0.4.2 → 0.4.4

package/dist/cli/clean.d.ts

@@ -1,7 +1,8 @@
-/** `devz clean`: removes what the build and the checks generate, and nothing else. */
+/** `devz clean`: removes what the build and the checks generate, and nothing else. `--help` prints the usage; any other argument is refused, and nothing is deleted. */
 export declare class CleanCommand {
     static run(opts: {
         root: string;
+        args?: string[];
     }): number;
 }
 //# sourceMappingURL=clean.d.ts.map

package/dist/cli/clean.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clean.d.ts","sourceRoot":"","sources":["../../src/cli/clean.ts"],"names":[],"mappings":"AAYA,sFAAsF;AACtF,qBAAa,YAAY;IACvB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;CAa3C"}
+{"version":3,"file":"clean.d.ts","sourceRoot":"","sources":["../../src/cli/clean.ts"],"names":[],"mappings":"AAsBA,wKAAwK;AACxK,qBAAa,YAAY;IACvB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,MAAM;CA2B5D"}

package/dist/cli/clean.js

@@ -10,9 +10,26 @@ const GENERATED_PATHS = ['dist', 'node_modules/.cache'];
  * `<tsconfig name>.tsbuildinfo` next to the tsconfig. One inside `dist` is already removed with it.
  */
 const BUILD_INFO_SUFFIX = '.tsbuildinfo';
-/** `devz clean`: removes what the build and the checks generate, and nothing else. */
+const USAGE = `Usage: devz clean
+
+Removes what the build and the checks generate, in the current folder: dist, node_modules/.cache and
+the *.tsbuildinfo files next to the tsconfig. It takes no argument.
+
+  --help     print this text and exit`;
+/** A usage error: nothing was deleted. */
+const USAGE_ERROR_CODE = 2;
+/** `devz clean`: removes what the build and the checks generate, and nothing else. `--help` prints the usage; any other argument is refused, and nothing is deleted. */
 class CleanCommand {
     static run(opts) {
+        const { args = [] } = opts;
+        if (args.includes('--help') || args.includes('-h')) {
+            console.log(USAGE);
+            return 0;
+        }
+        if (args.length > 0) {
+            console.error(`devz clean: unexpected argument ${args.map((arg) => `"${arg}"`).join(', ')}\n${USAGE}`);
+            return USAGE_ERROR_CODE;
+        }
         for (const path of GENERATED_PATHS) {
             (0, node_fs_1.rmSync)((0, node_path_1.join)(opts.root, path), { recursive: true, force: true });
         }

package/dist/cli/clean.js.map

@@ -1 +1 @@
-{"version":3,"file":"clean.js","sourceRoot":"","sources":["../../src/cli/clean.ts"],"names":[],"mappings":";;;AAAA,qCAA8C;AAC9C,yCAAiC;AAEjC,0EAA0E;AAC1E,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAExD;;;GAGG;AACH,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAEzC,sFAAsF;AACtF,MAAa,YAAY;IACvB,MAAM,CAAC,GAAG,CAAC,IAAsB;QAC/B,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;YACnC,IAAA,gBAAM,EAAC,IAAA,gBAAI,EAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,IAAA,qBAAW,EAAC,IAAI,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YACpE,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;gBAC7D,IAAA,gBAAM,EAAC,IAAA,gBAAI,EAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACvD,CAAC;QACH,CAAC;QAED,OAAO,CAAC,CAAC;IACX,CAAC;CACF;AAdD,oCAcC","sourcesContent":["import { readdirSync, rmSync } from 'node:fs';\nimport { join } from 'node:path';\n\n/** What a build and the checks generate, relative to the project root. */\nconst GENERATED_PATHS = ['dist', 'node_modules/.cache'];\n\n/**\n * `incremental` is on in the base tsconfig, so a type-check that emits nothing leaves\n * `<tsconfig name>.tsbuildinfo` next to the tsconfig. One inside `dist` is already removed with it.\n */\nconst BUILD_INFO_SUFFIX = '.tsbuildinfo';\n\n/** `devz clean`: removes what the build and the checks generate, and nothing else. */\nexport class CleanCommand {\n  static run(opts: { root: string }): number {\n    for (const path of GENERATED_PATHS) {\n      rmSync(join(opts.root, path), { recursive: true, force: true });\n    }\n\n    for (const entry of readdirSync(opts.root, { withFileTypes: true })) {\n      if (entry.isFile() && entry.name.endsWith(BUILD_INFO_SUFFIX)) {\n        rmSync(join(opts.root, entry.name), { force: true });\n      }\n    }\n\n    return 0;\n  }\n}\n"]}
+{"version":3,"file":"clean.js","sourceRoot":"","sources":["../../src/cli/clean.ts"],"names":[],"mappings":";;;AAAA,qCAA8C;AAC9C,yCAAiC;AAEjC,0EAA0E;AAC1E,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAExD;;;GAGG;AACH,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAEzC,MAAM,KAAK,GAAG;;;;;sCAKwB,CAAC;AAEvC,0CAA0C;AAC1C,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B,wKAAwK;AACxK,MAAa,YAAY;IACvB,MAAM,CAAC,GAAG,CAAC,IAAuC;QAChD,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC;QAE3B,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACnD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO,CAAC,CAAC;QACX,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CACX,mCAAmC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CACxF,CAAC;YACF,OAAO,gBAAgB,CAAC;QAC1B,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;YACnC,IAAA,gBAAM,EAAC,IAAA,gBAAI,EAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,IAAA,qBAAW,EAAC,IAAI,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YACpE,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;gBAC7D,IAAA,gBAAM,EAAC,IAAA,gBAAI,EAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACvD,CAAC;QACH,CAAC;QAED,OAAO,CAAC,CAAC;IACX,CAAC;CACF;AA5BD,oCA4BC","sourcesContent":["import { readdirSync, rmSync } from 'node:fs';\nimport { join } from 'node:path';\n\n/** What a build and the checks generate, relative to the project root. */\nconst GENERATED_PATHS = ['dist', 'node_modules/.cache'];\n\n/**\n * `incremental` is on in the base tsconfig, so a type-check that emits nothing leaves\n * `<tsconfig name>.tsbuildinfo` next to the tsconfig. One inside `dist` is already removed with it.\n */\nconst BUILD_INFO_SUFFIX = '.tsbuildinfo';\n\nconst USAGE = `Usage: devz clean\n\nRemoves what the build and the checks generate, in the current folder: dist, node_modules/.cache and\nthe *.tsbuildinfo files next to the tsconfig. It takes no argument.\n\n  --help     print this text and exit`;\n\n/** A usage error: nothing was deleted. */\nconst USAGE_ERROR_CODE = 2;\n\n/** `devz clean`: removes what the build and the checks generate, and nothing else. `--help` prints the usage; any other argument is refused, and nothing is deleted. */\nexport class CleanCommand {\n  static run(opts: { root: string; args?: string[] }): number {\n    const { args = [] } = opts;\n\n    if (args.includes('--help') || args.includes('-h')) {\n      console.log(USAGE);\n      return 0;\n    }\n\n    if (args.length > 0) {\n      console.error(\n        `devz clean: unexpected argument ${args.map((arg) => `\"${arg}\"`).join(', ')}\\n${USAGE}`,\n      );\n      return USAGE_ERROR_CODE;\n    }\n\n    for (const path of GENERATED_PATHS) {\n      rmSync(join(opts.root, path), { recursive: true, force: true });\n    }\n\n    for (const entry of readdirSync(opts.root, { withFileTypes: true })) {\n      if (entry.isFile() && entry.name.endsWith(BUILD_INFO_SUFFIX)) {\n        rmSync(join(opts.root, entry.name), { force: true });\n      }\n    }\n\n    return 0;\n  }\n}\n"]}

package/dist/cli/codemod/const-classes.d.ts

@@ -0,0 +1,80 @@
+import type ts from 'typescript';
+type TTypeScript = typeof ts;
+/** What the user may change for one declaration, from the mapping file. */
+export interface IConstClassOverride {
+    /** The class name. */
+    class?: string;
+    /** The type name; only a property of an interface or object type gets a new one. */
+    type?: string;
+    /** A member key per literal value: `{ "read-only": "READ_ONLY" }`. */
+    members?: Record<string, string>;
+    /** Leave this declaration alone. */
+    skip?: boolean;
+}
+export type TConstClassMap = Record<string, IConstClassOverride>;
+export interface IConstClassProposal {
+    /** The key of the mapping file: `path/to/file.ts#TName` or `path/to/file.ts#IContainer.property`. */
+    id: string;
+    line: number;
+    className: string;
+    typeName: string;
+    /** The literal values and the member key each one gets, in order. */
+    members: Array<{
+        value: string;
+        key: string;
+    }>;
+    /** What the union also held: `null` or `undefined`. */
+    nullish: string[];
+}
+export interface IConstClassUntouched {
+    line: number;
+    column: number;
+    reason: string;
+}
+export interface IConstClassResult {
+    output: string;
+    changed: boolean;
+    proposals: IConstClassProposal[];
+    untouched: IConstClassUntouched[];
+}
+/**
+ * Turns the string-literal unions of exported declarations into const classes: an exported type
+ * alias, and a property of an exported interface or object type. The values stay the same, so every
+ * existing literal still type-checks and no call site changes. A union it cannot name is reported.
+ */
+export declare class ConstClasses {
+    static convert(opts: {
+        typescript: TTypeScript;
+        fileName: string;
+        source: string;
+        /** The id prefix of the mapping file: the path of the file relative to the project root. */
+        relativePath?: string;
+        overrides?: TConstClassMap;
+        importFrom?: string;
+    }): IConstClassResult;
+    private static planMembers;
+    /** Every top-level name the file declares or imports. */
+    private static declaredNames;
+    private static isExported;
+    /** The string values of a union, and its `null` or `undefined` members; the union must be string literals (and nullish) only. */
+    private static readUnion;
+    /** At least two string literals, and nothing else but `null` or `undefined`. */
+    private static isEnumerable;
+    private static checkPlan;
+    private static renderClass;
+    /** Reports every string-literal union of an exported declaration the codemod did not handle: it cannot name those. */
+    private static findStrays;
+    private static isKeySet;
+    /** The edit that makes `TConstValue` available: nothing when the file has it, a specifier on an import from the same module, else a new import line. */
+    private static planImport;
+}
+/** `devz codemod const-classes [paths...] [--write | --check]`. */
+export declare class ConstClassesCommand {
+    static readonly USAGE = "Usage: devz codemod const-classes [paths...] [--write | --check] [--map <file>] [--emit-map <file>] [--import-from <module>] [--include-tests]\n\nTurns a string-literal union in an exported declaration into a const class (SCHEME_SET, isValid) plus\n`TConstValue<typeof X>`, the shape the venizia/const-class-values lint rule asks for. It handles an\nexported type alias and a property of an exported interface or object type. The values stay the same,\nso every existing literal still type-checks and no call site changes.\n\nIt has to choose names: the class is the type name without its leading T, in the plural; a member is\nthe value in upper snake case. The dry run prints every proposal.\n\n  --write              write the changed files (without it, nothing is written)\n  --check              dry run that exits 1 while a union can be converted or is left untouched (for CI)\n  --map <file>         a JSON file of overrides, keyed by the id the dry run prints\n  --emit-map <file>    write the proposals as a mapping file to edit, then pass it with --map\n  --import-from <m>    where TConstValue is imported from (default @venizia/ignis-helpers/common)\n  --include-tests      also convert test files (skipped by default)\n  --help               print this text and exit\n\nA mapping entry: { \"src/a.ts#TMode\": { \"class\": \"Modes\", \"members\": { \"read-only\": \"READ_ONLY\" } } },\nor { \"skip\": true }. A union in a parameter, a return type, a generic or a nested type is reported as\nleft untouched: it has no name, so write that class by hand. Key sets (Pick, Omit, Extract, Exclude,\nRecord, mapped types) are not enumerable values and are never touched.";
+    static run(opts: {
+        root: string;
+        args: string[];
+    }): Promise<number>;
+}
+export {};
+//# sourceMappingURL=const-classes.d.ts.map

package/dist/cli/codemod/const-classes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"const-classes.d.ts","sourceRoot":"","sources":["../../../src/cli/codemod/const-classes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAGjC,KAAK,WAAW,GAAG,OAAO,EAAE,CAAC;AAU7B,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oCAAoC;IACpC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAEjE,MAAM,WAAW,mBAAmB;IAClC,qGAAqG;IACrG,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,uDAAuD;IACvD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,SAAS,EAAE,oBAAoB,EAAE,CAAC;CACnC;AA4CD;;;;GAIG;AACH,qBAAa,YAAY;IACvB,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE;QACnB,UAAU,EAAE,WAAW,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,4FAA4F;QAC5F,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,cAAc,CAAC;QAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,iBAAiB;IA4KrB,OAAO,CAAC,MAAM,CAAC,WAAW;IA8C1B,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAC,aAAa;IAoD5B,OAAO,CAAC,MAAM,CAAC,UAAU;IAQzB,iIAAiI;IACjI,OAAO,CAAC,MAAM,CAAC,SAAS;IA+BxB,gFAAgF;IAChF,OAAO,CAAC,MAAM,CAAC,YAAY;IAuB3B,OAAO,CAAC,MAAM,CAAC,SAAS;IAqCxB,OAAO,CAAC,MAAM,CAAC,WAAW;IAuB1B,sHAAsH;IACtH,OAAO,CAAC,MAAM,CAAC,UAAU;IAkCzB,OAAO,CAAC,MAAM,CAAC,QAAQ;IA2BvB,wJAAwJ;IACxJ,OAAO,CAAC,MAAM,CAAC,UAAU;CAqD1B;AAyDD,mEAAmE;AACnE,qBAAa,mBAAmB;IAC9B,MAAM,CAAC,QAAQ,CAAC,KAAK,ipDAAS;WAEjB,GAAG,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CA2K1E"}