@ia-qa/qa-discovery 0.1.1 → 0.1.2

package/README.md

@@ -290,6 +290,20 @@ They are two halves of the same loop, and neither replaces the other.
 
 ⚠️ **`scan` and `map` are not the same operation.** `map` writes a page *contract* — every interactive element by role and accessible name, for repairing broken locators. `scan` writes a *surface* — pages, headings, inputs, API calls, for deciding what to test. Do not expect one to produce the other.
 
+### `scan` vs `ia-qa-heal discover` — the one that actually gets confused
+
+Self-healing has its own crawling verb, and the names do not make the difference obvious. They answer different questions, and if yours is the first one you do **not** need this package:
+
+| | `ia-qa-heal discover` | `ia-qa-discover scan` |
+|---|---|---|
+| Answers | *Which routes are missing from my `config.pages`?* | *What does this app take as input, and where would testing start?* |
+| Gives you | `{ name, url }` candidates | the surface behind each URL |
+| Then what | `--apply` appends to `config.json` | you know what there is to test |
+
+Measured on the same four pages of ia-qa.com: `discover` returns **4 `{name, url}` pairs**; `scan` returns those four pages plus **159 headings, 3 input fields with their captured labels, 9 observed API calls**, and the verdict that none of the three fields can be located durably. That is not a richer rendering of the same data — it is a different dataset.
+
+**So: if you only want to fill `config.pages`, use `ia-qa-heal discover` and stop there.** Reach for `scan` when you need to know what the pages *contain*, or when you have no suite at all — which is the case self-healing's own README opens by excluding.
+
 **Discovery → healing.** Once you know the routes, hand them to healing and start writing tests against contracts:
 
 ```bash
@@ -299,7 +313,16 @@ ia-qa-heal init                                       # then map it for test mai
 
 `config.pages` here has the same `{ name, url }` shape as self-healing's, and both packages resolve page names through the *same* function (`pageNameFromUrl`), so a page called `checkout` in one is `checkout` in the other. The two sets of artifacts line up 1:1.
 
-**Healing → discovery.** Healing knows what your suite *covers*. Discovery knows what *exists*. The gap between them is your real coverage — and neither tool can tell you that alone.
+**Healing → discovery — and the gap is computed, not just described.** Healing knows what your suite *covers*; discovery knows what *exists*. When a project already has `.ia-qa/mapping/`, `scan` ends by stating the difference:
+
+```
+🔗 This project also uses `ia-qa-heal`: it holds contracts for 3 page(s), this scan found 4.
+   2 page(s) exist here with no contract: `all-tools`, `resources`
+   That is the gap between what the app has and what the suite holds — not a verdict:
+   a page with no contract may be deliberately out of scope. You decide which.
+```
+
+Comparable only because both packages resolve page names through the *same* `pageNameFromUrl`. It is **not** a verdict and this package gates nothing — an uncovered page may be out of scope on purpose. A contracted page this scan did not reach is reported as a limit of the scan (`--max`, crawl reach, session), never as a page that disappeared. On a project with no `.ia-qa/`, nothing is printed at all.
 
 **Sessions are interchangeable.** Both consume a Playwright `storageState`, so a session from either `login` verb works for the other: `ia-qa-discover scan --session ../.ia-qa/session.json`.
 

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@ia-qa/qa-discovery",
-  "version": "0.1.1",
-  "description": "Deterministic surface reconnaissance for an unknown web app — crawl, capture, diff. No LLM, no hosting: runs entirely on your machine, with a local MCP server for agents.",
-  "keywords": [
-    "qa",
-    "testing",
-    "test-discovery",
-    "crawler",
-    "playwright",
-    "mcp",
-    "model-context-protocol"
-  ],
-  "license": "MIT",
-  "author": "Jean-Christophe Jamet",
-  "homepage": "https://www.ia-qa.com",
-  "type": "commonjs",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./dist/*": [
-      "./dist/*",
-      "./dist/*.js"
-    ],
-    "./package.json": "./package.json"
-  },
-  "bin": {
-    "ia-qa-discover": "dist/cli/index.js",
-    "ia-qa-discover-mcp": "dist/mcp/server.js",
-    "ia-qa-discover-ai": "dist/cli-ai/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "ROADMAP.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch",
-    "start:mcp": "node dist/mcp/server.js",
-    "prepublishOnly": "npm run build"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@ia-qa/self-healing": "^1.7.0"
-  },
-  "peerDependencies": {
-    "playwright": ">=1.40.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.14.0",
-    "playwright": "^1.45.0",
-    "typescript": "^5.5.0"
-  }
-}
+{
+  "name": "@ia-qa/qa-discovery",
+  "version": "0.1.2",
+  "description": "Deterministic surface reconnaissance for an unknown web app — crawl, capture, diff. No LLM, no hosting: runs entirely on your machine, with a local MCP server for agents.",
+  "keywords": [
+    "qa",
+    "testing",
+    "test-discovery",
+    "crawler",
+    "playwright",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "author": "Jean-Christophe Jamet",
+  "homepage": "https://www.ia-qa.com",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dist/*": [
+      "./dist/*",
+      "./dist/*.js"
+    ],
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "ia-qa-discover": "dist/cli/index.js",
+    "ia-qa-discover-mcp": "dist/mcp/server.js",
+    "ia-qa-discover-ai": "dist/cli-ai/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "ROADMAP.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "start:mcp": "node dist/mcp/server.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@ia-qa/self-healing": "^1.7.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "playwright": "^1.45.0",
+    "typescript": "^5.5.0"
+  }
+}