shingan-lint 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hatyibei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# shingan-lint
+
+> AI Agent Workflow Static Analyzer — `npx`-installable wrapper for [Shingan](https://github.com/hatyibei/shingan).
+
+```bash
+# zero-install one-shot
+npx shingan-lint analyze --format adk-go --input ./agents
+
+# project-local
+pnpm add -D shingan-lint
+pnpm exec shingan analyze --format json --input ./testdata/buggy.json
+
+# global
+npm install -g shingan-lint
+shingan analyze --since main
+```
+
+## What it does
+
+Shingan detects 20 classes of design-time bugs in AI agent workflows **before they ship**:
+
+- **Infinite loops** (`loop_guard`, `cycle_detection`)
+- **Cost explosions** (`cost_estimation`, `retry_storm`, `max_parallel_branches`)
+- **PII / prompt injection** (`pii_leak_scanner`, `prompt_injection_sink`, `secret_in_prompt_template`)
+- **Code-execution risk** (`eval_missing`, `dynamic_node_construction`)
+- **Misconfiguration** (`deprecated_model`, `model_card_mismatch`, `temperature_misuse`)
+- **Architectural smells** (`circular_dep_agents`, `unbounded_tool_arg`, `error_handler_checker`, `redundant_llm_call`, `unreachable_node`, `missing_eval_dataset`)
+
+Supported frameworks: **LangGraph** (Python), **ADK-Go** (Google), **n8n** / **SamuraiAI** / generic JSON.
+
+## How this package works
+
+`shingan-lint` is a thin Node wrapper. On `npm install` it downloads the platform-specific Go binary from the matching GitHub Release, verifies its SHA-256 against `checksums.txt`, and installs it under `~/.cache/shingan-lint/v<version>/`. Subsequent `shingan` invocations spawn the cached binary directly — no Node overhead at runtime.
+
+| Platform | Supported |
+|---|---|
+| Linux x64 / arm64 | ✅ |
+| macOS Intel / Apple Silicon | ✅ |
+| Windows x64 / arm64 | ✅ |
+
+If your platform isn't listed, install via Go directly:
+```bash
+go install github.com/hatyibei/shingan/cmd/shingan@v0.6.0
+```
+
+## Environment variables
+
+| var | purpose |
+|---|---|
+| `SHINGAN_SKIP_POSTINSTALL=1` | skip the download step (air-gapped CI; you provide the binary yourself) |
+| `SHINGAN_CACHE_DIR=/some/dir` | override `~/.cache` for the binary cache |
+| `SHINGAN_DOWNLOAD_BASE=https://mirror/...` | mirror base URL (corporate proxies) |
+
+## Documentation
+
+Full rule list, ADRs, LSP setup, and contributing guide live in the main repository:
+- [README](https://github.com/hatyibei/shingan)
+- [Rule authoring guide](https://github.com/hatyibei/shingan/blob/main/docs/rule-authoring.md)
+- [LSP integration](https://github.com/hatyibei/shingan/blob/main/docs/lsp.md)
+- [ADRs](https://github.com/hatyibei/shingan/blob/main/shingan-adr.md)
+
+## License
+
+MIT — see [LICENSE](https://github.com/hatyibei/shingan/blob/main/LICENSE).

package/bin/shingan.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// shingan CLI shim. Spawns the platform-specific Go binary downloaded
+// by postinstall.js into ~/.cache/shingan-lint/v<version>/<binary>.
+// Forwards every argv element + stdio + exit code, so `npx shingan
+// analyze --input ./testdata` behaves identically to running the
+// native binary directly.
+
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const PACKAGE_VERSION = require('../package.json').version;
+
+function platformTag() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === 'darwin' && a === 'arm64') return { os: 'darwin', arch: 'arm64', exe: 'shingan' };
+  if (p === 'darwin' && a === 'x64') return { os: 'darwin', arch: 'amd64', exe: 'shingan' };
+  if (p === 'linux' && a === 'arm64') return { os: 'linux', arch: 'arm64', exe: 'shingan' };
+  if (p === 'linux' && a === 'x64') return { os: 'linux', arch: 'amd64', exe: 'shingan' };
+  if (p === 'win32' && a === 'arm64') return { os: 'windows', arch: 'arm64', exe: 'shingan.exe' };
+  if (p === 'win32' && a === 'x64') return { os: 'windows', arch: 'amd64', exe: 'shingan.exe' };
+  throw new Error(`shingan-lint: unsupported platform/arch combination: ${p}/${a}`);
+}
+
+function cacheDir() {
+  const base = process.env.SHINGAN_CACHE_DIR ||
+    process.env.XDG_CACHE_HOME ||
+    path.join(os.homedir(), '.cache');
+  return path.join(base, 'shingan-lint', `v${PACKAGE_VERSION}`);
+}
+
+function binaryPath() {
+  const t = platformTag();
+  return path.join(cacheDir(), t.exe);
+}
+
+function main() {
+  const bin = binaryPath();
+  if (!fs.existsSync(bin)) {
+    console.error(
+      `shingan-lint: binary not found at ${bin}\n` +
+      `Run \`npm rebuild shingan-lint\` (or \`pnpm rebuild shingan-lint\`) to re-trigger postinstall, ` +
+      `or download manually from https://github.com/hatyibei/shingan/releases/tag/v${PACKAGE_VERSION}`
+    );
+    process.exit(1);
+  }
+  const child = spawn(bin, process.argv.slice(2), { stdio: 'inherit' });
+  child.on('error', (err) => {
+    console.error(`shingan-lint: failed to exec ${bin}: ${err.message}`);
+    process.exit(1);
+  });
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      // Mirror the signal: re-raise so shells see e.g. 130 for SIGINT.
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code === null ? 1 : code);
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "shingan-lint",
+  "version": "0.6.1",
+  "description": "AI Agent Workflow Static Analyzer — detect infinite loops, cost explosions, PII leaks, prompt injection sinks before execution. CLI wrapper that downloads the platform-specific Go binary from GitHub Releases.",
+  "keywords": [
+    "ai-agent",
+    "workflow",
+    "static-analysis",
+    "lint",
+    "linter",
+    "langgraph",
+    "adk",
+    "samurai",
+    "llm",
+    "prompt-injection",
+    "shingan"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/hatyibei/shingan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hatyibei/shingan.git",
+    "directory": "npm"
+  },
+  "bugs": {
+    "url": "https://github.com/hatyibei/shingan/issues"
+  },
+  "author": "hatyibei <hathibei7@gmail.com>",
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "bin": {
+    "shingan": "./bin/shingan.js"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/postinstall.js"
+  },
+  "files": [
+    "bin/shingan.js",
+    "scripts/postinstall.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "tar": "^7.4.3"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// shingan-lint postinstall: downloads the platform-specific Go binary
+// from the matching GitHub Release tag, verifies it via the
+// checksums.txt sha256 entry, extracts it from the goreleaser tarball,
+// and installs it under ~/.cache/shingan-lint/v<version>/.
+//
+// Skipped silently when SHINGAN_SKIP_POSTINSTALL=1 (CI mirroring use
+// cases like air-gapped builds where the binary is provided
+// externally).
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { pipeline } = require('stream/promises');
+const tar = require('tar');
+
+const PACKAGE_VERSION = require('../package.json').version;
+
+function platformTag() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === 'darwin' && a === 'arm64') return { os: 'darwin', arch: 'arm64', ext: 'tar.gz', exe: 'shingan' };
+  if (p === 'darwin' && a === 'x64') return { os: 'darwin', arch: 'amd64', ext: 'tar.gz', exe: 'shingan' };
+  if (p === 'linux' && a === 'arm64') return { os: 'linux', arch: 'arm64', ext: 'tar.gz', exe: 'shingan' };
+  if (p === 'linux' && a === 'x64') return { os: 'linux', arch: 'amd64', ext: 'tar.gz', exe: 'shingan' };
+  if (p === 'win32' && a === 'arm64') return { os: 'windows', arch: 'arm64', ext: 'zip', exe: 'shingan.exe' };
+  if (p === 'win32' && a === 'x64') return { os: 'windows', arch: 'amd64', ext: 'zip', exe: 'shingan.exe' };
+  throw new Error(`shingan-lint: unsupported platform/arch: ${p}/${a}`);
+}
+
+function cacheDir() {
+  const base = process.env.SHINGAN_CACHE_DIR ||
+    process.env.XDG_CACHE_HOME ||
+    path.join(os.homedir(), '.cache');
+  return path.join(base, 'shingan-lint', `v${PACKAGE_VERSION}`);
+}
+
+function archiveName(tag) {
+  return `shingan_${PACKAGE_VERSION}_${tag.os}_${tag.arch}.${tag.ext}`;
+}
+
+function releaseURL(tag) {
+  const base = process.env.SHINGAN_DOWNLOAD_BASE ||
+    `https://github.com/hatyibei/shingan/releases/download/v${PACKAGE_VERSION}`;
+  return `${base}/${archiveName(tag)}`;
+}
+
+function checksumURL() {
+  const base = process.env.SHINGAN_DOWNLOAD_BASE ||
+    `https://github.com/hatyibei/shingan/releases/download/v${PACKAGE_VERSION}`;
+  return `${base}/checksums.txt`;
+}
+
+async function fetchBuffer(url) {
+  // Node 18+ has global fetch. Follow redirects (GitHub returns 302 to S3).
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) {
+    throw new Error(`download ${url} failed: HTTP ${res.status}`);
+  }
+  const ab = await res.arrayBuffer();
+  return Buffer.from(ab);
+}
+
+async function fetchText(url) {
+  const buf = await fetchBuffer(url);
+  return buf.toString('utf8');
+}
+
+function sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+function findExpectedHash(checksumsText, archiveName) {
+  // checksums.txt format: "<hash>  <filename>" per line
+  for (const line of checksumsText.split('\n')) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length === 2 && parts[1] === archiveName) {
+      return parts[0];
+    }
+  }
+  return null;
+}
+
+async function extractTar(buf, dest, tag) {
+  // Write to temp file so `tar` can stream it back.
+  const tmpFile = path.join(dest, `_archive.${tag.ext}`);
+  fs.writeFileSync(tmpFile, buf);
+  try {
+    if (tag.ext === 'tar.gz') {
+      await tar.x({ file: tmpFile, cwd: dest, strict: true });
+    } else if (tag.ext === 'zip') {
+      // Minimal zip extraction without an extra dependency: shell out.
+      const { execFileSync } = require('child_process');
+      execFileSync('powershell.exe', [
+        '-NoProfile',
+        '-Command',
+        `Expand-Archive -Path "${tmpFile}" -DestinationPath "${dest}" -Force`,
+      ], { stdio: 'inherit' });
+    } else {
+      throw new Error(`unknown archive ext: ${tag.ext}`);
+    }
+  } finally {
+    fs.unlinkSync(tmpFile);
+  }
+}
+
+async function main() {
+  if (process.env.SHINGAN_SKIP_POSTINSTALL === '1') {
+    console.log('shingan-lint: SHINGAN_SKIP_POSTINSTALL=1 set, skipping binary download.');
+    return;
+  }
+
+  let tag;
+  try {
+    tag = platformTag();
+  } catch (e) {
+    console.error(`shingan-lint: ${e.message}`);
+    console.error(`Supported: darwin/arm64, darwin/x64, linux/arm64, linux/x64, win32/arm64, win32/x64.`);
+    console.error(`If your platform is unsupported, install via: go install github.com/hatyibei/shingan/cmd/shingan@v${PACKAGE_VERSION}`);
+    process.exit(0); // exit 0 so CI installs don't break — user gets actionable error on first invoke
+  }
+
+  const dest = cacheDir();
+  const binPath = path.join(dest, tag.exe);
+  if (fs.existsSync(binPath)) {
+    console.log(`shingan-lint: binary already cached at ${binPath}`);
+    return;
+  }
+
+  fs.mkdirSync(dest, { recursive: true });
+
+  const archive = archiveName(tag);
+  const url = releaseURL(tag);
+  console.log(`shingan-lint: downloading ${archive} from ${url}`);
+
+  let archiveBuf;
+  try {
+    archiveBuf = await fetchBuffer(url);
+  } catch (e) {
+    console.error(`shingan-lint: download failed: ${e.message}`);
+    console.error(`If the release was just published, GitHub may need a few seconds to propagate.`);
+    process.exit(1);
+  }
+
+  // Verify checksum if checksums.txt is reachable. Soft-fail when the
+  // checksum file is missing (e.g. early-stage release without
+  // goreleaser's checksum step), so users still get a usable binary
+  // — at the cost of trust on first install.
+  try {
+    const checksumsText = await fetchText(checksumURL());
+    const expected = findExpectedHash(checksumsText, archive);
+    if (expected) {
+      const actual = sha256(archiveBuf);
+      if (actual !== expected) {
+        throw new Error(`sha256 mismatch: expected ${expected}, got ${actual}`);
+      }
+      console.log(`shingan-lint: sha256 verified (${expected.slice(0, 12)}…)`);
+    } else {
+      console.warn(`shingan-lint: ${archive} not found in checksums.txt — proceeding without verification`);
+    }
+  } catch (e) {
+    console.warn(`shingan-lint: checksum verification skipped: ${e.message}`);
+  }
+
+  await extractTar(archiveBuf, dest, tag);
+
+  if (!fs.existsSync(binPath)) {
+    console.error(`shingan-lint: binary ${tag.exe} missing after extraction in ${dest}.`);
+    console.error(`Archive may have a different layout than expected. Files extracted:`);
+    for (const f of fs.readdirSync(dest)) console.error(`  ${f}`);
+    process.exit(1);
+  }
+
+  // Ensure executable bit (no-op on Windows).
+  try { fs.chmodSync(binPath, 0o755); } catch (_) {}
+
+  console.log(`shingan-lint: installed ${tag.exe} → ${binPath}`);
+}
+
+main().catch((err) => {
+  console.error(`shingan-lint: postinstall failed: ${err.stack || err.message}`);
+  process.exit(1);
+});