diff --git a/.github/workflows/plugin-spike.yml b/.github/workflows/plugin-spike.yml new file mode 100644 index 0000000..cbbdc87 --- /dev/null +++ b/.github/workflows/plugin-spike.yml @@ -0,0 +1,40 @@ +name: Plugin integration experiment + +on: + pull_request: + paths: + - "experiments/plugin-spike/**" + - ".github/workflows/plugin-spike.yml" + push: + branches: [main] + paths: + - "experiments/plugin-spike/**" + - ".github/workflows/plugin-spike.yml" + +permissions: + contents: read + +jobs: + experiment: + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest] + runs-on: ${{ matrix.os }} + timeout-minutes: 15 + defaults: + run: + working-directory: experiments/plugin-spike + env: + NPM_CONFIG_REGISTRY: https://registry.npmjs.org + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + with: + node-version: 22 + - run: npm ci --ignore-scripts --no-audit --no-fund + - run: npm test + - name: Install an actual packed consumer and exercise both renderers + run: npm run test:package -- --report artifacts/package-smoke.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 25bbab9..27a7c0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,10 @@ publication remains a separate release-owner action. ### Added +- Retain an isolated TypeScript/Rust/Tauri plugin-integration experiment with + reproducible package checks and bounded source/rendering findings; not released + Rust support. Core landing/catalogue integration remains separate work. + - Add GitHub-only publication of verified tarballs: normal OIDC and explicit first-package bootstrap through version/commit-bound tags, with a UI-managed token exposed only to its publish step. No local npm authentication is needed. diff --git a/experiments/plugin-spike/.gitignore b/experiments/plugin-spike/.gitignore new file mode 100644 index 0000000..6a3a6a3 --- /dev/null +++ b/experiments/plugin-spike/.gitignore @@ -0,0 +1,14 @@ +/node_modules/ +/artifacts/ +/dist/ +/coverage/ +/.cache/ +/npm-cache/ +*.tgz +*.log +*.png +*.jpg +*.jpeg +*.webp +*.webm +.DS_Store diff --git a/experiments/plugin-spike/LICENSE b/experiments/plugin-spike/LICENSE new file mode 100644 index 0000000..a736e9b --- /dev/null +++ b/experiments/plugin-spike/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Dylan McCurry + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/experiments/plugin-spike/README.md b/experiments/plugin-spike/README.md new file mode 100644 index 0000000..6f288bd --- /dev/null +++ b/experiments/plugin-spike/README.md @@ -0,0 +1,187 @@ +# Experimental language/framework integration + +**Retained technical experiment, not production Rust/Tauri support or a public +plugin SDK.** This directory adds no capabilities to the published +`@jdylanmc/topo-code@0.1.0` CLI. It supplies a separate `topo-spike` executable to +test source analysis, baseline-bound explanations and real diagram rendering. + +Read [integration findings](REPORT.md), [measured evidence](evidence/summary.json) +and the [bounded semantic probe receipt](evidence/semantic-probe.json). +Human semantic/visual acceptance remains pending. + +## Install and verify + +Requirements: Node.js 22+, npm, Git, and npm registry access. macOS ARM64 and +Linux x64 are the dedicated CI targets; other platforms are not certified. +Native parser dependencies must have their shipped prebuilds available. + +```sh +cd experiments/plugin-spike +npm ci --ignore-scripts --no-audit --no-fund +npm test +npm run test:package +node bin/topo-spike.mjs --help +``` + +All direct dependencies use exact published versions. The lock retains package +versions and verified integrity values but omits registry-resolved URLs (npm's +`omit-lockfile-registry-resolved` format), avoiding machine-specific mirror URLs. +Npm must look up those versions in the selected registry. It contains no +`file:` dependencies, workspace links or vendored tarballs. +Tests create disposable synthetic repositories, including fixture-only Git +commits. They never build or launch the inspected Rust application. + +`test:package` packs the actual experiment, checks its contents/size, installs it +in a fresh synthetic consumer, invokes the npm bin entrypoint, runs `init`, +`scan`, `validate`, and renders with **both** actual engines. It checks the +partial exit code, supported Tauri source binding, renderer receipts and source +preservation. It is not a browser acceptance test. + +### Registry-constrained local bootstrap + +The original host cannot connect to public npm, and its mirror lacks the two +published Topocode packages. This is an environment limitation, not silently +treated as a successful public-registry install. Hosted CI uses normal npm. +For this host only, obtain the exact release tarballs separately from a +registry-capable machine: + +```sh +npm pack @jdylanmc/topo-code@0.1.0 --ignore-scripts +npm pack @jdylanmc/topo-archify@0.1.0 --ignore-scripts +``` + +Verify their SHA-256 values in [evidence](evidence/summary.json). From this +experiment directory, explicit local bootstrap may install them alongside +ordinary upstream packages: + +```sh +npm install --no-save --package-lock=false --ignore-scripts --no-audit --no-fund \ + --registry=https://packagefeedproxy.microsoft.io/npm \ + --cache=./artifacts/npm-cache \ + /absolute/path/jdylanmc-topo-code-0.1.0.tgz \ + /absolute/path/jdylanmc-topo-archify-0.1.0.tgz +npm test +npm run test:package -- \ + --registry=https://packagefeedproxy.microsoft.io/npm \ + --local-topocode /absolute/path/jdylanmc-topo-code-0.1.0.tgz \ + --local-renderer /absolute/path/jdylanmc-topo-archify-0.1.0.tgz +``` + +The smoke script verifies the exact release bytes before this explicit local +install. This is **not** proof that public-registry `npm ci` ran on that host. +No global npm configuration, credentials, install hooks, rebuilt release +substitutes or hidden checkout symlinks are needed. Tarballs, caches and +historical full artifacts stay ignored locally; they are not part of this PR. + +## Use in an isolated consumer + +Package the retained source, then install its tarball in a **separately +authorized disposable consumer**: + +```sh +mkdir -p artifacts +npm run pack:local +# In the consumer: +npm install --save-dev --save-exact --ignore-scripts \ + /absolute/path/topocode-plugin-spike-0.1.0-spike.1.tgz +npm exec --no -- topo-spike init . +npm exec --no -- topo-spike scan . --allow-partial +``` + +`init` installs shipped Topocode/spike instructions and configuration without +overwriting conflicting existing guidance. It does not modify `AGENTS.md`, +activate orchestration or start an application/server. + +**Partial scans exit 2**, including with `--allow-partial`. Without that flag, +partial analysis publishes no baseline and exits 1. The explicit flag permits a +limited-evidence preview, not a claim of semantic completeness. + +Read the installed [authoring guidance](skills/topo-plugin-spike/SKILL.md): + +```sh +npm exec --no -- topo-spike inspect .topo/cache/plugin-spike/baseline.json --query review --limit 20 +npm exec --no -- topo-spike validate . .topo/cache/plugin-spike/baseline.json stories/review.topo-view.json +npm exec --no -- topo-spike render . .topo/cache/plugin-spike/baseline.json stories/review.topo-view.json \ + --output .topo/cache/plugin-spike/review.html +npm exec --no -- topo-spike book . .topo/cache/plugin-spike/baseline.json stories/*.topo-view.json \ + --renderer graphviz --output .topo/cache/plugin-spike/book +``` + +Keep a rendered wrapper with its adjacent `.native.html`, `.spec.json`, +`.evidence.json` and `.receipt.json`. Use `node scripts/serve-artifacts.mjs +` for an optional loopback preview; open its explicit HTML +path and stop the process when finished. + +For PR-Sniper, check out the public source commit linked in +[evidence](evidence/summary.json) in your own disposable directory, install the +experiment there, and use the same commands. Do not run Cargo/build.rs/proc +macros or the application. Source/dependency state can change analysis counts; +the historical counts are not an invariant oracle. + +## Data and rendering boundaries + +- Explicit first-party plugin registry; no arbitrary loader or marketplace. +- Captured source inventory and deterministic contribution contract. TypeScript + uses the published package's bundled **private** compiler adapter, not a + supported SDK. Rust uses Tree-sitter through AST-grep; no compiler/Cargo/model + runs during `scan`. +- Native Rust kinds/private declarations and declared Cargo/module evidence. + Calls, cfg, unexpanded macros, import aliases and unsupported bindings remain + explicit. The pinned grammar has an `unsafe extern` recovery gap. +- Tauri joins are bounded source bindings with lexical-shadow/mutation checks, + not proof of runtime reachability, permissions or authorization. +- Source-derived connections must cite matching baseline topology. Authored + `source-traced` connections require snapshot-bound exact code excerpts and + remain labeled **agent source traces**, not compiler control-flow graphs. + Inference needs its own rationale and visible label. +- Source changes invalidate views. Regenerate and deliberately reconcile; + never edit derived baselines or ignore stale-source errors. Artifact sets are + staged and rolled back after reported publication failures, not crash-atomic. + Books prepare every chapter and companion file before publishing one set + containing those files, `index.html` and `book.json`. Chapter ID `index` is + reserved and rejected before writes. +- Default rendering uses pristine Archify 3.0.0 via the published renderer CLI + and requires all nine native showcase checks. Dense branch-heavy pages may + exceed its layout capability; failures remain explicit. +- `--renderer graphviz` selects Graphviz 16.0.0 WASM through + `@viz-js/viz@3.30.0`. Its receipts identify that engine and its distinct + structural checks; **they do not claim Archify's nine checks**. + +## Stopping point and next integration + +The experiment establishes a useful partial source-to-explanation loop and +documents where it fails. It does not establish a supported plugin API, +production language compatibility, complete Rust semantics or human acceptance. +The separate controlled rust-analyzer probe is **historical evidence only**; +no LSP launcher or compiler integration ships in the default plugin. Its precise +method, source fixture, tool prerequisites and limits are recorded in +[the semantic receipt](evidence/semantic-probe.json). + +**The current book `index.html` is the first diagram with chapter navigation. +It is not the missing branded core landing/catalogue experience.** Core +`topo init` landing/catalogue integration is the **next, separate deliverable** +and must not be represented as completed by this PR. + +## Optional historical browser reproduction + +Full historical views/screenshots/baselines are deliberately not committed. +The portable evidence JSON records measured results and original artifact +hashes, not links to absent local files. Given your own authored technical book, +`render-pr-sniper-guide.mjs` consumes its explicitly supplied consumer directory +and `.topo/cache/plugin-spike/meaningful-guide/manifest.json` page list. +`check-guide.mjs [chapter-id]` additionally +requires Playwright and a browser already installed in that consumer. +`PLAYWRIGHT_CHANNEL` optionally selects an existing browser; no browser is +downloaded by the script. These helpers are not prerequisites for static scans. +Empty manifests and unmatched chapter selections are rejected before browser +loading/launch. Successful measurement reports require the full nonzero +selected-chapter-by-viewport count. + +## Licenses + +First-party source is [MIT](LICENSE). Dependencies retain their own notices. +AST-grep NAPI is MIT; `@iarna/toml` declares ISC. +`@ast-grep/lang-rust@0.0.7` declares ISC in package metadata but ships an MIT +`LICENSE`; that upstream labeling discrepancy remains explicit for adoption +review. The published renderer retains Archify and font notices. Graphviz WASM +retains its package and Graphviz notices. diff --git a/experiments/plugin-spike/REPORT.md b/experiments/plugin-spike/REPORT.md new file mode 100644 index 0000000..30f5bfd --- /dev/null +++ b/experiments/plugin-spike/REPORT.md @@ -0,0 +1,134 @@ +# Integration findings: retained experiment + +**Logical learning stop reached; production adoption and human acceptance are +not claimed.** The retained source is executable independently of a development +Topocode checkout. Measured historical results are in +[summary.json](evidence/summary.json); source revisions are immutable public +links. The full original report and generated artifacts were preserved locally +before this portable report was curated. They are intentionally not PR content. + +## What worked + +The explicit TypeScript/Rust/Tauri plugin composition produced deterministic, +source-relative facts, per-plugin coverage, supported command bindings and +honest unresolved inventories. Private Rust functions and native +struct/trait/impl kinds remain useful without pretending Rust is TypeScript. +All 53 observed Rust commands had declared Cargo/module paths. + +A real installed consumer exercised npm-bin initialization, baseline +inspection, authored/refined views, stale-source failures and renderer output. +The recorded combined snapshot held 148 source/configuration files, 3,069 +entities, 5,242 relationships and 63 Tauri binding observations, with 17,784 +unresolved references and **partial** coverage. These are historical +source/dependency-state observations, not whole-program truth. + +The source-change exercise temporarily replaced one frontend invoke command, +verified stale-baseline rejection, regenerated an explicitly unresolved +sentinel, reconciled an authored view, and restored exact original bytes. +144 original instruction/context files and 146 original non-dependency source +files retained their hashes. This curation does not repeat or modify PR-Sniper. + +## Failures that changed the design + +The first package candidate's npm-bin symlink exited successfully without +executing. The entry guard and actual symlink/packed-consumer tests now cover +that defect. Early diagrams were shallow and had label collisions; grouping +was not accepted as a substitute for preserving technical branches. + +Independent prototype review identified five consequential fidelity failures: + +1. Bare handler names incorrectly joined a root command despite local shadowing. +2. Written TypeScript helper parameters retained obsolete arguments, including + assertion/non-null/destructuring forms. +3. Shared constants collapsed invocation identities and discarded evidence. +4. Same-line declarations received incorrect ownership. +5. Late output failures left mixed-generation artifacts. + +The reviewed corrections retain lexical bindings/ancestry, conservative +mutation handling, binding-site identities, full column containment and +staged output-set rollback. Historical independent fix-review reported all five +resolved, with positive controls. That review is **not approval of this new +curation commit**, a security audit or manual semantic acceptance. + +The curation PR's independent whole review subsequently found three further +defects: books published chapters before the complete book was ready, chapter +ID `index` collided with the book entry page, and an empty browser-check +selection could report success. The correction prepares the entire book before +one rollback-capable publication, reserves `index`, and requires a nonzero +complete measurement count. Tests cover second-chapter render failure, late +book publication rollback, reserved-ID preservation, and executable empty/ +unmatched selection rejection. Independent verification of these corrections +remains pending; rollback is still not crash-atomic publication. + +## Rendering: two engines, different evidence + +Simple native Archify 3.0.0 pages passed all nine showcase checks and ten +desktop browser cases. Their minimum effective text size was 14.1067 px; +native SVG/PNG exports and the detailed/grouped views were retained. + +The deeper five-chapter technical guide required explicit branches, predicates +and short exact source excerpts: **39 nodes, 55 edges, 336 excerpts across +19 source files**. Bounded native layout attempts failed. The retained +alternative uses **Graphviz 16.0.0 WASM**, package `@viz-js/viz@3.30.0`, for +decision/data shapes and branch-heavy layouts. Its receipts name the engine; +they do not borrow the native Archify nine-check claim. + +Those Graphviz pages passed 15 measured desktop cases at 1440x900, 1600x1000 +and 1920x1080, with minimum effective text size 12.1319 px. Node-to-source +focus, chapter navigation and SVG export were observed. These bounded results +do not guarantee arbitrary diagrams, fonts, browsers or viewport sizes. +Source-traced edges prove exact excerpt attachment, **not compiler CFG**. + +## Rust semantics: separately bounded, not integrated + +Exactly two rust-analyzer LSP attempts used an explicit JSON project: a +two-module synthetic trait/cfg fixture and a hash-verified PR-Sniper source +snapshot. Seven synthetic oracles passed; the real snapshot returned 92 +top-level symbols, correct local/cross-module definitions, 45 references to +`GithubAuth` and 13 outgoing local calls from `run`. + +Requests followed actual negotiated capabilities and quiescent protocol status. +Each attempt ran only pinned rustc version/cfg queries. Cargo, rustup, builds, +proc macros and provisioning did not run. An optional unstable target-spec +query was denied; the initial conservative gate failure and subsequent audit +are both retained in [the compact receipt](evidence/semantic-probe.json). +Targets stayed empty, both servers exited cleanly, and **no OS sandbox claim** +is made. + +No sysroot/rust-src, external dependency graph or macro expansion was loaded. +Explicit cfg assumptions are not complete Cargo configuration. Portabilizing +the full guarded launcher would widen this curation into a new semantic +implementation, so only the precise fixture/method/receipt is retained. +There is no claim that an unshipped live probe is reproducible by a bundled +command. Static parser-backed scanning remains runnable. + +## Portability and review gate + +The source package uses exact published `@jdylanmc/topo-code@0.1.0` and +`@jdylanmc/topo-archify@0.1.0`; no release tarballs or source-checkout links +are committed. Npm's URL-free lock format retains original versions/integrities +without manufacturing public-registry metadata. Local release tarballs were +hash/manifest verified and the constrained-host bootstrap is explicit. + +The new isolated Node 22 macOS/Linux workflow performs normal +`npm ci --ignore-scripts`, all experiment tests, then actual packed-consumer +init/scan/validate/render. Existing production CI is untouched. Hosted execution +and independent review of the curated commit remain provider/coordinator gates; +local evidence must not be relabeled as those gates passing. +Local curation passed **80 tests on Node 22.23.2 and 24.20.0**. A fresh +standalone source copy passed all 80 tests using the explicit local release +bootstrap without changing its portable lock. Actual packed-consumer +init/scan/validate and both renderer routes passed on both Node versions. + +## Next: separate core landing/catalogue deliverable + +The current book index copies the first diagram and adds chapter links. +**It does not implement the branded core landing/catalogue required after +`topo init`.** That is the coordinator's next **separate PR**, not unfinished +Rust functionality to sneak into this experiment. + +Production adoption also needs a supported scanner/plugin boundary, +compatibility/version policy, platform/license review and stronger semantic +coverage where promised. No plugin marketplace, production Rust/Tauri release, +universal runtime reachability, completed human approval or release authority +is implied by retaining this experiment. diff --git a/experiments/plugin-spike/bin/topo-spike.mjs b/experiments/plugin-spike/bin/topo-spike.mjs new file mode 100755 index 0000000..a1a38dc --- /dev/null +++ b/experiments/plugin-spike/bin/topo-spike.mjs @@ -0,0 +1,143 @@ +#!/usr/bin/env node +import { parseArgs } from "node:util"; +import { resolve } from "node:path"; +import { pathToFileURL } from "node:url"; +import { realpath } from "node:fs/promises"; +import { scanBaseline, readBaseline, writeArtifact } from "../src/baseline.mjs"; +import { serialize } from "../src/contract.mjs"; +import { assertBaselineCurrent } from "../src/inventory.mjs"; +import { initialize } from "../src/initialize.mjs"; +import { readView, renderView, renderBook, validateViewEvidence } from "../src/view.mjs"; + +const HELP = `Topocode plugin spike (EXPERIMENTAL; not published Rust support) + + topo-spike init + topo-spike scan [--output file] [--plugins typescript,rust,tauri] [--allow-partial] + topo-spike inspect [--query text] [--entity id] [--relationship id] [--limit 20] + topo-spike validate + topo-spike render --output diagram.html + topo-spike book [more.json ...] --output directory [--renderer archify|graphviz] + +Partial analysis requires --allow-partial to publish a baseline and exits 2. +Source-derived connections must cite baseline relationships with matching endpoints. +Inferred connections require an explicit classification and rationale. +Agent source-traced connections require snapshot-bound exact code excerpts. +No model, Cargo build, procedural macro, application, or package installation is invoked. +`; + +export function inspectBaseline(baseline, values) { + const limit = Number(values.limit ?? 20); + if (!Number.isSafeInteger(limit) || limit < 1 || limit > 200) throw new Error("--limit must be an integer from 1 to 200"); + const query = (values.query ?? "").toLowerCase(); + const allEntities = new Map(baseline.entities.map((entity) => [entity.id, entity])); + const entityMatches = baseline.entities.filter((entity) => values.entity + ? entity.id === values.entity + : `${entity.id} ${entity.name} ${entity.qualifiedName} ${entity.location.path} ${entity.kind}`.toLowerCase().includes(query)); + if (values.entity && !entityMatches.length) throw new Error(`Unknown entity: ${values.entity}`); + const matchingIds = new Set(entityMatches.map(({ id }) => id)); + const relationshipMatches = baseline.relationships.filter((relationship) => values.relationship + ? relationship.id === values.relationship + : values.entity + ? relationship.from === values.entity || relationship.to === values.entity + : !query || matchingIds.has(relationship.from) || matchingIds.has(relationship.to) || + `${relationship.id} ${relationship.kind}`.toLowerCase().includes(query)); + if (values.relationship && !relationshipMatches.length) throw new Error(`Unknown relationship: ${values.relationship}`); + const relationships = relationshipMatches.slice(0, limit); + const entities = values.relationship + ? [...new Set(relationships.flatMap(({ from, to }) => [from, to]))].map((id) => allEntities.get(id)) + : entityMatches.slice(0, limit); + const unresolvedMatches = baseline.unresolved.filter((item) => + `${item.text} ${item.location.path} ${item.reason}`.toLowerCase().includes(query)); + return { + baselineId: baseline.id, repository: baseline.repository, coverage: baseline.coverage, + totals: { entities: baseline.entities.length, relationships: baseline.relationships.length, unresolved: baseline.unresolved.length }, + matching: { entities: entityMatches.length, relationships: relationshipMatches.length, unresolved: unresolvedMatches.length }, + truncated: { entities: !values.relationship && entityMatches.length > entities.length, + relationships: relationshipMatches.length > relationships.length, unresolved: unresolvedMatches.length > limit }, + entities, relationships, + relatedEntities: [...new Set(relationships.flatMap(({ from, to }) => [from, to]))] + .filter((id) => !entities.some((entity) => entity.id === id)).map((id) => allEntities.get(id)), + unresolved: unresolvedMatches.slice(0, limit), + }; +} + +export async function run(args) { + const { values, positionals } = parseArgs({ + args, allowPositionals: true, + options: { + help: { type: "boolean", short: "h" }, output: { type: "string" }, plugins: { type: "string" }, + "allow-partial": { type: "boolean" }, "repository-id": { type: "string" }, + query: { type: "string" }, entity: { type: "string" }, relationship: { type: "string" }, + limit: { type: "string" }, renderer: { type: "string" }, + }, + }); + const [command, ...inputs] = positionals; + if (values.help || !command || command === "help") { console.log(HELP); return 0; } + if (command === "init") { + if (inputs.length !== 1) throw new Error("init requires one repository path"); + console.log(serialize(await initialize(inputs[0])).trim()); + return 0; + } + if (command === "scan") { + if (inputs.length !== 1) throw new Error("scan requires one repository path"); + const baseline = await scanBaseline(inputs[0], { + ...(values.plugins ? { plugins: values.plugins.split(",") } : {}), + ...(values["repository-id"] ? { repositoryId: values["repository-id"] } : {}), + }); + const partial = baseline.coverage.status !== "complete"; + if (partial && !values["allow-partial"]) { + console.error(serialize({ coverage: baseline.coverage, diagnostics: baseline.diagnostics }).trim()); + throw new Error("Analysis is partial; no baseline was published. Use --allow-partial only for an explicit limited-evidence preview."); + } + const output = resolve(values.output ?? `${inputs[0]}/.topo/cache/plugin-spike/baseline.json`); + await writeArtifact(output, serialize(baseline)); + console.log(serialize({ + baselineId: baseline.id, output, status: baseline.coverage.status, + entities: baseline.entities.length, relationships: baseline.relationships.length, + unresolved: baseline.unresolved.length, plugins: baseline.plugins.map(({ id }) => id), + }).trim()); + return partial ? 2 : 0; + } + if (command === "inspect") { + if (inputs.length !== 1) throw new Error("inspect requires one baseline JSON file"); + console.log(serialize(inspectBaseline(await readBaseline(inputs[0]), values)).trim()); + return 0; + } + if (command === "validate" || command === "render") { + if (inputs.length !== 3) throw new Error(`${command} requires repository, baseline JSON, and authored view JSON`); + const [root, baselinePath, viewPath] = inputs; + const baseline = await readBaseline(baselinePath); + const view = await readView(viewPath); + const source = await assertBaselineCurrent(root, baseline); + validateViewEvidence(baseline, view, source.files); + if (command === "validate") { + console.log(serialize({ validReferences: true, baselineId: baseline.id, + coverage: baseline.coverage.status, semanticTruth: "requires human review" }).trim()); + } else { + if (!values.output) throw new Error("render requires an explicit --output HTML path"); + console.log(serialize(await renderView(root, baseline, view, values.output, { renderer: values.renderer })).trim()); + } + return 0; + } + if (command === "book") { + if (inputs.length < 3 || !values.output) throw new Error("book requires repository, baseline, views and --output directory"); + const [root, baselinePath, ...paths] = inputs; + const baseline = await readBaseline(baselinePath); + const views = await Promise.all(paths.map(readView)); + console.log(serialize(await renderBook(root, baseline, views, resolve(values.output), { renderer: values.renderer })).trim()); + return 0; + } + throw new Error(`Unknown command: ${command}`); +} + +let invokedPath; +if (process.argv[1]) { + try { invokedPath = await realpath(resolve(process.argv[1])); } + catch (error) { if (error.code !== "ENOENT") throw error; } +} +if (invokedPath && pathToFileURL(invokedPath).href === import.meta.url) { + run(process.argv.slice(2)).then((code) => { process.exitCode = code; }).catch((error) => { + console.error(`Topocode plugin spike: ${error.message}`); + process.exitCode = 1; + }); +} diff --git a/experiments/plugin-spike/evidence/semantic-fixture/lib.rs b/experiments/plugin-spike/evidence/semantic-fixture/lib.rs new file mode 100644 index 0000000..ab47885 --- /dev/null +++ b/experiments/plugin-spike/evidence/semantic-fixture/lib.rs @@ -0,0 +1,10 @@ +mod model; +mod worker; + +pub fn entry() -> u32 { + worker::execute() +} + +pub fn dynamic(task: &dyn model::Task) -> u32 { + task.run() +} diff --git a/experiments/plugin-spike/evidence/semantic-fixture/model.rs b/experiments/plugin-spike/evidence/semantic-fixture/model.rs new file mode 100644 index 0000000..fff9e52 --- /dev/null +++ b/experiments/plugin-spike/evidence/semantic-fixture/model.rs @@ -0,0 +1,9 @@ +pub trait Task { + fn run(&self) -> u32; +} + +#[cfg(feature = "enabled")] +pub fn selected() -> u32 { 7 } + +#[cfg(not(feature = "enabled"))] +pub fn selected() -> u32 { 9 } diff --git a/experiments/plugin-spike/evidence/semantic-fixture/worker.rs b/experiments/plugin-spike/evidence/semantic-fixture/worker.rs new file mode 100644 index 0000000..1332bde --- /dev/null +++ b/experiments/plugin-spike/evidence/semantic-fixture/worker.rs @@ -0,0 +1,11 @@ +use crate::model::{Task, selected}; + +pub struct Worker; + +impl Task for Worker { + fn run(&self) -> u32 { selected() } +} + +pub fn execute() -> u32 { + Worker.run() +} diff --git a/experiments/plugin-spike/evidence/semantic-probe.json b/experiments/plugin-spike/evidence/semantic-probe.json new file mode 100644 index 0000000..5a04861 --- /dev/null +++ b/experiments/plugin-spike/evidence/semantic-probe.json @@ -0,0 +1,200 @@ +{ + "schemaVersion": 1, + "status": "bounded-historical-feasibility-evidence", + "analyzer": "rust-analyzer 0.0.0 (682a84e95b 2026-09-13)", + "toolchain": "1.98.1-aarch64-apple-darwin", + "attempts": 2, + "liveLauncherShipped": false, + "osSandboxClaimed": false, + "cargoInvocations": 0, + "rustupInvocations": 0, + "procMacroExecution": false, + "fixture": { + "root": "semantic-fixture/lib.rs", + "modules": [ + "semantic-fixture/model.rs", + "semantic-fixture/worker.rs" + ], + "edition": "2021", + "cfg": [ + "unix", + "target_os=\"macos\"", + "target_arch=\"aarch64\"", + "target_pointer_width=\"64\"", + "target_endian=\"little\"", + "target_family=\"unix\"", + "feature=\"enabled\"" + ], + "dependencies": [], + "sysroot": null + }, + "profile": { + "project": "Explicit linked JSON single-crate project; no Cargo project discovery.", + "configuration": { + "cargo": { + "autoreload": false, + "sysroot": null, + "sysrootSrc": null, + "buildScripts": { + "enable": false, + "rebuildOnSave": false + } + }, + "checkOnSave": false, + "procMacro": { + "enable": false, + "attributes": { + "enable": false + } + }, + "rustc": { + "source": null + }, + "cachePriming": { + "enable": false + }, + "diagnostics": { + "enable": false + } + }, + "environment": "Isolated HOME/CARGO_HOME/RUSTUP_HOME/TMPDIR/cache/target; offline Cargo setting; fixed PATH with deny-by-default tool guards; explicit pinned rustc.", + "allowedPerAttempt": [ + [ + "rustc", + "-vV" + ], + [ + "rustc", + "--version" + ], + [ + "rustc", + "--print", + "cfg", + "-O", + "--target", + "aarch64-apple-darwin" + ] + ], + "deniedPerAttempt": [ + [ + "rustc", + "-Z", + "unstable-options", + "--print", + "target-spec-json", + "--target", + "aarch64-apple-darwin" + ] + ], + "initialAnyDenialGate": { + "synthetic": false, + "real": false + }, + "reviewedNonBuildingGate": { + "synthetic": true, + "real": true + }, + "audit": "Initial conservative gate rejected any denied command. Audit found only the exact optional rustc -Z target-spec-json metadata request; it stayed DENIED and was never executed. No guard expansion, build, download, sysroot installation or synthetic retry." + }, + "protocol": { + "transport": "Standard JSON-RPC LSP over stdio", + "negotiated": [ + "textDocument/documentSymbol", + "textDocument/definition", + "textDocument/references", + "textDocument/prepareCallHierarchy", + "callHierarchy/incomingCalls", + "callHierarchy/outgoingCalls" + ], + "readiness": "Actual experimental/serverStatus quiescent notification before queries; autoreload-disabled warning retained.", + "syntheticOracles": [ + { + "name": "cross-module-definition", + "passed": true + }, + { + "name": "trait-definition", + "passed": true + }, + { + "name": "cfg-enabled-definition", + "passed": true + }, + { + "name": "method-definition", + "passed": true + }, + { + "name": "dynamic-trait-not-invented-concrete-target", + "passed": true + }, + { + "name": "call-hierarchy-cross-module-target", + "passed": true + }, + { + "name": "references-include-cross-module-trait-use", + "passed": true + } + ], + "realQueries": [ + { + "name": "real-document-symbols", + "resultCount": 92, + "status": "responded" + }, + { + "name": "local-GithubAuth-definition", + "resultCount": 1, + "status": "responded" + }, + { + "name": "cross-module-Store-definition", + "resultCount": 1, + "status": "responded" + }, + { + "name": "local-GithubAuth-references", + "resultCount": 45, + "status": "responded" + }, + { + "name": "real-run-call-hierarchy", + "resultCount": 1, + "status": "responded" + } + ], + "realOutgoingLocalCallsFromRun": 13, + "realDefinitionOracles": [ + { + "symbol": "GithubAuth", + "url": "https://github.com/jdylanmc/pr-sniper/blob/9222f8a8b5abe0e65223703a1bf80e994db7f9cc/src-tauri/src/lib.rs#L66" + }, + { + "symbol": "Store", + "url": "https://github.com/jdylanmc/pr-sniper/blob/9222f8a8b5abe0e65223703a1bf80e994db7f9cc/src-tauri/src/storage.rs#L416" + } + ], + "bothServersExited": 0, + "targetDirectoriesEmpty": true + }, + "inputBoundary": "Hash-verified source snapshot only; no Cargo.toml, build.rs, proc-macro libraries, dependencies or runtime files copied into the language-server project.", + "limitations": [ + "No rust-src/sysroot", + "No external dependency crate graph", + "No procedural macros/build.rs", + "Explicit cfg assumptions, not Cargo feature/target resolution", + "Not whole-program reachability or compiler validation" + ], + "liveReproduction": { + "status": "Not supplied as a runnable launcher; no new semantic experiments during curation.", + "prerequisites": "A separately approved guarded LSP client, matching installed analyzer/toolchain, explicit JSON project/isolated environment and monitored command policy. Rust-src was absent. Settings are not an OS sandbox.", + "fixtureOnly": "The included sources preserve the synthetic input, not a complete packaged semantic backend." + }, + "originalReceiptSha256": { + "summary": "166f527e128e634d263d5d111a333ab76314ad4e8013a3400fe72b79f1060876", + "syntheticProtocol": "74ff5ffed800d21870a6a8c64ee8839e3c1b8b10a63d5264f4cb0720da583476", + "realProtocol": "0bd34fd103c199c4766ccae5a6421b8162babab46815d216beaf308e0afe2c51" + } +} diff --git a/experiments/plugin-spike/evidence/summary.json b/experiments/plugin-spike/evidence/summary.json new file mode 100644 index 0000000..a157a46 --- /dev/null +++ b/experiments/plugin-spike/evidence/summary.json @@ -0,0 +1,201 @@ +{ + "schemaVersion": 1, + "status": "historical-measurements-not-human-acceptance", + "scope": "Retained local plugin integration experiment; not released Rust/Tauri support.", + "source": { + "topocode": { + "commit": "b64bb2fc9c1ba6319287f7c701588eee3de2d1d5", + "url": "https://github.com/jdylanmc/topo-code/tree/b64bb2fc9c1ba6319287f7c701588eee3de2d1d5" + }, + "rendererPackaging": { + "commit": "b94790e99e2ca51fcdb74a9bd0f10f637856f92f", + "url": "https://github.com/jdylanmc/topo-archify/tree/b94790e99e2ca51fcdb74a9bd0f10f637856f92f" + }, + "consumer": { + "commit": "9222f8a8b5abe0e65223703a1bf80e994db7f9cc", + "url": "https://github.com/jdylanmc/pr-sniper/tree/9222f8a8b5abe0e65223703a1bf80e994db7f9cc" + } + }, + "publishedDependencies": [ + { + "name": "@jdylanmc/topo-code", + "version": "0.1.0", + "sha256": "f2248386c8aa9cf3c141a32eafffdce3117a2ab56aa91595c36cf164ffc40f64" + }, + { + "name": "@jdylanmc/topo-archify", + "version": "0.1.0", + "sha256": "d32492b080b1fbc8126506d83678d3bdbf321ab935d0b74e89586576b58c4d27" + } + ], + "analysis": { + "baselineId": "sha256:f678655f318fd7a79cbce6ac53e2e2cf017457d702951061705cd0acf2466e97", + "files": 148, + "entities": 3069, + "relationships": 5242, + "tauriBindings": 63, + "unresolved": 17784, + "coverage": "partial", + "rust": { + "entities": 2552, + "syntaxRelationships": 1592, + "declaredCommandPaths": 53 + }, + "caveat": "Counts bind to the historical consumer source/dependency snapshot, not every checkout or compiler semantics." + }, + "rendering": { + "native": { + "engine": "Archify 3.0.0", + "checksPassed": 9, + "browserCases": 10, + "minimumEffectiveTextPx": 14.106666666666667, + "viewports": [ + "1024x768", + "1280x720", + "1440x900", + "1600x1000", + "1920x1080" + ], + "evidenceScope": "Earlier simple detailed/grouped consumer views; not the later dense technical guide.", + "exports": [ + "SVG", + "PNG" + ] + }, + "technical": { + "engine": "Graphviz 16.0.0", + "package": "@viz-js/viz@3.30.0", + "chapters": 5, + "nodes": 39, + "edges": 55, + "excerpts": 336, + "sourceFiles": 19, + "browserCases": 15, + "minimumEffectiveTextPx": 12.131868131868131, + "viewports": [ + "1440x900", + "1600x1000", + "1920x1080" + ], + "nodesPreserved": true, + "noClippingOrTextOverlap": true, + "nodeToSource": true, + "chapterNavigation": true, + "svgExport": true, + "archifyChecksClaimed": false, + "classification": "Exact source-excerpt traces, not automatically resolved compiler control flow.", + "chaptersAndArtifactHashes": [ + { + "id": "pr-sniper-native-lifetime", + "sections": 8, + "edges": 9, + "htmlSha256": "430080f990744f6d66cae60e599022a4b24fdaf281eecbcfb2ef361ae7163ed4" + }, + { + "id": "pr-sniper-ui-native", + "sections": 7, + "edges": 7, + "htmlSha256": "ab5c02a30689055ceaa4e017aff515355f2f5b7cd3caaed881da9e687ccb6aa7" + }, + { + "id": "pr-sniper-check-admission", + "sections": 8, + "edges": 11, + "htmlSha256": "6205a3fb6507a043731cbe0d63359fdfe8805aa5167a04d69c37306fbcbef96b" + }, + { + "id": "pr-sniper-copilot-session", + "sections": 8, + "edges": 13, + "htmlSha256": "f23d0ff136400cabaf33357802b6d9344e645456c3846d8a61a26fd25f49330e" + }, + { + "id": "pr-sniper-publication-recovery", + "sections": 8, + "edges": 15, + "htmlSha256": "946e8d2567f2d9d7ead2ad3f484bbf13967473654f0edc7f314d8557fa539ce1" + } + ] + } + }, + "preservation": { + "originalContextFileHashes": 144, + "originalNonDependencySourceFileHashes": 146, + "applicationSourceDiff": "", + "sentinelInvokeExercise": { + "staleAttemptsRejected": 4, + "lastGoodFilesPreserved": 13, + "unknownCommandReportedUnresolved": true, + "exactSourceBytesRestored": true, + "caveat": "Earlier installed-consumer exercise; not rerun during PR curation." + } + }, + "testing": { + "preCurationTestsPassed": 77, + "curationVerification": { + "testsPassed": 80, + "nodeVersions": ["22.23.2", "24.20.0"], + "platform": "macOS arm64", + "standaloneSourceCopy": "Installed with explicit local release tarballs; all 80 tests passed and committed lock stayed unchanged.", + "packedConsumer": "Actual npm pack/install/bin init/partial scan/validate/render with Archify and Graphviz passed on both Node versions.", + "publicRegistryInstall": "Not verified on the local host: public npm transport failed; hosted workflow remains pending.", + "browserScope": "Historical matrices above; curation did not repeat browser or human acceptance." + }, + "liveTestCommand": "npm test", + "packedConsumerCommand": "npm run test:package", + "hostedCuratedCommit": "Pending dedicated Node 22 macOS/Linux workflow; local proof is not hosted proof." + }, + "review": { + "scope": "Local experimental TypeScript/Rust/Tauri prototype; not production approval or a general security audit", + "originalFindings": 5, + "historicalDisposition": "All five original findings resolved within the bounded review; no additional consequential defect reported", + "findings": [ + { + "issue": "Rust local handler shadowing could bind a root declaration", + "status": "resolved" + }, + { + "issue": "Written helper parameters could fabricate obsolete command bindings", + "status": "resolved" + }, + { + "issue": "Shared constants collapsed invocation identity and discarded evidence", + "status": "resolved" + }, + { + "issue": "Same-line declarations received incorrect invocation ownership", + "status": "resolved" + }, + { + "issue": "Late artifact writes left mixed generations", + "status": "resolved for reviewed reported-I/O failures" + } + ], + "curatedCommitIndependentReview": "pending" + }, + "failedApproaches": [ + "First package bin symlink was a no-op; installed npm-bin execution is now tested.", + "Initial shallow/manual-routed diagrams lost useful detail and collided; not accepted as technical depth.", + "Bounded native Archify dense-branch layouts failed; Graphviz is an explicit alternative, not relabeled Archify output." + ], + "nextCoreDeliverable": { + "implementedHere": false, + "title": "Branded core init landing/catalogue", + "currentBookIndex": "First diagram plus chapter navigation", + "delivery": "Separate core PR" + }, + "limitations": [ + "Historical full baselines, HTML, screenshots and logs are deliberately not committed; receipt hashes identify locally preserved originals.", + "Private published Topocode scanner boundary; no supported public plugin SDK or marketplace.", + "Rust calls/macros/cfg remain partial; pinned grammar recovers modern unsafe extern syntax.", + "Tauri source bindings are not runtime reachability or authorization.", + "Human semantic/visual acceptance remains pending." + ], + "originalLocalReceiptSha256": { + "nativeBrowser": "e92a7f6a32511903467bbd78a98a7988fb1018d7ec075d430632c646ae5c1207", + "technicalBrowser": "3261928c0799c324de4bceebd8a00c9a0f7778e44207cc40d5033ece742cca07", + "sourcePreservation": "35387dc5d6b71858f1385ba7789290cf2eba6d86cec3022bc5db208dcee9a4a9", + "technicalGuide": "60c76082be5863475ac2b12fd90c6d243b4c4cd06a2583b0511828c829e3bfb1", + "independentReview": "cdb20f06e0ea3943fe47b98bd27496c3c650d9e3db48ea5ac05ad7d2bd98b4e1" + } +} diff --git a/experiments/plugin-spike/package-lock.json b/experiments/plugin-spike/package-lock.json new file mode 100644 index 0000000..4f9c93d --- /dev/null +++ b/experiments/plugin-spike/package-lock.json @@ -0,0 +1,467 @@ +{ + "name": "topocode-plugin-spike", + "version": "0.1.0-spike.1", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "topocode-plugin-spike", + "version": "0.1.0-spike.1", + "license": "MIT", + "dependencies": { + "@ast-grep/lang-rust": "0.0.7", + "@ast-grep/napi": "0.45.3", + "@iarna/toml": "2.2.5", + "@jdylanmc/topo-archify": "0.1.0", + "@jdylanmc/topo-code": "0.1.0", + "@viz-js/viz": "3.30.0" + }, + "bin": { + "topo-spike": "bin/topo-spike.mjs" + }, + "engines": { + "node": ">=22" + } + }, + "node_modules/@ast-grep/lang-rust": { + "version": "0.0.7", + "integrity": "sha1-pwVjcpEXYLUc5zQlCRC27+OJh+4=", + "hasInstallScript": true, + "license": "ISC", + "dependencies": { + "@ast-grep/setup-lang": "0.0.6" + }, + "peerDependencies": { + "tree-sitter-cli": "0.25.8" + }, + "peerDependenciesMeta": { + "tree-sitter-cli": { + "optional": true + } + } + }, + "node_modules/@ast-grep/napi": { + "version": "0.45.3", + "integrity": "sha1-XtDgBc82Vqn6vp/zA69yu3wi5FM=", + "license": "MIT", + "engines": { + "node": ">= 10" + }, + "optionalDependencies": { + "@ast-grep/napi-darwin-arm64": "0.45.3", + "@ast-grep/napi-darwin-x64": "0.45.3", + "@ast-grep/napi-linux-arm64-gnu": "0.45.3", + "@ast-grep/napi-linux-arm64-musl": "0.45.3", + "@ast-grep/napi-linux-x64-gnu": "0.45.3", + "@ast-grep/napi-linux-x64-musl": "0.45.3", + "@ast-grep/napi-win32-arm64-msvc": "0.45.3", + "@ast-grep/napi-win32-ia32-msvc": "0.45.3", + "@ast-grep/napi-win32-x64-msvc": "0.45.3" + } + }, + "node_modules/@ast-grep/napi-darwin-arm64": { + "version": "0.45.3", + "integrity": "sha1-VlGmvqgfflQ5f0EB7Ir0YFi5F+k=", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@ast-grep/napi-darwin-x64": { + "version": "0.45.3", + "integrity": "sha512-tIclZ5pM+YSgk8NNTBoTkaclbS39cU5lbVfSrFWX4LUnxXfUPG+F+ppxyFjKwJTBELsGHEO4LdX3/Lc+FDwPNA==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@ast-grep/napi-linux-arm64-gnu": { + "version": "0.45.3", + "integrity": "sha1-tncRiHoChC1GB6V9HNXfruLlPGs=", + "cpu": [ + "arm64" + ], + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@ast-grep/napi-linux-arm64-musl": { + "version": "0.45.3", + "integrity": "sha1-aPYBZr/usYpKov7zBQTHmdb4mpQ=", + "cpu": [ + "arm64" + ], + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@ast-grep/napi-linux-x64-gnu": { + "version": "0.45.3", + "integrity": "sha512-lluRK3hxfHMQdFuVID6seAKVx4FH0kEwF6rCh5/I40Sf3EtNR2UCBXAqd6RBA6hqlSckktvBxCfw+h4aescDmg==", + "cpu": [ + "x64" + ], + "libc": [ + "glibc" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@ast-grep/napi-linux-x64-musl": { + "version": "0.45.3", + "integrity": "sha1-VkWcnClv2fmBKiu5WK8GKIa3UhQ=", + "cpu": [ + "x64" + ], + "libc": [ + "musl" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@ast-grep/napi-win32-arm64-msvc": { + "version": "0.45.3", + "integrity": "sha512-/HiVgw2cdtzXLDLoG4eBBcauekNXewfagy7qiVbjkVu/KcCH8dJ9lpj8DzeWwuBNtZxuD8jpiwP0M1pz3Bc3uw==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@ast-grep/napi-win32-ia32-msvc": { + "version": "0.45.3", + "integrity": "sha1-ZcGLr362mVussSr2YhRho4kgTnk=", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@ast-grep/napi-win32-x64-msvc": { + "version": "0.45.3", + "integrity": "sha1-PLUGYvNe2RoXgauw6EF0UIRj9xE=", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10" + } + }, + "node_modules/@ast-grep/setup-lang": { + "version": "0.0.6", + "integrity": "sha1-n2+AWSNnwNCizHRBr5qdADRy3xA=", + "license": "ISC" + }, + "node_modules/@iarna/toml": { + "version": "2.2.5", + "integrity": "sha1-syNmyJtDxvjO+976x3i5yCjjuow=", + "license": "ISC" + }, + "node_modules/@jdylanmc/topo-archify": { + "version": "0.1.0", + "integrity": "sha512-PgSnOHBR/sZfJKQBEx94UZgqd2udqILEGYX9nxMq/i0tsXPxo8tWfkFppt3YAUGVH7AkriF6SSVbIg42nJvnnQ==", + "license": "MIT", + "engines": { + "node": ">=22" + } + }, + "node_modules/@jdylanmc/topo-code": { + "version": "0.1.0", + "integrity": "sha512-Jw+bAM+oM7ehrSvBWj2PDeK5u2Ykokr844EK6MjJjgGDGPg7epV9TBZlmcBdRYFJXLLLhksxQSj54H1veNnR0A==", + "bundleDependencies": [ + "@topo/cli", + "@topo/diagram-core", + "@topo/enrichment", + "@topo/graph", + "@topo/modules", + "@topo/reports", + "@topo/scanner", + "@topo/schema", + "@topo/site", + "@topo/story", + "@topo/views", + "@topo/workspace" + ], + "license": "MIT", + "dependencies": { + "@jdylanmc/topo-archify": "0.1.0", + "@topo/cli": "0.0.0", + "@topo/diagram-core": "0.0.0", + "@topo/enrichment": "0.0.0", + "@topo/graph": "0.0.0", + "@topo/modules": "0.0.0", + "@topo/reports": "0.0.0", + "@topo/scanner": "0.0.0", + "@topo/schema": "0.0.0", + "@topo/site": "0.0.0", + "@topo/story": "0.0.0", + "@topo/views": "0.0.0", + "@topo/workspace": "0.0.0", + "ajv": "8.17.1", + "ajv-formats": "3.0.1", + "ignore": "^7.0.0", + "typescript-compiler-api": "npm:typescript@^6.0.0" + }, + "bin": { + "topo": "bin/topo.js" + }, + "engines": { + "node": ">=22" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/cli": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "@topo/diagram-core": "0.0.0", + "@topo/enrichment": "0.0.0", + "@topo/graph": "0.0.0", + "@topo/modules": "0.0.0", + "@topo/reports": "0.0.0", + "@topo/scanner": "0.0.0", + "@topo/schema": "0.0.0", + "@topo/site": "0.0.0", + "@topo/story": "0.0.0", + "@topo/views": "0.0.0", + "@topo/workspace": "0.0.0" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/diagram-core": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "@jdylanmc/topo-archify": "0.1.0", + "@topo/story": "0.0.0" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/enrichment": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "@topo/schema": "0.0.0" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/graph": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "@topo/schema": "0.0.0" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/modules": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "@topo/graph": "0.0.0", + "@topo/schema": "0.0.0" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/reports": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "@topo/schema": "0.0.0" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/scanner": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "@topo/schema": "0.0.0", + "ignore": "^7.0.0", + "typescript-compiler-api": "npm:typescript@^6.0.0" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/schema": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "ajv": "8.17.1", + "ajv-formats": "3.0.1" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/site": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "@topo/enrichment": "0.0.0", + "@topo/graph": "0.0.0", + "@topo/modules": "0.0.0", + "@topo/schema": "0.0.0", + "@topo/views": "0.0.0" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/story": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "typescript-compiler-api": "npm:typescript@^6.0.0" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/views": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "@topo/graph": "0.0.0", + "@topo/schema": "0.0.0", + "ignore": "^7.0.0" + } + }, + "node_modules/@jdylanmc/topo-code/node_modules/@topo/workspace": { + "version": "0.0.0", + "inBundle": true, + "dependencies": { + "@topo/schema": "0.0.0" + } + }, + "node_modules/@viz-js/viz": { + "version": "3.30.0", + "integrity": "sha1-0cpKJcQsIGg/bZBtGsmxvdeOsic=", + "license": "MIT" + }, + "node_modules/ajv": { + "version": "8.17.1", + "integrity": "sha1-N9mlx3ava8ktf0+VEOukwKYNEaY=", + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/ajv-formats": { + "version": "3.0.1", + "integrity": "sha1-PV3HYryhdnnDwup+kK1rdTIwlXg=", + "license": "MIT", + "dependencies": { + "ajv": "^8.0.0" + }, + "peerDependencies": { + "ajv": "^8.0.0" + }, + "peerDependenciesMeta": { + "ajv": { + "optional": true + } + } + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "integrity": "sha1-On1WtVnWy8PrUSMlJE5hmmXGxSU=", + "license": "MIT" + }, + "node_modules/fast-uri": { + "version": "3.1.8", + "integrity": "sha512-GZMtZUTNRpOVIECoXwLNZS5xUGE+mVNbTB8h/7Rwh2TFWcBQiPzTgyZi05BF9UMZKkLJv8XBRJTlU7zg8+ZfMg==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fastify" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fastify" + } + ], + "license": "BSD-3-Clause" + }, + "node_modules/ignore": { + "version": "7.0.10", + "integrity": "sha512-HpbUakT7xp5miBUywCHf36ZEuAJNklBJDDsGpUIjMzOSmM8ELSfA9Sa/QDPeNeqeoN31u+UTCkL4klCOVvRm4Q==", + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/json-schema-traverse": { + "version": "1.0.0", + "integrity": "sha1-rnvLNlard6c7pcSb9lTzjmtoYOI=", + "license": "MIT" + }, + "node_modules/require-from-string": { + "version": "2.0.2", + "integrity": "sha1-iaf92TgmEmcxjq/hT5wy5ZjDaQk=", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/typescript-compiler-api": { + "name": "typescript", + "version": "6.0.3", + "integrity": "sha1-kCUdwAeRbpcnhsuU100VsYVXfSE=", + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + } + } +} diff --git a/experiments/plugin-spike/package.json b/experiments/plugin-spike/package.json new file mode 100644 index 0000000..652086f --- /dev/null +++ b/experiments/plugin-spike/package.json @@ -0,0 +1,37 @@ +{ + "name": "topocode-plugin-spike", + "version": "0.1.0-spike.1", + "private": true, + "type": "module", + "description": "Experimental, local-only TypeScript/Rust/Tauri baseline and agent-adoption spike.", + "engines": { + "node": ">=22" + }, + "bin": { + "topo-spike": "./bin/topo-spike.mjs" + }, + "scripts": { + "test": "node --test test/*.test.mjs", + "test:integration": "node --test test/integration.test.mjs", + "pack:local": "npm pack --ignore-scripts --pack-destination artifacts", + "test:package": "node scripts/package-smoke.mjs" + }, + "files": [ + "bin", + "src", + "skills", + "README.md", + "REPORT.md", + "evidence", + "LICENSE" + ], + "dependencies": { + "@ast-grep/lang-rust": "0.0.7", + "@ast-grep/napi": "0.45.3", + "@iarna/toml": "2.2.5", + "@jdylanmc/topo-archify": "0.1.0", + "@jdylanmc/topo-code": "0.1.0", + "@viz-js/viz": "3.30.0" + }, + "license": "MIT" +} diff --git a/experiments/plugin-spike/scripts/check-guide.mjs b/experiments/plugin-spike/scripts/check-guide.mjs new file mode 100644 index 0000000..fb3c1c8 --- /dev/null +++ b/experiments/plugin-spike/scripts/check-guide.mjs @@ -0,0 +1,83 @@ +import { createRequire } from "node:module"; +import { mkdir, readFile, writeFile } from "node:fs/promises"; +import { resolve, join } from "node:path"; + +if (!process.argv[2] || !process.argv[3] || !process.argv[4]) { + throw new Error("Usage: node scripts/check-guide.mjs [chapter-id]"); +} +const consumer = resolve(process.argv[2]); +const output = resolve(process.argv[3]); +const baseUrl = process.argv[4]; +const onlyId = process.argv[5]; +const manifest = JSON.parse(await readFile(join(consumer, ".topo/cache/plugin-spike/meaningful-guide/manifest.json"), "utf8")); +if (!Array.isArray(manifest.pages) || manifest.pages.length === 0) { + throw new Error("Guide manifest requires a nonempty pages array"); +} +const pages = onlyId ? manifest.pages.filter(({ id }) => id === onlyId) : manifest.pages; +if (pages.length === 0) throw new Error(`No guide chapters matched: ${onlyId}`); +const viewports = [[1440, 900], [1600, 1000], [1920, 1080]]; +const expectedMeasurements = pages.length * viewports.length; +const require = createRequire(join(consumer, "package.json")); +const { chromium } = require("@playwright/test"); +await mkdir(output, { recursive: true }); +const browser = await chromium.launch({ headless: true, + ...(process.env.PLAYWRIGHT_CHANNEL ? { channel: process.env.PLAYWRIGHT_CHANNEL } : {}) }); +const results = []; +try { + const page = await browser.newPage(); + for (const chapter of pages) { + const view = JSON.parse(await readFile(join(consumer, chapter.path), "utf8")); + for (const [width, height] of viewports) { + await page.setViewportSize({ width, height }); + await page.goto(`${baseUrl}/${chapter.id}.html`); + await page.waitForFunction(() => document.querySelector("#diagram")?.contentDocument?.querySelector("svg")); + const measurement = await page.evaluate(async (expected) => { + const frame = document.querySelector("#diagram"); + const doc = frame.contentDocument; + await doc.fonts.ready; + await new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))); + const svg = doc.querySelector("svg"); + const items = [...svg.querySelectorAll("text")].map((text) => { + const rect = text.getBoundingClientRect(); + const matrix = text.getScreenCTM(); + return { text: text.textContent, font: parseFloat(frame.contentWindow.getComputedStyle(text).fontSize) * Math.hypot(matrix.a, matrix.b), + x: rect.x, y: rect.y, right: rect.right, bottom: rect.bottom, width: rect.width, height: rect.height }; + }).filter(({ width }) => width > 0); + const overlap = []; + for (let i = 0; i < items.length; i++) for (let j = i + 1; j < items.length; j++) { + const a = items[i], b = items[j]; + if (Math.min(a.right, b.right) - Math.max(a.x, b.x) > 1 && + Math.min(a.bottom, b.bottom) - Math.max(a.y, b.y) > 1) overlap.push([a.text, b.text]); + } + const nodes = [...svg.querySelectorAll("[data-node-id]")].map((node) => ({ + id: node.dataset.nodeId, text: [...node.querySelectorAll("text")].map((t) => t.textContent).join(" "), + })); + return { + outer: [document.documentElement.scrollWidth, document.documentElement.scrollHeight], + frame: [frame.clientWidth, frame.clientHeight, doc.documentElement.scrollWidth, doc.documentElement.scrollHeight], + minFont: Math.min(...items.map(({ font }) => font)), overlap, + clipped: items.filter((r) => r.x < -.5 || r.y < -.5 || r.right > frame.clientWidth + .5 || r.bottom > frame.clientHeight + .5), + nodesPreserved: expected.every((node) => nodes.some((actual) => actual.id === node.id && actual.text === node.title)), + navLinks: document.querySelectorAll(".chapters a").length, + svgViewBox: svg.getAttribute("viewBox"), + }; + }, view.sections.map(({ id, title }) => ({ id, title }))); + const result = { id: chapter.id, width, height, ...measurement }; + result.passed = measurement.nodesPreserved && !measurement.overlap.length && !measurement.clipped.length && + measurement.minFont >= 12 && measurement.outer[0] <= width && measurement.outer[1] <= height; + results.push(result); + await page.screenshot({ path: join(output, `${chapter.id}-${width}.png`) }); + } + } +} finally { + await browser.close(); +} +if (results.length === 0 || results.length !== expectedMeasurements) { + throw new Error(`Incomplete guide measurements: expected ${expectedMeasurements}, received ${results.length}`); +} +await writeFile(join(output, "measurements.json"), JSON.stringify({ + passed: results.every(({ passed }) => passed), expectedMeasurements, results, +}, null, 2) + "\n"); +console.log(JSON.stringify(results.map(({ id, width, minFont, nodesPreserved, overlap, passed, svgViewBox }) => + ({ id, width, minFont, nodesPreserved, overlap, passed, svgViewBox })), null, 2)); +if (results.some(({ passed }) => !passed)) process.exitCode = 1; diff --git a/experiments/plugin-spike/scripts/package-smoke.mjs b/experiments/plugin-spike/scripts/package-smoke.mjs new file mode 100644 index 0000000..44dec46 --- /dev/null +++ b/experiments/plugin-spike/scripts/package-smoke.mjs @@ -0,0 +1,149 @@ +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { promisify, parseArgs } from "node:util"; +import { createHash } from "node:crypto"; +import { mkdtemp, mkdir, readFile, writeFile, rm, lstat } from "node:fs/promises"; +import { dirname, join, resolve } from "node:path"; +import { tmpdir } from "node:os"; +import { fileURLToPath } from "node:url"; +import { MIXED_FILES } from "../test/helpers.mjs"; + +const execute = promisify(execFile); +const root = fileURLToPath(new URL("../", import.meta.url)); +const { values } = parseArgs({ options: { + "local-topocode": { type: "string" }, "local-renderer": { type: "string" }, + registry: { type: "string", default: "https://registry.npmjs.org" }, + report: { type: "string" }, +} }); +if (Boolean(values["local-topocode"]) !== Boolean(values["local-renderer"])) { + throw new Error("Local bootstrap requires both --local-topocode and --local-renderer."); +} +const directory = await mkdtemp(join(tmpdir(), "topo-spike-packed-smoke-")); +const consumer = join(directory, "consumer"); +const home = join(directory, "home"); +await mkdir(consumer); +await mkdir(home); +const env = { + PATH: process.env.PATH, HOME: home, TMPDIR: directory, + GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", + GIT_AUTHOR_DATE: "2000-01-01T00:00:00Z", GIT_COMMITTER_DATE: "2000-01-01T00:00:00Z", + npm_config_cache: join(directory, "npm-cache"), + npm_config_userconfig: join(directory, "empty.npmrc"), + npm_config_globalconfig: join(directory, "empty-global.npmrc"), + npm_config_registry: values.registry, +}; +await writeFile(env.npm_config_userconfig, ""); +await writeFile(env.npm_config_globalconfig, ""); +const receipt = { status: "running", node: process.version, + dependencySource: values["local-topocode"] ? "explicit-local-release-tarballs" : "published-npm-packages", + steps: [], humanAcceptance: "not-claimed" }; +async function run(command, args, expectedCode = 0, cwd = consumer) { + let result; + try { + result = { ...(await execute(command, args, { cwd, env, timeout: 120_000, maxBuffer: 8 * 1024 * 1024 })), code: 0 }; + } catch (error) { + if (error.killed || error.code !== expectedCode) throw error; + result = error; + } + assert.equal(result.code, expectedCode, `${command} ${args[0]} exit code`); + return result.stdout; +} +try { + const localPackages = []; + for (const [flag, expectedName, expectedHash] of [ + ["local-topocode", "@jdylanmc/topo-code", "f2248386c8aa9cf3c141a32eafffdce3117a2ab56aa91595c36cf164ffc40f64"], + ["local-renderer", "@jdylanmc/topo-archify", "d32492b080b1fbc8126506d83678d3bdbf321ab935d0b74e89586576b58c4d27"], + ]) { + if (!values[flag]) continue; + const path = resolve(values[flag]); + assert.equal((await lstat(path)).isFile(), true); + assert.equal(createHash("sha256").update(await readFile(path)).digest("hex"), expectedHash, + `Expected preserved exact ${expectedName}@0.1.0 release tarball, not a rebuilt substitute`); + const metadata = JSON.parse(await run("tar", ["-xOf", path, "package/package.json"])); + assert.equal(metadata.name, expectedName); + assert.equal(metadata.version, "0.1.0"); + localPackages.push(path); + } + const pack = JSON.parse(await run("npm", ["pack", "--json", "--ignore-scripts", "--pack-destination", directory], 0, root))[0]; + assert.equal(pack.name, "topocode-plugin-spike"); + assert.ok(pack.unpackedSize < 512 * 1024, "Retained experiment package must remain bounded"); + assert.ok(pack.files.length < 60, "No generated artifacts should enter the package"); + for (const file of pack.files) { + assert.match(file.path, /^(?:package\.json|LICENSE|README\.md|REPORT\.md|(?:bin|src|skills|evidence)\/)/); + assert.ok(!/(?:node_modules|artifacts|\.tgz|\.png|\.log|package-lock)/.test(file.path)); + } + receipt.package = { name: pack.name, version: pack.version, integrity: pack.integrity, + files: pack.files.map(({ path }) => path), unpackedSize: pack.unpackedSize }; + receipt.steps.push("actual npm pack with bounded inventory"); + for (const [path, text] of Object.entries(MIXED_FILES)) { + await mkdir(dirname(join(consumer, path)), { recursive: true }); + await writeFile(join(consumer, path), text); + } + await writeFile(join(consumer, ".gitignore"), "node_modules/\n.topo/cache/\n"); + await writeFile(join(consumer, "AGENTS.md"), "Keep this synthetic consumer guidance unchanged.\n"); + await run("npm", ["install", "--save-dev", "--save-exact", "--ignore-scripts", "--no-audit", "--no-fund", + "--registry", values.registry, join(directory, pack.filename), ...localPackages]); + receipt.steps.push("fresh packed-consumer npm install --ignore-scripts"); + const installed = join(consumer, "node_modules/topocode-plugin-spike"); + assert.equal((await lstat(installed)).isSymbolicLink(), false, "Consumer must not link a source checkout"); + assert.equal((await lstat(join(consumer, "node_modules/@jdylanmc/topo-code"))).isSymbolicLink(), false); + await run("git", ["init", "-q", "-b", "main"]); + const help = await run("npm", ["exec", "--no", "--", "topo-spike", "--help"]); + assert.match(help, /EXPERIMENTAL/); + await run("npm", ["exec", "--no", "--", "topo-spike", "init", "."]); + assert.match(await readFile(join(consumer, ".agents/skills/topo-plugin-spike/SKILL.md"), "utf8"), /experimental|technical spike/i); + assert.equal(await readFile(join(consumer, "AGENTS.md"), "utf8"), "Keep this synthetic consumer guidance unchanged.\n"); + await run("git", ["add", "package.json", "package-lock.json", ".gitignore", "AGENTS.md", "src", "src-tauri", ".agents", ".github", ".topo/config.json"]); + await run("git", ["-c", "core.hooksPath=/dev/null", "-c", "user.name=Topocode synthetic fixture", + "-c", "user.email=fixture@example.invalid", "commit", "-qm", "fixture"]); + const preserved = new Map(await Promise.all(["src/main.ts", "src-tauri/Cargo.toml", "src-tauri/src/lib.rs", "AGENTS.md"] + .map(async (path) => [path, await readFile(join(consumer, path))]))); + const baselinePath = ".topo/cache/plugin-spike/baseline.json"; + await run("npm", ["exec", "--no", "--", "topo-spike", "scan", ".", "--allow-partial"], 2); + const baseline = JSON.parse(await readFile(join(consumer, baselinePath), "utf8")); + assert.equal(baseline.coverage.status, "partial"); + const edge = baseline.relationships.find((item) => item.kind === "tauri-command-binding"); + assert.ok(edge, "Actual installed mixed-language scan must produce the supported source binding"); + receipt.steps.push("installed npm-bin init and partial scan (exit 2), source Tauri binding"); + const view = { + schemaVersion: "0.1.0-spike.1", id: "packed-smoke", title: "Packed command binding", + summary: "A synthetic TypeScript call binds to a source-declared Rust command; runtime execution is unknown.", + baselineId: baseline.id, + sections: [ + { id: "frontend", title: "Frontend", body: "Captured invocation.", entityIds: [edge.from] }, + { id: "rust", title: "Rust command", body: "Captured command declaration.", entityIds: [edge.to] }, + ], + connections: [{ from: "frontend", to: "rust", label: "snapshot", + classification: "source-derived", relationshipIds: [edge.id] }], + }; + const viewPath = "stories/packed-smoke.topo-view.json"; + await mkdir(join(consumer, "stories")); + await writeFile(join(consumer, viewPath), JSON.stringify(view, null, 2)); + await run("npm", ["exec", "--no", "--", "topo-spike", "validate", ".", baselinePath, viewPath]); + for (const renderer of ["archify", "graphviz"]) { + const output = `.topo/cache/plugin-spike/${renderer}.html`; + const rendered = JSON.parse(await run("npm", ["exec", "--no", "--", "topo-spike", "render", + ".", baselinePath, viewPath, "--renderer", renderer, "--output", output])); + assert.match(await readFile(join(consumer, output), "utf8"), /"); + throw error; +} finally { + if (values.report) { + const reportPath = resolve(values.report); + await mkdir(dirname(reportPath), { recursive: true }); + await writeFile(reportPath, JSON.stringify(receipt, null, 2) + "\n"); + } + await rm(directory, { recursive: true, force: true }); +} +console.log(JSON.stringify(receipt, null, 2)); diff --git a/experiments/plugin-spike/scripts/probe-native-layout.mjs b/experiments/plugin-spike/scripts/probe-native-layout.mjs new file mode 100644 index 0000000..2162300 --- /dev/null +++ b/experiments/plugin-spike/scripts/probe-native-layout.mjs @@ -0,0 +1,48 @@ +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { mkdir, readFile, writeFile } from "node:fs/promises"; +import { resolve } from "node:path"; +import { cliPath, verifyRuntime } from "@jdylanmc/topo-archify"; + +const execute = promisify(execFile); +if (!process.argv[2]) throw new Error("Usage: node scripts/probe-native-layout.mjs [output-directory]"); +const directory = resolve(process.argv[3] ?? "artifacts/native-layout-probe"); +await mkdir(directory, { recursive: true }); +verifyRuntime(); +const root = resolve(process.argv[2]); +for (const [file, name] of [ + ["review-publication.before.topo-view.json", "detailed"], + ["review-publication.topo-view.json", "grouped"], +]) { + const view = JSON.parse(await readFile(`${root}/${file}`, "utf8")); + const cols = view.sections.length <= 3 ? 1 : 2; + const width = Math.max(160, ...view.sections.map(({ title }) => Math.ceil(title.length * 6.6 + 28))); + const gapX = Math.max(100, ...view.connections.map(({ label }) => Math.ceil(label.length * 4.8 + 24))); + const rows = Math.ceil(view.sections.length / cols); + const specification = { + schema_version: 1, diagram_type: "architecture", + meta: { + title: view.title, output: `${name}.html`, quality_profile: "showcase", locale: "en", + viewBox: [Math.max(320, cols * width + (cols - 1) * gapX + 48), Math.max(240, rows * 52 + (rows - 1) * 48 + 48)], + legend: { mode: "hidden" }, + }, + layout: { mode: "grid", cols, origin: [24, 24], gapX, gapY: 48, cellW: width, cellH: 52 }, + components: view.sections.map(({ id, title }, index) => ({ + id, type: "backend", icon: "none", label: title, row: Math.floor(index / cols), col: index % cols, size: [width, 52], + })), + connections: view.connections.map(({ from, to, label }, index) => ({ id: `edge-${index}`, from, to, label })), + }; + const source = resolve(directory, `${name}.json`); + const output = resolve(directory, `${name}.html`); + await writeFile(source, JSON.stringify(specification, null, 2) + "\n"); + try { + const result = await execute(process.execPath, [cliPath, "deliver", "architecture", source, output, "--quality", "showcase", "--json"], + { cwd: directory, maxBuffer: 8 * 1024 * 1024 }); + await writeFile(resolve(directory, `${name}.receipt.json`), result.stdout); + console.log(result.stdout); + } catch (error) { + await writeFile(resolve(directory, `${name}.failed.json`), error.stdout || error.message); + console.error(name, error.stdout || error.message); + process.exitCode = 1; + } +} diff --git a/experiments/plugin-spike/scripts/render-pr-sniper-guide.mjs b/experiments/plugin-spike/scripts/render-pr-sniper-guide.mjs new file mode 100644 index 0000000..19b9318 --- /dev/null +++ b/experiments/plugin-spike/scripts/render-pr-sniper-guide.mjs @@ -0,0 +1,13 @@ +import { readFile } from "node:fs/promises"; +import { resolve } from "node:path"; +import { readBaseline } from "../src/baseline.mjs"; +import { readView, renderBook } from "../src/view.mjs"; + +if (!process.argv[2]) throw new Error("Supply the PR-Sniper adoption worktree path"); +const root = resolve(process.argv[2]); +const output = resolve(process.argv[3] ?? "artifacts/final-consumer/pr-sniper-guide"); +const baseline = await readBaseline(`${root}/.topo/cache/plugin-spike/baseline.json`); +const manifest = JSON.parse(await readFile(`${root}/.topo/cache/plugin-spike/meaningful-guide/manifest.json`, "utf8")); +const views = await Promise.all(manifest.pages.map(({ path }) => readView(resolve(root, path)))); +const book = await renderBook(root, baseline, views, output, { renderer: "graphviz" }); +console.log(`Book ready: ${book.views} chapters at ${output}`); diff --git a/experiments/plugin-spike/scripts/serve-artifacts.mjs b/experiments/plugin-spike/scripts/serve-artifacts.mjs new file mode 100644 index 0000000..aa2f2b1 --- /dev/null +++ b/experiments/plugin-spike/scripts/serve-artifacts.mjs @@ -0,0 +1,39 @@ +import { createServer } from "node:http"; +import { lstat, readFile, realpath } from "node:fs/promises"; +import { extname, relative, resolve, sep } from "node:path"; + +const root = await realpath(resolve(process.argv[2] ?? "artifacts")); +const port = Number(process.argv[3] ?? "0"); +if (!Number.isSafeInteger(port) || port < 0 || port > 65535) throw new Error("Invalid local preview port"); +const types = { ".html": "text/html; charset=utf-8", ".json": "application/json", ".svg": "image/svg+xml", + ".png": "image/png", ".js": "text/javascript", ".css": "text/css" }; +const server = createServer(async (request, response) => { + try { + const url = new URL(request.url ?? "/", "http://127.0.0.1"); + const path = resolve(root, `.${decodeURIComponent(url.pathname)}`); + const rel = relative(root, path); + if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || + await realpath(path) !== path || !(await lstat(path)).isFile()) { + response.writeHead(404).end("Not found"); + return; + } + const bytes = await readFile(path); + response.writeHead(200, { "Content-Type": types[extname(path)] ?? "application/octet-stream", + "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" }).end(bytes); + } catch (error) { + if (error.code === "ENOENT") response.writeHead(404).end("Not found"); + else { + console.error(error.message); + response.writeHead(500).end("Preview read failed"); + } + } +}); +server.listen(port, "127.0.0.1", () => { + console.log(JSON.stringify({ root, url: `http://127.0.0.1:${server.address().port}`, pid: process.pid })); +}); +function stop() { + server.close(); + server.closeAllConnections(); +} +process.on("SIGINT", stop); +process.on("SIGTERM", stop); diff --git a/experiments/plugin-spike/skills/topo-plugin-spike.instructions.md b/experiments/plugin-spike/skills/topo-plugin-spike.instructions.md new file mode 100644 index 0000000..7f1e5fa --- /dev/null +++ b/experiments/plugin-spike/skills/topo-plugin-spike.instructions.md @@ -0,0 +1,9 @@ +--- +applyTo: "stories/**/*.topo-view.json,.topo/config.json" +--- + +Read `.agents/skills/topo-plugin-spike/SKILL.md` for this experimental +TypeScript/Rust/Tauri adoption. Generate and inspect the baseline before +authoring. Keep extracted facts separate from interpretation, preserve source +references and human intent, and report partial coverage explicitly. Use the +installed `topo-spike` command; do not edit generated baseline or HTML output. diff --git a/experiments/plugin-spike/skills/topo-plugin-spike/SKILL.md b/experiments/plugin-spike/skills/topo-plugin-spike/SKILL.md new file mode 100644 index 0000000..77d6c68 --- /dev/null +++ b/experiments/plugin-spike/skills/topo-plugin-spike/SKILL.md @@ -0,0 +1,108 @@ +--- +name: topo-plugin-spike +description: "Use the experimental language/framework baseline to author and refine source-backed diagrams." +--- + +# Experimental plugin adoption + +This is a local technical spike, not released Rust support in Topocode 0.1.0. +Use the installed `topo-spike` command through `npm exec --no -- topo-spike`. +Do not inspect a Topocode development checkout or rely on coordinator history. + +## Start from the generated baseline + +```sh +npm exec --no -- topo-spike scan . --allow-partial +npm exec --no -- topo-spike inspect .topo/cache/plugin-spike/baseline.json --query monitoring --limit 20 +``` + +A partial scan writes an explicitly limited-evidence artifact and exits **2**, +not success. Read `coverage`, `diagnostics`, and `unresolved`; never claim that +syntax-only Rust analysis resolves every call, macro, conditional branch, or +runtime path. No model, Cargo build, or procedural macro runs during this scan. + +The baseline contains stable source-relative fact IDs, source locations and +hashes, language/plugin provenance, relationships and unresolved references. +Use `inspect --entity ID` or `inspect --relationship ID` for exact records. +Truncation is explicit; refine a query rather than assuming the first page is +the complete graph. Read referenced source to understand meaning. + +## Author a view, not replacement facts + +Store an authored JSON file outside `.topo/cache`, for example +`stories/monitoring.topo-view.json`. Use a small focused view, at most eight +sections. Keep IDs stable during human-requested refinements. + +```json +{ + "schemaVersion": "0.1.0-spike.1", + "id": "monitoring", + "title": "Monitoring boundary", + "summary": "Explain the selected source-backed scope and its limits.", + "baselineId": "COPY THE EXACT BASELINE ID", + "sections": [ + {"id": "frontend", "title": "Frontend", "body": "Explain the cited code.", "entityIds": ["EXACT ENTITY ID"]}, + {"id": "native", "title": "Native command", "body": "Explain the cited command.", "entityIds": ["EXACT ENTITY ID"]} + ], + "connections": [ + {"from": "frontend", "to": "native", "label": "command binding", "classification": "source-derived", "relationshipIds": ["EXACT RELATIONSHIP ID"]} + ] +} +``` + +Every source-derived connection must cite real baseline relationships in the +displayed direction. A section referencing a source file includes its declared +members, so a human may request a collapsed file-level view without inventing +new edges. Interpretation-only connections instead use +`"classification": "inferred"`, an empty `relationshipIds` array, and a nonblank +`rationale`; the diagram visibly labels them **Inferred**. + +Valid references do not prove narrative truth, runtime execution, permissions, +or complete application coverage. Tauri bindings are source registrations and +known invocation expressions, not a promise that the call executes. + +For implementation flow that the analyzer has not resolved, a connection may +use `classification: "source-traced"`, empty `relationshipIds`, a nonblank +`rationale`, and `evidence` entries containing `path`, `startLine`, `endLine`, +the complete source-file `sha256`, and an exact full-line `excerpt`. +The CLI checks the excerpt against the current snapshot. The workbench labels +it an **agent source trace**, not an analyzer-generated control-flow edge. +Sections may carry the same evidence entries and a `kind` of `step`, +`decision`, or `data`. Explain technology choices and real predicates/actions +in the diagram's section narrative, not only in the agent conversation. + +Publish connected diagrams with `topo-spike book + [more.json ...] --output `. The ordered views become +navigable chapters; clicking a diagram node focuses its explanation and code. +Use small meaningful pages rather than dropping branches to fit one overview. + +```sh +npm exec --no -- topo-spike validate . .topo/cache/plugin-spike/baseline.json stories/monitoring.topo-view.json +npm exec --no -- topo-spike render . .topo/cache/plugin-spike/baseline.json stories/monitoring.topo-view.json --output .topo/cache/plugin-spike/monitoring.html +``` + +By default, the HTML workbench embeds pristine pinned Archify in native +presentation mode, with its nine showcase checks. For branch-heavy books, +`--renderer graphviz` explicitly selects the packaged Graphviz WASM engine and +its separate structural checks; do not claim those are Archify validation. +Keep the adjacent `.native.html` file with the wrapper. The `.spec.json`, +`.evidence.json` and `.receipt.json` retain exact inputs, evidence, engine +identity and engine-specific validation. +Open the workbench locally; the prototype does not start a server or launch +the application. The native viewer retains theme, zoom and export controls. +The Graphviz alternative exposes SVG export. Book `index.html` is currently the +first diagram with chapter navigation, not a branded core landing/catalogue. + +## Refine and reconcile + +Respond to human requests by editing the authored view: grouping, scope, +explanation and labels. Never edit baseline JSON or renderer HTML to fake facts. +After source changes, regenerate the baseline and revalidate. Stale snapshot +bindings fail explicitly. Inspect changed facts, repair affected references and +narrative, then deliberately update `baselineId`; preserve unaffected section +IDs and intent. Do not blindly replace IDs or treat a changed source hash as +proof that every explanation remains accurate. + +Commit, push, publish, execute repository scripts, or change application source +only when separately authorized. Report human semantic/visual review as pending +until a human actually performs it. diff --git a/experiments/plugin-spike/src/baseline.mjs b/experiments/plugin-spike/src/baseline.mjs new file mode 100644 index 0000000..31c68e4 --- /dev/null +++ b/experiments/plugin-spike/src/baseline.mjs @@ -0,0 +1,179 @@ +import { readFile } from "node:fs/promises"; +import { captureInventory, assertInventoryCurrent } from "./inventory.mjs"; +import { compare, CONTRACT_VERSION, factId, hash, serialize, sourceLocation } from "./contract.mjs"; +import { manifest as typescriptManifest, scanTypeScript } from "./plugins/typescript.mjs"; +export { writeArtifact, writeArtifactSet } from "./publication.mjs"; + +export const registry = [ + { ...typescriptManifest, scan: scanTypeScript }, + { + id: "rust", kind: "language", requires: [], languages: ["rust"], + detect: (files) => files.some(({ path }) => path.endsWith(".rs") || /(?:^|\/)Cargo\.toml$/.test(path)), + scan: async (context) => (await import("./plugins/rust.mjs")).scanRust(context), + }, + { + id: "tauri", kind: "framework", requires: ["typescript", "rust"], languages: ["typescript", "javascript", "rust"], + detect: (files) => typescriptManifest.detect(files) && files.some(({ path, contents }) => + path.endsWith(".rs") && /tauri::(?:command|generate_handler)/.test(contents)), + scan: async (context, contributions) => (await import("./plugins/tauri.mjs")).scanTauri(context, contributions), + }, +]; + +export function pluginOrder(available, selected) { + const byId = new Map(); + for (const plugin of available) { + if (byId.has(plugin.id)) throw new Error(`Duplicate plugin: ${plugin.id}`); + byId.set(plugin.id, plugin); + } + if (new Set(selected).size !== selected.length) throw new Error("Duplicate selected plugin"); + const visiting = new Set(); + const visited = new Set(); + const ordered = []; + function visit(id) { + if (visited.has(id)) return; + if (visiting.has(id)) throw new Error(`Plugin dependency cycle at ${id}`); + const plugin = byId.get(id); + if (!plugin) throw new Error(`Unknown plugin: ${id}`); + visiting.add(id); + for (const requirement of [...plugin.requires].sort(compare)) { + if (!selected.includes(requirement)) throw new Error(`Plugin ${id} requires explicitly selected ${requirement}`); + visit(requirement); + } + visiting.delete(id); + visited.add(id); + ordered.push(plugin); + } + for (const id of [...selected].sort(compare)) visit(id); + return ordered; +} + +function validateLocation(location, sources) { + if (!location || !sources.has(location.path)) throw new Error("Evidence references uncaptured source"); + const { path, startLine, startColumn, endLine, endColumn } = location; + sourceLocation(path, startLine, endLine, startColumn, endColumn); + const lines = sources.get(path).contents.split(/\r?\n/); + if (endLine > lines.length) throw new Error(`Evidence range exceeds ${path}`); + if (startColumn > lines[startLine - 1].length + 1 || endColumn > lines[endLine - 1].length + 1) { + throw new Error(`Evidence column exceeds ${path}`); + } +} + +export function validateFacts(baseline, files) { + const sources = new Map(files.map((file) => [file.path, file])); + const entities = new Map(); + for (const entity of baseline.entities) { + if (!entity.id || entities.has(entity.id)) throw new Error(`Duplicate/empty entity ID: ${entity.id}`); + validateLocation(entity.location, sources); + if (!entity.name || !entity.kind || !entity.language || typeof entity.exported !== "boolean") { + throw new Error(`Malformed entity: ${entity.id}`); + } + entities.set(entity.id, entity); + } + for (const entity of entities.values()) { + if (entity.ownerId && !entities.has(entity.ownerId)) throw new Error(`Unknown owner: ${entity.ownerId}`); + } + const relationshipIds = new Set(); + for (const relation of baseline.relationships) { + if (!relation.id || relationshipIds.has(relation.id)) throw new Error(`Duplicate relationship: ${relation.id}`); + if (!entities.has(relation.from) || !entities.has(relation.to)) { + throw new Error(`Relationship references unknown endpoint: ${relation.id}`); + } + if (!relation.kind || !relation.method || !Array.isArray(relation.evidence) || !relation.evidence.length) { + throw new Error(`Relationship lacks evidence/method: ${relation.id}`); + } + relation.evidence.forEach((value) => validateLocation(value, sources)); + relationshipIds.add(relation.id); + } + const unresolvedIds = new Set(); + for (const item of baseline.unresolved) { + if (!item.id || unresolvedIds.has(item.id) || !item.reason || !item.kind) { + throw new Error("Malformed/duplicate unresolved reference"); + } + validateLocation(item.location, sources); + if (item.ownerId && !entities.has(item.ownerId)) throw new Error(`Unresolved reference has unknown owner: ${item.id}`); + for (const candidate of item.candidates ?? []) { + if (!entities.has(candidate)) throw new Error(`Unresolved candidate does not exist: ${candidate}`); + } + unresolvedIds.add(item.id); + } + serialize(baseline); +} + +export function baselineDigest(value) { + const { id: omitted, ...body } = value; + return `sha256:${hash(serialize(body))}`; +} + +export async function scanBaseline(root, options = {}) { + const captured = await captureInventory(root); + if (options.repositoryId) captured.repository.id = options.repositoryId; + const available = options.registry ?? registry; + const selected = options.plugins ?? available.filter((plugin) => plugin.detect(captured.files)).map(({ id }) => id); + if (!selected.length) throw new Error("No supported language was detected; no baseline generated"); + const ordered = pluginOrder(available, selected); + const context = { root: captured.root, files: captured.files, repository: captured.repository }; + const contributions = []; + for (const plugin of ordered) { + const contribution = await plugin.scan(context, contributions); + if (contribution.plugin.id !== plugin.id || contribution.plugin.kind !== plugin.kind || + contribution.plugin.version !== CONTRACT_VERSION) { + throw new Error(`Plugin contribution identity/version mismatch: ${plugin.id}`); + } + contributions.push(contribution); + } + const entities = captured.files.map((file) => ({ + id: factId("core", "file", file.path, file.path), + language: file.language, kind: "file", name: file.path.split("/").at(-1), + qualifiedName: file.path, location: sourceLocation(file.path, 1), + exported: false, signatures: [], attributes: [], + })); + for (const contribution of contributions) entities.push(...contribution.entities); + const relationships = contributions.flatMap(({ relationships }) => relationships); + for (const entity of entities) { + if (entity.kind === "file") continue; + relationships.push({ + id: factId("core", "contains", entity.location.path, entity.id), + from: factId("core", "file", entity.location.path, entity.location.path), + to: entity.id, + kind: "declares", method: "captured-source-location", evidence: [entity.location], + }); + } + const supportedLanguages = new Set(ordered.filter(({ kind }) => kind === "language").flatMap(({ languages }) => languages)); + const auxiliary = new Set(["configuration", "html", "css", "svg"]); + const unsupportedLanguages = [...new Set(captured.files.map(({ language }) => language) + .filter((language) => !supportedLanguages.has(language) && !auxiliary.has(language)))].sort(compare); + const baseline = { + schemaVersion: CONTRACT_VERSION, + experimental: true, + repository: captured.repository, + source: { + ...captured.snapshot, + selection: "Git tracked and nonignored files with recognized source/configuration extensions; .topo, node_modules and .skill-log excluded.", + }, + execution: { repositoryBuildScripts: false, proceduralMacros: false, modelInvocations: false }, + plugins: contributions.map(({ plugin }) => plugin).sort((a, b) => compare(a.id, b.id)), + entities: entities.sort((a, b) => compare(a.id, b.id)), + relationships: relationships.sort((a, b) => compare(a.id, b.id)), + unresolved: contributions.flatMap(({ unresolved }) => unresolved).sort((a, b) => compare(a.id, b.id)), + diagnostics: contributions.flatMap(({ diagnostics }) => diagnostics) + .sort((a, b) => compare(a.path ?? "", b.path ?? "") || compare(a.code, b.code) || compare(a.message, b.message)), + coverage: { + status: unsupportedLanguages.length || contributions.some(({ coverage }) => coverage.status !== "complete") ? "partial" : "complete", + unsupportedLanguages, + byPlugin: Object.fromEntries(contributions.map(({ plugin, coverage }) => [plugin.id, coverage])), + }, + extensions: Object.fromEntries(contributions.map(({ plugin, extensions }) => [plugin.id, extensions])), + }; + validateFacts(baseline, captured.files); + await assertInventoryCurrent(captured); + baseline.id = baselineDigest(baseline); + return baseline; +} + +export async function readBaseline(path) { + const value = JSON.parse(await readFile(path, "utf8")); + if (value.schemaVersion !== CONTRACT_VERSION || value.id !== baselineDigest(value)) { + throw new Error("Unsupported or modified baseline; regenerate rather than editing derived facts"); + } + return value; +} diff --git a/experiments/plugin-spike/src/contract.d.ts b/experiments/plugin-spike/src/contract.d.ts new file mode 100644 index 0000000..fd4e123 --- /dev/null +++ b/experiments/plugin-spike/src/contract.d.ts @@ -0,0 +1,84 @@ +export interface SourceLocation { + path: string; + startLine: number; + startColumn: number; + endLine: number; + endColumn: number; +} + +export interface SourceFile { + path: string; + contents: string; + sha256: string; +} + +export interface Entity { + id: string; + language: string; + kind: string; + name: string; + qualifiedName: string; + location: SourceLocation; + exported: boolean; + signatures: string[]; + attributes: string[]; + ownerId?: string; +} + +export interface Relationship { + id: string; + from: string; + to: string; + kind: string; + method: string; + evidence: SourceLocation[]; +} + +export interface UnresolvedReference { + id: string; + kind: string; + text: string; + reason: string; + location: SourceLocation; + ownerId?: string; + candidates?: string[]; +} + +export interface Diagnostic { + code: string; + severity: "warning" | "error"; + message: string; + path?: string; +} + +export interface Contribution { + plugin: { + id: string; + version: string; + kind: "language" | "framework"; + languages: string[]; + capabilities: string[]; + }; + entities: Entity[]; + relationships: Relationship[]; + unresolved: UnresolvedReference[]; + diagnostics: Diagnostic[]; + coverage: { + status: "complete" | "partial" | "unsupported"; + analyzedFiles: string[]; + limitations: string[]; + }; + extensions: Record; +} + +export interface ScanContext { + root: string; + files: readonly SourceFile[]; +} + +// Plugins receive a captured source inventory; they must not mutate the repository. +export type LanguagePlugin = (context: ScanContext) => Promise; +export type FrameworkPlugin = ( + context: ScanContext, + languages: readonly Contribution[], +) => Promise; diff --git a/experiments/plugin-spike/src/contract.mjs b/experiments/plugin-spike/src/contract.mjs new file mode 100644 index 0000000..e0796a8 --- /dev/null +++ b/experiments/plugin-spike/src/contract.mjs @@ -0,0 +1,69 @@ +import { createHash } from "node:crypto"; +import { posix } from "node:path"; + +export const CONTRACT_VERSION = "0.1.0-spike.1"; + +export function compare(left, right) { + return left < right ? -1 : left > right ? 1 : 0; +} + +export function hash(value) { + return createHash("sha256").update(value).digest("hex"); +} + +export function repositoryPath(value) { + if (typeof value !== "string" || !value || value.includes("\\") || + value.includes("\0") || value.startsWith("/") || /^[A-Za-z]:/.test(value) || + value.split("/").some((part) => part === "." || part === ".." || !part)) { + throw new Error(`Expected a contained repository-relative path: ${JSON.stringify(value)}`); + } + return posix.normalize(value); +} + +export function factId(plugin, kind, path, key) { + repositoryPath(path); + for (const [name, value] of Object.entries({ plugin, kind, key })) { + if (typeof value !== "string" || !value || value.includes("\0")) { + throw new Error(`Invalid fact identity ${name}`); + } + } + return `${plugin}:${kind}:${hash(`${path}\0${key}`).slice(0, 24)}`; +} + +export function sourceLocation(path, startLine, endLine = startLine, startColumn = 1, endColumn = 1) { + repositoryPath(path); + if (![startLine, endLine, startColumn, endColumn].every((value) => Number.isSafeInteger(value) && value > 0) || + endLine < startLine || (endLine === startLine && endColumn < startColumn)) { + throw new Error(`Invalid source location in ${path}`); + } + return { path, startLine, startColumn, endLine, endColumn }; +} + +export function canonical(value) { + if (value === null || typeof value === "string" || typeof value === "boolean") return value; + if (typeof value === "number" && Number.isFinite(value)) return value; + if (Array.isArray(value)) return value.map(canonical); + if (typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) { + return Object.fromEntries(Object.keys(value).sort(compare).map((key) => { + if (value[key] === undefined) throw new Error(`Undefined value in artifact field ${key}`); + return [key, canonical(value[key])]; + })); + } + throw new Error("Artifact contains a non-JSON value"); +} + +export function serialize(value) { + return `${JSON.stringify(canonical(value), null, 2)}\n`; +} + +export function emptyContribution(id, kind, languages, capabilities) { + return { + plugin: { id, version: CONTRACT_VERSION, kind, languages, capabilities }, + entities: [], + relationships: [], + unresolved: [], + diagnostics: [], + coverage: { status: "partial", analyzedFiles: [], limitations: [] }, + extensions: {}, + }; +} diff --git a/experiments/plugin-spike/src/flow-renderer.mjs b/experiments/plugin-spike/src/flow-renderer.mjs new file mode 100644 index 0000000..8c36e90 --- /dev/null +++ b/experiments/plugin-spike/src/flow-renderer.mjs @@ -0,0 +1,74 @@ +import { instance } from "@viz-js/viz"; +import { hash, serialize } from "./contract.mjs"; + +function escape(value) { + return String(value).replaceAll("&", "&").replaceAll("<", "<") + .replaceAll(">", ">").replaceAll('"', """); +} + +function wrap(value, limit = 24) { + const lines = [""]; + for (const word of value.split(/\s+/)) { + if (lines.at(-1) && lines.at(-1).length + word.length + 1 > limit) lines.push(word); + else lines[lines.length - 1] += `${lines.at(-1) ? " " : ""}${word}`; + } + return lines.join("\n"); +} + +export function flowSpecification(view) { + const q = JSON.stringify; + const lines = [ + "digraph Topocode {", + 'graph [rankdir=TB,bgcolor="transparent",pad="0.2",nodesep="0.3",ranksep="0.3",splines=spline,ordering=out];', + 'node [fontname="Arial",fontsize=20,shape=box,style="rounded,filled",fillcolor="#e6f1f8",color="#235a77",fontcolor="#183647",margin="0.18,0.12",penwidth=1.5];', + 'edge [fontname="Arial",fontsize=17,color="#526f85",fontcolor="#324e63",arrowsize=0.7,penwidth=1.4];', + ]; + for (const [index, section] of view.sections.entries()) { + const kind = section.kind ?? "step"; + lines.push(`${q(section.id)} [id=${q(`node${index}`)},label=${q(wrap(section.title))},shape=${q(kind === "decision" ? "diamond" : kind === "data" ? "cylinder" : "box")},fillcolor=${q(kind === "decision" ? "#fff1d9" : kind === "data" ? "#e8e5f6" : "#e6f1f8")}];`); + } + for (const [index, edge] of view.connections.entries()) { + const label = `${edge.classification === "inferred" ? "Inferred: " : ""}${edge.label}`; + lines.push(`${q(edge.from)} -> ${q(edge.to)} [id=${q(`edge${index}`)},label=${q(wrap(label))},style=${q(edge.classification === "inferred" ? "dashed" : "solid")}];`); + } + lines.push("}"); + return { engine: "dot", format: "svg", source: lines.join("\n") + "\n" }; +} + +export async function renderFlow(view) { + const specification = flowSpecification(view); + const viz = await instance(); + const result = viz.render(specification.source, { engine: "dot", format: "svg" }); + if (result.status !== "success" || result.errors.length) throw new Error(`Flowchart layout failed: ${serialize(result.errors)}`); + let svg = result.output.slice(result.output.indexOf("${escape(view.title)} +
Source-traced logic. Select a node for implementation detail.
${svg}
+`; + return { + contents, specification, + renderer: { name: "graphviz", pin: viz.graphvizVersion, package: "@viz-js/viz@3.30.0" }, + validation: { status: "pass", errors: 0, warnings: 0, nodes: view.sections.length, edges: view.connections.length, + checks: ["Graphviz layout succeeded", "all authored node IDs retained", "all authored connection IDs retained"], + browserReview: "separate" }, + specificationSha256: hash(serialize(specification)), + }; +} diff --git a/experiments/plugin-spike/src/initialize.mjs b/experiments/plugin-spike/src/initialize.mjs new file mode 100644 index 0000000..2cc215c --- /dev/null +++ b/experiments/plugin-spike/src/initialize.mjs @@ -0,0 +1,53 @@ +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { dirname, join, relative, resolve, sep } from "node:path"; +import { fileURLToPath } from "node:url"; +import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises"; +import { topocodeBin } from "./topocode.mjs"; + +const execute = promisify(execFile); +const resources = fileURLToPath(new URL("../skills/", import.meta.url)); + +async function safeDestination(root, target) { + const rel = relative(root, target); + if (!rel || rel === ".." || rel.startsWith(`..${sep}`)) throw new Error("Context destination escapes repository"); + const parts = rel.split(sep); + for (let index = 1; index <= parts.length; index++) { + const candidate = resolve(root, ...parts.slice(0, index)); + try { + const info = await lstat(candidate); + if (info.isSymbolicLink() || (candidate !== target && !info.isDirectory())) { + throw new Error(`Context destination conflict: ${candidate}`); + } + } catch (error) { + if (error.code !== "ENOENT") throw error; + } + } +} + +export async function initialize(rootInput) { + const root = await realpath(resolve(rootInput)); + const descriptors = [ + ["topo-plugin-spike/SKILL.md", ".agents/skills/topo-plugin-spike/SKILL.md"], + ["topo-plugin-spike.instructions.md", ".github/instructions/topo-plugin-spike.instructions.md"], + ]; + const pending = []; + for (const [source, destination] of descriptors) { + const target = join(root, destination); + await safeDestination(root, target); + const contents = await readFile(join(resources, source)); + try { + if (!(await readFile(target)).equals(contents)) throw new Error(`Context destination conflict: ${destination}`); + } catch (error) { + if (error.code !== "ENOENT") throw error; + pending.push({ target, contents }); + } + } + const installed = await execute(process.execPath, [topocodeBin(), "init", root, "--skills"], { maxBuffer: 1024 * 1024 }); + for (const { target, contents } of pending) { + await safeDestination(root, target); + await mkdir(dirname(target), { recursive: true }); + await writeFile(target, contents, { flag: "wx" }); + } + return { installedContextFiles: pending.length, topocode: installed.stdout.trim() }; +} diff --git a/experiments/plugin-spike/src/inventory.mjs b/experiments/plugin-spike/src/inventory.mjs new file mode 100644 index 0000000..db34c48 --- /dev/null +++ b/experiments/plugin-spike/src/inventory.mjs @@ -0,0 +1,102 @@ +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { constants } from "node:fs"; +import { lstat, open, realpath } from "node:fs/promises"; +import { basename, extname, relative, resolve, sep } from "node:path"; +import { compare, hash, repositoryPath, serialize } from "./contract.mjs"; + +const execute = promisify(execFile); +const LANGUAGES = new Map([ + [".ts", "typescript"], [".tsx", "typescript"], [".mts", "typescript"], [".cts", "typescript"], + [".js", "javascript"], [".jsx", "javascript"], [".mjs", "javascript"], [".cjs", "javascript"], + [".rs", "rust"], [".py", "python"], [".swift", "swift"], [".go", "go"], [".cs", "csharp"], + [".java", "java"], [".kt", "kotlin"], [".rb", "ruby"], [".c", "c"], [".cpp", "cpp"], + [".h", "c-header"], [".sh", "shell"], [".html", "html"], [".css", "css"], [".svg", "svg"], +]); + +export function languageOf(path) { + return LANGUAGES.get(extname(path).toLowerCase()) ?? "configuration"; +} + +function relevant(path) { + if (path.split("/").some((part) => [".git", "node_modules", ".topo", ".skill-log"].includes(part))) return false; + const name = basename(path); + return LANGUAGES.has(extname(path).toLowerCase()) || + ["Cargo.toml", "Cargo.lock", "package.json", "package-lock.json", "rust-toolchain.toml", + "rust-toolchain", "tauri.conf.json"].includes(name) || + /^tsconfig(?:\.[^.]+)*\.json$/.test(name) || /(?:^|\/)\.cargo\/config(?:\.toml)?$/.test(path); +} + +export async function stableRead(root, path) { + repositoryPath(path); + const target = resolve(root, path); + const rel = relative(root, target); + if (!rel || rel.startsWith(`..${sep}`) || rel === "..") throw new Error(`Source escapes repository: ${path}`); + const actual = await realpath(target); + const info = await lstat(target); + if (actual !== target || !info.isFile() || info.isSymbolicLink()) { + throw new Error(`Source must be a regular, non-symlinked repository file: ${path}`); + } + const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW); + try { + const before = await handle.stat(); + if (before.dev !== info.dev || before.ino !== info.ino) throw new Error(`Source changed before reading: ${path}`); + const bytes = await handle.readFile(); + const contents = bytes.toString("utf8"); + if (!Buffer.from(contents, "utf8").equals(bytes)) throw new Error(`Source is not valid UTF-8: ${path}`); + const after = await handle.stat(); + const current = await lstat(target); + if (before.dev !== current.dev || before.ino !== current.ino || + before.size !== after.size || before.mtimeMs !== after.mtimeMs || + before.ctimeMs !== after.ctimeMs || await realpath(target) !== target) { + throw new Error(`Source changed while reading: ${path}`); + } + return { path, contents, sha256: hash(bytes), language: languageOf(path) }; + } finally { + await handle.close(); + } +} + +export async function captureInventory(rootInput) { + const root = await realpath(resolve(rootInput)); + const options = { maxBuffer: 64 * 1024 * 1024 }; + const [listing, revision] = await Promise.all([ + execute("git", ["-C", root, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], options), + execute("git", ["-C", root, "rev-parse", "HEAD"], options), + ]); + const paths = [...new Set(listing.stdout.split("\0").filter(Boolean).filter(relevant))].sort(compare); + const files = []; + for (const path of paths) { + try { + files.push(await stableRead(root, path)); + } catch (error) { + if (error.code !== "ENOENT") throw error; + } + } + const selected = files.map(({ path, sha256, language }) => ({ path, sha256, language })); + const status = await execute("git", ["-C", root, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--", + ...files.map(({ path }) => path)], options); + return { + root, + repository: { id: basename(root), revision: revision.stdout.trim(), dirty: status.stdout.length > 0 }, + files, + snapshot: { sha256: hash(serialize(selected)), files: selected }, + }; +} + +export async function assertInventoryCurrent(captured) { + const current = await captureInventory(captured.root); + if (current.repository.revision !== captured.repository.revision || + current.snapshot.sha256 !== captured.snapshot.sha256) { + throw new Error("Source inventory changed during analysis; no baseline was published"); + } +} + +export async function assertBaselineCurrent(root, baseline) { + const current = await captureInventory(root); + if (current.repository.revision !== baseline.repository.revision || + current.snapshot.sha256 !== baseline.source.sha256) { + throw new Error("Baseline is stale for this source snapshot; scan again and deliberately reconcile the authored view"); + } + return current; +} diff --git a/experiments/plugin-spike/src/native-renderer.mjs b/experiments/plugin-spike/src/native-renderer.mjs new file mode 100644 index 0000000..f4d132b --- /dev/null +++ b/experiments/plugin-spike/src/native-renderer.mjs @@ -0,0 +1,76 @@ +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { cliPath, verifyRuntime } from "@jdylanmc/topo-archify"; +import { hash, serialize } from "./contract.mjs"; + +const execute = promisify(execFile); + +function units(value) { + return [...value].reduce((count, character) => count + (character.codePointAt(0) > 255 ? 2 : 1), 0); +} + +export function architectureSpecification(view) { + const cols = view.sections.length <= 3 ? 1 : 2; + const width = Math.max(160, ...view.sections.map(({ title }) => Math.ceil(units(title) * 6.6 + 28))); + const labels = view.connections.map((connection) => + `${connection.classification === "inferred" ? "Inferred: " : ""}${connection.label}`); + const gapX = Math.max(100, ...labels.map((label) => Math.ceil(units(label) * 4.8 + 24))); + const rows = Math.ceil(view.sections.length / cols); + return { + schema_version: 1, + diagram_type: "architecture", + meta: { + title: view.title, output: "diagram.html", quality_profile: "showcase", locale: "en", + viewBox: [Math.max(320, cols * width + (cols - 1) * gapX + 48), + Math.max(240, rows * 52 + (rows - 1) * 48 + 48)], + legend: { mode: "hidden" }, + }, + layout: { mode: "grid", cols, origin: [24, 24], gapX, gapY: 48, cellW: width, cellH: 52 }, + components: view.sections.map(({ id, title, kind }, index) => ({ + id, type: kind === "decision" ? "security" : kind === "data" ? "database" : "backend", icon: "none", label: title, + row: Math.floor(index / cols), col: index % cols, size: [width, 52], + })), + connections: view.connections.map((connection, index) => ({ + id: `edge-${index}`, from: connection.from, to: connection.to, label: labels[index], + ...(connection.classification === "inferred" ? { variant: "dashed" } : {}), + })), + }; +} + +export async function renderNative(view) { + const integrity = verifyRuntime(); + if (integrity.version !== "3.0.0") throw new Error(`Unexpected experimental renderer version: ${integrity.version}`); + const specification = architectureSpecification(view); + const directory = await mkdtemp(join(tmpdir(), "topo-plugin-native-")); + try { + const input = join(directory, "diagram.json"); + const output = join(directory, "diagram.html"); + await writeFile(input, serialize(specification), { flag: "wx" }); + let result; + try { + result = await execute(process.execPath, + [cliPath, "deliver", "architecture", input, output, "--quality", "showcase", "--json"], + { cwd: directory, maxBuffer: 8 * 1024 * 1024, timeout: 120_000 }); + } catch (error) { + throw new Error(`Native Archify delivery failed: ${error.stdout || error.stderr || error.message}`, { cause: error }); + } + const receipt = JSON.parse(result.stdout); + if (receipt.ok !== true || receipt.validation?.checksPassed !== 9 || receipt.validation?.checkCount !== 9 || + receipt.validation?.compositionStatus !== "pass" || receipt.validation.errors !== 0 || receipt.validation.warnings !== 0) { + throw new Error(`Native showcase validation was not complete: ${serialize(receipt.validation)}`); + } + const contents = await readFile(output, "utf8"); + if (hash(contents) !== receipt.artifact.sha256) throw new Error("Native renderer receipt does not match artifact bytes"); + return { + contents, specification, + renderer: { name: "archify", pin: integrity.version, sha256: integrity.archiveSha256 }, + validation: receipt.validation, + specificationSha256: receipt.specification.sha256, + }; + } finally { + await rm(directory, { recursive: true, force: true }); + } +} diff --git a/experiments/plugin-spike/src/plugins/rust.mjs b/experiments/plugin-spike/src/plugins/rust.mjs new file mode 100644 index 0000000..c4542cb --- /dev/null +++ b/experiments/plugin-spike/src/plugins/rust.mjs @@ -0,0 +1,880 @@ +import { parse, registerDynamicLanguage } from "@ast-grep/napi"; +import rust from "@ast-grep/lang-rust"; +import toml from "@iarna/toml"; +import { posix } from "node:path"; +import { compare, emptyContribution, factId, hash, repositoryPath, sourceLocation } from "../contract.mjs"; + +// The napi package bundles web grammars only. This loads the separate prebuilt +// Rust grammar; neither the grammar's postinstall nor a compiler is invoked. +registerDynamicLanguage({ rust }); + +export const manifest = Object.freeze({ + id: "rust", + version: "0.1.0-spike.1", + kind: "language", + languages: ["rust"], + capabilities: ["syntax-declarations", "lexical-ownership", "lexical-binding-observations", "local-impl-targets", "cargo-manifest-evidence", "tauri-syntax-observations"], +}); + +const KINDS = new Map([ + ["struct_item", "struct"], ["enum_item", "enum"], ["union_item", "union"], + ["trait_item", "trait"], ["impl_item", "impl"], ["mod_item", "module"], + ["function_item", "function"], ["function_signature_item", "function"], + ["type_item", "type"], ["associated_type", "type"], ["const_item", "const"], + ["static_item", "static"], ["enum_variant", "variant"], ["field_declaration", "field"], + ["macro_definition", "macro"], ["foreign_mod_item", "extern-block"], + ["extern_crate_declaration", "extern-crate"], +]); +const COMMENT_KINDS = new Set(["line_comment", "block_comment"]); +const ATTRIBUTE_KINDS = new Set(["attribute_item", "inner_attribute_item"]); +const LIMITATIONS = [ + "Tree-sitter syntax evidence, not Rust compiler validation or whole-program semantics.", + "cfg and cfg_attr are recorded but never evaluated; all observed branches remain present.", + "Macros (including derive, attribute/procedural macros and include!) are not expanded.", + "Calls and use declarations remain unresolved; spelling is not semantic name resolution.", + "Impl endpoint edges are limited to unique, direct, nongeneric names in the same lexical scope.", + "Cargo TOML records declared configuration only; no Cargo metadata, dependency resolution, build scripts or compiler execution.", + "Base qualified names remain source-relative lexical names. Extension Rust paths follow only captured Cargo lib/bin roots and explicit default-layout module declarations; custom path/cfg_attr routing and aliases are not resolved.", + "Named item/field declarations are extracted; local bindings are syntax-only extension observations, not entities or resolved names. Tuple-field positions and generic parameter entities are not inventoried.", + "Lexical binding candidates do not resolve Rust namespaces or identifier-versus-constant patterns. Unsupported patterns, conditional binding scopes and opaque statement/item macros are explicit wildcard blockers.", + "Visibility records syntax only; inherited means no explicit modifier, not necessarily private. exported means explicit unrestricted pub, not effective API visibility.", + "The pinned Rust grammar does not fully support modern unsafe extern blocks; parser recovery is flagged rather than repaired or normalized.", + "Tauri observations are syntactic declarations/registration tokens, not macro validity, plugin installation or runtime reachability.", + "Ranges are 1-based UTF-16 code-unit columns with exclusive ends, matching the pinned napi binding's observed offsets.", +]; + +function cleanName(text) { + return text.startsWith("r#") ? text.slice(2) : text; +} + +function location(file, node) { + const { start, end } = node.range(); + return sourceLocation(file.path, start.line + 1, end.line + 1, start.column + 1, end.column + 1); +} + +function tokens(node) { + return node.children().filter((child) => !COMMENT_KINDS.has(child.kind())); +} + +function commaGroups(tree) { + const result = [[]]; + for (const token of tokens(tree).slice(1, -1)) { + if (token.kind() === ",") result.push([]); + else result.at(-1).push(token); + } + return result.filter((group) => group.length); +} + +function stringValue(node) { + if (node.kind() === "raw_string_literal") { + const text = node.text(); + return text.slice(text.indexOf('"') + 1, text.lastIndexOf('"')); + } + if (node.kind() !== "string_literal") return null; + const text = node.text().slice(1, -1); + let result = ""; + for (let index = 0; index < text.length; index++) { + if (text[index] !== "\\") { + result += text[index]; + continue; + } + const escape = text[++index]; + const simple = { n: "\n", r: "\r", t: "\t", "0": "\0", "\\": "\\", '"': '"', "'": "'" }; + if (Object.hasOwn(simple, escape)) result += simple[escape]; + else if (escape === "x" && /^[0-7][0-9a-f]$/i.test(text.slice(index + 1, index + 3))) { + result += String.fromCharCode(Number.parseInt(text.slice(index + 1, index + 3), 16)); + index += 2; + } else if (escape === "u") { + const match = /^\{([0-9a-f_]{1,8})\}/i.exec(text.slice(index + 1)); + const value = match ? Number.parseInt(match[1].replaceAll("_", ""), 16) : NaN; + if (!Number.isInteger(value) || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff)) return null; + result += String.fromCodePoint(value); + index += match[0].length; + } else if (escape === "\n" || (escape === "\r" && text[index + 1] === "\n")) { + if (escape === "\r") index++; + while (/\s/.test(text[index + 1] ?? "") && index + 1 < text.length) index++; + } else return null; + } + return result; +} + +function attributeInfo(node) { + const attribute = node.namedChildren().find((child) => child.kind() === "attribute"); + const path = attribute?.namedChildren().find((child) => child.kind() !== "token_tree")?.text() ?? ""; + return { path, text: node.text(), args: attribute?.field("arguments") ?? null, node }; +} + +function conditionsFor(attributes) { + return attributes.filter((attribute) => attribute.path === "cfg" || attribute.path === "cfg_attr") + .map((attribute) => attribute.text); +} + +function unique(values) { + return [...new Set(values)]; +} + +function signature(node) { + const body = node.field("body"); + return body ? node.text().slice(0, body.range().start.index - node.range().start.index).trimEnd() : node.text(); +} + +function handlerPaths(tree) { + const paths = []; + const rejected = []; + for (const group of commaGroups(tree)) { + let expectName = true; + let valid = true; + const parts = []; + for (const token of group) { + if (token.kind() === "::" && (parts.length === 0 || !expectName)) { + parts.push("::"); + expectName = true; + } else if (expectName && ["identifier", "crate", "self", "super"].includes(token.kind())) { + parts.push(token.text()); + expectName = false; + } else valid = false; + } + if (valid && !expectName) paths.push(parts.join("")); + else rejected.push(group.map((token) => token.text()).join(" ")); + } + return { paths, rejected }; +} + +function registrationContext(node) { + const args = node.parent(); + const call = args?.parent(); + const fn = call?.kind() === "call_expression" ? call.field("function") : null; + if (args?.kind() !== "arguments" || fn?.kind() !== "field_expression" || + fn.field("field")?.text() !== "invoke_handler") return { registrationKind: "unknown" }; + let receiver = fn.field("value"); + while (receiver?.kind() === "call_expression") { + const callee = receiver.field("function"); + if (callee?.kind() === "field_expression") receiver = callee.field("value"); + else { + const rootCallee = callee?.text() ?? ""; + if (rootCallee === "tauri::Builder::default" || rootCallee === "tauri::Builder::new") { + return { registrationKind: "app-builder", receiverRoot: rootCallee }; + } + if (rootCallee === "tauri::plugin::Builder::new") { + const argumentsNode = receiver.field("arguments"); + const firstArgument = argumentsNode?.namedChildren().find((child) => !COMMENT_KINDS.has(child.kind())); + const pluginNamespace = firstArgument ? stringValue(firstArgument) : null; + return { + registrationKind: "plugin-builder", receiverRoot: rootCallee, + pluginNamespaceStatus: pluginNamespace === null ? "unresolved" : "literal", + ...(pluginNamespace === null ? {} : { pluginNamespace }), + }; + } + return { registrationKind: "unknown", receiverRoot: rootCallee }; + } + } + return { registrationKind: "unknown" }; +} + +function cargoRecords(file, inventory, contribution) { + let parsed; + try { + parsed = toml.parse(file.contents); + } catch (error) { + contribution.diagnostics.push({ code: "rust.invalid-cargo-manifest", severity: "error", path: file.path, message: error.message }); + return { manifestPath: file.path, sha256: file.sha256, status: "invalid", evidenceKind: "declared-manifest-only" }; + } + const table = (value) => value !== null && typeof value === "object" && !Array.isArray(value); + const tableKeys = ["package", "workspace", "lib", "dependencies", "dev-dependencies", "build-dependencies", "target", "features"]; + const invalid = tableKeys.some((key) => parsed[key] !== undefined && !table(parsed[key])) || + ["bin", "example", "test", "bench"].some((key) => parsed[key] !== undefined && (!Array.isArray(parsed[key]) || !parsed[key].every(table))) || + Object.values(parsed.target ?? {}).some((value) => !table(value) || + ["dependencies", "dev-dependencies", "build-dependencies"].some((key) => value[key] !== undefined && !table(value[key]))); + if (invalid) { + contribution.diagnostics.push({ code: "rust.invalid-cargo-shape", severity: "error", path: file.path, message: "Cargo manifest tables/target lists have unsupported shapes; no package or dependency facts inferred." }); + return { manifestPath: file.path, sha256: file.sha256, status: "invalid", evidenceKind: "declared-manifest-only" }; + } + const plain = (value) => JSON.parse(JSON.stringify(value)); + const dependencies = []; + function addDependencies(table, target = null) { + for (const kind of ["dependencies", "dev-dependencies", "build-dependencies"]) { + for (const [name, specification] of Object.entries(table?.[kind] ?? {}).sort(([a], [b]) => compare(a, b))) { + dependencies.push({ name, kind, target, specification: plain(specification) }); + } + } + } + addDependencies(parsed); + for (const [target, table] of Object.entries(parsed.target ?? {}).sort(([a], [b]) => compare(a, b))) addDependencies(table, target); + const directory = posix.dirname(file.path); + const targets = []; + function target(kind, value, origin) { + const record = { kind, declaration: plain(value), origin }; + if (typeof value.path === "string") { + const candidate = posix.normalize(posix.join(directory, value.path)); + try { + repositoryPath(candidate); + record.sourcePath = candidate; + record.sourcePresent = inventory.has(candidate); + } catch { + contribution.diagnostics.push({ code: "rust.cargo-target-outside-inventory", severity: "warning", path: file.path, message: `Target path is outside the repository-relative inventory: ${value.path}` }); + } + } + targets.push(record); + } + if (parsed.lib) target("lib", parsed.lib, "manifest"); + for (const kind of ["bin", "example", "test", "bench"]) { + if (Array.isArray(parsed[kind])) for (const value of parsed[kind]) target(kind, value, "manifest"); + } + for (const [kind, path] of [["lib", "src/lib.rs"], ["bin", "src/main.rs"], ["build-script", "build.rs"]]) { + const candidate = posix.join(directory === "." ? "" : directory, path); + if (inventory.has(candidate)) target(kind, { path }, "conventional-source-candidate-not-resolved-target"); + } + if (!parsed.package && !parsed.workspace) { + contribution.diagnostics.push({ code: "rust.manifest-without-package-or-workspace", severity: "warning", path: file.path, message: "TOML parsed, but neither [package] nor [workspace] is present." }); + } + const moduleRoots = []; + function moduleRoot(kind, path, declaredName, rootEvidence, requiredFeatures = []) { + const invalidRoot = () => contribution.diagnostics.push({ + code: "rust.unresolved-cargo-root", severity: "warning", path: file.path, + message: `Cannot establish a contained ${kind} source root from this declared path: ${JSON.stringify(path)}`, + }); + if (typeof path !== "string" || path.startsWith("/") || path.includes("\\")) { + invalidRoot(); + return; + } + const sourcePath = posix.normalize(posix.join(directory, path)); + try { + repositoryPath(sourcePath); + } catch { + invalidRoot(); + return; + } + if (!sourcePath.endsWith(".rs") || !inventory.has(sourcePath)) return; + const crateId = factId("rust", "crate-root", file.path, JSON.stringify([kind, sourcePath, declaredName])); + if (!moduleRoots.some((root) => root.crateId === crateId)) { + moduleRoots.push({ crateId, kind, sourcePath, manifestPath: file.path, declaredName, rootEvidence, requiredFeatures }); + } + } + if (typeof parsed.package?.name === "string") { + const packageName = parsed.package.name.replaceAll("-", "_"); + if (parsed.lib || parsed.package.autolib !== false) { + moduleRoot("lib", parsed.lib?.path ?? "src/lib.rs", parsed.lib?.name ?? packageName, + parsed.lib?.path ? "explicit-lib-path" : "cargo-default-lib-source"); + } + for (const bin of parsed.bin ?? []) { + if (typeof bin.path === "string") { + moduleRoot("bin", bin.path, bin.name ?? packageName, "explicit-bin-path", plain(bin["required-features"] ?? [])); + } + } + const mainSource = posix.join(directory, "src/main.rs"); + if (parsed.package.autobins !== false && !moduleRoots.some((root) => root.kind === "bin" && root.sourcePath === mainSource)) { + moduleRoot("bin", "src/main.rs", packageName, "cargo-default-bin-source"); + } + } + return { + id: factId("rust", "manifest", file.path, "cargo"), + manifestPath: file.path, + sha256: file.sha256, + status: "parsed", + evidenceKind: "declared-manifest-only", cargoSchemaValidated: false, + package: parsed.package ? plain(parsed.package) : null, + workspace: parsed.workspace ? plain(parsed.workspace) : null, + dependencies, + features: plain(parsed.features ?? {}), + targets, + moduleRoots, + }; +} + +/** @param {import("../contract.d.ts").ScanContext} context + * @returns {Promise} */ +export async function scanRust(context) { + const contribution = emptyContribution(manifest.id, manifest.kind, manifest.languages, manifest.capabilities); + const inventory = new Map(); + for (const file of context.files) { + repositoryPath(file.path); + if (inventory.has(file.path)) throw new Error(`Duplicate captured inventory path: ${file.path}`); + if (typeof file.contents !== "string" || hash(file.contents) !== file.sha256) { + throw new Error(`Captured inventory sha256 mismatch: ${file.path}`); + } + inventory.set(file.path, file); + } + const files = [...inventory.values()].sort((a, b) => compare(a.path, b.path)); + const rustFiles = files.filter((file) => file.path.endsWith(".rs")); + const manifests = files.filter((file) => posix.basename(file.path) === "Cargo.toml"); + const metadata = []; + const declarations = []; + const impls = []; + const registrationRecords = new Map(); + const identities = new Map(); + const unresolvedIds = new Set(); + const scopesByName = new Map(); + const bindingIds = new Set(); + const extensions = { + parser: { binding: "@ast-grep/napi", version: "0.45.3", grammar: "@ast-grep/lang-rust", grammarVersion: "0.0.7", backend: "tree-sitter", rangeEncoding: "utf-16", endExclusive: true }, + crates: manifests.map((file) => cargoRecords(file, inventory, contribution)), + entityMetadata: metadata, + attributeObservations: [], + files: [], + tauriCommands: [], + tauriRegistrations: [], + moduleMappings: [], + lexicalScopes: [], + lexicalBindings: [], + useDeclarations: [], + analysisPolicy: { builds: false, cargo: false, compiler: false, procMacros: false, macroExpansion: false, cfgEvaluation: false, callsResolved: false }, + }; + contribution.extensions = extensions; + contribution.coverage.limitations = [...LIMITATIONS]; + contribution.coverage.analyzedFiles = [...manifests, ...rustFiles].map((file) => file.path).sort(compare); + if (!rustFiles.length && !manifests.length) contribution.coverage.status = "unsupported"; + + function unresolved(file, node, kind, text, reason, ownerId, candidates) { + const loc = location(file, node); + const id = factId("rust", `unresolved-${kind}`, file.path, JSON.stringify([node.range().start.index, node.range().end.index, text])); + if (unresolvedIds.has(id)) return; + unresolvedIds.add(id); + contribution.unresolved.push({ id, kind, text, reason, location: loc, ...(ownerId ? { ownerId } : {}), ...(candidates ? { candidates } : {}) }); + } + function edge(from, to, kind, evidence, method = "syntax-explicit-lexical") { + contribution.relationships.push({ + id: factId("rust", kind, evidence.path, JSON.stringify([from, to, evidence])), + from, to, kind, method, evidence: [evidence], + }); + } + + for (const file of rustFiles) { + const metadataStart = metadata.length; + const root = parse("rust", file.contents).root(); + const manifestFile = manifests.filter((candidate) => { + const directory = posix.dirname(candidate.path); + return directory === "." || file.path.startsWith(`${directory}/`); + }).sort((a, b) => b.path.length - a.path.length)[0]; + const fileRecord = { + path: file.path, sha256: file.sha256, status: "parsed", syntaxErrors: 0, + nearestManifestPath: manifestFile?.path ?? null, + manifestAssociation: "directory-containment-only", + }; + extensions.files.push(fileRecord); + if (!manifestFile) contribution.diagnostics.push({ code: "rust.missing-cargo-manifest", severity: "warning", path: file.path, message: "No enclosing Cargo.toml in captured inventory; syntax extraction continues without crate ownership." }); + const diagnosticCodes = new Set(); + function warnOnce(code, message) { + if (diagnosticCodes.has(code)) return; + diagnosticCodes.add(code); + contribution.diagnostics.push({ code, severity: "warning", path: file.path, message }); + } + function lexicalScope(scope, parentScope, kind, node, ownerId) { + const loc = location(file, node); + const existing = scopesByName.get(scope); + if (existing) { + if (JSON.stringify(existing.location) !== JSON.stringify(loc)) { + existing.status = "ambiguous"; + existing.alternateLocations ??= []; + existing.alternateLocations.push(loc); + unsupportedBinding(node, { scope, owner: ownerId ? { id: ownerId } : null, conditions: [] }, + "ambiguous-scope", "Multiple declarations share this lexical scope identity; no unique scope is inferred."); + } + return; + } + const record = { + lexicalScope: scope, parentScope, kind, location: loc, status: "established", + ...(ownerId ? { ownerId } : {}), + }; + scopesByName.set(scope, record); + extensions.lexicalScopes.push(record); + } + function scopedName(scope, kind, node) { + const { start } = node.range(); + return `${scope}::<${kind}@${start.line + 1}:${start.column + 1}>`; + } + function binding(node, state, kind, name, options = {}) { + const id = factId("rust", "lexical-binding", file.path, + JSON.stringify([state.scope, kind, name, node.range().start.index, node.range().end.index, options.entityId ?? null])); + if (bindingIds.has(id)) return; + bindingIds.add(id); + extensions.lexicalBindings.push({ + id, ...(name === null ? { wildcard: true } : { name: cleanName(name) }), + kind, lexicalScope: state.scope, location: location(file, node), text: node.text(), + availability: "whole-scope", bindingStatus: "syntactic-candidate", + ...(state.owner?.id ? { ownerId: state.owner.id } : {}), + ...(state.conditions?.length ? { conditions: state.conditions } : {}), + ...options, + }); + } + function unsupportedBinding(node, state, kind, reason, options = {}) { + binding(node, state, kind, null, { ...options, bindingStatus: "unsupported", reason }); + warnOnce("rust.lexical-bindings-partial", "Unsupported binding syntax/scopes and opaque macros are explicit wildcard observations; lexical absence is not semantic resolution."); + unresolved(file, node, "lexical-binding", node.text(), reason, state.owner?.id); + } + function bindPattern(node, state, kind, options = {}) { + const syntax = node.kind(); + if (["identifier", "shorthand_field_identifier", "self"].includes(syntax)) { + if (node.text() !== "_") binding(node, state, kind, node.text(), options); + } else if (syntax === "field_pattern") { + const pattern = node.field("pattern"); + const name = node.field("name"); + if (pattern) bindPattern(pattern, state, kind, options); + else if (name?.kind() === "shorthand_field_identifier") bindPattern(name, state, kind, options); + else unsupportedBinding(node, state, "unsupported-pattern", "Unsupported field-pattern binding.", options); + } else if (["tuple_pattern", "tuple_struct_pattern", "struct_pattern", "slice_pattern", "ref_pattern", + "mut_pattern", "reference_pattern", "captured_pattern", "match_pattern"].includes(syntax)) { + const type = node.field("type"); + const condition = node.field("condition"); + for (const child of node.namedChildren()) { + if (child.id() !== type?.id() && child.id() !== condition?.id()) bindPattern(child, state, kind, options); + } + } else if (node.text() === "_" || ["remaining_field_pattern", "mutable_specifier", + "scoped_identifier", "type_identifier", "integer_literal", "float_literal", "boolean_literal", + "string_literal", "raw_string_literal", "char_literal", "negative_literal", "range_pattern", + "unit_expression"].includes(syntax) || COMMENT_KINDS.has(syntax)) { + return; + } else { + unsupportedBinding(node, state, "unsupported-pattern", `Unsupported or ambiguous ${syntax} binding pattern; names are not guessed.`, options); + } + } + function useLeaf(node) { + if (!node) return null; + if (node.kind() === "scoped_identifier") { + const name = node.field("name"); + return name?.kind() === "self" ? useLeaf(node.field("path")) : useLeaf(name); + } + return ["identifier", "self", "super", "crate"].includes(node.kind()) ? node.text() : null; + } + function bindUse(node, state, prefixLeaf, useDeclarationId) { + const syntax = node.kind(); + const options = { bindingStatus: "unresolved-import", useDeclarationId }; + const unsupported = (reason) => unsupportedBinding(node, state, "unsupported-use", reason, { useDeclarationId }); + if (syntax === "use_list") { + for (const child of node.namedChildren()) if (!COMMENT_KINDS.has(child.kind())) bindUse(child, state, prefixLeaf, useDeclarationId); + } else if (syntax === "scoped_use_list") { + const path = node.field("path"); + const leaf = useLeaf(path); + const list = node.namedChildren().find((child) => child.kind() === "use_list"); + if (list) bindUse(list, state, leaf === "self" ? prefixLeaf : leaf, useDeclarationId); + else unsupported("Use-list structure is incomplete; introduced names are unknown."); + } else if (syntax === "use_as_clause") { + const alias = node.field("alias"); + if (alias?.kind() === "identifier") { + if (alias.text() !== "_") binding(alias, state, "use-alias", alias.text(), options); + } else unsupported("Use alias is not a parsed identifier."); + } else if (syntax === "use_wildcard") { + binding(node, state, "use-glob", null, { ...options, reason: "Glob-imported names are not resolved." }); + } else if (syntax === "self") { + if (prefixLeaf) binding(node, state, "use-self", prefixLeaf, options); + else unsupported("Self import has no established syntactic prefix name."); + } else { + const name = useLeaf(node); + if (name && !["crate", "super", "self", "_"].includes(name)) binding(node, state, "use", name, options); + else unsupported(`Unsupported ${syntax} use tree; introduced names are unknown.`); + } + } + function recordAttributes(attributes, ownerId) { + for (const attribute of attributes) { + extensions.attributeObservations.push({ + path: attribute.path, text: attribute.text, location: location(file, attribute.node), + attachment: attribute.node.kind() === "inner_attribute_item" ? "inner" : "outer", + ...(ownerId ? { ownerId } : {}), + }); + if (attribute.path === "cfg" || attribute.path === "cfg_attr") { + warnOnce("rust.cfg-unevaluated", "cfg/cfg_attr conditions are preserved, not evaluated."); + unresolved(file, attribute.node, "cfg", attribute.text, "Condition unevaluated; no active-branch claim.", ownerId); + } else if (!["doc", "allow", "warn", "deny", "forbid", "test", "ignore", "inline", "cold", "must_use", "repr", "path", "no_mangle", "export_name", "link", "link_name"].includes(attribute.path)) { + warnOnce("rust.attributes-unexpanded", "Nontrivial attributes, including derive and potential procedural macros, are not expanded or validated."); + unresolved(file, attribute.node, "attribute", attribute.text, "Attribute syntax only; effect and macro expansion unknown.", ownerId); + } + } + } + function command(entity, attributes, conditions) { + const commandAttributes = attributes.filter((attribute) => attribute.path === "tauri::command"); + if (commandAttributes.length > 1) { + warnOnce("rust.ambiguous-tauri-command", "Multiple tauri::command attributes on one declaration; no unique command observation emitted."); + return; + } + const attribute = commandAttributes[0]; + if (!attribute) return; + let commandName = entity.name; + let renameAll = null; + let invalidRename = false; + let seenRename = false; + for (const group of attribute.args ? commaGroups(attribute.args) : []) { + const option = group[0].text(); + if (option !== "rename" && option !== "rename_all") continue; + const value = group.length === 3 && group[1].kind() === "=" ? stringValue(group[2]) : null; + if (value === null || (option === "rename" && seenRename)) { + invalidRename = true; + unresolved(file, attribute.node, "tauri-command-options", attribute.text, "Unsupported or duplicate rename option; command name not inferred.", entity.id); + } else if (option === "rename") { + seenRename = true; + commandName = value; + } else renameAll = value; + } + if (!invalidRename) { + extensions.tauriCommands.push({ + entityId: entity.id, commandName, location: entity.location, conditions, + attributeLocation: location(file, attribute.node), argumentRenameAll: renameAll, + evidenceKind: "unexpanded-command-attribute", runtimeReachability: "unknown", + }); + } + } + function visitContainer(container, state) { + const children = container.children(); + const inner = children.filter((node) => node.kind() === "inner_attribute_item").map(attributeInfo); + recordAttributes(inner, state.owner?.id); + const inherited = unique([...state.conditions, ...conditionsFor(inner)]); + let pending = []; + for (const child of children) { + if (child.kind() === "inner_attribute_item") continue; + if (child.kind() === "attribute_item") { + pending.push(attributeInfo(child)); + continue; + } + if (COMMENT_KINDS.has(child.kind())) continue; + if (!child.isNamed() && child.text()) continue; + const attributes = pending; + pending = []; + visit(child, { ...state, conditions: inherited }, attributes); + } + recordAttributes(pending, state.owner?.id); + } + function visit(node, state, attributes = []) { + const syntaxKind = node.kind(); + if (syntaxKind === "ERROR" || (node.text() === "" && syntaxKind !== "source_file")) { + fileRecord.status = "recovered-with-errors"; + fileRecord.syntaxErrors++; + warnOnce("rust.syntax-error", "Tree-sitter recovered malformed or missing syntax; declarations are partial syntax evidence."); + unresolved(file, node, "syntax-error", node.text() || ``, "Parser recovery; Rust validity unknown.", state.owner?.id); + unsupportedBinding(node, state, "recovered-syntax-bindings", "Parser recovery may conceal bindings in this lexical scope."); + } + const conditions = unique([...state.conditions, ...conditionsFor(attributes)]); + let owner = state.owner; + let kind = KINDS.get(syntaxKind); + if (kind === "function" && ["impl", "trait"].includes(owner?.kind)) kind = "method"; + if (kind) { + const rawName = node.field("name")?.text(); + const header = signature(node); + const name = rawName ? cleanName(rawName) : kind === "impl" ? header : kind === "extern-block" ? header : ``; + const loc = location(file, node); + const segment = ["impl", "extern-block"].includes(kind) ? `${name}@${loc.startLine}:${loc.startColumn}` : name; + const qualifiedName = `${state.scope}::${segment}`; + const visibility = node.children().find((child) => child.kind() === "visibility_modifier")?.text() ?? "inherited"; + const id = factId("rust", kind, file.path, JSON.stringify([qualifiedName, node.range().start.index])); + const entity = { + id, language: "rust", kind, name, qualifiedName, location: loc, + exported: visibility === "pub", signatures: [header], attributes: attributes.map((attribute) => attribute.text), + ...(owner ? { ownerId: owner.id } : {}), + }; + contribution.entities.push(entity); + const syntaxStatus = node.find({ rule: { kind: "ERROR" } }) ? "recovered-with-errors" : "parsed"; + const record = { entity, node, file, fileRecord, scope: state.scope, moduleScope: state.moduleScope, attributes, conditions, syntaxStatus }; + declarations.push(record); + const identityKey = JSON.stringify([file.path, state.scope, kind, name]); + if (!["impl", "extern-block"].includes(kind)) { + const records = identities.get(identityKey) ?? []; + records.push(record); + identities.set(identityKey, records); + } + metadata.push({ + entityId: id, syntaxKind, syntaxStatus, rawName: rawName ?? null, visibility, conditions, + attributeLocations: attributes.map((attribute) => location(file, attribute.node)), + lexicalScope: state.scope, + ...(kind === "impl" ? { targetType: node.field("type")?.text() ?? null, traitPath: node.field("trait")?.text() ?? null } : {}), + ...(kind === "module" ? { outOfLine: !node.field("body") } : {}), + }); + if (rawName && kind !== "field") { + const nameNode = kind === "extern-crate" ? node.field("alias") ?? node.field("name") : node.field("name"); + const containingScope = owner?.kind === "extern-block" ? scopesByName.get(state.scope)?.parentScope ?? state.scope : state.scope; + binding(nameNode, { ...state, scope: containingScope, conditions }, kind, nameNode.text(), { + entityId: id, bindingStatus: "declared", + }); + } + lexicalScope(qualifiedName, state.scope, kind, node, id); + if (owner) edge(owner.id, id, "owns", loc); + if (kind === "impl") impls.push(record); + if (kind === "function" || kind === "method") command(entity, attributes, conditions); + owner = entity; + state = { ...state, scope: qualifiedName, ...(kind === "module" ? { moduleScope: qualifiedName } : {}) }; + } + recordAttributes(attributes, owner?.id); + if (syntaxKind === "closure_expression" || syntaxKind === "match_arm") { + const scope = scopedName(state.scope, syntaxKind === "closure_expression" ? "closure" : "match-arm", node); + lexicalScope(scope, state.scope, syntaxKind, node, owner?.id); + state = { ...state, scope }; + } + const condition = ["if_expression", "while_expression"].includes(syntaxKind) ? node.field("condition") : null; + if (condition?.find({ rule: { kind: "let_condition" } })) { + const scope = scopedName(state.scope, "conditional", node); + lexicalScope(scope, state.scope, "unsupported-conditional-scope", node, owner?.id); + state = { ...state, scope }; + unsupportedBinding(condition, { ...state, owner, conditions }, "unsupported-conditional-bindings", + "Precise conditional binding scopes are unsupported; this conservative scope covers the condition and its branches, not surrounding statements."); + } + const bindingState = { ...state, owner, conditions }; + if (syntaxKind === "parameter" && node.parent()?.kind() === "parameters" && + ["function_item", "function_signature_item"].includes(node.parent()?.parent()?.kind())) { + const pattern = node.field("pattern"); + if (pattern) bindPattern(pattern, bindingState, "parameter"); + else unsupportedBinding(node, bindingState, "unsupported-parameter", "Parameter binding pattern is missing or unsupported."); + } else if (syntaxKind === "self_parameter") { + const self = node.namedChildren().find((child) => child.kind() === "self"); + binding(self ?? node, bindingState, "parameter", "self"); + } else if (syntaxKind === "closure_parameters") { + for (const parameter of node.namedChildren()) { + if (COMMENT_KINDS.has(parameter.kind())) continue; + const pattern = parameter.kind() === "parameter" ? parameter.field("pattern") : parameter; + if (pattern) bindPattern(pattern, bindingState, "closure-parameter"); + else unsupportedBinding(parameter, bindingState, "unsupported-parameter", "Closure parameter pattern is missing."); + } + } else if (syntaxKind === "let_declaration") { + const pattern = node.field("pattern"); + const end = node.range().end; + const options = { + availability: "after-statement", + visibleAfter: sourceLocation(file.path, end.line + 1, end.line + 1, end.column + 1, end.column + 1), + }; + if (pattern) bindPattern(pattern, bindingState, "let-pattern", options); + else unsupportedBinding(node, bindingState, "unsupported-pattern", "Let declaration has no supported pattern.", options); + } else if (syntaxKind === "for_expression") { + const pattern = node.field("pattern"); + const body = node.field("body"); + if (pattern && body?.kind() === "block") { + bindPattern(pattern, { ...bindingState, scope: scopedName(state.scope, "block", body) }, "for-pattern"); + } else unsupportedBinding(node, bindingState, "unsupported-pattern", "For-loop pattern/body scope is unsupported."); + } else if (syntaxKind === "match_arm") { + const pattern = node.field("pattern"); + if (pattern) bindPattern(pattern, bindingState, "match-pattern"); + else unsupportedBinding(node, bindingState, "unsupported-pattern", "Match-arm pattern is missing."); + } else if (["type_parameter", "const_parameter"].includes(syntaxKind)) { + const name = node.field("name"); + if (name) binding(name, bindingState, "generic-parameter", name.text()); + } + if (syntaxKind === "call_expression") { + const callee = node.field("function"); + unresolved(file, node, "call", callee?.text() ?? node.text(), "Callee spelling only; imports, receiver types, traits, cfg and dynamic dispatch are not resolved.", owner?.id); + } else if (syntaxKind === "use_declaration") { + unresolved(file, node, "use", node.text(), "Import/re-export tree preserved; targets and aliases not resolved.", owner?.id); + const useDeclarationId = factId("rust", "use-declaration", file.path, String(node.range().start.index)); + extensions.useDeclarations.push({ + id: useDeclarationId, text: node.text(), location: location(file, node), + lexicalScope: state.scope, moduleLexicalScope: state.moduleScope, conditions, + ...(owner?.id ? { ownerId: owner.id } : {}), + }); + const argument = node.field("argument"); + if (argument) bindUse(argument, bindingState, null, useDeclarationId); + else unsupportedBinding(node, bindingState, "unsupported-use", "Use declaration has no parsed use tree.", { useDeclarationId }); + } else if (syntaxKind === "extern_crate_declaration") { + unresolved(file, node, "extern-crate", node.text(), "Declared external crate; Cargo graph not resolved.", owner?.id); + } else if (syntaxKind === "macro_invocation") { + const macro = node.field("macro")?.text() ?? node.namedChildren()[0]?.text() ?? ""; + unresolved(file, node, "macro", node.text(), "Macro invocation tokens retained; no expansion or generated declaration inference.", owner?.id); + warnOnce("rust.macros-unexpanded", "Macro invocations are retained as unresolved syntax facts."); + if (macro !== "tauri::generate_handler" && ["source_file", "declaration_list", "expression_statement"].includes(node.parent()?.kind())) { + unsupportedBinding(node, bindingState, "unexpanded-macro-bindings", "An unexpanded statement/item macro may introduce bindings in this scope."); + } + if (macro === "tauri::generate_handler") { + const tree = node.namedChildren().find((child) => child.kind() === "token_tree"); + if (tree) { + const { paths, rejected } = handlerPaths(tree); + const registration = { + location: location(file, node), rustPaths: paths, conditions, + ...registrationContext(node), + evidenceKind: "unexpanded-handler-macro", runtimeReachability: "unknown", + ...(owner ? { ownerId: owner.id } : {}), rejectedTokens: rejected, + pathResolution: "unresolved-token-paths", + modulePath: null, + lexicalScope: state.scope, + moduleLexicalScope: state.moduleScope, + }; + extensions.tauriRegistrations.push(registration); + registrationRecords.set(registration, { file, node, moduleScope: state.moduleScope }); + if (registration.pluginNamespaceStatus === "unresolved") { + unresolved(file, node, "tauri-plugin-namespace", node.text(), "Plugin builder name is not a parsed literal; plugin namespace not inferred.", owner?.id); + } + for (const text of rejected) unresolved(file, node, "tauri-handler-tokens", text, "Unsupported handler token group; not interpreted as a Rust path.", owner?.id); + } + } + return; + } + if (syntaxKind === "macro_definition") { + unresolved(file, node, "macro-definition", node.text(), "Macro definition body retained, never parsed as expanded declarations.", owner?.id); + return; + } + if (COMMENT_KINDS.has(syntaxKind) || ATTRIBUTE_KINDS.has(syntaxKind) || + ["token_tree", "token_tree_pattern", "string_literal", "raw_string_literal", "char_literal"].includes(syntaxKind)) return; + const next = { + owner, + scope: syntaxKind === "block" ? scopedName(state.scope, "block", node) : state.scope, + conditions, + moduleScope: state.moduleScope, + }; + if (syntaxKind === "block") lexicalScope(next.scope, state.scope, "block", node, owner?.id); + if (["block", "declaration_list", "source_file", "field_declaration_list", "enum_variant_list"].includes(syntaxKind)) { + visitContainer(node, next); + } else { + for (const child of node.namedChildren()) visit(child, next); + } + } + lexicalScope(file.path, null, "source-file", root); + visit(root, { owner: null, scope: file.path, moduleScope: file.path, conditions: [] }); + for (const record of metadata.slice(metadataStart)) record.fileSyntaxStatus = fileRecord.status; + } + for (const records of identities.values()) { + if (records.length < 2) continue; + const { entity, file, node } = records[0]; + contribution.diagnostics.push({ + code: "rust.ambiguous-identity", severity: "warning", path: file.path, + message: `Multiple ${entity.kind} declarations share lexical identity ${entity.qualifiedName}; cfg is not evaluated.`, + }); + unresolved(file, node, "duplicate-identity", entity.qualifiedName, "Multiple declarations, no unique endpoint selected.", entity.ownerId, records.map((record) => record.entity.id)); + } + const moduleContexts = new Map(); + const modules = declarations.filter((record) => record.entity.kind === "module"); + const seenModules = new Set(); + const queue = extensions.crates.flatMap((crate) => (crate.moduleRoots ?? []).map((root) => ({ + crateId: root.crateId, rootSourcePath: root.sourcePath, + sourcePath: root.sourcePath, moduleScope: root.sourcePath, rustModulePath: "crate", + moduleDirectory: posix.dirname(root.sourcePath), conditions: [], + evidence: [sourceLocation(root.manifestPath, 1)], sourceChain: [root.sourcePath], + }))); + for (let index = 0; index < queue.length; index++) { + const context = queue[index]; + const contexts = moduleContexts.get(context.moduleScope) ?? []; + contexts.push(context); + moduleContexts.set(context.moduleScope, contexts); + const children = modules.filter((record) => record.file.path === context.sourcePath && record.scope === context.moduleScope); + for (const child of children) { + seenModules.add(child.entity.id); + const name = child.node.field("name")?.text() ?? ""; + const rustModulePath = `${context.rustModulePath}::${name}`; + const conditions = unique([...context.conditions, ...child.conditions]); + const evidence = [...context.evidence, child.entity.location]; + const mapping = { + moduleEntityId: child.entity.id, crateId: context.crateId, rustModulePath, + location: child.entity.location, conditions, evidence, + }; + const inline = Boolean(child.node.field("body")); + const sourceCandidates = !name ? [] : inline ? [child.file.path] : [ + posix.join(context.moduleDirectory, `${cleanName(name)}.rs`), + posix.join(context.moduleDirectory, cleanName(name), "mod.rs"), + ].filter((path) => inventory.has(path)); + let reason; + if (!name) reason = "Module name is missing; source ownership not established."; + else if (child.fileRecord.status !== "parsed") reason = "Module declaration is in a recovered file; source ownership not established."; + else if (child.attributes.some((attribute) => ["path", "cfg_attr"].includes(attribute.path))) reason = "Module path/cfg_attr routing is not interpreted."; + else if (children.filter((candidate) => candidate.entity.name === child.entity.name).length > 1) reason = "Duplicate module declarations require cfg selection; no unique module owner."; + else if (sourceCandidates.length !== 1) reason = sourceCandidates.length ? "Both default Rust module files exist; ownership is ambiguous." : "Declared module source is absent from the captured inventory."; + else if (!inline && context.sourceChain.includes(sourceCandidates[0])) reason = "Cyclic module-source mapping is unsupported."; + if (reason) { + mapping.status = sourceCandidates.length > 1 || reason.startsWith("Duplicate") ? "ambiguous" : "unresolved"; + mapping.reason = reason; + mapping.candidates = sourceCandidates; + unresolved(child.file, child.node, "module-source", child.node.text(), reason, child.entity.id); + } else { + const sourcePath = sourceCandidates[0]; + mapping.status = "established"; + mapping.sourcePath = sourcePath; + queue.push({ + crateId: context.crateId, rootSourcePath: context.rootSourcePath, + sourcePath, moduleScope: inline ? child.entity.qualifiedName : sourcePath, + rustModulePath, conditions, evidence, + moduleDirectory: posix.join(context.moduleDirectory, cleanName(name)), + sourceChain: inline ? context.sourceChain : [...context.sourceChain, sourcePath], + }); + } + extensions.moduleMappings.push(mapping); + } + } + for (const child of modules.filter((record) => !seenModules.has(record.entity.id) && !record.node.field("body"))) { + const reason = "No supported Cargo-root module chain reaches this declaration; local/macro/alias/custom module contexts are not inferred."; + extensions.moduleMappings.push({ moduleEntityId: child.entity.id, location: child.entity.location, status: "unresolved", reason, candidates: [] }); + unresolved(child.file, child.node, "module-source", child.node.text(), reason, child.entity.id); + } + const declarationsById = new Map(declarations.map((record) => [record.entity.id, record])); + function pathCandidates(scope, conditions, segment) { + return (moduleContexts.get(scope) ?? []).map((context) => ({ + crateId: context.crateId, rootSourcePath: context.rootSourcePath, + rustModulePath: context.rustModulePath, + ...(segment ? { rustPath: `${context.rustModulePath}::${segment}` } : {}), + conditions: unique([...context.conditions, ...conditions]), evidence: context.evidence, + })); + } + for (const command of extensions.tauriCommands) { + const record = declarationsById.get(command.entityId); + const candidates = record.entity.kind === "function" && record.scope === record.moduleScope && + record.fileRecord.status === "parsed" ? pathCandidates(record.moduleScope, command.conditions, record.node.field("name").text()) : []; + command.rustPathCandidates = candidates; + command.rustPathStatus = candidates.length === 1 ? "established" : candidates.length ? "ambiguous" : "unresolved"; + if (candidates.length === 1) { + const candidate = candidates[0]; + Object.assign(command, { + rustPath: candidate.rustPath, crateId: candidate.crateId, + rustModulePath: candidate.rustModulePath, conditions: candidate.conditions, + rustPathEvidence: candidate.evidence, + }); + } else { + unresolved(record.file, record.node, "tauri-command-path", record.entity.name, + candidates.length ? "Multiple declared crate/module contexts; no unique command path selected." : + "Command is not an unrecovered module-level function reached by a supported declared Cargo/module chain.", + record.entity.id); + } + } + const commandsByPath = new Map(); + for (const command of extensions.tauriCommands.filter((item) => item.rustPathStatus === "established")) { + const key = JSON.stringify([command.crateId, command.rustPath.split("::").map(cleanName)]); + const commands = commandsByPath.get(key) ?? []; + commands.push(command); + commandsByPath.set(key, commands); + } + for (const commands of commandsByPath.values()) { + if (commands.length < 2) continue; + const candidates = commands.map((command) => ({ ...command.rustPathCandidates[0], entityId: command.entityId })); + for (const command of commands) { + const record = declarationsById.get(command.entityId); + command.rustPathStatus = "ambiguous"; + command.rustPathCandidates = candidates; + for (const field of ["rustPath", "crateId", "rustModulePath", "rustPathEvidence"]) delete command[field]; + unresolved(record.file, record.node, "tauri-command-path", record.entity.name, + "Multiple command declarations share this declared path; cfg is unevaluated and no endpoint is selected.", + record.entity.id, commands.map((item) => item.entityId)); + } + } + for (const registration of extensions.tauriRegistrations) { + const record = registrationRecords.get(registration); + const candidates = pathCandidates(record.moduleScope, registration.conditions); + registration.moduleContextCandidates = candidates; + registration.moduleContextStatus = candidates.length === 1 ? "established" : candidates.length ? "ambiguous" : "unresolved"; + if (candidates.length === 1) { + const candidate = candidates[0]; + Object.assign(registration, { + crateId: candidate.crateId, rustModulePath: candidate.rustModulePath, + modulePath: candidate.rustModulePath, + conditions: candidate.conditions, moduleContextEvidence: candidate.evidence, + }); + } else { + unresolved(record.file, record.node, "tauri-registration-context", record.node.text(), + "No unique declared crate/module context; handler token paths and aliases remain unresolved.", registration.ownerId); + } + } + for (const implementation of impls) { + for (const [field, kinds, relationship] of [ + ["type", ["struct", "enum", "union", "type"], "impl-for"], + ["trait", ["trait"], "impl-trait"], + ]) { + const target = implementation.node.field(field); + if (!target) continue; + const name = cleanName(target.text()); + const parameters = implementation.node.field("type_parameters"); + const shadows = parameters?.findAll({ rule: { kind: "type_identifier" } }).some((node) => cleanName(node.text()) === name); + const candidates = target.kind() === "type_identifier" && !shadows ? declarations.filter((record) => + record.file.path === implementation.file.path && record.scope === implementation.scope && + record.entity.name === name && kinds.includes(record.entity.kind)) : []; + if (candidates.length === 1 && candidates[0].syntaxStatus === "parsed" && implementation.syntaxStatus === "parsed" && + implementation.fileRecord.status === "parsed") { + edge(implementation.entity.id, candidates[0].entity.id, relationship, location(implementation.file, target), "syntax-explicit-unique-local-name"); + } else { + unresolved(implementation.file, target, `impl-${field}`, target.text(), + candidates.length > 1 ? "Ambiguous local declarations; cfg not evaluated." : "Endpoint is not a unique unrecovered direct nongeneric name in this lexical scope.", + implementation.entity.id, candidates.map((record) => record.entity.id)); + } + } + } + contribution.entities.sort((a, b) => compare(a.id, b.id)); + contribution.relationships.sort((a, b) => compare(a.id, b.id)); + contribution.unresolved.sort((a, b) => compare(a.id, b.id)); + contribution.diagnostics.sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b))); + return contribution; +} diff --git a/experiments/plugin-spike/src/plugins/tauri.mjs b/experiments/plugin-spike/src/plugins/tauri.mjs new file mode 100644 index 0000000..f27a1eb --- /dev/null +++ b/experiments/plugin-spike/src/plugins/tauri.mjs @@ -0,0 +1,370 @@ +import { resolve } from "node:path"; +import { compiler } from "../topocode.mjs"; +import { compare, emptyContribution, factId, serialize, sourceLocation } from "../contract.mjs"; + +export const manifest = { id: "tauri", kind: "framework", requires: ["typescript", "rust"] }; + +export async function scanTauri(context, contributions) { + const result = emptyContribution("tauri", "framework", ["typescript", "javascript", "rust"], + ["source-command-registrations", "literal-invocations", "bounded-constant-invocations", "known-wrapper-call-sites"]); + const rust = contributions.find(({ plugin }) => plugin.id === "rust"); + if (!rust) throw new Error("Tauri analysis requires the Rust contribution"); + const ts = await compiler(); + const sourceFiles = context.files.filter(({ path }) => /\.(?:[cm]?[jt]s|[jt]sx)$/.test(path)); + const sources = new Map(sourceFiles.map((file) => [ + resolve(context.root, file.path), + ts.createSourceFile(resolve(context.root, file.path), file.contents, ts.ScriptTarget.Latest, true), + ])); + const options = { + allowJs: true, checkJs: false, noEmit: true, noLib: true, + module: ts.ModuleKind.NodeNext, moduleResolution: ts.ModuleResolutionKind.NodeNext, + target: ts.ScriptTarget.ESNext, skipLibCheck: true, + }; + const host = ts.createCompilerHost(options); + host.getSourceFile = (path) => sources.get(resolve(path)); + host.readFile = (path) => context.files.find((file) => resolve(context.root, file.path) === resolve(path))?.contents; + host.fileExists = (path) => sources.has(resolve(path)) || context.files.some((file) => resolve(context.root, file.path) === resolve(path)); + host.writeFile = () => { throw new Error("The framework analyzer must never emit compiler output"); }; + host.getCurrentDirectory = () => context.root; + const program = ts.createProgram([...sources.keys()], options, host); + const checker = program.getTypeChecker(); + const paths = new Map(sourceFiles.map((file) => [resolve(context.root, file.path), file.path])); + const calls = []; + const writtenSymbols = new Set(); + const opaqueFunctions = new Set(); + function writtenTarget(node) { + node = unwrap(node); + if (ts.isIdentifier(node)) { + const symbol = checker.getSymbolAtLocation(node); + if (symbol) writtenSymbols.add(symbol); + } else if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) { + const symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node); + if (symbol) writtenSymbols.add(symbol); + } else if (ts.isArrayLiteralExpression(node)) { + node.elements.forEach(writtenTarget); + } else if (ts.isObjectLiteralExpression(node)) { + for (const property of node.properties) { + if (ts.isPropertyAssignment(property)) writtenTarget(property.initializer); + else if (ts.isShorthandPropertyAssignment(property)) { + const symbol = checker.getShorthandAssignmentValueSymbol(property); + if (symbol) writtenSymbols.add(symbol); + } else if (ts.isSpreadAssignment(property)) writtenTarget(property.expression); + } + } else if (ts.isSpreadElement(node) || ts.isParenthesizedExpression(node)) { + writtenTarget(node.expression); + } else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) { + writtenTarget(node.left); + } + } + const parsed = []; + for (const source of sources.values()) { + const path = paths.get(source.fileName); + if (source.parseDiagnostics.length) { + result.diagnostics.push({ code: "tauri-frontend-parse-error", severity: "error", + message: "Frontend syntax errors prevented trustworthy invocation extraction.", path }); + continue; + } + parsed.push(path); + const visit = (node) => { + if (ts.isCallExpression(node)) { + calls.push(node); + if (ts.isIdentifier(unwrap(node.expression)) && unwrap(node.expression).text === "eval") { + for (let owner = node.parent; owner; owner = owner.parent) if (ts.isFunctionLike(owner)) opaqueFunctions.add(owner); + } + } + if (ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && + node.operatorToken.kind <= ts.SyntaxKind.LastAssignment) writtenTarget(node.left); + if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) && + [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(node.operator)) writtenTarget(node.operand); + if ((ts.isForOfStatement(node) || ts.isForInStatement(node)) && + !ts.isVariableDeclarationList(node.initializer)) writtenTarget(node.initializer); + ts.forEachChild(node, visit); + }; + visit(source); + } + function location(node) { + const source = node.getSourceFile(); + const start = source.getLineAndCharacterOfPosition(node.getStart(source)); + const end = source.getLineAndCharacterOfPosition(node.getEnd()); + return sourceLocation(paths.get(source.fileName), start.line + 1, end.line + 1, start.character + 1, end.character + 1); + } + function unwrap(node) { + while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || + ts.isNonNullExpression(node) || ts.isSatisfiesExpression(node) || ts.isTypeAssertionExpression(node))) { + node = node.expression; + } + return node; + } + function declarations(node, aliases = false) { + const symbol = checker.getSymbolAtLocation(node); + if (!symbol) return []; + if (aliases && symbol.flags & ts.SymbolFlags.Alias) { + return checker.getAliasedSymbol(symbol).declarations ?? []; + } + return symbol.declarations ?? []; + } + function importedFromCore(node) { + while (node && !ts.isImportDeclaration(node)) node = node.parent; + return node && !node.importClause?.isTypeOnly && ts.isStringLiteral(node.moduleSpecifier) && + node.moduleSpecifier.text === "@tauri-apps/api/core"; + } + function isConst(declaration) { + return ts.isVariableDeclaration(declaration) && ts.isVariableDeclarationList(declaration.parent) && + Boolean(declaration.parent.flags & ts.NodeFlags.Const); + } + function isInvoke(expression, seen = new Set()) { + expression = unwrap(expression); + if (!expression || seen.has(expression)) return false; + const next = new Set(seen).add(expression); + if (ts.isIdentifier(expression)) { + return declarations(expression).some((declaration) => { + if (ts.isImportSpecifier(declaration)) { + return !declaration.isTypeOnly && (declaration.propertyName ?? declaration.name).text === "invoke" && + importedFromCore(declaration); + } + return isConst(declaration) && declaration.initializer && isInvoke(declaration.initializer, next); + }); + } + const member = ts.isPropertyAccessExpression(expression) ? expression.name.text : + ts.isElementAccessExpression(expression) && ts.isStringLiteral(expression.argumentExpression) + ? expression.argumentExpression.text : undefined; + return member === "invoke" && declarations(expression.expression).some((declaration) => + ts.isNamespaceImport(declaration) && importedFromCore(declaration)); + } + function functionForCall(call) { + let expression = unwrap(call.expression); + if (ts.isPropertyAccessExpression(expression)) expression = expression.name; + let symbol = checker.getSymbolAtLocation(expression); + if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol); + if (writtenSymbols.has(symbol)) return []; + return declarations(expression, true).flatMap((declaration) => { + if ((ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration)) && declaration.body) return [declaration]; + if (ts.isVariableDeclaration(declaration) && declaration.initializer) { + const initializer = unwrap(declaration.initializer); + if (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer)) return [initializer]; + } + return []; + }); + } + const callsByFunction = new Map(); + for (const call of calls) { + for (const fn of functionForCall(call)) { + const list = callsByFunction.get(fn) ?? []; + list.push(call); + callsByFunction.set(fn, list); + } + } + function strings(node, seen = new Set(), depth = 0) { + node = unwrap(node); + if (!node || depth > 8 || seen.has(node)) return { values: [], complete: false }; + const next = new Set(seen).add(node); + if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) { + return { values: [{ value: node.text, origin: location(node), evidence: [location(node)] }], complete: true }; + } + if (ts.isConditionalExpression(node)) { + const a = strings(node.whenTrue, next, depth + 1); + const b = strings(node.whenFalse, next, depth + 1); + return { values: [...a.values, ...b.values], complete: a.complete && b.complete }; + } + if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) { + const a = strings(node.left, next, depth + 1); + const b = strings(node.right, next, depth + 1); + if (!a.complete || !b.complete || a.values.length * b.values.length > 32) return { values: [], complete: false }; + return { values: a.values.flatMap((left) => b.values.map((right) => ({ + value: left.value + right.value, origin: location(node), evidence: [...left.evidence, ...right.evidence], + }))), complete: true }; + } + if (ts.isIdentifier(node)) { + const definitions = declarations(node, true); + if (definitions.length !== 1) return { values: [], complete: false }; + const declaration = definitions[0]; + if (isConst(declaration) && declaration.initializer) { + return strings(declaration.initializer, next, depth + 1); + } + if (ts.isParameter(declaration)) { + const symbol = checker.getSymbolAtLocation(node); + if (writtenSymbols.has(symbol) || opaqueFunctions.has(declaration.parent)) return { values: [], complete: false }; + const fn = declaration.parent; + const index = fn.parameters?.indexOf(declaration); + if (index === undefined || index < 0) return { values: [], complete: false }; + const invocations = callsByFunction.get(fn) ?? []; + const values = invocations.flatMap((call) => strings(call.arguments[index], next, depth + 1).values.map((value) => ({ + ...value, bindingSite: value.bindingSite ?? location(call), evidence: [...value.evidence, location(call)], + }))); + // Known call sites are evidence; this is not a closed-world caller inventory. + return { values, complete: false }; + } + if (ts.isBindingElement(declaration) && ts.isArrayBindingPattern(declaration.parent)) { + const binding = declaration.parent; + const variable = binding.parent; + const statement = variable.parent?.parent; + if (isConst(variable) && ts.isForOfStatement(statement) && ts.isArrayLiteralExpression(statement.expression)) { + const index = binding.elements.indexOf(declaration); + const parts = statement.expression.elements.map((element) => + ts.isArrayLiteralExpression(element) ? strings(element.elements[index], next, depth + 1) : { values: [], complete: false }); + return { values: parts.flatMap(({ values }) => values), complete: parts.every(({ complete }) => complete) }; + } + } + } + return { values: [], complete: false }; + } + const entities = contributions.flatMap(({ entities }) => entities); + function position(lineA, columnA, lineB, columnB) { + return lineA - lineB || columnA - columnB; + } + function owner(source) { + const candidates = entities.filter((entity) => entity.location.path === source.path && + position(entity.location.startLine, entity.location.startColumn, source.startLine, source.startColumn) <= 0 && + position(entity.location.endLine, entity.location.endColumn, source.endLine, source.endColumn) >= 0); + candidates.sort((a, b) => position(b.location.startLine, b.location.startColumn, a.location.startLine, a.location.startColumn) || + position(a.location.endLine, a.location.endColumn, b.location.endLine, b.location.endColumn) || compare(a.id, b.id)); + if (candidates.length > 1 && serialize(candidates[0].location) === serialize(candidates[1].location)) { + return factId("core", "file", source.path, source.path); + } + return candidates[0]?.id ?? factId("core", "file", source.path, source.path); + } + const commands = rust.extensions.tauriCommands ?? []; + const registrations = rust.extensions.tauriRegistrations ?? []; + const rustEntities = new Map(rust.entities.map((entity) => [entity.id, entity])); + const lexicalScopes = new Map((rust.extensions.lexicalScopes ?? []).map((scope) => [scope.lexicalScope, scope])); + const lexicalBindings = rust.extensions.lexicalBindings ?? []; + function normalizedRustPath(path) { + return path.replace(/\s+/g, ""); + } + function registrationPath(path, modulePath) { + path = normalizedRustPath(path); + if (path.startsWith("crate::")) return path; + if (!modulePath || !/^crate(?:::|$)/.test(modulePath) || path.startsWith("::")) return undefined; + const scope = normalizedRustPath(modulePath).split("::"); + if (path.startsWith("self::")) path = path.slice("self::".length); + while (path.startsWith("super::")) { + if (scope.length <= 1) return undefined; + scope.pop(); + path = path.slice("super::".length); + } + return `${scope.join("::")}::${path}`; + } + function unqualifiedPathSupported(registration, path, command) { + path = normalizedRustPath(path); + if (/^(?:crate|self|super)::/.test(path)) return true; + if (!registration.lexicalScope || !registration.moduleLexicalScope) return false; + const ancestors = new Set(); + let scope = registration.lexicalScope; + while (scope !== null && scope !== undefined) { + if (ancestors.has(scope)) return false; + ancestors.add(scope); + if (scope === registration.moduleLexicalScope) break; + const descriptor = lexicalScopes.get(scope); + if (!descriptor || descriptor.status !== "established") return false; + scope = descriptor.parentScope; + } + if (!ancestors.has(registration.moduleLexicalScope)) return false; + const first = path.split("::")[0].replace(/^r#/, ""); + for (const binding of lexicalBindings) { + if (!ancestors.has(binding.lexicalScope) || !binding.wildcard && binding.name !== first) continue; + if (binding.availability === "after-statement" && binding.visibleAfter && + position(binding.visibleAfter.endLine, binding.visibleAfter.endColumn, + registration.location.startLine, registration.location.startColumn) > 0) continue; + if (binding.entityId === command.entityId) continue; + const entity = rustEntities.get(binding.entityId); + if (binding.lexicalScope === registration.moduleLexicalScope && + entity?.kind === "module" && path.includes("::")) continue; + return false; + } + return true; + } + function matchingRegistrations(command) { + if (!command.rustPath || !command.crateId) return []; + return registrations.filter((registration) => registration.registrationKind === "app-builder" && + registration.crateId === command.crateId && + registration.rustPaths.some((path) => registrationPath(path, registration.modulePath) === normalizedRustPath(command.rustPath) && + unqualifiedPathSupported(registration, path, command))); + } + const bindings = []; + const unresolved = new Map(); + const edges = new Map(); + function recordUnresolved(call, text, reason, source = location(call)) { + const id = factId("tauri", "unresolved-invoke", source.path, + `${source.startLine}:${source.startColumn}:${text}:${reason}`); + unresolved.set(id, { id, kind: "tauri-invocation", text, reason, location: source, ownerId: owner(source) }); + } + for (const registration of registrations) { + if (registration.registrationKind !== "app-builder") continue; + for (const path of registration.rustPaths) { + const resolved = registrationPath(path, registration.modulePath); + const targets = commands.filter((command) => resolved && command.crateId && + command.crateId === registration.crateId && normalizedRustPath(command.rustPath ?? "") === resolved && + unqualifiedPathSupported(registration, path, command)); + if (targets.length !== 1) { + const id = factId("tauri", "unresolved-handler", registration.location.path, + `${registration.location.startLine}:${registration.location.startColumn}:${path}`); + unresolved.set(id, { + id, kind: "tauri-handler-entry", text: path, + reason: "The declared handler entry has no unique source command without lexical shadowing/import/opaque-binding ambiguity in the supported scope.", + location: registration.location, ownerId: owner(registration.location), + }); + continue; + } + const command = targets[0]; + const id = factId("tauri", "handler-entry", registration.location.path, + `${registration.location.startLine}:${registration.location.startColumn}:${command.entityId}`); + edges.set(id, { + id, from: owner(registration.location), to: command.entityId, + kind: "tauri-handler-entry", method: "declared-generate_handler-entry", + evidence: [registration.location, command.location], + }); + } + } + for (const call of calls.filter((candidate) => isInvoke(candidate.expression))) { + const invokeSite = location(call); + const names = strings(call.arguments[0]); + if (!names.complete) recordUnresolved(call, call.arguments[0]?.getText() ?? "(missing)", + "Command expression is dynamic or the helper caller inventory is not closed; only separately enumerated known bindings are shown."); + for (const name of names.values) { + const bindingSite = name.bindingSite ?? invokeSite; + const candidates = commands.map((command) => ({ command, registrations: matchingRegistrations(command) })) + .filter(({ command, registrations }) => command.commandName === name.value && registrations.length); + if (candidates.length !== 1) { + recordUnresolved(call, name.value, candidates.length + ? "Multiple source-declared command targets/registrations are possible." + : "No uniquely supported in-repository command registration was resolved; plugin or dynamic registrations may exist.", bindingSite); + continue; + } + const { command, registrations: registered } = candidates[0]; + const from = owner(bindingSite); + const evidence = [...new Map([ + invokeSite, ...name.evidence, command.location, ...registered.map(({ location }) => location), + ].map((item) => [serialize(item), item])).values()] + .sort((a, b) => compare(a.path, b.path) || a.startLine - b.startLine || a.startColumn - b.startColumn); + const id = factId("tauri", "invokes", bindingSite.path, + `${bindingSite.startLine}:${bindingSite.startColumn}:${invokeSite.path}:${invokeSite.startLine}:${invokeSite.startColumn}:${name.value}:${command.entityId}`); + const relationship = { id, from, to: command.entityId, kind: "tauri-command-binding", + method: "source-import-and-bounded-string-flow-plus-declared-handler-registration", evidence }; + edges.set(id, relationship); + bindings.push({ relationshipId: id, commandName: name.value, invokeSite, callSite: bindingSite, + conditions: [...new Set([...(command.conditions ?? []), ...registered.flatMap((r) => r.conditions ?? [])])], + runtimeReachability: "not-established" }); + } + } + result.relationships = [...edges.values()].sort((a, b) => compare(a.id, b.id)); + result.unresolved = [...unresolved.values()].sort((a, b) => compare(a.id, b.id)); + result.coverage.analyzedFiles = [...new Set([ + ...parsed, ...commands.map(({ location }) => location.path), ...registrations.map(({ location }) => location.path), + ])].sort(compare); + result.coverage.status = "partial"; + result.coverage.limitations = [ + "Bindings describe source structure, not runtime execution, authorization, permissions or reachability.", + "Only explicit app generate_handler registrations with established Rust paths are joined.", + "Plugin/custom/generated registrations and non-enumerable dynamic command names remain unresolved.", + "Helper propagation enumerates known local call sites, not all potential callers.", + "Rust cfg conditions, procedural macros and build-time pruning are not evaluated.", + ]; + result.extensions = { + declaredCommands: commands.length, + registrationSites: registrations.length, + invocationSites: calls.filter((call) => isInvoke(call.expression)).length, + bindings: [...new Map(bindings.map((binding) => [serialize(binding), binding])).values()] + .sort((a, b) => compare(a.relationshipId, b.relationshipId)), + }; + return result; +} diff --git a/experiments/plugin-spike/src/plugins/typescript.mjs b/experiments/plugin-spike/src/plugins/typescript.mjs new file mode 100644 index 0000000..d469359 --- /dev/null +++ b/experiments/plugin-spike/src/plugins/typescript.mjs @@ -0,0 +1,127 @@ +import { emptyContribution, factId, sourceLocation, compare } from "../contract.mjs"; +import { compiler, topocodeModule } from "../topocode.mjs"; + +export const manifest = { + id: "typescript", + kind: "language", + requires: [], + languages: ["typescript", "javascript"], + detect: (files) => files.some(({ path }) => /\.(?:[cm]?[jt]s|[jt]sx)$/.test(path)), +}; + +function location(value) { + return sourceLocation( + value.path, value.start.line, value.end?.line ?? value.start.line, + value.start.column, value.end?.column ?? value.start.column, + ); +} + +export async function scanTypeScript(context) { + const result = emptyContribution("typescript", "language", manifest.languages, + ["file-imports", "declarations", "static-calls", "type-use"]); + const ts = await compiler(); + const { scanRepository } = await topocodeModule("@topo/scanner"); + let scanned; + try { + scanned = await scanRepository({ + root: context.root, + repositoryId: context.repository?.id ?? "spike-repository", + revision: context.repository?.revision, + quality: { allowPartial: true }, + }); + } catch (error) { + if (!Array.isArray(error.diagnostics)) throw error; + result.coverage.status = "unsupported"; + result.coverage.limitations.push("The shipped TypeScript adapter rejected this source configuration."); + result.diagnostics = error.diagnostics.map(({ code, severity, message, path }) => ({ + code, severity, message, ...(path ? { path } : {}), + })); + return result; + } + const paths = new Set(context.files.map(({ path }) => path)); + const entities = new Map(); + for (const entity of scanned.logicalArchitecture.entities) { + const first = [...entity.declarations].sort((a, b) => compare(a.path, b.path) || + a.start.line - b.start.line || a.start.column - b.start.column)[0]; + if (!first || !paths.has(first.path)) throw new Error(`TypeScript declaration lacks captured source: ${entity.name}`); + const id = `typescript:${entity.id}`; + entities.set(entity.id, id); + result.entities.push({ + id, language: /\.[cm]?jsx?$/.test(first.path) ? "javascript" : "typescript", + kind: entity.kind, name: entity.name, qualifiedName: `${first.path}::${entity.name}`, + location: location(first), exported: entity.exported, + signatures: entity.signatures.map((value) => value.replaceAll(context.root, "")), attributes: [], + }); + } + for (const relationship of scanned.logicalArchitecture.relationships) { + result.relationships.push({ + id: `typescript:${relationship.id}`, + from: entities.get(relationship.sourceId), + to: entities.get(relationship.targetId), + kind: relationship.kind, + method: "typescript-compiler-resolved-static-reference", + evidence: relationship.locations.map(location), + }); + } + const evidence = new Map(scanned.graph.evidence.map((item) => [item.id, item])); + const nodes = new Map(scanned.graph.nodes.map((node) => [node.id, node])); + const importLocations = new Map(); + function locationsFor(item) { + if (item?.location) return [location(item.location)]; + if (!item?.anchor?.symbol?.startsWith("import:")) return []; + const source = context.files.find(({ path }) => path === item.anchor.path); + if (!source) return []; + const key = `${source.path}:${item.anchor.symbol}`; + if (importLocations.has(key)) return importLocations.get(key); + const specifier = item.anchor.symbol.slice("import:".length); + const parsed = ts.createSourceFile(source.path, source.contents, ts.ScriptTarget.Latest, true); + const locations = []; + const visit = (node) => { + const literal = ts.isImportDeclaration(node) || ts.isExportDeclaration(node) + ? node.moduleSpecifier + : ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || + ts.isIdentifier(node.expression) && node.expression.text === "require") + ? node.arguments[0] : undefined; + if (literal && ts.isStringLiteralLike(literal) && literal.text === specifier) { + const start = parsed.getLineAndCharacterOfPosition(node.getStart(parsed)); + const end = parsed.getLineAndCharacterOfPosition(node.getEnd()); + locations.push(sourceLocation(source.path, start.line + 1, end.line + 1, start.character + 1, end.character + 1)); + } + ts.forEachChild(node, visit); + }; + visit(parsed); + importLocations.set(key, locations); + return locations; + } + for (const edge of scanned.graph.edges) { + const from = nodes.get(edge.sourceId); + const to = nodes.get(edge.targetId); + if (from?.identity.kind !== "path" || to?.identity.kind !== "path") continue; + const locations = edge.provenance.evidenceIds.flatMap((id) => locationsFor(evidence.get(id))); + if (!locations.length) { + result.diagnostics.push({ code: "import-evidence-location-missing", severity: "warning", + message: `Import was not promoted without a source location: ${edge.id}`, path: from.identity.value }); + continue; + } + result.relationships.push({ + id: `typescript:${edge.id}`, + from: factId("core", "file", from.identity.value, from.identity.value), + to: factId("core", "file", to.identity.value, to.identity.value), + kind: "imports", method: "typescript-module-resolution", evidence: locations, + }); + } + result.coverage.analyzedFiles = scanned.graph.nodes + .filter((node) => node.identity.kind === "path").map((node) => node.identity.value).sort(compare); + result.coverage.status = scanned.authoritative && !result.diagnostics.length ? "complete" : "partial"; + result.coverage.limitations = [ + "Static compiler references are not runtime execution or exhaustive impact.", + "This prototype uses the existing published TypeScript adapter's supported syntax and assets.", + ]; + result.diagnostics = [...result.diagnostics, ...scanned.diagnostics.map(({ code, severity, message, path }) => ({ + code, severity, message, ...(path ? { path } : {}), + }))]; + result.extensions.metrics = scanned.metrics; + result.extensions.adapter = "@jdylanmc/topo-code@0.1.0 bundled @topo/scanner"; + result.extensions.compilerVersion = ts.version; + return result; +} diff --git a/experiments/plugin-spike/src/publication.mjs b/experiments/plugin-spike/src/publication.mjs new file mode 100644 index 0000000..fb25212 --- /dev/null +++ b/experiments/plugin-spike/src/publication.mjs @@ -0,0 +1,100 @@ +import { createHash, randomUUID } from "node:crypto"; +import { lstat, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises"; +import { dirname, resolve } from "node:path"; + +async function preflight(path) { + let current = dirname(path); + const ancestors = []; + while (current !== dirname(current)) { + ancestors.push(current); + current = dirname(current); + } + for (const ancestor of ancestors.reverse()) { + try { + const information = await lstat(ancestor); + if (!information.isDirectory() || information.isSymbolicLink()) throw new Error(`Unsafe output ancestor: ${ancestor}`); + } catch (error) { + if (error.code !== "ENOENT") throw error; + } + } + try { + const information = await lstat(path); + if (!information.isFile() || information.isSymbolicLink()) throw new Error(`Unsafe artifact destination: ${path}`); + return await readFile(path); + } catch (error) { + if (error.code !== "ENOENT") throw error; + return undefined; + } +} + +export async function writeArtifactSet(artifacts, options = {}) { + if (!artifacts.length) throw new Error("Artifact publication set is empty"); + const files = artifacts.map(({ path, contents }) => ({ + path: resolve(path), contents: Buffer.isBuffer(contents) ? contents : Buffer.from(contents, "utf8"), + })); + if (new Set(files.map(({ path }) => path)).size !== files.length) throw new Error("Duplicate artifact destination"); + const id = randomUUID(); + const renameFile = options.renameFile ?? rename; + const lockHash = createHash("sha256").update(files.map(({ path }) => path).sort().join("\0")).digest("hex").slice(0, 24); + const lock = resolve(dirname(files[0].path), `.topo-publication-${lockHash}.lock`); + for (const file of files) await preflight(file.path); + for (const file of files) await mkdir(dirname(file.path), { recursive: true }); + await writeFile(lock, JSON.stringify({ pid: process.pid }), { flag: "wx" }).catch((error) => { + if (error.code === "EEXIST") throw new Error(`Artifact publication is already locked: ${lock}`); + throw error; + }); + const temporary = []; + const prepared = []; + const committed = []; + let failure; + try { + for (const file of files) { + const previous = await preflight(file.path); + const staged = `${file.path}.${id}.stage`; + const backup = previous === undefined ? undefined : `${file.path}.${id}.rollback`; + temporary.push(staged); + await writeFile(staged, file.contents, { flag: "wx" }); + if (backup) { + temporary.push(backup); + await writeFile(backup, previous, { flag: "wx" }); + } + prepared.push({ ...file, previous, staged, backup }); + } + for (const file of prepared) { + const current = await preflight(file.path); + if (current === undefined ? file.previous !== undefined : file.previous === undefined || !current.equals(file.previous)) { + throw new Error(`Artifact changed during staging: ${file.path}`); + } + } + for (const file of prepared) { + await renameFile(file.staged, file.path); + committed.push(file); + } + } catch (error) { + const errors = [error]; + for (const file of committed.reverse()) { + try { + if (file.backup) await rename(file.backup, file.path); + else await unlink(file.path); + } catch (rollbackError) { + errors.push(new Error(`Could not restore previous artifact ${file.path}: ${rollbackError.message}`, { cause: rollbackError })); + } + } + failure = errors.length === 1 ? error : new AggregateError(errors, "Artifact publication failed and rollback was incomplete"); + } finally { + const cleanupErrors = []; + for (const path of [...temporary, lock]) { + try { await unlink(path); } + catch (error) { if (error.code !== "ENOENT") cleanupErrors.push(error); } + } + if (cleanupErrors.length) { + failure = new AggregateError([...(failure ? [failure] : []), ...cleanupErrors], "Artifact publication cleanup failed"); + } + } + if (failure) throw failure; + return files.map(({ path }) => path); +} + +export async function writeArtifact(path, contents) { + return (await writeArtifactSet([{ path, contents }]))[0]; +} diff --git a/experiments/plugin-spike/src/topocode.mjs b/experiments/plugin-spike/src/topocode.mjs new file mode 100644 index 0000000..72fcea7 --- /dev/null +++ b/experiments/plugin-spike/src/topocode.mjs @@ -0,0 +1,21 @@ +import { createRequire } from "node:module"; +import { pathToFileURL } from "node:url"; +import { dirname, join } from "node:path"; + +const require = createRequire(import.meta.url); +const packagePath = require.resolve("@jdylanmc/topo-code/package.json"); +const fromPackage = createRequire(packagePath); + +// Experimental integration only: these bundled modules are not a public SDK. +export async function topocodeModule(name) { + return import(pathToFileURL(fromPackage.resolve(name)).href); +} + +export async function compiler() { + const imported = await topocodeModule("typescript-compiler-api"); + return imported.default; +} + +export function topocodeBin() { + return join(dirname(packagePath), "bin/topo.js"); +} diff --git a/experiments/plugin-spike/src/view-page.mjs b/experiments/plugin-spike/src/view-page.mjs new file mode 100644 index 0000000..c04bee7 --- /dev/null +++ b/experiments/plugin-spike/src/view-page.mjs @@ -0,0 +1,149 @@ +function escape(value) { + return String(value).replaceAll("&", "&").replaceAll("<", "<") + .replaceAll(">", ">").replaceAll('"', """).replaceAll("'", "'"); +} + +export function viewPage(view, baseline, evidence, nativeFile, navigation = []) { + const sourceDetails = (sources) => sources.map((source) => `
+ ${escape(source.path)}:${source.startLine}-${source.endLine} +
${escape(source.excerpt)}
+
`).join("\n"); + const sections = evidence.sections.map((section) => `
+

${escape(section.title)}

+

${escape(section.body)}

+ ${sourceDetails(section.sources)} +
`).join("\n"); + const connections = evidence.connections.map((connection) => `
  • + ${escape(connection.fromTitle)} to ${escape(connection.toTitle)} +

    ${escape(connection.label)}

    + ${connection.classification === "inferred" ? "Agent interpretation" : connection.classification === "source-traced" ? "Agent source trace - exact code checked" : "Analyzer-derived connection"} + ${connection.rationale ? `

    ${escape(connection.rationale)}

    ` : ""} + ${sourceDetails(connection.evidence ?? [])} + ${connection.relationships.map((relation) => `
    + ${escape(relation.kind)}: ${escape(relation.method)} +
      ${relation.evidence.map((location) => `
    • ${escape(location.path)}:${location.startLine}-${location.endLine}
    • `).join("")}
    +
    `).join("\n")} +
  • `).join("\n"); + const limitations = Object.entries(baseline.coverage.byPlugin).map(([id, coverage]) => + `
  • ${escape(id)} (${escape(coverage.status)})
      ${coverage.limitations.map((item) => `
    • ${escape(item)}
    • `).join("")}
  • `).join(""); + return ` + + + + + + ${escape(view.title)} | Topocode source view + + + +
    +

    ${escape(view.title)}

    Topocode prototype (${escape(baseline.coverage.status)} coverage) | Source ${escape(baseline.repository.revision.slice(0, 12))}${baseline.repository.dirty ? " + working-tree changes" : ""}

    + Open diagram only + +
    + ${navigation.length ? `` : ""} +
    + + +
    + + + +`; +} diff --git a/experiments/plugin-spike/src/view.mjs b/experiments/plugin-spike/src/view.mjs new file mode 100644 index 0000000..a9f20b4 --- /dev/null +++ b/experiments/plugin-spike/src/view.mjs @@ -0,0 +1,231 @@ +import { readFile } from "node:fs/promises"; +import { basename, join } from "node:path"; +import { assertBaselineCurrent } from "./inventory.mjs"; +import { baselineDigest, validateFacts, writeArtifactSet } from "./baseline.mjs"; +import { CONTRACT_VERSION, hash, serialize } from "./contract.mjs"; +import { viewPage } from "./view-page.mjs"; +import { renderNative } from "./native-renderer.mjs"; +import { renderFlow } from "./flow-renderer.mjs"; + +function nonblank(value, label) { + if (typeof value !== "string" || !value.trim()) throw new Error(`${label} must be nonblank text`); +} + +function identifiers(values, label) { + if (!Array.isArray(values) || values.some((value) => typeof value !== "string") || + new Set(values).size !== values.length) throw new Error(`${label} must be a unique ID array`); +} + +function fields(value, keys, label) { + if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`); + for (const key of Object.keys(value)) if (!keys.includes(key)) throw new Error(`${label} has unsupported field: ${key}`); +} + +function checkEvidence(baseline, evidence) { + if (!Array.isArray(evidence) || !evidence.length) throw new Error("Source evidence must be a nonempty array"); + const sources = new Map(baseline.source.files.map((file) => [file.path, file])); + for (const item of evidence) { + fields(item, ["path", "startLine", "endLine", "sha256", "excerpt"], "Source evidence"); + if (!sources.has(item.path) || sources.get(item.path).sha256 !== item.sha256) { + throw new Error(`Source evidence is not bound to the captured file: ${item.path}`); + } + if (!Number.isSafeInteger(item.startLine) || !Number.isSafeInteger(item.endLine) || + item.startLine < 1 || item.endLine < item.startLine) throw new Error("Invalid authored source range"); + nonblank(item.excerpt, "Source excerpt"); + } +} + +export function validateViewEvidence(baseline, view, files) { + validateView(baseline, view); + const sources = new Map(files.map((file) => [file.path, file])); + for (const item of [...view.sections, ...view.connections].flatMap((part) => part.evidence ?? [])) { + const source = sources.get(item.path); + if (!source || hash(source.contents) !== item.sha256) throw new Error(`Source evidence changed: ${item.path}`); + const lines = source.contents.split("\n"); + if (item.endLine > lines.length || + lines.slice(item.startLine - 1, item.endLine).join("\n") !== item.excerpt) { + throw new Error(`Source excerpt does not match ${item.path}:${item.startLine}-${item.endLine}`); + } + } +} + +export function validateView(baseline, view) { + fields(view, ["schemaVersion", "baselineId", "id", "title", "summary", "sections", "connections"], "View"); + if (baseline.id !== baselineDigest(baseline)) throw new Error("Baseline digest does not match its contents"); + if (view.schemaVersion !== CONTRACT_VERSION) throw new Error("Unsupported experimental view schemaVersion"); + if (view.baselineId !== baseline.id) throw new Error("View is bound to a different baseline; reconcile it explicitly"); + if (!/^[a-z][a-z0-9-]*$/.test(view.id)) throw new Error("View id must be a stable lowercase slug"); + nonblank(view.title, "View title"); + nonblank(view.summary, "View summary"); + if (!Array.isArray(view.sections) || view.sections.length < 1 || view.sections.length > 8) { + throw new Error("A focused experimental view must contain 1 to 8 sections"); + } + if (!Array.isArray(view.connections)) throw new Error("View connections must be an array"); + const entities = new Map(baseline.entities.map((entity) => [entity.id, entity])); + const relations = new Map(baseline.relationships.map((relation) => [relation.id, relation])); + const sections = new Map(); + for (const section of view.sections) { + fields(section, ["id", "title", "body", "entityIds", "kind", "evidence"], "Section"); + if (!/^[a-z][a-z0-9-]*$/.test(section.id) || sections.has(section.id)) throw new Error("Invalid or duplicate section id"); + nonblank(section.title, "Section title"); + nonblank(section.body, "Section body"); + identifiers(section.entityIds, "Section entityIds"); + if (!section.entityIds.length) throw new Error("Every section must reference baseline entities"); + if (section.kind !== undefined && !["step", "decision", "data"].includes(section.kind)) throw new Error("Unsupported section kind"); + if (section.evidence !== undefined) checkEvidence(baseline, section.evidence); + const members = new Set(section.entityIds); + for (const id of members) if (!entities.has(id)) throw new Error(`View references unknown entity: ${id}`); + let previous; + do { + previous = members.size; + for (const entity of entities.values()) if (entity.ownerId && members.has(entity.ownerId)) members.add(entity.id); + for (const relation of relations.values()) { + if (["declares", "contains"].includes(relation.kind) && members.has(relation.from)) members.add(relation.to); + } + } while (previous !== members.size); + sections.set(section.id, { section, members }); + } + for (const connection of view.connections) { + fields(connection, ["from", "to", "label", "classification", "relationshipIds", "rationale", "evidence"], "Connection"); + const from = sections.get(connection.from); + const to = sections.get(connection.to); + if (!from || !to || from === to) throw new Error("Connection must join two different existing sections"); + nonblank(connection.label, "Connection label"); + identifiers(connection.relationshipIds, "Connection relationshipIds"); + if (connection.rationale !== undefined) nonblank(connection.rationale, "Connection rationale"); + if (connection.evidence !== undefined) checkEvidence(baseline, connection.evidence); + if (connection.classification === "source-traced") { + if (connection.relationshipIds.length) throw new Error("A source trace must not borrow analyzer relationship IDs"); + nonblank(connection.rationale, "Source-traced rationale"); + checkEvidence(baseline, connection.evidence); + continue; + } + if (connection.classification === "inferred") { + if (connection.relationshipIds.length) throw new Error("An inferred connection must not borrow factual relationship IDs"); + nonblank(connection.rationale, "Inferred connection rationale"); + continue; + } + if (connection.classification !== "source-derived" || !connection.relationshipIds.length) { + throw new Error("A source-derived connection needs baseline relationships; otherwise mark it inferred with rationale"); + } + for (const id of connection.relationshipIds) { + const relation = relations.get(id); + if (!relation) throw new Error(`View references unknown relationship: ${id}`); + if (!from.members.has(relation.from) || !to.members.has(relation.to)) { + throw new Error(`Relationship ${id} does not support the displayed connection direction/membership`); + } + } + } + return { entities, relations, sections }; +} + +async function prepareView(root, baseline, view, output, options = {}) { + const validated = validateView(baseline, view); + const current = await assertBaselineCurrent(root, baseline); + validateFacts(baseline, current.files); + validateViewEvidence(baseline, view, current.files); + const files = new Map(current.files.map((file) => [file.path, file])); + const anchors = new Map(); + const sectionAnchors = new Map(); + for (const section of view.sections) { + const ids = []; + const represented = new Set(section.entityIds); + const members = validated.sections.get(section.id).members; + for (const connection of view.connections) { + for (const relationshipId of connection.relationshipIds) { + const relationship = validated.relations.get(relationshipId); + if (connection.from === section.id && members.has(relationship.from)) represented.add(relationship.from); + if (connection.to === section.id && members.has(relationship.to)) represented.add(relationship.to); + } + } + for (const entityId of represented) { + const entity = validated.entities.get(entityId); + const location = entity.location; + const id = `source-${hash(`${location.path}:${location.startLine}:${location.endLine}`).slice(0, 20)}`; + const contents = files.get(location.path).contents; + anchors.set(id, { + id, path: location.path, + location: { startLine: location.startLine, endLine: location.endLine }, + excerpt: contents.split(/\r?\n/).slice(location.startLine - 1, location.endLine).join("\n"), + }); + ids.push(id); + } + sectionAnchors.set(section.id, [...new Set(ids)]); + } + if (options.renderer && !["archify", "graphviz"].includes(options.renderer)) throw new Error("Unsupported view renderer"); + const renderArtifact = options.renderArtifact ?? (options.renderer === "graphviz" ? renderFlow : renderNative); + const artifact = await renderArtifact(view); + const evidence = { + baselineId: baseline.id, + sections: view.sections.map((section) => ({ + id: section.id, title: section.title, body: section.body, kind: section.kind ?? "step", + sources: section.evidence ?? sectionAnchors.get(section.id).map((id) => { + const anchor = anchors.get(id); + return { path: anchor.path, ...anchor.location, excerpt: anchor.excerpt }; + }), + })), + connections: view.connections.map((connection) => ({ + ...connection, + fromTitle: validated.sections.get(connection.from).section.title, + toTitle: validated.sections.get(connection.to).section.title, + relationships: connection.relationshipIds.map((id) => validated.relations.get(id)), + })), + }; + const page = viewPage(view, baseline, evidence, `${basename(output)}.native.html`, options.navigation); + await assertBaselineCurrent(root, baseline); + const receipt = { + schemaVersion: CONTRACT_VERSION, + viewId: view.id, baselineId: baseline.id, + viewSha256: hash(serialize(view)), htmlSha256: hash(page), nativeHtmlSha256: hash(artifact.contents), + renderer: artifact.renderer, + nativeValidation: artifact.validation, + specificationSha256: artifact.specificationSha256, + layout: { strategy: options.renderer === "graphviz" ? "graphviz-directed-flow" : "native-grid-auto-routing", + ...(artifact.specification.layout ? { columns: artifact.specification.layout.cols } : {}), + sectionOrder: view.sections.map(({ id }) => id), presentation: "contained-source-view" }, + sourceDerivedConnections: view.connections.filter((connection) => connection.classification === "source-derived").length, + sourceTracedConnections: view.connections.filter((connection) => connection.classification === "source-traced").length, + inferredConnections: view.connections.filter((connection) => connection.classification === "inferred").length, + humanReview: "pending", + limitation: "Checks establish source references and baseline topology, not semantic truth of authored text or runtime behavior.", + }; + const artifacts = [ + { path: `${output}.native.html`, contents: artifact.contents }, + { path: `${output}.spec.json`, contents: serialize(artifact.specification) }, + { path: `${output}.evidence.json`, contents: serialize(evidence) }, + { path: output, contents: page }, + { path: `${output}.receipt.json`, contents: serialize(receipt) }, + ]; + return { receipt, artifacts, page }; +} + +export async function renderView(root, baseline, view, output, options = {}) { + const prepared = await prepareView(root, baseline, view, output, options); + await writeArtifactSet(prepared.artifacts); + return prepared.receipt; +} + +export async function renderBook(root, baseline, views, output, options = {}) { + if (!views.length || new Set(views.map(({ id }) => id)).size !== views.length) throw new Error("A diagram book requires unique view IDs"); + if (views.some(({ id }) => id === "index")) throw new Error("The view ID index is reserved for the book entry page"); + const source = await assertBaselineCurrent(root, baseline); + for (const view of views) validateViewEvidence(baseline, view, source.files); + const navigation = views.map(({ id, title }) => ({ id, title })); + const prepared = []; + for (const view of views) { + prepared.push(await prepareView(root, baseline, view, join(output, `${view.id}.html`), + { navigation, renderer: options.renderer, renderArtifact: options.renderArtifact })); + } + await assertBaselineCurrent(root, baseline); + const receipts = prepared.map(({ receipt }) => receipt); + await writeArtifactSet([ + ...prepared.flatMap(({ artifacts }) => artifacts), + { path: join(output, "index.html"), contents: prepared[0].page }, + { path: join(output, "book.json"), contents: serialize({ baselineId: baseline.id, navigation, receipts }) }, + ], options.publication); + return { views: views.length, baselineId: baseline.id, receipts }; +} + +export async function readView(path) { + return JSON.parse(await readFile(path, "utf8")); +} diff --git a/experiments/plugin-spike/test/baseline.test.mjs b/experiments/plugin-spike/test/baseline.test.mjs new file mode 100644 index 0000000..0df7d78 --- /dev/null +++ b/experiments/plugin-spike/test/baseline.test.mjs @@ -0,0 +1,42 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { pluginOrder, baselineDigest, validateFacts } from "../src/baseline.mjs"; +import { sourceLocation } from "../src/contract.mjs"; + +test("plugin dependency ordering is independent of requested order", () => { + const plugins = [ + { id: "ts", requires: [] }, { id: "rust", requires: [] }, + { id: "tauri", requires: ["ts", "rust"] }, + ]; + assert.deepEqual(pluginOrder(plugins, ["tauri", "ts", "rust"]).map(({ id }) => id), ["rust", "ts", "tauri"]); + assert.throws(() => pluginOrder(plugins, ["tauri", "rust"]), /requires explicitly selected ts/); + assert.throws(() => pluginOrder(plugins, ["unknown"]), /Unknown plugin/); + assert.throws(() => pluginOrder(plugins, ["rust", "rust"]), /Duplicate selected/); + assert.throws(() => pluginOrder([{ id: "a", requires: ["b"] }, { id: "b", requires: ["a"] }], ["a", "b"]), /cycle/); +}); + +test("baseline identity ignores only its own digest field", () => { + assert.equal(baselineDigest({ id: "anything", value: 1 }), baselineDigest({ value: 1 })); + assert.notEqual(baselineDigest({ value: 1 }), baselineDigest({ value: 2 })); +}); + +test("fact validation rejects invented endpoints and absent source evidence", () => { + const location = sourceLocation("src/lib.rs", 1); + const entity = { id: "rust:a", name: "a", kind: "function", language: "rust", exported: true, location }; + const files = [{ path: "src/lib.rs", contents: "fn a() {}\n" }]; + const baseline = { entities: [entity], relationships: [], unresolved: [] }; + validateFacts(baseline, files); + assert.throws(() => validateFacts({ + ...baseline, + relationships: [{ id: "r", from: "rust:a", to: "made-up", kind: "calls", method: "guess", evidence: [location] }], + }, files), /unknown endpoint/); + assert.throws(() => validateFacts({ + ...baseline, entities: [{ ...entity, location: sourceLocation("other.rs", 1) }], + }, files), /uncaptured source/); + assert.throws(() => validateFacts({ + ...baseline, entities: [{ ...entity, location: sourceLocation("src/lib.rs", 5) }], + }, files), /range exceeds/); + assert.throws(() => validateFacts({ + ...baseline, entities: [{ ...entity, location: sourceLocation("src/lib.rs", 1, 1, 90, 91) }], + }, files), /column exceeds/); +}); diff --git a/experiments/plugin-spike/test/book-publication.test.mjs b/experiments/plugin-spike/test/book-publication.test.mjs new file mode 100644 index 0000000..19f5fe1 --- /dev/null +++ b/experiments/plugin-spike/test/book-publication.test.mjs @@ -0,0 +1,91 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFile, readdir, rename } from "node:fs/promises"; +import { basename, join } from "node:path"; +import { scanBaseline } from "../src/baseline.mjs"; +import { CONTRACT_VERSION } from "../src/contract.mjs"; +import { renderBook } from "../src/view.mjs"; +import { renderFlow } from "../src/flow-renderer.mjs"; +import { repository } from "./helpers.mjs"; + +async function existingBook(context) { + const root = await repository(context, { + "Cargo.toml": '[package]\nname="book_fixture"\nversion="0.1.0"\nedition="2021"\n', + "src/lib.rs": "pub struct Snapshot;\n", + }); + const baseline = await scanBaseline(root); + const entity = baseline.entities.find((item) => item.name === "Snapshot"); + const views = ["first", "second"].map((id) => ({ + schemaVersion: CONTRACT_VERSION, baselineId: baseline.id, id, title: `${id} chapter`, + summary: "Original source-backed chapter.", + sections: [{ id: "snapshot", title: "Snapshot", body: "The captured Rust declaration.", entityIds: [entity.id] }], + connections: [], + })); + const output = join(root, ".topo/cache/book"); + await renderBook(root, baseline, views, output, { renderer: "graphviz" }); + const before = await artifacts(output); + assert.equal(before.length, 12, "Two complete five-file chapter sets, index and book metadata"); + return { root, baseline, views, output, before, entity }; +} + +async function artifacts(directory) { + return Promise.all((await readdir(directory)).sort().map(async (name) => ({ + name, bytes: await readFile(join(directory, name)), + }))); +} + +async function assertUnchanged(fixture) { + const current = await artifacts(fixture.output); + assert.deepEqual(current.map(({ name }) => name), fixture.before.map(({ name }) => name)); + for (const [index, file] of current.entries()) { + assert.ok(file.bytes.equals(fixture.before[index].bytes), `Previous bytes must survive: ${file.name}`); + } +} + +test("a second-chapter renderer failure leaves every prior book artifact byte-identical", async (context) => { + const fixture = await existingBook(context); + const updated = structuredClone(fixture.views); + updated[0].summary = "A changed first chapter must not publish before later rendering succeeds."; + const rendered = []; + await assert.rejects(renderBook(fixture.root, fixture.baseline, updated, fixture.output, { + renderer: "graphviz", + renderArtifact: async (view) => { + rendered.push(view.id); + if (view.id === "second") throw new Error("Injected second-chapter rendering failure"); + return renderFlow(view); + }, + }), /Injected second-chapter rendering failure/); + assert.deepEqual(rendered, ["first", "second"]); + await assertUnchanged(fixture); +}); + +test("late book metadata publication failure rolls back all chapters, companions and index", async (context) => { + const fixture = await existingBook(context); + const updated = fixture.views.map((view) => ({ ...view, title: `Updated ${view.title}`, summary: "New generation." })); + const committed = []; + await assert.rejects(renderBook(fixture.root, fixture.baseline, updated, fixture.output, { + renderer: "graphviz", + publication: { + renameFile: async (from, to) => { + if (basename(to) === "book.json") throw new Error("Injected late book publication failure"); + await rename(from, to); + committed.push(basename(to)); + }, + }, + }), /Injected late book publication failure/); + assert.equal(committed.length, 11); + assert.ok(committed.includes("second.html.receipt.json")); + assert.ok(committed.includes("index.html")); + await assertUnchanged(fixture); +}); + +test("reserved index chapter ID is rejected before replacing any existing two-chapter book artifact", async (context) => { + const fixture = await existingBook(context); + const updated = [ + { ...fixture.views[0], title: "Changed first chapter" }, + { ...fixture.views[1], id: "index" }, + ]; + await assert.rejects(renderBook(fixture.root, fixture.baseline, updated, fixture.output, + { renderer: "graphviz" }), /reserved.*index|index.*reserved/i); + await assertUnchanged(fixture); +}); diff --git a/experiments/plugin-spike/test/check-guide.test.mjs b/experiments/plugin-spike/test/check-guide.test.mjs new file mode 100644 index 0000000..0021672 --- /dev/null +++ b/experiments/plugin-spike/test/check-guide.test.mjs @@ -0,0 +1,80 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { access, readFile } from "node:fs/promises"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { repository } from "./helpers.mjs"; + +const execute = promisify(execFile); +const checker = fileURLToPath(new URL("../scripts/check-guide.mjs", import.meta.url)); +const manifestPath = ".topo/cache/plugin-spike/meaningful-guide/manifest.json"; +const controlledBrowser = ` +const { writeFileSync } = require("node:fs"); +writeFileSync("browser-required.txt", "required"); +exports.chromium = { + async launch() { + writeFileSync("browser-launched.txt", "launched"); + let viewport; + return { + async newPage() { return { + async setViewportSize(value) { viewport = value; }, + async goto() {}, + async waitForFunction() {}, + async evaluate() { return { + nodesPreserved: true, overlap: [], clipped: [], minFont: 16, + outer: [viewport.width, viewport.height], + frame: [viewport.width, viewport.height, viewport.width, viewport.height], + navLinks: 1, svgViewBox: "0 0 100 100", + }; }, + async screenshot() {}, + }; }, + async close() { writeFileSync("browser-closed.txt", "closed"); }, + }; + }, +}; +`; + +async function fixture(context, pages) { + return repository(context, { + ".gitignore": "node_modules/\n.topo/cache/\n", + "package.json": '{"name":"checker-fixture","private":true}\n', + [manifestPath]: JSON.stringify({ pages }), + "chapter.json": '{"sections":[{"id":"one","title":"One"}]}\n', + "node_modules/@playwright/test/package.json": '{"name":"@playwright/test","main":"index.cjs"}\n', + "node_modules/@playwright/test/index.cjs": controlledBrowser, + }); +} + +for (const [name, pages, chapter, expected] of [ + ["empty manifest", [], undefined, /nonempty.*pages|no.*pages|empty.*manifest/i], + ["unmatched chapter", [{ id: "chapter", path: "chapter.json" }], "missing", /no.*match|unknown.*chapter/i], +]) { + test(`guide checker rejects ${name} before requiring or launching the browser`, async (context) => { + const root = await fixture(context, pages); + const output = join(root, ".topo/cache/measurements"); + await assert.rejects(execute(process.execPath, + [checker, root, output, "http://127.0.0.1:9", ...(chapter ? [chapter] : [])], { cwd: root }), (error) => { + assert.equal(error.code, 1); + assert.match(error.stderr, expected); + return true; + }); + await assert.rejects(access(join(root, "browser-required.txt")), { code: "ENOENT" }); + await assert.rejects(access(join(root, "browser-launched.txt")), { code: "ENOENT" }); + await assert.rejects(access(output), { code: "ENOENT" }); + }); +} + +test("guide checker requires the nonzero selected-page viewport count using a controlled browser", async (context) => { + const root = await fixture(context, [{ id: "chapter", path: "chapter.json" }]); + const output = join(root, ".topo/cache/measurements"); + await execute(process.execPath, [checker, root, output, "http://127.0.0.1:9", "chapter"], { cwd: root }); + const report = JSON.parse(await readFile(join(output, "measurements.json"), "utf8")); + assert.equal(report.passed, true); + assert.equal(report.expectedMeasurements, 3); + assert.equal(report.results.length, 3); + assert.deepEqual(report.results.map(({ width, height }) => [width, height]), + [[1440, 900], [1600, 1000], [1920, 1080]]); + assert.equal(await readFile(join(root, "browser-closed.txt"), "utf8"), "closed"); +}); diff --git a/experiments/plugin-spike/test/contract.test.mjs b/experiments/plugin-spike/test/contract.test.mjs new file mode 100644 index 0000000..8d1798e --- /dev/null +++ b/experiments/plugin-spike/test/contract.test.mjs @@ -0,0 +1,27 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { factId, repositoryPath, serialize, sourceLocation } from "../src/contract.mjs"; + +test("canonical JSON ordering preserves array meaning and rejects non-JSON values", () => { + assert.equal(serialize({ z: 1, a: { y: 2, x: 3 } }), serialize({ a: { x: 3, y: 2 }, z: 1 })); + assert.notEqual(serialize([1, 2]), serialize([2, 1])); + assert.throws(() => serialize({ missing: undefined })); + assert.throws(() => serialize({ value: Number.NaN })); +}); + +test("fact identities are source-relative and namespaced by plugin and kind", () => { + const id = factId("rust", "function", "src/lib.rs", "module::run"); + assert.equal(id, factId("rust", "function", "src/lib.rs", "module::run")); + assert.notEqual(id, factId("typescript", "function", "src/lib.rs", "module::run")); + assert.notEqual(id, factId("rust", "method", "src/lib.rs", "module::run")); +}); + +test("paths and locations reject escapes and nonsensical evidence", () => { + for (const path of ["../src.rs", "/src.rs", "C:/src.rs", "src\\lib.rs", "src/../lib.rs", "src//lib.rs"]) { + assert.throws(() => repositoryPath(path)); + } + assert.deepEqual(sourceLocation("src/lib.rs", 2, 3, 4, 5), + { path: "src/lib.rs", startLine: 2, startColumn: 4, endLine: 3, endColumn: 5 }); + assert.throws(() => sourceLocation("src/lib.rs", 0)); + assert.throws(() => sourceLocation("src/lib.rs", 3, 2)); +}); diff --git a/experiments/plugin-spike/test/distribution.test.mjs b/experiments/plugin-spike/test/distribution.test.mjs new file mode 100644 index 0000000..6330e35 --- /dev/null +++ b/experiments/plugin-spike/test/distribution.test.mjs @@ -0,0 +1,57 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFile, access } from "node:fs/promises"; +import { fileURLToPath } from "node:url"; +import { dirname, resolve } from "node:path"; + +const root = fileURLToPath(new URL("../", import.meta.url)); +const json = async (path) => JSON.parse(await readFile(resolve(root, path), "utf8")); + +test("distribution pins published dependencies without local registry or checkout references", async () => { + const manifest = await json("package.json"); + const lock = await json("package-lock.json"); + assert.equal(manifest.private, true); + assert.equal(manifest.dependencies["@jdylanmc/topo-code"], "0.1.0"); + assert.equal(manifest.dependencies["@jdylanmc/topo-archify"], "0.1.0"); + assert.deepEqual(lock.packages[""].dependencies, manifest.dependencies); + for (const [name, entry] of Object.entries(lock.packages)) { + assert.equal(entry.link, undefined, name); + assert.equal(entry.resolved, undefined, `URL-free registry lock: ${name}`); + if (name && !entry.inBundle) assert.match(entry.integrity, /^sha(?:1|512)-[A-Za-z0-9+/]+=*$/, name); + } + for (const script of ["preinstall", "install", "postinstall", "prepare", "prepublishOnly"]) { + assert.equal(manifest.scripts[script], undefined, "No install or publication hooks"); + } +}); + +test("portable documentation links and bounded evidence are present without local artifact dependencies", async () => { + for (const path of ["README.md", "REPORT.md", "skills/topo-plugin-spike/SKILL.md"]) { + const text = await readFile(resolve(root, path), "utf8"); + assert.doesNotMatch(text, /\/Users\/|session-state\/|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/i); + for (const match of text.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) { + if (/^(?:https?:|#)/.test(match[1])) continue; + await access(resolve(root, dirname(path), match[1].split("#")[0])); + } + } + for (const path of ["evidence/summary.json", "evidence/semantic-probe.json"]) { + const text = await readFile(resolve(root, path), "utf8"); + assert.ok(Buffer.byteLength(text) < 20 * 1024, "Compact evidence, not full baseline/native HTML"); + assert.doesNotMatch(text, /\/Users\/|\/home\/|session-state|file:\/\//); + } +}); + +test("evidence distinguishes historical engines, incomplete semantics and the missing core landing", async () => { + const summary = await json("evidence/summary.json"); + assert.equal(summary.status, "historical-measurements-not-human-acceptance"); + assert.equal(summary.rendering.native.engine, "Archify 3.0.0"); + assert.equal(summary.rendering.native.checksPassed, 9); + assert.equal(summary.rendering.technical.engine, "Graphviz 16.0.0"); + assert.equal(summary.rendering.technical.archifyChecksClaimed, false); + assert.equal(summary.nextCoreDeliverable.implementedHere, false); + const semantic = await json("evidence/semantic-probe.json"); + assert.equal(semantic.attempts, 2); + assert.equal(semantic.liveLauncherShipped, false); + assert.equal(semantic.osSandboxClaimed, false); + assert.equal(semantic.cargoInvocations, 0); + assert.equal(semantic.procMacroExecution, false); +}); diff --git a/experiments/plugin-spike/test/flow-renderer.test.mjs b/experiments/plugin-spike/test/flow-renderer.test.mjs new file mode 100644 index 0000000..bf21a60 --- /dev/null +++ b/experiments/plugin-spike/test/flow-renderer.test.mjs @@ -0,0 +1,29 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { flowSpecification, renderFlow } from "../src/flow-renderer.mjs"; + +test("algorithm renderer keeps every branch and distinct decision/data shapes", async () => { + const view = { + title: "Admission", + sections: [ + { id: "ready", title: "Ready to run?", kind: "decision" }, + { id: "save", title: "Save Running", kind: "data" }, + { id: "stop", title: "Return error", kind: "step" }, + ], + connections: [ + { from: "ready", to: "save", label: "Yes: begin", classification: "source-traced" }, + { from: "ready", to: "stop", label: "No: reject", classification: "source-traced" }, + ], + }; + const spec = flowSpecification(view); + assert.match(spec.source, /shape="diamond"/); + assert.match(spec.source, /shape="cylinder"/); + const first = await renderFlow(view); + const second = await renderFlow(view); + assert.equal(first.contents, second.contents); + assert.equal(first.validation.nodes, 3); + assert.equal(first.validation.edges, 2); + assert.match(first.contents, /data-node-id="ready"/); + assert.match(first.contents, /Yes: begin/); + assert.match(first.contents, /No: reject/); +}); diff --git a/experiments/plugin-spike/test/helpers.mjs b/experiments/plugin-spike/test/helpers.mjs new file mode 100644 index 0000000..9f2361c --- /dev/null +++ b/experiments/plugin-spike/test/helpers.mjs @@ -0,0 +1,38 @@ +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { mkdtemp, mkdir, realpath, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; + +const execute = promisify(execFile); + +export async function repository(context, files) { + const root = await mkdtemp(join(tmpdir(), "topo-plugin-spike-test-")); + context.after(() => rm(root, { recursive: true, force: true })); + for (const [path, contents] of Object.entries(files)) { + await mkdir(dirname(join(root, path)), { recursive: true }); + await writeFile(join(root, path), contents); + } + const env = { + ...process.env, GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", + GIT_AUTHOR_DATE: "2000-01-01T00:00:00Z", GIT_COMMITTER_DATE: "2000-01-01T00:00:00Z", + }; + await execute("git", ["init", "-q", "-b", "main", root], { env }); + await execute("git", ["-C", root, "add", "."], { env }); + await execute("git", ["-C", root, "-c", "core.hooksPath=/dev/null", + "-c", "user.name=Topocode synthetic fixture", "-c", "user.email=fixture@example.invalid", + "commit", "-qm", "fixture"], { env }); + return realpath(root); +} + +export const MIXED_FILES = { + "package.json": '{"name":"fixture","type":"module","dependencies":{"@tauri-apps/api":"2.10.1"}}\n', + "src/main.ts": `import { invoke } from "@tauri-apps/api/core"; +export async function refresh() { return invoke("snapshot"); } +`, + "src-tauri/Cargo.toml": '[package]\nname="fixture"\nversion="0.1.0"\nedition="2021"\n', + "src-tauri/src/lib.rs": `#[tauri::command] +pub fn snapshot() -> String { "fixture".to_owned() } +pub fn run() { tauri::Builder::default().invoke_handler(tauri::generate_handler![snapshot]); } +`, +}; diff --git a/experiments/plugin-spike/test/initialize.test.mjs b/experiments/plugin-spike/test/initialize.test.mjs new file mode 100644 index 0000000..eecf5e3 --- /dev/null +++ b/experiments/plugin-spike/test/initialize.test.mjs @@ -0,0 +1,38 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFile, mkdir, writeFile, symlink } from "node:fs/promises"; +import { join } from "node:path"; +import { initialize } from "../src/initialize.mjs"; +import { repository } from "./helpers.mjs"; + +test("project onboarding preserves existing instructions and is idempotent", async (context) => { + const originals = { + "AGENTS.md": "Existing repository authority. Preserve it.\n", + ".agents/skills/unrelated/SKILL.md": "Existing unrelated skill.\n", + ".github/instructions/existing.instructions.md": "Existing path instructions.\n", + "src/main.ts": "export const value = 1;\n", + }; + const root = await repository(context, originals); + const first = await initialize(root); + assert.equal(first.installedContextFiles, 2); + assert.match(await readFile(join(root, ".agents/skills/topo-plugin-spike/SKILL.md"), "utf8"), /baseline/); + assert.match(await readFile(join(root, ".agents/skills/topo/SKILL.md"), "utf8"), /scan/); + for (const [path, bytes] of Object.entries(originals)) assert.equal(await readFile(join(root, path), "utf8"), bytes); + const second = await initialize(root); + assert.equal(second.installedContextFiles, 0); +}); + +test("differing or symlinked prototype context fails before changing workspace configuration", async (context) => { + const root = await repository(context, { + ".agents/skills/topo-plugin-spike/SKILL.md": "A different, human-owned file.\n", + "src/main.ts": "export const value = 1;\n", + }); + await assert.rejects(initialize(root), /Context destination conflict/); + await assert.rejects(readFile(join(root, ".topo/config.json")), { code: "ENOENT" }); + assert.equal(await readFile(join(root, ".agents/skills/topo-plugin-spike/SKILL.md"), "utf8"), "A different, human-owned file.\n"); + const other = await repository(context, { "src/main.ts": "export const value = 1;\n" }); + await mkdir(join(other, ".agents/skills"), { recursive: true }); + await symlink(join(root, ".agents/skills/topo-plugin-spike"), join(other, ".agents/skills/topo-plugin-spike")); + await assert.rejects(initialize(other), /Context destination conflict/); + await assert.rejects(readFile(join(other, ".topo/config.json")), { code: "ENOENT" }); +}); diff --git a/experiments/plugin-spike/test/integration.test.mjs b/experiments/plugin-spike/test/integration.test.mjs new file mode 100644 index 0000000..cad9edc --- /dev/null +++ b/experiments/plugin-spike/test/integration.test.mjs @@ -0,0 +1,138 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { readFile, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { scanBaseline, readBaseline, writeArtifact } from "../src/baseline.mjs"; +import { renderView, renderBook, validateView } from "../src/view.mjs"; +import { CONTRACT_VERSION, serialize } from "../src/contract.mjs"; +import { repository, MIXED_FILES } from "./helpers.mjs"; + +const execute = promisify(execFile); +const cli = fileURLToPath(new URL("../bin/topo-spike.mjs", import.meta.url)); + +test("real language plugins compose repeatably and expose a source-backed Tauri edge", async (context) => { + const root = await repository(context, MIXED_FILES); + const first = await scanBaseline(root, { repositoryId: "fixture" }); + const second = await scanBaseline(root, { repositoryId: "fixture", plugins: ["tauri", "typescript", "rust"] }); + assert.equal(serialize(first), serialize(second)); + assert.equal(first.coverage.status, "partial"); + assert.deepEqual(first.plugins.map(({ id }) => id), ["rust", "tauri", "typescript"]); + const native = first.entities.find((entity) => entity.language === "rust" && entity.name === "snapshot" && entity.kind !== "file"); + assert.ok(native); + const edge = first.relationships.find((relation) => relation.kind === "tauri-command-binding" && relation.to === native.id); + assert.ok(edge); + assert.ok(edge.evidence.some(({ path }) => path === "src/main.ts")); + assert.ok(edge.evidence.some(({ path }) => path === "src-tauri/src/lib.rs")); + assert.deepEqual(first.execution, { repositoryBuildScripts: false, proceduralMacros: false, modelInvocations: false }); + for (const [path, expected] of Object.entries(MIXED_FILES)) { + assert.equal(await readFile(join(root, path), "utf8"), expected); + } +}); + +test("Rust-only repositories do not need a TypeScript project", async (context) => { + const root = await repository(context, { + "Cargo.toml": '[package]\nname="rust_only"\nversion="0.1.0"\nedition="2021"\n', + "src/lib.rs": "pub struct Store;\nimpl Store { pub fn load(&self) {} }\n", + }); + const baseline = await scanBaseline(root); + assert.deepEqual(baseline.plugins.map(({ id }) => id), ["rust"]); + assert.ok(baseline.entities.some((entity) => entity.kind === "struct" && entity.name === "Store")); + assert.ok(baseline.entities.some((entity) => entity.name === "load" && entity.language === "rust")); +}); + +test("baseline-bound authored view renders with the pinned renderer and rejects source drift", async (context) => { + const root = await repository(context, MIXED_FILES); + const baseline = await scanBaseline(root); + const edge = baseline.relationships.find((relation) => relation.kind === "tauri-command-binding"); + assert.ok(edge); + const view = { + schemaVersion: CONTRACT_VERSION, id: "fixture", title: "Source-backed command", + summary: "A frontend call binds to a declared Rust command; runtime execution is not claimed.", + baselineId: baseline.id, + sections: [ + { id: "frontend", title: "Frontend", body: "The captured TypeScript call.", entityIds: [edge.from] }, + { id: "native", title: "Rust command", body: "The captured source-declared handler.", entityIds: [edge.to] }, + ], + connections: [{ from: "frontend", to: "native", label: "snapshot", + classification: "source-derived", relationshipIds: [edge.id] }], + }; + validateView(baseline, view); + const output = join(root, ".topo/cache/spike/view.html"); + const receipt = await renderView(root, baseline, view, output); + assert.equal(receipt.renderer.pin, "3.0.0"); + assert.equal(receipt.nativeValidation.checksPassed, 9); + assert.equal(receipt.nativeValidation.errors, 0); + assert.equal(receipt.nativeValidation.warnings, 0); + assert.equal(receipt.sourceDerivedConnections, 1); + assert.equal(receipt.humanReview, "pending"); + const html = await readFile(output, "utf8"); + assert.match(html, /]*id="diagram"/); + assert.match(await readFile(`${output}.native.html`, "utf8"), / relation.kind === "tauri-command-binding").length, 0); + assert.ok(changed.unresolved.some(({ text }) => text === "other")); +}); + +test("CLI partial publication is explicit and generated baseline edits are rejected", async (context) => { + const root = await repository(context, MIXED_FILES); + const output = join(root, ".topo/cache/spike/baseline.json"); + await assert.rejects(execute(process.execPath, [cli, "scan", root, "--output", output]), (error) => { + assert.equal(error.code, 1); + assert.match(error.stderr, /no baseline was published/); + return true; + }); + await assert.rejects(readFile(output), { code: "ENOENT" }); + await assert.rejects(execute(process.execPath, [cli, "scan", root, "--output", output, "--allow-partial"]), (error) => { + assert.equal(error.code, 2); + assert.match(error.stdout, /"status": "partial"/); + return true; + }); + const baseline = await readBaseline(output); + baseline.entities[0].name = "invented"; + await writeArtifact(output, serialize(baseline)); + await assert.rejects(readBaseline(output), /modified baseline/); +}); + +test("a linked technical book retains navigation, source evidence and independently reproducible native views", async (context) => { + const root = await repository(context, MIXED_FILES); + const baseline = await scanBaseline(root); + const edge = baseline.relationships.find((relation) => relation.kind === "tauri-command-binding"); + const frontend = baseline.entities.find((entity) => entity.id === edge.from); + const source = { + path: "src/main.ts", startLine: 2, endLine: 2, + sha256: baseline.source.files.find((file) => file.path === "src/main.ts").sha256, + excerpt: MIXED_FILES["src/main.ts"].split("\n")[1], + }; + const makeView = (id, title) => ({ + schemaVersion: CONTRACT_VERSION, id, title, summary: "Concrete command and source evidence.", + baselineId: baseline.id, + sections: [ + { id: "frontend", title: "refresh()", body: "The TypeScript frontend calls invoke.", entityIds: [frontend.id], evidence: [source] }, + { id: "native", title: "snapshot()", body: "A source-declared Rust command.", entityIds: [edge.to] }, + ], + connections: [{ from: "frontend", to: "native", label: "snapshot", classification: "source-derived", relationshipIds: [edge.id] }], + }); + const views = [makeView("entry", "Entry"), makeView("command", "Command bridge")]; + const output = join(root, ".topo/cache/book"); + const receipt = await renderBook(root, baseline, views, output); + assert.equal(receipt.views, 2); + const entry = await readFile(join(output, "entry.html"), "utf8"); + assert.equal(await readFile(join(output, "index.html"), "utf8"), entry); + assert.match(entry, /href="\.\/command.html"/); + assert.match(entry, /refresh\(\)/); + assert.ok(receipt.receipts.every((item) => item.nativeValidation.checksPassed === 9)); + const modified = structuredClone(views); + modified[1].sections[0].evidence[0].excerpt = "invented();"; + await assert.rejects(renderBook(root, baseline, modified, output), /excerpt does not match/); + assert.equal(await readFile(join(output, "entry.html"), "utf8"), entry); +}); diff --git a/experiments/plugin-spike/test/inventory.test.mjs b/experiments/plugin-spike/test/inventory.test.mjs new file mode 100644 index 0000000..ef510cf --- /dev/null +++ b/experiments/plugin-spike/test/inventory.test.mjs @@ -0,0 +1,39 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdir, readFile, symlink, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { captureInventory, assertInventoryCurrent, stableRead } from "../src/inventory.mjs"; +import { repository } from "./helpers.mjs"; + +test("source snapshot ignores generated cache but detects edits to already-untracked source", async (context) => { + const root = await repository(context, { "src/lib.rs": "pub fn a() {}\n" }); + await writeFile(join(root, "src/new.rs"), "pub fn first() {}\n"); + const before = await captureInventory(root); + await mkdir(join(root, ".topo/cache"), { recursive: true }); + await writeFile(join(root, ".topo/cache/generated.ts"), "not source\n"); + await assertInventoryCurrent(before); + await writeFile(join(root, "src/new.rs"), "pub fn other() {}\n"); + await assert.rejects(assertInventoryCurrent(before), /inventory changed/); + assert.equal(await readFile(join(root, "src/lib.rs"), "utf8"), "pub fn a() {}\n"); +}); + +test("Rust root/nested metadata and compiler configuration are fingerprinted", async (context) => { + const root = await repository(context, { + "Cargo.toml": '[workspace]\nmembers=["native"]\n', + "native/Cargo.toml": '[package]\nname="native"\nversion="0.1.0"\n', + "native/src/lib.rs": "pub fn a() {}\n", + ".cargo/config.toml": '[build]\ntarget="aarch64-apple-darwin"\n', + }); + const captured = await captureInventory(root); + assert.ok(captured.files.some(({ path }) => path === ".cargo/config.toml")); + assert.ok(captured.files.some(({ path }) => path === "native/Cargo.toml")); + await writeFile(join(root, ".cargo/config.toml"), '[build]\ntarget="x86_64-unknown-linux-gnu"\n'); + await assert.rejects(assertInventoryCurrent(captured), /inventory changed/); +}); + +test("source reads refuse symlinked files and parent escapes", async (context) => { + const root = await repository(context, { "src/lib.rs": "pub fn a() {}\n" }); + await symlink(join(root, "src/lib.rs"), join(root, "src/link.rs")); + await assert.rejects(stableRead(root, "src/link.rs"), /non-symlinked/); + await assert.rejects(stableRead(root, "../source.rs"), /repository-relative/); +}); diff --git a/experiments/plugin-spike/test/native-renderer.test.mjs b/experiments/plugin-spike/test/native-renderer.test.mjs new file mode 100644 index 0000000..ff5590f --- /dev/null +++ b/experiments/plugin-spike/test/native-renderer.test.mjs @@ -0,0 +1,30 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { architectureSpecification } from "../src/native-renderer.mjs"; + +test("native layout preserves every authored node and edge with no typography or routing rewrite", () => { + const view = { + title: "Source boundary", + sections: ["ui", "start", "cancel", "publish", "withdraw"].map((id) => ({ id, title: id })), + connections: [ + { from: "ui", to: "start", label: "start_review", classification: "source-derived" }, + { from: "ui", to: "publish", label: "architectural role", classification: "inferred" }, + ], + }; + const specification = architectureSpecification(view); + assert.deepEqual(specification.components.map(({ id }) => id), view.sections.map(({ id }) => id)); + assert.equal(specification.connections[0].label, "start_review"); + assert.equal(specification.connections[1].label, "Inferred: architectural role"); + assert.equal(specification.connections[1].variant, "dashed"); + assert.ok(specification.connections.every((connection) => !("via" in connection) && !("labelAt" in connection))); + assert.equal(specification.meta.quality_profile, "showcase"); + assert.equal(specification.layout.cols, 2); + assert.deepEqual(architectureSpecification(view), specification); +}); + +test("small views use the same native grid contract without hidden nodes or alternate topology", () => { + const view = { title: "Three roles", sections: ["a", "b", "c"].map((id) => ({ id, title: id })), connections: [] }; + const specification = architectureSpecification(view); + assert.equal(specification.layout.cols, 1); + assert.equal(specification.components.length, 3); +}); diff --git a/experiments/plugin-spike/test/publication.test.mjs b/experiments/plugin-spike/test/publication.test.mjs new file mode 100644 index 0000000..7c53298 --- /dev/null +++ b/experiments/plugin-spike/test/publication.test.mjs @@ -0,0 +1,71 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdir, readFile, readdir, rename, symlink, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; +import { writeArtifactSet } from "../src/publication.mjs"; +import { repository } from "./helpers.mjs"; + +const execute = promisify(execFile); + +test("late artifact publication failures restore every prior output and remove staging files", async (context) => { + const root = await repository(context, { "src/a.ts": "export const a = 1;\n" }); + for (const failAt of [1, 3]) { + const directory = join(root, `case-${failAt}`); + await mkdir(directory); + const names = ["view.html.native.html", "view.html.evidence.json", "view.html", "view.html.receipt.json"]; + for (const name of names) await writeFile(join(directory, name), `prior:${name}`); + const files = names.map((name) => ({ path: join(directory, name), contents: `new:${name}` })); + let commits = 0; + await assert.rejects(writeArtifactSet(files, { + renameFile: async (from, to) => { + if (commits++ === failAt) throw new Error("Injected commit failure"); + return rename(from, to); + }, + }), /Injected commit failure/); + for (const name of names) assert.equal(await readFile(join(directory, name), "utf8"), `prior:${name}`); + assert.deepEqual((await readdir(directory)).sort(), [...names].sort()); + } +}); + +test("a late failure on first publication does not leave a success-shaped partial set", async (context) => { + const root = await repository(context, { "src/a.ts": "export const a = 1;\n" }); + const directory = join(root, "output"); + let commits = 0; + await assert.rejects(writeArtifactSet([ + { path: join(directory, "native.html"), contents: "native" }, + { path: join(directory, "evidence.json"), contents: "{}" }, + ], { + renameFile: async (from, to) => { + if (commits++ === 1) throw new Error("Injected commit failure"); + return rename(from, to); + }, + }), /Injected commit failure/); + assert.deepEqual(await readdir(directory), []); +}); + +test("all output destinations are preflighted before replacing an existing artifact", async (context) => { + const root = await repository(context, { "src/a.ts": "export const a = 1;\n" }); + const output = join(root, "view.html"); + await writeFile(output, "prior"); + await mkdir(join(root, "receipt.json")); + await assert.rejects(writeArtifactSet([ + { path: output, contents: "new" }, { path: join(root, "receipt.json"), contents: "{}" }, + ]), /Unsafe artifact destination/); + assert.equal(await readFile(output, "utf8"), "prior"); +}); + +test("the npm-style symlink entrypoint executes instead of silently returning success", async (context) => { + const root = await repository(context, { "src/a.ts": "export const a = 1;\n" }); + const bin = join(root, "topo-spike"); + await symlink(fileURLToPath(new URL("../bin/topo-spike.mjs", import.meta.url)), bin); + const result = await execute(process.execPath, [bin, "--help"]); + assert.match(result.stdout, /topo-spike scan/); + await assert.rejects(execute(process.execPath, [bin, "not-a-command"]), (error) => { + assert.equal(error.code, 1); + assert.match(error.stderr, /Unknown command/); + return true; + }); +}); diff --git a/experiments/plugin-spike/test/rust.test.mjs b/experiments/plugin-spike/test/rust.test.mjs new file mode 100644 index 0000000..d364573 --- /dev/null +++ b/experiments/plugin-spike/test/rust.test.mjs @@ -0,0 +1,560 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import { scanRust, manifest } from "../src/plugins/rust.mjs"; +import { serialize } from "../src/contract.mjs"; + +function source(path, contents) { + return { path, contents, sha256: createHash("sha256").update(contents).digest("hex") }; +} +function scan(code, others = []) { + return scanRust({ root: "/nonexistent-must-not-read", files: [source("nested/src/lib.rs", code), ...others] }); +} +const cargo = source("nested/Cargo.toml", '[package]\nname = "fixture"\nversion = "0.1.0"\nedition = "2021"\n'); +function named(result, name, kind) { + return result.entities.find((entity) => entity.name === name && (!kind || entity.kind === kind)); +} +function meta(result, entity) { + return result.extensions.entityMetadata.find((record) => record.entityId === entity.id); +} + +test("real Rust grammar: private native kinds, owners, signatures, impl endpoints and trait signatures", async () => { + const result = await scan(`pub(crate) struct Engine { secret: u8 } +pub trait Run { type Output; fn run(&self) -> Self::Output; } +impl Run for Engine { + type Output = u8; + fn run(&self) -> u8 { self.secret } +} +enum State { Idle, Busy { value: u8 } } +type Alias = Engine; +mod inner { fn hidden() {} } +`, [cargo]); + assert.equal(manifest.kind, "language"); + assert.equal(named(result, "Engine").kind, "struct"); + assert.equal(named(result, "Engine").exported, false); + assert.equal(meta(result, named(result, "Engine")).visibility, "pub(crate)"); + assert.equal(named(result, "Run").exported, true); + assert.equal(named(result, "Run").signatures[0], "pub trait Run"); + assert.equal(named(result, "Alias").kind, "type"); + assert.equal(named(result, "Busy").kind, "variant"); + assert.equal(named(result, "value").ownerId, named(result, "Busy").id); + assert.equal(named(result, "hidden").ownerId, named(result, "inner").id); + const methods = result.entities.filter((entity) => entity.kind === "method"); + assert.equal(methods.length, 2); + assert.ok(methods.some((entity) => entity.signatures[0] === "fn run(&self) -> Self::Output;")); + assert.equal(result.relationships.filter((edge) => edge.kind === "impl-for").length, 1); + assert.equal(result.relationships.find((edge) => edge.kind === "impl-for").to, named(result, "Engine").id); + assert.equal(result.relationships.find((edge) => edge.kind === "impl-trait").to, named(result, "Run").id); + assert.equal(result.coverage.status, "partial"); + assert.ok(result.entities.every((entity) => entity.kind !== "class")); + assert.doesNotThrow(() => serialize(result)); +}); + +test("comments, strings and macro bodies do not fabricate declarations; UTF-16 locations stay exact", async () => { + const result = await scan('// fn fake() {}\nconst NOTE: &str = "😀é fn fake2() {}"; fn r#type() {}\nmacro_rules! make { () => { fn fake3() {} } }\nmake!();\n', [cargo]); + assert.deepEqual(result.entities.map((entity) => entity.name).sort(), ["NOTE", "make", "type"]); + assert.deepEqual(named(result, "type").location, { + path: "nested/src/lib.rs", startLine: 2, endLine: 2, startColumn: 41, endColumn: 55, + }); + assert.equal(meta(result, named(result, "type")).rawName, "r#type"); + assert.ok(result.unresolved.some((ref) => ref.kind === "macro" && ref.text === "make!()")); + assert.ok(result.unresolved.some((ref) => ref.kind === "macro-definition")); +}); + +test("Tauri rename changes command name, rename_all only records argument naming", async () => { + const result = await scan(`#![cfg(unix)] +#[cfg(feature = "desktop")] +mod nested { + #[tauri::command(rename_all = "camelCase")] + fn do_work() {} + #[tauri::command(rename = r#"run-now"#, rename_all = "snake_case")] + fn r#type() {} +} +`, [cargo]); + assert.deepEqual(result.extensions.tauriCommands.map((command) => command.commandName), ["do_work", "run-now"]); + assert.deepEqual(result.extensions.tauriCommands[0].conditions, ["#![cfg(unix)]", '#[cfg(feature = "desktop")]']); + assert.equal(result.extensions.tauriCommands[0].argumentRenameAll, "camelCase"); + assert.equal(result.extensions.tauriCommands[1].argumentRenameAll, "snake_case"); + assert.ok(result.unresolved.filter((ref) => ref.kind === "cfg").length >= 2); +}); + +test("handler tokens distinguish app/plugin/unknown without claiming reachability or scanning strings", async () => { + const result = await scan(`fn registrations() { + tauri::Builder::default().plugin(other()).invoke_handler(tauri::generate_handler![a::r#type, nested::work]); + tauri::plugin::Builder::new("test").invoke_handler(tauri::generate_handler![one]); + builder.invoke_handler(tauri::generate_handler![two, "fake::path"]); + let fake = "tauri::generate_handler![not_real]"; +} +`, [cargo]); + const registrations = result.extensions.tauriRegistrations; + assert.equal(registrations.length, 3); + assert.deepEqual(registrations.map((item) => item.registrationKind), ["app-builder", "plugin-builder", "unknown"]); + assert.deepEqual(registrations[0].rustPaths, ["a::r#type", "nested::work"]); + assert.deepEqual(registrations[2].rustPaths, ["two"]); + assert.deepEqual(registrations[2].rejectedTokens, ['"fake::path"']); + assert.ok(registrations.every((item) => item.runtimeReachability === "unknown")); + assert.equal(result.relationships.filter((edge) => edge.kind === "calls").length, 0); + assert.ok(result.unresolved.some((ref) => ref.kind === "call" && ref.text === "other")); +}); + +test("duplicate cfg declarations remain distinct, diagnosed and not falsely resolved", async () => { + const result = await scan(`#[cfg(a)] struct Service; +#[cfg(b)] struct Service; +trait Work {} +impl Work for Service {} +#[cfg(a)] fn go() {} +#[cfg(b)] fn go() {} +`, [cargo]); + const services = result.entities.filter((entity) => entity.name === "Service"); + assert.equal(services.length, 2); + assert.notEqual(services[0].id, services[1].id); + assert.equal(result.diagnostics.filter((item) => item.code === "rust.ambiguous-identity").length, 2); + assert.equal(result.relationships.filter((edge) => edge.kind === "impl-for").length, 0); + assert.equal(result.unresolved.find((ref) => ref.kind === "impl-type").candidates.length, 2); +}); + +test("generic parameters cannot be falsely connected to same-spelled local structs", async () => { + const result = await scan("struct T; trait Run {} impl Run for T {} impl Run for foreign::T {}", [cargo]); + assert.equal(result.relationships.filter((edge) => edge.kind === "impl-for").length, 0); + assert.equal(result.unresolved.filter((ref) => ref.kind === "impl-type").length, 2); +}); + +test("imports, aliased calls, cfg_attr and out-of-line modules explicitly remain unresolved", async () => { + const result = await scan(`use other::{work as alias, Stuff}; +mod outside; +#[cfg_attr(feature = "x", tauri::command)] +fn work(value: &dyn Work) { alias(); value.go(); T::go(); } +`, [cargo]); + assert.deepEqual(result.unresolved.filter((ref) => ref.kind === "call").map((ref) => ref.text).sort(), ["T::go", "alias", "value.go"]); + assert.equal(result.unresolved.filter((ref) => ref.kind === "use").length, 1); + assert.equal(result.unresolved.filter((ref) => ref.kind === "module-source").length, 1); + assert.equal(result.extensions.tauriCommands.length, 0); + assert.ok(result.unresolved.some((ref) => ref.kind === "cfg" && ref.text.includes("cfg_attr"))); +}); + +test("nested Cargo manifests preserve declared dependencies/features, not a resolved graph", async () => { + const result = await scan("fn helper() {}", [ + source("Cargo.toml", '[workspace]\nmembers = ["nested"]\n'), + source("nested/Cargo.toml", `[package] +name = "fixture" +version = "0.1.0" +edition = "2021" +[lib] +path = "src/lib.rs" +[dependencies] +serde = { version = "1", features = ["derive"] } +[target.'cfg(unix)'.dependencies] +libc = "0.2" +[build-dependencies] +codegen = "1" +[features] +default = ["desktop"] +desktop = ["serde/std"] +`), + ]); + assert.equal(result.extensions.crates.length, 2); + const crate = result.extensions.crates.find((record) => record.package); + assert.equal(crate.package.name, "fixture"); + assert.deepEqual(crate.dependencies.map((item) => [item.name, item.kind, item.target]), [ + ["serde", "dependencies", null], ["codegen", "build-dependencies", null], ["libc", "dependencies", "cfg(unix)"], + ]); + assert.deepEqual(crate.features.desktop, ["serde/std"]); + assert.equal(crate.targets[0].sourcePath, "nested/src/lib.rs"); + assert.equal(crate.targets[0].sourcePresent, true); + assert.equal(crate.evidenceKind, "declared-manifest-only"); + assert.equal(result.extensions.files[0].nearestManifestPath, "nested/Cargo.toml"); +}); + +test("bad/missing manifests and Rust parse errors do not become success-shaped completeness", async () => { + const result = await scan("fn broken( {", [source("nested/Cargo.toml", "[package\n")]); + assert.equal(result.coverage.status, "partial"); + assert.ok(result.diagnostics.some((item) => item.code === "rust.invalid-cargo-manifest")); + assert.ok(result.diagnostics.some((item) => item.code === "rust.syntax-error")); + assert.equal(result.extensions.files[0].status, "recovered-with-errors"); + const missing = await scan("fn valid() {}"); + assert.ok(missing.diagnostics.some((item) => item.code === "rust.missing-cargo-manifest")); + assert.ok(named(missing, "valid")); +}); + +test("canonical facts are deterministic, source-relative and independent of root or inventory order", async () => { + const files = [source("src/lib.rs", "fn alpha() {}"), source("Cargo.toml", '[package]\nname="a"\nversion="0.1.0"\n')]; + const first = await scanRust({ root: "/host/one", files }); + const second = await scanRust({ root: "/host/two", files: files.toReversed() }); + assert.equal(serialize(first), serialize(second)); + assert.ok(!serialize(first).includes("/host/")); + assert.equal(new Set(first.entities.map((item) => item.id)).size, first.entities.length); + assert.deepEqual(files[0], source("src/lib.rs", "fn alpha() {}")); +}); + +test("ambiguous or corrupt source inventories are rejected before extraction", async () => { + const file = source("src/lib.rs", "fn a() {}"); + await assert.rejects(scanRust({ root: ".", files: [file, file] }), /Duplicate captured inventory path/); + await assert.rejects(scanRust({ root: ".", files: [{ ...file, contents: "fn b() {}" }] }), /sha256 mismatch/); + await assert.rejects(scanRust({ root: ".", files: [source("../escape.rs", "")] }), /repository-relative/); +}); + +test("no Rust input means unsupported, not a complete empty program", async () => { + const result = await scanRust({ root: ".", files: [source("a.ts", "export {}")] }); + assert.equal(result.coverage.status, "unsupported"); + assert.deepEqual(result.coverage.analyzedFiles, []); +}); + +test("block-scoped declarations are not merged with unrelated enclosing names", async () => { + const result = await scan(`struct Local; +fn outer() { + { struct Local; impl Local {} } + { struct Local; impl Local {} } +} +`, [cargo]); + const locals = result.entities.filter((entity) => entity.name === "Local"); + assert.equal(locals.length, 3); + assert.equal(new Set(locals.map((entity) => entity.qualifiedName)).size, 3); + assert.equal(result.diagnostics.filter((item) => item.code === "rust.ambiguous-identity").length, 0); + const edges = result.relationships.filter((edge) => edge.kind === "impl-for"); + assert.equal(edges.length, 2); + assert.ok(edges.every((edge) => result.entities.find((entity) => entity.id === edge.to).location.startLine > 1)); +}); + +test("invalid Cargo table shapes are diagnosed rather than treated as declared dependency evidence", async () => { + const result = await scan("fn f() {}", [source("nested/Cargo.toml", 'package = "not-a-table"\ndependencies = "not-a-table"\n')]); + assert.equal(result.extensions.crates[0].status, "invalid"); + assert.ok(result.diagnostics.some((item) => item.code === "rust.invalid-cargo-shape")); +}); + +test("CRLF, Unicode identifiers and multiline signatures retain original spelling and ranges", async () => { + const result = await scan('struct Café;\r\npub fn café(\r\n value: &str,\r\n) -> usize {\r\n value.len()\r\n}\r\n', [cargo]); + assert.equal(named(result, "café").signatures[0], "pub fn café(\r\n value: &str,\r\n) -> usize"); + assert.deepEqual(named(result, "café").location, { + path: "nested/src/lib.rs", startLine: 2, startColumn: 1, endLine: 6, endColumn: 2, + }); + assert.equal(named(result, "Café").kind, "struct"); +}); + +test("modern unsafe extern grammar recovery is explicit rather than rewritten source", async () => { + const result = await scan('unsafe extern "C" {\n fn external();\n}\n', [cargo]); + assert.ok(result.diagnostics.some((item) => item.code === "rust.syntax-error")); + assert.equal(result.extensions.files[0].status, "recovered-with-errors"); + assert.ok(result.extensions.entityMetadata.some((item) => item.fileSyntaxStatus === "recovered-with-errors")); + assert.ok(result.coverage.limitations.some((item) => item.includes("unsafe extern"))); + assert.equal(result.coverage.status, "partial"); +}); + +test("inherited visibility and inner attributes are recorded without false public/private semantics", async () => { + const result = await scan('#![allow(dead_code)]\npub trait Public { fn visible(&self); }\npub enum Choice { Variant }\n', [cargo]); + assert.equal(meta(result, named(result, "visible")).visibility, "inherited"); + assert.equal(meta(result, named(result, "Variant")).visibility, "inherited"); + assert.ok(result.extensions.attributeObservations.some((item) => + item.text === "#![allow(dead_code)]" && item.attachment === "inner" && item.location.startLine === 1)); +}); + +test("failed or duplicate command renames do not invent a default command identity", async () => { + const result = await scan('#[tauri::command(rename = "a", rename = "b")]\nfn command() {}\n', [cargo]); + assert.deepEqual(result.extensions.tauriCommands, []); + assert.ok(result.unresolved.some((item) => item.kind === "tauri-command-options")); +}); + +test("declared Rust paths follow Cargo roots, out-of-line/inline modules and module cfg, not proximity", async () => { + const result = await scan(`#[cfg(feature = "desktop")] +mod copilot; +fn setup() { tauri::Builder::default().invoke_handler(tauri::generate_handler![copilot::state]); } +`, [cargo, + source("nested/src/copilot.rs", 'mod host;\n#[tauri::command(rename = "frontend_state")]\nfn state() {}\n'), + source("nested/src/copilot/host.rs", 'mod nested { #[tauri::command] fn r#type() {} }\n'), + source("nested/src/not_declared.rs", '#[tauri::command] fn state() {}\n'), + ]); + const commands = result.extensions.tauriCommands; + const state = commands.find((item) => item.commandName === "frontend_state"); + assert.equal(state.rustPathStatus, "established"); + assert.equal(state.rustPath, "crate::copilot::state"); + assert.deepEqual(state.conditions, ['#[cfg(feature = "desktop")]']); + assert.equal(commands.find((item) => item.commandName === "type").rustPath, "crate::copilot::host::nested::r#type"); + const orphan = commands.find((item) => item.location.path.endsWith("not_declared.rs")); + assert.equal(orphan.rustPathStatus, "unresolved"); + assert.equal(Object.hasOwn(orphan, "rustPath"), false); + assert.ok(result.unresolved.some((item) => item.kind === "tauri-command-path" && item.ownerId === orphan.entityId)); + const registration = result.extensions.tauriRegistrations[0]; + assert.equal(registration.modulePath, "crate"); + assert.equal(registration.rustModulePath, "crate"); + assert.equal(registration.crateId, state.crateId); + assert.equal(registration.pathResolution, "unresolved-token-paths"); +}); + +test("custom paths, cfg_attr module routing and two matching files remain explicitly unresolved", async () => { + const result = await scan(`#[path = "alternate.rs"] mod custom; +#[cfg_attr(unix, path = "other.rs")] mod platform; +mod ambiguous; +`, [cargo, + source("nested/src/custom.rs", "#[tauri::command] fn custom() {}"), + source("nested/src/platform.rs", "#[tauri::command] fn platform() {}"), + source("nested/src/ambiguous.rs", "#[tauri::command] fn one() {}"), + source("nested/src/ambiguous/mod.rs", "#[tauri::command] fn two() {}"), + ]); + assert.ok(result.extensions.tauriCommands.every((item) => item.rustPathStatus === "unresolved" && !Object.hasOwn(item, "rustPath"))); + assert.ok(result.extensions.moduleMappings.some((item) => item.status === "ambiguous" && item.candidates.length === 2)); + assert.ok(result.extensions.moduleMappings.filter((item) => item.reason?.includes("path/cfg_attr")).length === 2); +}); + +test("multiple crate roots cannot yield one guessed command crate identity", async () => { + const result = await scan("mod shared;", [ + cargo, source("nested/src/main.rs", "mod shared;"), + source("nested/src/shared.rs", "#[tauri::command] fn shared_command() {}"), + ]); + const command = result.extensions.tauriCommands[0]; + assert.equal(command.rustPathStatus, "ambiguous"); + assert.equal(Object.hasOwn(command, "rustPath"), false); + assert.equal(command.rustPathCandidates.length, 2); + assert.deepEqual(command.rustPathCandidates.map((item) => item.rustPath), ["crate::shared::shared_command", "crate::shared::shared_command"]); + assert.equal(new Set(command.rustPathCandidates.map((item) => item.crateId)).size, 2); +}); + +test("inline plugin registration records only a parsed literal namespace and module context", async () => { + const result = await scan(`mod plugin { + #[tauri::command] fn command() {} + fn setup(name: &str) { + tauri::plugin::Builder::new("native-tools").invoke_handler(tauri::generate_handler![command]); + tauri::plugin::Builder::new(name).invoke_handler(tauri::generate_handler![command]); + } +} +`, [cargo]); + const [literal, dynamic] = result.extensions.tauriRegistrations; + assert.equal(literal.registrationKind, "plugin-builder"); + assert.equal(literal.pluginNamespace, "native-tools"); + assert.equal(literal.pluginNamespaceStatus, "literal"); + assert.equal(literal.rustModulePath, "crate::plugin"); + assert.equal(literal.modulePath, "crate::plugin"); + assert.equal(dynamic.pluginNamespaceStatus, "unresolved"); + assert.equal(Object.hasOwn(dynamic, "pluginNamespace"), false); + assert.equal(dynamic.runtimeReachability, "unknown"); + assert.equal(result.extensions.tauriCommands[0].rustPath, "crate::plugin::command"); +}); + +test("nested function commands and use aliases never become crate-qualified declarations", async () => { + const result = await scan(`mod actual { #[tauri::command] fn command() {} } +use actual::command as renamed; +fn outer() { #[tauri::command] fn command() {} } +fn setup() { tauri::Builder::default().invoke_handler(tauri::generate_handler![renamed]); } +`, [cargo]); + assert.equal(result.extensions.tauriCommands.filter((item) => item.rustPathStatus === "established").length, 1); + assert.equal(result.extensions.tauriCommands.find((item) => item.rustPathStatus === "established").rustPath, "crate::actual::command"); + assert.equal(result.extensions.tauriCommands.filter((item) => item.rustPathStatus === "unresolved").length, 1); + assert.deepEqual(result.extensions.tauriRegistrations[0].rustPaths, ["renamed"]); + assert.ok(result.unresolved.some((item) => item.kind === "use" && item.text.includes("renamed"))); + assert.equal(result.relationships.filter((item) => item.kind.includes("tauri")).length, 0); +}); + +test("explicit Cargo library roots honor source path, conventional autodiscovery disablement and mod.rs", async () => { + const result = await scan("#[tauri::command] fn not_a_root() {}", [ + source("nested/Cargo.toml", '[package]\nname="fixture"\nversion="0.1.0"\nautolib=false\nautobins=false\n[lib]\npath="native/entry.rs"\n'), + source("nested/native/entry.rs", "mod api;"), + source("nested/native/api/mod.rs", 'mod child;\n'), + source("nested/native/api/child.rs", '#[tauri::command] fn command() {}'), + source("nested/src/main.rs", '#[tauri::command] fn not_a_bin() {}'), + ]); + const command = result.extensions.tauriCommands.find((item) => item.commandName === "command"); + assert.equal(command.rustPath, "crate::api::child::command"); + assert.ok(result.extensions.tauriCommands.filter((item) => item.commandName.startsWith("not_a_")) + .every((item) => item.rustPathStatus === "unresolved")); + assert.equal(result.extensions.crates[0].moduleRoots.length, 1); +}); + +test("cfg-alternative command declarations do not produce one guessed Rust endpoint", async () => { + const result = await scan('#[cfg(a)] #[tauri::command] fn command() {}\n#[cfg(b)] #[tauri::command] fn command() {}\n', [cargo]); + assert.equal(result.extensions.tauriCommands.length, 2); + for (const command of result.extensions.tauriCommands) { + assert.equal(command.rustPathStatus, "ambiguous"); + assert.equal(Object.hasOwn(command, "rustPath"), false); + assert.equal(command.rustPathCandidates.length, 2); + assert.ok(command.rustPathCandidates.every((candidate) => candidate.rustPath === "crate::command")); + assert.equal(new Set(command.rustPathCandidates.map((candidate) => candidate.entityId)).size, 2); + } +}); + +test("Tauri source locations after emoji use one-based UTF-16, not byte columns", async () => { + const result = await scan('const S: &str = "🦀"; #[tauri::command] fn crab() {}\nfn setup() {\n let _ = "🦀"; tauri::generate_handler![crab];\n}\n', [cargo]); + assert.equal(result.extensions.tauriCommands[0].location.startColumn, 41); + assert.equal(result.extensions.tauriCommands[0].location.startLine, 1); + assert.equal(result.extensions.tauriRegistrations[0].location.startColumn, 19); + assert.equal(result.extensions.tauriRegistrations[0].location.startLine, 3); + assert.equal(result.extensions.parser.rangeEncoding, "utf-16"); +}); + +test("nested registration modulePath preserves self/super scope and is null without a proved module chain", async () => { + const result = await scan(`#[tauri::command] fn same() {} +mod review { + #[tauri::command] fn same() {} + fn setup() { tauri::generate_handler![self::same, super::same]; } +} +`, [cargo]); + const registration = result.extensions.tauriRegistrations[0]; + assert.equal(registration.modulePath, "crate::review"); + assert.equal(registration.moduleContextStatus, "established"); + assert.deepEqual(registration.rustPaths, ["self::same", "super::same"]); + assert.ok(registration.moduleContextEvidence.some((location) => location.startLine === 2)); + assert.deepEqual(result.extensions.tauriCommands.map((command) => command.rustPath), ["crate::same", "crate::review::same"]); + const unlinked = await scan("fn setup() { tauri::generate_handler![self::same]; }"); + assert.equal(unlinked.extensions.tauriRegistrations[0].modulePath, null); + assert.equal(unlinked.extensions.tauriRegistrations[0].moduleContextStatus, "unresolved"); +}); + +function lexicalAncestors(result, scope) { + const ancestors = []; + const scopes = new Map(result.extensions.lexicalScopes.map((item) => [item.lexicalScope, item])); + while (scope !== null) { + assert.ok(!ancestors.includes(scope), "Lexical scope ancestry must not cycle"); + ancestors.push(scope); + assert.ok(scopes.has(scope), `Scope must have an explicit parent record: ${scope}`); + scope = scopes.get(scope).parentScope; + } + return ancestors; +} + +test("root-versus-local command shadow is observable without resolving handler targets", async () => { + const result = await scan(`#[tauri::command] fn snapshot() {} +fn setup() { + #[tauri::command] fn snapshot() {} + tauri::Builder::default().invoke_handler(tauri::generate_handler![snapshot]); +} +`, [cargo]); + const registration = result.extensions.tauriRegistrations[0]; + assert.equal(registration.moduleLexicalScope, "nested/src/lib.rs"); + const local = result.extensions.tauriCommands.find((item) => item.rustPathStatus === "unresolved"); + const root = result.extensions.tauriCommands.find((item) => item.rustPath === "crate::snapshot"); + const localBinding = result.extensions.lexicalBindings.find((item) => item.entityId === local.entityId); + const rootBinding = result.extensions.lexicalBindings.find((item) => item.entityId === root.entityId); + assert.equal(localBinding.name, "snapshot"); + assert.equal(localBinding.kind, "function"); + assert.equal(localBinding.lexicalScope, registration.lexicalScope); + assert.equal(localBinding.availability, "whole-scope"); + assert.equal(rootBinding.lexicalScope, registration.moduleLexicalScope); + assert.notEqual(rootBinding.lexicalScope, localBinding.lexicalScope); + assert.ok(lexicalAncestors(result, registration.lexicalScope).includes(registration.moduleLexicalScope)); + assert.deepEqual(registration.rustPaths, ["snapshot"]); + assert.equal(result.relationships.filter((item) => item.kind.includes("tauri")).length, 0); +}); + +test("function parameter and nested let-pattern names are distinct from constructor/field labels", async () => { + const result = await scan(`fn setup(snapshot: i32, Pair { left: renamed, right }: Pair) { + let (local, Some(inner), Pair { ref field, other: shadow, .. }, [head, tail @ ..]) = value; + { tauri::generate_handler![snapshot, renamed, local, inner, field, shadow, head, tail]; } +} +`, [cargo]); + const parameters = result.extensions.lexicalBindings.filter((item) => item.kind === "parameter"); + assert.deepEqual(parameters.map((item) => item.name).sort(), ["renamed", "right", "snapshot"]); + const lets = result.extensions.lexicalBindings.filter((item) => item.kind === "let-pattern"); + assert.deepEqual(lets.map((item) => item.name).sort(), ["field", "head", "inner", "local", "shadow", "tail"]); + const registration = result.extensions.tauriRegistrations[0]; + const ancestors = lexicalAncestors(result, registration.lexicalScope); + assert.ok([...parameters, ...lets].every((item) => ancestors.includes(item.lexicalScope))); + assert.ok(lets.every((item) => item.availability === "after-statement" && item.visibleAfter.startLine === 2)); + assert.ok([...parameters, ...lets].every((item) => item.bindingStatus === "syntactic-candidate")); +}); + +test("let visibility begins after the statement while item declarations are whole-scope", async () => { + const result = await scan(`fn setup() { + let snapshot = tauri::generate_handler![snapshot]; + tauri::generate_handler![snapshot]; + fn later() {} +} +`, [cargo]); + const binding = result.extensions.lexicalBindings.find((item) => item.kind === "let-pattern" && item.name === "snapshot"); + const [initializer, after] = result.extensions.tauriRegistrations; + assert.equal(binding.lexicalScope, initializer.lexicalScope); + assert.equal(binding.visibleAfter.startLine, 2); + assert.ok(binding.visibleAfter.startColumn > initializer.location.endColumn); + assert.ok(binding.visibleAfter.startLine < after.location.startLine); + assert.equal(result.extensions.lexicalBindings.find((item) => item.name === "later").availability, "whole-scope"); +}); + +test("root/module/block use trees expose aliases, imported leaves, self imports and globs with exact scopes", async () => { + const result = await scan(`use crate::api::{self, snapshot as root_alias, nested::{self as module_alias, leaf}, *}; +mod review { + use crate::api::snapshot as module_snapshot; + fn setup() { + use crate::api::{snapshot as local_snapshot, other::*}; + tauri::generate_handler![local_snapshot, module_snapshot, root_alias]; + } +} +`, [cargo]); + const uses = result.extensions.lexicalBindings.filter((item) => item.kind.startsWith("use")); + const registration = result.extensions.tauriRegistrations[0]; + assert.equal(uses.find((item) => item.name === "root_alias").lexicalScope, "nested/src/lib.rs"); + assert.equal(uses.find((item) => item.name === "api").kind, "use-self"); + assert.equal(uses.find((item) => item.name === "module_alias").kind, "use-alias"); + assert.equal(uses.find((item) => item.name === "leaf").kind, "use"); + assert.equal(uses.find((item) => item.name === "module_snapshot").lexicalScope, registration.moduleLexicalScope); + assert.equal(uses.find((item) => item.name === "local_snapshot").lexicalScope, registration.lexicalScope); + const globs = uses.filter((item) => item.wildcard === true); + assert.equal(globs.length, 2); + assert.deepEqual(globs.map((item) => item.lexicalScope).sort(), ["nested/src/lib.rs", registration.lexicalScope].sort()); + assert.ok(globs.every((item) => item.bindingStatus === "unresolved-import")); + const useDeclarations = new Map(result.extensions.useDeclarations.map((item) => [item.id, item])); + assert.equal(useDeclarations.size, 3); + assert.ok(uses.every((item) => useDeclarations.get(item.useDeclarationId)?.lexicalScope === item.lexicalScope)); + assert.equal(registration.modulePath, "crate::review"); +}); + +test("sibling-block bindings are not registration ancestors and anonymous imports introduce no named binding", async () => { + const result = await scan(`fn setup() { + { use crate::api::snapshot; let hidden = 1; } + { use crate::Trait as _; tauri::generate_handler![snapshot]; } +} +`, [cargo]); + const registration = result.extensions.tauriRegistrations[0]; + const ancestors = lexicalAncestors(result, registration.lexicalScope); + const sibling = result.extensions.lexicalBindings.filter((item) => ["snapshot", "hidden"].includes(item.name)); + assert.equal(sibling.length, 2); + assert.ok(sibling.every((item) => !ancestors.includes(item.lexicalScope))); + assert.ok(!result.extensions.lexicalBindings.some((item) => item.name === "_")); + assert.ok(result.unresolved.some((item) => item.kind === "use" && item.text.endsWith("as _;"))); + const anonymous = result.extensions.useDeclarations.find((item) => item.text.endsWith("as _;")); + assert.equal(anonymous.lexicalScope, registration.lexicalScope); + assert.equal(anonymous.moduleLexicalScope, registration.moduleLexicalScope); +}); + +test("closure parameters, for-patterns and match-arm bindings have bounded lexical scopes", async () => { + const result = await scan(`fn setup() { + let callback = |snapshot, (a, b)| { tauri::generate_handler![snapshot, a]; }; + for snapshot in items { tauri::generate_handler![snapshot]; } + match value { Some(snapshot) => { tauri::generate_handler![snapshot]; }, _ => () } + tauri::generate_handler![snapshot]; +} +`, [cargo]); + const registrations = result.extensions.tauriRegistrations; + assert.equal(registrations.length, 4); + for (const [index, kind] of ["closure-parameter", "for-pattern", "match-pattern"].entries()) { + const binding = result.extensions.lexicalBindings.find((item) => item.name === "snapshot" && item.kind === kind); + assert.ok(binding, kind); + assert.ok(lexicalAncestors(result, registrations[index].lexicalScope).includes(binding.lexicalScope)); + assert.ok(!lexicalAncestors(result, registrations[3].lexicalScope).includes(binding.lexicalScope)); + } +}); + +test("unsupported patterns and conditional binding scopes are explicit wildcard blockers, not guessed names", async () => { + const result = await scan(`fn setup() { + if let Some(snapshot) = value { tauri::generate_handler![snapshot]; } + match value { A(snapshot) | B(other) => { tauri::generate_handler![snapshot]; }, _ => () } + tauri::generate_handler![root_command]; +} +`, [cargo]); + const unknown = result.extensions.lexicalBindings.filter((item) => item.wildcard && item.bindingStatus === "unsupported"); + assert.ok(unknown.some((item) => item.reason.includes("conditional"))); + assert.ok(unknown.some((item) => item.reason.includes("or_pattern"))); + assert.ok(unknown.every((item) => !Object.hasOwn(item, "name"))); + const outer = result.extensions.tauriRegistrations.at(-1); + assert.ok(unknown.every((item) => !lexicalAncestors(result, outer.lexicalScope).includes(item.lexicalScope))); + assert.ok(result.unresolved.some((item) => item.kind === "lexical-binding")); +}); + +test("opaque statement/item macros expose possible generated bindings without expanding tokens", async () => { + const result = await scan(`fn setup() { + make_local!(); + tauri::generate_handler![snapshot]; +} +`, [cargo]); + const registration = result.extensions.tauriRegistrations[0]; + const opaque = result.extensions.lexicalBindings.find((item) => item.kind === "unexpanded-macro-bindings"); + assert.equal(opaque.wildcard, true); + assert.equal(opaque.lexicalScope, registration.lexicalScope); + assert.equal(opaque.bindingStatus, "unsupported"); + assert.ok(!result.extensions.lexicalBindings.some((item) => item.kind === "unexpanded-macro-bindings" && item.location.startLine === 3)); +}); diff --git a/experiments/plugin-spike/test/source-trace.test.mjs b/experiments/plugin-spike/test/source-trace.test.mjs new file mode 100644 index 0000000..95abe38 --- /dev/null +++ b/experiments/plugin-spike/test/source-trace.test.mjs @@ -0,0 +1,72 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { validateViewEvidence } from "../src/view.mjs"; +import { viewPage } from "../src/view-page.mjs"; +import { baselineDigest } from "../src/baseline.mjs"; +import { CONTRACT_VERSION, hash, sourceLocation } from "../src/contract.mjs"; + +function fixture() { + const contents = "fn main() {\n run();\n}\n"; + const files = [{ path: "src/main.rs", contents, sha256: hash(contents) }]; + const source = { path: files[0].path, sha256: files[0].sha256, startLine: 2, endLine: 2, excerpt: " run();" }; + const baseline = { + entities: [ + { id: "main", kind: "function", location: sourceLocation("src/main.rs", 1, 3) }, + { id: "run", kind: "function", location: sourceLocation("src/main.rs", 2) }, + ], relationships: [], source: { files }, + }; + baseline.id = baselineDigest(baseline); + const view = { + schemaVersion: CONTRACT_VERSION, baselineId: baseline.id, id: "startup", title: "Startup", + summary: "The actual Rust entry calls the native host.", + sections: [ + { id: "entry", title: "main()", body: "Native entry.", entityIds: ["main"], evidence: [source] }, + { id: "host", title: "run()", body: "The called host.", entityIds: ["run"], kind: "step" }, + ], + connections: [{ from: "entry", to: "host", label: "calls", classification: "source-traced", + relationshipIds: [], rationale: "Direct call in the entry body; not a compiler-extracted edge.", evidence: [source] }], + }; + return { baseline, view, files }; +} + +test("agent source traces verify exact code without pretending to be analyzer relationships", () => { + const { baseline, view, files } = fixture(); + validateViewEvidence(baseline, view, files); + const wrong = structuredClone(view); + wrong.connections[0].evidence[0].excerpt = " fabricated();"; + assert.throws(() => validateViewEvidence(baseline, wrong, files), /excerpt does not match/); + wrong.connections[0].evidence[0].sha256 = "0".repeat(64); + assert.throws(() => validateViewEvidence(baseline, wrong, files), /not bound/); +}); + +test("source trace validation rejects changed, absent, or incorrectly ranged evidence", () => { + const { baseline, view, files } = fixture(); + assert.throws(() => validateViewEvidence(baseline, view, [{ ...files[0], contents: "changed" }]), /evidence changed/); + view.connections[0].evidence[0].endLine = 99; + assert.throws(() => validateViewEvidence(baseline, view, files), /excerpt does not match/); + view.connections[0].evidence = []; + assert.throws(() => validateViewEvidence(baseline, view, files), /nonempty/); + view.connections[0].relationshipIds = ["pretend-compiler-edge"]; + assert.throws(() => validateViewEvidence(baseline, view, files)); +}); + +test("technical workbench renders navigation, full explanations, exact excerpts and provenance distinctions", () => { + const { baseline, view } = fixture(); + baseline.repository = { revision: "a".repeat(40), dirty: false }; + baseline.coverage = { status: "partial", byPlugin: {}, unsupportedLanguages: [] }; + const evidence = { + sections: view.sections.map((section) => ({ ...section, sources: section.evidence ?? [] })), + connections: view.connections.map((connection) => ({ ...connection, + fromTitle: "main()", toTitle: "run()", relationships: [] })), + }; + const html = viewPage(view, baseline, evidence, "startup.native.html", [ + { id: "startup", title: "Startup" }, { id: "review", title: "Review" }, + ]); + assert.match(html, /aria-label="PR-Sniper diagrams"/); + assert.match(html, /href="\.\/review.html"/); + assert.match(html, /aria-current="page"/); + assert.match(html, /Agent source trace - exact code checked/); + assert.match(html, /run\(\);/); + assert.match(html, /focusSection/); + assert.throws(() => viewPage(view, baseline, evidence, "native.html", [{ id: "../escape", title: "No" }]), /Invalid chapter ID/); +}); diff --git a/experiments/plugin-spike/test/tauri.test.mjs b/experiments/plugin-spike/test/tauri.test.mjs new file mode 100644 index 0000000..c09b813 --- /dev/null +++ b/experiments/plugin-spike/test/tauri.test.mjs @@ -0,0 +1,224 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { scanTauri } from "../src/plugins/tauri.mjs"; +import { scanRust } from "../src/plugins/rust.mjs"; +import { hash, sourceLocation } from "../src/contract.mjs"; + +const rust = { + plugin: { id: "rust" }, entities: [], + extensions: { + tauriCommands: [ + { entityId: "rust:snapshot", commandName: "snapshot", rustPath: "crate::snapshot", crateId: "fixture-lib", conditions: [], + location: sourceLocation("src/lib.rs", 1) }, + { entityId: "rust:review", commandName: "start_review", rustPath: "crate::review::start_review", crateId: "fixture-lib", conditions: [], + location: sourceLocation("src/review.rs", 1) }, + ], + tauriRegistrations: [{ location: sourceLocation("src/lib.rs", 3), modulePath: "crate", crateId: "fixture-lib", registrationKind: "app-builder", + rustPaths: ["crate::snapshot", "crate::review::start_review"], conditions: [] }], + }, +}; + +async function analyze(contents, extra = []) { + const files = [{ path: "src/main.ts", contents, sha256: hash(contents) }, ...extra]; + return scanTauri({ root: "/synthetic", files }, [rust]); +} + +test("literal, constant, and imported alias invocation bindings retain evidence", async () => { + const result = await analyze(` +import { invoke as call } from "@tauri-apps/api/core"; +const COMMAND = "snapshot"; +await call(COMMAND); +await call("start_review"); +`); + assert.deepEqual(result.extensions.bindings.map((b) => b.commandName).sort(), ["snapshot", "start_review"]); + assert.equal(result.relationships.filter((r) => r.kind === "tauri-command-binding").length, 2); + assert.equal(result.relationships.filter((r) => r.kind === "tauri-handler-entry").length, 2); + assert.ok(result.relationships.every((r) => r.evidence.some((e) => e.path.endsWith(".rs")))); + assert.ok(result.extensions.bindings.every((b) => b.runtimeReachability === "not-established")); +}); + +test("shadowed names and strings/comments are not Tauri invocations", async () => { + const result = await analyze(` +import { invoke } from "@tauri-apps/api/core"; +function other(invoke: (s:string)=>void) { invoke("snapshot"); } +const example = 'invoke("start_review")'; +// invoke("snapshot"); +`); + assert.equal(result.extensions.invocationSites, 0); + assert.equal(result.relationships.filter((r) => r.kind === "tauri-command-binding").length, 0); +}); + +test("known helper call sites are shown without claiming the caller set is complete", async () => { + const result = await analyze(` +import { invoke } from "@tauri-apps/api/core"; +async function run(command: string) { await invoke(command); } +await run("snapshot"); +await run("start_review"); +await run(globalThis.userCommand); +`); + assert.deepEqual(result.extensions.bindings.map((b) => b.commandName).sort(), ["snapshot", "start_review"]); + assert.ok(result.unresolved.some((u) => u.reason.includes("not closed"))); +}); + +test("destructured const loop commands produce enumerable source bindings", async () => { + const result = await analyze(` +import { invoke } from "@tauri-apps/api/core"; +for (const [id, command] of [["a", "snapshot"], ["b", "start_review"]]) { + document.getElementById(id)!.onclick = () => invoke(command); +} +`); + assert.deepEqual(result.extensions.bindings.map((b) => b.commandName).sort(), ["snapshot", "start_review"]); +}); + +test("mutable and unknown names stay unresolved, not guessed from spelling", async () => { + const result = await analyze(` +import { invoke } from "@tauri-apps/api/core"; +let command = "snapshot"; +await invoke(command); +await invoke("not_registered"); +`); + assert.equal(result.relationships.filter((r) => r.kind === "tauri-command-binding").length, 0); + assert.equal(result.unresolved.length, 2); +}); + +test("a matching leaf name in the wrong Rust module does not establish registration", async () => { + const other = structuredClone(rust); + other.extensions.tauriRegistrations[0].rustPaths = ["wrong::snapshot"]; + const contents = 'import { invoke } from "@tauri-apps/api/core"; invoke("snapshot");'; + const result = await scanTauri({ root: "/synthetic", files: [ + { path: "main.ts", contents, sha256: hash(contents) }, + ] }, [other]); + assert.equal(result.relationships.length, 0); + assert.equal(result.unresolved.filter((r) => r.kind === "tauri-invocation").length, 1); +}); + +test("handler scope and type-only frontend imports cannot invent root command bindings", async () => { + const other = structuredClone(rust); + other.extensions.tauriRegistrations[0].modulePath = "crate::other"; + other.extensions.tauriRegistrations[0].rustPaths = ["self::snapshot"]; + const contents = 'import { invoke } from "@tauri-apps/api/core"; invoke("snapshot");'; + const result = await scanTauri({ root: "/synthetic", files: [ + { path: "main.ts", contents, sha256: hash(contents) }, + ] }, [other]); + assert.equal(result.relationships.length, 0); + const typeOnly = await analyze('import type { invoke } from "@tauri-apps/api/core"; invoke("snapshot");'); + assert.equal(typeOnly.relationships.filter((r) => r.kind === "tauri-command-binding").length, 0); +}); + +test("different crates and inline plugin namespaces cannot become app-command bindings", async () => { + for (const mutation of [ + (registration) => { registration.crateId = "other-crate"; }, + (registration) => { registration.registrationKind = "plugin-builder"; registration.pluginNamespace = "other"; }, + (registration) => { registration.registrationKind = "unknown"; }, + ]) { + const other = structuredClone(rust); + mutation(other.extensions.tauriRegistrations[0]); + const contents = 'import { invoke } from "@tauri-apps/api/core"; invoke("snapshot");'; + const result = await scanTauri({ root: "/synthetic", files: [ + { path: "main.ts", contents, sha256: hash(contents) }, + ] }, [other]); + assert.equal(result.relationships.filter((r) => r.kind === "tauri-command-binding").length, 0); + assert.ok(result.unresolved.some((reference) => reference.kind === "tauri-invocation")); + } +}); + +test("modified helper parameters cannot retain their original caller-argument binding", async () => { + for (const mutation of [ + 'command = "start_review";', + 'command += "_changed";', + '[command] = ["start_review"];', + '({ command } = { command: "start_review" });', + 'const update = () => { command = "start_review"; }; update();', + '(command as string) = "start_review";', + 'command! = "start_review";', + '[(command as string)] = ["start_review"];', + '({ value: (command as string) } = { value: "start_review" });', + 'eval(\'command = "start_review"\');', + ]) { + const result = await analyze(`import { invoke } from "@tauri-apps/api/core"; +function run(command: string) { ${mutation} return invoke(command); } +run("snapshot"); +`); + assert.equal(result.extensions.bindings.length, 0, mutation); + assert.ok(result.unresolved.some((reference) => reference.kind === "tauri-invocation")); + } +}); + +test("reassigned helper bindings cannot propagate arguments into their previous definition", async () => { + const result = await analyze(`import { invoke } from "@tauri-apps/api/core"; +function run(command: string) { return invoke(command); } +run = () => invoke("start_review"); +run("snapshot"); +`); + assert.ok(!result.extensions.bindings.some(({ commandName }) => commandName === "snapshot")); + assert.ok(result.unresolved.some(({ kind }) => kind === "tauri-invocation")); +}); + +test("shared literal origins preserve each invocation site and its actual owner", async () => { + const contents = 'import { invoke } from "@tauri-apps/api/core";\nconst COMMAND = "snapshot";\nfunction one() { return invoke(COMMAND); } function two() { return invoke(COMMAND); }\n'; + const line = contents.split("\n")[2]; + const two = line.indexOf("function two"); + const first = line.indexOf("function one"); + const contribution = { + plugin: { id: "typescript" }, + entities: [ + { id: "typescript:one", location: sourceLocation("src/main.ts", 3, 3, first + 1, two) }, + { id: "typescript:two", location: sourceLocation("src/main.ts", 3, 3, two + 1, line.length + 1) }, + { id: "typescript:constant", location: sourceLocation("src/main.ts", 2, 2, 1, 28) }, + ], + }; + const result = await scanTauri({ root: "/synthetic", files: [ + { path: "src/main.ts", contents, sha256: hash(contents) }, + ] }, [rust, contribution]); + const bindings = result.relationships.filter((relation) => relation.kind === "tauri-command-binding"); + assert.equal(bindings.length, 2); + assert.equal(new Set(bindings.map(({ id }) => id)).size, 2); + assert.deepEqual(bindings.map(({ from }) => from).sort(), ["typescript:one", "typescript:two"]); + assert.deepEqual(result.extensions.bindings.map(({ callSite }) => callSite.startLine), [3, 3]); + for (const binding of result.extensions.bindings) { + const relationship = bindings.find(({ id }) => id === binding.relationshipId); + assert.ok(relationship.evidence.some((item) => item.path === binding.invokeSite.path && + item.startLine === binding.invokeSite.startLine && item.startColumn === binding.invokeSite.startColumn)); + assert.ok(relationship.evidence.some((item) => item.path === "src/main.ts" && item.startLine === 2)); + } +}); + +test("real Rust lexical shadows and use aliases do not bind the root command", async () => { + for (const body of [ + '#[tauri::command] fn snapshot() {} tauri::Builder::default().invoke_handler(tauri::generate_handler![snapshot]);', + 'use crate::other::snapshot; tauri::Builder::default().invoke_handler(tauri::generate_handler![snapshot]);', + 'use crate::other::*; tauri::Builder::default().invoke_handler(tauri::generate_handler![snapshot]);', + 'let snapshot = 1; tauri::Builder::default().invoke_handler(tauri::generate_handler![snapshot]);', + ]) { + const code = `#[tauri::command] fn snapshot() {} fn setup() { ${body} }`; + const files = [ + { path: "Cargo.toml", contents: '[package]\nname="fixture"\nversion="0.1.0"\n', sha256: hash('[package]\nname="fixture"\nversion="0.1.0"\n') }, + { path: "src/lib.rs", contents: code, sha256: hash(code) }, + { path: "src/ui.ts", contents: 'import { invoke } from "@tauri-apps/api/core"; invoke("snapshot");', + sha256: hash('import { invoke } from "@tauri-apps/api/core"; invoke("snapshot");') }, + ]; + const rustFacts = await scanRust({ root: "/synthetic", files }); + const result = await scanTauri({ root: "/synthetic", files }, [rustFacts]); + assert.equal(result.extensions.bindings.length, 0, body); + assert.ok(result.unresolved.some(({ kind }) => kind === "tauri-handler-entry")); + } +}); + +test("explicit crate paths and unrelated sibling bindings preserve valid source joins", async () => { + for (const body of [ + '#[tauri::command] fn snapshot() {} tauri::Builder::default().invoke_handler(tauri::generate_handler![crate::snapshot]);', + '{ let snapshot = 1; } tauri::Builder::default().invoke_handler(tauri::generate_handler![snapshot]);', + 'tauri::Builder::default().invoke_handler(tauri::generate_handler![snapshot]); let snapshot = 1;', + ]) { + const code = `#[tauri::command] fn snapshot() {} fn setup() { ${body} }`; + const files = [ + { path: "Cargo.toml", contents: '[package]\nname="fixture"\nversion="0.1.0"\n', sha256: hash('[package]\nname="fixture"\nversion="0.1.0"\n') }, + { path: "src/lib.rs", contents: code, sha256: hash(code) }, + { path: "src/ui.ts", contents: 'import { invoke } from "@tauri-apps/api/core"; invoke("snapshot");', + sha256: hash('import { invoke } from "@tauri-apps/api/core"; invoke("snapshot");') }, + ]; + const rustFacts = await scanRust({ root: "/synthetic", files }); + const result = await scanTauri({ root: "/synthetic", files }, [rustFacts]); + assert.equal(result.extensions.bindings.length, 1, body); + } +}); diff --git a/experiments/plugin-spike/test/view.test.mjs b/experiments/plugin-spike/test/view.test.mjs new file mode 100644 index 0000000..06c8f90 --- /dev/null +++ b/experiments/plugin-spike/test/view.test.mjs @@ -0,0 +1,60 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { validateView } from "../src/view.mjs"; +import { baselineDigest } from "../src/baseline.mjs"; +import { CONTRACT_VERSION, sourceLocation } from "../src/contract.mjs"; + +function fixture() { + const baseline = { + entities: [ + { id: "a", kind: "function", location: sourceLocation("src/ui.ts", 1) }, + { id: "b", kind: "function", location: sourceLocation("src/lib.rs", 1) }, + { id: "file", kind: "file", location: sourceLocation("src/ui.ts", 1) }, + ], + relationships: [ + { id: "edge", from: "a", to: "b", kind: "tauri-command-binding" }, + { id: "contains", from: "file", to: "a", kind: "declares" }, + ], + }; + baseline.id = baselineDigest(baseline); + const view = { + schemaVersion: CONTRACT_VERSION, id: "example", title: "Example", summary: "Source-backed.", + baselineId: baseline.id, + sections: [ + { id: "frontend", title: "Frontend", body: "Calls the source-declared command.", entityIds: ["a"] }, + { id: "native", title: "Native", body: "Registered command.", entityIds: ["b"] }, + ], + connections: [{ from: "frontend", to: "native", label: "command binding", + classification: "source-derived", relationshipIds: ["edge"] }], + }; + return { baseline, view }; +} + +test("a source-derived view must bind real source entities and correctly directed relationships", () => { + const { baseline, view } = fixture(); + validateView(baseline, view); + assert.throws(() => validateView(baseline, { ...view, baselineId: "old" }), /different baseline/); + const wrong = structuredClone(view); + wrong.connections[0].from = "native"; + wrong.connections[0].to = "frontend"; + assert.throws(() => validateView(baseline, wrong), /direction\/membership/); + wrong.connections[0].relationshipIds = ["invented"]; + assert.throws(() => validateView(baseline, wrong), /unknown relationship/); +}); + +test("collapsing a source file preserves factual relationships of its declared members", () => { + const { baseline, view } = fixture(); + view.sections[0].entityIds = ["file"]; + validateView(baseline, view); +}); + +test("interpretation is permitted but cannot masquerade as an observed baseline edge", () => { + const { baseline, view } = fixture(); + view.connections[0] = { + from: "frontend", to: "native", label: "architectural role", + classification: "inferred", rationale: "Human-reviewed interpretation of the cited entities.", relationshipIds: [], + }; + validateView(baseline, view); + view.connections[0].relationshipIds = ["edge"]; + assert.throws(() => validateView(baseline, view), /borrow factual/); +});