@mafianacho/nacholens 0.0.0-stage → 0.3.0

package/docs/model-schema.md

@@ -0,0 +1,137 @@
+# Model and change-overlay formats
+
+`src/model.js` (`validateModel`, `validateChanges`) is the source of truth; this page is its description.
+
+## `model.json`
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "product": { "id": "my-api", "name": "My API", "description": "One or two sentences." },
+  "source":  { "repo": "owner/repo", "commit": "SHA of the commit whose code you read" },
+  "components": [{
+    "id": "api",                              // lowercase-with-hyphens, unique
+    "kind": "client | gateway | service | datastore | external",
+    "label": "Order API\nNode http",          // text after \n is the sub-title
+    "detail": "What it is and does, one or two sentences.",
+    "lane": 2, "row": 1,                      // optional layout hints (0-9). Default lanes: client 0, gateway 1, service 2, datastore/external 3
+    "evidence": [{ "file": "api.js", "lines": [36, 85], "contains": "async function route" }]
+  }],
+  "links": [{ "a": "browser", "b": "gateway", "label": "HTTP, same origin /api/*", "evidence": [ ... ] }],  // one per pair, undirected
+  "useCases": [{
+    "id": "list-orders", "title": "List my orders", "summary": "...", "trigger": "GET /api/orders",
+    "steps": [{
+      "id": "query",
+      "kind": "request | response | call | internal",
+      "from": "api", "via": ["gateway"], "to": "db",   // via: components passed through (e.g. the gateway); every hop needs a link
+      "label": "Read the user's orders",
+      "narration": "One or two plain sentences for a non-developer.",
+      "request": "one-line summary",                    // required for request and call
+      "response": "one-line summary",                   // required for response and call
+      "evidence": [ ... ]
+    }]
+  }]
+}
+```
+
+Step kinds: `request` one way in · `response` one way out · `call` a round trip (database, third party) · `internal` a decision inside one component (`from` = `to`, no `via`).
+
+`evidence` entries are `{file, lines:[start,end], contains?}`: a repository-relative path (no `..`, not absolute), an inclusive line range, and an optional string that must appear inside that range. `verify` fails when the file, the range or the string does not match the source at `source.commit`. Use `contains`: without it a range that drifted onto other code goes unnoticed (`verify` warns).
+
+Validation rejects: items without evidence, links or steps over undeclared links, duplicate ids, unknown kinds or keys, absolute or `..` paths, `call` steps without a response summary, leftover `TODO`s from the template.
+
+## Optional drill-down detail
+
+All fields below are **optional**. A model without them is valid and renders exactly as before; a node that has any of them gets a "· 상세" caption and opens a detail view on click (Esc, the back button or browser Back closes it). Every item carries its own `evidence` and `verify` checks it like any other item.
+
+```jsonc
+// on a client / gateway / service component: its inside and the wiring between the parts
+"parts": [{
+  "id": "orders-svc", "label": "OrderService",
+  "role": "route | handler | middleware | service | port | adapter | job | module",
+  "detail": "What this part does, one or two sentences.",
+  "connects": "db",                       // optional: the component this part talks to (adapters)
+  "evidence": [ ... ]
+}],
+"wires": [{ "from": "orders-route", "to": "orders-svc", "label": "listOrders(user)", "evidence": [ ... ] }],   // directed, both ends are parts of this component
+
+// on a datastore component: its tables and columns
+"tables": [{
+  "name": "order_events", "detail": "...",
+  "columns": [{ "name": "kind", "type": "text", "note": "created|paid|shipped" }],   // type and note optional
+  "evidence": [ ... ]                     // the migration / schema lines
+}],
+
+// on an external component: the endpoints this code calls
+"endpoints": [{
+  "id": "track", "method": "GET | POST | PUT | PATCH | DELETE | HEAD | WS | RPC | SSE", "path": "/v1/track",
+  "auth": "Bearer API key (server setting)",   // optional, the NAME of the scheme only
+  "detail": "...",
+  "request":  [{ "name": "code", "note": "tracking code" }],    // optional, key fields only
+  "response": [{ "name": "status" }],                      // optional
+  "evidence": [ ... ]
+}]
+
+// on a step: how the step uses that detail
+"trace": ["api/orders-route", "api/orders-svc"],        // "component/part" in the order the request passes them
+"data": [{ "store": "db", "table": "orders", "op": "read | insert | update | upsert | delete",
+           "columns": ["user_id", "status"], "evidence": [ ... ] }],   // the query lines; columns must be declared on the table
+"endpoints": ["tracker/track"]                  // "component/endpoint" this step calls
+```
+
+Rules the validator enforces:
+
+- `parts`/`wires` only on `client | gateway | service`; `tables` only on `datastore`; `endpoints` only on `external`. `wires` need `parts`.
+- `trace`: every entry is a declared part of a component the step passes (`from`, `via`, `to`). Two consecutive parts of the same component need a declared wire between them (either direction); parts of different components need a declared link.
+- `data`: `store` is a datastore the step passes; `table` and every `columns` entry are declared on it.
+- `endpoints` on a step: declared on a component the step passes.
+- **No secrets anywhere in a model.** Strings that look like keys or tokens (`sk-…`, `ghp_…`, `AKIA…`, JWTs, PEM blocks, `Bearer <long value>`) are rejected. Write the auth scheme's name, never a value.
+
+### Optional data shapes and transforms (on a step)
+
+`payload` is what travels on a moving step, shown when the user clicks the dot or the data label. `transforms` is how the data changes at a part on the step's `trace`, shown in the right panel and on the current wire inside the detail view. Both are optional; a step without them shows its `request`/`response` summary as before.
+
+```jsonc
+"payload": [{
+  "leg": "request | response",           // call: both; request step: request; response step: response; internal: not allowed
+  "format": "json | http | sql | row | text | vector | sse | ws",
+  "title": "read my orders",             // optional, <= 80 chars
+  "body": "SELECT id, item FROM orders WHERE email = ?",   // optional, <= 2000 chars / 40 lines
+  "bind":    [{ "name": "?1 email", "value": "<email>" }],  // optional: SQL parameters
+  "columns": [{ "name": "id", "value": "INTEGER" }],        // optional: row shape (table, column, value type)
+  "evidence": [ ... ]                    // the statement, the struct, or the code that builds the body
+}],
+"transforms": [{
+  "at": "api/orders-post",               // a "component/part" on this step's trace
+  "in":  { "type": "validated order", "fields": ["item", "qty"] },
+  "out": { "type": "insertOrder arguments", "fields": ["email", "item (cut to 80)", "qty", "tracking"] },
+  "map": [{ "from": "item", "to": "item.slice(0, 80)", "how": "optional note" }],
+  "evidence": [ ... ]                    // the lines that do the conversion
+}]
+```
+
+- At least one of `body`, `bind`, `columns`. Values are **shapes and placeholders** (`<uuid>`, `<text>`, `<int>`, `<email>`, `INTEGER`), never real data: the validator refuses e-mail addresses (other than `example.com/org/net`), phone numbers, resident-number shapes and runs of 10+ digits, besides the secret patterns above.
+- Write only fields you saw in code (the struct, the `json!` body, the SQL text). Elide the rest with `…`; do not guess.
+- `transforms` need `trace`; `at` must be on it. List them in the order the data flows.
+- Their evidence belongs to the step (`verify` checks it; a changed line marks the step).
+
+`diff` maps changed lines to detail items too: `changes.details` lists parts, wires, tables and endpoints whose own evidence changed (`{component, kind: part|wire|table|endpoint, id, change, note}`; a wire's id is `from>to`). They mark items inside the detail view and never badge the component. Table access cited in `step.data` belongs to the step, so a changed query marks the step.
+
+## `changes.json` (change overlay)
+
+`nacholens diff` / `build --repo` produce it; a hand-written file with only the first four fields is accepted too.
+
+```jsonc
+{
+  "title": "...", "summary": "...", "ref": "repo base..head",
+  "components": [{ "id": "api", "change": "added | modified | removed", "note": "..." }],
+  "steps":      [{ "useCase": "list-orders", "step": "shipping", "change": "added", "note": "..." }],
+  // optional, written by `diff`
+  "unmapped": [{ "file": "...", "category": "code | style", "status": "added | modified | deleted", "lines": "...", "hint": "..." }],
+  "details":  [{ "component": "db", "kind": "table", "id": "order_events", "change": "added", "note": "..." }],
+  "ignored":  [{ "file": "...", "reason": "tests | docs | lock file | static asset" }],
+  "generated": { "by": "nacholens diff", "base": "sha", "head": "sha", "modelCommit": "sha", "lineTranslation": true }
+}
+```
+
+A complete worked example lives in `models/demo-shop/`: `model.json`, the hand-written `changes.example.json` and the generated `changes.auto.json`.

package/docs/review.md

@@ -0,0 +1,78 @@
+# Review: before/after, intent check, regression map
+
+These answer the questions a reviewer has *after* "what changed?": "what was it before?", "is this what we asked for?" and
+"what else can this break?". Nothing is guessed: whatever the model cannot show is reported as `unknown` / "not found", never as a pass.
+
+On the page they live in the **review dock** under the stage, as three tracks:
+
+| Tab | For | Still to check (the count on the tab) |
+|---|---|---|
+| 기획 의도 | planner | expectations not met or not provable, and flows with changes no expectation points at |
+| 회귀 테스트 | QA | use cases to re-test |
+| 모델 밖 변경 | developer | folders with changed code that no step cites (config/style and ignored files are listed apart) |
+
+Each tab carries its status (a coloured dot and how many items are left), so the tab bar is the page's to-do summary.
+Ticks are a per-viewer convenience kept in browser storage when it is available. Rows never repeat a step: they link to it and the
+stage moves there. `#dock=intent|impact|unmapped` in the URL opens a tab; clicking the open tab folds the dock; its top edge resizes it.
+The dock is shown whenever there is a change overlay or review data.
+
+## 1. Before / after (`compare`)
+
+Rows are aligned by step id for every use case: **added** (nothing before), **removed** (nothing after), **modified**, **moved**, **same**,
+with the component path before and after (a component reached only by an added step is marked new). They are in `review.json`.
+On the page, before/after belongs to the step: with two models the current step's explanation lists the fields it had before
+(name, kind, route, request, response) or says it only moved, and the flow overview lists the steps that are gone. In overlay mode the
+step shows the reason from the overlay (its changed evidence) and nothing is claimed about the old text.
+
+| Mode | How | What it can say |
+|---|---|---|
+| overlay (default) | model + change overlay | added / removed / "code changed". The old text of a modified step is not in the model, and the row says so. |
+| two models | `build --before-model <model written against the base commit>` | the flow itself: label, kind, from/to/via, request/response differences per field, removed steps, moved steps, new/removed use cases |
+
+## 2. Intent check (`intent`)
+
+The planner (or the agent from the planner's words) writes `intent.json`; the CLI checks every expectation against the model.
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "title": "Show shipping status on the order list",
+  "source": "link or name of the spec",              // optional
+  "expectations": [
+    { "id": "ship-lookup", "text": "The order list asks the carrier for each status", "useCase": "list-orders",
+      "check": { "type": "step", "match": { "kind": "call", "to": "shipping" } } },
+    { "id": "login-first", "text": "Orders are read only after the session check", "useCase": "list-orders",
+      "check": { "type": "order", "first": { "table": "sessions", "op": "read" }, "then": { "table": "orders", "op": "read" } } },
+    { "id": "no-export", "text": "There is no CSV export", "useCase": "list-orders",
+      "check": { "type": "absent", "match": { "text": "csv|export" } } },
+    { "id": "wording", "text": "Shipping wording is friendly" }          // no check -> stays "unknown"
+  ]
+}
+```
+
+- `check.type`: `step` (some step matches), `absent` (no step matches), `order` (a `first` step comes before a `then` step).
+- A matcher uses any of `kind`, `from`, `to`, `with` (component the step passes), `table`, `op`, `text` (alternatives separated by `|`, case-insensitive substring over label, narration, request, response and column names; no regular expressions).
+- Verdict per expectation: **met** (with the proving steps and their `file:lines`), **unmet** (the use case exists but the model shows no such step, or the opposite), **unknown** (no check).
+  An expectation whose proving steps were changed by this work is flagged *touched*, so the planner re-reads it.
+- **Uncovered changes**: changed steps that no expectation points at. They are candidates for scope drift; a human decides. An expectation with a `useCase` but no `check` claims that use case's changed steps.
+- Matching reads the *model*, which cites real code. If the model is wrong the verdict is wrong, so keep `verify` green.
+
+`nacholens intent --model M --intent I [--repo R --base B | --changes C] [--out report.json] [--strict-intent]` prints the verdicts; with `--strict-intent` an unmet expectation exits with code **4**.
+
+## 3. Regression map (`impact`)
+
+For the change overlay, which use cases should be checked again, why, and whether a test mentions them.
+
+- **direct**: the use case holds a changed step.
+- **indirect**: a step of another use case shares something the change touched: a **table** (also a changed schema), an external **endpoint**, a **part**, a **wire** (a drill-down item whose own evidence changed), or a **component** whose own evidence changed.
+  A component that is merely an end point of a changed step is *not* a link (every use case passes the API, that would flag everything). A changed step's own parts and endpoints are not repeated as reasons.
+- **tests** (needs `--repo`): test files at `--head` that mention the use case's route (`/api/orders` matches `"/api/orders"` and `/api/orders/7`, not `/api/orders-archive`).
+  States: `covered-changed` (the test file changed in this diff), `covered`, `none-found` (**not** "untested": a test that builds the URL differently is missed), `unknown` (no repository was read).
+- Sorted so that use cases without a test come first.
+
+`nacholens impact --repo R --base B [--head H] [--model M] [--out impact.json]` prints it.
+
+## Output
+
+`build` embeds the review data in the page whenever there is an overlay, `--before-model` or `--intent`; with `--repo` it also writes `review.json`
+and adds a `review` summary (`compare`, `intent`, `impact` counts) to `report.json`. Without an overlay or review data the dock stays hidden.