diff --git a/.github/instructions/agent-docusaurus-writer.instructions.md b/.github/instructions/agent-docusaurus-writer.instructions.md index 833d2402..19c17ee5 100644 --- a/.github/instructions/agent-docusaurus-writer.instructions.md +++ b/.github/instructions/agent-docusaurus-writer.instructions.md @@ -39,7 +39,7 @@ Invoke the `docusaurus-writer` agent and provide: Before creating a page, select the root: - Zi plugin-manager user docs → `docs/`. -- Community content (contributing, handbook, ZUnit) → `community/`. +- Community content (contributing, handbook, tools such as ZUnit and Zsh Lint) → `community/`. - Third-party ecosystem (annexes, packages, plugins) → `ecosystem/`. - Admin / tooling / operational / infrastructure → **not the wiki**; these are runbooks for `z-shell/.github/runbooks/`. diff --git a/.github/instructions/docs-authoring.instructions.md b/.github/instructions/docs-authoring.instructions.md index b34bf2ef..8b872fb3 100644 --- a/.github/instructions/docs-authoring.instructions.md +++ b/.github/instructions/docs-authoring.instructions.md @@ -9,12 +9,12 @@ applyTo: "{docs,community,ecosystem}/**/*.mdx" Choose the content root before writing. The roots are not interchangeable: -| Content type | Root | -| -------------------------------------------------- | ---------------------------------------------- | -| Zi plugin-manager install / commands / usage | `docs/` | -| Contributing, Zsh handbook, plugin standard, ZUnit | `community/` | -| Maintainer / operational / infrastructure runbooks | **not the wiki** — `z-shell/.github/runbooks/` | -| Third-party annexes, packages, plugins | `ecosystem/` | +| Content type | Root | +| --------------------------------------------------------------------------------------- | ---------------------------------------------- | +| Zi plugin-manager install / commands / usage | `docs/` | +| Contributing, Zsh handbook, plugin standard, community tools such as ZUnit and Zsh Lint | `community/` | +| Maintainer / operational / infrastructure runbooks | **not the wiki** — `z-shell/.github/runbooks/` | +| Third-party annexes, packages, plugins | `ecosystem/` | **Prohibition:** Never place maintainer, operational, or infrastructure documentation anywhere in the wiki (neither `docs/` nor `community/`). It leaks diff --git a/AGENTS.md b/AGENTS.md index c0aae809..0ed9ede2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,8 @@ This project follows the organization-wide [Z-Shell Organization Guidelines](htt - `docs/` → `/docs` — **Zi plugin manager user documentation only** (installation, commands, usage guides). - `community/` → `/community` — Z-Shell ecosystem community content: - contributing, the Zsh handbook/plugin standard, and ZUnit. + contributing, the Zsh handbook/plugin standard, and community tools such as + ZUnit and Zsh Lint. - `ecosystem/` → `/ecosystem` — third-party catalog: annexes, packages, plugins. - **Maintainer, operational, and infrastructure runbooks do not belong on the public wiki.** They live in `z-shell/.github/runbooks/`. diff --git a/community/00_contributing/04_contributing_docs.mdx b/community/00_contributing/04_contributing_docs.mdx index dda9a6a0..8987580c 100644 --- a/community/00_contributing/04_contributing_docs.mdx +++ b/community/00_contributing/04_contributing_docs.mdx @@ -59,7 +59,7 @@ The wiki has three independent docs roots: | Directory | URL Prefix | Purpose | | --- | --- | --- | | `docs/` | `/docs` | Core documentation, getting started, guides | -| `community/` | `/community` | Community guides, Zsh plugin standard | +| `community/` | `/community` | Community guides, Zsh plugin standard, tools | | `ecosystem/` | `/ecosystem` | Annexes, packages, plugins | ## File Naming Conventions diff --git a/community/04_zsh_lint/_category_.json b/community/04_zsh_lint/_category_.json new file mode 100644 index 00000000..d6110a74 --- /dev/null +++ b/community/04_zsh_lint/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "🔍 Zsh Lint", + "position": 4, + "link": { + "type": "doc", + "id": "zsh_lint" + } +} diff --git a/ecosystem/plugins/zsh_lint.mdx b/community/04_zsh_lint/index.mdx similarity index 57% rename from ecosystem/plugins/zsh_lint.mdx rename to community/04_zsh_lint/index.mdx index 957970ae..3208b926 100644 --- a/ecosystem/plugins/zsh_lint.mdx +++ b/community/04_zsh_lint/index.mdx @@ -1,7 +1,7 @@ --- id: zsh_lint title: 🔍 Zsh Lint -sidebar_position: 13 +sidebar_position: 1 description: A Go-based semantic analyzer for Zsh. keywords: - zsh-lint @@ -14,10 +14,9 @@ keywords: ## A Go-based semantic analyzer for Zsh -`zsh-lint` is being rebooted as a Go semantic analyzer for Zsh. It parses Zsh -sources with a real grammar front end and reports problems. It currently -operates as a **parser survey** — reporting which files the parser accepts — and -does not implement lint rules yet. +`zsh-lint` is a standalone Go semantic analyzer for Zsh. It parses Zsh sources +with a real grammar front end and reports greppable diagnostics from its default +static-analysis rules. ### [z-shell/zsh-lint][] @@ -33,8 +32,15 @@ go install github.com/z-shell/zsh-lint/cmd/zsh-lint@latest zsh-lint path/to/file.zsh another.zsh ``` -Each file gets an `OK`/`FAIL` line; failures include a greppable -`path:line:col: message`. The exit code is `0` only if every file parsed. +Diagnostics use the `path:line:col: [rule-id] message` format. Parse errors, +warnings, and errors produce a non-zero exit code. + +For parser-gap corpus evaluation without static-analysis rules, use the +dedicated survey command: + +```sh +zsh-lint-survey path/to/file.zsh another.zsh +``` ### Reference @@ -42,33 +48,43 @@ Each file gets an `OK`/`FAIL` line; failures include a greppable -# zsh\-lint +#### zsh\-lint + + import "github.com/z-shell/zsh-lint/cmd/zsh-lint" + +Command zsh\-lint performs static analysis of Zsh shell scripts. + +##### Index + + + +#### zsh\-lint\-survey - import "github.com/z-shell/zsh-lint/cmd/zsh-lint" + import "github.com/z-shell/zsh-lint/cmd/zsh-lint-survey" -Command zsh\-lint surveys Zsh files with the mvdan/sh parser front end and reports parse success or failure per file \(reboot parser\-evaluation phase, issues \#5, \#8\). Lint rule diagnostics \(issue \#18\) build on this foundation. +Command zsh\-lint\-survey runs the parser front end across Zsh files and reports parser gaps without evaluating static\-analysis rules. -## Index +##### Index -# survey +#### survey - import "github.com/z-shell/zsh-lint/internal/survey" + import "github.com/z-shell/zsh-lint/internal/survey" Package survey runs the parser front end across a set of Zsh files and reports, per file, whether parsing succeeded. It produces greppable \`path:line:col: message\` diagnostics for failures and a one\-line summary. This is the reboot's parser\-evaluation surface \(issues \#5, \#8\): it reports parser outcomes only and intentionally implements no lint rules yet. -## Index +##### Index -- [func Run\(names \[\]string, w io.Writer\) int](#Run) +- [func Run\(names \[\]string, w io.Writer\) int](#func-run) -## func Run +##### func Run - func Run(names []string, w io.Writer) int + func Run(names []string, w io.Writer) int Run parses each file in names, writing per\-file status and a summary to w. diff --git a/community/index.mdx b/community/index.mdx index cc5f85b3..db1a9fbe 100644 --- a/community/index.mdx +++ b/community/index.mdx @@ -18,7 +18,7 @@ keywords: import Link from "@docusaurus/Link"; import useBaseUrl from "@docusaurus/useBaseUrl"; -The Z-Shell community is home to contributors, plugin authors, and Zsh enthusiasts. Find guides, a plugin gallery, the ZUnit testing framework, and everything you need to get involved. +The Z-Shell community is home to contributors, plugin authors, and Zsh enthusiasts. Find guides, a plugin gallery, community tools, and everything you need to get involved.
Explore ZUnit →
+
+ + Zsh Lint + A standalone semantic analyzer for Zsh scripts with greppable static-analysis diagnostics. + Explore Zsh Lint → +
+
Plugin Gallery diff --git a/static/_redirects b/static/_redirects index e69de29b..0a35942d 100644 --- a/static/_redirects +++ b/static/_redirects @@ -0,0 +1,2 @@ +/ecosystem/plugins/zsh_lint /community/zsh_lint 301 +/ecosystem/plugins/zsh_lint/ /community/zsh_lint 301 diff --git a/static/_routes.json b/static/_routes.json new file mode 100644 index 00000000..16e72f12 --- /dev/null +++ b/static/_routes.json @@ -0,0 +1,5 @@ +{ + "version": 1, + "include": ["/*"], + "exclude": ["/ecosystem/plugins/zsh_lint", "/ecosystem/plugins/zsh_lint/"] +}