unguard 0.1.0

package/bin/unguard.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const binDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(binDir, "..");
+const configPath = path.join(packageRoot, "sgconfig.yml");
+const localBinDir = path.join(packageRoot, "node_modules", ".bin");
+
+const rawArgs = process.argv.slice(2);
+const firstArg = rawArgs[0];
+
+if (firstArg === "-h" || firstArg === "--help") {
+  console.log(
+    "unguard: data-shape AST checker\n\nUsage:\n  unguard scan [paths...] [ast-grep scan options]\n  unguard scan [paths...] --strict\n  unguard [paths...] [ast-grep scan options]\n\nExamples:\n  unguard scan src\n  unguard scan src --filter no-loose-null-check\n  unguard scan src --strict\n  unguard src --strict\n",
+  );
+  process.exit(0);
+}
+
+const isScanCommand = firstArg === "scan";
+const userArgs = isScanCommand ? rawArgs.slice(1) : rawArgs;
+
+const forwardedArgs = [];
+let strictMode = false;
+for (const arg of userArgs) {
+  if (arg === "--strict") {
+    strictMode = true;
+    continue;
+  }
+  forwardedArgs.push(arg);
+}
+
+const scanArgs = ["scan", "--config", configPath, ...forwardedArgs];
+if (strictMode) {
+  scanArgs.push("--error");
+}
+
+const astGrepBinary = process.platform === "win32" ? "ast-grep.cmd" : "ast-grep";
+const envPath = process.env.PATH
+  ? `${localBinDir}${path.delimiter}${process.env.PATH}`
+  : localBinDir;
+
+const result = spawnSync(astGrepBinary, 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);
+}
+
+process.exit(result.status ?? 0);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "unguard",
+  "version": "0.1.0",
+  "description": "Prove data-shape guarantees with ast-grep rule packs",
+  "author": "TwoAbove",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TwoAbove/unguard.git"
+  },
+  "homepage": "https://github.com/TwoAbove/unguard#readme",
+  "bugs": {
+    "url": "https://github.com/TwoAbove/unguard/issues"
+  },
+  "type": "module",
+  "bin": {
+    "unguard": "./bin/unguard.mjs"
+  },
+  "files": ["bin", "rules", "sgconfig.yml"],
+  "scripts": {
+    "scan": "node ./bin/unguard.mjs scan .",
+    "scan:strict": "node ./bin/unguard.mjs scan . --strict",
+    "test:rules": "ast-grep test -c sgconfig.yml",
+    "test:rules:update": "ast-grep test -c sgconfig.yml -U",
+    "prepublishOnly": "npm run test:rules"
+  },
+  "dependencies": {
+    "@ast-grep/cli": "^0.39.4"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/rules/no-loose-null-check.yml

@@ -0,0 +1,8 @@
+id: no-loose-null-check
+language: TypeScript
+severity: warning
+message: Replace loose null checks with explicit upstream guarantees or strict checks
+rule:
+  any:
+    - pattern: $VALUE == null
+    - pattern: $VALUE != null

package/rules/no-nested-existence-guard.yml

@@ -0,0 +1,8 @@
+id: no-nested-existence-guard
+language: TypeScript
+severity: warning
+message: Nested existence guards indicate missing boundary proof; enforce shape upstream
+rule:
+  any:
+    - pattern: if ($OBJ && $OBJ.$PROP) { $$$BODY }
+    - pattern: if ($OBJ && $OBJ.$PROP) $STMT

package/rules/no-optional-chain-fallback.yml

@@ -0,0 +1,9 @@
+id: no-optional-chain-fallback
+language: TypeScript
+severity: warning
+message: Remove optional-chain fallback and prove this shape upstream at the boundary
+rule:
+  pattern: $VALUE ?? $DEFAULT
+constraints:
+  VALUE:
+    regex: \?\.

package/rules/no-property-nullish-fallback.yml

@@ -0,0 +1,12 @@
+id: no-property-nullish-fallback
+language: TypeScript
+severity: warning
+message: Property nullish fallback hides upstream guarantees; validate earlier or throw
+rule:
+  pattern: $VALUE ?? $DEFAULT
+constraints:
+  VALUE:
+    all:
+      - kind: member_expression
+      - not:
+          regex: \?\.

package/sgconfig.yml

@@ -0,0 +1,4 @@
+ruleDirs:
+  - rules
+testConfigs:
+  - testDir: rule-tests