Engineering Assessment: Weekend Warrior

· combray's blog

Executive Summary #

Weekend Warrior is a static site generator that transforms Git repository commit histories into interactive, step-by-step technical tutorials styled as "Future Systems Reports." The project is in early prototype stage (~1,600 LOC) with a clean, focused architecture but lacking standard engineering infrastructure (tests, linting, CI/CD). Given its scope as an internal tool, the current engineering rigor is appropriate for early development, but the most critical improvement needed is addressing shell command injection vulnerabilities in the build scripts.

Technology Stack #

Category Technology Version Status
Language TypeScript Strict (Astro preset) Current
Framework Astro 5.16.1 Current (5.16.3 available)
UI Framework React 19.2.0 Current
Styling Tailwind CSS 4.1.17 Current
Syntax Highlighting Shiki 3.15.0 Minor update available (3.17.0)
Package Manager npm - Current
Build Tool Vite (via Astro) - Current
Runtime Manager mise - Current

Project Structure #

The codebase follows standard Astro conventions with a focused, minimal structure appropriate for its scope.

weekend-warrior/
├── src/
│   ├── components/           # 2 files: Astro + React components
│   │   ├── Header.astro      # Site navigation header
│   │   └── Workspace.tsx     # Interactive file/diff viewer (largest component)
│   ├── content/              # Astro Content Collections
│   │   ├── config.ts         # Zod schemas for steps and docs
│   │   ├── docs/             # Generated README content
│   │   └── steps/            # Generated step files (gitignored)
│   ├── data/                 # Runtime data (project.json, gitignored)
│   ├── layouts/
│   │   └── Layout.astro      # Base HTML template
│   ├── pages/
│   │   ├── index.astro       # Homepage/cover page
│   │   └── steps/[slug].astro # Dynamic step pages
│   ├── styles/
│   │   └── global.css        # Tailwind v4 theme configuration
│   └── utils/                # Build-time utilities
│       ├── git.ts            # Git command wrappers
│       ├── project.ts        # Project data access
│       └── steps.ts          # Step parsing logic
├── scripts/
│   ├── build-site.ts         # Main build orchestrator
│   └── sync-data.ts          # Git-to-content sync script
├── astro.config.mjs
├── tsconfig.json
├── mise.toml                 # mise task runner configuration
└── package.json

Notable patterns:

Current Engineering Practices #

What Exists #

What's Missing #

Dependency Health #

Critical (Security Vulnerabilities) #

Package Current Issue Recommendation
- - npm audit shows 0 vulnerabilities No action needed

High (Major Version Behind or Deprecated) #

Package Current Latest Gap
- - - All dependencies are current

Medium (Stale - No Updates 12+ Months) #

Package Last Update Concern
- - No stale dependencies detected

Note: astro has a patch update (5.16.1 → 5.16.3) and shiki has a minor update (3.15.0 → 3.17.0). Neither is urgent.

Security Assessment #

Issues Found #

Areas Reviewed (No Issues) #

Testing Assessment #

Coverage: 0% - No tests exist Test Types Present: None Test Quality: N/A

Gaps #

  1. Workspace.tsx is complex (~295 lines) with state management, effects, and tree building logic. Unit tests for the tree builder and diff generation would catch regressions.
  2. Build scripts handle external input but have no validation tests.
  3. Content parsing (steps.ts, sync-data.ts) parses markdown and YAML without tests for edge cases.

Given the prototype scope:

  1. Start with unit tests for escapeHtml and tree building in Workspace.tsx
  2. Add smoke tests for build scripts (verify output structure)
  3. Integration tests later for the full sync-data pipeline

Complexity vs Rigor Analysis #

Inferred Scope: Prototype / Internal Tool

Evidence:

Assessment: Current rigor is appropriate for early prototype stage with one exception: the security issues in build scripts should be addressed immediately as they affect the build-time trusted boundary. The lack of tests and linting is acceptable for now but should be added before expanding the project.

The project demonstrates good framework usage (Astro 5, React 19, Tailwind v4) and clean code organization. The main component (Workspace.tsx) is well-structured despite some any types.

Prioritized Improvements #

High Impact / Low Effort (Do First) #

  1. Fix command injection in build-site.ts

    • What: Replace execSync with spawnSync for git clone with proper argument handling
    • Why: Prevents arbitrary command execution from malicious git URLs
    • How: 
      1// Instead of:
2execSync(`git clone --depth=1000 "${gitPath}" "${sourceRepo}"`, { stdio: 'inherit' });
3// Use:
4spawnSync('git', ['clone', '--depth=1000', gitPath, sourceRepo], { stdio: 'inherit' });

  2. Add DOMPurify for rendered HTML

    • What: Sanitize Shiki output and marked output before rendering
    • Why: Prevents XSS from malicious source repositories
    • How: npm install dompurify @types/dompurify, wrap dangerouslySetInnerHTML values

  3. Add ESLint with Astro/React presets

    • What: Create .eslintrc.cjs with recommended configs
    • Why: Catches bugs early, enforces consistency, eliminates any types
    • How: npm init @eslint/config and extend eslint:recommended, plugin:@typescript-eslint/recommended, plugin:astro/recommended

High Impact / High Effort (Plan For) #

  1. Add Vitest for unit testing

    • What: Set up Vitest with React Testing Library for Workspace.tsx tests
    • Why: Workspace.tsx has enough logic to warrant regression tests
    • How: npm install -D vitest @testing-library/react happy-dom, create vitest.config.ts

  2. Add GitHub Actions CI

    • What: Create .github/workflows/ci.yml for lint, typecheck, and build
    • Why: Prevents broken builds from being merged
    • How: Standard Node.js workflow with npm ci, lint, typecheck, build steps

  3. Refactor git utilities to use spawnSync

    • What: Replace all execSync with spawnSync using argument arrays
    • Why: Eliminates entire class of injection vulnerabilities
    • How: Systematic refactor of git.ts, steps.ts, sync-data.ts

Low Impact / Low Effort (Quick Wins) #

  1. Update outdated packages

    • What: npm update astro shiki
    • Why: Gets patch/minor fixes

  2. Replace any types in Workspace.tsx

    • What: Define proper types for tree nodes and file tree props
    • Why: Better autocomplete and error catching

  3. Add error boundary to Workspace

    • What: Wrap Workspace in React error boundary
    • Why: Graceful failure if file operations fail

Low Impact / High Effort (Deprioritize) #

  1. Add E2E tests with Playwright

    • Note: Overkill for a prototype. Revisit if project grows to production use.

  2. Add Storybook for component documentation

    • Note: Only one interactive component; doesn't justify the setup cost.

  3. Add pre-commit hooks

    • Note: Single developer project; manual checks sufficient for now.

Research References #

Research reports generated during this analysis:

last updated: