npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@pleaseai/ast-grep-config

v0.1.0

Published

ast-grep rules that keep code agent-navigable (greppable symbols, dedicated error files, no in-source tests)

Readme

@pleaseai/ast-grep-config

English | 한국어

ast-grep rules that keep a codebase navigable for coding agents: public symbols you can find by name, error types in a designated file, and no tests inside source files. This package is the layer-2 (structural) side of ADR-0022 for TypeScript, Dart, Kotlin, Java, and Rust. The layer-3 path checker (file names, test paths, shared test helpers) is please-style check in @pleaseai/code-style, which uses this package's extract/ rules.

Every rule ships as a warning. Nothing here fails a build unless you raise a rule's severity in your own config.

Install

bun add -D @pleaseai/ast-grep-config @ast-grep/cli

bunx @pleaseai/code-style init does this for you and writes sgconfig.yml (select ast-grep). @ast-grep/cli is a peer dependency that provides the ast-grep binary; install it next to this package so ast-grep is on your project's bin path.

With bun, add "trustedDependencies": ["@ast-grep/cli"] to your package.json so its postinstall step runs; otherwise ast-grep prints a fallback warning on every call (the path checker is unaffected).

The five principles

| Slug | Principle | | --- | --- | | code-greppable-public-symbols | Public symbols are named declarations, so one name search finds the definition and every use. | | code-filename-matches-primary-symbol | A file with one public symbol is named after it (normalized to the language's file-name convention). | | code-error-types-in-dedicated-module | A module's error types live in its designated error file or package. | | test-path-derivable-from-source | Tests live under the toolchain's test root, at a path mirrored from the source they test. | | test-helpers-in-dedicated-location | Helpers shared by several tests live in the designated helper location. |

The checks run in two layers. Layer 2 is the ast-grep rules in this package; layer 3 is please-style check, a path checker for what ast-grep cannot see (file names, test paths, and which helpers are shared).

Rules

Point your project's sgconfig.yml at the rules:

# sgconfig.yml
ruleDirs:
  - node_modules/@pleaseai/ast-grep-config/rules
bunx ast-grep scan

Or use the package's own config without adding one:

bunx ast-grep scan -c node_modules/@pleaseai/ast-grep-config/sgconfig.yml

| Rule | Slug | Language | | --- | --- | --- | | ts-no-default-export | code-greppable-public-symbols | TypeScript | | tsx-no-default-export | code-greppable-public-symbols | TSX | | rust-no-glob-reexport | code-greppable-public-symbols | Rust | | ts-error-outside-errors-file | code-error-types-in-dedicated-module | TypeScript | | tsx-error-outside-errors-file | code-error-types-in-dedicated-module | TSX | | dart-error-outside-errors-file | code-error-types-in-dedicated-module | Dart | | kotlin-error-outside-errors-file | code-error-types-in-dedicated-module | Kotlin | | java-error-outside-error-package | code-error-types-in-dedicated-module | Java | | rust-error-outside-error-file | code-error-types-in-dedicated-module | Rust | | ts-no-in-source-test | test-path-derivable-from-source | TypeScript | | tsx-no-in-source-test | test-path-derivable-from-source | TSX |

Each rule has a README next to it with the reason, a wrong and a right example, and the steps to fix a violation. The warning message names the slug and the README path, so an agent can fix the violation from the message alone.

Files whose shape a framework dictates (config files, Nuxt 4 app/pages/ and app/layouts/, Nitro server/api/, Storybook stories, and so on) are excluded through each rule's ignores list. Nuxt 3 root layouts (pages/ without app/) are not; the ts-no-default-export README shows how to scope the rule for them.

extract/ holds the extraction rules please-style check runs. It is not in ruleDirs, so its matches never appear in ast-grep scan output.

License

MIT