Skip to content

validate --json: emit the validateSpace result shape, not a second derived one #198

Closed

Description

@mindsocket

Problem

sctx validate <space> --json and validateSpace() describe the same run in two shapes.

validate --json (src/commands/validate.ts) builds a derived summary: errors is keyed by file name, hierarchy violations are folded into it as message strings, rule violations appear in it only at error severity, and node-level schema issues are not included as structured data. validateSpace() returns ValidationResult: nodeErrors, hierarchyViolations and ruleViolations carry a nodeId, plus issues, severity and source.

A consumer that only has the CLI cannot get node-level results. Example: a standalone page that overlays validation on a rendered map of the space needs results by nodeId (the shape structured-context-map-views' annotationsFrom takes). It had to call the library API instead of reading CLI output. Agents and scripts that shell out hit the same wall.

measured: validate demo --json on a fixture space returns the keys space, valid, validCount, errorCount, errors, ruleViolations, orphanCount, parseIssues, …, with no nodeErrors or hierarchyViolations. validateSpace() on the same space returns both (3 hierarchy violations).

Proposal

One shape. --json serialises the ValidationResult (nodes referenced by nodeId) plus the summary fields it adds today (space, valid, errorCount). Drop the file-keyed errors map. Pre-1.0, so a clean break: update consumers (the plugin hooks' plugin/scripts/state.ts, bun run test:hook) rather than keep both.

Alternatives

  • Keep the summary and add --json --full for the raw result: two shapes to document and keep in sync, which is the problem here.
  • Leave it and tell consumers to use the API: rules out the CLI-only and agent cases.

Checks if done

docs/* for the command, plugin/skills/structured-context/references/commands.md, plugin/scripts/state.ts, hook tests.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions