openlore 2.0.0

package/examples/opencode-skills/openlore-write-tests/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: openlore-write-tests
+description: Write real tests for a function or spec scenario — language-agnostic (TypeScript, Python, C++…). Reads the implementation and spec contract first, runs tests, fixes failures. No stubs, no placeholders.
+license: MIT
+compatibility: openlore MCP server
+---
+
+# openlore: Write Tests
+
+## When to use this skill
+
+Trigger this skill when the user wants to **write real tests** for a function, module, or spec
+scenario, with phrasings like:
+- "write tests for X"
+- "add test coverage for Y"
+- "what spec scenarios are untested?"
+- "implement the test for this scenario"
+- explicit command `/openlore-write-tests`
+
+**The rule**: read the implementation and spec contract before writing a single assertion.
+No `expect(true).toBe(true)`, no stubs, no placeholders.
+
+**Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
+If `orient` returns `"error": "no cache"` → run `openlore analyze` first, then retry.
+
+---
+
+## Step 1 — Identify target + detect framework
+
+Ask the user:
+1. **Target** — a function name, file path, spec scenario, or domain to test. If unsure, skip to Step 1b.
+2. **`$PROJECT_ROOT`** — project root directory.
+
+**Step 1b — Find untested scenarios (if no target given)**
+
+Call the openlore MCP tool `get_test_coverage` with `{"directory": "$PROJECT_ROOT"}`.
+
+Present the top 5 uncovered scenarios to the user, ranked by spec importance. Ask which to implement first.
+
+**Step 1c — Detect test framework**
+
+Scan the project root for framework config files:
+
+| File found | Framework |
+|---|---|
+| `vitest.config.*`, `vitest.config.ts` | Vitest — runner: `npx vitest run <file>` |
+| `jest.config.*` | Jest — runner: `npx jest <file>` |
+| `pytest.ini`, `pyproject.toml` (with `[tool.pytest]`), `setup.cfg` | pytest — runner: `pytest <file> -v` |
+| `CMakeLists.txt` with `enable_testing()`, `*.test.cpp` | CTest/GTest — runner: build + `ctest` |
+| `go.mod` | Go test — runner: `go test ./...` |
+
+Store as `$TEST_RUNNER`. If ambiguous, ask the user.
+
+---
+
+## Step 2 — Orient
+
+Call the openlore MCP tool `orient` with:
+```json
+{
+  "directory": "$PROJECT_ROOT",
+  "task": "write tests for $TARGET",
+  "limit": 5
+}
+```
+
+Extract:
+- **`$TARGET_FILE`** — the file containing the function(s) to test
+- **`$EXISTING_TEST_FILE`** — nearby test file, if any (e.g. `foo.test.ts`, `test_foo.py`, `foo_test.go`)
+- **`$SPEC_DOMAIN`** — the spec domain associated with the target
+
+---
+
+## Step 3 — Read implementation + spec contract
+
+**This step is mandatory. Do not write any test before completing it.**
+
+**3a — Read the function body**
+
+Call the openlore MCP tool `get_function_body` with:
+```json
+{
+  "directory": "$PROJECT_ROOT",
+  "symbol": "$TARGET_FUNCTION",
+  "filePath": "$TARGET_FILE"
+}
+```
+
+Identify:
+- What the function takes as input, what it returns
+- What external dependencies it calls (filesystem, network, DB, LLM, subprocess)
+- What invariants are visible (guards, throws, early returns)
+
+**3b — Find the spec contract (if specs exist)**
+
+Call the openlore MCP tool `search_specs` with:
+```json
+{
+  "directory": "$PROJECT_ROOT",
+  "query": "$TARGET — expected behaviour",
+  "limit": 5
+}
+```
+
+For each matching spec scenario, note:
+- The **GIVEN / WHEN / THEN** clauses — these become the test body
+- The scenario name — this becomes the `it()` / `def test_` / `TEST()` description
+
+If no specs exist, infer the contract from the function signature, docstring, and call sites.
+Document the inferred contract explicitly before writing any test.
+
+**3c — Absorb local test conventions**
+
+If `$EXISTING_TEST_FILE` exists, read it. Extract:
+- Mock setup pattern (`vi.mock`, `unittest.mock.patch`, `gmock`, etc.)
+- Fixture or factory helpers
+- Import path style (relative vs absolute)
+- Describe/class/suite structure
+
+If no test file exists nearby, find the closest test file in the project tree and read that instead.
+
+---
+
+## Step 4 — Write tests
+
+Write (or append to) `$EXISTING_TEST_FILE` (or create `<name>.test.ts` / `test_<name>.py` / `<name>_test.go` next to the source file).
+
+### Rules — enforced without exception
+
+1. **No placeholder assertions** — `expect(true).toBe(true)`, `assert True`, `EXPECT_TRUE(true)`,
+   `self.assertTrue(True)` are forbidden. Every assertion must test real return values or side effects.
+
+2. **One test = one scenario** — each `it()` / `def test_` / `TEST()` maps to one GIVEN/WHEN/THEN
+   clause. Use the spec scenario name (or a descriptive contract statement) as the test description.
+
+3. **Annotation tag (mandatory)** — place a coverage tag on the line immediately above each
+   `describe` / class / suite block so `openlore test --coverage` can track it:
+   - TypeScript/JS: `// openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO","specFile":"openspec/specs/$DOMAIN/spec.md"}`
+   - Python: `# openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO"}`
+   - C++/Go: `// openlore: {"domain":"$DOMAIN","requirement":"$REQ","scenario":"$SCENARIO"}`
+
+   If no spec scenario exists (contract inferred), omit the tag.
+
+4. **Mock only system boundaries** — mock filesystem, network, LLM API, DB connections, and
+   external processes. Do not mock the function under test, its pure helpers, or in-memory logic.
+
+5. **One suite per function** — `describe` / class / suite named after the function.
+   Use nested blocks for distinct concerns (happy path, error path, edge cases).
+
+6. **At least one edge case** — empty input, null/None/nullptr, maximum value, or an error path
+   must be included for every function tested.
+
+7. **Small model constraint** — if the test file exceeds 200 lines, split into multiple files
+   grouped by concern. Each file must be independently runnable.
+
+### Structure reference (adapt to the detected framework)
+
+```typescript
+// TypeScript / Vitest
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { $TARGET_FUNCTION } from '../$TARGET_FILE';
+
+vi.mock('../$DEPENDENCY', () => ({ ... }));
+
+// openlore: {"domain":"$DOMAIN","requirement":"$REQUIREMENT","scenario":"$SCENARIO","specFile":"openspec/specs/$DOMAIN/spec.md"}
+describe('$TARGET_FUNCTION', () => {
+  beforeEach(() => { vi.resetAllMocks(); });
+
+  describe('$SCENARIO_NAME', () => {
+    it('should $EXPECTED_BEHAVIOUR when $CONDITION', () => {
+      // GIVEN
+      // WHEN
+      const result = $TARGET_FUNCTION($INPUT);
+      // THEN
+      expect(result).toEqual($EXPECTED);
+    });
+  });
+});
+```
+
+```python
+# Python / pytest
+import pytest
+from unittest.mock import patch, MagicMock
+from $MODULE import $TARGET_FUNCTION
+
+# openlore: {"domain":"$DOMAIN","requirement":"$REQUIREMENT","scenario":"$SCENARIO"}
+class Test$TargetFunction:
+    def test_$scenario_name_when_$condition(self):
+        # GIVEN / WHEN / THEN
+        result = $target_function($input)
+        assert result == $expected
+```
+
+---
+
+## Step 5 — Run and fix
+
+Run the test file with `$TEST_RUNNER`. Iterate until all tests pass.
+
+| Outcome | Action |
+|---|---|
+| All green | Proceed to Step 6 |
+| Failure in new test | Diagnose: is the assertion wrong, or is there a real bug? Fix the assertion if the expectation was incorrect. If a real bug is revealed, do not weaken the assertion — report the bug instead. |
+| Failure in pre-existing test | Stop. Fix the regression before adding more tests. |
+| Test can't compile / import | Fix the import path, mock setup, or dependency injection before retrying. |
+
+Do not weaken assertions to make tests pass. A test that masks a bug is worse than no test.
+
+---
+
+## Step 6 — Coverage check
+
+Call the openlore MCP tool `get_test_coverage` with `{"directory": "$PROJECT_ROOT"}`.
+
+Report:
+- Which spec scenarios are now covered (new)
+- Which scenarios remain uncovered in `$SPEC_DOMAIN`
+- Whether any hub functions in `$SPEC_DOMAIN` are still untested (high-value next targets)
+
+---
+
+## Absolute constraints
+
+- Never write `expect(true).toBe(true)`, `assert True`, or equivalent placeholder assertions
+- Never skip Step 3 — the implementation read and spec contract are the test source of truth
+- Never mock the function under test itself
+- Never weaken an assertion to make a test pass — fix the implementation or the expectation
+- If `get_test_coverage` shows the scenario is already covered, report it and stop
+- Do not refactor the implementation as part of this skill — open a separate task

package/examples/openspec-analysis/README.md

@@ -0,0 +1,59 @@
+# Example: OpenSpec CLI Analysis
+
+This directory contains the output of running `openlore analyze` against the OpenSpec CLI codebase itself.
+
+## How This Was Generated
+
+```bash
+cd /path/to/OpenSpec-main
+openlore init
+openlore analyze
+```
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| `config.json` | openlore configuration for the project |
+| `SUMMARY.md` | Human-readable analysis summary |
+| `repo-structure.json` | Complete file metadata and significance scores |
+| `dependency-graph.json` | Import/export relationships between files |
+| `llm-context.json` | Optimized context for LLM generation |
+| `dependencies.mermaid` | Visual dependency graph |
+
+## Key Findings
+
+From analyzing the OpenSpec CLI:
+
+- **221 files analyzed** (TypeScript, Markdown, JSON)
+- **50 high-value files** identified for spec generation
+- **37 domain clusters** detected
+
+### Detected Domains
+
+1. **completions** - Shell completion providers (16 files)
+2. **command-generation** - IDE command generation (26 files)
+3. **artifact-graph** - Artifact dependency resolution (7 files)
+4. **schemas** - Configuration schemas (9 files)
+5. **validation** - Spec validation (3 files)
+6. **commands** - CLI commands (14 files)
+7. **parsers** - Markdown/requirement parsing (3 files)
+
+### Top Significant Files
+
+1. `src/core/completions/types.ts` (score: 65)
+2. `src/core/command-generation/types.ts` (score: 65)
+3. `src/core/artifact-graph/types.ts` (score: 65)
+4. `src/core/config-schema.ts` (score: 65)
+5. `src/core/schemas/change.schema.ts` (score: 60)
+
+## Next Steps
+
+To generate full specifications, run:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+openlore generate
+```
+
+This will create OpenSpec-format specifications in `openspec/specs/`.

package/examples/openspec-analysis/SUMMARY.md

@@ -0,0 +1,72 @@
+# Repository Analysis: @fission-ai/openspec
+
+## Overview
+- **Type**: Node.js/TypeScript
+- **Frameworks**: Vitest, GitHub Actions
+- **Files Analyzed**: 221 of 231 (10 skipped)
+- **Analysis Date**: 2026-01-31T15:45:00.646Z
+
+## Architecture Pattern
+This appears to be a **unknown** architecture.
+
+**Detected Layers:**
+- Infrastructure Layer: Configuration, middleware, and utilities (30 files)
+
+## Language Breakdown
+| Language | Files | Percentage |
+|----------|-------|------------|
+| TypeScript | 172 | 78.0% |
+| Markdown | 26 | 12.0% |
+| JSON | 7 | 3.0% |
+|  | 4 | 2.0% |
+| JavaScript | 3 | 1.0% |
+
+## Detected Domains
+These domains will become OpenSpec specifications:
+
+| Domain | Files | Key Entities | Spec Path |
+|--------|-------|--------------|-----------|
+| completions | 16 | CompletionProvider, Factory, BashGenerator | `openspec/specs/completions/spec.md` |
+| command-generation | 26 | Registry, Cursor, Windsurf | `openspec/specs/command-generation/spec.md` |
+| artifact-graph | 7 | Schema, Resolver, InstructionLoader | `openspec/specs/artifact-graph/spec.md` |
+| schemas | 9 | ChangeSchema, BaseSchema, SchemaYaml | `openspec/specs/schemas/spec.md` |
+| validation | 3 | Validator | `openspec/specs/validation/spec.md` |
+| commands | 14 | Schemas, Feedback, Schema | `openspec/specs/commands/spec.md` |
+| parsers | 3 | RequirementBlocks, ChangeParser, MarkdownParser | `openspec/specs/parsers/spec.md` |
+| templates | 2 | SkillTemplates | `openspec/specs/templates/spec.md` |
+| users | 5 | LlmContextJson, SUMMARYMd, DependencyGraphJson | `openspec/specs/users/spec.md` |
+| ui | 2 | AsciiPatterns, WelcomeScreen | `openspec/specs/ui/spec.md` |
+
+## Dependency Insights
+
+**Most Connected Files:**
+- `package.json` (5 connections)
+- `src/commands/feedback.ts` (1 connections)
+- `src/core/init.ts` (1 connections)
+
+**Orphan Files**: 215 file(s) with no imports or exports
+
+## Files Selected for Deep Analysis
+The following files were selected as most significant:
+
+1. `src/core/completions/types.ts` (score: 65) - high-value-name
+2. `src/core/command-generation/types.ts` (score: 65) - high-value-name
+3. `src/core/artifact-graph/types.ts` (score: 65) - high-value-name
+4. `src/core/config-schema.ts` (score: 65) - schema, high-value-name
+5. `src/core/schemas/change.schema.ts` (score: 60) - schema, high-value-name
+6. `src/core/schemas/base.schema.ts` (score: 60) - schema, high-value-name
+7. `src/core/validation/types.ts` (score: 60) - high-value-name
+8. `src/core/artifact-graph/schema.ts` (score: 60) - schema, high-value-name
+9. `src/core/global-config.ts` (score: 60) - config, high-value-name
+10. `src/core/project-config.ts` (score: 60) - config, high-value-name
+11. `src/core/completions/completion-provider.ts` (score: 55) - service
+12. `src/core/config.ts` (score: 55) - config, high-value-name
+13. `src/commands/workflow/schemas.ts` (score: 55) - schema, high-value-name
+14. `src/commands/feedback.ts` (score: 55) - high-value-name
+15. `src/telemetry/config.ts` (score: 55) - config, high-value-name
+
+## Recommendations
+- Review 215 orphan file(s) that may be unused
+
+---
+*Generated by openlore v1.0.0*

package/examples/openspec-analysis/config.json

@@ -0,0 +1,16 @@
+{
+  "version": "1.0.0",
+  "projectType": "nodejs",
+  "openspecPath": "./openspec",
+  "analysis": {
+    "maxFiles": 500,
+    "includePatterns": [],
+    "excludePatterns": []
+  },
+  "generation": {
+    "model": "claude-sonnet-4-20250514",
+    "domains": "auto"
+  },
+  "createdAt": "2026-01-31T15:44:29.845Z",
+  "lastRun": null
+}

package/examples/openspec-analysis/dependencies.mermaid

@@ -0,0 +1,35 @@
+```mermaid
+graph TD
+    N0["types.ts"]
+    N1["types.ts"]
+    N2["types.ts"]
+    N3["config-schema.ts"]
+    N4["change.schema.ts"]
+    N5["base.schema.ts"]
+    N6["types.ts"]
+    N7["schema.ts"]
+    N8["global-config.ts"]
+    N9["project-config.ts"]
+    N10["completion-provider.ts"]
+    N11["config.ts"]
+    N12["schemas.ts"]
+    N13["feedback.ts"]
+    N14["config.ts"]
+    N15["schema.yaml"]
+    N16["spec.schema.ts"]
+    N17["schema.ts"]
+    N18["requirement-blocks.ts"]
+    N19["change-parser.ts"]
+    N20["markdown-parser.ts"]
+    N21["factory.ts"]
+    N22["skill-generation.ts"]
+    N23["tool-detection.ts"]
+    N24["registry.ts"]
+    N25["resolver.ts"]
+    N26["instruction-loader.ts"]
+    N27["init.ts"]
+    N28["config-prompts.ts"]
+    N29["package.json"]
+    N13 --> N29
+    N27 --> N29
+```