@spfx-fast/playwright 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,6 +4,8 @@ Playwright helpers for any SPFx project. This dev tool stays out of the web-part
4
4
 
5
5
  It adds agent-friendly recipes, same-origin navigation, and authenticated runs with reviewable evidence. Playwright provides the test runner, locators, recorder, traces, and screenshots.
6
6
 
7
+ When [`@spfx-fast/ide`](https://www.npmjs.com/package/@spfx-fast/ide) is installed, `spfx-ide e2e` routes to this package's CLI. The router does not install the optional Playwright peers or browser runtime; follow the install and browser setup below before running E2E.
8
+
7
9
  ## Install in an SPFx project
8
10
 
9
11
  ```sh
@@ -12,22 +14,22 @@ npm install --save-dev @spfx-fast/playwright @playwright/test playwright
12
14
 
13
15
  SPFx is not a dependency. Production web parts do not import this package by default.
14
16
 
15
- Scaffold a serial Playwright setup with a starter recipe, generated test spec, agent instructions, screenshots, traces, and an ignored auth-state folder:
17
+ Scaffold a serial Playwright setup with a starter recipe, generated test spec, and agent instructions:
16
18
 
17
19
  ```sh
18
20
  npx spfx-fast-playwright init
19
21
  ```
20
22
 
21
- The config uses storage state only when `SPFX_STORAGE_STATE` is set. Keep it in an ignored folder; never commit it. The scaffold adds `SPFX-PLAYWRIGHT.md` and links it from `AGENTS.md` without replacing existing instructions.
23
+ The config uses storage state when `SPFX_STORAGE_STATE` is set. Point it at the shared per-tenant file such as `~/.playwright-auth/workswithagents.json`; keep state out of the project and never commit it. The scaffold adds `SPFX-PLAYWRIGHT.md` and links it from `AGENTS.md` without replacing existing instructions.
22
24
 
23
25
  ## Record a test with the Playwright recorder
24
26
 
25
- Use a dedicated signed-in test profile. The command calls Playwright Codegen and writes an ordinary Playwright spec:
27
+ Reuse the Workbench shared state. The command calls Playwright Codegen and writes an ordinary Playwright spec:
26
28
 
27
29
  ```sh
28
30
  npx spfx-fast-playwright record \
29
31
  --url "$SPFX_BASE_URL" \
30
- --profile-dir "$SPFX_TEST_PROFILE" \
32
+ --storage-state "$HOME/.playwright-auth/workswithagents.json" \
31
33
  --out tests/e2e/home-page.spec.ts
32
34
  ```
33
35
 
@@ -47,14 +49,42 @@ npx spfx-fast-playwright generate tests/e2e/sharepoint-smoke.recipe.json --out t
47
49
  The output is a normal Playwright Test spec. Run it with the project's `SPFX_BASE_URL` and `storageState`:
48
50
 
49
51
  ```sh
50
- SPFX_BASE_URL="https://tenant.sharepoint.com/sites/your-site" npx playwright test
52
+ SPFX_BASE_URL="https://tenant.sharepoint.com/sites/your-site" \
53
+ SPFX_STORAGE_STATE="$HOME/.playwright-auth/workswithagents.json" npx playwright test
51
54
  ```
52
55
 
53
56
  Keep state files out of source control. They contain impersonation-capable session data. Use a dedicated least-privilege account and test site.
54
57
 
55
- ## Run a recipe with a persistent authenticated browser profile
58
+ ## Capture and contribute a SharePoint UI discovery
59
+
60
+ Capture a reusable finding and runnable recipe as a local draft:
61
+
62
+ ```sh
63
+ npx spfx-fast-playwright learn init
64
+ # Edit test-results/spfx-fast-playwright/learning-draft.json.
65
+ npx spfx-fast-playwright learn validate test-results/spfx-fast-playwright/learning-draft.json
66
+ ```
67
+
68
+ The default stays with Playwright artifacts under `test-results/`; `learn init` adds that file to `.gitignore` when the directory is not already ignored. The strict format has no author or tenant fields. Validation rejects common emails, GUIDs, tenant domains, site-specific paths, and credential-like strings; it does not upload anything. It cannot guarantee anonymity, detect every identifier, or inspect screenshots and other attachments. Keep drafts local until you have reviewed all values and evidence. Never include tenant URLs, IDs, user names, list content, browser profiles, auth state, screenshots, or traces in a shared learning.
69
+
70
+ Promote verified findings to the smallest durable artifact: a recipe in `examples/`, a pattern in the agent guide, or an API/scenario note in core docs. Record applicability and validation limits; do not present tenant-specific behavior as universal. The [learning index](https://github.com/vystartasv/spfx-fast/blob/main/docs/LEARNINGS.md) points agents to existing guidance.
56
71
 
57
- This path is useful when a team already has a signed-in Playwright profile and does not want to export its storage state:
72
+ To contribute the browser discovery through the shared knowledge flow, convert and review the draft with `npx --yes @spfx-fast/knowledge learn import-playwright <draft.json>`, then run `learn validate` and `learn patch`. The converter maps fields mechanically; verify the result before sharing.
73
+
74
+ ## Run a recipe with shared storage state
75
+
76
+ ```sh
77
+ npx spfx-fast-playwright run tests/e2e/sharepoint-smoke.recipe.json \
78
+ --base-url "$SPFX_BASE_URL" \
79
+ --storage-state "$HOME/.playwright-auth/workswithagents.json" \
80
+ --artifacts test-results/sharepoint-smoke
81
+ ```
82
+
83
+ Runs headless and saves requested screenshots, a trace, and `summary.json`. Set `SPFX_STORAGE_STATE` instead of passing `--storage-state` to share the path across commands. State is loaded into a normal browser context and is not rewritten. Use `--headed` to debug.
84
+
85
+ ## Legacy persistent profile mode
86
+
87
+ Existing teams can continue using a signed-in Playwright profile:
58
88
 
59
89
  ```sh
60
90
  npx spfx-fast-playwright run tests/e2e/sharepoint-smoke.recipe.json \
@@ -63,7 +93,7 @@ npx spfx-fast-playwright run tests/e2e/sharepoint-smoke.recipe.json \
63
93
  --artifacts test-results/sharepoint-smoke
64
94
  ```
65
95
 
66
- Runs headless, enforces the origin, and saves requested screenshots, a trace, and `summary.json`. Use `--headed` to debug. The command locks the profile and releases it after browser exit. It does not sign in, inspect cookies, or copy/remove profile files.
96
+ Runs headless, enforces the origin, and saves requested screenshots, a trace, and `summary.json`. Use `--headed` to debug. The command locks the profile and releases it after browser exit. It does not sign in, inspect cookies, or copy/remove profile files. The Workbench IDE workflow uses storage-state JSON instead.
67
97
 
68
98
  Use `--fast` during fix loops: assertions remain, successful screenshots/traces are skipped, and failures capture a screenshot. Run once without it after fixes. Use one job per profile; close any manually opened Chrome first.
69
99
 
@@ -100,7 +130,7 @@ cp node_modules/@spfx-fast/playwright/examples/tenant-crud-validation.recipe.jso
100
130
  npx spfx-fast-playwright validate tests/e2e/tenant-crud-validation.recipe.json
101
131
  npx spfx-fast-playwright run tests/e2e/tenant-crud-validation.recipe.json \
102
132
  --base-url "$SPFX_BASE_URL" \
103
- --profile-dir "$SPFX_TEST_PROFILE" \
133
+ --storage-state "$HOME/.playwright-auth/workswithagents.json" \
104
134
  --artifacts test-results/tenant-crud
105
135
  ```
106
136
 
@@ -121,4 +151,4 @@ For a full workflow with profile, SharePoint page, image, and OCR guidance, read
121
151
 
122
152
  ## Package status
123
153
 
124
- This is the `0.1.1` companion package. It is framework-agnostic across SPFx projects and ships independently from `@spfx-fast/core`.
154
+ This checkout prepares `0.1.3`; published `0.1.2` remains unchanged. It is framework-agnostic across SPFx projects and ships independently from `@spfx-fast/core`.
@@ -6,12 +6,12 @@ For any SPFx project. This dev tool does not require `@spfx-fast/core`.
6
6
 
7
7
  - Reuse the project's Playwright version, config, test account, and site.
8
8
  - Set `SPFX_BASE_URL` to the SharePoint **web URL**. Set `SPFX_STORAGE_STATE` only to a local ignored file when that project already uses saved state.
9
- - Never automate sign-in, inspect cookies, copy a daily profile, or commit auth state.
10
- - Run one job per persistent profile. `run` and `record` lock it; close manually opened browsers first.
9
+ - Reuse the shared per-tenant state at `~/.playwright-auth/<tenant>.json` with `--storage-state` or `SPFX_STORAGE_STATE`. Never automate sign-in, inspect cookies, or commit state.
10
+ - Legacy `--profile-dir` mode is supported for existing projects and locks the profile; close manually opened browsers first.
11
11
 
12
12
  ## Generate and run
13
13
 
14
- - Record with `spfx-fast-playwright record`; review selectors and add user-visible assertions.
14
+ - Record with `spfx-fast-playwright record --url "$SPFX_BASE_URL" --storage-state "$HOME/.playwright-auth/$SPFX_TENANT.json" --out tests/e2e/recorded.spec.ts`; set `SPFX_TENANT` to the tenant key and review selectors and add user-visible assertions.
15
15
  - For repeatable checks, validate a JSON recipe, then `generate` or `run` it.
16
16
  - Prefer `testId` locators for stable targeting when the app exposes `data-testid`. Use role/label locators when checking accessible interaction, especially for form controls. Use `assertText` to verify user-visible content on the selected element; use text locators only when the text itself is the only useful target. Always use explicit waits; do not use generic `networkidle` on SharePoint.
17
17
  - Use `run --fast` during fixes, then run once without it.
@@ -29,4 +29,5 @@ For any SPFx project. This dev tool does not require `@spfx-fast/core`.
29
29
  - Screenshots show appearance only. Assert API or saved/published state separately.
30
30
  - After three failed attempts to reach a control, stop and report the blocker with evidence.
31
31
  - Check artifacts for tenant/personal data before sharing.
32
+ - When a task reveals a reusable UI behavior, capture it with `learn init`, validate it with `learn validate`, and recommend a recipe or guide change. Drafts stay local; validation catches common identifiers but cannot guarantee anonymity. Never attach screenshots, traces, profiles, or tenant data to a shared learning.
32
33
  - For image overviews, OCR, PDF text, and screenshot diagnostics, see [the browser, image, and OCR workflow](../../../docs/AGENT-BROWSER-WORKFLOW.md). OCR does not prove visual layout or complete text capture.
@@ -6,9 +6,10 @@ import { createRequire } from "node:module";
6
6
  import { pathToFileURL } from "node:url";
7
7
  import { parseArgs } from "node:util";
8
8
  import { generateTestSource, runRecipe, validateBaseUrl, validateRecipe } from "../src/index.js";
9
+ import { createLearningDraft, validateLearning } from "../src/learning.js";
9
10
  import { acquireProfileLock } from "../src/profile-lock.js";
10
11
 
11
- const help = `SPFx Fast Playwright\n\nCommands:\n init [--force] Scaffold config and a smoke recipe\n validate <recipe.json> Validate a recipe\n generate <recipe.json> --out <test.spec.mjs> [--force] Generate a native Playwright test\n run <recipe.json> --base-url <url> --profile-dir <dir> [--artifacts <dir>] [--fast] [--headed]\n record --url <url> --profile-dir <dir> --out <test.spec.ts> Start Playwright Codegen\n\nRuns are headless by default. --fast skips success screenshots and traces; do one full run after fixes.\n`;
12
+ const help = `SPFx Fast Playwright\n\nCommands:\n init [--force] Scaffold config and a smoke recipe\n validate <recipe.json> Validate a recipe\n generate <recipe.json> --out <test.spec.mjs> [--force] Generate a native Playwright test\n learn init [--out <learning.json>] Create a local, anonymous learning draft\n learn validate <learning.json> Validate structure and check for common identifiers\n run <recipe.json> --base-url <url> (--storage-state <file> | --profile-dir <dir>) [--artifacts <dir>] [--fast] [--headed]\n record --url <url> (--storage-state <file> | --profile-dir <dir>) --out <test.spec.ts> Start Playwright Codegen\n\nLearning drafts default to test-results/spfx-fast-playwright/ and stay local; no telemetry or upload is performed. Review all evidence manually before sharing.\nRuns are headless by default. --fast skips success screenshots and traces; do one full run after fixes.\nSet SPFX_STORAGE_STATE to reuse a storage-state file for run and record.\n`;
12
13
 
13
14
  const parsed = parseArgs({
14
15
  args: process.argv.slice(2),
@@ -18,6 +19,7 @@ const parsed = parseArgs({
18
19
  out: { type: "string" },
19
20
  "base-url": { type: "string" },
20
21
  "profile-dir": { type: "string" },
22
+ "storage-state": { type: "string" },
21
23
  artifacts: { type: "string" },
22
24
  "timeout-ms": { type: "string" },
23
25
  url: { type: "string" },
@@ -41,6 +43,15 @@ async function readRecipe(file) {
41
43
  }
42
44
  }
43
45
 
46
+ async function readLearning(file) {
47
+ if (!file) throw new Error("Supply a learning JSON file.");
48
+ try { return validateLearning(JSON.parse(await readFile(resolve(file), "utf8"))); }
49
+ catch (error) {
50
+ if (error instanceof TypeError) throw error;
51
+ throw new Error("Could not read a valid learning JSON file.");
52
+ }
53
+ }
54
+
44
55
  async function outputPath(file) {
45
56
  if (!file) throw new Error("Supply --out.");
46
57
  const target = resolve(file);
@@ -52,6 +63,18 @@ async function outputPath(file) {
52
63
  return target;
53
64
  }
54
65
 
66
+ async function ignoreLearningDraft() {
67
+ const file = resolve(".gitignore");
68
+ let existing = "";
69
+ try { existing = await readFile(file, "utf8"); }
70
+ catch (error) { if (error.code !== "ENOENT") throw error; }
71
+ const entry = "/test-results/spfx-fast-playwright/learning-draft.json";
72
+ const ignored = existing.split(/\r?\n/);
73
+ if (ignored.includes(entry) || ignored.includes("/test-results/") || ignored.includes("test-results/")) return false;
74
+ await writeFile(file, `${existing}${existing && !existing.endsWith("\n") ? "\n" : ""}${entry}\n`, "utf8");
75
+ return true;
76
+ }
77
+
55
78
  async function requireProfileDirectory(value) {
56
79
  if (!value) throw new Error("Supply an existing --profile-dir. The command will not create or copy a signed-in profile.");
57
80
  const path = resolve(value);
@@ -61,6 +84,23 @@ async function requireProfileDirectory(value) {
61
84
  return path;
62
85
  }
63
86
 
87
+ async function requireStorageState(value) {
88
+ if (!value) return undefined;
89
+ const path = resolve(value);
90
+ let metadata;
91
+ try { metadata = await stat(path); } catch { throw new Error("The supplied storage-state file does not exist."); }
92
+ if (!metadata.isFile()) throw new Error("The supplied storage-state path must be a file.");
93
+ return path;
94
+ }
95
+
96
+ async function browserAuth() {
97
+ const storageState = await requireStorageState(options["storage-state"] ?? (options["profile-dir"] ? undefined : process.env.SPFX_STORAGE_STATE));
98
+ if (storageState && options["profile-dir"]) throw new Error("Choose either --storage-state or --profile-dir, not both.");
99
+ const profile = options["profile-dir"] ? await requireProfileDirectory(options["profile-dir"]) : undefined;
100
+ if (!storageState && !profile) throw new Error("Supply --storage-state (or set SPFX_STORAGE_STATE) or --profile-dir.");
101
+ return { storageState, profile };
102
+ }
103
+
64
104
  async function main() {
65
105
  if (options.help || !command || command === "help") {
66
106
  console.log(help);
@@ -81,7 +121,6 @@ async function main() {
81
121
  ["playwright.config.ts", `import { defineConfig } from "@playwright/test";\n\nexport default defineConfig({\n testDir: "./tests/e2e",\n fullyParallel: false,\n workers: 1,\n reporter: [["list"], ["html", { open: "never" }]],\n use: {\n baseURL: process.env.SPFX_BASE_URL,\n storageState: process.env.SPFX_STORAGE_STATE || undefined,\n actionTimeout: 15_000,\n navigationTimeout: 45_000,\n screenshot: "only-on-failure",\n trace: "retain-on-failure",\n viewport: { width: 1440, height: 900 },\n },\n});\n`],
82
122
  ["tests/e2e/sharepoint-smoke.recipe.json", `${JSON.stringify(smokeRecipe, null, 2)}\n`],
83
123
  ["tests/e2e/sharepoint-smoke.spec.mjs", generateTestSource(smokeRecipe)],
84
- ["playwright/.auth/.gitignore", "*\n!.gitignore\n"],
85
124
  ["SPFX-PLAYWRIGHT.md", agentGuide],
86
125
  ];
87
126
  if (!options.force) {
@@ -105,7 +144,7 @@ async function main() {
105
144
  const prefix = existingAgents ? `${existingAgents}${existingAgents.endsWith("\n") ? "" : "\n"}\n` : "# Agent instructions\n\n";
106
145
  await writeFile(agentsFile, `${prefix}${link}`, "utf8");
107
146
  }
108
- console.log("Created Playwright config, a generated smoke test, agent instructions, and an ignored auth-state folder.");
147
+ console.log("Created Playwright config, a generated smoke test, and agent instructions.");
109
148
  console.log("Set SPFX_BASE_URL to the SharePoint web URL. Keep SPFX_STORAGE_STATE private.");
110
149
  return;
111
150
  }
@@ -114,6 +153,26 @@ async function main() {
114
153
  console.log(`Recipe valid: ${recipe.name} (${recipe.steps.length} steps).`);
115
154
  return;
116
155
  }
156
+ if (command === "learn") {
157
+ const action = recipeFile;
158
+ const file = parsed.positionals[2];
159
+ if (action === "init") {
160
+ const isDefault = !options.out && !file;
161
+ const target = await outputPath(options.out ?? file ?? "test-results/spfx-fast-playwright/learning-draft.json");
162
+ if (isDefault && await ignoreLearningDraft()) console.log("Added the default draft path to .gitignore.");
163
+ await writeFile(target, `${JSON.stringify(createLearningDraft(), null, 2)}\n`, "utf8");
164
+ console.log(`Created local learning draft: ${target}`);
165
+ console.log("The draft contains no author or tenant fields. Edit it, validate it, then review it manually before sharing.");
166
+ return;
167
+ }
168
+ if (action === "validate") {
169
+ const learning = await readLearning(file ?? options.out);
170
+ console.log(`Learning valid: ${learning.title} (${learning.topic}, ${learning.validation.level}).`);
171
+ console.log("No upload occurred. Validation catches common identifiers; it cannot prove a draft is anonymous. Review every value and attached artifact.");
172
+ return;
173
+ }
174
+ throw new Error("Usage: spfx-fast-playwright learn <init [--out <file>] | validate <file>>");
175
+ }
117
176
  if (command === "generate") {
118
177
  const recipe = await readRecipe(recipeFile);
119
178
  const target = await outputPath(options.out);
@@ -123,16 +182,17 @@ async function main() {
123
182
  return;
124
183
  }
125
184
  if (command === "record") {
126
- const profile = await requireProfileDirectory(options["profile-dir"]);
185
+ const { storageState, profile } = await browserAuth();
127
186
  const output = await outputPath(options.out);
128
187
  if (!/\.spec\.(?:mjs|ts)$/.test(output)) throw new Error("Recorded tests must end in .spec.mjs or .spec.ts.");
129
188
  const url = validateBaseUrl(options.url).href;
130
189
  const requireFromProject = createRequire(pathToFileURL(resolve("package.json")));
131
190
  const playwrightEntry = requireFromProject.resolve("playwright");
132
191
  const cli = resolve(dirname(playwrightEntry), "cli.js");
133
- const releaseProfile = acquireProfileLock(profile);
192
+ const releaseProfile = profile ? acquireProfileLock(profile) : () => {};
134
193
  try {
135
- const result = spawnSync(process.execPath, [cli, "codegen", `--user-data-dir=${profile}`, `--output=${output}`, "--viewport-size=1440,900", url], { stdio: "inherit" });
194
+ const authArgs = storageState ? [`--load-storage=${storageState}`] : [`--user-data-dir=${profile}`];
195
+ const result = spawnSync(process.execPath, [cli, "codegen", ...authArgs, `--output=${output}`, "--viewport-size=1440,900", url], { stdio: "inherit" });
136
196
  if (result.error) throw new Error("Playwright Codegen could not start. Check that Playwright is installed in this project.");
137
197
  if (result.status !== 0) process.exitCode = result.status ?? 1;
138
198
  } finally { releaseProfile(); }
@@ -141,7 +201,7 @@ async function main() {
141
201
  if (command === "run") {
142
202
  const recipe = await readRecipe(recipeFile);
143
203
  const base = validateBaseUrl(options["base-url"]);
144
- const profile = await requireProfileDirectory(options["profile-dir"]);
204
+ const { storageState, profile } = await browserAuth();
145
205
  const artifactRoot = resolve(options.artifacts ?? "test-results/spfx-fast-playwright");
146
206
  const timeoutMs = Number(options["timeout-ms"] ?? 15000);
147
207
  if (!Number.isInteger(timeoutMs) || timeoutMs < 1) throw new Error("--timeout-ms must be a positive integer.");
@@ -154,16 +214,22 @@ async function main() {
154
214
  } catch {}
155
215
  await mkdir(artifacts, { recursive: true });
156
216
  const { chromium } = await import("playwright");
157
- const releaseProfile = acquireProfileLock(profile);
217
+ const releaseProfile = profile ? acquireProfileLock(profile) : () => {};
218
+ let browser;
158
219
  let context;
159
220
  let page;
160
221
  let result;
161
222
  let error;
162
223
  try {
163
- context = await chromium.launchPersistentContext(profile, {
164
- headless: options.headed ? false : true,
165
- viewport: { width: 1440, height: 900 },
166
- });
224
+ if (profile) {
225
+ context = await chromium.launchPersistentContext(profile, {
226
+ headless: options.headed ? false : true,
227
+ viewport: { width: 1440, height: 900 },
228
+ });
229
+ } else {
230
+ browser = await chromium.launch({ headless: !options.headed });
231
+ context = await browser.newContext({ storageState, viewport: { width: 1440, height: 900 } });
232
+ }
167
233
  page = context.pages()[0] ?? await context.newPage();
168
234
  if (!options.fast) await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
169
235
  result = await runRecipe(page, recipe, { baseUrl: base.href, screenshotDir: artifacts, timeoutMs, fast: options.fast });
@@ -175,6 +241,7 @@ async function main() {
175
241
  } finally {
176
242
  if (context && !options.fast) try { await context.tracing.stop({ path: resolve(artifacts, "trace.zip") }); } catch {}
177
243
  await context?.close();
244
+ await browser?.close();
178
245
  releaseProfile();
179
246
  }
180
247
  const report = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spfx-fast/playwright",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "author": "Vilius Vystartas",
5
5
  "description": "Authenticated, recipe-driven Playwright testing helpers for any SharePoint Framework project.",
6
6
  "license": "MIT",
@@ -19,5 +19,5 @@
19
19
  "bin": { "spfx-fast-playwright": "bin/spfx-fast-playwright.mjs" },
20
20
  "files": ["src", "bin", "README.md", "LICENSE", "examples", "agent"],
21
21
  "peerDependencies": { "@playwright/test": ">=1.50.0 <2", "playwright": ">=1.50.0 <2" },
22
- "keywords": ["spfx", "sharepoint", "playwright", "e2e", "testing", "agents"]
22
+ "keywords": ["spfx", "sharepoint", "playwright", "e2e", "testing", "agents", "agent-skills"]
23
23
  }
@@ -0,0 +1,110 @@
1
+ import { validateRecipe } from "./index.js";
2
+
3
+ const fields = {
4
+ root: ["format", "version", "title", "topic", "appliesTo", "problem", "finding", "reproduction", "recommendation", "limitations", "validation", "recipe"],
5
+ appliesTo: ["service", "surface", "spfxVersion", "browser"],
6
+ validation: ["level", "checkedOn", "sampleSize"],
7
+ };
8
+ const topics = new Set(["ui", "accessibility", "navigation", "deployment", "permissions", "data", "performance", "other"]);
9
+ const levels = new Set(["unverified", "reproduced", "tenant-validated", "documented"]);
10
+
11
+ function rejectUnknownKeys(value, allowed, path) {
12
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${path} must be an object.`);
13
+ for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new TypeError(`${path}.${key} is not a supported field.`);
14
+ }
15
+
16
+ export function createLearningDraft() {
17
+ return {
18
+ format: "spfx-fast-learning",
19
+ version: 1,
20
+ title: "Describe the reusable SharePoint discovery",
21
+ topic: "ui",
22
+ appliesTo: { service: "SharePoint Online", surface: "SPFx web part", spfxVersion: "1.24+", browser: "Chromium" },
23
+ problem: "What was difficult to discover?",
24
+ finding: "What behavior or reliable pattern did you observe?",
25
+ reproduction: ["Describe the setup and steps without tenant-specific details."],
26
+ recommendation: "What should another agent or developer do?",
27
+ limitations: "State what has not been verified and where this may not apply.",
28
+ validation: { level: "unverified" },
29
+ recipe: {
30
+ name: "Replace with a focused, reusable UI check",
31
+ steps: [
32
+ { action: "navigate", path: "/sites/your-site" },
33
+ { action: "assertPageReady" },
34
+ { action: "assertAuthenticated" },
35
+ ],
36
+ },
37
+ };
38
+ }
39
+
40
+ function checkKeys(value, allowed, path) {
41
+ rejectUnknownKeys(value, allowed, path);
42
+ for (const key of allowed) {
43
+ if (!Object.hasOwn(value, key) && !(path === "validation" && key !== "level")) {
44
+ throw new TypeError(`${path}.${key} is required.`);
45
+ }
46
+ }
47
+ }
48
+
49
+ function strings(value, path, found = []) {
50
+ if (typeof value === "string") {
51
+ const patterns = [
52
+ [/[\w.+-]+@[\w.-]+\.[A-Z]{2,}/i, "email address"],
53
+ [/\b[a-f\d]{8}-(?:[a-f\d]{4}-){3}[a-f\d]{12}\b/i, "GUID"],
54
+ [/\b[a-z\d-]+\.sharepoint(?:-df)?\.com\b|\b[a-z\d-]+\.onmicrosoft\.com\b/i, "tenant domain"],
55
+ [/\/(?:sites|teams)\/(?!your-site(?:\/|$)|your-team(?:\/|$)|example(?:\/|$))[a-z\d._%-]+/i, "site-specific path"],
56
+ [/\bBearer\s+\S+/i, "bearer token"],
57
+ [/\beyJ[a-zA-Z\d_-]{10,}\.[a-zA-Z\d_-]{10,}\.[a-zA-Z\d_-]{10,}\b/, "JWT-like token"],
58
+ [/[?&](?:access_token|refresh_token|client_secret|code)=[^&\s]+/i, "credential query parameter"],
59
+ ];
60
+ for (const [pattern, label] of patterns) if (pattern.test(value)) found.push({ path, label });
61
+ } else if (Array.isArray(value)) {
62
+ value.forEach((item, index) => strings(item, `${path}[${index}]`, found));
63
+ } else if (value && typeof value === "object") {
64
+ for (const [key, item] of Object.entries(value)) strings(item, `${path}.${key}`, found);
65
+ }
66
+ return found;
67
+ }
68
+
69
+ function requireText(value, path, max = 2000) {
70
+ if (typeof value !== "string" || !value.trim() || value.length > max) throw new TypeError(`${path} must be a non-empty string of at most ${max} characters.`);
71
+ }
72
+
73
+ export function validateLearning(learning) {
74
+ if (!learning || typeof learning !== "object" || Array.isArray(learning)) throw new TypeError("Learning must be a JSON object.");
75
+ const sensitive = strings(learning, "learning");
76
+ if (sensitive.length) throw new TypeError(`Possible ${sensitive[0].label} at ${sensitive[0].path}. Replace it with generic details before sharing.`);
77
+
78
+ checkKeys(learning, fields.root, "learning");
79
+ if (learning.format !== "spfx-fast-learning" || learning.version !== 1) throw new TypeError("Learning format/version must be spfx-fast-learning/1.");
80
+ requireText(learning.title, "learning.title", 120);
81
+ if (!topics.has(learning.topic)) throw new TypeError(`learning.topic must be one of: ${[...topics].join(", ")}.`);
82
+ checkKeys(learning.appliesTo, fields.appliesTo, "learning.appliesTo");
83
+ for (const key of fields.appliesTo) requireText(learning.appliesTo[key], `learning.appliesTo.${key}`, 120);
84
+ requireText(learning.problem, "learning.problem");
85
+ requireText(learning.finding, "learning.finding");
86
+ if (!Array.isArray(learning.reproduction) || learning.reproduction.length < 1 || learning.reproduction.length > 12) throw new TypeError("learning.reproduction must contain 1 to 12 steps.");
87
+ learning.reproduction.forEach((step, index) => requireText(step, `learning.reproduction[${index}]`, 500));
88
+ requireText(learning.recommendation, "learning.recommendation");
89
+ requireText(learning.limitations, "learning.limitations");
90
+ checkKeys(learning.validation, fields.validation, "learning.validation");
91
+ if (!levels.has(learning.validation.level)) throw new TypeError(`learning.validation.level must be one of: ${[...levels].join(", ")}.`);
92
+ if (learning.validation.checkedOn !== undefined) {
93
+ const checkedOn = new Date(`${learning.validation.checkedOn}T00:00:00Z`);
94
+ if (!/^\d{4}-\d{2}-\d{2}$/.test(learning.validation.checkedOn) || Number.isNaN(checkedOn.valueOf()) || checkedOn.toISOString().slice(0, 10) !== learning.validation.checkedOn) throw new TypeError("learning.validation.checkedOn must be a valid YYYY-MM-DD date.");
95
+ }
96
+ if (learning.validation.level !== "unverified" && !learning.validation.checkedOn) throw new TypeError("Set validation.checkedOn for reproduced, tenant-validated, and documented findings.");
97
+ if (learning.validation.sampleSize !== undefined && (!Number.isInteger(learning.validation.sampleSize) || learning.validation.sampleSize < 1 || learning.validation.sampleSize > 10000)) throw new TypeError("learning.validation.sampleSize must be an integer from 1 to 10000.");
98
+ try {
99
+ validateRecipe(learning.recipe);
100
+ rejectUnknownKeys(learning.recipe, ["name", "steps"], "learning.recipe");
101
+ learning.recipe.steps.forEach((step, index) => {
102
+ const stepPath = `learning.recipe.steps[${index}]`;
103
+ rejectUnknownKeys(step, ["action", "path", "query", "locator", "value", "confirm", "checked", "expected", "exact", "name", "fullPage"], stepPath);
104
+ if (step.locator) rejectUnknownKeys(step.locator, ["role", "text", "label", "testId", "placeholder", "name", "exact"], `${stepPath}.locator`);
105
+ if (step.query && Object.keys(step.query).some((key) => key !== "debugManifestsFile")) throw new TypeError(`${stepPath}.query may only contain the local debugManifestsFile parameter.`);
106
+ });
107
+ }
108
+ catch (error) { throw new TypeError(`learning.recipe is invalid: ${error.message}`); }
109
+ return learning;
110
+ }