unguard 0.2.0 → 0.4.1

package/README.md

@@ -0,0 +1,113 @@
+# unguard
+
+Unguard your code. Defend agains overdefensive AI-generated code.
+
+Built on [oxc-parser](https://github.com/nicolo-ribaudo/oxc-parser-js).
+
+## Install
+
+```bash
+npm install -g unguard
+```
+
+or simply
+
+```bash
+npx unguard
+```
+
+## Usage
+
+```bash
+unguard src/
+unguard src/ --strict           # treat warnings as errors (CI)
+unguard src/ --filter no-any-cast  # run a single rule
+```
+
+Add `unguard` to your lint check.
+
+## Current Rules
+
+### Type system evasion
+
+| Rule | What it catches |
+|------|----------------|
+| `no-any-cast` | `x as any` |
+| `no-explicit-any-annotation` | `param: any`, `const x: any` |
+| `no-type-assertion` | `x as unknown as T` |
+| `no-ts-ignore` | `@ts-ignore` / `@ts-expect-error` |
+
+### Defensive code
+
+| Rule | What it catches |
+|------|----------------|
+| `no-optional-property-access` | `obj?.prop` |
+| `no-optional-element-access` | `obj?.[key]` |
+| `no-optional-call` | `fn?.()` |
+| `no-nullish-coalescing` | `x ?? fallback` |
+| `no-logical-or-fallback` | `x \|\| fallback` |
+| `no-null-ternary-normalization` | `x == null ? fallback : x` |
+| `no-non-null-assertion` | `x!` |
+| `no-double-negation-coercion` | `!!value` |
+| `no-redundant-existence-guard` | `obj && obj.prop` |
+
+### Error handling
+
+| Rule | What it catches |
+|------|----------------|
+| `no-empty-catch` | `catch {}` with no body |
+| `no-catch-return` | `catch { return fallback }` without rethrowing |
+| `no-error-rewrap` | `throw new Error(e.message)` without `{ cause: e }` |
+
+### Interface design
+
+| Rule | What it catches |
+|------|----------------|
+| `no-inline-type-in-params` | `fn(opts: { a: string; b: number })` |
+| `prefer-default-param-value` | Optional param reassigned with `??` in the body |
+| `prefer-required-param-with-guard` | `arg?: T` followed by `if (!arg) throw` |
+
+### Cross-file analysis
+
+| Rule | What it catches |
+|------|----------------|
+| `duplicate-type-declaration` | Same type shape in multiple files |
+| `duplicate-type-name` | Same exported type name, different shapes |
+| `duplicate-function-declaration` | Same function body in multiple files |
+| `duplicate-function-name` | Same exported function name, different bodies |
+| `optional-arg-always-used` | Optional param provided at every call site |
+| `explicit-null-arg` | `fn(null)` / `fn(undefined)` to project functions |
+
+### Imports
+
+| Rule | What it catches |
+|------|----------------|
+| `no-dynamic-import` | `import("./module")` |
+
+## Annotations
+
+Comments near flagged lines appear in the output as context:
+
+```typescript
+// intentional escape hatch for untyped AST access
+type AnyNode = Record<string, any>;
+```
+
+```txt
+file.ts:2:31 warning Explicit `any` annotation ... (intentional escape hatch for untyped AST access)
+```
+
+## API
+
+```typescript
+import { scan } from "unguard";
+
+const result = await scan({ paths: ["src/"] });
+for (const d of result.diagnostics) {
+  console.log(`${d.file}:${d.line} [${d.ruleId}] ${d.message}`);
+}
+```
+
+## License
+
+MIT

package/bin/unguard.mjs

@@ -1,80 +1,3 @@
 #!/usr/bin/env node
-
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import crossSpawn from "cross-spawn";
-
-const binDir = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.resolve(binDir, "..");
-const localBinDir = path.join(packageRoot, "node_modules", ".bin");
-
-const rulepacks = [
-  {
-    configPath: path.join(packageRoot, "rulepacks", "ts", "sgconfig.yml"),
-    globs: ["**/*.ts", "**/*.cts", "**/*.mts"],
-  },
-  {
-    configPath: path.join(packageRoot, "rulepacks", "tsx", "sgconfig.yml"),
-    globs: ["**/*.tsx"],
-  },
-];
-
-const rawArgs = process.argv.slice(2);
-const firstArg = rawArgs[0];
-
-if (firstArg === "-h" || firstArg === "--help") {
-  console.log(`unguard: data-shape AST checker
-
-Usage:
-  unguard scan [paths...] [ast-grep scan options]
-  unguard scan [paths...] --strict
-  unguard [paths...] [ast-grep scan options]
-
-Examples:
-  unguard scan src
-  unguard scan src --filter no-loose-nullish-check
-  unguard scan src --strict
-  unguard src --strict
-`);
-  process.exit(0);
-}
-
-const userArgs = firstArg === "scan" ? rawArgs.slice(1) : rawArgs;
-const strictMode = userArgs.includes("--strict");
-const forwardedArgs = userArgs.filter((a) => a !== "--strict");
-
-const envPath = process.env.PATH
-  ? `${localBinDir}${path.delimiter}${process.env.PATH}`
-  : localBinDir;
-
-let finalStatus = 0;
-for (const rulepack of rulepacks) {
-  const scanArgs = ["scan", "--config", rulepack.configPath, ...forwardedArgs];
-  for (const glob of rulepack.globs) {
-    scanArgs.push("--globs", glob);
-  }
-  if (strictMode) {
-    scanArgs.push("--error");
-  }
-
-  const result = crossSpawn.sync("ast-grep", scanArgs, {
-    stdio: "inherit",
-    env: { ...process.env, PATH: envPath },
-  });
-
-  if (result.error) {
-    if (result.error.code === "ENOENT") {
-      console.error(
-        "ast-grep binary not found. Run `npm install` in this package or install @ast-grep/cli globally.",
-      );
-    }
-    console.error(result.error.message);
-    process.exit(1);
-  }
-
-  if ((result.status ?? 0) !== 0) {
-    finalStatus = result.status ?? 1;
-  }
-}
-
-process.exit(finalStatus);
+import { main } from "../dist/cli.js";
+main(process.argv).then((code) => process.exit(code));