@wcstack/lint 1.31.0 → 1.33.0

package/README.ja.md

@@ -26,7 +26,7 @@ npx wcs-validate --errors-only src/**/*.html
 `<wcs-state src="...">` で参照される外部 state（`.json` / `.js` / `.ts`）は HTML ファイルからの相対パスで解決され、パス検証の対象になります。URL・絶対パスは読み込まず、読めないファイルはスキップされ、解決できないパスは warning のままです。なお外部 state が**解決できた**ページには通常の検証面が全て適用されるため、error severity の検出（例: 配列でない値への `for:`）が「これまでパス未解決で沈黙していたビルド」を新たに落とすことがあります。
 
 ```
-wcs-validate [--attr=data-wcs] [--state-tag=wcs-state] [--lang=ja|en] [--errors-only] <file> [<file> ...]
+wcs-validate [--attr=data-wcs] [--state-tag=wcs-state] [--lang=ja|en] [--errors-only] [--strict] <file> [<file> ...]
 ```
 
 | オプション | 説明 |
@@ -35,6 +35,7 @@ wcs-validate [--attr=data-wcs] [--state-tag=wcs-state] [--lang=ja|en] [--errors-
 | `--state-tag=<name>` | state カスタム要素のタグ名（既定 `wcs-state`） |
 | `--lang=ja\|en` | 診断メッセージの言語。未指定時は環境ロケール（`LC_ALL` / `LC_MESSAGES` / `LANG` → OS ロケール）に従う。code / range は言語に依らず不変 |
 | `--errors-only`（別名 `--quiet`） | error severity の行だけ表示。warning / info の件数と exit code は不変 |
+| `--strict` | warning severity の診断でも exit `1` にする。severity 自体は不変（IDE の表示と同じ）で、exit code の閾値だけを error → warning に下げる。summary 行の末尾に `(strict)` が付く。パスの typo（`wcs/binding-path-missing` は warning）で CI を落としたいときに使う — ただし先に `<wcs-state src>` を全て解決可能にしておくこと（解決できない外部 state が残す warning でも落ちるようになる）。`--errors-only` と併用可: 表示は error のみのまま、exit code は warning を反映する |
 
 ## 出力と exit code
 
@@ -49,10 +50,41 @@ app.manifest.json:1:3 error wcs/manifest-broken Broken manifest JSON: ...
 
 | exit code | 意味 |
 |---|---|
-| `0` | error severity の診断なし（warning / info はあってもよい） |
-| `1` | error severity の診断が 1 件以上 |
+| `0` | error severity の診断なし（warning / info はあってもよい）。`--strict` 時は error も warning もなし |
+| `1` | error severity の診断が 1 件以上。`--strict` 時は error または warning が 1 件以上 |
 | `2` | usage エラー、またはファイル読み取り失敗 |
 
+## state の契約を宣言する（`stateSchema`）
+
+契約が無いと、validator が解決できないパスは **warning**（`wcs/binding-path-missing`）に留まります: インラインスクリプトが静的に読めなくても `count` は実行時には存在するかもしれないからです。HTML と同じ（または上の）ディレクトリに `application` sidecar を置くと、同じ typo が **error** になります:
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "application",
+  "manifestExtensions": {
+    "wcstack.application": {
+      "version": 1,
+      "states": {
+        "default": {
+          "stateSchema": {
+            "type": "object",
+            "properties": {
+              "count": { "type": "number" },
+              "users": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+- **発見**: HTML ファイルから上へ辿って最も近い `wcstack.manifest.json` が自動で使われます — コマンドラインに渡す必要はありません。`application` artifact を含む `*.manifest.json` を引数に渡した場合は、その実行全体で発見を置き換えます。VS Code 拡張も同じファイルを発見するので IDE と CLI の結果は一致します。
+- **効果**: `stateSchema` を持つ state では、schema 上に確定的に存在しないバインドパスは `wcs/path-nonexistent`（**error**・exit `1`）、`for:` に非配列は `wcs/path-type-mismatch`（**error**）になります。schema が開いたままの箇所（素の `{}`）は沈黙し、インラインスクリプトのメソッド / getter / `$listKeys` は引き続き存在扱いです。schema の無い state は従来どおりです。
+- **schema の出どころ**: 手で書く（受け付けるのは JSON-Schema サブセット `type / properties / required / items / enum / const / anyOf / $defs / $ref` のみ）か、TypeScript の state ファイルから `wcs-schema`（`@wcstack/typescript`）で生成します。manifest は派生物なので、CI では `wcs-schema check` で同期を保ってください。
+
 ## 生成 → 検証 → 修正ループでの利用
 
 安定した diagnostic code・`source:line:col` range・exit code 契約により、CI のゲートにも AI コード生成フローにもそのまま組み込めます: HTML を生成 → `npx @wcstack/lint --errors-only` → 診断を読んで修正 → exit code `0` になるまで再実行。

package/README.md

@@ -26,7 +26,7 @@ Files ending in `.manifest.json` are validated as sidecar manifests; everything
 External state referenced via `<wcs-state src="...">` (`.json` / `.js` / `.ts`) is resolved relative to the HTML file and included in path validation. URLs and absolute paths are never read, unreadable files are skipped, and unresolved paths stay warnings. Note that once external state *does* resolve, the full validation surface applies to those pages — error-severity findings (e.g. `for:` bound to a non-array) can fail a build that was previously silent because the paths could not be checked.
 
 ```
-wcs-validate [--attr=data-wcs] [--state-tag=wcs-state] [--lang=ja|en] [--errors-only] <file> [<file> ...]
+wcs-validate [--attr=data-wcs] [--state-tag=wcs-state] [--lang=ja|en] [--errors-only] [--strict] <file> [<file> ...]
 ```
 
 | Option | Description |
@@ -35,6 +35,7 @@ wcs-validate [--attr=data-wcs] [--state-tag=wcs-state] [--lang=ja|en] [--errors-
 | `--state-tag=<name>` | State custom-element tag name (default `wcs-state`) |
 | `--lang=ja\|en` | Diagnostic message language. Defaults to the environment locale (`LC_ALL` / `LC_MESSAGES` / `LANG`, then the OS locale); codes and ranges are language-independent |
 | `--errors-only` (alias `--quiet`) | Print only error-severity lines; warning/info counts and the exit code are unchanged |
+| `--strict` | Exit `1` on warning-severity diagnostics too. Severities are unchanged (the IDE shows the same thing); only the exit-code threshold moves from error to warning. The summary line ends with `(strict)`. Use it to fail CI on a path typo (`wcs/binding-path-missing` is a warning) — but resolve every `<wcs-state src>` first (an unresolvable external state leaves warnings that would now fail the build). Combines with `--errors-only`: output stays error-only, the exit code still reflects warnings |
 
 ## Output & exit codes
 
@@ -49,10 +50,41 @@ app.manifest.json:1:3 error wcs/manifest-broken Broken manifest JSON: ...
 
 | Exit code | Meaning |
 |---|---|
-| `0` | No error-severity diagnostics (warnings/info may exist) |
-| `1` | At least one error-severity diagnostic |
+| `0` | No error-severity diagnostics (warnings/info may exist); with `--strict`, no error or warning |
+| `1` | At least one error-severity diagnostic; with `--strict`, at least one error or warning |
 | `2` | Usage error or unreadable file |
 
+## Declaring a state contract (`stateSchema`)
+
+Without a contract, a path the validator cannot resolve is only a **warning** (`wcs/binding-path-missing`): `count` may well exist at runtime even when the inline script cannot be read statically. Put an `application` sidecar next to (or above) the HTML and the same typo becomes an **error**:
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "application",
+  "manifestExtensions": {
+    "wcstack.application": {
+      "version": 1,
+      "states": {
+        "default": {
+          "stateSchema": {
+            "type": "object",
+            "properties": {
+              "count": { "type": "number" },
+              "users": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+- **Discovery**: the nearest `wcstack.manifest.json` walking up from the HTML file is used automatically — nothing to pass on the command line. Passing `*.manifest.json` arguments that contain an `application` artifact replaces discovery for the whole run. The VS Code extension discovers the same file, so IDE and CLI agree.
+- **Effect**: for a state that has a `stateSchema`, a bound path that the schema definitely lacks is `wcs/path-nonexistent` (**error**, exit `1`); `for:` on a non-array is `wcs/path-type-mismatch` (**error**). Paths the schema leaves open (a bare `{}`) stay silent, and methods / getters / `$listKeys` from the inline script still count as existing. States without a schema are unchanged.
+- **Where the schema comes from**: write it by hand (only the JSON-Schema subset `type / properties / required / items / enum / const / anyOf / $defs / $ref` is accepted), or generate it from a TypeScript state file with `wcs-schema` (`@wcstack/typescript`). The manifest is a derived artifact — keep it in sync with `wcs-schema check` in CI.
+
 ## Use in generate–validate–fix loops
 
 Stable diagnostic codes, `source:line:col` ranges, and the exit-code contract make this CLI a drop-in gate for CI and for AI code-generation flows: generate HTML → `npx @wcstack/lint --errors-only` → read the diagnostics, fix, and re-run until exit code `0`.