From b93e88e43f2ce6bfd5c2b8ab8ab06ef1f1148a79 Mon Sep 17 00:00:00 2001 From: hkimw <54717101+hkimw@users.noreply.github.com> Date: Thu, 7 May 2026 12:15:59 +0900 Subject: [PATCH 1/2] feat(config): settings schema with vscode integration --- README.md | 2 + editors/vscode-prototype/README.md | 8 + editors/vscode-prototype/package.json | 39 +++++ editors/vscode-prototype/src/config.mjs | 63 +++++++ .../test/extension-config.test.mjs | 50 +++++- .../test/extension-entrypoint.test.mjs | 23 +++ schema/sv-ide-settings-v0.json | 159 ++++++++++++++++++ 7 files changed, 343 insertions(+), 1 deletion(-) create mode 100644 schema/sv-ide-settings-v0.json diff --git a/README.md b/README.md index 566e284..692ab83 100644 --- a/README.md +++ b/README.md @@ -341,6 +341,8 @@ bash scripts/editor-bridge-smoke.sh The current pre-stable envelope shape is described in [`schema/diagnostics-v0.json`](./schema/diagnostics-v0.json). +The experimental sv-ide settings shape for editor prototypes is described +in [`schema/sv-ide-settings-v0.json`](./schema/sv-ide-settings-v0.json). Handoff notes for the eventual `pccx-lab` and xsim integration paths live in [`docs/HANDOFF.md`](./docs/HANDOFF.md). The initial roadmap for navigation, diagnostics, read-only handoff diff --git a/editors/vscode-prototype/README.md b/editors/vscode-prototype/README.md index 5ebd2d1..0f8df9e 100644 --- a/editors/vscode-prototype/README.md +++ b/editors/vscode-prototype/README.md @@ -166,6 +166,14 @@ The prototype-only settings are: - `pccxSystemVerilog.defaultNavigationRoot`, default `fixtures/modules` - `pccxSystemVerilog.defaultModule`, default `simple_mod` - `pccxSystemVerilog.defaultDeclarationKind`, default `module` +- `pccxSystemVerilog.panel.dataSources`, default `diagnosticsHandoff`, `runtimeReadiness`, `deviceSession`, `localWorkflow` +- `pccxSystemVerilog.panel.refreshIntervalMs`, default `5000` +- `pccxSystemVerilog.logLevel`, default `info` + +The settings contribution in `package.json` mirrors the checked schema in +[`../../schema/sv-ide-settings-v0.json`](../../schema/sv-ide-settings-v0.json) +so VS Code reads the same schema shape for its Settings UI that tests use +as the local settings contract. The default diagnostics publishing command is `pccxSystemVerilog.publishCheckedExampleDiagnostics`. It is experimental diff --git a/editors/vscode-prototype/package.json b/editors/vscode-prototype/package.json index b9e0650..eb62a89 100644 --- a/editors/vscode-prototype/package.json +++ b/editors/vscode-prototype/package.json @@ -236,6 +236,45 @@ ], "default": "module", "description": "Experimental local prototype default declaration kind used by navigation; not a stable API." + }, + "pccxSystemVerilog.panel.dataSources": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "diagnosticsHandoff", + "runtimeReadiness", + "deviceSession", + "localWorkflow" + ] + }, + "uniqueItems": true, + "default": [ + "diagnosticsHandoff", + "runtimeReadiness", + "deviceSession", + "localWorkflow" + ], + "description": "Experimental local prototype status-panel data sources shown by future settings UI surfaces; not a stable API." + }, + "pccxSystemVerilog.panel.refreshIntervalMs": { + "type": "integer", + "default": 5000, + "minimum": 1000, + "maximum": 60000, + "description": "Experimental local prototype status-panel refresh interval in milliseconds for future UI surfaces; not a stable API." + }, + "pccxSystemVerilog.logLevel": { + "type": "string", + "enum": [ + "error", + "warn", + "info", + "debug", + "trace" + ], + "default": "info", + "description": "Experimental local prototype log verbosity for extension-side status and diagnostics surfaces; not a stable API." } } } diff --git a/editors/vscode-prototype/src/config.mjs b/editors/vscode-prototype/src/config.mjs index 4b15ccb..1c3cb5d 100644 --- a/editors/vscode-prototype/src/config.mjs +++ b/editors/vscode-prototype/src/config.mjs @@ -20,6 +20,9 @@ export const CONFIG_KEYS = Object.freeze([ "defaultNavigationRoot", "defaultModule", "defaultDeclarationKind", + "panel.dataSources", + "panel.refreshIntervalMs", + "logLevel", ]); export const FACADE_COMMAND_IDS = Object.freeze([ @@ -68,6 +71,13 @@ export const WORKFLOW_BOUNDARY_BACKENDS = Object.freeze(["none", "pccx-llm-launc export const DECLARATION_KINDS = Object.freeze(["module", "package", "interface", "any"]); export const VALIDATION_RUNNER_MODES = Object.freeze(["disabled", "allowlisted"]); export const VALIDATION_RUNNER_CWD_KINDS = Object.freeze(["repo-root", "workspace"]); +export const PANEL_DATA_SOURCES = Object.freeze([ + "diagnosticsHandoff", + "runtimeReadiness", + "deviceSession", + "localWorkflow", +]); +export const LOG_LEVELS = Object.freeze(["error", "warn", "info", "debug", "trace"]); export const LIVE_WORKSPACE_COMMAND_IDS = Object.freeze([ "pccxSystemVerilog.publishLiveWorkspaceDiagnostics", "pccxSystemVerilog.showLiveWorkspaceNavigation", @@ -100,6 +110,16 @@ const DEFAULT_CONFIG = Object.freeze({ defaultNavigationRoot: "fixtures/modules", defaultModule: "simple_mod", defaultDeclarationKind: "module", + panel: Object.freeze({ + dataSources: Object.freeze([ + "diagnosticsHandoff", + "runtimeReadiness", + "deviceSession", + "localWorkflow", + ]), + refreshIntervalMs: 5000, + }), + logLevel: "info", }); const SHELL_CONTROL_PATTERN = /(?:&&|\|\||;|`|\$\()/; @@ -185,6 +205,30 @@ function integerSetting(rawConfig, key, fallback, options = {}) { return value; } +function enumArraySetting(rawConfig, key, fallback, allowedValues) { + const value = rawConfigValue(rawConfig, key); + if (value == null) { + return [...fallback]; + } + if (!Array.isArray(value)) { + throw new Error(`${CONFIG_SECTION}.${key} must be an array`); + } + + const seen = new Set(); + for (const item of value) { + if (typeof item !== "string" || !allowedValues.includes(item)) { + throw new Error( + `${CONFIG_SECTION}.${key} entries must be one of: ${allowedValues.join(", ")}`, + ); + } + if (seen.has(item)) { + throw new Error(`${CONFIG_SECTION}.${key} entries must be unique`); + } + seen.add(item); + } + return [...value]; +} + export function defaultConfig() { return { ...DEFAULT_CONFIG, @@ -192,6 +236,10 @@ export function defaultConfig() { pccxLab: { ...DEFAULT_CONFIG.pccxLab }, workflowBoundary: { ...DEFAULT_CONFIG.workflowBoundary }, validationRunner: { ...DEFAULT_CONFIG.validationRunner }, + panel: { + dataSources: [...DEFAULT_CONFIG.panel.dataSources], + refreshIntervalMs: DEFAULT_CONFIG.panel.refreshIntervalMs, + }, }; } @@ -267,6 +315,21 @@ export function normalizeConfig(rawConfig = {}) { DEFAULT_CONFIG.defaultDeclarationKind, DECLARATION_KINDS, ), + panel: { + dataSources: enumArraySetting( + rawConfig, + "panel.dataSources", + DEFAULT_CONFIG.panel.dataSources, + PANEL_DATA_SOURCES, + ), + refreshIntervalMs: integerSetting( + rawConfig, + "panel.refreshIntervalMs", + DEFAULT_CONFIG.panel.refreshIntervalMs, + { min: 1000, max: 60000 }, + ), + }, + logLevel: enumSetting(rawConfig, "logLevel", DEFAULT_CONFIG.logLevel, LOG_LEVELS), }; } diff --git a/editors/vscode-prototype/test/extension-config.test.mjs b/editors/vscode-prototype/test/extension-config.test.mjs index 6cabaa3..4858f44 100644 --- a/editors/vscode-prototype/test/extension-config.test.mjs +++ b/editors/vscode-prototype/test/extension-config.test.mjs @@ -10,7 +10,9 @@ import { WORKFLOW_BOUNDARY_BACKENDS, DECLARATION_KINDS, FACADE_COMMAND_IDS, + LOG_LEVELS, MODES, + PANEL_DATA_SOURCES, VALIDATION_RUNNER_CWD_KINDS, VALIDATION_RUNNER_MODES, buildFacadeArgsForCommand, @@ -20,6 +22,7 @@ import { const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../.."); const PACKAGE_JSON = resolve(ROOT, "editors/vscode-prototype/package.json"); +const SETTINGS_SCHEMA_JSON = resolve(ROOT, "schema/sv-ide-settings-v0.json"); const REQUIRED_SETTINGS = new Map([ ["pccxSystemVerilog.mode", { type: "string", default: "checkedExample" }], @@ -38,6 +41,15 @@ const REQUIRED_SETTINGS = new Map([ ["pccxSystemVerilog.defaultNavigationRoot", { type: "string", default: "fixtures/modules" }], ["pccxSystemVerilog.defaultModule", { type: "string", default: "simple_mod" }], ["pccxSystemVerilog.defaultDeclarationKind", { type: "string", default: "module" }], + [ + "pccxSystemVerilog.panel.dataSources", + { + type: "array", + default: ["diagnosticsHandoff", "runtimeReadiness", "deviceSession", "localWorkflow"], + }, + ], + ["pccxSystemVerilog.panel.refreshIntervalMs", { type: "integer", default: 5000 }], + ["pccxSystemVerilog.logLevel", { type: "string", default: "info" }], ]); const LIVE_WORKSPACE_CONFIG = { @@ -49,10 +61,16 @@ async function readPackageJson() { return JSON.parse(await readFile(PACKAGE_JSON, "utf8")); } +async function readSettingsSchema() { + return JSON.parse(await readFile(SETTINGS_SCHEMA_JSON, "utf8")); +} + async function testPackageConfigurationSchema() { const manifest = await readPackageJson(); + const settingsSchema = await readSettingsSchema(); const configuration = manifest.contributes?.configuration; assert.ok(configuration); + assert.deepEqual(configuration, settingsSchema.$defs.vscodeConfiguration); assert.equal(configuration.title, "PCCX SystemVerilog IDE Prototype"); assert.deepEqual( Object.keys(configuration.properties ?? {}).sort(), @@ -64,7 +82,7 @@ async function testPackageConfigurationSchema() { const property = configuration.properties?.[setting]; assert.ok(property, `${setting} missing`); assert.equal(property.type, expected.type); - assert.equal(property.default, expected.default); + assert.deepEqual(property.default, expected.default); assert.match(property.description, /experimental local prototype/i); assert.match(property.description, /not a stable API/i); } @@ -86,6 +104,11 @@ async function testPackageConfigurationSchema() { configuration.properties["pccxSystemVerilog.validationRunner.defaultWorkingDirectory"].enum, VALIDATION_RUNNER_CWD_KINDS, ); + assert.deepEqual( + configuration.properties["pccxSystemVerilog.panel.dataSources"].items.enum, + PANEL_DATA_SOURCES, + ); + assert.deepEqual(configuration.properties["pccxSystemVerilog.logLevel"].enum, LOG_LEVELS); } function testDefaultConfig() { @@ -114,6 +137,11 @@ function testDefaultConfig() { defaultNavigationRoot: "fixtures/modules", defaultModule: "simple_mod", defaultDeclarationKind: "module", + panel: { + dataSources: ["diagnosticsHandoff", "runtimeReadiness", "deviceSession", "localWorkflow"], + refreshIntervalMs: 5000, + }, + logLevel: "info", }); } @@ -170,6 +198,26 @@ function testNormalizeConfigRejectsInvalidSettings() { () => normalizeConfig({ defaultNavigationRoot: "fixtures/modules && whoami" }), /pccxSystemVerilog\.defaultNavigationRoot must not contain shell control syntax/, ); + assert.throws( + () => normalizeConfig({ panel: { dataSources: "diagnosticsHandoff" } }), + /pccxSystemVerilog\.panel\.dataSources must be an array/, + ); + assert.throws( + () => normalizeConfig({ panel: { dataSources: ["diagnosticsHandoff", "unknown"] } }), + /pccxSystemVerilog\.panel\.dataSources entries must be one of: diagnosticsHandoff, runtimeReadiness, deviceSession, localWorkflow/, + ); + assert.throws( + () => normalizeConfig({ panel: { dataSources: ["deviceSession", "deviceSession"] } }), + /pccxSystemVerilog\.panel\.dataSources entries must be unique/, + ); + assert.throws( + () => normalizeConfig({ panel: { refreshIntervalMs: 999 } }), + /pccxSystemVerilog\.panel\.refreshIntervalMs must be between 1000 and 60000/, + ); + assert.throws( + () => normalizeConfig({ logLevel: "verbose" }), + /pccxSystemVerilog\.logLevel must be one of: error, warn, info, debug, trace/, + ); } function testFacadeArgsForKnownCommands() { diff --git a/editors/vscode-prototype/test/extension-entrypoint.test.mjs b/editors/vscode-prototype/test/extension-entrypoint.test.mjs index d6e770b..e77fb5c 100644 --- a/editors/vscode-prototype/test/extension-entrypoint.test.mjs +++ b/editors/vscode-prototype/test/extension-entrypoint.test.mjs @@ -242,6 +242,9 @@ function testResolveCommandRequestUsesVsCodeSettings() { ["defaultNavigationRoot", "configured/modules"], ["defaultModule", "pkg_defs"], ["defaultDeclarationKind", "package"], + ["panel.dataSources", ["deviceSession", "localWorkflow"]], + ["panel.refreshIntervalMs", 15000], + ["logLevel", "debug"], ]); const vscodeApi = { workspace: { @@ -281,6 +284,11 @@ function testResolveCommandRequestUsesVsCodeSettings() { defaultNavigationRoot: "configured/modules", defaultModule: "pkg_defs", defaultDeclarationKind: "package", + panel: { + dataSources: ["deviceSession", "localWorkflow"], + refreshIntervalMs: 15000, + }, + logLevel: "debug", }); assert.deepEqual( resolveCommandRequest("pccxSystemVerilog.runDiagnosticsLive", undefined, vscodeApi), @@ -309,6 +317,11 @@ function testResolveCommandRequestUsesVsCodeSettings() { defaultNavigationRoot: "configured/modules", defaultModule: "pkg_defs", defaultDeclarationKind: "package", + panel: { + dataSources: ["deviceSession", "localWorkflow"], + refreshIntervalMs: 15000, + }, + logLevel: "debug", }, ); assert.deepEqual( @@ -338,6 +351,11 @@ function testResolveCommandRequestUsesVsCodeSettings() { defaultNavigationRoot: "configured/modules", defaultModule: "pkg_defs", defaultDeclarationKind: "package", + panel: { + dataSources: ["deviceSession", "localWorkflow"], + refreshIntervalMs: 15000, + }, + logLevel: "debug", }, ); assert.deepEqual( @@ -367,6 +385,11 @@ function testResolveCommandRequestUsesVsCodeSettings() { defaultNavigationRoot: "configured/modules", defaultModule: "pkg_defs", defaultDeclarationKind: "package", + panel: { + dataSources: ["deviceSession", "localWorkflow"], + refreshIntervalMs: 15000, + }, + logLevel: "debug", }, ); } diff --git a/schema/sv-ide-settings-v0.json b/schema/sv-ide-settings-v0.json new file mode 100644 index 0000000..86cdbda --- /dev/null +++ b/schema/sv-ide-settings-v0.json @@ -0,0 +1,159 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/pccxai/systemverilog-ide/schema/sv-ide-settings-v0.json", + "title": "pccx IDE settings schema (v0, scaffold)", + "description": "Schema source for experimental local sv-ide settings surfaced by editor prototypes. v0 is scaffold-only and not a stable API.", + "$defs": { + "vscodeConfiguration": { + "title": "PCCX SystemVerilog IDE Prototype", + "properties": { + "pccxSystemVerilog.mode": { + "type": "string", + "enum": [ + "checkedExample", + "liveWorkspace" + ], + "default": "checkedExample", + "description": "Experimental local prototype setting selecting checked-example mode or explicit live workspace mode for prototype commands; not a stable API." + }, + "pccxSystemVerilog.liveWorkspace.enabled": { + "type": "boolean", + "default": false, + "description": "Experimental local prototype opt-in gate for live workspace commands; checked-example mode remains the default and this is not a stable API." + }, + "pccxSystemVerilog.pccxLab.command": { + "type": "string", + "default": "pccx_ide_cli", + "description": "Experimental local prototype command-boundary name for the pccx-lab CLI-first backend; no arguments, no direct internals, and not a stable API." + }, + "pccxSystemVerilog.workflowBoundary.enabled": { + "type": "boolean", + "default": false, + "description": "Experimental local prototype opt-in flag reserved for future SystemVerilog workflow boundaries; no provider calls and not a stable API." + }, + "pccxSystemVerilog.workflowBoundary.backend": { + "type": "string", + "enum": [ + "none", + "pccx-llm-launcher", + "mcp" + ], + "default": "none", + "description": "Experimental local prototype workflow boundary backend selector for future controlled tool boundaries; no runtime calls in this scaffold and not a stable API." + }, + "pccxSystemVerilog.validationRunner.enabled": { + "type": "boolean", + "default": false, + "description": "Experimental local prototype opt-in gate for approved validation runner execution; disabled by default and not a stable API." + }, + "pccxSystemVerilog.validationRunner.mode": { + "type": "string", + "enum": [ + "disabled", + "allowlisted" + ], + "default": "disabled", + "description": "Experimental local prototype validation runner mode; allowlisted mode must be explicit and is not a stable API." + }, + "pccxSystemVerilog.validationRunner.defaultWorkingDirectory": { + "type": "string", + "enum": [ + "repo-root", + "workspace" + ], + "default": "repo-root", + "description": "Experimental local prototype working-directory label for approved validation runner commands; fixed allowlisted commands may override it and this is not a stable API." + }, + "pccxSystemVerilog.validationRunner.maxOutputLines": { + "type": "integer", + "default": 120, + "minimum": 1, + "maximum": 500, + "description": "Experimental local prototype maximum stdout/stderr lines retained in approved validation summaries; not a stable API." + }, + "pccxSystemVerilog.validationRunner.timeoutMs": { + "type": "integer", + "default": 30000, + "minimum": 1000, + "maximum": 120000, + "description": "Experimental local prototype timeout in milliseconds for approved validation runner commands; not a stable API." + }, + "pccxSystemVerilog.pythonPath": { + "type": "string", + "default": "python3", + "description": "Experimental local prototype Python executable used by the live CLI prototype path; not a stable API." + }, + "pccxSystemVerilog.defaultSource": { + "type": "string", + "default": "fixtures/missing_endmodule.sv", + "description": "Experimental local prototype workspace-relative default SystemVerilog source used by live diagnostics; not a stable API." + }, + "pccxSystemVerilog.defaultLog": { + "type": "string", + "default": "fixtures/xsim/mixed.log", + "description": "Experimental local prototype workspace-relative default synthetic xsim-style log used by live diagnostics; not a stable API." + }, + "pccxSystemVerilog.defaultNavigationRoot": { + "type": "string", + "default": "fixtures/modules", + "description": "Experimental local prototype workspace-relative source root used by live navigation; not a stable API." + }, + "pccxSystemVerilog.defaultModule": { + "type": "string", + "default": "simple_mod", + "description": "Experimental local prototype default module name used by navigation examples; not a stable API." + }, + "pccxSystemVerilog.defaultDeclarationKind": { + "type": "string", + "enum": [ + "module", + "package", + "interface", + "any" + ], + "default": "module", + "description": "Experimental local prototype default declaration kind used by navigation; not a stable API." + }, + "pccxSystemVerilog.panel.dataSources": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "diagnosticsHandoff", + "runtimeReadiness", + "deviceSession", + "localWorkflow" + ] + }, + "uniqueItems": true, + "default": [ + "diagnosticsHandoff", + "runtimeReadiness", + "deviceSession", + "localWorkflow" + ], + "description": "Experimental local prototype status-panel data sources shown by future settings UI surfaces; not a stable API." + }, + "pccxSystemVerilog.panel.refreshIntervalMs": { + "type": "integer", + "default": 5000, + "minimum": 1000, + "maximum": 60000, + "description": "Experimental local prototype status-panel refresh interval in milliseconds for future UI surfaces; not a stable API." + }, + "pccxSystemVerilog.logLevel": { + "type": "string", + "enum": [ + "error", + "warn", + "info", + "debug", + "trace" + ], + "default": "info", + "description": "Experimental local prototype log verbosity for extension-side status and diagnostics surfaces; not a stable API." + } + } + } + } +} From 37344ce7ab1d8b4a5873c4547bfd0ea3b41c494f Mon Sep 17 00:00:00 2001 From: Hyunwoo Kim Date: Thu, 21 May 2026 02:53:40 +0900 Subject: [PATCH 2/2] docs(settings): settings reference (#136) --- editors/vscode-prototype/README.md | 3 + .../docs/settings-reference.md | 197 ++++++++++++++++++ .../test/extension-config.test.mjs | 23 ++ 3 files changed, 223 insertions(+) create mode 100644 editors/vscode-prototype/docs/settings-reference.md diff --git a/editors/vscode-prototype/README.md b/editors/vscode-prototype/README.md index 0f8df9e..7a1267f 100644 --- a/editors/vscode-prototype/README.md +++ b/editors/vscode-prototype/README.md @@ -170,6 +170,9 @@ The prototype-only settings are: - `pccxSystemVerilog.panel.refreshIntervalMs`, default `5000` - `pccxSystemVerilog.logLevel`, default `info` +A setting-by-setting reference is maintained in +[`docs/settings-reference.md`](./docs/settings-reference.md). + The settings contribution in `package.json` mirrors the checked schema in [`../../schema/sv-ide-settings-v0.json`](../../schema/sv-ide-settings-v0.json) so VS Code reads the same schema shape for its Settings UI that tests use diff --git a/editors/vscode-prototype/docs/settings-reference.md b/editors/vscode-prototype/docs/settings-reference.md new file mode 100644 index 0000000..696af4e --- /dev/null +++ b/editors/vscode-prototype/docs/settings-reference.md @@ -0,0 +1,197 @@ +# Settings Reference + +## Status + +These settings belong to the experimental local VS Code prototype. They are +not a stable API, not a stable ABI, not a marketplace contract, and not an +LSP contract. The source of truth for the setting shape is +[`../../../schema/sv-ide-settings-v0.json`](../../../schema/sv-ide-settings-v0.json); +the VS Code package manifest mirrors that schema. + +Checked-example mode remains the default. Live workspace commands require +both `pccxSystemVerilog.mode=liveWorkspace` and +`pccxSystemVerilog.liveWorkspace.enabled=true`. + +## Settings + +### `pccxSystemVerilog.mode` + +- Type: `string` +- Default: `checkedExample` +- Allowed values: `checkedExample`, `liveWorkspace` +- Purpose: selects whether prototype commands use checked examples or the + explicit live workspace command shape. +- Notes: `liveWorkspace` does not enable live commands by itself; the + live-workspace opt-in flag must also be enabled. + +### `pccxSystemVerilog.liveWorkspace.enabled` + +- Type: `boolean` +- Default: `false` +- Purpose: opt-in gate for live workspace commands. +- Notes: checked-example behavior remains the default. Live commands are + blocked unless this is `true` and `pccxSystemVerilog.mode` is + `liveWorkspace`. + +### `pccxSystemVerilog.pccxLab.command` + +- Type: `string` +- Default: `pccx_ide_cli` +- Purpose: command-boundary name for the future pccx-lab CLI-first backend + status surface. +- Notes: the current status command reports this value but does not execute + pccx-lab. The value must be a single command name or path without + arguments, newlines, null bytes, or shell control syntax. + +### `pccxSystemVerilog.workflowBoundary.enabled` + +- Type: `boolean` +- Default: `false` +- Purpose: opt-in flag for workflow boundary status and context-bundle + surfaces. +- Notes: disabled means the boundary reports a disabled status. Enabling this + setting does not add provider calls, runtime calls, MCP, LSP, write-file + behavior, or direct execution. + +### `pccxSystemVerilog.workflowBoundary.backend` + +- Type: `string` +- Default: `none` +- Allowed values: `none`, `pccx-llm-launcher`, `mcp` +- Purpose: labels the future controlled workflow backend candidate. +- Notes: `none` reports not configured when the workflow boundary is enabled. + Non-`none` values report a proposal-only boundary in this scaffold; they do + not start a launcher, provider, runtime, or MCP server. + +### `pccxSystemVerilog.validationRunner.enabled` + +- Type: `boolean` +- Default: `false` +- Purpose: opt-in gate for approved validation runner execution. +- Notes: execution remains blocked unless this is `true` and + `pccxSystemVerilog.validationRunner.mode` is `allowlisted`. + +### `pccxSystemVerilog.validationRunner.mode` + +- Type: `string` +- Default: `disabled` +- Allowed values: `disabled`, `allowlisted` +- Purpose: selects the approved validation runner mode. +- Notes: `allowlisted` must be explicit and still only accepts known proposal + IDs. The runner does not accept raw shell command strings. + +### `pccxSystemVerilog.validationRunner.defaultWorkingDirectory` + +- Type: `string` +- Default: `repo-root` +- Allowed values: `repo-root`, `workspace` +- Purpose: default working-directory policy for approved validation runner + commands. +- Notes: allowlisted command proposals may specify their own working-directory + policy. Unknown policy values fall back to the repo root after schema/config + validation would normally reject them. + +### `pccxSystemVerilog.validationRunner.maxOutputLines` + +- Type: `integer` +- Default: `120` +- Range: `1` to `500` +- Purpose: maximum stdout and stderr lines retained in approved validation + summaries. +- Notes: this controls bounded summaries only; full logs are not persisted by + the in-memory validation-result cache. + +### `pccxSystemVerilog.validationRunner.timeoutMs` + +- Type: `integer` +- Default: `30000` +- Range: `1000` to `120000` +- Purpose: timeout in milliseconds for approved validation runner commands. +- Notes: timed-out commands return bounded structured results through the + validation runner surface. + +### `pccxSystemVerilog.pythonPath` + +- Type: `string` +- Default: `python3` +- Purpose: Python executable used by the live CLI prototype path. +- Notes: the value must be a non-empty single-line string without null bytes, + newlines, or shell control syntax. + +### `pccxSystemVerilog.defaultSource` + +- Type: `string` +- Default: `fixtures/missing_endmodule.sv` +- Purpose: workspace-relative default SystemVerilog source for live + diagnostics. +- Notes: live diagnostics map this value to the facade argument + `--from-check `. The value must be a non-empty single-line + string without null bytes, newlines, or shell control syntax. + +### `pccxSystemVerilog.defaultLog` + +- Type: `string` +- Default: `fixtures/xsim/mixed.log` +- Purpose: workspace-relative default synthetic xsim-style log for prototype + diagnostics surfaces. +- Notes: the setting is part of the normalized configuration and context + shape. It is reserved for known log-oriented prototype flows; it does not + enable arbitrary log scanning. + +### `pccxSystemVerilog.defaultNavigationRoot` + +- Type: `string` +- Default: `fixtures/modules` +- Purpose: workspace-relative source root used by live navigation. +- Notes: live navigation maps this value to the facade argument + `--locate --kind `. + The value must be a non-empty single-line string without null bytes, + newlines, or shell control syntax. + +### `pccxSystemVerilog.defaultModule` + +- Type: `string` +- Default: `simple_mod` +- Purpose: default declaration name used by live navigation examples. +- Notes: despite the setting name, this is the lookup name supplied to the + facade locate flow and is paired with `defaultDeclarationKind`. + +### `pccxSystemVerilog.defaultDeclarationKind` + +- Type: `string` +- Default: `module` +- Allowed values: `module`, `package`, `interface`, `any` +- Purpose: declaration kind used by live navigation. +- Notes: this is passed to the facade locate flow as `--kind`. + +### `pccxSystemVerilog.panel.dataSources` + +- Type: `array` of `string` +- Default: `diagnosticsHandoff`, `runtimeReadiness`, `deviceSession`, + `localWorkflow` +- Allowed values: `diagnosticsHandoff`, `runtimeReadiness`, `deviceSession`, + `localWorkflow` +- Purpose: selected status-panel data sources for future settings UI + surfaces. +- Notes: entries must be unique. This setting is a prototype UI data-source + selector and does not enable provider calls, runtime calls, or external + services. + +### `pccxSystemVerilog.panel.refreshIntervalMs` + +- Type: `integer` +- Default: `5000` +- Range: `1000` to `60000` +- Purpose: status-panel refresh interval in milliseconds for future UI + surfaces. +- Notes: this is reserved for UI refresh behavior and does not add background + workspace scanning in the current scaffold. + +### `pccxSystemVerilog.logLevel` + +- Type: `string` +- Default: `info` +- Allowed values: `error`, `warn`, `info`, `debug`, `trace` +- Purpose: extension-side status and diagnostics verbosity label. +- Notes: this is normalized with the rest of the prototype configuration and + remains local to extension-side status surfaces. diff --git a/editors/vscode-prototype/test/extension-config.test.mjs b/editors/vscode-prototype/test/extension-config.test.mjs index 4858f44..f5e9ef9 100644 --- a/editors/vscode-prototype/test/extension-config.test.mjs +++ b/editors/vscode-prototype/test/extension-config.test.mjs @@ -23,6 +23,10 @@ import { const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../.."); const PACKAGE_JSON = resolve(ROOT, "editors/vscode-prototype/package.json"); const SETTINGS_SCHEMA_JSON = resolve(ROOT, "schema/sv-ide-settings-v0.json"); +const SETTINGS_REFERENCE_MD = resolve( + ROOT, + "editors/vscode-prototype/docs/settings-reference.md", +); const REQUIRED_SETTINGS = new Map([ ["pccxSystemVerilog.mode", { type: "string", default: "checkedExample" }], @@ -111,6 +115,24 @@ async function testPackageConfigurationSchema() { assert.deepEqual(configuration.properties["pccxSystemVerilog.logLevel"].enum, LOG_LEVELS); } +async function testSettingsReferenceDocumentsSchema() { + const settingsSchema = await readSettingsSchema(); + const settingsReference = await readFile(SETTINGS_REFERENCE_MD, "utf8"); + const schemaSettings = Object.keys(settingsSchema.$defs.vscodeConfiguration.properties ?? {}); + + assert.match(settingsReference, /# Settings Reference/); + assert.match(settingsReference, /not a stable API/i); + assert.match(settingsReference, /sv-ide-settings-v0\.json/); + + for (const setting of schemaSettings) { + assert.match( + settingsReference, + new RegExp(`^### \`${setting.replaceAll(".", "\\.")}\`$`, "m"), + `${setting} missing from settings reference`, + ); + } +} + function testDefaultConfig() { assert.deepEqual(defaultConfig(), { mode: "checkedExample", @@ -321,6 +343,7 @@ function testUnknownCommandAndShellShape() { } await testPackageConfigurationSchema(); +await testSettingsReferenceDocumentsSchema(); testDefaultConfig(); testNormalizeConfigRejectsInvalidSettings(); testFacadeArgsForKnownCommands();