[ss-o]

Pull request

Summary

• Add zsh-lint.json (configuration schema version 2): kind plugin, minimum Zsh 5.8, identifier fsh. F-Sy-H.plugin.zsh and lib are sourced libraries; functions and chroma are autoload functions; completions are autoloaded completion functions; tools holds standalone executables.
• Add .github/workflows/zsh-lint.yml, an observe-mode caller of the organization zsh-lint.yml workflow at main, with the analyzer pinned to v1.6.0 (f6341241c398fd2a784452e75895dafb06186bbc) and the same six literal roots.

Observe mode reports findings without failing the job; parser errors, invalid configuration, incomplete reports and tool failures still fail it. The check is not required, and the native syntax and ZUnit workflows are unchanged.

Closes #209

Findings at main 1e36df5

58 files, 0 parser errors, 0 errors, 0 warnings, 53 info, 5 hint. Every finding was checked against the source; the true positives were confirmed with zsh -f on Zsh 5.9.2.

Rule	Severity	Count	Verdict
quoting/unquoted-var	Info	49	48 intentional, 1 true positive
security/eval	Info	4	4 intentional
plugin/function-namespace	Hint	2	2 intentional
plugin/function-scoped-options	Hint	2	2 true positives
style/prefer-double-brackets	Hint	1	1 true positive

Judged sample:

• Intentional quoting/unquoted-var: ${(M)_fsh_state[chroma-...]%\%*} at lib/highlight.zsh:678 and ${_fsh_styles[...]:#none} at lib/highlight.zsh:1188 are optional arguments meant to drop when empty; ${${(s.:.)widgets[$cur_widget]}[2,3]} at F-Sy-H.plugin.zsh:481 must stay unquoted to pass two arguments; $__start_pos, $__end_pos and return $ret hold numbers that are never empty.
• Intentional security/eval: the widget stubs at F-Sy-H.plugin.zsh:477 and :482 quote every interpolated name with (q); lib/lifecycle.zsh:648 and functions/fsh_theme:532 restore declarations Zsh generated from in-process state.
• Intentional plugin/function-namespace: _zsh_highlight (F-Sy-H.plugin.zsh:253, lib/lifecycle.zsh:610) is the zsh-syntax-highlighting compatibility entry point.
• True positive quoting/unquoted-var: chroma/_fsh_chroma_subversion:63. For a word ending in @, $rev is empty and is dropped, so _fsh_chroma_subversion_parse_revision receives shifted arguments and adds the region 8 0 styled as a number where the quoted form adds an empty 8 8 region.
• True positive plugin/function-scoped-options: chroma/_fsh_chroma_ssh:20 and functions/fsh_theme:14. With xtrace on and an inherited IFS that lacks a space, ${=${options[xtrace]:#off}:+-o xtrace} stays one word, emulate fails with status 1, and localoptions stays off.
• True positive style/prefer-double-brackets: chroma/_fsh_chroma_zi:284 uses [ ... ].

This pull request does not change those sources. The true positives are recorded for separate follow-up.

Verification

• The organization runner (automation/ci/zsh_lint_ci.py from z-shell/.github main) in observe mode, with this configuration, on this branch: passed, with the counts above. Its diagnostics are byte-identical to the judged run at main 1e36df5.
• An explicit zsh-lint --config zsh-lint.json run resolves every input to a configured source root.
• Negative checks: an unknown configuration field fails the run (analyzer exit 2), and an empty source selection fails it.
• zsh-lint-survey -judge agrees with zsh -f -n on all 58 files; -trace-parses counts 102 parses, maximum adapter depth 10.
• trunk check --no-fix --ci zsh-lint.json .github/workflows/zsh-lint.yml: no issues.
• The hosted Zsh Lint check on this head is the remaining acceptance evidence.

Compatibility and lifecycle

No compatibility or lifecycle impact: no plugin source, theme or chroma function changes.

Agent handoff

No handoff needed.

[github-actions]

PR highlighting performance

Buffer	Base	PR	Difference
173 chars	4.588 ms	4.509 ms	-1.7%
1000 chars	14.519 ms	14.373 ms	-1.0%

Negative differences are faster. Medians use nine parses after one warm-up on the same runner.

Behavioral assertions

• Pass: representative buffers produce highlighting
• Pass: steady-state highlighting performs no full lifecycle refresh
• Pass: buffers above the configured limit take the skip path
• Pass: lazy and steady-state plugin resources unload cleanly

[ss-o]

Fallback review under ADR-0026: Copilot request not registered on 74ff6ed

Findings

No actionable findings.

One observation, not adopted: zsh-n.yml, trunk-check.yml and zunit.yml also run on v*.*.* tag pushes, while zsh-lint.yml runs only on main pushes and pull requests. A release tag points at a commit already analyzed on main, and this check is advisory, so a tag trigger would repeat the same result. No change.

Scope: the complete diff of 74ff6ed: the new zsh-lint.json and .github/workflows/zsh-lint.yml, against #209.

Note

This fallback review is not an approval to merge.

Validation

• Passed: every check on this head, including Configured Zsh Lint in observe mode: 58 files, 0 parser errors, 0 errors, 0 warnings, 53 info, 5 hint. Its diagnostics.json is byte-identical to the judged local run at main 1e36df5.
• Passed, rerun independently: the organization runner in observe mode on this head (same counts), and both native reproductions behind the true positives listed in the description (emulate status 1 with localoptions off under IFS=: and xtrace; region 8 0 instead of 8 8 for a word ending in @).
• Unavailable: a Copilot review; the request did not register on this head.

Checklist verdicts and supporting evidence

• Configuration: correct. Schema version 2. minimum_zsh 5.8 matches the README, AGENTS.md and the Zsh 5.8 job in zsh-n.yml. Identifier fsh gives the documented fsh_, _fsh_ and fsh_plugin_unload names. chroma/ is put on fpath and autoloaded by the entrypoint, so the autoload-function profile matches its use. All 58 Zsh production sources are covered; themes/, share/, docs/ and tests/ are excluded.
• Workflow: correct. The organization reusable workflow is referenced at @main under ADR-0042, and the analyzer is pinned by full SHA. The six literal paths equal the configuration roots. Permissions are contents: read, concurrency matches the repository's other workflows, and the path filters cover every analyzed root plus the workflow and configuration files.
• Code scanning: the CodeQL actions/unpinned-tag alert on the @main reference is answered with the ADR-0042 reason, dismissed as won't fix, and its thread is resolved, as the workflow contract directs.
• Description: accurate. The per-rule counts match the runner output, and each judged-sample location was checked against the source.
• Compatibility and lifecycle: no impact. No plugin, theme or chroma source changes.

Limits and follow-up

The true positives in existing sources (the subversion chroma argument shift, the xtrace emulate initializer at two sites, one [ ] condition) are outside this pull request and are recorded for separate follow-up.