From 7335cf680caed33ae8543ad14ee03d6efc699ed0 Mon Sep 17 00:00:00 2001 From: Forge Date: Tue, 22 Sep 2026 02:48:58 +0000 Subject: [PATCH] Record external author-kit publication and graph acceptance --- .../extensions-author-20260922.json | 294 ++++++++++++++++++ docs/validation/extensions-author-20260922.md | 122 ++++++++ .../extensions-recovery-20260922.md | 8 +- 3 files changed, 421 insertions(+), 3 deletions(-) create mode 100644 docs/validation/extensions-author-20260922.json create mode 100644 docs/validation/extensions-author-20260922.md diff --git a/docs/validation/extensions-author-20260922.json b/docs/validation/extensions-author-20260922.json new file mode 100644 index 000000000..cfda62089 --- /dev/null +++ b/docs/validation/extensions-author-20260922.json @@ -0,0 +1,294 @@ +{ + "sourceRevision": "8b30afb328fc8fe0c4d2d0b348d53bdbcb009acc", + "platform": "linux", + "authorOutsideCore": true, + "generatedId": "python-events", + "publicSdk": "@colbymchenry/codegraph", + "artifactSha256": "d87fe94c5016372984c579b31989c036e863b6102bbf027704c7ff8afe21e5c8", + "checks": [ + "generated CLI starter", + "fresh local npm package installation", + "public JSDoc typecheck", + "generated positive and negative fixture harness", + "signed browser publisher submission", + "managed install from local release URL", + "actual event-to-Python-handler edge", + "non-Node target", + "managed removal clears contribution" + ], + "routes": [ + { + "id": "plugin:python-events:checkout.events.yaml:1", + "kind": "route", + "name": "event:order.created", + "qualifiedName": "checkout.events.yaml::event:order.created:1", + "filePath": "checkout.events.yaml", + "language": "yaml", + "startLine": 1, + "endLine": 1, + "startColumn": 0, + "endColumn": 27, + "visibility": null, + "isExported": false, + "isAsync": false, + "isStatic": false, + "isAbstract": false, + "updatedAt": 0 + } + ], + "edges": [ + { + "source": "plugin:python-events:checkout.events.yaml:1", + "target": "function:58a0dab3277dcb344ab16c8590891a47", + "kind": "calls", + "metadata": { + "label": "Python event dispatch", + "registeredAt": "checkout.events.yaml:1", + "synthesizedBy": "python-events", + "confidence": 1, + "resolvedBy": "framework", + "refName": "python-events:send_receipt" + }, + "line": 1, + "column": 0, + "provenance": null + } + ], + "commands": [ + { + "command": [ + "/usr/local/bin/node", + "/data/workspace/Chats/109197f0a288be0afa6b7f8902925630f5a0bfde/codegraph/dist/bin/codegraph.js", + "extensions", + "create", + "/tmp/codegraph-external-author-q7LLRf/python-events", + "--id", + "python-events" + ], + "cwd": "/tmp/codegraph-external-author-q7LLRf", + "exit": 0, + "seconds": 0.374 + }, + { + "command": [ + "npm", + "pack", + "--ignore-scripts", + "--json", + "--pack-destination", + "/tmp/codegraph-external-author-q7LLRf" + ], + "cwd": "/data/workspace/Chats/109197f0a288be0afa6b7f8902925630f5a0bfde/codegraph", + "exit": 0, + "seconds": 13.987 + }, + { + "command": [ + "npm", + "install", + "--ignore-scripts", + "--no-audit", + "--no-fund", + "--save-dev", + "/tmp/codegraph-external-author-q7LLRf/colbymchenry-codegraph-1.6.0.tgz" + ], + "cwd": "/tmp/codegraph-external-author-q7LLRf/python-events", + "exit": 0, + "seconds": 7.007 + }, + { + "command": [ + "/usr/local/bin/node", + "/data/workspace/Chats/109197f0a288be0afa6b7f8902925630f5a0bfde/codegraph/node_modules/typescript/bin/tsc", + "--allowJs", + "--checkJs", + "--noEmit", + "--skipLibCheck", + "--target", + "ES2022", + "--module", + "commonjs", + "/tmp/codegraph-external-author-q7LLRf/python-events/index.cjs" + ], + "cwd": "/tmp/codegraph-external-author-q7LLRf/python-events", + "exit": 0, + "seconds": 1.535 + }, + { + "command": [ + "/usr/local/bin/node", + "/tmp/codegraph-external-author-q7LLRf/python-events/node_modules/@colbymchenry/codegraph/dist/bin/codegraph.js", + "extensions", + "test", + "." + ], + "cwd": "/tmp/codegraph-external-author-q7LLRf/python-events", + "exit": 0, + "seconds": 5.734 + }, + { + "command": [ + "/usr/local/bin/node", + "/tmp/codegraph-external-author-q7LLRf/python-events/node_modules/@colbymchenry/codegraph/dist/bin/codegraph.js", + "extensions", + "pack", + ".", + "--out", + "/tmp/codegraph-external-author-q7LLRf/python-events-0.1.0.cgext" + ], + "cwd": "/tmp/codegraph-external-author-q7LLRf/python-events", + "exit": 0, + "seconds": 0.409 + }, + { + "command": [ + "/usr/local/bin/node", + "/tmp/codegraph-external-author-q7LLRf/python-events/node_modules/@colbymchenry/codegraph/dist/bin/codegraph.js", + "extensions", + "install", + "http://127.0.0.1:39495/api/download/python-events/0.1.0", + "--path", + "/tmp/codegraph-external-author-q7LLRf/python-app" + ], + "cwd": "/tmp/codegraph-external-author-q7LLRf", + "exit": 0, + "seconds": 1.531 + }, + { + "command": [ + "/usr/local/bin/node", + "/tmp/codegraph-external-author-q7LLRf/python-events/node_modules/@colbymchenry/codegraph/dist/bin/codegraph.js", + "extensions", + "remove", + "python-events", + "--path", + "/tmp/codegraph-external-author-q7LLRf/python-app" + ], + "cwd": "/tmp/codegraph-external-author-q7LLRf", + "exit": 0, + "seconds": 1.5 + }, + { + "command": [ + "git", + "rev-parse", + "HEAD" + ], + "cwd": "/data/workspace/Chats/109197f0a288be0afa6b7f8902925630f5a0bfde/codegraph", + "exit": 0, + "seconds": 0.005 + } + ], + "browserErrors": [], + "generatedHarness": { + "apiVersion": 1, + "engineVersion": "1.6.0", + "artifactSha256": "d87fe94c5016372984c579b31989c036e863b6102bbf027704c7ff8afe21e5c8", + "cases": [ + { + "name": "literal event reaches its Python handler; unknown and computed targets do not", + "assertions": 6, + "deterministic": true, + "removalClean": true + }, + { + "name": "ambiguous Python handlers stay unresolved", + "assertions": 2, + "deterministic": true, + "removalClean": true + } + ] + }, + "sourceFiles": { + "src/index.ts": "72b3178b79a999c42d117927a9db758b8fd918a08031dd2c8812bb1e28c54464", + "src/plugins/author.ts": "a485954370619e31aacf3e70f6126ac4b86dfa5e038d32fe8484b9c528b74979", + "src/plugins/author-template.ts": "effca678ce3c0f25aa620cda4f5ad49b77a6d894f1b02a5ea3246236f14e18c4", + "src/plugins/package.ts": "8e44d767ab0e461d46ebcad5b6e0fc80d9f69adb8b3978adea7cc53b58630f9e", + "src/plugins/loader.ts": "be9cebf6c35552b60958a627ef022059e9e879b9c002437233dd0f91115f58a6", + "src/plugins/cli.ts": "33d015518c878853c9c9a1fc449ea0cc7b31bbaa8433b65e4ebd0db0e43af894" + }, + "validationReceipts": [ + { + "command": [ + "npm", + "run", + "build" + ], + "cwd": "/data/workspace/Chats/109197f0a288be0afa6b7f8902925630f5a0bfde/codegraph", + "started_at": "2026-09-22T02:34:40.721360+00:00", + "revision": "1466021e1855a87f95bec6a7885935e4c412c02e", + "working_tree": " M package.json\n M scripts/pack-npm.sh\n M src/index.ts\n M src/plugins/cli.ts\n M src/plugins/loader.ts\n M src/plugins/package.ts\n?? __tests__/extension-author.test.ts\n?? docs/extensions/\n?? src/plugins/author-template.ts\n?? src/plugins/author.ts\n", + "exit_code": 0, + "seconds": 121.099, + "finished_at": "2026-09-22T02:36:41.821256+00:00", + "summary": [], + "name": "author-build-fixed", + "log_sha256": "fafb0510d7f8202de576141182b2c472d70c72f71c65d714403b96f6e201435a", + "source_provenance": "Ran on the uncommitted implementation later saved in 8b30afb328fc8fe0c4d2d0b348d53bdbcb009acc. Runtime/author source was unchanged afterward; documentation and the external acceptance runner were finalized before that commit." + }, + { + "command": [ + "npx", + "vitest", + "run", + "__tests__/extension-author.test.ts", + "__tests__/plugins.test.ts", + "__tests__/extension-marketplace.test.ts", + "__tests__/extension-explore.test.ts", + "__tests__/npm-sdk.test.ts", + "__tests__/cli-install-init.test.ts", + "--maxWorkers=2", + "--minWorkers=1" + ], + "cwd": "/data/workspace/Chats/109197f0a288be0afa6b7f8902925630f5a0bfde/codegraph", + "started_at": "2026-09-22T02:36:55.849622+00:00", + "revision": "1466021e1855a87f95bec6a7885935e4c412c02e", + "working_tree": " M package.json\n M scripts/pack-npm.sh\n M src/index.ts\n M src/plugins/cli.ts\n M src/plugins/loader.ts\n M src/plugins/package.ts\n?? __tests__/extension-author.test.ts\n?? docs/extensions/\n?? src/plugins/author-template.ts\n?? src/plugins/author.ts\n", + "exit_code": 0, + "seconds": 16.937, + "finished_at": "2026-09-22T02:37:12.786761+00:00", + "summary": [ + "Test Files 6 passed (6)", + "Tests 26 passed (26)", + "Duration 13.98s (transform 4.05s, setup 0ms, collect 9.63s, tests 11.18s, environment 4ms, prepare 891ms)" + ], + "name": "author-focused", + "log_sha256": "8b015c4302523b64d02aa89231844ee62273eee1cc5004dd83aa7a3c3827c4f9", + "source_provenance": "Ran on the uncommitted implementation later saved in 8b30afb328fc8fe0c4d2d0b348d53bdbcb009acc. Runtime/author source was unchanged afterward; documentation and the external acceptance runner were finalized before that commit." + }, + { + "command": [ + "node", + "scripts/validation/extension-author.cjs" + ], + "cwd": "/data/workspace/Chats/109197f0a288be0afa6b7f8902925630f5a0bfde/codegraph", + "started_at": "2026-09-22T02:45:34.362731+00:00", + "revision": "8b30afb328fc8fe0c4d2d0b348d53bdbcb009acc", + "working_tree": "", + "exit_code": 0, + "seconds": 35.338, + "finished_at": "2026-09-22T02:46:09.700357+00:00", + "summary": [], + "name": "author-e2e-verified", + "log_sha256": "0fea1999575dc8d05e7c17023233a13f1b6a32a0758e46271e664bf2850bab98" + }, + { + "command": [ + "node", + "--test", + "scripts/validation/extensions-runtime.test.cjs" + ], + "cwd": "/data/workspace/Chats/109197f0a288be0afa6b7f8902925630f5a0bfde/codegraph", + "started_at": "2026-09-22T02:46:43.214257+00:00", + "revision": "8b30afb328fc8fe0c4d2d0b348d53bdbcb009acc", + "working_tree": "", + "exit_code": 0, + "seconds": 8.019, + "finished_at": "2026-09-22T02:46:51.233044+00:00", + "summary": [], + "name": "author-compiled-workers", + "log_sha256": "55f18f7919ecc0245b730827ae8461cbcd46aac2615fbd5737a68b66da9dd788" + } + ], + "scope": "Author kit and local generated-extension acceptance; not a production release or hosted HTTPS/platform acceptance." +} diff --git a/docs/validation/extensions-author-20260922.md b/docs/validation/extensions-author-20260922.md new file mode 100644 index 000000000..7cbbe1477 --- /dev/null +++ b/docs/validation/extensions-author-20260922.md @@ -0,0 +1,122 @@ +# Extension author tooling acceptance — September 22, 2026 + +Author implementation: `8b30afb328fc8fe0c4d2d0b348d53bdbcb009acc` on +`feature/extensions-author-kit-20260922`. This continues the recovered implementation, +not a second implementation. [Draft PR #1911](https://github.com/colbymchenry/codegraph/pull/1911) +contains the work. No merge, npm publication or production deployment was performed. + +The complete prior checkpoint `1466021e1855a87f95bec6a7885935e4c412c02e` was pushed +first. Git fetch verified both SHA and tree +`5a341950db6cfaa21395100d6f2c709074f85c6a` matched locally, with an empty diff. +The original partial remote branch at `99cdef0c7d1845abbeb9b349f4877f36e0b341f8` +was preserved. Main was `ba3c21e50d9129d2f5f3843ec3728868ae6d47a1` immediately +before publishing. Later author/evidence commits extend the new topic branch. + +## Delivered author path + +- Public package-root exports for `CodeGraphPlugin`, context, framework/synthesis + types, `defineExtension`, API version, starter, packer and test harness. These + work through the existing npm SDK entry and generated declaration tree. +- `codegraph extensions create --id ` emits a standalone CJS + Python event-map example, manifest, test fixtures and README. It refuses to + overwrite an existing directory. No private imports or runtime SDK dependency. +- `codegraph extensions test ` uses the real managed installer and + graph API in disposable non-Node projects. It checks explicit positive/negative + graph expectations, deterministic rebuild and cleanup after removal. +- Compatibility is checked before evaluating author code. Unsupported API, + incompatible engine, malformed extraction arrays/node IDs and missing edge + labels have actionable failures. Empty assertions and unsafe fixture paths fail. +- [External author guide](../extensions/authoring.md), CLI usage, public contracts, + local publisher walkthrough and compatibility limits. The guide ships in the + development npm package and is included by the release shim packaging script. + +Reproducible author commands, using the built preview CLI on PATH: + +```sh +codegraph extensions create ./python-events --id python-events +codegraph extensions test ./python-events +codegraph extensions pack ./python-events --out ./python-events-0.1.0.cgext +codegraph extensions install ./python-events-0.1.0.cgext --path ./python-app +codegraph extensions remove python-events --path ./python-app +``` + +The guide supplies the Python application fixture. No public npm release contains +these commands yet; use the branch build or locally packed development archive. + +## Evidence + +Linux x86-64 / Node 22.23.2. Exact commands, exits, source hashes and generated +graph data are in [the committed receipt](extensions-author-20260922.json). + +| Check | Result | Receipt | +|---|---|---| +| Engine/viewer/grammar build | Exit 0, 121.099 s | `.qa/recovery/author-build-fixed.json` | +| Author, runtime, marketplace, route, npm SDK and CLI regression | 6 files / 26 tests passed, exit 0 | `.qa/recovery/author-focused.json` | +| Fresh external author/package/browser/install exercise | 9 checks, exit 0, 35.338 s at clean `8b30afb` | `.qa/recovery/author-e2e-verified.json` | +| Compiled worker lifecycle/isolation/rollback | 2 tests passed, exit 0, 8.019 s at clean `8b30afb` | `.qa/recovery/author-compiled-workers.json` | +| Packaging shell syntax and diff whitespace | Passed | `bash -n scripts/pack-npm.sh`; `git diff --check` | + +Build and focused tests ran before the author commit. Their receipts correctly +record parent HEAD and dirty source; runtime/author source did not change after +those passes. Only documentation and the external acceptance runner were finalized +before commit. The two clean-commit exercises above validate the compiled build. +The prior 4,545-pass/192-skipped full regression remains evidence for `07b0a10`, +not a claim that the entire suite was rerun on the author-kit commit. + +The fresh author exercise (`scripts/validation/extension-author.cjs`) creates an +author project under a new temporary directory outside core, packages the built +engine locally with `npm pack`, installs that archive as an author development +dependency, and type-checks the generated JSDoc against public declarations. +It then runs the generated CLI test/pack commands through that installed engine. +There is no manual copy of private core source into the extension. + +The generated fixture harness passes eight assertions across two cases: literal +event-to-handler wiring, absent computed/commented events, unresolved unknown +handlers and unresolved ambiguous handlers. Each case also proves deterministic +rebuild and removal cleanup. The runtime is configured to exercise compiled +parse/resolver workers during the external test. + +An actual Chrome browser submitted the generated `.cgext` through the existing +signed local publisher form. The release was community-owned and its integrity +matched the packed bytes. The CLI downloaded that local release URL and installed +it into a separate Python application with no `package.json`. The public graph +API confirmed `event:order.created` → `send_receipt`, labelled `Python event +dispatch`, with extension provenance. Managed removal cleared the route and edge. +There were no browser page errors. Screenshot and command logs are retained under +`.qa/recovery/author-e2e/`; the temporary application/registry were cleaned up. + +Generated artifact SHA-256: +`d87fe94c5016372984c579b31989c036e863b6102bbf027704c7ff8afe21e5c8`. +It includes the generated author's local development manifest/lock file, so a +fresh directory/dependency resolution can change package bytes. Deterministic +graph output, rather than identical npm lock-file paths, is the asserted property. + +Failed preparation attempts remain visible: the first compiler run found a +test-harness type error; the first external exercise needed a writable isolated +npm cache; the next used a synchronous child process that blocked its own local +HTTP registry. The type and runner issues were fixed before the successful run. +Those failures are not counted as passes or presented as production failures. + +## Gates and remaining work + +The EXT-01 external author-kit acceptance described above is complete for this +Linux preview. The original Drupal corpora and broader browser security artifacts +are reused because valid extension behavior and those sources did not change. +This increment does not establish compatibility with every framework or engine. + +Repository main requires one approving PR review, prohibits deletion/non-fast-forward +updates, and has no required status-check rule in the inspected ruleset. Existing +workflows are manual release and main-branch site deployment; there is no PR test +workflow and no hosted CI pass is claimed. + +Still pending: compatible-version fallback; process-kill/stale-lock recovery; +actual Windows/macOS; hosted HTTPS companion acceptance; durable SQLite/artifact +registry hosting and Vercel setup; broader Drupal accuracy and performance review. +The earlier measured Drupal rebuild overhead remains about **22–30%** versus the +built-in resolver, with limited samples and selected boundary-flow coverage. +Agent A/B remained excluded; no extra model sessions were launched. + +Product code-complete: **no**. Validation: **local author milestone passed; broader +acceptance partial**. Hosted preview-ready: **unverified**. Released: **no**. +The next bounded product step is compatible-version resolution, with explicit +fallback/rejection tests against multiple immutable releases, after Klaus review. diff --git a/docs/validation/extensions-recovery-20260922.md b/docs/validation/extensions-recovery-20260922.md index 7cedd8726..1aceb22bb 100644 --- a/docs/validation/extensions-recovery-20260922.md +++ b/docs/validation/extensions-recovery-20260922.md @@ -209,9 +209,11 @@ Per-repository records, hashes and all nine raw responses are under ## Acceptance gaps -- The runtime types and pack command exist, but a usable author template, - dedicated author test harness and complete SDK/author documentation are absent. - These recovery scripts are product-validation tools, not the authoring kit. +- The author-kit gap at this regression checkpoint was subsequently closed for + the Linux preview by `8b30afb`: public SDK exports, starter generation, dedicated + author tests and a fresh generated-extension publish/install/removal exercise. + See [author acceptance](extensions-author-20260922.md) for its separate evidence + and limits; the original recovery scripts alone did not satisfy this gate. - The catalog selects the most recently published release. Installation rejects incompatible engine ranges but does not resolve an older compatible release. - Exception rollback is tested. Process termination between config/database