apdev-js 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# apdev
+
+Shared development tools for TypeScript/JavaScript projects - character validation, circular import detection, and more.
+
+## Installation
+
+```bash
+pnpm add -D apdev-js
+# or
+npm install --save-dev apdev-js
+```
+
+## Available Tools
+
+### check-chars
+
+Validate files contain only allowed characters (ASCII + emoji + technical symbols).
+
+```bash
+npx apdev check-chars src/**/*.ts
+```
+
+### check-imports
+
+Detect circular imports in a JS/TS package.
+
+```bash
+npx apdev check-imports --package mylib --src-dir src
+```
+
+### release
+
+Interactive release automation (build, tag, GitHub release, npm publish).
+
+```bash
+npx apdev release
+npx apdev release 1.0.0
+```
+
+## Configuration
+
+Add an `"apdev"` field to your `package.json`:
+
+```json
+{
+  "apdev": {
+    "base_package": "mylib",
+    "src_dir": "src"
+  }
+}
+```
+
+With configuration, you can run `check-imports` without flags:
+
+```bash
+npx apdev check-imports
+```
+
+## Integration with lint-staged / Husky
+
+Add character checking as a pre-commit hook:
+
+```json
+{
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": ["apdev check-chars"]
+  }
+}
+```
+
+## Programmatic API
+
+```typescript
+import {
+  isAllowedChar,
+  checkFile,
+  checkPaths,
+  checkCircularImports,
+  loadConfig,
+} from "apdev-js";
+
+// Check a single character
+isAllowedChar("A"); // true
+isAllowedChar("\u4E2D"); // false (CJK)
+
+// Check a file
+const problems = checkFile("src/index.ts");
+
+// Detect circular imports
+const exitCode = checkCircularImports("src", "mylib");
+```
+
+## Development
+
+Prerequisites: Node.js >= 18, pnpm.
+
+```bash
+cd typescript
+pnpm install              # Install dependencies
+pnpm build                # Build (ESM + CJS + types)
+pnpm test                 # Run tests
+pnpm lint                 # Lint
+pnpm format               # Format
+```
+
+### Release
+
+Requires npm authentication (`~/.npmrc`) and GitHub CLI (`gh`).
+
+```bash
+./release.sh              # Use version from package.json
+./release.sh 0.2.0        # Specify version
+./release.sh --yes        # Silent mode (CI/CD)
+```
+
+The script will: verify version → clean → build → pack check → git tag → GitHub release → npm publish.
+
+## License
+
+Apache-2.0

package/dist/cli.js

@@ -0,0 +1,556 @@
+#!/usr/bin/env node
+
+// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var getFilename = () => fileURLToPath(import.meta.url);
+var getDirname = () => path.dirname(getFilename());
+var __dirname = /* @__PURE__ */ getDirname();
+
+// src/cli.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { resolve, dirname, join as join3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { execFileSync } from "child_process";
+import { Command } from "commander";
+
+// src/check-chars.ts
+import { readFileSync } from "fs";
+import { extname } from "path";
+var EMOJI_RANGES = [
+  [127744, 128511],
+  // Symbols and Pictographs
+  [128512, 128591],
+  // Emoticons
+  [128640, 128767],
+  // Transport and Map Symbols
+  [128896, 129023],
+  // Geometric Shapes Extended
+  [129280, 129535],
+  // Supplemental Symbols and Pictographs
+  [9728, 9983],
+  // Miscellaneous Symbols
+  [9984, 10175]
+  // Dingbats
+];
+var EXTRA_ALLOWED_RANGES = [
+  [128, 255],
+  // Latin-1 Supplement
+  [8192, 8303],
+  // General Punctuation
+  [8448, 8527],
+  // Letterlike Symbols
+  [8592, 8703],
+  // Arrows
+  [8704, 8959],
+  // Mathematical Operators
+  [8960, 9215],
+  // Miscellaneous Technical
+  [9472, 9599],
+  // Box Drawing
+  [9632, 9727],
+  // Geometric Shapes
+  [11008, 11263],
+  // Miscellaneous Symbols and Arrows
+  [65024, 65039]
+  // Variation Selectors
+];
+var ALL_RANGES = [...EMOJI_RANGES, ...EXTRA_ALLOWED_RANGES];
+var DANGEROUS_CODEPOINTS = /* @__PURE__ */ new Map([
+  // Bidi control characters (Trojan Source - CVE-2021-42574)
+  [8234, "LEFT-TO-RIGHT EMBEDDING"],
+  [8235, "RIGHT-TO-LEFT EMBEDDING"],
+  [8236, "POP DIRECTIONAL FORMATTING"],
+  [8237, "LEFT-TO-RIGHT OVERRIDE"],
+  [8238, "RIGHT-TO-LEFT OVERRIDE"],
+  [8294, "LEFT-TO-RIGHT ISOLATE"],
+  [8295, "RIGHT-TO-LEFT ISOLATE"],
+  [8296, "FIRST STRONG ISOLATE"],
+  [8297, "POP DIRECTIONAL ISOLATE"],
+  // Zero-width characters
+  [8203, "ZERO WIDTH SPACE"],
+  [8204, "ZERO WIDTH NON-JOINER"],
+  [8205, "ZERO WIDTH JOINER"],
+  [8206, "LEFT-TO-RIGHT MARK"],
+  [8207, "RIGHT-TO-LEFT MARK"],
+  [8288, "WORD JOINER"]
+]);
+var PYTHON_SUFFIXES = /* @__PURE__ */ new Set([".py"]);
+var JS_SUFFIXES = /* @__PURE__ */ new Set([".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs"]);
+function isAllowedChar(c) {
+  const code = c.codePointAt(0);
+  if (code <= 127) {
+    return true;
+  }
+  for (const [start, end] of ALL_RANGES) {
+    if (code >= start && code <= end) {
+      return true;
+    }
+  }
+  return false;
+}
+function isDangerousChar(c) {
+  return DANGEROUS_CODEPOINTS.has(c.codePointAt(0));
+}
+function computeCommentMask(content, suffix) {
+  if (PYTHON_SUFFIXES.has(suffix)) {
+    return computeCommentMaskPython(content);
+  }
+  if (JS_SUFFIXES.has(suffix)) {
+    return computeCommentMaskJs(content);
+  }
+  return /* @__PURE__ */ new Set();
+}
+function computeCommentMaskPython(content) {
+  const mask = /* @__PURE__ */ new Set();
+  let i = 0;
+  const n = content.length;
+  while (i < n) {
+    if (i + 2 < n && (content.slice(i, i + 3) === '"""' || content.slice(i, i + 3) === "'''")) {
+      const quote = content.slice(i, i + 3);
+      i += 3;
+      while (i < n) {
+        if (content[i] === "\\" && i + 1 < n) {
+          i += 2;
+          continue;
+        }
+        if (i + 2 < n && content.slice(i, i + 3) === quote) {
+          i += 3;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+    if (content[i] === '"' || content[i] === "'") {
+      const quoteChar = content[i];
+      i++;
+      while (i < n && content[i] !== "\n") {
+        if (content[i] === "\\" && i + 1 < n) {
+          i += 2;
+          continue;
+        }
+        if (content[i] === quoteChar) {
+          i++;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+    if (content[i] === "#") {
+      while (i < n && content[i] !== "\n") {
+        mask.add(i);
+        i++;
+      }
+      continue;
+    }
+    i++;
+  }
+  return mask;
+}
+function computeCommentMaskJs(content) {
+  const mask = /* @__PURE__ */ new Set();
+  let i = 0;
+  const n = content.length;
+  while (i < n) {
+    if (content[i] === "`") {
+      i++;
+      while (i < n) {
+        if (content[i] === "\\" && i + 1 < n) {
+          i += 2;
+          continue;
+        }
+        if (content[i] === "`") {
+          i++;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+    if (content[i] === '"' || content[i] === "'") {
+      const quoteChar = content[i];
+      i++;
+      while (i < n && content[i] !== "\n") {
+        if (content[i] === "\\" && i + 1 < n) {
+          i += 2;
+          continue;
+        }
+        if (content[i] === quoteChar) {
+          i++;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+    if (i + 1 < n && content[i] === "/" && content[i + 1] === "/") {
+      while (i < n && content[i] !== "\n") {
+        mask.add(i);
+        i++;
+      }
+      continue;
+    }
+    if (i + 1 < n && content[i] === "/" && content[i + 1] === "*") {
+      while (i < n) {
+        if (i + 1 < n && content[i] === "*" && content[i + 1] === "/") {
+          mask.add(i);
+          mask.add(i + 1);
+          i += 2;
+          break;
+        }
+        mask.add(i);
+        i++;
+      }
+      continue;
+    }
+    i++;
+  }
+  return mask;
+}
+function checkFile(filePath, maxProblems = 5) {
+  const problems = [];
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const suffix = extname(filePath).toLowerCase();
+    const commentMask = computeCommentMask(content, suffix);
+    let position = 0;
+    let offset = 0;
+    for (const char of content) {
+      position++;
+      const code = char.codePointAt(0);
+      if (isDangerousChar(char)) {
+        if (!commentMask.has(offset)) {
+          const name = DANGEROUS_CODEPOINTS.get(code);
+          const hex = code.toString(16).toUpperCase().padStart(4, "0");
+          problems.push(
+            `Dangerous character in code at position ${position}: U+${hex} (${name})`
+          );
+        }
+      } else if (!isAllowedChar(char)) {
+        const hex = code.toString(16).toUpperCase().padStart(4, "0");
+        problems.push(
+          `Illegal character at position ${position}: ${JSON.stringify(char)} (U+${hex})`
+        );
+      }
+      if (problems.length >= maxProblems) {
+        break;
+      }
+      offset += char.length;
+    }
+  } catch {
+    problems.push(`Failed to read file: ${filePath}`);
+  }
+  return problems;
+}
+function checkPaths(paths) {
+  let hasError = false;
+  for (const path2 of paths) {
+    const problems = checkFile(path2);
+    if (problems.length > 0) {
+      hasError = true;
+      console.log(`
+${path2} contains illegal characters:`);
+      for (const p of problems) {
+        console.log(`  ${p}`);
+      }
+    }
+  }
+  return hasError ? 1 : 0;
+}
+
+// src/check-imports.ts
+import { readFileSync as readFileSync2, readdirSync, statSync } from "fs";
+import { join, relative, sep, extname as extname2, basename } from "path";
+import ts from "typescript";
+var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs"
+]);
+var INDEX_BASENAMES = /* @__PURE__ */ new Set([
+  "index.ts",
+  "index.tsx",
+  "index.js",
+  "index.jsx",
+  "index.mjs",
+  "index.cjs"
+]);
+function fileToModule(filePath, srcDir) {
+  const rel = relative(srcDir, filePath);
+  const parts = rel.split(sep);
+  const last = parts[parts.length - 1];
+  if (last === "index.ts" || last === "index.js" || last === "index.tsx" || last === "index.jsx") {
+    parts.pop();
+  } else {
+    const ext = extname2(last);
+    parts[parts.length - 1] = basename(last, ext);
+  }
+  return parts.join(".");
+}
+function extractImports(source, fileName) {
+  const imports = /* @__PURE__ */ new Set();
+  const sourceFile = ts.createSourceFile(
+    fileName,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    fileName.endsWith(".tsx") || fileName.endsWith(".jsx") ? ts.ScriptKind.TSX : void 0
+  );
+  function visit(node) {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+      imports.add(node.moduleSpecifier.text);
+    }
+    if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      imports.add(node.moduleSpecifier.text);
+    }
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.Identifier && node.expression.text === "require" && node.arguments.length === 1 && ts.isStringLiteral(node.arguments[0])) {
+      imports.add(node.arguments[0].text);
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return imports;
+}
+function resolveImports(rawImports, basePackage, currentModule, isPackage) {
+  const resolved = /* @__PURE__ */ new Set();
+  for (const imp of rawImports) {
+    if (imp.startsWith("./") || imp.startsWith("../")) {
+      if (!currentModule) continue;
+      const moduleParts = currentModule.split(".");
+      let dirParts;
+      if (isPackage) {
+        dirParts = [...moduleParts];
+      } else {
+        dirParts = moduleParts.slice(0, -1);
+      }
+      const segments = imp.split("/");
+      for (const seg of segments) {
+        if (seg === ".") continue;
+        if (seg === "..") {
+          dirParts.pop();
+        } else {
+          dirParts.push(seg);
+        }
+      }
+      const resolvedModule = dirParts.join(".");
+      if (resolvedModule === basePackage || resolvedModule.startsWith(basePackage + ".")) {
+        resolved.add(resolvedModule);
+      }
+    } else if (imp === basePackage || imp.startsWith(basePackage + "/")) {
+      resolved.add(imp.replaceAll("/", "."));
+    }
+  }
+  return resolved;
+}
+function findSourceFiles(dir) {
+  const results = [];
+  function walk(d) {
+    const entries = readdirSync(d);
+    for (const entry of entries) {
+      if (entry === "node_modules" || entry === "dist" || entry === ".git") {
+        continue;
+      }
+      const full = join(d, entry);
+      const stat = statSync(full);
+      if (stat.isDirectory()) {
+        walk(full);
+      } else if (SUPPORTED_EXTENSIONS.has(extname2(entry))) {
+        results.push(full);
+      }
+    }
+  }
+  walk(dir);
+  return results;
+}
+function buildDependencyGraph(srcDir, basePackage) {
+  const graph = /* @__PURE__ */ new Map();
+  const files = findSourceFiles(srcDir);
+  for (const file of files) {
+    const moduleName = fileToModule(file, srcDir);
+    if (!moduleName) continue;
+    let source;
+    try {
+      source = readFileSync2(file, "utf-8");
+    } catch (e) {
+      console.error(`Warning: could not read ${file}: ${e}`);
+      continue;
+    }
+    let rawImports;
+    try {
+      rawImports = extractImports(source, file);
+    } catch (e) {
+      console.error(`Warning: could not parse ${file}: ${e}`);
+      continue;
+    }
+    const isPackage = INDEX_BASENAMES.has(basename(file));
+    const deps = resolveImports(rawImports, basePackage, moduleName, isPackage);
+    deps.delete(moduleName);
+    graph.set(moduleName, deps);
+  }
+  return graph;
+}
+function findCycles(graph) {
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = /* @__PURE__ */ new Map();
+  const path2 = [];
+  const cycles = [];
+  function dfs(node) {
+    color.set(node, GRAY);
+    path2.push(node);
+    const neighbors = graph.get(node) ?? /* @__PURE__ */ new Set();
+    for (const neighbor of [...neighbors].sort()) {
+      if (color.get(neighbor) === GRAY && path2.includes(neighbor)) {
+        const idx = path2.indexOf(neighbor);
+        cycles.push([...path2.slice(idx), neighbor]);
+      } else if ((color.get(neighbor) ?? WHITE) === WHITE) {
+        dfs(neighbor);
+      }
+    }
+    path2.pop();
+    color.set(node, BLACK);
+  }
+  for (const node of [...graph.keys()].sort()) {
+    if ((color.get(node) ?? WHITE) === WHITE) {
+      dfs(node);
+    }
+  }
+  const unique = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const cycle of cycles) {
+    const ring = cycle.slice(0, -1);
+    let minVal = ring[0];
+    let minIdx = 0;
+    for (let i = 1; i < ring.length; i++) {
+      if (ring[i] < minVal) {
+        minVal = ring[i];
+        minIdx = i;
+      }
+    }
+    const normalized = [...ring.slice(minIdx), ...ring.slice(0, minIdx)].join(",");
+    if (!seen.has(normalized)) {
+      seen.add(normalized);
+      unique.push(cycle);
+    }
+  }
+  return unique;
+}
+function checkCircularImports(srcDir, basePackage) {
+  let stat;
+  try {
+    stat = statSync(srcDir);
+  } catch {
+    console.error(`Error: ${srcDir}/ directory not found`);
+    return 1;
+  }
+  if (!stat.isDirectory()) {
+    console.error(`Error: ${srcDir}/ is not a directory`);
+    return 1;
+  }
+  const graph = buildDependencyGraph(srcDir, basePackage);
+  console.log(`Scanned ${graph.size} modules`);
+  const cycles = findCycles(graph);
+  if (cycles.length > 0) {
+    console.log(`
+Found ${cycles.length} circular import(s):
+`);
+    for (let i = 0; i < cycles.length; i++) {
+      console.log(`  Cycle ${i + 1}: ${cycles[i].join(" -> ")}`);
+    }
+    console.log();
+    return 1;
+  }
+  console.log("No circular imports detected.");
+  return 0;
+}
+
+// src/config.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join2 } from "path";
+function loadConfig(projectDir) {
+  const dir = projectDir ?? process.cwd();
+  const pkgPath = join2(dir, "package.json");
+  let raw;
+  try {
+    raw = readFileSync3(pkgPath, "utf-8");
+  } catch {
+    return {};
+  }
+  const pkg = JSON.parse(raw);
+  const apdev = pkg["apdev"];
+  if (apdev && typeof apdev === "object" && !Array.isArray(apdev)) {
+    return apdev;
+  }
+  return {};
+}
+
+// src/cli.ts
+function getVersion() {
+  const thisDir = typeof __dirname !== "undefined" ? __dirname : dirname(fileURLToPath2(import.meta.url));
+  const pkgPath = join3(thisDir, "..", "package.json");
+  try {
+    const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function getReleaseScript() {
+  const thisDir = typeof __dirname !== "undefined" ? __dirname : dirname(fileURLToPath2(import.meta.url));
+  return join3(thisDir, "..", "release.sh");
+}
+function buildProgram() {
+  const program2 = new Command();
+  program2.name("apdev").description("Shared development tools for TypeScript/JavaScript projects").version(getVersion());
+  program2.command("check-chars").description("Validate files contain only allowed characters").argument("<files...>", "Files to check").action((files) => {
+    const resolved = files.map((f) => resolve(f));
+    const code = checkPaths(resolved);
+    process.exit(code);
+  });
+  program2.command("check-imports").description("Detect circular imports in a JS/TS package").option("--package <name>", "Base package name (e.g. mylib). Reads from package.json apdev config if omitted.").option("--src-dir <dir>", "Source directory containing the package (default: src)").action((opts) => {
+    const config = loadConfig();
+    const basePackage = opts.package ?? config["base_package"];
+    const srcDir = opts.srcDir ?? config["src_dir"] ?? "src";
+    if (!basePackage) {
+      console.error(
+        'Error: --package is required (or set base_package in package.json "apdev" field)'
+      );
+      process.exit(1);
+    }
+    const code = checkCircularImports(resolve(srcDir), basePackage);
+    process.exit(code);
+  });
+  program2.command("release").description("Interactive release automation (build, tag, GitHub release, npm publish)").option("--yes, -y", "Auto-accept all defaults (silent mode)").argument("[version]", "Version to release (auto-detected from package.json if omitted)").action((version, opts) => {
+    const script = getReleaseScript();
+    try {
+      readFileSync4(script);
+    } catch {
+      console.error("Error: release.sh not found in package");
+      process.exit(1);
+    }
+    const args = ["bash", script];
+    if (opts?.yes) args.push("--yes");
+    if (version) args.push(version);
+    try {
+      execFileSync(args[0], args.slice(1), {
+        stdio: "inherit",
+        env: process.env
+      });
+    } catch (e) {
+      const err = e;
+      process.exit(err.status ?? 1);
+    }
+  });
+  return program2;
+}
+var program = buildProgram();
+program.parse();
+export {
+  buildProgram
+};