242 lines
6.0 KiB
YAML
242 lines
6.0 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Renamer Sequence Command Contract
|
|
version: 0.1.0
|
|
description: >
|
|
Conceptual REST contract for the `renamer sequence` CLI behavior, used to
|
|
formalize preview/apply expectations for testing and documentation.
|
|
servers:
|
|
- url: cli://local
|
|
paths:
|
|
/sequence/preview:
|
|
post:
|
|
summary: Generate a deterministic sequence numbering preview.
|
|
operationId: previewSequence
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SequenceRequest'
|
|
responses:
|
|
'200':
|
|
description: Preview generated successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SequencePlan'
|
|
'400':
|
|
description: Invalid configuration (e.g., width <= 0, invalid separator).
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
/sequence/apply:
|
|
post:
|
|
summary: Apply sequence numbering to previously previewed candidates.
|
|
operationId: applySequence
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/SequenceRequest'
|
|
- type: object
|
|
properties:
|
|
confirm:
|
|
type: boolean
|
|
const: true
|
|
responses:
|
|
'200':
|
|
description: Sequence numbering applied.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SequenceApplyResult'
|
|
'207':
|
|
description: Applied with skipped conflicts.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SequenceApplyResult'
|
|
'400':
|
|
description: Invalid configuration or missing confirmation.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'409':
|
|
description: Scope filters yielded zero candidates.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
components:
|
|
schemas:
|
|
SequenceRequest:
|
|
type: object
|
|
required:
|
|
- start
|
|
- placement
|
|
- separator
|
|
properties:
|
|
path:
|
|
type: string
|
|
description: Root directory for traversal.
|
|
recursive:
|
|
type: boolean
|
|
includeDirs:
|
|
type: boolean
|
|
description: Directories remain untouched even when included.
|
|
hidden:
|
|
type: boolean
|
|
extensions:
|
|
type: array
|
|
items:
|
|
type: string
|
|
pattern: '^\\.[^./]+$'
|
|
dryRun:
|
|
type: boolean
|
|
yes:
|
|
type: boolean
|
|
start:
|
|
type: integer
|
|
minimum: 1
|
|
width:
|
|
type: integer
|
|
minimum: 1
|
|
placement:
|
|
type: string
|
|
enum: [prefix, suffix]
|
|
separator:
|
|
type: string
|
|
minLength: 1
|
|
pattern: '^[^/\\\\]+$'
|
|
SequencePlan:
|
|
type: object
|
|
required:
|
|
- candidates
|
|
- config
|
|
- summary
|
|
properties:
|
|
candidates:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SequenceCandidate'
|
|
skippedConflicts:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SequenceConflict'
|
|
summary:
|
|
$ref: '#/components/schemas/SequenceSummary'
|
|
config:
|
|
$ref: '#/components/schemas/SequenceConfig'
|
|
SequenceCandidate:
|
|
type: object
|
|
required:
|
|
- originalPath
|
|
- proposedPath
|
|
- index
|
|
properties:
|
|
originalPath:
|
|
type: string
|
|
proposedPath:
|
|
type: string
|
|
index:
|
|
type: integer
|
|
minimum: 0
|
|
SequenceConflict:
|
|
type: object
|
|
required:
|
|
- originalPath
|
|
- conflictingPath
|
|
- reason
|
|
properties:
|
|
originalPath:
|
|
type: string
|
|
conflictingPath:
|
|
type: string
|
|
reason:
|
|
type: string
|
|
enum: [existing_target, invalid_separator, width_overflow]
|
|
SequenceSummary:
|
|
type: object
|
|
required:
|
|
- totalCandidates
|
|
- renamedCount
|
|
- skippedCount
|
|
properties:
|
|
totalCandidates:
|
|
type: integer
|
|
renamedCount:
|
|
type: integer
|
|
skippedCount:
|
|
type: integer
|
|
warnings:
|
|
type: array
|
|
items:
|
|
type: string
|
|
SequenceConfig:
|
|
type: object
|
|
required:
|
|
- start
|
|
- placement
|
|
- separator
|
|
properties:
|
|
start:
|
|
type: integer
|
|
width:
|
|
type: integer
|
|
placement:
|
|
type: string
|
|
enum: [prefix, suffix]
|
|
separator:
|
|
type: string
|
|
SequenceApplyResult:
|
|
type: object
|
|
required:
|
|
- plan
|
|
- ledgerEntry
|
|
properties:
|
|
plan:
|
|
$ref: '#/components/schemas/SequencePlan'
|
|
ledgerEntry:
|
|
$ref: '#/components/schemas/SequenceLedgerEntry'
|
|
SequenceLedgerEntry:
|
|
type: object
|
|
required:
|
|
- rule
|
|
- config
|
|
- operations
|
|
properties:
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
rule:
|
|
type: string
|
|
const: sequence
|
|
config:
|
|
$ref: '#/components/schemas/SequenceConfig'
|
|
operations:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SequenceOperation'
|
|
SequenceOperation:
|
|
type: object
|
|
required:
|
|
- from
|
|
- to
|
|
properties:
|
|
from:
|
|
type: string
|
|
to:
|
|
type: string
|
|
ErrorResponse:
|
|
type: object
|
|
required:
|
|
- message
|
|
properties:
|
|
message:
|
|
type: string
|