eser 0.1.5 → 0.8.2

package/commands/codebase/mod.ts

@@ -0,0 +1,411 @@
+// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
+
+/**
+ * Codebase command group - validation and management tools
+ *
+ * Subcommands:
+ *   check-circular-deps   Detect circular package dependencies
+ *   check-mod-exports     Validate mod.ts exports all files
+ *   check-export-names    Validate export naming conventions
+ *   check-docs            Validate JSDoc documentation
+ *   check-licenses        Validate license headers
+ *   check-package-configs Validate deno.json/package.json consistency
+ *   versions              Manage workspace versions
+ *
+ * @module
+ */
+
+import * as cliParseArgs from "@std/cli/parse-args";
+import * as fmtColors from "@std/fmt/colors";
+import * as standardsRuntime from "@eser/standards/runtime";
+import * as checkCircularDeps from "@eser/codebase/check-circular-deps";
+import * as checkModExports from "@eser/codebase/check-mod-exports";
+import * as checkExportNames from "@eser/codebase/check-export-names";
+import * as checkDocs from "@eser/codebase/check-docs";
+import * as checkLicenses from "@eser/codebase/check-licenses";
+import * as checkPackageConfigs from "@eser/codebase/check-package-configs";
+import * as versions from "@eser/codebase/versions";
+
+type SubcommandDef = {
+  description: string;
+  usage: string;
+  options: Array<{ flag: string; description: string }>;
+  handler: (args: string[], flags: Record<string, unknown>) => Promise<void>;
+};
+
+const showSubcommandHelp = (name: string, def: SubcommandDef): void => {
+  console.log(`eser codebase ${name} - ${def.description}\n`);
+  console.log(`Usage: ${def.usage}\n`);
+  if (def.options.length > 0) {
+    console.log("Options:");
+    for (const opt of def.options) {
+      console.log(`  ${opt.flag.padEnd(20)} ${opt.description}`);
+    }
+  }
+};
+
+const subcommands: Record<string, SubcommandDef> = {
+  "check-circular-deps": {
+    description: "Detect circular package dependencies",
+    usage: "eser codebase check-circular-deps [options]",
+    options: [
+      {
+        flag: "--root <path>",
+        description: "Root directory (default: current)",
+      },
+      { flag: "-h, --help", description: "Show this help message" },
+    ],
+    handler: async (_args, flags) => {
+      const root = flags["root"] as string | undefined;
+      console.log("Checking for circular dependencies...\n");
+
+      const result = await checkCircularDeps.checkCircularDeps({ root });
+
+      console.log(`Checked ${result.packagesChecked} packages.`);
+
+      if (result.hasCycles) {
+        console.log(
+          fmtColors.red(
+            `\nFound ${result.cycles.length} circular dependencies:\n`,
+          ),
+        );
+        for (const cycle of result.cycles) {
+          console.log(fmtColors.yellow(`  ${cycle.join(" → ")}`));
+        }
+        standardsRuntime.runtime.process.exit(1);
+      } else {
+        console.log(fmtColors.green("\nNo circular dependencies found."));
+      }
+    },
+  },
+
+  "check-mod-exports": {
+    description: "Validate mod.ts exports all public files",
+    usage: "eser codebase check-mod-exports [options]",
+    options: [
+      {
+        flag: "--root <path>",
+        description: "Root directory (default: current)",
+      },
+      { flag: "-h, --help", description: "Show this help message" },
+    ],
+    handler: async (_args, flags) => {
+      const root = flags["root"] as string | undefined;
+      console.log("Checking mod.ts exports...\n");
+
+      const result = await checkModExports.checkModExports({ root });
+
+      console.log(`Checked ${result.packagesChecked} packages.`);
+
+      if (!result.isComplete) {
+        console.log(
+          fmtColors.red(
+            `\nFound ${result.missingExports.length} missing exports:\n`,
+          ),
+        );
+        for (const missing of result.missingExports) {
+          console.log(
+            fmtColors.yellow(`  ${missing.packageName}: ${missing.file}`),
+          );
+        }
+        standardsRuntime.runtime.process.exit(1);
+      } else {
+        console.log(fmtColors.green("\nAll mod.ts exports are complete."));
+      }
+    },
+  },
+
+  "check-export-names": {
+    description: "Validate export naming conventions",
+    usage: "eser codebase check-export-names [options]",
+    options: [
+      {
+        flag: "--root <path>",
+        description: "Root directory (default: current)",
+      },
+      { flag: "-h, --help", description: "Show this help message" },
+    ],
+    handler: async (_args, flags) => {
+      const root = flags["root"] as string | undefined;
+      console.log("Checking export naming conventions...\n");
+
+      const result = await checkExportNames.checkExportNames({ root });
+
+      console.log(`Checked ${result.packagesChecked} packages.`);
+
+      if (!result.isValid) {
+        console.log(
+          fmtColors.red(
+            `\nFound ${result.violations.length} naming violations:\n`,
+          ),
+        );
+        for (const violation of result.violations) {
+          console.log(fmtColors.yellow(`  ${violation.packageName}:`));
+          console.log(`    Export: ${violation.exportPath}`);
+          console.log(`    Suggestion: ${violation.suggestion}`);
+        }
+        standardsRuntime.runtime.process.exit(1);
+      } else {
+        console.log(fmtColors.green("\nAll export names follow conventions."));
+      }
+    },
+  },
+
+  "check-docs": {
+    description: "Validate JSDoc documentation",
+    usage: "eser codebase check-docs [options]",
+    options: [
+      {
+        flag: "--root <path>",
+        description: "Root directory (default: current)",
+      },
+      { flag: "-h, --help", description: "Show this help message" },
+    ],
+    handler: async (_args, flags) => {
+      const root = flags["root"] as string | undefined;
+      console.log("Checking documentation...\n");
+
+      const result = await checkDocs.checkDocs({ root });
+
+      console.log(
+        `Checked ${result.filesChecked} files, ${result.symbolsChecked} symbols.`,
+      );
+
+      if (!result.isValid) {
+        console.log(
+          fmtColors.red(
+            `\nFound ${result.issues.length} documentation issues:\n`,
+          ),
+        );
+
+        // Group by file
+        const byFile = new Map<string, checkDocs.DocIssue[]>();
+        for (const issue of result.issues) {
+          const existing = byFile.get(issue.file) ?? [];
+          existing.push(issue);
+          byFile.set(issue.file, existing);
+        }
+
+        for (const [file, fileIssues] of byFile) {
+          console.log(fmtColors.yellow(`\n${file}:`));
+          for (const issue of fileIssues) {
+            const lineInfo = issue.line !== undefined ? `:${issue.line}` : "";
+            console.log(`  ${issue.symbol}${lineInfo}: ${issue.issue}`);
+          }
+        }
+
+        standardsRuntime.runtime.process.exit(1);
+      } else {
+        console.log(fmtColors.green("\nAll documentation is valid."));
+      }
+    },
+  },
+
+  "check-licenses": {
+    description: "Validate license headers in source files",
+    usage: "eser codebase check-licenses [options]",
+    options: [
+      { flag: "--fix", description: "Auto-fix missing or incorrect headers" },
+      { flag: "-h, --help", description: "Show this help message" },
+    ],
+    handler: async (_args, flags) => {
+      const fix = flags["fix"] as boolean | undefined;
+      console.log("Validating license headers...\n");
+
+      const result = await checkLicenses.validateLicenses({ fix });
+
+      if (result.issues.length === 0) {
+        console.log(
+          `Checked ${result.checked} files. All licenses are valid.`,
+        );
+        return;
+      }
+
+      if (fix) {
+        for (const issue of result.issues) {
+          if (issue.fixed) {
+            console.log(`Fixed ${issue.issue} header: ${issue.path}`);
+          }
+        }
+        console.log(`Fixed ${result.fixedCount} files.`);
+      } else {
+        for (const issue of result.issues) {
+          console.error(
+            fmtColors.red(
+              `${
+                issue.issue === "missing" ? "Missing" : "Incorrect"
+              } copyright header: ${issue.path}`,
+            ),
+          );
+        }
+        console.log(
+          fmtColors.yellow(
+            `\nCopyright header should be "// Copyright YYYY-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license."`,
+          ),
+        );
+        standardsRuntime.runtime.process.exit(1);
+      }
+    },
+  },
+
+  "check-package-configs": {
+    description: "Validate deno.json and package.json consistency",
+    usage: "eser codebase check-package-configs [options]",
+    options: [
+      {
+        flag: "--root <path>",
+        description: "Root directory (default: current)",
+      },
+      { flag: "-h, --help", description: "Show this help message" },
+    ],
+    handler: async (_args, flags) => {
+      const root = flags["root"] as string | undefined;
+      console.log("Checking package config consistency...\n");
+
+      const result = await checkPackageConfigs.checkPackageConfigs({ root });
+
+      console.log(`Checked ${result.packagesChecked} packages.`);
+
+      if (!result.isConsistent) {
+        console.log(
+          fmtColors.red(
+            `\nFound ${result.inconsistencies.length} inconsistencies:\n`,
+          ),
+        );
+
+        // Group by package
+        const byPackage = new Map<
+          string,
+          checkPackageConfigs.ConfigInconsistency[]
+        >();
+        for (const inc of result.inconsistencies) {
+          const existing = byPackage.get(inc.packageName) ?? [];
+          existing.push(inc);
+          byPackage.set(inc.packageName, existing);
+        }
+
+        for (const [pkgName, inconsistencies] of byPackage) {
+          console.log(fmtColors.yellow(`${pkgName}:`));
+          for (const inc of inconsistencies) {
+            console.log(fmtColors.red(`  ⚠ ${inc.field} mismatch:`));
+            console.log(`    deno.json:    ${JSON.stringify(inc.denoValue)}`);
+            console.log(
+              `    package.json: ${JSON.stringify(inc.packageValue)}`,
+            );
+          }
+        }
+
+        standardsRuntime.runtime.process.exit(1);
+      } else {
+        console.log(fmtColors.green("\nAll package configs are consistent."));
+      }
+    },
+  },
+
+  versions: {
+    description: "Manage workspace package versions",
+    usage: "eser codebase versions [command] [options]",
+    options: [
+      { flag: "sync", description: "Sync all packages to root version" },
+      { flag: "patch", description: "Bump patch version (0.0.x)" },
+      { flag: "minor", description: "Bump minor version (0.x.0)" },
+      { flag: "major", description: "Bump major version (x.0.0)" },
+      { flag: "--dry-run", description: "Preview changes without applying" },
+      { flag: "-h, --help", description: "Show this help message" },
+    ],
+    handler: async (args, flags) => {
+      const command = args[0] as versions.VersionCommand | undefined;
+      const dryRun = flags["dry-run"] as boolean | undefined;
+
+      if (command === undefined) {
+        const result = await versions.showVersions();
+        console.table(result.packages);
+        return;
+      }
+
+      const validCommands = ["sync", "patch", "minor", "major"];
+      if (!validCommands.includes(command)) {
+        console.error(fmtColors.red(`Invalid command: ${command}`));
+        console.error(
+          "Usage: eser codebase versions [sync|patch|minor|major] [--dry-run]",
+        );
+        standardsRuntime.runtime.process.exit(1);
+      }
+
+      if (command === "sync") {
+        console.log("Syncing all versions...");
+      } else {
+        console.log(`Bumping all versions (${command})...`);
+      }
+
+      const result = await versions.versions(command, { dryRun });
+
+      console.log(`Target version: ${result.targetVersion}`);
+      console.table(result.updates);
+
+      if (result.dryRun) {
+        console.log(
+          fmtColors.cyan(
+            `Dry run - ${result.changedCount} packages would be modified.`,
+          ),
+        );
+      } else {
+        console.log(`Done. Updated ${result.changedCount} packages.`);
+      }
+    },
+  },
+};
+
+const showHelp = (): void => {
+  console.log("eser codebase - Codebase validation tools\n");
+  console.log("Usage: eser codebase <subcommand> [options]\n");
+  console.log("Subcommands:");
+  console.log("  check-circular-deps   Detect circular package dependencies");
+  console.log("  check-mod-exports     Validate mod.ts exports all files");
+  console.log("  check-export-names    Validate export naming conventions");
+  console.log("  check-docs            Validate JSDoc documentation");
+  console.log("  check-licenses        Validate license headers");
+  console.log(
+    "  check-package-configs Validate deno.json/package.json consistency",
+  );
+  console.log("  versions              Manage workspace versions");
+  console.log(
+    "\nRun 'eser codebase <subcommand> --help' for subcommand options.",
+  );
+};
+
+export const codebaseCommand = async (
+  rawArgs: string[],
+  _parentFlags: Record<string, unknown>,
+): Promise<void> => {
+  // Parse all flags (don't use stopEarly so --help is always captured)
+  const parsed = cliParseArgs.parseArgs(rawArgs, {
+    boolean: ["help", "dry-run", "fix"],
+    string: ["root"],
+    alias: { h: "help" },
+  });
+
+  const subcommand = parsed._[0] as string | undefined;
+
+  // Show main help if no subcommand or help without subcommand
+  if (subcommand === undefined) {
+    showHelp();
+    return;
+  }
+
+  const def = subcommands[subcommand];
+  if (def === undefined) {
+    console.error(fmtColors.red(`Unknown subcommand: ${subcommand}`));
+    console.log("");
+    showHelp();
+    standardsRuntime.runtime.process.exit(1);
+  }
+
+  // Show subcommand help if --help flag
+  if (parsed.help) {
+    showSubcommandHelp(subcommand, def);
+    return;
+  }
+
+  await def.handler(parsed._.slice(1) as string[], parsed);
+};

package/deno.json

@@ -0,0 +1,10 @@
+{
+  "name": "@eser/cli",
+  "version": "0.8.2",
+  "exports": "./main.ts",
+  "imports": {
+    "@std/cli": "jsr:@std/cli@^1.0.25",
+    "@std/fmt": "jsr:@std/fmt@^1.0.8",
+    "@std/path": "jsr:@std/path@^1.1.4"
+  }
+}

package/main.ts

@@ -0,0 +1,78 @@
+// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
+
+/**
+ * eser - Versatile development CLI
+ *
+ * A multi-purpose command-line tool for development workflows.
+ * Similar in design to `gh` (GitHub CLI) or `wrangler` (Cloudflare).
+ *
+ * Usage:
+ *   deno run -A ./main.ts <command> [subcommand] [options]
+ *   dx jsr:@eser/cli <command> [subcommand] [options]
+ *
+ * Commands:
+ *   codebase    Codebase validation and management tools
+ *
+ * @module
+ */
+
+import * as cliParseArgs from "@std/cli/parse-args";
+import * as standardsRuntime from "@eser/standards/runtime";
+import { codebaseCommand } from "./commands/codebase/mod.ts";
+
+type CommandHandler = (
+  args: string[],
+  flags: Record<string, unknown>,
+) => Promise<void>;
+
+const commands: Record<string, CommandHandler> = {
+  codebase: codebaseCommand,
+};
+
+const showHelp = (): void => {
+  console.log("eser - Versatile development CLI\n");
+  console.log("Usage: eser <command> [subcommand] [options]\n");
+  console.log("Commands:");
+  console.log("  codebase    Codebase validation and management tools");
+  console.log("\nOptions:");
+  console.log("  -h, --help     Show this help message");
+  console.log("  -v, --version  Show version number");
+  console.log("\nRun 'eser <command> --help' for command-specific help.");
+};
+
+const main = async (): Promise<void> => {
+  // @ts-ignore parseArgs doesn't mutate the array, readonly is safe
+  const args = cliParseArgs.parseArgs(standardsRuntime.runtime.process.args, {
+    boolean: ["help", "version"],
+    alias: { h: "help", v: "version" },
+    stopEarly: true, // Stop parsing at first non-option to pass rest to subcommand
+  });
+
+  if (args.version) {
+    console.log("eser 0.8.0");
+    return;
+  }
+
+  const command = args._[0] as string | undefined;
+
+  // Show main help only if no command or help without command
+  if (command === undefined) {
+    showHelp();
+    return;
+  }
+
+  const handler = commands[command];
+  if (handler === undefined) {
+    console.error(`Unknown command: ${command}`);
+    console.log("");
+    showHelp();
+    standardsRuntime.runtime.process.exit(1);
+  }
+
+  // Pass remaining args to command handler
+  await handler(args._.slice(1) as string[], args);
+};
+
+if (import.meta.main) {
+  await main();
+}

package/package.json

@@ -1,52 +1,16 @@
 {
   "name": "eser",
-  "description": "JavaScript Coding Convention",
-  "keywords": [
-    "eser",
-    "ozvataf",
-    "eslintconfig"
-  ],
-  "version": "0.1.5",
-  "homepage": "",
-  "author": "Eser Ozvataf <eser@ozvataf.com>",
-  "contributors": [
-    {
-      "name": "Eser Ozvataf",
-      "email": "eser@ozvataf.com",
-      "url": "http://eser.ozvataf.com/"
-    }
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/eserozvataf/eser.git"
-  },
-  "bugs": {
-    "url": "https://github.com/eserozvataf/eser/issues",
-    "email": "eser@ozvataf.com"
-  },
-  "license": "Apache-2.0",
-  "preferGlobal": true,
-  "main": "./lib/index.js",
-  "engines": {
-    "node": ">=4.2.0"
-  },
-  "scripts": {},
-  "directories": {
-    "lib": "./lib"
-  },
-  "files": [
-    "lib",
-    "bin",
-    ".eslintrc.json",
-    ".csscomb.json"
-  ],
+  "version": "0.8.2",
+  "type": "module",
+  "exports": "./main.ts",
   "bin": {
-    "eser": "./bin/eser"
+    "eser": "./main.ts"
   },
   "dependencies": {
-    "eslint": "^3.8.1",
-    "standard-engine": "^5.1.1",
-    "update-notifier": "^1.0.2"
-  },
-  "devDependencies": {}
+    "@eser/codebase": "npm:@jsr/eser__codebase@^0.8.2",
+    "@eser/standards": "npm:@jsr/eser__standards@^0.8.2",
+    "@std/cli": "npm:@jsr/std__cli@^1.0.25",
+    "@std/fmt": "npm:@jsr/std__fmt@^1.0.8",
+    "@std/path": "npm:@jsr/std__path@^1.1.4"
+  }
 }

package/package.json.template

@@ -0,0 +1,16 @@
+{
+  "name": "@eser/cli",
+  "version": "0.8.2",
+  "type": "module",
+  "exports": "./main.ts",
+  "bin": {
+    "eser": "./main.ts"
+  },
+  "dependencies": {
+    "@eser/codebase": "workspace:*",
+    "@eser/standards": "workspace:*",
+    "@std/cli": "npm:@jsr/std__cli@^1.0.25",
+    "@std/fmt": "npm:@jsr/std__fmt@^1.0.8",
+    "@std/path": "npm:@jsr/std__path@^1.1.4"
+  }
+}

package/scripts/npm-publish-prepare.ts

@@ -0,0 +1,123 @@
+// Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
+
+/**
+ * Prepares package.json for npm publishing.
+ *
+ * Reads package.json.template, replaces workspace:* dependencies with
+ * npm:@jsr/eser__<package>@^<version>, sets name to "eser", and writes
+ * the result to package.json.
+ *
+ * @module
+ */
+
+import * as path from "@std/path";
+
+type PackageJson = {
+  name: string;
+  version: string;
+  type?: string;
+  exports?: string | Record<string, string>;
+  bin?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+type DenoJson = {
+  name: string;
+  version: string;
+};
+
+const isWorkspaceDep = (spec: string): boolean => {
+  return spec === "workspace:*" || spec.startsWith("workspace:");
+};
+
+const extractPackageName = (depName: string): string => {
+  // @eser/codebase -> codebase
+  const parts = depName.split("/");
+  return parts.length > 1 ? parts[1] : depName;
+};
+
+const getPackageVersion = async (
+  pkgDir: string,
+  depName: string,
+): Promise<string> => {
+  const packageName = extractPackageName(depName);
+  const denoJsonPath = path.join(pkgDir, "..", packageName, "deno.json");
+
+  const content = await Deno.readTextFile(denoJsonPath);
+  const denoJson = JSON.parse(content) as DenoJson;
+
+  return denoJson.version;
+};
+
+const convertWorkspaceDep = async (
+  pkgDir: string,
+  depName: string,
+): Promise<string> => {
+  const packageName = extractPackageName(depName);
+  const version = await getPackageVersion(pkgDir, depName);
+
+  // @eser/codebase -> npm:@jsr/eser__codebase@^0.8.0
+  return `npm:@jsr/eser__${packageName}@^${version}`;
+};
+
+const processDependencies = async (
+  pkgDir: string,
+  deps: Record<string, string> | undefined,
+): Promise<Record<string, string> | undefined> => {
+  if (deps === undefined) {
+    return undefined;
+  }
+
+  const result: Record<string, string> = {};
+
+  for (const [name, spec] of Object.entries(deps)) {
+    if (isWorkspaceDep(spec)) {
+      result[name] = await convertWorkspaceDep(pkgDir, name);
+    } else {
+      result[name] = spec;
+    }
+  }
+
+  return result;
+};
+
+const main = async (): Promise<void> => {
+  const scriptDir = import.meta.dirname;
+  if (scriptDir === undefined) {
+    throw new Error("Cannot determine script directory");
+  }
+
+  const pkgDir = path.dirname(scriptDir);
+  const templatePath = path.join(pkgDir, "package.json.template");
+  const outputPath = path.join(pkgDir, "package.json");
+
+  // Read template
+  const templateContent = await Deno.readTextFile(templatePath);
+  const pkg = JSON.parse(templateContent) as PackageJson;
+
+  // Set name to "eser" for npx
+  pkg.name = "eser";
+
+  // Process dependencies
+  pkg.dependencies = await processDependencies(pkgDir, pkg.dependencies);
+  pkg.devDependencies = await processDependencies(pkgDir, pkg.devDependencies);
+
+  // Write output
+  const outputContent = JSON.stringify(pkg, null, 2) + "\n";
+  await Deno.writeTextFile(outputPath, outputContent);
+
+  // deno-lint-ignore no-console
+  console.log(`Generated ${outputPath}`);
+  // deno-lint-ignore no-console
+  console.log(`  name: ${pkg.name}`);
+
+  if (pkg.dependencies !== undefined) {
+    for (const [name, spec] of Object.entries(pkg.dependencies)) {
+      // deno-lint-ignore no-console
+      console.log(`  ${name}: ${spec}`);
+    }
+  }
+};
+
+main();