Implement zlint rule 'unused-decls'

[rockorager]

Rule: unused-decls

Disallows container-scoped variables that are declared but never used, including top-level declarations.

The Zig compiler checks for unused locals within functions, but does not flag unused container-scoped const/var declarations or unused functions. This rule fills that gap.

Example

// Bad: declared but never referenced
const UNUSED_CONSTANT: u32 = 42;

pub fn main() void {
    // ...
}

Implementation notes

Complexity: requires reference tracking across the module

This needs to track all container-scoped declarations and all identifier references, then report declarations with zero references. ziglint already does this for imports (Z013 tracks used_identifiers and import_bindings), so extending to all container decls is conceptually similar but broader.

Note that even zlint's implementation is incomplete — their docs note it doesn't handle member access expressions (foo.bar) or method calls correctly yet, and only checks top-level const declarations.

Reference

• zlint docs: https://donisaac.github.io/zlint/docs/rules/unused-decls
• Category: correctness / warning

Suggested-By: @mattrobenolt

[rockorager]

This becomes more tractable if #19 (disallow accessing container-level declarations via instance) is enforced first. With that rule in place, struct-level decls are always accessed via Type.bar, making reference tracking follow the type chain rather than needing to resolve arbitrary instance types.