Code Analysis Documentation

This directory contains documentation for code analysis tools and practices used in the home repository.

Documents

ast-grep Guide

Comprehensive guide to using ast-grep for the home repository.

Topics covered:

• Why ast-grep for this repository
• Quick start and common commands
• Current rules and findings
• Real-world examples
• Performance benchmarks
• Integration with workflow
• FAQ

Quick stats:

• 154 issues found across 415 files
• Scan time: 0.022 seconds (~19,000 files/sec)
• Rules: 10 custom rules (Nix, Bash, Security)

ast-grep for Tekton

Guide for using ast-grep with Tekton and Kubernetes projects.

Topics covered:

• Use cases (API migration, security, best practices)
• Example rules for Tekton
• Migration workflows
• CI/CD integration
• Performance on large codebases

Use cases:

• v1beta1 → v1 API migration
• Security scanning (secrets, unsafe patterns)
• Best practices enforcement (workspaces, RBAC)
• Error handling patterns
• Testing quality

Tool Comparison

Comparison of different code analysis tools.

Tools compared:

• ast-grep vs. ripgrep (text search)
• ast-grep vs. semgrep (semantic analysis)
• ast-grep vs. language-specific tools (statix, shellcheck, golangci-lint)
• When to use which tool

Decision matrix:

• Use ripgrep for: Quick text search (< 0.01s)
• Use ast-grep for: Structural patterns, refactoring (< 0.1s)
• Use semgrep for: Deep security audits (30s+)
• Use language tools for: Deep semantic analysis

Quick Start

Note: Run commands from repository root (~/src/home)

Run Full Scan

cd ~/src/home
ast-grep scan

Search for Pattern

cd ~/src/home
# Find all mkHost calls
ast-grep -p 'mkHost { $$$ }' -l nix flake.nix

# Find all bash functions
ast-grep -p '$NAME() { $$$ }' -l bash tools/

Interactive Refactoring

ast-grep -p 'oldPattern' --rewrite 'newPattern' --interactive

Current Rules

Nix (4 rules)

• nix-prefer-inherit: Use ‘inherit’ for cleaner code
• nix-explicit-option-types: Always specify types in mkOption
• nix-prefer-optional: Use lib.optional for conditional lists
• nix-boolean-comparison: Don’t compare booleans directly

Bash (5 rules)

• bash-require-strict-mode: Scripts need set -euo pipefail
• bash-unsafe-rm-rf: Dangerous rm -rf without checks
• bash-use-command-over-which: Use ‘command -v’ not ‘which’
• bash-prefer-dollar-parens: Use $() instead of backticks

Security (1 rule)

• security-unsafe-curl-pipe-sh: Never curl | sh without review

Scan Results Summary

Last scan: 2026-02-09

Top Issues

1. nix-explicit-option-types (137 warnings)

   • Missing type annotations in mkOption
   • Affected modules: jellyfin-auto-collections, nixpkgs-consolidate, govanityurl, microshift, job-notify, etc.
   • Action needed: Add type = types.<type> to option definitions

2. bash-require-strict-mode (10 errors)

   • Scripts missing set -euo pipefail
   • Affected files: install.sh, keyboards/eyelash_corne/go.sh, imperative/{nagoya,wakasu}/apply.sh, and more
   • Action needed: Add after shebang line

3. bash-unsafe-rm-rf (5 errors)

   • Potentially dangerous rm -rf usage
   • Need review to ensure variables are checked before deletion

Performance

Home repository (415 files):

• Full scan: 0.022s (~19,000 files/sec)
• Single rule: 0.010s
• Memory: < 50 MB

Comparison:

• ripgrep: 0.005s (4.4x faster, but text-only)
• semgrep: ~30s (1,360x slower, but deeper analysis)

Integration

Makefile (Planned)

Add these targets to Makefile:

.PHONY: lint-ast-grep
lint-ast-grep:
	@echo "Running ast-grep scan..."
	@ast-grep scan

.PHONY: lint-ast-grep-errors
lint-ast-grep-errors:
	@ast-grep scan --json 2>/dev/null | \
	  jq -r '.[] | select(.severity == "error") | "\(.file):\(.range.start.line): \(.message)"'

.PHONY: lint-ast-grep-stats
lint-ast-grep-stats:
	@ast-grep scan --json 2>/dev/null | \
	  jq -s 'group_by(.severity) | map({severity: .[0].severity, count: length})'

Usage:

make lint-ast-grep         # Full scan
make lint-ast-grep-errors  # Show only errors
make lint-ast-grep-stats   # Statistics

Pre-commit Hook (Recommended)

Add to .git/hooks/pre-commit:

#!/usr/bin/env bash
set -euo pipefail

echo "Running ast-grep linting..."
cd "$(git rev-parse --show-toplevel)"

if ! ast-grep scan --json 2>/dev/null | jq -e '.[] | select(.severity == "error")' >/dev/null; then
  # No errors found
  exit 0
else
  echo "❌ ast-grep found errors. Run 'ast-grep scan' to see details."
  exit 1
fi

Make executable:

chmod +x .git/hooks/pre-commit

Wrapper Script (Optional)

Create ~/bin/ast-grep-home to run from anywhere:

#!/usr/bin/env bash
set -euo pipefail
cd ~/src/home
exec ast-grep "$@"

Usage:

# From any directory
ast-grep-home scan
ast-grep-home -p 'pattern' -l nix

CI/CD (Future)

- name: Run ast-grep
  run: |
    cd ~/src/home
    ast-grep scan --error

Configuration

Configuration structure:

~/src/home/
├── sgconfig.yml              # Main configuration (repo root)
└── .ast-grep/
    └── rules/                # Rule definitions
        ├── nix-prefer-inherit.yml
        ├── nix-explicit-option-types.yml
        ├── nix-prefer-optional.yml
        ├── nix-boolean-comparison.yml
        ├── bash-require-strict-mode.yml
        ├── bash-unsafe-rm-rf.yml
        ├── bash-use-command-over-which.yml
        ├── bash-prefer-dollar-parens.yml
        ├── security-unsafe-curl-pipe-sh.yml
        └── (more rules...)

Important: sgconfig.yml must be in repository root, not in .ast-grep/

Adding New Rules

1. Create .ast-grep/rules/your-rule.yml:

   id: your-rule-id
   message: Clear message
   severity: error  # or warning, info, hint
   language: Nix  # or Bash, Go, etc.
   rule:
     pattern: $PATTERN
   fix: $FIX  # optional
   note: Explanation
   

2. Test:

   ast-grep scan --rule .ast-grep/rules/your-rule.yml
   

3. Add to documentation

Resources

• Main guide: ast-grep-guide.md
• Tekton guide: ast-grep-tekton-guide.md
• Tool comparison: tool-comparison.md
• Official docs: https://ast-grep.github.io/
• Playground: https://ast-grep.github.io/playground.html
• Rule catalog: https://ast-grep.github.io/catalog/

Next Steps

• Add pre-commit hook
• Fix nix-explicit-option-types warnings (137 instances)
• Fix bash-require-strict-mode errors (10 scripts)
• Review bash-unsafe-rm-rf findings (5 instances)
• Add Python linting rules
• Add Go error-handling rules
• Integrate into CI/CD
• Create shared rule repository for NixOS community

For questions or contributions, see the main guides above.