docspec 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.docspec.md +180 -0
- package/README.md +127 -31
- package/dist/__tests__/cli.test.js +27 -39
- package/dist/__tests__/cli.test.js.map +1 -1
- package/dist/__tests__/constants.test.js +8 -18
- package/dist/__tests__/constants.test.js.map +1 -1
- package/dist/__tests__/generator.test.js +16 -16
- package/dist/__tests__/generator.test.js.map +1 -1
- package/dist/__tests__/validator.test.js +50 -94
- package/dist/__tests__/validator.test.js.map +1 -1
- package/dist/cli.js +3 -4
- package/dist/cli.js.map +1 -1
- package/dist/constants.d.ts +3 -2
- package/dist/constants.d.ts.map +1 -1
- package/dist/constants.js +52 -40
- package/dist/constants.js.map +1 -1
- package/dist/format-parser.d.ts +23 -0
- package/dist/format-parser.d.ts.map +1 -0
- package/dist/format-parser.js +175 -0
- package/dist/format-parser.js.map +1 -0
- package/dist/generator.d.ts +4 -5
- package/dist/generator.d.ts.map +1 -1
- package/dist/generator.js +9 -20
- package/dist/generator.js.map +1 -1
- package/dist/validator.js +5 -0
- package/dist/validator.js.map +1 -1
- package/docspec-format.md +45 -0
- package/package.json +4 -3
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# DOCSPEC: [README.md](/README.md)
|
|
2
|
+
|
|
3
|
+
> A specification that defines how the target document should be maintained by agents.
|
|
4
|
+
|
|
5
|
+
## AGENT INSTRUCTIONS
|
|
6
|
+
|
|
7
|
+
**Target document:** `README.md`
|
|
8
|
+
|
|
9
|
+
**Your task:**
|
|
10
|
+
|
|
11
|
+
* Compare the target document against this docspec.
|
|
12
|
+
* Update the target document to satisfy this docspec.
|
|
13
|
+
* Make the smallest changes necessary.
|
|
14
|
+
* Preserve existing content that already complies.
|
|
15
|
+
* Do not invent content, sections, or facts not implied by this docspec or the repository.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
## 1. Document Purpose
|
|
20
|
+
|
|
21
|
+
This README serves as the primary entry point and comprehensive documentation for the docspec project. It is a technical project overview that must answer:
|
|
22
|
+
|
|
23
|
+
- **What is docspec?** - A specification format and toolchain for agent-maintained documentation
|
|
24
|
+
- **How do I install it?** - npm installation methods (local and global)
|
|
25
|
+
- **How do I use it?** - CLI commands (`validate`, `generate`) and TypeScript API usage
|
|
26
|
+
- **How do I integrate it?** - Pre-commit hooks, GitHub Actions (post-merge sync, manual audit)
|
|
27
|
+
- **What is the docspec format?** - High-level overview and reference to docspec-format.md
|
|
28
|
+
- **How do I develop with it?** - Test and build commands
|
|
29
|
+
|
|
30
|
+
**Target audiences:**
|
|
31
|
+
- End-users using the CLI for validation and generation
|
|
32
|
+
- Library consumers using the TypeScript API in their projects
|
|
33
|
+
- GitHub Actions users integrating automated documentation workflows
|
|
34
|
+
- CI/CD integrators adding docspec validation to their pipelines
|
|
35
|
+
- Contributors developing and testing the project
|
|
36
|
+
|
|
37
|
+
**Document type:** Technical project documentation (README/overview)
|
|
38
|
+
|
|
39
|
+
## 2. Update Triggers
|
|
40
|
+
|
|
41
|
+
**Changes that SHOULD trigger updates:**
|
|
42
|
+
|
|
43
|
+
- **CLI changes** (src/cli.ts): New commands, modified command arguments, changed command behavior
|
|
44
|
+
- **Validation logic** (src/validator.ts): New validation rules, changed error messages, modified validation behavior
|
|
45
|
+
- **Docspec format definition** (docspec-format.md): Changes to required sections, section names, validation rules
|
|
46
|
+
- **GitHub Action configuration** (action.yml): New inputs/outputs, changed defaults, modified descriptions
|
|
47
|
+
- **Workflow files** (.github/workflows/docspec-check.yml, docspec-generate.yml): Workflow name changes, trigger changes, new steps or configuration
|
|
48
|
+
- **Installation method** (package.json): Package name changes, new installation requirements
|
|
49
|
+
- **File naming convention**: Changes to how .docspec.md maps to .md files
|
|
50
|
+
- **Required sections** (src/constants.ts): Changes to REQUIRED_SECTIONS array or section definitions
|
|
51
|
+
- **Pre-commit hook configuration** (.pre-commit-config.yaml): Changes to hook setup or usage
|
|
52
|
+
- **Library API exports** (src/index.ts): New exported functions, types, or constants; removed exports; changed function signatures
|
|
53
|
+
|
|
54
|
+
**Changes that SHOULD NOT trigger updates:**
|
|
55
|
+
|
|
56
|
+
- Internal implementation details that don't affect public APIs (validator internals, generator internals, format-parser internals)
|
|
57
|
+
- Test file changes (src/__tests__/*) unless they reveal new documented behavior
|
|
58
|
+
- Build system changes (tsconfig.json, package build scripts) that don't affect installation or usage
|
|
59
|
+
- Python script implementation details (docspec_update.py, improve_docspec.py) - these are internal to GitHub Actions
|
|
60
|
+
- Dependency version updates that don't change user-facing functionality
|
|
61
|
+
- Code refactoring that preserves the same external behavior
|
|
62
|
+
|
|
63
|
+
## 3. Expected Structure
|
|
64
|
+
|
|
65
|
+
The README must contain these sections in order:
|
|
66
|
+
|
|
67
|
+
1. **Title and Description**: Package name (`# docspec`) and one-sentence description of what docspec is
|
|
68
|
+
|
|
69
|
+
2. **The Docspec Format**: High-level overview of the format
|
|
70
|
+
- Link to docspec-format.md as the definitive format specification
|
|
71
|
+
- List the 5 required sections by name
|
|
72
|
+
- Explain validation requirements (non-boilerplate content, 50-character minimum)
|
|
73
|
+
- Constraint: Do NOT duplicate the full format specification; link to docspec-format.md instead
|
|
74
|
+
|
|
75
|
+
3. **Installation**: npm installation instructions
|
|
76
|
+
- Local installation (`npm install docspec`)
|
|
77
|
+
- Global installation (`npm install -g docspec`)
|
|
78
|
+
- Constraint: Keep concise, no version-specific details
|
|
79
|
+
|
|
80
|
+
4. **Usage**: How to use docspec with subsections:
|
|
81
|
+
- **CLI Commands**: Document `validate` and `generate` commands with examples matching src/cli.ts exactly
|
|
82
|
+
- **Library Usage**: TypeScript import examples showing exported functions and types from src/index.ts
|
|
83
|
+
- Constraint: Code examples must be actual working commands from the codebase
|
|
84
|
+
|
|
85
|
+
5. **Pre-commit Integration**: How to use with pre-commit hooks
|
|
86
|
+
- Reference .pre-commit-config.yaml
|
|
87
|
+
- Installation command (`pre-commit install`)
|
|
88
|
+
- Brief explanation of how validation works
|
|
89
|
+
- Constraint: High-level only, link to actual config file
|
|
90
|
+
|
|
91
|
+
6. **GitHub Action Integration**: How to use the GitHub Actions
|
|
92
|
+
- Overview of the two workflows (post-merge sync, manual audit)
|
|
93
|
+
- **Post-Merge Documentation Updates** subsection:
|
|
94
|
+
- Setup instructions (add workflow, configure secrets)
|
|
95
|
+
- How it works (discovery strategy, Claude Code CLI invocation, PR creation)
|
|
96
|
+
- File naming convention (filename.docspec.md → filename.md)
|
|
97
|
+
- Configuration options (reference action.yml inputs)
|
|
98
|
+
- Safety features (list specific guardrails)
|
|
99
|
+
- **Manual Docspec Audit** subsection:
|
|
100
|
+
- What it's for (audit, discover gaps, regenerate)
|
|
101
|
+
- How it works (two-phase approach: discovery and implementation)
|
|
102
|
+
- Usage instructions (how to trigger workflow)
|
|
103
|
+
- Constraint: Link to actual workflow files instead of duplicating YAML; configuration options must match action.yml exactly
|
|
104
|
+
|
|
105
|
+
7. **Development**: Commands for contributors
|
|
106
|
+
- Running tests (`npm test`, `npm run test:watch`)
|
|
107
|
+
- Building (`npm run build`)
|
|
108
|
+
- Constraint: Keep minimal, only essential commands
|
|
109
|
+
|
|
110
|
+
8. **License**: License type (MIT)
|
|
111
|
+
|
|
112
|
+
## 4. Editing Guidelines
|
|
113
|
+
|
|
114
|
+
**Tone and audience:**
|
|
115
|
+
- Use technical but accessible language
|
|
116
|
+
- Target developers familiar with Node.js/npm, GitHub Actions, and CI/CD concepts
|
|
117
|
+
- Be concise and direct; avoid marketing language
|
|
118
|
+
|
|
119
|
+
**Code examples and accuracy:**
|
|
120
|
+
- CLI command documentation must match src/cli.ts exactly
|
|
121
|
+
- Library API examples must only show functions/types exported from src/index.ts
|
|
122
|
+
- Action inputs/outputs must match action.yml exactly
|
|
123
|
+
- File paths in examples must use the actual naming convention (.docspec.md → .md)
|
|
124
|
+
- Workflow references should use actual file names (.github/workflows/docspec-check.yml, docspec-generate.yml)
|
|
125
|
+
|
|
126
|
+
**Level of detail:**
|
|
127
|
+
- Keep workflow configuration sections high-level; link to actual YAML files instead of duplicating content
|
|
128
|
+
- Reference the 5 required sections by name when describing validation
|
|
129
|
+
- Link to docspec-format.md for the full format specification; don't duplicate it in the README
|
|
130
|
+
- Safety features should list specific guardrails without implementation details
|
|
131
|
+
- Pre-commit integration should be high-level; link to .pre-commit-config.yaml
|
|
132
|
+
|
|
133
|
+
**DO:**
|
|
134
|
+
- Use actual command examples that work: `docspec validate`, `docspec generate path/to/README.docspec.md`
|
|
135
|
+
- Reference source files when describing behavior: "matches src/cli.ts", "exported from src/index.ts"
|
|
136
|
+
- Link to definitive sources: action.yml for configuration options, docspec-format.md for format details
|
|
137
|
+
- Mention that docspec-format.md is included in the published package
|
|
138
|
+
- Note that validation handles permission errors gracefully
|
|
139
|
+
|
|
140
|
+
**DON'T:**
|
|
141
|
+
- Invent CLI flags or options that don't exist in src/cli.ts
|
|
142
|
+
- Document internal APIs not exported from src/index.ts
|
|
143
|
+
- Include version-specific information (except referencing package.json)
|
|
144
|
+
- Repeat YAML workflow content verbatim; link to files instead
|
|
145
|
+
- Duplicate the docspec format specification from docspec-format.md
|
|
146
|
+
- Add exhaustive lists of every possible feature or edge case
|
|
147
|
+
|
|
148
|
+
## 5. Intentional Omissions
|
|
149
|
+
|
|
150
|
+
This README deliberately excludes:
|
|
151
|
+
|
|
152
|
+
**Internal implementation details:**
|
|
153
|
+
- TypeScript implementation internals (src/validator.ts, src/generator.ts, src/format-parser.ts, src/constants.ts)
|
|
154
|
+
- Validation algorithm implementation details
|
|
155
|
+
- Template rendering and substitution logic
|
|
156
|
+
- How the format file is parsed and cached
|
|
157
|
+
|
|
158
|
+
**GitHub Action internals:**
|
|
159
|
+
- Python script implementation (docspec_update.py, improve_docspec.py) - these are internal automation scripts
|
|
160
|
+
- Claude Code CLI prompt templates (.github/actions/*/templates/*.md)
|
|
161
|
+
- Action step-by-step implementation details
|
|
162
|
+
- How unified diff patches are generated and applied
|
|
163
|
+
|
|
164
|
+
**Development and build details:**
|
|
165
|
+
- Test implementation and test file structure (src/__tests__/)
|
|
166
|
+
- Build configuration (tsconfig.json, build scripts)
|
|
167
|
+
- Package.json configuration details beyond installation
|
|
168
|
+
- Pre-commit hook internal implementation
|
|
169
|
+
|
|
170
|
+
**Docspec format specification:**
|
|
171
|
+
- The detailed format specification lives in docspec-format.md
|
|
172
|
+
- Section definitions, boilerplate text, validation rules are defined there
|
|
173
|
+
- The README provides only a high-level overview and links to the format file
|
|
174
|
+
|
|
175
|
+
**Where to find this information:**
|
|
176
|
+
- Format specification: docspec-format.md
|
|
177
|
+
- API implementation: src/ directory TypeScript files
|
|
178
|
+
- GitHub Action implementation: .github/actions/ directory
|
|
179
|
+
- Tests: src/__tests__/ directory
|
|
180
|
+
- Build configuration: tsconfig.json, package.json
|
package/README.md
CHANGED
|
@@ -1,6 +1,22 @@
|
|
|
1
1
|
# docspec
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Docspec is a specification format and toolchain for documentation that is maintained by agents.
|
|
4
|
+
|
|
5
|
+
## The Docspec Format
|
|
6
|
+
|
|
7
|
+
Each `*.docspec.md` file is a specification for another document. The format is defined in [`docspec-format.md`](docspec-format.md), which serves as both the format definition and a reference example.
|
|
8
|
+
|
|
9
|
+
The format includes 5 required sections:
|
|
10
|
+
1. **Document Purpose** - What this document exists to explain or enable
|
|
11
|
+
2. **Update Triggers** - What kinds of changes should cause this document to be updated
|
|
12
|
+
3. **Expected Structure** - The sections this document should contain
|
|
13
|
+
4. **Editing Guidelines** - How edits to this document should be made
|
|
14
|
+
5. **Intentional Omissions** - What this document deliberately does not cover
|
|
15
|
+
|
|
16
|
+
Each section must be customized. The validator ensures each section contains non-boilerplate content by checking that:
|
|
17
|
+
- Each section differs from the template boilerplate text
|
|
18
|
+
- Content is not just whitespace differences from boilerplate
|
|
19
|
+
- Each section has at least 50 characters of meaningful content
|
|
4
20
|
|
|
5
21
|
## Installation
|
|
6
22
|
|
|
@@ -32,48 +48,44 @@ Or validate all `*.docspec.md` files in the current directory tree:
|
|
|
32
48
|
docspec validate
|
|
33
49
|
```
|
|
34
50
|
|
|
51
|
+
The validator will recursively find all docspec files, skipping `node_modules`, `.git`, and `dist` directories. Permission errors are handled gracefully and will not cause validation to fail.
|
|
52
|
+
|
|
35
53
|
#### Generate a new docspec file
|
|
36
54
|
|
|
37
55
|
```bash
|
|
38
|
-
docspec generate path/to/
|
|
56
|
+
docspec generate path/to/README.docspec.md
|
|
39
57
|
```
|
|
40
58
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
```bash
|
|
44
|
-
docspec generate path/to/new-file.docspec.md --name "My Document"
|
|
45
|
-
```
|
|
59
|
+
This will generate a docspec file that references the target markdown file using the naming convention: `filename.docspec.md` targets `filename.md` (e.g., `README.docspec.md` references `README.md`, `docs/guide.docspec.md` references `docs/guide.md`).
|
|
46
60
|
|
|
47
61
|
### Library Usage
|
|
48
62
|
|
|
49
63
|
```typescript
|
|
50
64
|
import { validateDocspec, generateDocspec } from "docspec";
|
|
65
|
+
import type { ValidationResult, DocspecSection } from "docspec";
|
|
51
66
|
|
|
52
67
|
// Validate a file
|
|
53
|
-
const result = await validateDocspec("path/to/file.docspec.md");
|
|
68
|
+
const result: ValidationResult = await validateDocspec("path/to/file.docspec.md");
|
|
54
69
|
if (!result.valid) {
|
|
55
70
|
console.error("Validation errors:", result.errors);
|
|
56
71
|
}
|
|
57
72
|
|
|
58
73
|
// Generate a new docspec file
|
|
59
|
-
await generateDocspec("path/to/
|
|
74
|
+
await generateDocspec("path/to/README.docspec.md");
|
|
60
75
|
```
|
|
61
76
|
|
|
77
|
+
The library exports:
|
|
78
|
+
- `validateDocspec()` - Validate a docspec file
|
|
79
|
+
- `generateDocspec()` - Generate a new docspec file
|
|
80
|
+
- `generateDocspecContent()` - Generate docspec content as a string
|
|
81
|
+
- `ValidationResult` - Type for validation results
|
|
82
|
+
- `DocspecSection` - Type for docspec sections
|
|
83
|
+
- `REQUIRED_SECTIONS` - Array of required section names
|
|
84
|
+
- `SECTION_BOILERPLATE` - Boilerplate text for each section
|
|
85
|
+
|
|
62
86
|
## Pre-commit Integration
|
|
63
87
|
|
|
64
|
-
To use docspec with [pre-commit](https://pre-commit.com/),
|
|
65
|
-
|
|
66
|
-
```yaml
|
|
67
|
-
repos:
|
|
68
|
-
- repo: local
|
|
69
|
-
hooks:
|
|
70
|
-
- id: docspec-validate
|
|
71
|
-
name: Validate docspec files
|
|
72
|
-
entry: docspec validate
|
|
73
|
-
language: system
|
|
74
|
-
files: \.docspec\.md$
|
|
75
|
-
pass_filenames: true
|
|
76
|
-
```
|
|
88
|
+
To use docspec with [pre-commit](https://pre-commit.com/), see [`.pre-commit-config.yaml`](.pre-commit-config.yaml) for the configuration. The hook uses `docspec validate` as the entry point, targets `\.docspec\.md$` files, and passes filenames to the validate command.
|
|
77
89
|
|
|
78
90
|
Then install the pre-commit hooks:
|
|
79
91
|
|
|
@@ -81,19 +93,103 @@ Then install the pre-commit hooks:
|
|
|
81
93
|
pre-commit install
|
|
82
94
|
```
|
|
83
95
|
|
|
84
|
-
The hook will automatically validate any modified `*.docspec.md` files on commit.
|
|
96
|
+
The hook will automatically validate any modified `*.docspec.md` files on commit. The hook passes filenames to the validate command, which will validate only those specific files. If no filenames are passed, the validator recursively finds all `*.docspec.md` files in the directory tree.
|
|
97
|
+
|
|
98
|
+
## GitHub Action Integration
|
|
99
|
+
|
|
100
|
+
Docspec includes two GitHub Actions for different use cases:
|
|
101
|
+
|
|
102
|
+
1. **Post-merge documentation updates** - Automatically syncs markdown files after PR merges (workflow file: `.github/workflows/docspec-check.yml`, workflow name: "Docspec PR check")
|
|
103
|
+
2. **Manual docspec generation** - Manually triggered workflow to generate and improve docspec files (workflow file: `.github/workflows/docspec-generate.yml`, workflow name: "Docspec generate")
|
|
104
|
+
|
|
105
|
+
### Post-Merge Documentation Updates
|
|
106
|
+
|
|
107
|
+
This action automatically updates markdown files based on `*.docspec.md` files after PR merges. It uses Claude Code CLI (not the Anthropic API directly) to explore the repository and generate unified diff patches for documentation updates.
|
|
108
|
+
|
|
109
|
+
#### Setup
|
|
110
|
+
|
|
111
|
+
1. **Add the workflow** to your repository: [`.github/workflows/docspec-check.yml`](.github/workflows/docspec-check.yml)
|
|
112
|
+
|
|
113
|
+
2. **Configure secrets**:
|
|
114
|
+
- Add `ANTHROPIC_API_KEY` to your repository secrets (Settings → Secrets and variables → Actions)
|
|
115
|
+
- `GITHUB_TOKEN` is automatically provided by GitHub Actions
|
|
116
|
+
|
|
117
|
+
#### How It Works
|
|
118
|
+
|
|
119
|
+
1. When a PR is merged, the workflow triggers
|
|
120
|
+
2. The action discovers relevant `*.docspec.md` files using a three-part discovery strategy:
|
|
121
|
+
- Files that changed directly in the PR (docspec files modified in the merge)
|
|
122
|
+
- Files in the same directory as any changed file (sibling docspecs)
|
|
123
|
+
- Files in parent directories, walking up to the repository root (ancestor docspecs)
|
|
124
|
+
3. For each discovered docspec, Claude Code CLI is invoked with built-in tools to explore the repository and understand the codebase context
|
|
125
|
+
4. Claude generates a unified diff patch to update the target markdown file based on the code changes and docspec requirements
|
|
126
|
+
5. Unified diff patches are validated and applied to update the markdown files
|
|
127
|
+
6. A new PR is opened with the documentation updates
|
|
128
|
+
|
|
129
|
+
**File naming convention**: The action uses the pattern `filename.docspec.md` → `filename.md`:
|
|
130
|
+
- `README.docspec.md` → targets `README.md`
|
|
131
|
+
- `docs/guide.docspec.md` → targets `docs/guide.md`
|
|
132
|
+
|
|
133
|
+
#### Configuration Options
|
|
134
|
+
|
|
135
|
+
The action supports optional inputs:
|
|
136
|
+
|
|
137
|
+
- `max_docspecs` (default: `10`) - Maximum number of docspec files to process per merge
|
|
138
|
+
- `max_diff_chars` (default: `120000`) - Maximum characters in PR diff before truncation
|
|
139
|
+
- `anthropic_model` (default: `claude-sonnet-4-5`) - Anthropic model to use (short alias for the Claude Sonnet 4.5 model)
|
|
140
|
+
|
|
141
|
+
See [`.github/workflows/docspec-check.yml`](.github/workflows/docspec-check.yml) for the complete workflow file and [`action.yml`](action.yml) for all available configuration options.
|
|
142
|
+
|
|
143
|
+
**Note**: For this repository's own workflow files, you can use the local reference `uses: ./` (at the action level in the step) instead of the published action reference. This applies to both the post-merge workflow and the manual improvement workflow.
|
|
144
|
+
|
|
145
|
+
#### Safety Features
|
|
146
|
+
|
|
147
|
+
The action includes multiple guardrails to ensure safe operation:
|
|
148
|
+
|
|
149
|
+
- **Max files limit**: Prevents processing too many files in a single run (default: 10)
|
|
150
|
+
- **Diff truncation**: Large PR diffs are truncated to stay within token limits (default: 120,000 characters)
|
|
151
|
+
- **Unified diff validation**: Only accepts properly formatted patches that start with `diff --git` or `--- ` markers
|
|
152
|
+
- **Path validation**: Patches must reference the expected file path
|
|
153
|
+
- **No new files**: Patches cannot create new files
|
|
154
|
+
- **No non-markdown modifications**: Only markdown files can be modified
|
|
155
|
+
- **Concurrency control**: Prevents multiple workflow runs from conflicting
|
|
156
|
+
- **Controlled environment**: Claude Code CLI runs with built-in tools in a controlled filesystem environment
|
|
157
|
+
|
|
158
|
+
### Manual Docspec Generation
|
|
159
|
+
|
|
160
|
+
The docspec-generate workflow allows you to manually trigger generation and improvements to a docspec file and its associated markdown file. This is useful when you want to:
|
|
161
|
+
|
|
162
|
+
- Update a docspec to better reflect the current state of the markdown
|
|
163
|
+
- Discover gaps in documentation that aren't triggered by code changes
|
|
164
|
+
- Regenerate a docspec from scratch
|
|
165
|
+
|
|
166
|
+
#### Setup
|
|
167
|
+
|
|
168
|
+
Add the workflow to your repository: [`.github/workflows/docspec-generate.yml`](.github/workflows/docspec-generate.yml)
|
|
169
|
+
|
|
170
|
+
#### How It Works
|
|
171
|
+
|
|
172
|
+
The workflow uses a two-phase approach with Claude Code CLI:
|
|
173
|
+
|
|
174
|
+
1. **Discovery Phase**: Claude explores the repository using available tools (no editing capabilities) and creates a detailed information discovery plan identifying:
|
|
175
|
+
- Missing information in the docspec (what should be documented but isn't)
|
|
176
|
+
- Irrelevant or incorrect information in the docspec (what doesn't match reality)
|
|
177
|
+
- Missing information in the markdown file (gaps in documentation)
|
|
178
|
+
|
|
179
|
+
2. **Implementation Phase**: Claude uses editing tools with `--permission-mode acceptEdits` to update both files based on the discovery plan. It preserves the exact structure of the docspec file (headers, separators, frontmatter, AGENT INSTRUCTIONS section) while only updating the content within sections 1-5.
|
|
85
180
|
|
|
86
|
-
|
|
181
|
+
Before the discovery phase begins, the workflow:
|
|
182
|
+
- Generates or overwrites the docspec file using `docspec generate`
|
|
183
|
+
- Validates the updated docspec file using `docspec validate` after changes are made
|
|
87
184
|
|
|
88
|
-
|
|
185
|
+
#### Usage
|
|
89
186
|
|
|
90
|
-
1.
|
|
91
|
-
2.
|
|
92
|
-
3.
|
|
93
|
-
4.
|
|
94
|
-
5. **Known Gaps or Intentional Omissions** - Things that should not be documented yet
|
|
187
|
+
1. Go to Actions → "Audit and improve docspec" in your repository
|
|
188
|
+
2. Click "Run workflow"
|
|
189
|
+
3. Enter the path to the markdown file (e.g., `README.md`)
|
|
190
|
+
4. The workflow will generate/update the corresponding docspec file and create a PR with improvements
|
|
95
191
|
|
|
96
|
-
|
|
192
|
+
**Note**: This workflow requires the `ANTHROPIC_API_KEY` secret to be configured.
|
|
97
193
|
|
|
98
194
|
## Development
|
|
99
195
|
|
|
@@ -69,29 +69,25 @@ describe("CLI", () => {
|
|
|
69
69
|
describe("validate command", () => {
|
|
70
70
|
it("should validate a valid docspec file", async () => {
|
|
71
71
|
const filePath = path.join(tempDir, "valid.docspec.md");
|
|
72
|
-
const validContent =
|
|
72
|
+
const validContent = `# DOCSPEC: Test
|
|
73
73
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
---
|
|
77
|
-
|
|
78
|
-
## 1. Purpose of This Document
|
|
74
|
+
## 1. Document Purpose
|
|
79
75
|
|
|
80
76
|
This document serves as a test case for the CLI validation command. It contains custom content that is different from the boilerplate template and sufficient to pass validation.
|
|
81
77
|
|
|
82
|
-
## 2.
|
|
78
|
+
## 2. Update Triggers
|
|
83
79
|
|
|
84
80
|
This document should be updated when testing CLI validation functionality. The content is meaningful and customized for testing purposes.
|
|
85
81
|
|
|
86
|
-
## 3. Structure
|
|
82
|
+
## 3. Expected Structure
|
|
87
83
|
|
|
88
84
|
This section describes the structure of the test document. It includes all required sections with adequate content to pass validation checks.
|
|
89
85
|
|
|
90
|
-
## 4.
|
|
86
|
+
## 4. Editing Guidelines
|
|
91
87
|
|
|
92
88
|
The style for this test document is straightforward and technical. It focuses on clarity and precision in describing test scenarios. Do: Ensure all sections have adequate content. Don't: Use boilerplate text or leave sections empty. Always provide meaningful test data.
|
|
93
89
|
|
|
94
|
-
## 5.
|
|
90
|
+
## 5. Intentional Omissions
|
|
95
91
|
|
|
96
92
|
There are no known gaps in this test document. All sections are complete and properly formatted with sufficient content.
|
|
97
93
|
`;
|
|
@@ -102,7 +98,7 @@ There are no known gaps in this test document. All sections are complete and pro
|
|
|
102
98
|
});
|
|
103
99
|
it("should reject an invalid docspec file", async () => {
|
|
104
100
|
const filePath = path.join(tempDir, "invalid.docspec.md");
|
|
105
|
-
await (0, generator_1.generateDocspec)(filePath
|
|
101
|
+
await (0, generator_1.generateDocspec)(filePath); // This creates boilerplate-only content
|
|
106
102
|
const result = await runCli(`validate ${filePath}`);
|
|
107
103
|
expect(result.code).toBe(1);
|
|
108
104
|
const output = result.stdout + result.stderr;
|
|
@@ -112,29 +108,25 @@ There are no known gaps in this test document. All sections are complete and pro
|
|
|
112
108
|
it("should validate multiple files", async () => {
|
|
113
109
|
const file1 = path.join(tempDir, "file1.docspec.md");
|
|
114
110
|
const file2 = path.join(tempDir, "file2.docspec.md");
|
|
115
|
-
const validContent =
|
|
116
|
-
|
|
117
|
-
# DOCSPEC: Test
|
|
118
|
-
|
|
119
|
-
---
|
|
111
|
+
const validContent = `# DOCSPEC: Test
|
|
120
112
|
|
|
121
|
-
## 1. Purpose
|
|
113
|
+
## 1. Document Purpose
|
|
122
114
|
|
|
123
115
|
This document serves as a test case for validating multiple docspec files. It contains custom content that is different from the boilerplate template.
|
|
124
116
|
|
|
125
|
-
## 2.
|
|
117
|
+
## 2. Update Triggers
|
|
126
118
|
|
|
127
119
|
This document should be updated when testing multiple file validation. The content is meaningful and customized for testing purposes.
|
|
128
120
|
|
|
129
|
-
## 3. Structure
|
|
121
|
+
## 3. Expected Structure
|
|
130
122
|
|
|
131
123
|
This section describes the structure of the test document. It includes all required sections with adequate content to pass validation checks.
|
|
132
124
|
|
|
133
|
-
## 4.
|
|
125
|
+
## 4. Editing Guidelines
|
|
134
126
|
|
|
135
127
|
The style for this test document is straightforward and technical. It focuses on clarity and precision in describing test scenarios. Do: Ensure all sections have adequate content. Don't: Use boilerplate text or leave sections empty. Always provide meaningful test data.
|
|
136
128
|
|
|
137
|
-
## 5.
|
|
129
|
+
## 5. Intentional Omissions
|
|
138
130
|
|
|
139
131
|
There are no known gaps in this test document. All sections are complete and properly formatted with sufficient content.
|
|
140
132
|
`;
|
|
@@ -149,29 +141,25 @@ There are no known gaps in this test document. All sections are complete and pro
|
|
|
149
141
|
const file1 = path.join(tempDir, "file1.docspec.md");
|
|
150
142
|
const file2 = path.join(tempDir, "nested", "file2.docspec.md");
|
|
151
143
|
await fs.mkdir(path.join(tempDir, "nested"), { recursive: true });
|
|
152
|
-
const validContent =
|
|
144
|
+
const validContent = `# DOCSPEC: Test
|
|
153
145
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
---
|
|
157
|
-
|
|
158
|
-
## 1. Purpose of This Document
|
|
146
|
+
## 1. Document Purpose
|
|
159
147
|
|
|
160
148
|
This document serves as a test case for validating multiple docspec files. It contains custom content that is different from the boilerplate template.
|
|
161
149
|
|
|
162
|
-
## 2.
|
|
150
|
+
## 2. Update Triggers
|
|
163
151
|
|
|
164
152
|
This document should be updated when testing multiple file validation. The content is meaningful and customized for testing purposes.
|
|
165
153
|
|
|
166
|
-
## 3. Structure
|
|
154
|
+
## 3. Expected Structure
|
|
167
155
|
|
|
168
156
|
This section describes the structure of the test document. It includes all required sections with adequate content to pass validation checks.
|
|
169
157
|
|
|
170
|
-
## 4.
|
|
158
|
+
## 4. Editing Guidelines
|
|
171
159
|
|
|
172
160
|
The style for this test document is straightforward and technical. It focuses on clarity and precision in describing test scenarios. Do: Ensure all sections have adequate content. Don't: Use boilerplate text or leave sections empty. Always provide meaningful test data.
|
|
173
161
|
|
|
174
|
-
## 5.
|
|
162
|
+
## 5. Intentional Omissions
|
|
175
163
|
|
|
176
164
|
There are no known gaps in this test document. All sections are complete and properly formatted with sufficient content.
|
|
177
165
|
`;
|
|
@@ -204,7 +192,7 @@ There are no known gaps in this test document. All sections are complete and pro
|
|
|
204
192
|
describe("generate command", () => {
|
|
205
193
|
it("should generate a new docspec file", async () => {
|
|
206
194
|
const filePath = path.join(tempDir, "new.docspec.md");
|
|
207
|
-
const result = await runCli(`generate ${filePath}
|
|
195
|
+
const result = await runCli(`generate ${filePath}`);
|
|
208
196
|
expect(result.code).toBe(0);
|
|
209
197
|
expect(result.stdout).toContain("✅");
|
|
210
198
|
expect(result.stdout).toContain("new.docspec.md");
|
|
@@ -213,30 +201,30 @@ There are no known gaps in this test document. All sections are complete and pro
|
|
|
213
201
|
});
|
|
214
202
|
it("should generate file with correct content", async () => {
|
|
215
203
|
const filePath = path.join(tempDir, "test.docspec.md");
|
|
216
|
-
await runCli(`generate ${filePath}
|
|
204
|
+
await runCli(`generate ${filePath}`);
|
|
217
205
|
const content = await fs.readFile(filePath, "utf-8");
|
|
218
|
-
expect(content).toContain("# DOCSPEC:
|
|
219
|
-
expect(content).toContain("Purpose
|
|
206
|
+
expect(content).toContain("# DOCSPEC: [test.md](/test.md)");
|
|
207
|
+
expect(content).toContain("Document Purpose");
|
|
220
208
|
});
|
|
221
209
|
it("should auto-append .docspec.md if not present", async () => {
|
|
222
210
|
const filePath = path.join(tempDir, "test");
|
|
223
|
-
await runCli(`generate ${filePath}
|
|
211
|
+
await runCli(`generate ${filePath}`);
|
|
224
212
|
const fullPath = filePath + ".docspec.md";
|
|
225
213
|
const exists = await fs.access(fullPath).then(() => true).catch(() => false);
|
|
226
214
|
expect(exists).toBe(true);
|
|
227
215
|
});
|
|
228
216
|
it("should create nested directories", async () => {
|
|
229
217
|
const filePath = path.join(tempDir, "nested", "deep", "test.docspec.md");
|
|
230
|
-
const result = await runCli(`generate ${filePath}
|
|
218
|
+
const result = await runCli(`generate ${filePath}`);
|
|
231
219
|
expect(result.code).toBe(0);
|
|
232
220
|
const exists = await fs.access(filePath).then(() => true).catch(() => false);
|
|
233
221
|
expect(exists).toBe(true);
|
|
234
222
|
});
|
|
235
|
-
it("should
|
|
223
|
+
it("should generate link to target markdown file", async () => {
|
|
236
224
|
const filePath = path.join(tempDir, "my-awesome-doc.docspec.md");
|
|
237
225
|
await runCli(`generate ${filePath}`);
|
|
238
226
|
const content = await fs.readFile(filePath, "utf-8");
|
|
239
|
-
expect(content).toContain("# DOCSPEC:
|
|
227
|
+
expect(content).toContain("# DOCSPEC: [my-awesome-doc.md](/my-awesome-doc.md)");
|
|
240
228
|
});
|
|
241
229
|
});
|
|
242
230
|
describe("help and version", () => {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.test.js","sourceRoot":"","sources":["../../src/__tests__/cli.test.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAkC;AAClC,2CAA6B;AAC7B,uCAAyB;AACzB,iDAAqC;AACrC,+BAAiC;AACjC,4CAA+C;AAE/C,MAAM,SAAS,GAAG,IAAA,gBAAS,EAAC,oBAAI,CAAC,CAAC;AAElC,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE;IACnB,IAAI,OAAe,CAAC;IACpB,IAAI,WAAmB,CAAC;IAExB,UAAU,CAAC,KAAK,IAAI,EAAE;QACpB,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,mBAAmB,CAAC,CAAC,CAAC;QACxE,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;QAC5B,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,KAAK,IAAI,EAAE;QACnB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAC3B,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,KAAK,EAAE,IAAY,EAA6D,EAAE;QAC/F,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC;QAC1D,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,QAAQ,OAAO,IAAI,IAAI,EAAE,CAAC,CAAC;YACtE,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACjE,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO;gBACL,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;gBAC1B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;gBAC1B,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC;aACtB,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;IAEF,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;QAChC,EAAE,CAAC,sCAAsC,EAAE,KAAK,IAAI,EAAE;YACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;YAExD,MAAM,YAAY,GAAG
|
|
1
|
+
{"version":3,"file":"cli.test.js","sourceRoot":"","sources":["../../src/__tests__/cli.test.ts"],"names":[],"mappings":"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"}
|
|
@@ -8,11 +8,11 @@ describe("constants", () => {
|
|
|
8
8
|
});
|
|
9
9
|
it("should contain all expected section names", () => {
|
|
10
10
|
const expectedSections = [
|
|
11
|
-
"Purpose
|
|
12
|
-
"
|
|
13
|
-
"Structure
|
|
14
|
-
"
|
|
15
|
-
"
|
|
11
|
+
"Document Purpose",
|
|
12
|
+
"Update Triggers",
|
|
13
|
+
"Expected Structure",
|
|
14
|
+
"Editing Guidelines",
|
|
15
|
+
"Intentional Omissions",
|
|
16
16
|
];
|
|
17
17
|
expectedSections.forEach((section) => {
|
|
18
18
|
expect(constants_1.REQUIRED_SECTIONS).toContain(section);
|
|
@@ -28,9 +28,9 @@ describe("constants", () => {
|
|
|
28
28
|
});
|
|
29
29
|
});
|
|
30
30
|
describe("getDocspecTemplate", () => {
|
|
31
|
-
it("should generate a template with
|
|
32
|
-
const template = (0, constants_1.getDocspecTemplate)("
|
|
33
|
-
expect(template).toContain("# DOCSPEC:
|
|
31
|
+
it("should generate a template with link to target file", () => {
|
|
32
|
+
const template = (0, constants_1.getDocspecTemplate)("README.md");
|
|
33
|
+
expect(template).toContain("# DOCSPEC: [README.md](/README.md)");
|
|
34
34
|
});
|
|
35
35
|
it("should include all 5 required sections", () => {
|
|
36
36
|
const template = (0, constants_1.getDocspecTemplate)("Test");
|
|
@@ -52,16 +52,6 @@ describe("constants", () => {
|
|
|
52
52
|
expect(template).toContain(boilerplate.split("\n")[0]);
|
|
53
53
|
});
|
|
54
54
|
});
|
|
55
|
-
it("should include separators between sections", () => {
|
|
56
|
-
const template = (0, constants_1.getDocspecTemplate)("Test");
|
|
57
|
-
// Should have separators for 5 sections
|
|
58
|
-
const separatorCount = (template.match(/^---$/gm) || []).length;
|
|
59
|
-
expect(separatorCount).toBeGreaterThanOrEqual(2); // At least front matter and between sections
|
|
60
|
-
});
|
|
61
|
-
it("should have proper front matter format", () => {
|
|
62
|
-
const template = (0, constants_1.getDocspecTemplate)("Test");
|
|
63
|
-
expect(template).toMatch(/^---\n/);
|
|
64
|
-
});
|
|
65
55
|
});
|
|
66
56
|
});
|
|
67
57
|
//# sourceMappingURL=constants.test.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"constants.test.js","sourceRoot":"","sources":["../../src/__tests__/constants.test.ts"],"names":[],"mappings":";;AAAA,4CAA0F;AAE1F,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;QACjC,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;YACjD,MAAM,CAAC,6BAAiB,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;YACnD,MAAM,gBAAgB,GAAG;gBACvB,
|
|
1
|
+
{"version":3,"file":"constants.test.js","sourceRoot":"","sources":["../../src/__tests__/constants.test.ts"],"names":[],"mappings":";;AAAA,4CAA0F;AAE1F,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;QACjC,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;YACjD,MAAM,CAAC,6BAAiB,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;YACnD,MAAM,gBAAgB,GAAG;gBACvB,kBAAkB;gBAClB,iBAAiB;gBACjB,oBAAoB;gBACpB,oBAAoB;gBACpB,uBAAuB;aACxB,CAAC;YAEF,gBAAgB,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;gBACnC,MAAM,CAAC,6BAAiB,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAC/C,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;QACnC,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;YAC3D,6BAAiB,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;gBACpC,MAAM,CAAC,+BAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;gBACnD,MAAM,CAAC,+BAAmB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YACjE,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAClC,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;YAC7D,MAAM,QAAQ,GAAG,IAAA,8BAAkB,EAAC,WAAW,CAAC,CAAC;YACjD,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,oCAAoC,CAAC,CAAC;QACnE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;YAChD,MAAM,QAAQ,GAAG,IAAA,8BAAkB,EAAC,MAAM,CAAC,CAAC;YAC5C,6BAAiB,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;gBACpC,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YACtC,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;YACxC,MAAM,QAAQ,GAAG,IAAA,8BAAkB,EAAC,MAAM,CAAC,CAAC;YAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5B,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzC,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;YAC7D,MAAM,QAAQ,GAAG,IAAA,8BAAkB,EAAC,MAAM,CAAC,CAAC;YAC5C,6BAAiB,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;gBACpC,MAAM,WAAW,GAAG,+BAAmB,CAAC,OAAO,CAAC,CAAC;gBACjD,yDAAyD;gBACzD,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACzD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IAEL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
|