semantic-dev

name	semantic-dev
description	Develop and contribute to the Semantic project. Use when working on semantic source code, adding features, fixing bugs, running tests, or preparing PRs. Triggers on "work on semantic", "semantic development", "contribute to semantic", "fix semantic bug", "add semantic feature".

Semantic Development

Zero-dependency Go library for matching natural language queries against accessibility tree elements.

Essential Commands

Before any PR:

./dev pr                # runs: check + e2e + lint corpus + bench

During development:

./dev test              # unit tests (fast)
./dev check             # fmt + vet + lint + test race (full validation)
./dev build             # build ./semantic CLI binary

Quality regression checks:

./dev baseline check    # compare quality against baseline
./dev runtime           # compare performance against baseline

When quality changes intentionally:

./dev baseline update   # accept new quality baseline (after review)

When to Use Each

Scenario	Command
Made code changes, quick sanity	./dev test
Ready to commit	./dev check
Before opening PR	./dev pr
Changed scoring/matching logic	./dev baseline check
Performance-sensitive changes	./dev runtime
Tuning weights	./dev tune then ./dev bench

Architecture

semantic.go               Public API (type aliases + constructors)
semantic_test.go           API-level smoke tests

internal/
  types/types.go           Type definitions (interfaces, structs)
  engine/                  All matching implementations (hidden)
    combined.go              Fused lexical + embedding matcher
    lexical.go               Jaccard similarity + synonyms + role boosting
    embedding.go             Cosine similarity on dense vectors
    hashing.go               Feature hashing embedder (zero-dep)
    synonyms.go              54 synonym groups for UI vocabulary
    stopwords.go             Context-aware stopword removal

recovery/                  Public subpackage
  engine.go                  RecoveryEngine (semantic re-matching)
  cache.go                   IntentCache (per-tab LRU)
  failure.go                 FailureType classification

cmd/semantic/main.go       CLI tool (find, match, classify)
cmd/semantic-bench/        Benchmark CLI (check, baseline, calibrate, tune, runtime)

Key Design Decisions

• internal/ — implementations are hidden. Consumers only see ElementMatcher interface + constructors.
• recovery/ — public subpackage. Pinchtab imports both semantic and semantic/recovery.
• Zero dependencies — hashing embedder, no ML models, no network calls.
• Stateless — every Find() call is independent. Thread-safe by default.

Workflow: New Feature or Bug Fix

1. Run doctor first:

   ./dev doctor
   

2. Make changes — implementations go in internal/engine/, types in internal/types/

3. Run checks:

   ./dev check   # fmt + vet + lint + test with race
   

4. Pre-commit hook runs gofmt + golangci-lint automatically on staged files.

Benchmark Improvement Loop

When implementing changes that affect matching quality:

./dev baseline          # create baseline (first time only)
# ... make changes ...
./dev bench             # run benchmark, compare to baseline
./dev baseline update   # accept new baseline (if improved)

Key metrics:

• MRR — Mean Reciprocal Rank (higher = finds correct element faster)
• P@1 — Precision at 1 (is top result correct?)
• Hit@3 — Any correct result in top 3?

Adding test cases:

1. Add to tests/benchmark/corpus/*/queries.json
2. Run ./dev lint corpus to validate
3. Run ./dev bench — shows regression until fixed

Public API Surface

Only these symbols are visible to consumers:

// Types (from internal/types via aliases)
semantic.ElementMatcher      // interface
semantic.Embedder            // interface
semantic.ElementDescriptor   // struct
semantic.ElementMatch        // struct
semantic.FindOptions         // struct
semantic.FindResult          // struct

// Constructors
semantic.NewCombinedMatcher(embedder)  → ElementMatcher
semantic.NewHashingEmbedder(dim)       → Embedder
semantic.NewLexicalMatcher()           → ElementMatcher
semantic.NewEmbeddingMatcher(e)        → ElementMatcher

// Functions
semantic.CalibrateConfidence(score)    → string
semantic.LexicalScore(query, desc)     → float64
semantic.CosineSimilarity(a, b)        → float64

// Recovery subpackage
recovery.IntentCache, recovery.IntentEntry
recovery.RecoveryEngine, recovery.RecoveryResult
recovery.ClassifyFailure, recovery.DefaultRecoveryConfig

Testing

• 167 tests across 3 packages (root, engine, recovery)
• internal/engine/ has unit tests for all matchers + benchmark suite
• Root has API-level smoke tests
• recovery/ has scenario tests (SPA re-render, checkout, login, etc.)

Release Process

1. Update npm/package.json version
2. git tag v0.X.0 && git push origin v0.X.0
3. CI builds binaries (GoReleaser) + opens homebrew tap PR
4. npm publish manually or via release-manual-publish.yml