mdast-control 0.1.0

package/README.md

@@ -0,0 +1,359 @@
+# mdast-control
+
+Markdown の AST 変換、Markdown 復元、独自 Query 言語による抽出と挿入、CLI と LSP をまとめた TypeScript 実装です。
+
+詳細仕様は [docs/specification.md](docs/specification.md) を参照してください。
+表操作と CSV/TSV 相互変換の設計は [docs/table-design.md](docs/table-design.md) を参照してください。
+AST 要素プラグインと introspection の設計は [docs/plugin-architecture.md](docs/plugin-architecture.md) を参照してください。
+MVP 受入境界は [docs/acceptance/mvp-baseline.md](docs/acceptance/mvp-baseline.md)、現在のローカル候補保証は [docs/acceptance/local-release-candidate.md](docs/acceptance/local-release-candidate.md)、確定した設計判断は [docs/adr/README.md](docs/adr/README.md) を参照してください。
+
+## インストール
+
+```bash
+npm install mdast-control
+```
+
+TypeScript / JavaScript API に加えて、`mdastctl` CLI と `mdast-lsp` language server が含まれます。
+
+## 機能
+
+- Markdown から mdast 互換 AST への変換
+- GFM table の parse / stringify
+- GFM table の正規化モデル抽出と座標解決
+- CSV/TSV の robust な export/import と table AST 生成
+- table cell/row/column の構造編集と安定ソート
+- AST JSON から Markdown への復元
+- Query 言語によるノード抽出
+- anchored glob と数値比較を含む Query predicate
+- Query 結果に対する before/after/prepend/append 挿入
+- Query 結果に対する置換と削除
+- Query 結果に対する wrap、unwrap、move
+- 明示的な wrapper placeholder、move target policy、非破壊 copy
+- plugin registry と capability introspection
+- table plugin の `updateCell` と `exportDelimited`
+- codeBlock plugin の literal edit/extract と JSON validation/formatting
+- table query/export/import/edit の CLI フロント
+- LSP による Markdown 構造シンボル、Query 診断、table query/export/import/edit
+
+## Query 言語
+
+単純なセレクタ列を採用します。
+
+- `heading`
+- `root`
+- `heading[depth=2]`
+- `heading[depth=1,text*=Release]`
+- `heading[text*=Release]`
+- `heading[text^=Release]`
+- `heading[text$=Notes]`
+- `heading[text!=Changelog]`
+- `heading[text~=Release*]`
+- `heading[depth>=2]`
+- `tableRow[rowIndex=0]`
+- `tableCell[columnIndex=1,cellText=Open]`
+- `tableCell[rowIndex=0,headerText=Status,cellText=Open]`
+- `table[rowCount=2,columnCount=3]`
+- `paragraph > text`
+- `listItem text[value*=TODO]`
+
+対応演算子:
+
+- `=`: 完全一致
+- `*=`: 部分一致
+- `^=`: 前方一致
+- `$=`: 後方一致
+- `!=`: 不一致
+- `~=`: 文字列全体に対する glob 一致（`*` は 0 文字以上、`?` は 1 文字、`\` は escape）
+- `>` / `>=` / `<` / `<=`: 有限数値フィールドと 10 進 operand の数値比較
+
+特別なフィールド:
+
+- `text`: ノード配下の可視テキストを連結して比較
+- `rowIndex`: `tableRow` と `tableCell` に対する body row の 0-based index
+- `columnIndex`: `tableCell` に対する 0-based column index
+- `headerText`: `tableCell` が属する列の header cell text
+- `cellText`: `tableCell` の可視テキスト
+- `rowCount`: `table` の header を除く body row 数
+- `columnCount`: `table` の正規化後の列数
+
+子孫は空白、直下の子は `>` で指定します。
+
+## CLI
+
+```bash
+npm install
+npm run build
+
+echo '# Title' | node dist/cli.js parse
+echo '{"type":"root","children":[]}' | node dist/cli.js print
+echo '# Title' | node dist/cli.js query --select 'heading[depth=1]'
+echo '# Title' | node dist/cli.js insert --select 'heading[depth=1]' --position after --markdown 'Inserted text'
+echo '# Title' | node dist/cli.js replace --select 'heading[depth=1]' --markdown 'New Title'
+echo '# Title\n\nBody' | node dist/cli.js delete --select 'paragraph[text=Body]'
+echo '# Title' | node dist/cli.js wrap --select 'heading' --markdown '> Quote'
+echo '> Quote' | node dist/cli.js unwrap --select 'blockquote'
+echo '# One\n\n# Two' | node dist/cli.js move --select 'heading[text=One]' --to 'heading[text=Two]' --position after
+echo '# One\n\n# Target\n\n# Target' | node dist/cli.js move --select 'heading[text=One]' --to 'heading[text=Target]' --position after --target-policy last
+echo '# One\n\n# Target\n\n# Target' | node dist/cli.js copy --select 'heading[text=One]' --to 'heading[text=Target]' --position after --target-policy first
+node dist/cli.js capabilities --format json
+node dist/cli.js plugin list
+node dist/cli.js plugin show --plugin table --format json
+node dist/cli.js plugin operation --plugin table --name updateCell --format json
+printf '| Name | Value |\n| - | - |\n| A | 1 |\n' | node dist/cli.js plugin run --plugin table --name updateCell --select 'tableCell' --args '{"markdown":"Updated"}'
+printf '| Name | Value |\n| - | - |\n| A | 1 |\n' | node dist/cli.js plugin run --plugin table --name exportDelimited --select 'table' --args '{"format":"csv"}'
+printf '```json\n{"ok":true}\n```\n' | node dist/cli.js plugin run --plugin codeBlock --name validateContent --select 'code' --args '{"format":"json"}'
+printf '```json\n{"ok":true}\n```\n' | node dist/cli.js plugin run --plugin codeBlock --name formatContent --select 'code' --args '{"format":"json","indent":2}'
+printf '| Name | Value |\n| - | - |\n| A | 1 |\n' | node dist/cli.js table query --select table
+printf '| Name | Note |\n| - | - |\n| A | x, y |\n' | node dist/cli.js table export --select table --format csv
+printf 'Name,Value\nA,1\n' | node dist/cli.js table import --format csv
+printf '| Old | Value |\n| - | - |\n| A | 1 |\n' | node dist/cli.js table import --format csv --replace table --data $'New,Value\nB,2'
+printf '| Name | Status |\n| - | - |\n| A | Open |\n' | node dist/cli.js table cell set --select table --row 0 --column Status --value Closed
+printf '| Name | Status |\n| - | - |\n| A | Open |\n' | node dist/cli.js table row insert --select table --index 1 --values '["B"]'
+printf '| Name | Status |\n| - | - |\n| A | Open |\n' | node dist/cli.js table column add --select table --index 1 --header Owner --values '["Kai"]'
+printf '| Name | Status |\n| - | - |\n| B | Open |\n| A | Closed |\n' | node dist/cli.js table sort --select table --column Name --direction asc
+```
+
+`query` の出力は transport-safe な `{ path, node }` 配列です。
+
+`print` と API の `jsonToAst` は、JSON の各 node に空でない文字列 `type` があり、存在する `children` が同じ node 形状の配列であることを検証します。その他の mdast 拡張プロパティは保持します。
+
+`capabilities` は core の query operator / generic operation / custom LSP request と plugin 群の snapshot を返します。`plugin list`、`plugin show`、`plugin operation` で element plugin の metadata を introspection できます。
+`plugin run` は stdin の Markdown を対象に plugin operation を実行します。built-in の table 操作は `updateCell` と `exportDelimited`、codeBlock 操作は `setLanguage`、`replaceContent`、`appendContent`、`extractContent`、`validateContent`、`formatContent` です。codeBlock の validation/formatting は明示的な `json` format だけを扱い、多言語 formatter を暗黙に選びません。
+
+operation descriptor は `targetCardinality` を持ち、registry が引数、対象数、対象 node kind を handler の前で検証します。未知の引数は拒否されます。API の operation failure は `PluginOperationError` として `{ code, plugin, operation, message, details? }` を保持し、LSP は同じ shape を JSON-RPC error data に載せます。
+
+`table query` と `table export` は exactly one の table を要求します。`table import` は単体変換では stdin を CSV/TSV として読みます。`--replace` または `--insert` を使う場合は stdin を Markdown とし、CSV/TSV は `--data` で明示します。import は plain-text cell を生成し、inline Markdown の書式は保持しません。
+
+table 構造編集も exactly one の table を要求します。body row と column は 0-based、header 名は完全一致で重複時に失敗します。短い row/column 値は空 cell で補完し、暗黙の列追加になる過剰値は拒否します。cell set は plain text を書き込み、sort は既存の inline AST を保ったまま body row だけを安定ソートします。
+
+`root` は Query 対象にできます。編集では `prepend` と `append` は有効ですが、`before`、`after`、`delete`、`replace` の対象にはできません。
+
+`wrap` は従来どおり 1 個の top-level container node の末尾へ追加できます。wrapper Markdown に standalone block marker `<!-- mdast:content -->` をちょうど 1 個置くと、複数 top-level node または blockquote/list item 内のその位置へ matched node を配置できます。
+
+`move` と `copy` は source query の入れ子一致をそのまま複製せず、外側の一致だけへ正規化します。target policy は後方互換の `exactly-one`（既定）、document order の `first`、`last` です。`move` は原本を削除し、`copy` は clone を挿入して原本を保ちます。
+
+## LSP
+
+```bash
+node dist/lsp/server.js --stdio
+```
+
+LSP は次を提供します。
+
+- Markdown 文書の AST ベース document symbols
+- ```mdast-query``` フェンス内 Query の構文診断
+- カスタム request `mdast/query` による抽出
+- カスタム request `mdast/capabilities` による capability snapshot の取得
+- カスタム request `mdast/pluginList` による plugin 一覧の取得
+- カスタム request `mdast/pluginShow` による plugin descriptor の取得
+- カスタム request `mdast/elementCapabilities` による element kind 別 capability の取得
+- カスタム request `mdast/pluginOperation` による operation descriptor の取得
+- カスタム request `mdast/pluginRun` による plugin operation 実行
+- カスタム request `mdast/insert` による Markdown 更新案の返却
+- カスタム request `mdast/delete` による削除後 Markdown の返却
+- カスタム request `mdast/replace` による置換後 Markdown の返却
+- カスタム request `mdast/wrap` による wrap 後 Markdown の返却
+- カスタム request `mdast/unwrap` による unwrap 後 Markdown の返却
+- カスタム request `mdast/move` による move 後 Markdown の返却
+- カスタム request `mdast/copy` による非破壊 copy 後 Markdown の返却
+- カスタム request `mdast/tableQuery` による正規化 table model の取得
+- カスタム request `mdast/tableExport` による CSV/TSV 取得
+- カスタム request `mdast/tableImport` による table の置換または挿入案の返却
+- カスタム request `mdast/tableUpdateCell`、`mdast/tableInsertRow`、`mdast/tableDeleteRow` による cell/row 編集案の返却
+- カスタム request `mdast/tableAddColumn`、`mdast/tableDeleteColumn`、`mdast/tableSort` による column/順序編集案の返却
+
+`mdast/query` request 例:
+
+```json
+{
+	"uri": "file:///tmp/sample.md",
+	"query": "heading[depth=2]"
+}
+```
+
+`mdast/query` の応答も transport-safe な `{ path, node }` 配列です。
+
+`mdast/capabilities` は core と plugin の capability snapshot を返します。`mdast/pluginShow` と `mdast/pluginOperation` は未解決の対象に対して `null` を返します。
+`mdast/pluginRun` は plugin operation の結果を返します。mutation 系は `{ kind: "mutation", changed, markdown }`、text conversion は `{ kind: "text", text }`、structured analysis は `{ kind: "json", value }` を返します。
+
+`mdast/insert` は `{ inserted, markdown }` を返します。`mdast/delete` と `mdast/replace` は `{ changed, markdown }` を返します。
+`mdast/wrap`、`mdast/unwrap`、`mdast/move` も `{ changed, markdown }` を返します。
+`mdast/move` と `mdast/copy` は optional `targetPolicy` として `exactly-one`、`first`、`last` を受け取ります。
+
+`mdast/tableQuery` は正規化 model、`mdast/tableExport` は CSV/TSV text、table import/edit request は `{ changed, markdown }` を返します。table query/export/replacement/structural edit は exactly one の table、interchange insertion は exactly one の target を要求します。
+
+対象文書が LSP に未オープンの場合、`mdast/query` は空配列、table query/export は `null`、編集系 request は件数 0 と空 Markdown を返します。
+
+payload が不正な場合、LSP custom request は invalid params エラーで失敗します。
+
+`mdast/insert` request 例:
+
+```json
+{
+	"uri": "file:///tmp/sample.md",
+	"query": "heading[depth=1]",
+	"position": "after",
+	"markdown": "Inserted paragraph"
+}
+```
+
+`mdast/delete` request 例:
+
+```json
+{
+	"uri": "file:///tmp/sample.md",
+	"query": "paragraph[text=Body]"
+}
+```
+
+`mdast/wrap` request 例:
+
+```json
+{
+	"uri": "file:///tmp/sample.md",
+	"query": "heading",
+	"markdown": "> Quote"
+}
+```
+
+`mdast/unwrap` request 例:
+
+```json
+{
+	"uri": "file:///tmp/sample.md",
+	"query": "blockquote"
+}
+```
+
+`mdast/move` request 例:
+
+```json
+{
+	"uri": "file:///tmp/sample.md",
+	"query": "heading[text=One]",
+	"target": "heading[text=Two]",
+	"position": "after"
+}
+```
+
+`mdast/replace` request 例:
+
+```json
+{
+	"uri": "file:///tmp/sample.md",
+	"query": "heading[depth=1]",
+	"markdown": "## Replaced Title"
+}
+```
+
+`mdast/capabilities` response 例:
+
+```json
+{
+	"core": {
+		"queryOperators": ["=", "*=", "^=", "$=", "!=", "~=", ">", ">=", "<", "<="],
+		"genericOperations": ["query", "insert", "delete", "replace", "wrap", "unwrap", "move", "copy"],
+		"customRequests": ["mdast/capabilities", "mdast/query", "mdast/copy", "mdast/tableQuery", "mdast/tableExport", "mdast/tableImport", "mdast/tableUpdateCell", "mdast/tableInsertRow", "mdast/tableDeleteRow", "mdast/tableAddColumn", "mdast/tableDeleteColumn", "mdast/tableSort"]
+	},
+	"plugins": [
+		{
+			"id": "table",
+			"availability": "available"
+		},
+		{
+			"id": "codeBlock",
+			"availability": "available"
+		}
+	]
+}
+```
+
+`mdast/pluginRun` request 例:
+
+```json
+{
+	"uri": "file:///tmp/sample.md",
+	"plugin": "table",
+	"operation": "exportDelimited",
+	"query": "table",
+	"args": {
+		"format": "csv"
+	}
+}
+```
+
+## 検証
+
+```bash
+npm run check
+npm run build
+npm run test
+npm run verify:package
+```
+
+`verify:package` は一時領域へ tarball を作り、runtime entrypoint と compiled test の除外を確認した後、別の一時プロジェクトへ clean install して public API、CLI、LSP stdio を検証します。tarball や install tree はリポジトリ内に残しません。
+
+## API
+
+```ts
+import {
+	copyMarkdown,
+	deleteMarkdown,
+	addTableColumn,
+	deleteTableColumn,
+	deleteTableRow,
+	extractTableModel,
+	csvToMarkdownTable,
+	getCapabilities,
+	getTableCell,
+	insertMarkdown,
+	insertTableRow,
+	listPlugins,
+	moveMarkdown,
+	parseMarkdown,
+	queryAst,
+	replaceMarkdown,
+	resolveTableColumnIndexes,
+	tableToCsv,
+	sortTable,
+	updateTableCell,
+	runPluginOperation,
+	stringifyAst,
+	unwrapMarkdown,
+	wrapMarkdown,
+} from 'mdast-control';
+
+const tree = parseMarkdown('# Title');
+const matches = queryAst(tree, 'heading[depth=1]');
+const updated = insertMarkdown('# Title', 'heading[depth=1]', 'after', 'Body');
+const replaced = replaceMarkdown('# Title', 'heading[text=Title]', '## New Title');
+const removed = deleteMarkdown('# Title\n\nBody', 'paragraph[text=Body]');
+const wrapped = wrapMarkdown('# Title', 'heading', '> Quote');
+const unwrapped = unwrapMarkdown('> Quote', 'blockquote');
+const moved = moveMarkdown('# One\n\n# Two', 'heading[text=One]', 'heading[text=Two]', 'after');
+const copied = copyMarkdown('# One\n\n# Target', 'heading[text=One]', 'heading[text=Target]', 'after');
+const table = extractTableModel('| Name | Status |\n| - | - |\n| A | Open |', 'table');
+const statusColumns = resolveTableColumnIndexes(table, 'Status');
+const firstStatus = getTableCell(table, 0, statusColumns[0]);
+const csv = tableToCsv('| Name | Status |\n| - | - |\n| A | Open |', 'table');
+const importedTable = csvToMarkdownTable('Name,Status\nA,Open');
+const editedCell = updateTableCell('| Name | Status |\n| - | - |\n| A | Open |', 'table', 0, 'Status', 'Closed');
+const sortedTable = sortTable('| Name |\n| - |\n| B |\n| A |', 'table', 'Name', 'asc');
+const capabilities = getCapabilities();
+const plugins = listPlugins();
+const exported = runPluginOperation({
+	plugin: 'table',
+	operation: 'exportDelimited',
+	markdown: '| Name | Value |\n| - | - |\n| A | 1 |\n',
+	query: 'table',
+	args: { format: 'csv' },
+});
+const formattedJson = runPluginOperation({
+	plugin: 'codeBlock',
+	operation: 'formatContent',
+	markdown: '```json\n{"ok":true}\n```\n',
+	query: 'code',
+	args: { format: 'json', indent: 2 },
+});
+console.log(stringifyAst(updated.tree));
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};