Taskfile.yml

version: '3'

vars:
  VERSION: '{{default "dev" .VERSION}}'

tasks:
  default:
    cmds: [task: build]
  list:
    desc: List available tasks
    cmds: [task --list]
  build:
    desc: Build ./gloss (skipped when nothing it is built from has changed)
    env:
      GLOSS_VERSION: '{{.VERSION}}'
    # What the binary is made of: the Go of its packages (the harness, tools,
    # and tests of the browser are not part of it), the files it embeds
    # (skills/gloss/SKILL.md and the web page's scripts), and the modules. A new
    # package under internal/ is picked up; one elsewhere must be added here.
    sources:
      - go.mod
      - go.sum
      - cmd/**/*.go
      - internal/**/*.go
      - internal/document/fonts/*.ttf
      - internal/theme/themes/*.json
      - skills/*.go
      - skills/gloss/SKILL.md
      - web/embed.go
      - web/serve.html
      - web/serve.mjs
      - web/viewer-session.mjs
      - web/drop.mjs
      - web/upload.mjs
      - web/pickers.mjs
      - web/remote.mjs
      - web/pick.html
      - web/pick.mjs
      - web/pick-api.mjs
      - exclude: '**/*_test.go'
      - exclude: internal/tools/**
      - exclude: internal/browse/browsetest/**
      - exclude: internal/browse/browsecfg/**
      - exclude: internal/browse/cmd/**
    generates:
      - gloss
    # The version is stamped in by -ldflags, which no source file records: it
    # is up to date only if the binary says the version asked for.
    status:
      # Workspace dependencies can change outside these source globs. Let Go's
      # own build cache track them instead of skipping the build at Task level.
      - 'test -z "$(go env GOWORK)" || test "$(go env GOWORK)" = off'
      - test "$(./gloss --version 2>/dev/null)" = "gloss {{.VERSION}}"
    cmds:
      - go build -mod=readonly -trimpath -ldflags "-X main.version=$GLOSS_VERSION" -o gloss ./cmd/gloss
  run:
    desc: Run gloss (pass arguments after --)
    cmds: ['go run ./cmd/gloss {{.CLI_ARGS}}']
  install:
    desc: Install gloss into the Go bin directory
    cmds: [go install -mod=readonly ./cmd/gloss]
  fmt:
    desc: Format Go sources
    cmds: [gofmt -w cmd internal examples scripts/gen-assets]
  fmt-check:
    desc: Check Go formatting
    cmds:
      - 'test -z "$(gofmt -l cmd internal examples scripts/gen-assets)"'
  go-tidy:
    desc: Tidy module dependencies
    cmds: [go mod tidy]
  go-tidy-check:
    cmds: [go mod tidy -diff]
  go-verify:
    cmds: [go mod verify]
  test:
    desc: Run tests
    cmds: [go test -mod=readonly ./...]
  test-race:
    desc: Run tests with race detection
    cmds: [go test -mod=readonly -race ./...]
  vet:
    desc: Run Go static checks
    cmds: [go vet -mod=readonly ./...]
  cross-windows:
    desc: Compile and vet for Windows, which CI does not run on (the release ships it)
    env:
      GOOS: windows
    cmds:
      - go build -mod=readonly -o /dev/null ./...
      - go vet -mod=readonly ./...
  fuzz:
    desc: Fuzz the loaders, one target after another (FUZZTIME=60s; FUZZ=FuzzParseSTL for just one)
    vars:
      FUZZTIME: '{{.FUZZTIME | default "60s"}}'
    cmds:
      # Each target runs on its own, as go test -fuzz requires; a failure does
      # not stop the others, and fails the task at the end.
      - |
        failed=0
        targets="{{.FUZZ}}"
        [ -n "$targets" ] || targets=$(grep -ho '^func Fuzz[A-Za-z0-9_]*' internal/document/fuzz_test.go | cut -d' ' -f2)
        for t in $targets; do
          go test ./internal/document -run '^$' -fuzz "^${t}\$" -fuzztime {{.FUZZTIME}} || failed=1
        done
        exit $failed
  browse:test:
    desc: Run the file browser's tests and its scripts (internal/browse)
    cmds: ['go test -mod=readonly ./internal/browse/...']
  browse:screens:
    desc: Rewrite the golden screens of the browser's scripts, then read the diff
    cmds: ['go test -mod=readonly ./internal/browse/... -update-screens']
  browse:bench:
    desc: Time typing and drawing in a folder of 100,000 files
    cmds: ["go test -mod=readonly -run '^$' -bench . ./internal/browse"]
  browse:play:
    desc: Try the file browser over an in-memory tree (-- -from ~/Downloads, -script FILE, -option layout=columns)
    interactive: true
    cmds: ['go run ./internal/browse/cmd/play {{.CLI_ARGS}}']
  browse:record:
    desc: Play with the browser and keep what you do as a test script (NAME=mything)
    interactive: true
    requires:
      vars: [NAME]
    preconditions:
      - sh: test ! -e internal/browse/testdata/scripts/{{.NAME}}.txt
        msg: "internal/browse/testdata/scripts/{{.NAME}}.txt exists: pick another NAME"
    cmds:
      - go run ./internal/browse/cmd/play -record internal/browse/testdata/scripts/{{.NAME}}.txt {{.CLI_ARGS}}
      - go test -mod=readonly ./internal/browse -run 'TestScripts/{{.NAME}}$' -update-screens
      - echo "Written internal/browse/testdata/scripts/{{.NAME}}.txt and its .golden; read both, add checks, then task browse:test"
  browse:replay:
    desc: Step through a browser script in the terminal, its checks shown (SCRIPT=columns)
    interactive: true
    requires:
      vars: [SCRIPT]
    cmds: ['go run ./internal/browse/cmd/play -replay -script internal/browse/testdata/scripts/{{.SCRIPT}}.txt {{.CLI_ARGS}}']
  browse:tape:
    desc: Write a browser script as a VHS tape in dist/browse (SCRIPT=columns)
    requires:
      vars: [SCRIPT]
    vars:
      CMD: '{{.CMD | default "gloss examples"}}'
      KEYS: '{{.KEYS | default "alt+up=Ctrl+Up,alt+left=Ctrl+O"}}'
      PAUSE: '{{.PAUSE | default "500ms"}}'
    cmds:
      - mkdir -p dist/browse
      - >-
        go run ./internal/browse/browsetest/tape
        -cmd "{{.CMD}}" -keys "{{.KEYS}}" -pause "{{.PAUSE}}"
        -o "dist/browse/{{.SCRIPT}}.gif"
        internal/browse/testdata/scripts/{{.SCRIPT}}.txt > dist/browse/{{.SCRIPT}}.tape
  browse:gif:
    desc: Record a browser script as a GIF in dist/browse (SCRIPT=columns; needs vhs)
    requires:
      vars: [SCRIPT]
    preconditions:
      - sh: command -v vhs
        msg: "vhs is not installed (brew install vhs): it records the GIF"
    cmds:
      - task: browse:tape
        vars: {SCRIPT: '{{.SCRIPT}}', CMD: '{{.CMD}}', KEYS: '{{.KEYS}}', PAUSE: '{{.PAUSE}}'}
      # The tape types gloss, so the one just built is first on the path; it
      # runs from here, where examples/ is.
      - go build -mod=readonly -o dist/browse/bin/gloss ./cmd/gloss
      - PATH="$PWD/dist/browse/bin:$PATH" vhs dist/browse/{{.SCRIPT}}.tape
  browse:gifs:
    desc: Record the browser's showcase scripts as GIFs in dist/browse (needs vhs)
    vars:
      SCRIPTS: '{{.SCRIPTS | default "columns places filter complete2"}}'
    cmds:
      - for: {var: SCRIPTS, split: ' '}
        task: browse:gif
        vars: {SCRIPT: '{{.ITEM}}'}
  staticcheck:
    desc: Run staticcheck
    cmds: [go run honnef.co/go/tools/cmd/staticcheck@latest ./...]
  vulncheck:
    desc: Check the modules linked for known vulnerabilities
    cmds: [go run golang.org/x/vuln/cmd/govulncheck@latest ./...]
  ci:
    desc: Check the pinned release dependencies, ignoring local workspaces
    env:
      GOWORK: 'off'
    # A subprocess carries this environment into every child task. Task's
    # direct task references do not inherit their parent's task-level env.
    cmds:
      - task fmt-check go-tidy-check go-verify test-race vet cross-windows staticcheck vulncheck
      # A preceding workspace build may have the same sources and version.
      - task --force build
      - task notices-check docs-check
  notices:
    env:
      GOWORK: 'off'
    desc: Regenerate THIRD_PARTY_NOTICES.md from the modules linked
    cmds: ['go run ./internal/tools/notices > THIRD_PARTY_NOTICES.md']
  notices-check:
    env:
      GOWORK: 'off'
    desc: Fail when THIRD_PARTY_NOTICES.md is not what the modules linked say
    cmds:
      - 'go run ./internal/tools/notices | cmp -s - THIRD_PARTY_NOTICES.md || (echo "THIRD_PARTY_NOTICES.md is stale: run task notices" >&2; exit 1)'
  release:
    env:
      GOWORK: 'off'
    desc: Package a snapshot release into dist with GoReleaser, publishing nothing
    cmds: [goreleaser release --snapshot --clean]
  release-check:
    desc: Check the GoReleaser configuration
    cmds: [goreleaser check]
  demo:
    desc: Run the embedded sample gallery in your terminal
    dir: examples/demo
    cmds: ['go run . {{.CLI_ARGS}}']
  demo-check:
    desc: Check the browser demo module
    dir: examples/demo
    cmds:
      - go mod tidy -diff
      - go mod verify
      - go test -mod=readonly ./...
      - go vet -mod=readonly ./...
  build-wasm-site:
    desc: Build the self-contained sample gallery site into web/dist
    cmds: [sh scripts/build-site.sh]
  web-check:
    desc: Test download progress and demo navigation (Node 18+)
    cmds: ['node --test web/*.test.mjs']
  serve-wasm-site:
    desc: Build and serve the demo at http://localhost:8000
    deps: [build-wasm-site]
    cmds: [python3 -m http.server 8000 --directory web/dist --bind 127.0.0.1]
  docs:
    desc: Generate the man page, completions, and the documentation pages (see docs:hugo:serve)
    cmds:
      - task: docs:man:build
      - task: docs:completions:build
      - task: docs:md:build
  docs:man:build:
    desc: Generate the gloss(1) man page into docs/man
    sources:
      - cmd/gloss/*.go
      - internal/document/*.go
      - go.mod
      - go.sum
    generates:
      - docs/man/gloss.1
    cmds: [go run ./cmd/gloss --docs-man docs/man]
  docs:completions:build:
    desc: Generate the bash, zsh, and fish completions into docs/completions
    sources:
      - cmd/gloss/*.go
      - internal/document/*.go
      - go.mod
      - go.sum
    generates:
      - docs/completions/gloss.bash
      - docs/completions/_gloss
      - docs/completions/gloss.fish
    cmds: [go run ./cmd/gloss --docs-completions docs/completions]
  docs:md:build:
    desc: Generate the command reference, and the guide pages made from DEVELOP.md and the skill
    sources:
      - cmd/gloss/*.go
      - internal/document/*.go
      - internal/tools/docsite/*.go
      - DEVELOP.md
      - skills/gloss/SKILL.md
      - go.mod
      - go.sum
    generates:
      - docs/hugo/content/command/_index.md
      - docs/hugo/content/guide/development.md
      - docs/hugo/content/guide/for-llms.md
    cmds:
      - go run ./cmd/gloss --docs-markdown docs/hugo/content/command --docs-hugo
      - go run ./internal/tools/docsite -o docs/hugo/content/guide
  docs:hugo:serve:
    desc: Serve the documentation site while editing it (needs hugo, extended)
    deps: [docs:md:build]
    dir: docs/hugo
    cmds: [hugo serve]
  docs:hugo:build:
    desc: Build the documentation site into docs/hugo/public (pass hugo flags after --)
    deps: [docs:md:build]
    dir: docs/hugo
    cmds: ['hugo --minify {{.CLI_ARGS}}']
  docs:clean:
    desc: Remove what the docs tasks generate
    cmds: [rm -rf docs/man docs/hugo/content/command docs/hugo/content/guide/development.md docs/hugo/content/guide/for-llms.md docs/hugo/public docs/hugo/resources]
  docs-check:
    desc: Check that the man page, completions, and reference can be generated from the options
    cmds:
      - 'dir="$(mktemp -d)" && go run ./cmd/gloss --docs-man "$dir/man" --docs-completions "$dir/completions" --docs-markdown "$dir/md" --docs-hugo && go run ./internal/tools/docsite -o "$dir/guide"; status=$?; rm -rf "$dir"; exit $status'
  gen-assets:
    desc: Regenerate the original PNG, HEIC, PDF, and Grist fixtures
    cmds:
      - go run ./scripts/gen-assets
      - python3 scripts/gen-grist.py