@soleri/core 9.13.0 → 9.14.0

package/dist/knowledge-packs/knowledge-packs/starter/react/vault/patterns.json

@@ -0,0 +1,164 @@
+[
+  {
+    "id": "react-001",
+    "type": "rule",
+    "domain": "react",
+    "title": "Rules of Hooks — Call Order and No Conditionals",
+    "severity": "critical",
+    "description": "Hooks must be called at the top level of a component or custom hook, in the same order every render. Never call hooks inside conditionals, loops, or nested functions — React relies on call order to track state.\n\nBad:\n```jsx\nif (isLoggedIn) {\n  const [name, setName] = useState('');\n}\n```\n\nGood:\n```jsx\nconst [name, setName] = useState('');\n// use `name` conditionally in the render, not the hook itself\n```",
+    "tags": ["react", "hooks", "rules"]
+  },
+  {
+    "id": "react-002",
+    "type": "pattern",
+    "domain": "react",
+    "title": "Extract Custom Hooks for Reusable Logic",
+    "severity": "suggestion",
+    "description": "When two or more components share stateful logic, extract it into a custom hook. Custom hooks compose — they can call other hooks. Name them `use*` so React enforces hook rules.\n\nExample:\n```jsx\nfunction useDebounce(value, delay) {\n  const [debounced, setDebounced] = useState(value);\n  useEffect(() => {\n    const id = setTimeout(() => setDebounced(value), delay);\n    return () => clearTimeout(id);\n  }, [value, delay]);\n  return debounced;\n}\n\n// Usage in any component\nconst debouncedSearch = useDebounce(query, 300);\n```",
+    "tags": ["react", "hooks", "reusability", "composition"]
+  },
+  {
+    "id": "react-003",
+    "type": "pattern",
+    "domain": "react",
+    "title": "Composition Over Prop Drilling",
+    "severity": "warning",
+    "description": "Instead of passing props through 3+ layers of components, restructure using composition. Pass components as children or props so intermediate layers don't need to know about the data.\n\nBad:\n```jsx\n<Layout user={user}>\n  <Sidebar user={user}>\n    <UserMenu user={user} />\n  </Sidebar>\n</Layout>\n```\n\nGood:\n```jsx\n<Layout sidebar={<Sidebar><UserMenu user={user} /></Sidebar>}>\n  {children}\n</Layout>\n```\n\nThe Layout and Sidebar no longer need to know about `user` at all.",
+    "tags": ["react", "composition", "props", "architecture"]
+  },
+  {
+    "id": "react-004",
+    "type": "pattern",
+    "domain": "react",
+    "title": "Controlled vs Uncontrolled Components",
+    "severity": "suggestion",
+    "description": "Controlled components derive their value from React state (`value` + `onChange`). Uncontrolled components use the DOM as the source of truth (`defaultValue` + `ref`). Default to controlled for forms that need validation, conditional logic, or shared state. Use uncontrolled for simple isolated inputs where you only need the value on submit.\n\nControlled:\n```jsx\nconst [email, setEmail] = useState('');\n<input value={email} onChange={e => setEmail(e.target.value)} />\n```\n\nUncontrolled:\n```jsx\nconst inputRef = useRef(null);\n<input defaultValue=\"\" ref={inputRef} />\n// read inputRef.current.value on submit\n```",
+    "tags": ["react", "forms", "state", "components"]
+  },
+  {
+    "id": "react-005",
+    "type": "anti-pattern",
+    "domain": "react",
+    "title": "Premature useMemo and useCallback",
+    "severity": "warning",
+    "description": "Don't wrap every value in `useMemo` or every function in `useCallback` by default. Memoization has a cost — the hook comparison runs every render. It only helps when: (1) the value is passed to a `React.memo`-wrapped child, (2) the computation is genuinely expensive, or (3) the value is a dependency of another hook.\n\nBad:\n```jsx\nconst label = useMemo(() => `Hello ${name}`, [name]); // trivial computation\nconst handleClick = useCallback(() => setOpen(true), []); // no memo'd child\n```\n\nGood — only memoize when it matters:\n```jsx\nconst sorted = useMemo(() => items.sort(compareFn), [items]); // expensive\n<MemoizedList onSelect={useCallback(fn, [deps])} /> // memo'd child\n```",
+    "tags": ["react", "hooks", "performance", "memoization"]
+  },
+  {
+    "id": "react-006",
+    "type": "anti-pattern",
+    "domain": "react",
+    "title": "Avoid Premature React.memo",
+    "severity": "warning",
+    "description": "Don't wrap components in `React.memo` without measuring first. Memo adds a shallow comparison on every render. If the component receives objects or functions as props (which are new references every render), memo provides zero benefit while adding overhead. Profile first, then memo components that: (1) render often with the same props, (2) are expensive to render, and (3) receive stable prop references.\n\nBad:\n```jsx\nexport default React.memo(SmallStatelessLabel); // trivial render\n```\n\nGood:\n```jsx\n// Profile shows this list item re-renders 500 times with same props\nexport default React.memo(ExpensiveListItem);\n```",
+    "tags": ["react", "performance", "memoization"]
+  },
+  {
+    "id": "react-007",
+    "type": "pattern",
+    "domain": "react",
+    "title": "Error Boundaries for Graceful Failure",
+    "severity": "warning",
+    "description": "Wrap major UI sections in error boundaries so a crash in one widget doesn't take down the entire page. Place them at route level, around third-party components, and around data-dependent sections.\n\n```jsx\nclass ErrorBoundary extends React.Component {\n  state = { hasError: false };\n  static getDerivedStateFromError() { return { hasError: true }; }\n  componentDidCatch(error, info) { logError(error, info); }\n  render() {\n    if (this.state.hasError) return <FallbackUI onRetry={() => this.setState({ hasError: false })} />;\n    return this.props.children;\n  }\n}\n\n// Usage\n<ErrorBoundary><Dashboard /></ErrorBoundary>\n```\n\nError boundaries catch errors in rendering, lifecycle methods, and constructors — not in event handlers or async code.",
+    "tags": ["react", "error-handling", "resilience"]
+  },
+  {
+    "id": "react-008",
+    "type": "rule",
+    "domain": "react",
+    "title": "Keys Must Be Stable, Unique, and Data-Derived",
+    "severity": "critical",
+    "description": "List keys must be stable across renders, unique among siblings, and derived from the data — never from the array index (unless the list is truly static and never reordered).\n\nBad:\n```jsx\n{items.map((item, index) => <Item key={index} {...item} />)}\n// Reordering or inserting corrupts component state\n```\n\nBad:\n```jsx\n{items.map(item => <Item key={Math.random()} {...item} />)}\n// Forces full remount every render\n```\n\nGood:\n```jsx\n{items.map(item => <Item key={item.id} {...item} />)}\n```",
+    "tags": ["react", "lists", "keys", "reconciliation"]
+  },
+  {
+    "id": "react-009",
+    "type": "pattern",
+    "domain": "react",
+    "title": "State Colocation — Keep State Close to Where It's Used",
+    "severity": "warning",
+    "description": "Start with state in the component that uses it. Only lift state up when a sibling genuinely needs it. Global state managers are for truly global concerns (auth, theme, feature flags) — not for form inputs or toggle states.\n\nBad:\n```jsx\n// Redux store holds isDropdownOpen for a single component\nconst isOpen = useSelector(s => s.ui.headerDropdownOpen);\n```\n\nGood:\n```jsx\n// Local state — only this component cares\nconst [isOpen, setIsOpen] = useState(false);\n```\n\nRule of thumb: if only one component reads the state, it belongs in that component.",
+    "tags": ["react", "state", "architecture", "colocation"]
+  },
+  {
+    "id": "react-010",
+    "type": "anti-pattern",
+    "domain": "react",
+    "title": "Derived State — Compute, Don't Sync",
+    "severity": "warning",
+    "description": "Never use `useEffect` to synchronize state that can be computed from other state or props. Compute it inline during render, or use `useMemo` if the computation is expensive.\n\nBad:\n```jsx\nconst [items, setItems] = useState([]);\nconst [count, setCount] = useState(0);\nuseEffect(() => setCount(items.length), [items]);\n```\n\nGood:\n```jsx\nconst [items, setItems] = useState([]);\nconst count = items.length; // derived — no state needed\n```\n\nThe anti-pattern causes an extra render cycle and can lead to visual tearing where the UI briefly shows stale derived values.",
+    "tags": ["react", "hooks", "state", "useEffect"]
+  },
+  {
+    "id": "react-011",
+    "type": "pattern",
+    "domain": "react",
+    "title": "useRef for Mutable Values That Don't Trigger Renders",
+    "severity": "suggestion",
+    "description": "Use `useRef` for values that need to persist across renders but shouldn't cause re-renders when they change: timer IDs, previous values, DOM references, instance-level flags.\n\n```jsx\nfunction useInterval(callback, delay) {\n  const savedCallback = useRef(callback);\n  // Update ref on every render so the interval always calls latest callback\n  useEffect(() => { savedCallback.current = callback; });\n  useEffect(() => {\n    const id = setInterval(() => savedCallback.current(), delay);\n    return () => clearInterval(id);\n  }, [delay]);\n}\n```\n\nAnti-pattern: using `useState` for values the UI never reads — it causes unnecessary re-renders.",
+    "tags": ["react", "hooks", "useRef", "performance"]
+  },
+  {
+    "id": "react-012",
+    "type": "pattern",
+    "domain": "react",
+    "title": "Suspense Boundaries for Async Loading",
+    "severity": "suggestion",
+    "description": "Use React Suspense to declaratively handle loading states for lazy-loaded components and data fetching (with supporting libraries). Place Suspense boundaries strategically — one per meaningful loading zone, not one per component.\n\n```jsx\nconst Dashboard = React.lazy(() => import('./Dashboard'));\n\nfunction App() {\n  return (\n    <Suspense fallback={<DashboardSkeleton />}>\n      <Dashboard />\n    </Suspense>\n  );\n}\n```\n\nNest Suspense boundaries for granular loading: a page-level boundary shows a full skeleton, while a widget-level boundary shows individual widget placeholders.",
+    "tags": ["react", "suspense", "performance", "loading"]
+  },
+  {
+    "id": "react-013",
+    "type": "anti-pattern",
+    "domain": "react",
+    "title": "Context API Pitfall — Frequently Changing Values",
+    "severity": "warning",
+    "description": "Every component consuming a context re-renders when the context value changes — even if it only reads a stable slice. Don't put frequently changing values (mouse position, animation frames, rapidly updating form state) in context.\n\nBad:\n```jsx\n<AppContext.Provider value={{ user, theme, mousePosition }}>\n// Every mousemove re-renders ALL consumers\n```\n\nGood — split contexts by update frequency:\n```jsx\n<UserContext.Provider value={user}>\n  <ThemeContext.Provider value={theme}>\n    {children}\n  </ThemeContext.Provider>\n</UserContext.Provider>\n```\n\nFor high-frequency values, use a ref-based subscription pattern or a dedicated state library.",
+    "tags": ["react", "context", "performance", "state"]
+  },
+  {
+    "id": "react-014",
+    "type": "rule",
+    "domain": "react",
+    "title": "One Component Per File",
+    "severity": "suggestion",
+    "description": "Each React component gets its own file, named to match the component. Co-locate related files (styles, tests, types) in the same directory. Small helper components used only by one parent can live in the same file, but if they grow or get reused, extract them.\n\n```\nButton/\n  Button.tsx        // component\n  Button.test.tsx   // tests\n  Button.module.css // styles\n  index.ts          // re-export\n```\n\nThis makes components easy to find, move, and delete. A file with 5 components is a file where no one can find anything.",
+    "tags": ["react", "file-structure", "organization", "conventions"]
+  },
+  {
+    "id": "react-015",
+    "type": "rule",
+    "domain": "react",
+    "title": "Event Handler Naming Conventions",
+    "severity": "suggestion",
+    "description": "Use `handle*` for the function definition and `on*` for the prop name. This creates a clear contract: the parent says what event it cares about, the child says how it handles it.\n\n```jsx\n// Parent\nfunction Form() {\n  const handleSubmit = (data) => { /* ... */ };\n  return <SearchField onSubmit={handleSubmit} />;\n}\n\n// Child\nfunction SearchField({ onSubmit }) {\n  const handleKeyDown = (e) => {\n    if (e.key === 'Enter') onSubmit(e.target.value);\n  };\n  return <input onKeyDown={handleKeyDown} />;\n}\n```\n\nConsistent naming makes it immediately clear which functions are event handlers during code review.",
+    "tags": ["react", "conventions", "naming", "events"]
+  },
+  {
+    "id": "react-016",
+    "type": "anti-pattern",
+    "domain": "react",
+    "title": "useEffect as Event Handler",
+    "severity": "warning",
+    "description": "Don't use `useEffect` to respond to events. Effects are for synchronizing with external systems, not for reacting to user actions. If something should happen when a button is clicked, put it in the click handler.\n\nBad:\n```jsx\nconst [submitted, setSubmitted] = useState(false);\nuseEffect(() => {\n  if (submitted) { sendAnalytics(); navigate('/thanks'); }\n}, [submitted]);\nconst handleSubmit = () => setSubmitted(true);\n```\n\nGood:\n```jsx\nconst handleSubmit = () => {\n  sendAnalytics();\n  navigate('/thanks');\n};\n```\n\nThe effect version adds an unnecessary state variable, an extra render, and makes the flow harder to trace.",
+    "tags": ["react", "hooks", "useEffect", "events"]
+  },
+  {
+    "id": "react-017",
+    "type": "pattern",
+    "domain": "react",
+    "title": "Prefer Enums and Union Types Over Boolean Props",
+    "severity": "suggestion",
+    "description": "When a component has mutually exclusive modes, use a union-typed prop instead of multiple booleans. This prevents impossible states and is self-documenting.\n\nBad:\n```jsx\n<Button isPrimary isOutlined isGhost /> // which one wins?\n```\n\nGood:\n```jsx\n<Button variant=\"primary\" />\n<Button variant=\"outlined\" />\n<Button variant=\"ghost\" />\n// type Variant = 'primary' | 'outlined' | 'ghost'\n```\n\nThis extends to size, status, and any prop where only one value should apply at a time.",
+    "tags": ["react", "typescript", "api-design", "components"]
+  },
+  {
+    "id": "react-018",
+    "type": "anti-pattern",
+    "domain": "react",
+    "title": "Fetching Data in useEffect Without Cleanup",
+    "severity": "warning",
+    "description": "When fetching data in `useEffect`, always handle cleanup to avoid setting state on unmounted components and to cancel stale requests.\n\nBad:\n```jsx\nuseEffect(() => {\n  fetch(`/api/user/${id}`).then(r => r.json()).then(setUser);\n}, [id]);\n// Race condition: fast id changes cause stale responses to overwrite fresh ones\n```\n\nGood:\n```jsx\nuseEffect(() => {\n  const controller = new AbortController();\n  fetch(`/api/user/${id}`, { signal: controller.signal })\n    .then(r => r.json())\n    .then(setUser)\n    .catch(e => { if (e.name !== 'AbortError') throw e; });\n  return () => controller.abort();\n}, [id]);\n```\n\nBetter yet, use a data-fetching library (TanStack Query, SWR) that handles caching, deduplication, and race conditions.",
+    "tags": ["react", "hooks", "useEffect", "data-fetching", "async"]
+  }
+]

package/dist/knowledge-packs/knowledge-packs/starter/security/soleri-pack.json

@@ -0,0 +1,10 @@
+{
+  "id": "starter-security",
+  "name": "Security Starter Pack",
+  "version": "1.0.0",
+  "description": "OWASP Top 10, auth patterns, input validation, secrets management — essential security patterns and anti-patterns for any codebase.",
+  "domains": ["security"],
+  "vault": {
+    "dir": "vault"
+  }
+}

package/dist/knowledge-packs/knowledge-packs/starter/security/vault/patterns.json

@@ -0,0 +1,137 @@
+[
+  {
+    "id": "sec-001",
+    "type": "pattern",
+    "domain": "security",
+    "title": "Parameterized Queries",
+    "description": "Always use parameterized queries or prepared statements for database access. Never concatenate user input into SQL strings. This prevents SQL injection, the most common and most dangerous web vulnerability.",
+    "severity": "critical",
+    "tags": ["sql-injection", "owasp", "database"]
+  },
+  {
+    "id": "sec-002",
+    "type": "pattern",
+    "domain": "security",
+    "title": "Input Validation at System Boundaries",
+    "description": "Validate and sanitize all input at system boundaries: HTTP handlers, CLI args, file readers, message consumers. Use allowlists over denylists. Validate type, length, format, and range. Reject early, fail loudly.",
+    "severity": "critical",
+    "tags": ["input-validation", "owasp", "boundaries"]
+  },
+  {
+    "id": "sec-003",
+    "type": "pattern",
+    "domain": "security",
+    "title": "Secrets in Environment Variables",
+    "description": "Store secrets (API keys, database passwords, tokens) in environment variables or a secrets manager. Never store them in source code, config files committed to git, or client-side bundles. Use .env files locally with .gitignore protection.",
+    "severity": "critical",
+    "tags": ["secrets", "configuration", "environment"]
+  },
+  {
+    "id": "sec-004",
+    "type": "pattern",
+    "domain": "security",
+    "title": "Principle of Least Privilege",
+    "description": "Grant the minimum permissions necessary for each component, service, or user. Database connections should use read-only credentials when writes are not needed. API tokens should be scoped to required operations only.",
+    "severity": "warning",
+    "tags": ["access-control", "permissions", "zero-trust"]
+  },
+  {
+    "id": "sec-005",
+    "type": "pattern",
+    "domain": "security",
+    "title": "CSRF Protection with Tokens",
+    "description": "Protect state-changing endpoints with CSRF tokens. Use the synchronizer token pattern or double-submit cookie. SameSite cookie attributes provide defense-in-depth but are not sufficient alone.",
+    "severity": "warning",
+    "tags": ["csrf", "owasp", "cookies"]
+  },
+  {
+    "id": "sec-006",
+    "type": "pattern",
+    "domain": "security",
+    "title": "Content Security Policy Headers",
+    "description": "Set Content-Security-Policy headers to prevent XSS by controlling which scripts, styles, and resources can load. Start with a strict policy and relax as needed. Avoid unsafe-inline and unsafe-eval directives.",
+    "severity": "warning",
+    "tags": ["xss", "csp", "headers", "owasp"]
+  },
+  {
+    "id": "sec-007",
+    "type": "pattern",
+    "domain": "security",
+    "title": "Rate Limiting on Authentication Endpoints",
+    "description": "Apply rate limiting to login, password reset, and registration endpoints. Use exponential backoff or sliding window algorithms. Lock accounts after repeated failures. This prevents brute-force and credential stuffing attacks.",
+    "severity": "warning",
+    "tags": ["authentication", "rate-limiting", "brute-force"]
+  },
+  {
+    "id": "sec-008",
+    "type": "anti-pattern",
+    "domain": "security",
+    "title": "Hardcoded Credentials",
+    "description": "Never hardcode passwords, API keys, or tokens in source code. They end up in version control, logs, and error messages. Use environment variables or a secrets manager instead.",
+    "severity": "critical",
+    "tags": ["secrets", "credentials", "owasp"]
+  },
+  {
+    "id": "sec-009",
+    "type": "anti-pattern",
+    "domain": "security",
+    "title": "Rolling Your Own Crypto",
+    "description": "Never implement custom encryption, hashing, or token generation. Use well-tested libraries: bcrypt or argon2 for passwords, AES-256-GCM for encryption, crypto.randomUUID() for tokens. Custom crypto has subtle flaws that attackers exploit.",
+    "severity": "critical",
+    "tags": ["cryptography", "hashing", "encryption"]
+  },
+  {
+    "id": "sec-010",
+    "type": "anti-pattern",
+    "domain": "security",
+    "title": "Verbose Error Messages in Production",
+    "description": "Do not expose stack traces, SQL queries, or internal paths in production error responses. Return generic error messages to users and log details server-side. Information disclosure helps attackers map your system.",
+    "severity": "warning",
+    "tags": ["error-handling", "information-disclosure", "owasp"]
+  },
+  {
+    "id": "sec-011",
+    "type": "anti-pattern",
+    "domain": "security",
+    "title": "Disabling SSL Certificate Verification",
+    "description": "Never disable TLS certificate verification in production. This opens the door to man-in-the-middle attacks. Fix certificate issues at the source: install proper CA certificates, use correct hostnames.",
+    "severity": "critical",
+    "tags": ["tls", "ssl", "mitm"]
+  },
+  {
+    "id": "sec-012",
+    "type": "rule",
+    "domain": "security",
+    "title": "Dependency Audit on Every PR",
+    "description": "Run npm audit or equivalent on every pull request. Block merges with known critical vulnerabilities. Keep dependencies updated since most breaches exploit known vulnerabilities in outdated packages.",
+    "severity": "warning",
+    "tags": ["dependencies", "supply-chain", "ci-cd"]
+  },
+  {
+    "id": "sec-013",
+    "type": "pattern",
+    "domain": "security",
+    "title": "Output Encoding for XSS Prevention",
+    "description": "Encode output based on context: HTML entity encoding for HTML body, JavaScript encoding for script contexts, URL encoding for URL parameters. Use framework auto-escaping (React JSX, template engines) and avoid injecting raw HTML.",
+    "severity": "critical",
+    "tags": ["xss", "encoding", "owasp"]
+  },
+  {
+    "id": "sec-014",
+    "type": "pattern",
+    "domain": "security",
+    "title": "Secure Session Management",
+    "description": "Use HttpOnly, Secure, and SameSite flags on session cookies. Regenerate session IDs after authentication. Set appropriate expiration. Store sessions server-side with cryptographically random identifiers.",
+    "severity": "warning",
+    "tags": ["sessions", "cookies", "authentication"]
+  },
+  {
+    "id": "sec-015",
+    "type": "anti-pattern",
+    "domain": "security",
+    "title": "JWT Stored in localStorage",
+    "description": "Do not store JWTs or sensitive tokens in localStorage because it is accessible to any JavaScript on the page, making XSS attacks devastating. Use HttpOnly cookies instead, or store in memory with refresh token rotation.",
+    "severity": "warning",
+    "tags": ["jwt", "xss", "storage", "authentication"]
+  }
+]

package/dist/knowledge-packs/knowledge-packs/starter/testing/soleri-pack.json

@@ -0,0 +1,9 @@
+{
+  "id": "starter-testing",
+  "name": "Testing Starter Pack",
+  "version": "1.0.0",
+  "description": "Test pyramid, mocking strategies, TDD, flaky test prevention, assertion patterns — essential testing patterns.",
+  "domains": ["testing"],
+  "tier": "default",
+  "vault": { "dir": "vault" }
+}

package/dist/knowledge-packs/knowledge-packs/starter/testing/vault/patterns.json

@@ -0,0 +1,128 @@
+[
+  {
+    "id": "test-001",
+    "type": "pattern",
+    "domain": "testing",
+    "title": "Test Pyramid — Many Unit, Some Integration, Few E2E",
+    "description": "Structure your test suite as a pyramid: ~70% unit tests (fast, isolated, cheap), ~20% integration tests (verify module interactions), ~10% end-to-end tests (critical user flows only). Unit tests catch logic errors fast; integration tests catch wiring bugs; e2e tests catch real-world failures. An inverted pyramid (mostly e2e) leads to slow, brittle, expensive suites.\n\nExample ratio for a 500-test suite:\n- 350 unit tests (run in <10s)\n- 100 integration tests (run in <60s)\n- 50 e2e tests (run in <5min)",
+    "severity": "warning",
+    "tags": ["testing", "test-pyramid", "architecture"]
+  },
+  {
+    "id": "test-002",
+    "type": "pattern",
+    "domain": "testing",
+    "title": "Arrange-Act-Assert Structure for Every Test",
+    "description": "Every test should follow the AAA pattern for readability:\n\n```ts\ntest('calculates total with discount', () => {\n  // Arrange — set up preconditions\n  const cart = createCart([item(10), item(20)]);\n  const discount = percent(15);\n\n  // Act — execute the behavior under test\n  const total = cart.applyDiscount(discount);\n\n  // Assert — verify the outcome\n  expect(total).toBe(25.5);\n});\n```\n\nIf you can't clearly separate these three phases, the test is likely doing too much.",
+    "severity": "suggestion",
+    "tags": ["testing", "readability", "structure"]
+  },
+  {
+    "id": "test-003",
+    "type": "rule",
+    "domain": "testing",
+    "title": "Test Behavior, Not Implementation Details",
+    "description": "Tests should verify what the code does, not how it does it. Testing implementation details (private methods, internal state, call order) creates brittle tests that break on every refactor.\n\nBad — tests implementation:\n```ts\nexpect(service._cache.size).toBe(1);\nexpect(fetchSpy).toHaveBeenCalledTimes(1);\n```\n\nGood — tests behavior:\n```ts\nconst first = await service.getUser(1);\nconst second = await service.getUser(1);\nexpect(first).toEqual(second); // caching works\n```\n\nAsk: 'If I refactor internals without changing behavior, will this test break?' If yes, it's testing implementation.",
+    "severity": "warning",
+    "tags": ["testing", "refactoring", "maintainability"]
+  },
+  {
+    "id": "test-004",
+    "type": "rule",
+    "domain": "testing",
+    "title": "No Test Interdependence — Each Test Runs Alone",
+    "description": "Every test must pass when run in isolation, in any order. Never rely on shared mutable state, test execution order, or side effects from other tests.\n\nAnti-pattern:\n```ts\nlet user;\ntest('creates user', () => { user = createUser(); });\ntest('updates user', () => { updateUser(user.id, { name: 'New' }); }); // fails if run alone\n```\n\nFix: each test creates its own data in beforeEach or in the test body. Use fresh fixtures per test. Run tests with --randomize flag to catch hidden dependencies.",
+    "severity": "critical",
+    "tags": ["testing", "isolation", "reliability"]
+  },
+  {
+    "id": "test-005",
+    "type": "pattern",
+    "domain": "testing",
+    "title": "Mock at Boundaries, Not Internals",
+    "description": "Mock external dependencies (HTTP APIs, databases, file system, clocks) at the boundary of your system. Don't mock internal modules or utility functions — let them run with real code.\n\n```ts\n// Good — mock the boundary (HTTP client)\nconst api = mockHttpClient({ '/users/1': { name: 'Alice' } });\nconst service = new UserService(api);\nconst user = await service.getById(1);\nexpect(user.name).toBe('Alice');\n\n// Bad — mocking internal helper\njest.mock('./formatName'); // now you're testing nothing useful\n```\n\nBoundary mocks make tests fast and deterministic without sacrificing coverage of real logic.",
+    "severity": "warning",
+    "tags": ["testing", "mocking", "boundaries", "dependency-injection"]
+  },
+  {
+    "id": "test-006",
+    "type": "pattern",
+    "domain": "testing",
+    "title": "Use Test Factories for Complex Object Setup",
+    "description": "Create factory functions that produce valid test objects with sensible defaults. Override only what matters for each test.\n\n```ts\nfunction buildUser(overrides: Partial<User> = {}): User {\n  return {\n    id: randomId(),\n    name: 'Test User',\n    email: 'test@example.com',\n    role: 'viewer',\n    createdAt: new Date('2024-01-01'),\n    ...overrides,\n  };\n}\n\n// In tests — only specify what matters\ntest('admins can delete', () => {\n  const admin = buildUser({ role: 'admin' });\n  expect(canDelete(admin)).toBe(true);\n});\n```\n\nFactories reduce noise, prevent fragile tests, and make required vs incidental data obvious.",
+    "severity": "suggestion",
+    "tags": ["testing", "factories", "test-data", "maintainability"]
+  },
+  {
+    "id": "test-007",
+    "type": "pattern",
+    "domain": "testing",
+    "title": "One Logical Assertion Per Test",
+    "description": "Each test should verify one behavior. Multiple assertions are fine when they verify different aspects of the same behavior. Multiple assertions testing different behaviors should be separate tests.\n\nGood — one behavior, multiple asserts:\n```ts\ntest('creates user with defaults', () => {\n  const user = createUser({ name: 'Alice' });\n  expect(user.name).toBe('Alice');\n  expect(user.role).toBe('viewer');   // default\n  expect(user.active).toBe(true);     // default\n});\n```\n\nBad — two behaviors in one test:\n```ts\ntest('user lifecycle', () => {\n  const user = createUser({ name: 'Alice' });\n  expect(user.active).toBe(true);\n  deactivateUser(user.id);\n  expect(user.active).toBe(false); // separate behavior\n});\n```",
+    "severity": "suggestion",
+    "tags": ["testing", "assertions", "readability"]
+  },
+  {
+    "id": "test-008",
+    "type": "anti-pattern",
+    "domain": "testing",
+    "title": "Flaky Tests — Never Use Sleep, Use Polling",
+    "description": "Never use fixed delays (sleep, setTimeout) to wait for async operations. They're either too slow (wasted CI time) or too fast (flaky failures).\n\nBad:\n```ts\nawait sleep(2000);\nexpect(screen.getByText('Done')).toBeVisible();\n```\n\nGood:\n```ts\nawait waitFor(() => {\n  expect(screen.getByText('Done')).toBeVisible();\n}, { timeout: 5000 });\n```\n\nOther flaky test sources: shared state, network calls without mocks, time-dependent logic without fake clocks, random data without seeds. Fix the root cause — never retry-until-green.",
+    "severity": "critical",
+    "tags": ["testing", "flaky-tests", "async", "ci"]
+  },
+  {
+    "id": "test-009",
+    "type": "pattern",
+    "domain": "testing",
+    "title": "Descriptive Test Names: should_expected_when_condition",
+    "description": "Test names should describe the expected behavior and the condition that triggers it. Use a consistent naming convention across the suite.\n\nGood names:\n```ts\ntest('should return 404 when user does not exist', ...)\ntest('should apply discount when cart total exceeds 100', ...)\ntest('should reject empty email on registration', ...)\n```\n\nBad names:\n```ts\ntest('test1', ...)\ntest('works correctly', ...)\ntest('handles edge case', ...)\n```\n\nWhen a test fails, its name should tell you what broke without reading the code.",
+    "severity": "suggestion",
+    "tags": ["testing", "naming", "readability"]
+  },
+  {
+    "id": "test-010",
+    "type": "anti-pattern",
+    "domain": "testing",
+    "title": "Snapshot Testing Overuse",
+    "description": "Snapshot tests capture output and compare against a stored reference. They're useful for catching unexpected changes but dangerous when overused — developers blindly update snapshots without reviewing diffs.\n\nGood use: serialized data structures, CLI output, small component renders.\nBad use: large component trees, frequently changing UI, API responses.\n\nRules:\n- Keep snapshots small and focused\n- Always review snapshot diffs in code review\n- Use inline snapshots for small values: expect(result).toMatchInlineSnapshot()\n- If a snapshot updates on every change, replace it with explicit assertions",
+    "severity": "warning",
+    "tags": ["testing", "snapshots", "code-review"]
+  },
+  {
+    "id": "test-011",
+    "type": "rule",
+    "domain": "testing",
+    "title": "Code Coverage Is a Guide, Not a Goal",
+    "description": "Aim for ~80% code coverage as a healthy baseline. Don't chase 100% — it leads to low-value tests that test getters, setters, and trivial code.\n\nWhat to cover:\n- Business logic and domain rules\n- Error handling paths\n- Edge cases and boundary conditions\n- Integration points\n\nWhat to skip:\n- Simple getters/setters\n- Framework boilerplate\n- Generated code\n- Type-only files\n\nCoverage tells you what's NOT tested. High coverage doesn't mean good tests — you can have 100% coverage with zero meaningful assertions.",
+    "severity": "warning",
+    "tags": ["testing", "coverage", "metrics"]
+  },
+  {
+    "id": "test-012",
+    "type": "pattern",
+    "domain": "testing",
+    "title": "TDD Red-Green-Refactor Cycle",
+    "description": "Write tests before implementation in three steps:\n\n1. RED — Write a failing test for the next piece of behavior:\n```ts\ntest('should hash password before saving', async () => {\n  const user = await createUser({ password: 'plain' });\n  expect(user.password).not.toBe('plain');\n  expect(user.password).toMatch(/^\\$2b\\$/);\n});\n```\n\n2. GREEN — Write the minimum code to make it pass. No more.\n\n3. REFACTOR — Clean up the implementation while keeping tests green.\n\nTDD catches design issues early — if a test is hard to write, the API is hard to use. Small cycles (5-10 min) keep you focused and prevent over-engineering.",
+    "severity": "suggestion",
+    "tags": ["testing", "tdd", "workflow"]
+  },
+  {
+    "id": "test-013",
+    "type": "anti-pattern",
+    "domain": "testing",
+    "title": "Testing Through the UI for Logic Validation",
+    "description": "Don't write e2e or browser tests to verify business logic. If you need to check that a discount calculation is correct, test the calculation function directly — not by filling out a form, clicking submit, and reading the total from the DOM.\n\n```ts\n// Bad — slow, brittle, tests too many things at once\ntest('discount works', async () => {\n  await page.fill('#amount', '100');\n  await page.click('#apply-discount');\n  expect(await page.textContent('#total')).toBe('$85.00');\n});\n\n// Good — fast, focused, tests the actual logic\ntest('applies 15% discount', () => {\n  expect(applyDiscount(100, 0.15)).toBe(85);\n});\n```\n\nPush logic tests down to the unit level. Use e2e only for user flow validation.",
+    "severity": "warning",
+    "tags": ["testing", "test-pyramid", "e2e", "unit-tests"]
+  },
+  {
+    "id": "test-014",
+    "type": "pattern",
+    "domain": "testing",
+    "title": "Parameterized Tests for Multiple Input Cases",
+    "description": "When testing the same behavior with different inputs, use parameterized tests (test.each / it.each) instead of duplicating test bodies.\n\n```ts\ntest.each([\n  ['empty string', '', false],\n  ['valid email', 'a@b.com', true],\n  ['missing @', 'ab.com', false],\n  ['missing domain', 'a@', false],\n  ['unicode local', 'ñ@b.com', true],\n])('isValidEmail(%s) returns %s', (_label, input, expected) => {\n  expect(isValidEmail(input)).toBe(expected);\n});\n```\n\nBenefits: less duplication, easy to add cases, each case reports separately on failure. Use for validators, parsers, formatters, and any pure function with varied inputs.",
+    "severity": "suggestion",
+    "tags": ["testing", "parameterized", "dry", "readability"]
+  }
+]

package/dist/knowledge-packs/knowledge-packs/starter/typescript/soleri-pack.json

@@ -0,0 +1,9 @@
+{
+  "id": "starter-typescript",
+  "name": "TypeScript Starter Pack",
+  "version": "1.0.0",
+  "description": "Type narrowing, generics, module patterns, strict config, discriminated unions — essential TypeScript patterns for production code.",
+  "domains": ["typescript"],
+  "tier": "default",
+  "vault": { "dir": "vault" }
+}