spec-gen-cli 1.2.6 → 1.2.8

package/examples/openspec-cli/openspec/specs/parsing/spec.md

@@ -0,0 +1,123 @@
+# Parsing Specification
+
+> Generated by spec-gen on 2025-01-30
+> Source files: src/core/parsers/markdown-parser.ts, src/core/parsers/change-parser.ts, src/core/parsers/requirement-blocks.ts
+
+## Purpose
+
+Handles parsing of markdown-based specification files into structured data. Supports section-based extraction, requirement normalization, and delta block parsing for changes.
+
+## Entities
+
+### ParsedSection
+
+| Property | Type | Description |
+|----------|------|-------------|
+| heading | string | Section heading text |
+| level | number | Heading level (1-6) |
+| content | string | Section body content |
+| children | ParsedSection[] | Nested subsections |
+
+### ParsedRequirement
+
+| Property | Type | Description |
+|----------|------|-------------|
+| name | string | Requirement identifier |
+| text | string | Full requirement text |
+| scenarios | ParsedScenario[] | Associated test scenarios |
+| line | number | Source line number |
+
+### DeltaBlock
+
+| Property | Type | Description |
+|----------|------|-------------|
+| operation | 'ADDED' \| 'MODIFIED' \| 'REMOVED' \| 'RENAMED' | Delta type |
+| specPath | string | Target spec file path |
+| content | string | Delta content |
+
+## Requirements
+
+### Requirement: SectionParsing
+
+The system SHALL parse markdown files into hierarchical section structures based on heading levels.
+
+#### Scenario: NestedHeadingExtraction
+- **GIVEN** a markdown file with h1, h2, and h3 headings
+- **WHEN** the file is parsed
+- **THEN** sections are organized hierarchically
+- **AND** h2 sections are children of h1 sections
+
+#### Scenario: ContentExtraction
+- **GIVEN** a section with paragraph text and code blocks
+- **WHEN** the section is parsed
+- **THEN** all content between headings is captured
+- **AND** code blocks are preserved with formatting
+
+### Requirement: RequirementExtraction
+
+The system SHALL extract requirements from spec files following the "### Requirement:" pattern.
+
+#### Scenario: StandardRequirementParsing
+- **GIVEN** a spec with "### Requirement: UserAuth" heading
+- **WHEN** requirements are extracted
+- **THEN** a requirement named "UserAuth" is returned
+- **AND** the requirement text includes the paragraph below the heading
+
+#### Scenario: RequirementWithScenarios
+- **GIVEN** a requirement followed by "#### Scenario:" subsections
+- **WHEN** the requirement is parsed
+- **THEN** all scenarios are associated with the requirement
+- **AND** Given/When/Then content is captured
+
+### Requirement: DeltaBlockParsing
+
+The system SHALL parse delta blocks (ADDED, MODIFIED, REMOVED, RENAMED) from change spec files.
+
+#### Scenario: AddedRequirementParsing
+- **GIVEN** a change file with "## ADDED Requirements" section
+- **WHEN** deltas are extracted
+- **THEN** delta blocks with operation "ADDED" are returned
+- **AND** the spec path and content are captured
+
+#### Scenario: ModifiedRequirementParsing
+- **GIVEN** a change file with "## MODIFIED Requirements" section
+- **WHEN** deltas are extracted
+- **THEN** delta blocks with operation "MODIFIED" are returned
+- **AND** the full updated requirement content is included
+
+#### Scenario: RemovedRequirementParsing
+- **GIVEN** a change file with "## REMOVED Requirements" section containing "Reason:"
+- **WHEN** deltas are extracted
+- **THEN** delta blocks with operation "REMOVED" are returned
+- **AND** the removal reason is preserved
+
+### Requirement: GivenWhenThenExtraction
+
+The system SHALL extract Given/When/Then scenario content with proper formatting.
+
+#### Scenario: BoldLabelExtraction
+- **GIVEN** a scenario with "- **GIVEN** user is logged in"
+- **WHEN** the scenario is parsed
+- **THEN** the "GIVEN" clause is extracted as "user is logged in"
+
+#### Scenario: MultipleThens
+- **GIVEN** a scenario with THEN and AND clauses
+- **WHEN** the scenario is parsed
+- **THEN** all outcome clauses are captured
+- **AND** the AND clause is included in outcomes
+
+### Requirement: ErrorRecovery
+
+The system SHOULD attempt partial parsing when encountering malformed content.
+
+#### Scenario: MalformedSectionRecovery
+- **GIVEN** a spec file with one malformed section among valid sections
+- **WHEN** parsing is attempted
+- **THEN** valid sections are still extracted
+- **AND** a warning is reported for the malformed section
+
+## Technical Notes
+
+- **Implementation**: `src/core/parsers/markdown-parser.ts`, `src/core/parsers/change-parser.ts`
+- **Pattern**: Regex-based extraction with fallback strategies
+- **Dependencies**: None (pure TypeScript implementation)

package/examples/openspec-cli/openspec/specs/validation/spec.md

@@ -0,0 +1,108 @@
+# Validation Specification
+
+> Generated by spec-gen on 2025-01-30
+> Source files: src/core/validation/validator.ts, src/core/schemas/*.ts
+
+## Purpose
+
+Provides comprehensive validation of specs and changes using Zod schemas and custom semantic rules. Ensures all specifications follow RFC 2119 conventions and contain required elements.
+
+## Entities
+
+### ValidationReport
+
+| Property | Type | Description |
+|----------|------|-------------|
+| isValid | boolean | Overall validation result |
+| errors | ValidationMessage[] | Critical issues that must be fixed |
+| warnings | ValidationMessage[] | Issues that should be addressed |
+| info | ValidationMessage[] | Informational notes |
+
+### ValidationMessage
+
+| Property | Type | Description |
+|----------|------|-------------|
+| code | string | Error code (e.g., "MISSING_SHALL") |
+| message | string | Human-readable description |
+| location | string | File path or section reference |
+
+## Requirements
+
+### Requirement: SchemaValidation
+
+The system SHALL validate specs and changes against Zod schemas before processing.
+
+#### Scenario: ValidSpecStructure
+- **GIVEN** a spec file with valid YAML frontmatter and markdown body
+- **WHEN** validation is performed
+- **THEN** the schema validation passes
+- **AND** no structural errors are reported
+
+#### Scenario: InvalidSpecStructure
+- **GIVEN** a spec file missing required sections
+- **WHEN** validation is performed
+- **THEN** schema validation fails
+- **AND** specific missing sections are identified in errors
+
+### Requirement: RFC2119Keywords
+
+The system SHALL require RFC 2119 keywords (SHALL, MUST, SHOULD, MAY) in all requirements.
+
+#### Scenario: RequirementWithShall
+- **GIVEN** a requirement containing "The system SHALL validate input"
+- **WHEN** keyword validation is performed
+- **THEN** validation passes for this requirement
+
+#### Scenario: RequirementWithoutKeyword
+- **GIVEN** a requirement stating "The system validates input" (no keyword)
+- **WHEN** keyword validation is performed
+- **THEN** validation fails with error code "MISSING_SHALL"
+- **AND** the error message indicates the requirement needs RFC 2119 keyword
+
+### Requirement: ScenarioPresence
+
+The system SHALL require at least one scenario for each requirement.
+
+#### Scenario: RequirementWithScenarios
+- **GIVEN** a requirement with two scenarios defined
+- **WHEN** scenario validation is performed
+- **THEN** validation passes
+
+#### Scenario: RequirementWithoutScenarios
+- **GIVEN** a requirement with no scenarios
+- **WHEN** scenario validation is performed
+- **THEN** validation fails with error "MISSING_SCENARIOS"
+
+### Requirement: ChangeWhyValidation
+
+The system SHALL validate that change proposals include a "Why" section between 50-500 characters.
+
+#### Scenario: ValidWhySection
+- **GIVEN** a change with Why section of 150 characters
+- **WHEN** change validation is performed
+- **THEN** validation passes
+
+#### Scenario: WhySectionTooShort
+- **GIVEN** a change with Why section of 30 characters
+- **WHEN** change validation is performed
+- **THEN** validation fails with "WHY_TOO_SHORT" error
+
+### Requirement: DeltaLimitEnforcement
+
+The system SHALL enforce a maximum of 20 deltas per change to maintain focused changes.
+
+#### Scenario: ChangeWithinLimit
+- **GIVEN** a change with 15 delta operations
+- **WHEN** delta count validation is performed
+- **THEN** validation passes
+
+#### Scenario: ChangeExceedsLimit
+- **GIVEN** a change with 25 delta operations
+- **WHEN** delta count validation is performed
+- **THEN** validation fails with "TOO_MANY_DELTAS" error
+
+## Technical Notes
+
+- **Implementation**: `src/core/validation/validator.ts`, `src/core/schemas/`
+- **Pattern**: Zod schemas + custom rule validators
+- **Dependencies**: Zod library for schema validation

package/examples/spec-kit/README.md

@@ -0,0 +1,104 @@
+# spec-gen extension for spec-kit
+
+Adds structural risk analysis and spec drift verification to the
+[spec-kit](https://github.com/github/spec-kit) Spec-Driven Development workflow.
+
+Part of the [spec-gen agentic workflow pattern](../../docs/agentic-workflows/README.md).
+
+## What it does
+
+| Hook | Command | When |
+|---|---|---|
+| `before_implement` | `speckit.spec-gen.orient` | Before `/speckit.implement` — orient + risk gate |
+| `after_implement` | `speckit.spec-gen.drift` | After implementation + green tests — drift check |
+
+## When to use it
+
+**Brownfield** (existing codebase): always useful. `orient` surfaces high-risk functions
+before you touch them; `drift` confirms the implementation stays aligned with specs.
+
+**Greenfield** (new project, no existing code): skip `orient` (nothing to analyse yet).
+`drift` is useful once `spec-gen generate` has been run at least once.
+
+## Installation
+
+```bash
+# In your project directory
+specify extension add spec-gen
+```
+
+Or manually copy this directory into `.specify/extensions/spec-gen/`.
+
+## Prerequisites
+
+1. spec-gen MCP server running and configured in your AI agent
+2. `spec-gen analyze $PROJECT_ROOT` run at least once
+
+## Workflow
+
+```mermaid
+flowchart TD
+    A["/speckit.specify\nspec from requirements"] --> B["/speckit.plan\ntechnical plan"]
+    B --> C["/speckit.tasks\ntask breakdown"]
+    C --> ORIENT
+
+    subgraph SG_PRE ["spec-gen — pre-flight (brownfield)"]
+        ORIENT["speckit.spec-gen.orient\norient + analyze_impact"]
+        ORIENT --> GATE{risk ≥ 70?}
+        GATE -- yes --> BLOCKED["🔴 blocked\nadd refactor task"]
+        GATE -- no --> RISK_CTX["Risk Context\npasted into tasks.md"]
+    end
+
+    RISK_CTX --> D["/speckit.implement\nexecute tasks"]
+    BLOCKED --> C
+
+    D --> TESTS["tests green ✅"]
+    TESTS --> DRIFT
+
+    subgraph SG_POST ["spec-gen — post-flight"]
+        DRIFT["speckit.spec-gen.drift\ncheck_spec_drift"]
+        DRIFT --> E{drift?}
+        E -- stale --> FIX["fix spec reference now"]
+        E -- gap/uncovered --> NOTE["note for post-sprint\nspec-gen generate"]
+        E -- none --> CLEAN["✅ clean"]
+    end
+
+    style BLOCKED fill:#fdd,stroke:#c00
+    style TESTS fill:#d4edda,stroke:#28a745
+```
+
+```
+/speckit.specify       → spec from requirements
+/speckit.plan          → technical plan from spec
+/speckit.tasks         → task breakdown from plan
+
+# spec-gen pre-flight (brownfield only)
+/speckit.spec-gen.orient   → orient + risk gate → paste Risk Context into tasks.md
+
+/speckit.implement     → execute tasks
+
+# spec-gen post-flight (once tests are green)
+/speckit.spec-gen.drift    → drift check → note any spec updates needed
+```
+
+## OpenSpec spec baseline
+
+`speckit.spec-gen.orient` uses `search_specs` to surface relevant requirements, and
+`speckit.spec-gen.drift` uses `check_spec_drift` to verify alignment. Both require
+OpenSpec specs to exist — without them, results are empty or everything shows as uncovered.
+
+| State | What to do |
+|---|---|
+| No specs yet | Run `spec-gen generate $PROJECT_ROOT` once before the first sprint |
+| Specs exist | Both commands work as expected |
+| New code not yet spec'd | `drift` will flag it as `uncovered` — run `spec-gen generate` to update |
+
+Both commands detect missing specs automatically and offer to run `spec-gen generate`.
+
+## Risk gate
+
+| Score | Level | Action |
+|---|---|---|
+| < 40 | 🟢 low | Proceed |
+| 40–69 | 🟡 medium | Proceed — protect listed callers |
+| ≥ 70 | 🔴 high / critical | Stop — refactor first |

package/examples/spec-kit/commands/drift.md

@@ -0,0 +1,87 @@
+---
+description: "Post-implementation spec drift check — verify the implementation matches existing OpenSpec specifications."
+tools:
+  - 'spec-gen/check_spec_drift'
+---
+
+# spec-gen: Drift Check
+
+Run this command **after** `/speckit.implement` and **only once tests are green**.
+
+It compares the implementation against existing OpenSpec specifications and reports
+gaps, stale references, and uncovered files.
+
+> **No specs yet?** If `spec-gen generate` has not been run on this project,
+> this command will report everything as uncovered — that is expected and not a problem.
+>
+> **What to do:** Run `spec-gen generate $PROJECT_ROOT` now to create a spec baseline
+> from the current codebase. Once generated, re-run this command — future drift checks
+> will be meaningful. A baseline only needs to be created once.
+
+## Prerequisites
+
+1. spec-gen MCP server configured in your AI agent settings
+2. Tests passing — do not run drift check on a red test suite
+3. `spec-gen analyze` run at least once (same requirement as orient)
+
+## User Input
+
+$ARGUMENTS
+
+If a project directory is provided, use it. Otherwise use the current working directory.
+
+## Step 1 — Check spec baseline
+
+```bash
+ls $PROJECT_ROOT/openspec/specs/ 2>/dev/null | wc -l
+```
+
+**If 0 specs found:**
+> "No OpenSpec specs exist yet. Running `check_spec_drift` now will flag all files as
+> uncovered, which is not actionable.
+>
+> Run `spec-gen generate $PROJECT_ROOT` first to create a spec baseline, then re-run
+> this command. The generate step takes a few minutes and only needs to be done once."
+>
+> Ask: "Run `spec-gen generate` now? (yes/no)"
+> - Yes → trigger generate, then proceed to Step 2
+> - No → stop here, remind user to run it before next drift check
+
+**If specs exist**: proceed.
+
+## Step 2 — Confirm tests are green
+
+Ask the user: "Are all tests passing?"
+
+If the answer is no: "Run tests first and fix any failures. Drift check is only
+meaningful on a green test suite." Stop here.
+
+## Step 3 — Run drift check
+
+```
+spec-gen check_spec_drift
+  directory: $PROJECT_ROOT
+```
+
+## Step 4 — Interpret results
+
+| Drift type | Meaning | Action |
+|---|---|---|
+| `uncovered` on new files | New code not yet in any spec | Note for post-sprint spec update |
+| `gap` on existing domain | Existing spec missing coverage of new behaviour | Run `spec-gen generate --domains $DOMAIN` |
+| `stale` | Spec references a function that no longer exists | Fix the reference in the spec file |
+| No drift | ✅ Implementation matches specs | Done |
+
+## Step 5 — Output
+
+Report findings in a compact table. For each gap or uncovered item:
+- Which file / domain is affected
+- Recommended action (generate, update, or fix)
+
+If drift is found on domains touched by this implementation:
+> "Spec drift detected. These updates can be applied now with `spec-gen generate`
+> or batched post-sprint. Recommend: note them in `.specify/{feature}/plan.md`
+> under a `## Spec Updates` section rather than interrupting the current sprint."
+
+If no drift:
+> "✅ No spec drift. Implementation is consistent with existing OpenSpec specifications."

package/examples/spec-kit/commands/orient.md

@@ -0,0 +1,138 @@
+---
+description: "Pre-flight structural risk check — orient + analyze_impact before implementation. Gates on riskScore ≥ 70."
+tools:
+  - 'spec-gen/orient'
+  - 'spec-gen/analyze_impact'
+  - 'spec-gen/search_specs'
+---
+
+# spec-gen: Pre-flight Check
+
+Run this command **before** `/speckit.implement` on an existing codebase.
+It identifies the functions affected by the planned tasks, scores their blast radius,
+and surfaces any spec requirements that apply — so you don't discover high-risk
+areas mid-implementation.
+
+> **Greenfield projects** (no existing codebase): skip this command.
+> It is only useful when implementing against an existing codebase.
+
+## Prerequisites
+
+1. spec-gen MCP server configured in your AI agent settings
+2. `spec-gen analyze` run at least once on the project directory
+   (produces the `.spec-gen/` cache used by orient)
+
+## User Input
+
+$ARGUMENTS
+
+If a project directory is provided, use it. Otherwise use the current working directory.
+
+## Step 1 — Read tasks.md
+
+Read `.specify/{feature}/tasks.md` to extract the list of planned tasks.
+Summarise the implementation intent in one sentence — this is the `$TASK_DESCRIPTION`
+passed to orient.
+
+If tasks.md does not exist, ask the user for a brief description of what they are about
+to implement.
+
+## Step 2 — Orient
+
+```
+spec-gen orient
+  directory: $PROJECT_ROOT
+  task: $TASK_DESCRIPTION
+  limit: 7
+```
+
+If orient returns `"error": "no cache"`:
+> "spec-gen has no analysis cache for this project. Run `spec-gen analyze $PROJECT_ROOT`
+> first (takes ~1 min), then re-run `/speckit.spec-gen.orient`."
+> Stop here.
+
+## Step 3 — Check spec baseline
+
+Check whether OpenSpec specifications exist for this project:
+
+```bash
+ls $PROJECT_ROOT/openspec/specs/ 2>/dev/null | head -5
+```
+
+**If no specs exist** (`openspec/specs/` is absent or empty):
+> "No OpenSpec specs found. `search_specs` and `check_spec_drift` will return empty
+> results until specs are generated.
+>
+> Recommended: run `spec-gen generate $PROJECT_ROOT` after this sprint to create a
+> spec baseline from the existing code. You only need to do this once — subsequent
+> sprints will have specs to align against.
+>
+> Continuing with structural analysis only (orient + impact)."
+
+**If specs exist**: proceed to search_specs below.
+
+## Step 4 — Check existing requirements
+
+```
+spec-gen search_specs
+  directory: $PROJECT_ROOT
+  query: $TASK_DESCRIPTION
+  limit: 5
+```
+
+If relevant requirements are found, list them. Note any constraints that apply to the
+planned implementation.
+
+If `search_specs` returns no results despite specs existing, note it — the planned
+change may be in an area not yet covered by specs.
+
+## Step 5 — Impact analysis
+
+For each of the top 2 functions returned by orient:
+
+```
+spec-gen analyze_impact
+  directory: $PROJECT_ROOT
+  symbol: $FUNCTION_NAME
+  depth: 2
+```
+
+Build a risk summary table:
+
+| Function | File | Risk Score | Level | Callers |
+|----------|------|-----------|-------|---------|
+
+## Step 6 — Decision gate
+
+| Max risk score | Action |
+|---|---|
+| < 40 | 🟢 Proceed — risk is low. Show insertion points from orient. |
+| 40–69 | 🟡 Proceed with caution — protect the callers listed above. |
+| ≥ 70 | 🔴 **Stop.** Do not implement until the high-risk function is refactored. |
+
+**If any function has riskScore ≥ 70:**
+
+> "⚠️ High structural risk detected on `$FUNCTION_NAME` (score: $SCORE).
+> Implementing against this function risks breaking $CALLER_COUNT callers.
+>
+> Recommended: add a refactor task to tasks.md for `$FUNCTION_NAME` and schedule
+> it before the tasks that touch it. Then re-run `/speckit.spec-gen.orient`."
+>
+> Stop and wait for user confirmation before proceeding.
+
+## Step 7 — Summary
+
+Output a compact block to paste into tasks.md or plan.md as a `## Risk Context` note:
+
+```
+## Risk Context (spec-gen)
+- Domains: {domains}
+- Max risk: {score} {badge}
+- Functions in scope: {fn1} ({file1}), {fn2} ({file2})
+- Callers to protect: {callers}
+- Blocking refactors: {none | list}
+- Insertion point: {top insertion point}
+```
+
+Ask the user: "Paste this into your tasks.md? (yes/no)"
+If yes, append it before the first task phase.

package/examples/spec-kit/extension.yml

@@ -0,0 +1,54 @@
+schema_version: "1.0"
+
+extension:
+  id: "spec-gen"
+  name: "spec-gen structural analysis"
+  version: "1.0.0"
+  description: "Pre-flight structural risk check and post-implementation spec drift verification via spec-gen MCP."
+  author: "spec-gen contributors"
+  repository: "https://github.com/clay-good/spec-gen"
+  license: "MIT"
+  homepage: "https://github.com/clay-good/spec-gen"
+
+requires:
+  speckit_version: ">=0.1.0"
+  tools:
+    - name: "spec-gen"
+      version: ">=1.2.0"
+      required: true
+
+provides:
+  commands:
+    - name: "speckit.spec-gen.orient"
+      file: "commands/orient.md"
+      description: "Pre-flight check — orient + analyze_impact before implementation. Gates on riskScore ≥ 70."
+
+    - name: "speckit.spec-gen.drift"
+      file: "commands/drift.md"
+      description: "Post-implementation spec drift check. Run after tests are green."
+
+hooks:
+  before_implement:
+    command: "speckit.spec-gen.orient"
+    optional: true
+    prompt: "Run spec-gen structural risk check before implementing?"
+    description: "Identifies high-risk functions and spec requirements relevant to the planned tasks."
+
+  after_implement:
+    command: "speckit.spec-gen.drift"
+    optional: true
+    prompt: "Run spec-gen drift check to verify implementation matches specs?"
+    description: "Detects gaps between the implementation and existing OpenSpec specifications."
+
+tags:
+  - "static-analysis"
+  - "risk-management"
+  - "spec-driven"
+  - "brownfield"
+  - "mcp"
+
+defaults:
+  analysis:
+    orient_limit: 7
+    impact_depth: 2
+    risk_threshold: 70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-gen-cli",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "description": "Reverse-engineer OpenSpec specifications from existing codebases",
   "type": "module",
   "main": "dist/api/index.js",
@@ -64,6 +64,7 @@
     "dist",
     "!dist/**/*.test.*",
     "src/viewer",
+    "examples",
     "README.md",
     "LICENSE"
   ],
@@ -102,8 +103,7 @@
     "yaml": "^2.6.1"
   },
   "optionalDependencies": {
-    "@lancedb/lancedb-darwin-x64": "^0.26.2",
-    "@lancedb/lancedb-linux-x64-gnu": "^0.26.2"
+    "tree-sitter-cli": "^0.23"
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
@@ -116,8 +116,5 @@
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.19.1",
     "vitest": "^4.0.18"
-  },
-  "optionalDependencies": {
-    "tree-sitter-cli": "^0.23"
   }
 }