Skip to content

Commit 5cbb66e

Browse files
svelderrainruizGitHub Copilot
svelderrainruiz
and
GitHub Copilot
authored
#894 Add offline real-history corpus harness (#898)
* #894 Add offline real-history corpus harness and portfolio sync * #894 Fix bridge capture schema and NDJSON logging --------- Co-authored-by: GitHub Copilot <copilot@users.noreply.github.com>
1 parent 9b3a1b1 commit 5cbb66e

13 files changed

Lines changed: 2023 additions & 25 deletions

‎docs/documentation-manifest.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"$schema": "./schemas/documentation-manifest-v1.schema.json",
33
"schema": "documentation-manifest-v1",
44
"version": "1.0.0",
5-
"updated": "2026-03-06T01:15:00Z",
5+
"updated": "2026-03-08T00:00:00Z",
66
"entries": [
77
{
88
"name": "Root Playbooks",
@@ -78,6 +78,7 @@
7878
"docs/knowledgebase/FEATURE_BRANCH_POLICY.md",
7979
"docs/knowledgebase/LVCompare-Git-CLI-Guide_Windows-LabVIEW-2025Q3.md",
8080
"docs/knowledgebase/CrossRepo-VIHistory.md",
81+
"docs/knowledgebase/Offline-RealHistory-Corpus.md",
8182
"docs/knowledgebase/DOCKER_TOOLS_PARITY.md",
8283
"docs/LABVIEW_GATING.md",
8384
"docs/LINT_BACKLOG_PLAN.md",

‎docs/knowledgebase/CrossRepo-VIHistory.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,14 @@ the recorded metadata bucket counts (2 entries in the `metadata` bucket) stay
113113
in sync with the documentation. Use the fixture as a template when capturing
114114
new cross-repo runs.
115115

116+
## Offline corpus harness
117+
118+
For the seeded offline real-history corpus path added under issue `#894`, use
119+
[`Offline-RealHistory-Corpus.md`](./Offline-RealHistory-Corpus.md). That flow
120+
wraps `Compare-VIHistory` with the NI Windows container bridge and writes
121+
generated evidence under `tests/results/offline-real-history/` instead of
122+
committing bulky raw reports.
123+
116124
## Observations / gaps
117125

118126
- With `CompareVI.Tools` we can reuse `Compare-VIHistory` and

‎docs/knowledgebase/Offline-RealHistory-Corpus.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
<!-- markdownlint-disable-next-line MD041 -->
2+
# Offline Real-History Corpus
3+
4+
This note defines the phase-1 contract for the offline real-history corpus
5+
seeded by issue `#894`.
6+
7+
## Checked-in inputs
8+
9+
- Target catalog: `fixtures/real-history/offline-corpus.targets.json`
10+
- Catalog schema:
11+
`docs/schemas/offline-real-history-corpus-targets-v1.schema.json`
12+
- Run envelope schema:
13+
`docs/schemas/offline-real-history-corpus-run-v1.schema.json`
14+
- Seed target: `icon-editor-settings-init`
15+
- repo slug: `svelderrainruiz/labview-icon-editor`
16+
- target VI:
17+
`resource/plugins/NIIconEditor/Miscellaneous/Settings Init.vi`
18+
- requested modes: `default`, `attributes`
19+
20+
The checked-in catalog is intentionally small. It captures the seed slice and
21+
the storage policy, not bulky raw reports.
22+
23+
## Generated outputs
24+
25+
Offline corpus runs write under:
26+
27+
- `tests/results/offline-real-history/<target-id>/<run-id>/`
28+
29+
Each run directory contains:
30+
31+
- `offline-real-history-run.json`
32+
- schema: `vi-history/offline-real-history-run@v1`
33+
- records repo/ref selection, requested and executed modes, compare policy,
34+
NI image identity, LabVIEW version hint, CLI path, and output paths
35+
- `history/`
36+
- aggregate `Compare-VIHistory` manifest
37+
- per-mode manifests
38+
- rendered `history-report.md` and `history-report.html`
39+
- translated `lvcompare-capture.json` files
40+
- raw `ni-windows-container-capture.json` files
41+
42+
Raw artifacts stay local under `tests/results/`; they are not committed to git.
43+
44+
## Harness
45+
46+
Entry point:
47+
48+
```powershell
49+
node tools/npm/run-script.mjs history:corpus:offline -- --PlanOnly
50+
```
51+
52+
The harness:
53+
54+
1. Loads the checked-in target catalog.
55+
2. Resolves a local external repo path from `-RepoPath` or the catalog's local
56+
path hints.
57+
3. Reuses `Compare-VIHistory.ps1`.
58+
4. Routes pair execution through
59+
`tools/Invoke-NIWindowsContainerCompareBridge.ps1`.
60+
5. Emits the run envelope plus standard VI history outputs.
61+
62+
The bridge calls `tools/Run-NIWindowsContainerCompare.ps1` so history capture
63+
uses the existing NI Windows container lane instead of a parallel compare path.
64+
65+
## Local refresh flow
66+
67+
Prerequisites:
68+
69+
- a local checkout of the external repo already exists
70+
- the NI Windows image already exists locally
71+
- Docker Desktop is running in Windows container mode
72+
73+
Plan without running the corpus:
74+
75+
```powershell
76+
node tools/npm/run-script.mjs history:corpus:offline -- --PlanOnly --RunId plan-only
77+
```
78+
79+
Run the seeded slice against an existing checkout:
80+
81+
```powershell
82+
node tools/npm/run-script.mjs history:corpus:offline -- `
83+
--TargetId icon-editor-settings-init `
84+
--RepoPath ..\labview-icon-editor `
85+
--RunId local-smoke
86+
```
87+
88+
Useful overrides:
89+
90+
- `-WindowsImage <tag>` to pin a different local NI Windows image
91+
- `-WindowsLabVIEWPath <path>` to record a different in-container LabVIEW path
92+
- `-WindowsCliPath <path>` to record a different in-container CLI path
93+
- `-ComparePolicy <policy>` to annotate the capture envelope
94+
- `-CompareTimeoutSeconds <n>` to raise or lower pair timeout
95+
96+
The harness does not clone or pull the external repository. Refresh is
97+
explicitly local/offline once the repo and image already exist on disk.
98+
99+
## Storage boundary
100+
101+
- Commit: the seed catalog and schemas
102+
- Keep local-only: raw HTML/XML/text reports, translated capture JSON, raw
103+
NI-container capture JSON, stdout/stderr, and per-run history bundles
104+
105+
That boundary keeps the repository deterministic while still preserving real
106+
execution evidence on the operator machine.

‎docs/schemas/offline-real-history-corpus-run-v1.schema.json‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://labview-community-ci-cd.github.io/compare-vi-cli-action/schemas/offline-real-history-corpus-run-v1.schema.json",
4+
"title": "Offline Real-History Corpus Run v1",
5+
"description": "Generated capture envelope for an offline real-history corpus run.",
6+
"type": "object",
7+
"required": [
8+
"schema",
9+
"generatedAt",
10+
"status",
11+
"planOnly",
12+
"runId",
13+
"target",
14+
"source",
15+
"capture",
16+
"container",
17+
"outputs",
18+
"storage"
19+
],
20+
"properties": {
21+
"schema": {
22+
"const": "vi-history/offline-real-history-run@v1"
23+
},
24+
"generatedAt": {
25+
"type": "string",
26+
"format": "date-time"
27+
},
28+
"status": {
29+
"enum": [
30+
"planned",
31+
"captured",
32+
"failed"
33+
]
34+
},
35+
"planOnly": {
36+
"type": "boolean"
37+
},
38+
"runId": {
39+
"type": "string",
40+
"minLength": 1
41+
},
42+
"message": {
43+
"type": [
44+
"string",
45+
"null"
46+
]
47+
},
48+
"target": {
49+
"type": "object",
50+
"required": [
51+
"id",
52+
"label",
53+
"targetPath",
54+
"requestedModes",
55+
"executedModes",
56+
"maxPairs",
57+
"reportFormat"
58+
],
59+
"properties": {
60+
"id": { "type": "string" },
61+
"label": { "type": "string" },
62+
"targetPath": { "type": "string" },
63+
"requestedModes": { "$ref": "#/$defs/stringArray" },
64+
"executedModes": { "$ref": "#/$defs/stringArray" },
65+
"maxPairs": {
66+
"type": "integer",
67+
"minimum": 1
68+
},
69+
"reportFormat": { "type": "string" },
70+
"notes": { "$ref": "#/$defs/stringArray" }
71+
},
72+
"additionalProperties": false
73+
},
74+
"source": {
75+
"type": "object",
76+
"required": [
77+
"repoSlug",
78+
"repoPath",
79+
"requestedStartRef",
80+
"requestedEndRef",
81+
"resolvedStartRef"
82+
],
83+
"properties": {
84+
"repoSlug": { "type": "string" },
85+
"repoPath": {
86+
"type": [
87+
"string",
88+
"null"
89+
]
90+
},
91+
"requestedStartRef": { "type": "string" },
92+
"requestedEndRef": {
93+
"type": [
94+
"string",
95+
"null"
96+
]
97+
},
98+
"resolvedStartRef": {
99+
"type": [
100+
"string",
101+
"null"
102+
]
103+
},
104+
"resolvedHeadRef": {
105+
"type": [
106+
"string",
107+
"null"
108+
]
109+
}
110+
},
111+
"additionalProperties": false
112+
},
113+
"capture": {
114+
"type": "object",
115+
"required": [
116+
"comparePolicy",
117+
"compareTimeoutSeconds",
118+
"invokeScriptPath"
119+
],
120+
"properties": {
121+
"comparePolicy": { "type": "string" },
122+
"compareTimeoutSeconds": {
123+
"type": [
124+
"integer",
125+
"null"
126+
],
127+
"minimum": 1
128+
},
129+
"invokeScriptPath": { "type": "string" },
130+
"historySuiteStatus": {
131+
"type": [
132+
"string",
133+
"null"
134+
]
135+
},
136+
"historySuiteStats": {
137+
"type": [
138+
"object",
139+
"null"
140+
]
141+
}
142+
},
143+
"additionalProperties": false
144+
},
145+
"container": {
146+
"type": "object",
147+
"required": [
148+
"lane",
149+
"image",
150+
"labviewPath",
151+
"labviewVersion",
152+
"cliPath",
153+
"runnerScriptPath"
154+
],
155+
"properties": {
156+
"lane": {
157+
"const": "windows-ni"
158+
},
159+
"image": { "type": "string" },
160+
"labviewPath": { "type": "string" },
161+
"labviewVersion": {
162+
"type": [
163+
"string",
164+
"null"
165+
]
166+
},
167+
"cliPath": { "type": "string" },
168+
"runnerScriptPath": { "type": "string" }
169+
},
170+
"additionalProperties": false
171+
},
172+
"outputs": {
173+
"type": "object",
174+
"required": [
175+
"runRoot",
176+
"historyResultsDir",
177+
"aggregateManifestPath",
178+
"historyReportMarkdownPath",
179+
"historyReportHtmlPath",
180+
"modeManifestPaths",
181+
"lvcompareCapturePaths",
182+
"niContainerCapturePaths"
183+
],
184+
"properties": {
185+
"runRoot": { "type": "string" },
186+
"historyResultsDir": { "type": "string" },
187+
"aggregateManifestPath": {
188+
"type": [
189+
"string",
190+
"null"
191+
]
192+
},
193+
"historyReportMarkdownPath": {
194+
"type": [
195+
"string",
196+
"null"
197+
]
198+
},
199+
"historyReportHtmlPath": {
200+
"type": [
201+
"string",
202+
"null"
203+
]
204+
},
205+
"modeManifestPaths": { "$ref": "#/$defs/stringArray" },
206+
"lvcompareCapturePaths": { "$ref": "#/$defs/stringArray" },
207+
"niContainerCapturePaths": { "$ref": "#/$defs/stringArray" }
208+
},
209+
"additionalProperties": false
210+
},
211+
"storage": {
212+
"type": "object",
213+
"required": [
214+
"catalogPath",
215+
"generatedRoot",
216+
"rawArtifactsInGit"
217+
],
218+
"properties": {
219+
"catalogPath": { "type": "string" },
220+
"generatedRoot": { "type": "string" },
221+
"rawArtifactsInGit": {
222+
"const": false
223+
}
224+
},
225+
"additionalProperties": false
226+
}
227+
},
228+
"$defs": {
229+
"stringArray": {
230+
"type": "array",
231+
"items": {
232+
"type": "string"
233+
}
234+
}
235+
},
236+
"additionalProperties": false
237+
}

0 commit comments

Comments
 (0)