skills/fission-ai__openspec
1
0
Fork 0
mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-09-14 20:16:53 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
codex/warp-skills-320
fission-ai__openspec/openspec/changes/spec-diffs/specs/cli-show/spec.md
T
bsmedberg-xometry dd7cea3ffe feat(show): diff delta requirements against the main specs (#980) 
* Proposed feature: openspec show --diff to see changed requirements more clearly

* Implementation of the --diff feature, which led to some spec changes during implementation.

* Update the proposal to be clearer. Thanks coderabbit

* Fix a bug identified by coderabbit with excessive trimming, and add a testcase for it.

* fix(show): harden --diff for review feedback

Keeps `openspec show <change>` without `--diff` a raw proposal
passthrough, reports when a change has no delta specs instead of
returning silently, preserves the Reason/Migration body of a REMOVED
requirement, and resolves main specs through the command's root so
`--store <id>` diffs against that store.

Text mode and JSON mode now render from one shared collection pass, the
CLI tests drive argv arrays from a mkdtemp project instead of
interpolated shell strings, `--diff` is registered for shell
completions, and the stray package-lock.json is gone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* build(deps): declare the diff dependency and refresh the flake hash

Adds the `diff` runtime dependency that requirement-diff.ts imports,
updates pnpm-lock.yaml, and regenerates the flake's pnpmDeps hash so
`nix build` matches the new lockfile.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(show): diff nested capabilities too

collectSpecDiffs enumerated only top-level directories under the
change's specs/, so a nested capability (specs/<area>/<id>/spec.md) was
skipped: text mode printed nothing for it and its MODIFIED deltas came
back from --json with no diff. It now uses the same discoverSpecFiles()
helper ChangeParser uses, so the capability ids match the `spec` field
of the JSON deltas.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(show): report header mismatches instead of hiding them

Two cases where --diff quietly showed something misleading:

A MODIFIED requirement whose capability has no main spec was rendered as
all-additions, which reads like a new capability. It is an authoring
error archive will reject, so it now prints the raw text with a warning
naming the missing spec.

A header that differs from the main spec only in case or interior
spacing found no match at all under exact lookup, or matched under a
lowercase-only comparison that let a real mismatch through silently.
Lookup is now exact first, then the shared foldRequirementName fallback,
and a folded match prints the diff the author meant alongside a warning
that archive matches names exactly.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* refactor(show): name the main spec as such in collectSpecDiffs

Comment and locals still called the main spec the "base" spec, and the
no-main-spec comment described the old all-additions behavior.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* chore(deps-dev): bump the development-dependencies group with 2 updates

Bumps the development-dependencies group with 2 updates: [smol-toml](https://github.com/squirrelchat/smol-toml) and [typescript-eslint](https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/typescript-eslint).


Updates `smol-toml` from 1.7.1 to 1.8.0
- [Release notes](https://github.com/squirrelchat/smol-toml/releases)
- [Commits](https://github.com/squirrelchat/smol-toml/compare/v1.7.1...v1.8.0)

Updates `typescript-eslint` from 8.66.0 to 8.67.0
- [Release notes](https://github.com/typescript-eslint/typescript-eslint/releases)
- [Changelog](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/typescript-eslint/CHANGELOG.md)
- [Commits](https://github.com/typescript-eslint/typescript-eslint/commits/v8.67.0/packages/typescript-eslint)

---
updated-dependencies:
- dependency-name: smol-toml
  dependency-version: 1.8.0
  dependency-type: direct:development
  update-type: version-update:semver-minor
  dependency-group: development-dependencies
- dependency-name: typescript-eslint
  dependency-version: 8.67.0
  dependency-type: direct:development
  update-type: version-update:semver-minor
  dependency-group: development-dependencies
...

Signed-off-by: dependabot[bot] <support@github.com>

* chore(nix): invalidate pnpm dependency hash

* fix(nix): update pnpm dependency hash

* fix(show): harden requirement diff output

* build(nix): pin combined dependency hash

* test(show): assert proposal precedes diffs

* docs(show): clarify JSON diff diagnostics

* fix(show): retain unified diff hunk headers

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Clay Good <hi@claygood.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
2026-08-26 20:18:03 +00:00

6.5 KiB
Raw Permalink Blame History

MODIFIED Requirements

Requirement: Output format options

The show command SHALL support various output formats consistent with existing commands.

Scenario: JSON output

  • WHEN executing openspec show <item> --json
  • THEN output the item in JSON format
  • AND include parsed metadata and structure
  • AND maintain format consistency with existing change/spec show commands

Scenario: Flag scoping and delegation

  • WHEN showing a change or a spec via the top-level command
  • THEN accept common flags such as --json
  • AND pass through type-specific flags to the corresponding implementation
    • Change-only flags: --deltas-only (alias --requirements-only deprecated), --diff
    • Spec-only flags: --requirements, --no-scenarios, -r/--requirement
  • AND ignore irrelevant flags for the detected type with a warning

Scenario: Text mode change display is unchanged without --diff

  • WHEN executing openspec show <change-name> in text mode without --diff
  • THEN print the proposal markdown and nothing else, exactly as before --diff existed

Scenario: Diff output in text mode

  • WHEN executing openspec show <change-name> --diff in text mode (no --json)
  • THEN display the proposal markdown text
  • AND for each delta spec file under openspec/changes/<change-name>/specs/<cap>/spec.md, display the parsed deltas grouped by capability
  • AND for ADDED requirements, display the full requirement text with a green "ADDED" label
  • AND for REMOVED requirements, display the authored removal block, including its Reason and Migration text, with a red "REMOVED" label
  • AND for RENAMED requirements, display the FROM:/TO: with a cyan "RENAMED" label
  • AND for MODIFIED requirements, extract the matching requirement block from the main spec at openspec/specs/<cap>/spec.md by ### Requirement: header name, compute a unified diff of the main block vs the delta block, and display it colorized (green for + lines, red for - lines, plain for context lines)
  • AND when a MODIFIED requirement's name matches a RENAMED entry's TO name in the same spec, the system SHALL look up the main block using the RENAMED entry's FROM name instead
  • AND when multiple RENAMED entries form a chain, the system SHALL resolve the MODIFIED name back to the original main requirement
  • AND when a MODIFIED requirement's header matches a main requirement only after folding case and interior whitespace, display the diff together with a warning that archive matches names exactly
  • AND if a MODIFIED requirement has no matching main requirement (and no corresponding RENAMED entry), display the full text with a warning
  • AND if the capability has no main spec at all, display the full text with a warning naming the missing spec, rather than rendering the requirement as an addition
  • AND if the MODIFIED block is textually identical to the matching main block, display (no textual changes)

Scenario: Diff output in JSON mode

  • WHEN executing openspec show <change-name> --json --diff
  • THEN the output SHALL use the same JSON structure as --json alone ({ id, title, deltaCount, deltas })
  • AND for each MODIFIED delta, the delta object SHALL include an additional diff string field containing the unified diff of the main requirement block vs the delta requirement block
  • AND when a MODIFIED requirement corresponds to a RENAMED entry, the main block SHALL be looked up using the RENAMED FROM name
  • AND ADDED, REMOVED, and RENAMED deltas SHALL NOT have a diff field
  • AND if a MODIFIED requirement has no matching main requirement, or its capability has no main spec, the delta object SHALL include a warning string field instead of diff
  • AND if a MODIFIED requirement matched only after folding case and interior whitespace, the delta object SHALL include both diff and warning
  • AND a textually identical MODIFIED block SHALL include diff as an empty string

Scenario: Diff input cannot be read

  • WHEN delta discovery fails, a delta spec cannot be read, or a main spec exists but cannot be read
  • THEN the command SHALL exit with an error
  • AND the command SHALL NOT present the result as an empty delta set, a missing main spec, or a partial diff

Scenario: Diff with no delta specs

  • WHEN executing openspec show <change-name> --diff and the change has no delta spec files
  • THEN print a message reporting that the change has no delta specs to diff
  • AND exit with code 0

Scenario: Diff flag on non-change item

  • WHEN executing openspec show <spec-name> --diff
  • THEN ignore the --diff flag with a warning (flag is not applicable to specs)

ADDED Requirements

Requirement: Requirement block extraction for diffing

The system SHALL extract raw markdown text for individual requirement blocks from spec files to support per-requirement diffing.

Scenario: Extract requirement block by name

  • WHEN a requirement name is provided and a spec file contains a matching ### Requirement: <name> header
  • THEN the system SHALL return the raw markdown text from the ### Requirement: header line through all content until the next ### header at the same or higher level (or end of file)

Scenario: Requirement name matching

  • WHEN a requirement name matches a ### Requirement: header exactly (after trimming)
  • THEN the system SHALL return that block and report the match as exact
  • AND when only a case- or interior-whitespace-folded match exists, the system SHALL return that block, report the match as inexact, and report the name as the main spec spells it
  • AND an exact match SHALL take precedence over a folded one

Scenario: Requirement name not found in the main spec

  • WHEN a MODIFIED delta requirement name does not match any ### Requirement: header in the main spec, exactly or folded
  • THEN the system SHALL return null for the main block
  • AND the caller SHALL display the full MODIFIED requirement text with a warning that no main requirement was found

Scenario: Main spec paths resolve against the selected root

  • WHEN resolving the main spec path for a given capability
  • THEN the system SHALL build openspec/specs/<cap>/spec.md under the same OpenSpec root the change was read from, so --store <id> diffs against that store's main specs rather than the working directory
  • AND the system SHALL use path.join() for filesystem operations
  • AND display paths SHALL use forward slashes regardless of platform
Reference in New Issue View Git Blame Copy Permalink