Skip to content

docs(knowledge): reconcile zsh-lint parser guidance with f1c43fa (#803) #804

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ss-o merged 1 commit into from
Oct 16, 2026
Merged

docs(knowledge): reconcile zsh-lint parser guidance with f1c43fa (#803) #804

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions knowledge/domains/tooling/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@

Select this domain for analyzers, parsers, linters and their supported language boundaries. Implementation detail belongs to the tool's source and instructions.

| Task | Authoritative context |
| --- | --- |
| Understand zsh-lint architecture | [Analyzer decision](../../../decisions/0011-zsh-lint-semantic-analyzer-architecture.md) and [parser strategy](../../../decisions/0023-zsh-lint-parser-front-end-strategy.md) |
| Work on parser internals | [zsh-lint repository](https://github.com/z-shell/zsh-lint), its AGENTS.md, parser-front-end instructions and parser-gap-fix skill |
| Understand parser fork disposition | [ADR-0030](../../../decisions/0030-zsh-lint-parser-fork-trigger-fired.md) |
| Change the CI integration | [zsh-lint CI runbook](../ci/zsh-lint-ci.md) |
| Task | Authoritative context |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Understand zsh-lint architecture | [Analyzer decision](../../../decisions/0011-zsh-lint-semantic-analyzer-architecture.md) and [parser strategy](../../../decisions/0023-zsh-lint-parser-front-end-strategy.md) |
| Work on parser internals | [zsh-lint repository](https://github.com/z-shell/zsh-lint), its AGENTS.md, parser-front-end instructions and parser-gap-fix skill |
| Understand parser fork disposition | [ADR-0030](../../../decisions/0030-zsh-lint-parser-fork-trigger-fired.md) |
| Change the CI integration | [zsh-lint CI runbook](../ci/zsh-lint-ci.md) |

## Pending project-source adoption

The [Go AST draft](zsh-lint-go-ast.md) and [parser-front-end draft](zsh-lint-parser-front-end.md) prepare complete version-compatible project instructions. They preserve native frontmatter and refer to project revision `7ff05091a5489becf32069db1738d38ec23c8fd5`. The project instructions, parser-gap-fix skill and source-coupled contracts remain authoritative until approved organization sources are published and project delivery, compatibility and discovery are verified. No project delivery record or source pin is active for these drafts.
The [Go AST draft](zsh-lint-go-ast.md) and [parser-front-end draft](zsh-lint-parser-front-end.md) prepare complete version-compatible project instructions. They preserve native frontmatter. The Go AST source refers to project revision `7ff05091a5489becf32069db1738d38ec23c8fd5`, and the parser-front-end source to `f1c43fac9c8eadfc914a4af89a1beea11afca891`. The project instructions, parser-gap-fix skill and source-coupled contracts remain authoritative until approved organization sources are published and project delivery, compatibility and discovery are verified. No project delivery record or source pin is active for these drafts.

Use [Zsh](../zsh/index.md) when deciding whether syntax or behavior is valid Zsh. Supplemental-tool acceptance is not language authority. Do not copy code-derived parser facts into this index.

Expand Down
6 changes: 3 additions & 3 deletions knowledge/domains/tooling/zsh-lint-parser-front-end.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ applyTo: "internal/parse/**,internal/survey/**,cmd/zsh-lint-survey/**"

# Parser Front End

This organization source supplies complete native project guidance through the approved records in `knowledge/project-delivery.json`. Edit the organization source, then publish and approve its revision before regenerating a project consumer; the generated consumer is not independently editable. Project instructions retain their existing authoring ownership until approved source publication, complete delivery and compatibility checks pass. Reconciled against project revision `7ff05091a5489becf32069db1738d38ec23c8fd5`; repository-relative code, command and fixture paths below refer to that project.
This organization source supplies complete native project guidance through the approved records in `knowledge/project-delivery.json`. Edit the organization source, then publish and approve its revision before regenerating a project consumer; the generated consumer is not independently editable. Project instructions retain their existing authoring ownership until approved source publication, complete delivery and compatibility checks pass. Reconciled against project revision `f1c43fac9c8eadfc914a4af89a1beea11afca891`; repository-relative code, command and fixture paths below refer to that project.

`internal/parse` wraps the in-repository mvdan/sh fork's `syntax` package in its Zsh dialect and closes proven valid-Zsh gaps with local compatibility adapters. Resolve the import prefix from the target project revision's `go.mod` and `third_party/mvdan-sh/FORK.md`, rather than assuming the upstream module namespace.
The contract is in [`docs/project/parser-gap-workflow.md`](https://github.com/z-shell/zsh-lint/blob/7ff05091a5489becf32069db1738d38ec23c8fd5/docs/project/parser-gap-workflow.md); this file only routes you there and names the invariants that reviews check.
`internal/parse` wraps the in-repository mvdan/sh fork's `syntax` package in its Zsh dialect and closes proven valid-Zsh gaps with local compatibility adapters. Resolve the import prefix from the target project revision's `go.mod` and `third_party/mvdan-sh/FORK.md`, rather than assuming the upstream module namespace; [ADR-0041](../../../decisions/0041-zsh-lint-parser-root-module-packaging.md) packages the fork inside the root module.
The contract is in [`docs/project/parser-gap-workflow.md`](https://github.com/z-shell/zsh-lint/blob/f1c43fac9c8eadfc914a4af89a1beea11afca891/docs/project/parser-gap-workflow.md); this file only routes you there and names the invariants that reviews check.

## Before changing anything

Expand Down
Loading