diff --git a/CHANGELOG.md b/CHANGELOG.md index da40a44..231c615 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## 0.5.1 — 2026-10-07 + +- **Clearer descriptions:** the Marketplace description, README and messages now say plainly that diagrams are `.archify` files in YAML. Archify's own JSON files (`*.architecture.json`, …) and rendered HTML are described as also supported, in their own section. +- The rendered-HTML editor is now called **Archify HTML Viewer** (was *Archify Diagram Viewer*, the same name as the extension), and its command **Open in Archify HTML Viewer**. +- Messages: "open a .archify diagram first"; an empty or broken `.archify` file asks for valid YAML, not JSON. + ## 0.5.0 — 2026-10-04 - **Brand completion:** after `brand:` in `.archify` files and Archify JSON sources, the editor suggests the 107 built-in brand IDs with their product names. Aliases and product names match too (`kafka` → `apache-kafka`, `postgres` → `postgresql`). diff --git a/README.md b/README.md index 837b0d4..6939caa 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,21 @@ # Archify Diagram Viewer -View [Archify](https://github.com/tt-a1i/archify) diagrams inside VS Code. Click a `.archify` file (YAML) and the interactive diagram opens straight away; open its source beside it and the diagram follows your edits. Rendered Archify HTML files open in a viewer tab instead of a browser. +Create and view [Archify](https://github.com/tt-a1i/archify) diagrams inside VS Code. You write a diagram as a **`.archify` file in YAML**; clicking it opens the interactive diagram, and the diagram follows your edits as you type. ![An Archify workflow diagram as shown by the preview](docs/preview.png) This is an unofficial extension. It bundles the Archify renderer (MIT, © tt-a1i) and runs it on VS Code's own Node runtime, so nothing else needs to be installed. +## Supported files + +| File | Format | What the extension does | +|---|---|---| +| **`name.archify`** | **YAML** (the main format) | Opens as the interactive diagram. Show Source, live updates, validation, completion, templates. | +| `name.architecture.json`, `name.workflow.json`, `name.sequence.json`, `name.dataflow.json`, `name.lifecycle.json` | JSON (Archify's own CLI format) | Opens as text, with a preview beside it and validation. For files produced by the Archify CLI or AI agents. | +| Rendered Archify `.html` | HTML | Read-only viewer instead of a browser. | + +New diagrams should be `.archify` files; everything below describes them unless it says otherwise. + ## Quick start The fastest start: right-click a folder in the Explorer and choose **New Diagram Archify…** (also in *File → New File…* and the Command Palette). Pick a kind of diagram (Architecture, Workflow, Sequence, Data Flow, Lifecycle or Everyday Plan), give it a name, and a small working `.archify` file is created and opened. Change its YAML to fit your case. @@ -36,22 +46,26 @@ The same file is in [examples/hello.archify](examples/hello.archify). ## The `.archify` format -A `.archify` file is an Archify diagram source written in **YAML**. It has the same fields as the JSON the Archify CLI renders, and plain JSON content still works, since JSON is valid YAML. `diagram_type` selects the kind of diagram: `architecture`, `workflow`, `sequence`, `dataflow` or `lifecycle`. +A `.archify` file is an Archify diagram written in **YAML**. Its fields are those of Archify's diagram schema; the extension converts the YAML for the renderer, so you never handle JSON yourself. `diagram_type` selects the kind of diagram: `architecture`, `workflow`, `sequence`, `dataflow` or `lifecycle`. - **Opening:** the **Archify Diagram** editor is the default for `.archify`. Use *Reopen Editor With… → Text Editor* to edit the YAML full-screen. - **Completion:** with the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) (`redhat.vscode-yaml`) installed, `.archify` files get completion and hover from Archify's schemas. The schema follows `diagram_type`. -Archify's own JSON naming, `name.architecture.json`, `name.workflow.json` and so on, works too. Those open as text with a preview button, and get schema help from VS Code's built-in JSON support. +`.archify` files from extension version 0.2.0 were written in JSON. They still open, because JSON is valid YAML, but new files should use YAML. + +## Archify's JSON files + +The Archify CLI and the AI agents that use it write diagrams as JSON, named `name.architecture.json`, `name.workflow.json` and so on. The extension supports these too: they open as text with a preview button in the editor title (Cmd/Ctrl+K V to the side, Cmd/Ctrl+Shift+V in place), get validation in Problems, and get schema completion from VS Code's built-in JSON support. Any other `.json` file that declares an Archify `diagram_type` previews the same way. ## Features - **New diagram from a template**: *New Diagram Archify…* creates a starter `.archify` file for any of the five diagram kinds, or an everyday plan, in the chosen folder. - **Diagram editor**: `.archify` files open as the rendered diagram. **Show Source** opens the YAML beside it, and edits re-render live. -- **Live preview**: for Archify's `*.architecture.json`-style files, or any JSON with a `diagram_type`. Use the preview button in the editor title, Cmd/Ctrl+K V (to the side) or Cmd/Ctrl+Shift+V. The preview keeps the focus and route you selected (`#focus=…`, `#route=…`) when it re-renders. -- **HTML viewer**: right-click a rendered `.html` file and choose **Open in Archify Viewer**, or use *Reopen Editor With… → Archify Diagram Viewer*. For Archify HTML already open as text, a button appears in the editor title. The viewer reloads when the file changes on disk. -- **Problems**: YAML syntax errors, plus `archify validate`'s schema, layout and evidence problems, appear at the matching line of the source. +- **Live updates**: the diagram re-renders as you edit, and keeps the focus and route you selected (`#focus=…`, `#route=…`). +- **HTML viewer**: right-click a rendered `.html` file and choose **Open in Archify HTML Viewer**, or use *Reopen Editor With… → Archify HTML Viewer*. For Archify HTML already open as text, a button appears in the editor title. The viewer reloads when the file changes on disk. +- **Problems**: YAML syntax errors, plus `archify validate`'s schema, layout and evidence problems, appear at the matching line of the `.archify` file. - **Brand logos**: after `brand:` the editor suggests Archify's built-in brand IDs (PostgreSQL, Redis, Kafka, Docker, …). Typing an alias or product name finds them too, so `kafka` offers `apache-kafka`. An unknown brand is reported on its own line. -- **Schema help**: completion and hover come from Archify's own schemas: built in for the JSON files, and through the YAML extension for `.archify` files. +- **Schema help**: completion and hover from Archify's own schemas, through the YAML extension for `.archify` files. - **Source links**: in source-backed diagrams, clicking a source reference opens that file and line range in the editor. If the file is not in the workspace, the web link opens instead. - **Export**: the diagram's own Export menu (PNG, SVG, share card, …) saves through a VS Code save dialog. - **Commands**: *New Diagram Archify…*, *Archify: Render to HTML File…*, *Archify: Open in Browser*, *Archify: Refresh Preview*, *Archify: Show Source*. diff --git a/package-lock.json b/package-lock.json index f6f12f3..0a2f1d4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "archify-vscode-ext", - "version": "0.5.0", + "version": "0.5.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "archify-vscode-ext", - "version": "0.5.0", + "version": "0.5.1", "license": "MIT", "dependencies": { "yaml": "^2.9.1" diff --git a/package.json b/package.json index d6df6fe..fe1bc4d 100644 --- a/package.json +++ b/package.json @@ -1,8 +1,8 @@ { "name": "archify-vscode-ext", "displayName": "Archify Diagram Viewer", - "description": "Visualize Archify diagrams: .archify files (YAML) open straight into the interactive diagram; also previews Archify JSON sources and rendered Archify HTML inside VS Code.", - "version": "0.5.0", + "description": "Archify diagrams in VS Code. Write diagrams as .archify files in YAML: they open as the interactive diagram, with live updates, validation, templates and completion. Also previews Archify's own JSON files (*.architecture.json, \u2026) and opens rendered Archify HTML.", + "version": "0.5.1", "publisher": "root-at-skic", "license": "MIT", "icon": "media/icon.png", @@ -23,6 +23,7 @@ ], "keywords": [ "archify", + "yaml", "diagram", "architecture", "sequence", @@ -57,7 +58,7 @@ }, { "command": "archify.openHtmlViewer", - "title": "Open in Archify Viewer", + "title": "Open in Archify HTML Viewer", "category": "Archify", "icon": "$(open-preview)" }, @@ -212,7 +213,7 @@ }, { "viewType": "archify.htmlViewer", - "displayName": "Archify Diagram Viewer", + "displayName": "Archify HTML Viewer", "selector": [ { "filenamePattern": "*.html" diff --git a/src/extension.ts b/src/extension.ts index 7b3b467..175ebea 100644 --- a/src/extension.ts +++ b/src/extension.ts @@ -35,7 +35,7 @@ export function activate(context: vscode.ExtensionContext): void { function sourceUri(arg?: unknown): vscode.Uri | undefined { const uri = targetUri(arg); - if (!uri) vscode.window.showWarningMessage('Archify: open a diagram JSON source first.'); + if (!uri) vscode.window.showWarningMessage('Archify: open a .archify diagram first.'); return uri; } diff --git a/src/preview.ts b/src/preview.ts index e6f61d9..45f68c6 100644 --- a/src/preview.ts +++ b/src/preview.ts @@ -1,6 +1,6 @@ import path from 'node:path'; import * as vscode from 'vscode'; -import { readDiagramSource } from './detect'; +import { isArchifyFile, readDiagramSource } from './detect'; import { renderDiagram } from './renderer'; import { evidenceMode, log, readText, runtimeFor, viewerTheme } from './runtime'; import { handleWebviewMessage, WebviewMessage } from './webviewMessages'; @@ -100,7 +100,7 @@ class DiagramPreview implements vscode.Disposable { if (!source) { this.showMessage( 'Nothing to show yet', - 'Set "diagram_type" to architecture, workflow, sequence, dataflow or lifecycle, and make sure the file is valid JSON.', + `Set "diagram_type" to architecture, workflow, sequence, dataflow or lifecycle, and make sure the file is valid ${isArchifyFile(this.uri.path) ? 'YAML' : 'JSON'}.`, ); return; }