@agentvibes/guardrails 0.1.0

package/README.md

@@ -0,0 +1,239 @@
+# @agentvibes/guardrails
+
+Verification toolkit that makes agents write simple code. One package holds the
+canonical ast-grep rule set (moved here from the agent-skills `defensive-errors`
+skill — this repo is now the source of truth; the skill and hooks consume
+builds of this package), the react structure check, an added-lines diff
+ratchet, and the shared biome/tsconfig presets.
+
+## Install
+
+```sh
+pnpm add -D @agentvibes/guardrails
+```
+
+Tools (ast-grep, biome) are not npm dependencies: the CLI resolves them from
+PATH, falls back to `mise x <tool>@<pin>` using the pins in this package's
+`mise.toml`, and prints a one-line install hint when neither works.
+
+Installing straight from git (`github:AgentVibes/guardrails#<sha>`) works —
+the `prepare` script builds `dist/` at install time — but pnpm blocks
+lifecycle scripts of git-hosted deps by default, and the unblock knob moved
+between pnpm versions:
+
+| pnpm | where to allow the build |
+|---|---|
+| 10.0–10.4 | `package.json` → `pnpm.onlyBuiltDependencies: ["@agentvibes/guardrails"]` |
+| 10.5+ | `pnpm-workspace.yaml` → `onlyBuiltDependencies: ["@agentvibes/guardrails"]` |
+| 11+ | `pnpm-workspace.yaml` → `allowBuilds` keyed by the exact resolved spec |
+
+(or install from the registry once the package is published).
+
+## Commands
+
+All subcommands accept `--json`.
+
+| command | what | exit |
+|---|---|---|
+| `guardrails verify [paths]` | full scan: rule canon + text-greps + structure (one component per file, 120-line error / 90-line warning) | 1 on any error-tier finding |
+| `guardrails verify-diff [--base R]` | ratchet: error-tier findings on lines your diff ADDED vs merge-base; falls back to whole-file, then whole-tree — never to silence | 1 on new findings only |
+| `guardrails doctor` | tool versions + resolution route, ruleset SHA, config discovery | 1 if a tool is missing |
+| `guardrails init` | writes `sgconfig.yml`, `biome.json` (extends the preset), and a detected-and-materialized `[stack]` in `.agentvibes/project.toml` | 0 |
+| `guardrails metrics [paths]` | per-component (loc, hooks, props, observer, JSX depth, branching), per-file (sloc, context-cost) and per-project metrics; `--check` compares the GATED set against the committed `.guardrails/metrics.json` baseline (recomputes facts, never trusts the file); `--update-baseline` tightens it (2% hysteresis, never loosens without `--force`); `--snapshot` appends a JSONL trend row | 1 on ratchet regression, 2 when `--check` finds no baseline |
+
+Gated (ratchet, lower = better): p90 component_loc, useState density,
+inline-map-row count, p90 context-cost, runInAction count, async-in-store,
+new-Map-in-store, reactions total, loading-boolean shapes. Everything else is
+observe-only.
+
+Counter provenance: runInAction / async-in-store / new-Map-in-store /
+inline-map-row are finding counts of the canon rules (`store-no-runinaction`,
+`store-async-method`, `store-new-map`, `inline-map-row` + tsx twins) — the
+metric counts exactly what `verify` gates. Note the rules' scoping:
+"store" means a class calling `make(Auto)Observable` (not a name/path
+heuristic), and `async_in_store` counts only async methods that mutate `this`
+WITHOUT a `runInAction` patch — the patched ones are already in
+`runInAction_count`, so the two counters partition the should-be-`flow()`
+population without double counting. `reactions_total` is a direct AST
+count (no rule yet). `loading_boolean_shapes` is deliberately NOT the
+`state-loading-boolean-shape` rule: the rule fires only on type-level shapes
+where the outcome is recorded twice (loading flag + second outcome/payload
+field), while the metric also counts lone boolean progress-flag declarations
+(`loading = false` class fields) — the wider Resource<T> migration target.
+
+## CI gate (reusable workflow)
+
+Add the whole gate as one job:
+
+```yaml
+jobs:
+  guardrails:
+    uses: AgentVibes/guardrails/.github/workflows/guardrails-gate.yml@v0
+    # with:
+    #   leaks: true        # recommended for public repos
+    #   base: origin/main  # override the merge-base ladder
+```
+
+It checks out with full history, installs the pinned toolchain via mise, runs
+`pnpm install --frozen-lockfile`, then BLOCKING `guardrails verify-diff` and
+`guardrails metrics --check` (skipped with a loud `::notice::` when the repo
+has no `.guardrails/metrics.json` baseline — never silently).
+
+Workspaces that reach outside their repo (`link:../<repo>/...` overrides,
+`../../<org>/<repo>` workspace globs) pass
+`sibling_repos: "owner/repo owner2/repo2"`: the gate then checks the main
+repo out at `repos/<org>/<repo>` depth and shallow-clones each sibling at its
+own `repos/<owner>/<name>`, reproducing a `gits/<org>/<repo>` disk layout so
+the relative escapes resolve. Private siblings additionally need
+`secrets: { sibling_token: <PAT with read on them> }` — the default job token
+cannot reach other repos. `@v0` is a
+moving tag that follows validated releases, actions-style; pin `@<commit-sha>`
+if your repo wants immutable supply-chain refs.
+
+**Mandatory adoption step — prove the gate can fail.** After wiring the job,
+open a throwaway PR containing an error-tier violation and watch it go red:
+
+```sh
+git checkout -b gate-red-team
+printf 'export const boom = (x: unknown) => x as any;\n' > gateRedTeam.ts
+git add gateRedTeam.ts && git commit -m "red-team the guardrails gate" && git push -u origin gate-red-team
+# open the PR → the guardrails job MUST fail on as-any-escape.
+# Then close the PR and delete the branch.
+```
+
+A gate that has never been seen red proves nothing — do not skip this.
+
+## Stop hook
+
+`guardrails hook-stop` is the "cannot say done over red findings" echelon: on
+Claude Code's Stop event it runs the verify-diff ratchet over the session's
+changed files and blocks the stop while NEW error-tier findings remain. Loop
+breaker built in: after 3 blocks in one session (env
+`GUARDRAILS_STOP_MAX_BLOCKS`) it stops blocking and prints a loud warning
+instead — a wedged agent is worse than undercleaned code, and CI holds the
+same line anyway. Like hook-postedit, it never fails the session on its own
+defects.
+
+```json
+{ "hooks": { "Stop": [ { "hooks": [{ "type": "command",
+  "command": "pnpm exec guardrails hook-stop" }] } ] } }
+```
+
+For a USER-level install (synced settings.json, per-machine tools), route
+both hooks through an opt-hook.sh-style wrapper that no-ops when the tool is
+absent on a host — a bare command errors on every event on machines without
+the package.
+
+## Iterate harness
+
+`guardrails iterate --task <file|text> --cmd '<runner>'` is the
+iterate-until-pass loop for cheap-model campaigns: run the agent command, run
+the gate ITSELF (never trusting the agent's report), feed the findings back as
+the next prompt's compact feedback, repeat to green or `--max` (default 6;
+`--gate` overrides the default `verify-diff`). The runner gets the prompt on
+stdin and via `$GUARDRAILS_PROMPT_FILE`, plus `$GUARDRAILS_ATTEMPT`:
+
+```sh
+guardrails iterate --task task.md \
+  --cmd 'claude -p "$(cat "$GUARDRAILS_PROMPT_FILE")" --model sonnet' \
+  --gate 'pnpm exec guardrails verify-diff && pnpm exec guardrails metrics --check'
+```
+
+Every attempt's tuple (agent exit, gate exit, gate tail, duration) is recorded
+and printed (`--json` for harness pipelines).
+
+## Post-edit hook
+
+`guardrails hook-postedit` is the Claude Code PostToolUse hook: it reads the
+hook JSON on stdin, and for an Edit/Write of a .ts/.tsx file scans just that
+file, gating the lines the edit actually changed (merge-base ladder; Write,
+untracked files, and unresolvable bases degrade to whole-file — never to
+silence). Error-tier findings emit a blocking decision, warnings attach as
+context. Wire it in settings.json:
+
+```json
+{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write",
+  "hooks": [{ "type": "command", "command": "pnpm exec guardrails hook-postedit" }] } ] } }
+```
+
+## Leak gate
+
+`guardrails leaks [paths]` is the public/private boundary gate: it scans every
+text file for credential patterns, runs gitleaks when available, and exits 1
+on any hit. The package ships only generic credential shapes; house marker
+lists ship via private plugins/config — `.guardrails/leaks.txt`, a
+`[leaks] patterns_file =` manifest entry, or the plugin contract's
+`leakPatterns()` hook (see `@agentvibes/guardrails/plugin`). Pattern files are
+one regex per line (`<id> <regex>`, `#` comments) and are themselves exempt
+from the scan. This repo runs the gate against itself in `pnpm check` and CI.
+
+## Deploy plugins
+
+`guardrails deploy [args…]` is an extension point, not a deployer: the public
+CLI resolves a plugin — `plugin = "<npm name>"` under `[deploy]` in
+`.agentvibes/project.toml`, or a single `guardrails-plugin-*` dependency — and
+hands it the args plus the `[deploy]` table. A plugin exports (default or
+named `plugin`) an object `{ name, deploy(args, context) }`; the contract type
+ships as `@agentvibes/guardrails/plugin`. All topology facts (hosts, orgs,
+registries, SSO) live in private plugin packages; `guardrails leaks` enforces
+that this package contains none.
+
+## Presets
+
+```jsonc
+// biome.json
+{ "extends": ["@agentvibes/guardrails/biome"] }
+// tsconfig.json
+{ "extends": "@agentvibes/guardrails/tsconfig" }
+```
+
+## Rules and fixtures
+
+- `rules/` — the canon. Stable ids, each message is a mini-manual (why + fix).
+  Suppress a genuine false positive with
+  `// ast-grep-ignore: <rule-id> -- <why>` on the line above.
+- `rules/__fixtures__/` — bad/good fixture pairs; `pnpm test:rules` asserts
+  exact hit counts in both directions (a rule that fails to load fails the
+  test — silence is not a pass).
+- `structure/` — the `component-decl` marker rule the CLI turns into
+  `react-multi-component` / `react-component-too-long` /
+  `react-component-needs-folder` findings.
+- `candidates/` — triaged in wave 2. Three PPA R-rules were promoted into
+  `rules/`; the eight that remain are repo-local by decision, with the reason
+  for each recorded in `candidates/README.md`. Still loaded nowhere.
+
+Per-repo severity RAISE: a repo that held a rule stricter than the canon keeps
+its gate via `[severity]` in `.agentvibes/project.toml`
+(`zod-optional-nullable = "error"`) — applied through ast-grep's native
+`--error=<rule-id>` in verify, verify-diff and the post-edit hook, so no
+same-id rule fork is ever needed. Raise-only: downgrades and unknown rule ids
+are refused (exit 2); weakening has its own sanctioned homes (warn-tier biome
+deviation, `[verify] exclude` for vendored trees, justified per-line
+`ast-grep-ignore`).
+
+## Repo-local extra rules
+
+A rule that encodes ONE repo's convention does not belong in the canon — but it
+should still run. `guardrails init` already writes the second `ruleDir`
+commented out; uncomment it and drop the rule in:
+
+```yaml
+# sgconfig.yml
+ruleDirs:
+  - node_modules/@agentvibes/guardrails/rules
+  - .ast-grep/rules          # repo-local extras
+```
+
+Both directories load together and findings print their own rule id, so a local
+rule suppresses under its own name. Verified: a canon rule and a repo-local rule
+firing side by side in one `ast-grep scan -c sgconfig.yml` run.
+
+Keep local ids distinct from canon ids — ast-grep refuses to load two rules with
+the same id, and a repo-local override of a canon rule is a silent fork rather
+than a fix. If a local rule turns out to be generally useful, promote it here
+with fixtures instead of copying it into a second repo.
+
+## Development
+
+`pnpm check` = build (tsc) + biome + fixture harness + gate-can-go-red test.
+CI runs exactly that, blocking.

package/candidates/README.md

@@ -0,0 +1,30 @@
+# candidates/ — triaged, wave 2
+
+The 11 PPA R-rules that came verbatim from `merkle-substrate/apps/ppa/.ast-grep/rules/`
+have been triaged. **Three were promoted into `rules/` and deleted from here.**
+The eight below stay **repo-local**: they encode a PPA convention rather than a
+house rule, so they keep living in the PPA repo and load through the repo-local
+`ruleDirs` entry (see the package README, "Repo-local extra rules").
+
+They are still NOT in the package `sgconfig.yml` and load nowhere from here.
+
+## Promoted to canon
+
+| R-rule | canon id | why |
+|---|---|---|
+| r4-ternary-on-discriminator | `discriminator-ternary` | 18 hits outside PPA, and measured **disjoint** from both rules it looked like a duplicate of: `∩ jsx-ternary = 0`, `∩ kind-if-without-match = 0`. The three partition the space — `if` on a discriminator, ternary yielding JSX, ternary yielding values. A `not: is-jsx` clause makes that disjointness structural rather than lucky. |
+| r14-literal-union-in-component | `literal-union-in-component` | Already a house rule — report §8 bans string-literal unions from component files in the `ui/` tier. Globs generalised from `apps/ppa/**` to `**/components/**`, `**/screens/**`, `**/app/**`. |
+| r1a-hardcoded-url-in-component | `hardcoded-url-in-component` | Enforces CLAUDE.md "No localhost": every service URL comes from `dev url`, never a literal. Same reusability boundary `ui-imports-app-store` guards from the other side. |
+
+## Staying repo-local
+
+| R-rule | why it is not canon |
+|---|---|
+| r10-as-cast | 121 hits in tg-gallery + observatory alone. `as Type` is legitimate at boundaries this codebase does not yet route through Zod, and `as-any-escape` already covers the escape-hatch half. Canon-promoting it buys a suppression campaign. |
+| r1d-scattered-numeric-const-in-component | 25 hits, but "module-level ALL_CAPS numeric belongs in tokens.ts" is a PPA layout convention, not a house rule. |
+| r2-helper-fn-in-tsx | Its own message admits "unavoidable false positives — it can't distinguish PascalCase observer-wrapped components from helpers". A rule its author documents as broken does not become canon. (The stated cause, "metavariable regex unsupported in ast-grep 0.42", no longer holds on 0.45 — so a corrected version is a real candidate for a later wave, but it would be a new rule, not this one.) |
+| r3-hooks-outside-layout | Bans useState/useEffect/useMemo outside two named layout files. That is PPA's architectural stance; the house rule (C24) permits a hook that owns DOM or lifecycle, and `usePageStore` is sanctioned. |
+| r6-jsx-comment-smell | "A JSX comment is a smell" at severity `hint`. House code uses JSX comments for real explanation (tg-gallery, observatory); this is a PPA style preference. |
+| r7-raw-hsl-outside-tokens | Points at `apps/ppa/lib/tokens.ts`. Tailwind remains a legal manifest value for web apps, so a raw-colour ban cannot be unconditional canon. |
+| r8-inline-style-prop | **Stale as well as local.** It tells you to prefer NativeWind `className` over `style={{}}` — but decision #10 (2026-08-28) converges PPA to *theme-inline*, which makes inline style from a theme hook the intended idiom. The rule now argues against the decision it lives under; PPA should retire or invert it. |
+| r9-optional-store-arg | Flags every `?:` parameter and property in store source. The principle is house-wide (make invalid states unrepresentable), but the rule as written has no way to tell a genuine optional from a modelled one, which is why PPA scoped it to two directories with three ignores. |

package/candidates/r10-as-cast.yml

@@ -0,0 +1,24 @@
+id: r10-as-cast
+language: typescript
+severity: warning
+message: |
+  R10 — `as Type` cast. Use Zod .safeParse() at boundaries, type guards,
+  or fix the source type. Allowed: `as const`, `as never` (test stubs),
+  `as any` (still flagged separately by defensive-errors as-any-escape).
+  See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R10.
+files:
+  - "apps/ppa-libs/store/src/**/*.ts"
+  - "apps/ppa/**/*.ts"
+  - "apps/ppa/**/*.tsx"
+ignores:
+  - "**/__tests__/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+rule:
+  pattern: '$EXPR as $TYPE'
+  not:
+    any:
+      - pattern: '$EXPR as const'
+      - pattern: '$EXPR as never'
+      - pattern: '$EXPR as any'
+      - pattern: '$EXPR as unknown'

package/candidates/r1d-scattered-numeric-const-in-component.yml

@@ -0,0 +1,13 @@
+id: r1d-scattered-numeric-const-in-component
+language: tsx
+severity: warning
+message: |
+  R1d — Module-level numeric ALL_CAPS constant in a component file.
+  Move to apps/ppa/lib/tokens.ts (layout dimensions) or a per-module
+  constants.ts (timeouts, thresholds, limits).
+  See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R1.
+files:
+  - "apps/ppa/components/**/*.tsx"
+rule:
+  kind: variable_declarator
+  regex: '^[A-Z][A-Z0-9_]+ = -?[0-9]'

package/candidates/r2-helper-fn-in-tsx.yml

@@ -0,0 +1,22 @@
+id: r2-helper-fn-in-tsx
+language: tsx
+severity: warning
+message: |
+  R2 — Helper function declared in a component file. Move to either:
+    - the appropriate MobX store as a `get` (computed) or method (action), or
+    - apps/ppa/lib/<scope>/ as a stateless utility.
+  Component files should be thin views; logic lives in stores.
+  Note: this rule has unavoidable false positives — it can't distinguish
+  PascalCase observer-wrapped components from helpers without metavariable
+  regex (unsupported in ast-grep 0.42). Filter visually or use the
+  scripts/lint/helpers-in-tsx.sh wrapper which adds a camelCase guard.
+  See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R2.
+files:
+  - "apps/ppa/components/**/*.tsx"
+rule:
+  any:
+    # Arrow functions WITH explicit return type — strongest signal of "helper"
+    - kind: variable_declarator
+      regex: '^[a-z][a-zA-Z0-9]* = .*\): [A-Za-z<>|& ]+ =>'
+    # function declarations
+    - pattern: 'function $NAME($$$): $RT { $$$ }'

package/candidates/r3-hooks-outside-layout.yml

@@ -0,0 +1,21 @@
+id: r3-hooks-outside-layout
+language: tsx
+severity: warning
+message: |
+  R3 — React hook (useState/useCallback/useMemo/useEffect) outside a
+  layout/page root. Promote local state to a ui-tier MobX store and
+  bind via plain props. The only legitimate hook callsites are:
+    - apps/ppa/app/_layout.tsx
+    - apps/ppa/app/(app)/_layout.tsx
+    - PageStoreManager.getOrCreate(...) wrapping at a route root
+    - Animation primitives (mark with `// hooks-ok: animation` comment)
+  See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R3.
+files:
+  - "apps/ppa/components/**/*.tsx"
+rule:
+  any:
+    - pattern: 'useState($$$)'
+    - pattern: 'useCallback($$$)'
+    - pattern: 'useMemo($$$)'
+    - pattern: 'useEffect($$$)'
+    - pattern: 'useReducer($$$)'

package/candidates/r6-jsx-comment-smell.yml

@@ -0,0 +1,14 @@
+id: r6-jsx-comment-smell
+language: tsx
+severity: hint
+message: |
+  R6 — JSX comment ({/* ... */}) is a smell. The element it labels
+  deserves a name — extract a named observer subcomponent.
+  Use the /refactor-jsx-comment slash command to extract.
+  See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R6.
+files:
+  - "apps/ppa/components/**/*.tsx"
+rule:
+  kind: jsx_expression
+  has:
+    kind: comment

package/candidates/r7-raw-hsl-outside-tokens.yml

@@ -0,0 +1,17 @@
+id: r7-raw-hsl-outside-tokens
+language: tsx
+severity: warning
+message: |
+  R7 — Raw hsl(...) string in a component. Use useTokens() and the
+  semantic tokens defined in apps/ppa/lib/tokens.ts. If the token
+  you need doesn't exist, ADD it to tokens.ts/themed-tokens.ts first.
+  See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R7
+  and AGENTS.md (HSL/tokens rule).
+files:
+  - "apps/ppa/components/**/*.tsx"
+ignores:
+  - "**/_fixture.ts"
+  - "**/__tests__/**"
+rule:
+  kind: string
+  regex: 'hsl\('

package/candidates/r8-inline-style-prop.yml

@@ -0,0 +1,13 @@
+id: r8-inline-style-prop
+language: tsx
+severity: hint
+message: |
+  R8 — Inline style={{}} prop. Prefer NativeWind className for static
+  values (color, spacing, layout, radius). Reserve style={{}} for
+  genuinely dynamic values: animated transforms, computed widths/positions.
+  See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R8.
+files:
+  - "apps/ppa/components/**/*.tsx"
+rule:
+  kind: jsx_attribute
+  regex: '^style=\{\{'

package/candidates/r9-optional-store-arg.yml

@@ -0,0 +1,24 @@
+id: r9-optional-store-arg
+language: typescript
+severity: warning
+message: |
+  R9 — Optional `?:` parameter or property in store API. Either every
+  caller passes it (required) or none do (don't define it). For "patch
+  any subset" shapes, model as a discriminated union of intents OR
+  split into N narrow methods.
+  Boundary cases (wrapping isomorphic-git, etc.) are exempt via the
+  ignores list below.
+  See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R9.
+files:
+  - "apps/ppa-libs/store/src/**/*.ts"
+  - "packages/gitapp-store/src/**/*.ts"
+ignores:
+  - "**/__tests__/**"
+  - "**/contents/iso-git/**"
+  - "**/operations.ts"
+rule:
+  any:
+    - kind: property_signature
+      regex: '\?:'
+    - kind: required_parameter
+      regex: '\?:'

package/configs/biome.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.10/schema.json",
+  "root": false,
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "includes": [
+      "**/*.ts",
+      "**/*.tsx",
+      "**/*.json",
+      "!**/dist",
+      "!**/node_modules",
+      "!**/*.tsbuildinfo",
+      "!pnpm-lock.yaml"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100,
+    "lineEnding": "lf"
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "trailingCommas": "all",
+      "semicolons": "always",
+      "arrowParentheses": "always",
+      "bracketSpacing": true
+    }
+  },
+  "json": {
+    "formatter": {
+      "indentWidth": 2,
+      "trailingCommas": "none"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "complexity": {
+        "useArrowFunction": "warn",
+        "useLiteralKeys": "error",
+        "useOptionalChain": "warn"
+      },
+      "correctness": {
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error",
+        "useExhaustiveDependencies": "warn"
+      },
+      "style": {
+        "noNonNullAssertion": "off",
+        "useAsConstAssertion": "error",
+        "useConst": "error",
+        "useFilenamingConvention": {
+          "level": "error",
+          "options": {
+            "requireAscii": true,
+            "filenameCases": ["camelCase", "PascalCase"]
+          }
+        },
+        "useImportType": "error",
+        "useNodejsImportProtocol": "error",
+        "useTemplate": "warn",
+        "useThrowOnlyError": "error"
+      },
+      "suspicious": {
+        "noConsole": {
+          "level": "warn",
+          "options": {
+            "allow": ["error", "warn"]
+          }
+        },
+        "noEmptyBlockStatements": "error",
+        "noExplicitAny": "error"
+      },
+      "performance": {
+        "noBarrelFile": "off"
+      }
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

package/configs/tsconfig.base.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true
+  }
+}

package/dist/astGrep.d.ts

@@ -0,0 +1,16 @@
+import type { Finding, Severity } from "./findings.js";
+export interface AstGrepRow {
+    ruleId: string;
+    file: string;
+    /** 1-based */
+    startLine: number;
+    /** inclusive line span of the matched node */
+    spanLines: number;
+    severity: Severity;
+    message: string;
+    metaText: (name: string) => string | undefined;
+}
+/** Run `ast-grep scan -c <config> --json` and return structured matches. */
+export declare function scan(configPath: string, targets: string[], extraArgs?: string[]): AstGrepRow[];
+/** Reportable (error/warning) rule findings, dropping marker/hint tiers. */
+export declare function scanFindings(configPath: string, targets: string[], extraArgs?: string[]): Finding[];

package/dist/astGrep.js

@@ -0,0 +1,48 @@
+import { spawnSync } from "node:child_process";
+import { resolveTool } from "./toolResolve.js";
+/** Run `ast-grep scan -c <config> --json` and return structured matches. */
+export function scan(configPath, targets, extraArgs = []) {
+    const tool = resolveTool("ast-grep");
+    const [cmd, ...prefix] = tool.argv;
+    if (cmd === undefined)
+        throw new Error("empty ast-grep argv");
+    const res = spawnSync(cmd, [...prefix, "scan", "-c", configPath, ...extraArgs, "--json", ...targets], {
+        encoding: "utf8",
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    if (res.error)
+        throw res.error;
+    const out = res.stdout.trim();
+    if (out === "")
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(out);
+    }
+    catch {
+        throw new Error(`ast-grep produced unparsable JSON (exit ${res.status}). stderr:\n${res.stderr.slice(0, 2000)}`);
+    }
+    return parsed.map((m) => ({
+        ruleId: m.ruleId,
+        file: m.file,
+        startLine: m.range.start.line + 1,
+        spanLines: m.range.end.line - m.range.start.line + 1,
+        severity: m.severity,
+        message: m.message,
+        metaText: (name) => m.metaVariables?.single?.[name]?.text,
+    }));
+}
+/** Reportable (error/warning) rule findings, dropping marker/hint tiers. */
+export function scanFindings(configPath, targets, extraArgs = []) {
+    return scan(configPath, targets, extraArgs)
+        .filter((r) => r.severity === "error" || r.severity === "warning")
+        .map((r) => ({
+        rule: r.ruleId,
+        severity: r.severity,
+        file: r.file,
+        line: r.startLine,
+        message: r.message,
+        source: "ast-grep",
+    }));
+}
+//# sourceMappingURL=astGrep.js.map

package/dist/astGrep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"astGrep.js","sourceRoot":"","sources":["../src/astGrep.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAuB/C,4EAA4E;AAC5E,MAAM,UAAU,IAAI,CAClB,UAAkB,EAClB,OAAiB,EACjB,YAAsB,EAAE;IAExB,MAAM,IAAI,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;IACnC,IAAI,GAAG,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC9D,MAAM,GAAG,GAAG,SAAS,CACnB,GAAG,EACH,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,EACzE;QACE,QAAQ,EAAE,MAAM;QAChB,SAAS,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;KAC7B,CACF,CAAC;IACF,IAAI,GAAG,CAAC,KAAK;QAAE,MAAM,GAAG,CAAC,KAAK,CAAC;IAC/B,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IAC1B,IAAI,MAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,2CAA2C,GAAG,CAAC,MAAM,eAAe,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAChG,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACxB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;QACjC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;QACpD,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI;KAClE,CAAC,CAAC,CAAC;AACN,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAC1B,UAAkB,EAClB,OAAiB,EACjB,YAAsB,EAAE;IAExB,OAAO,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC;SACxC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC;SACjE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,IAAI,EAAE,CAAC,CAAC,MAAM;QACd,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,SAAS;QACjB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,MAAM,EAAE,UAAmB;KAC5B,CAAC,CAAC,CAAC;AACR,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};