Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .agents/skills/topo-archify-maintenance/references/integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,20 @@ https://github.com/jdylanmc/topo-code/issues/13.
not semantic truth. The installed tarball fixture must move source, observe
stale-anchor failure, repair only affected fields, preserve stable IDs and
unrelated intent, then preview and bundle.
- **Theme ownership:** core owns `topo.theme.v1`, including native T/button/command
actions, reconstructed focus URLs and default SVG export's explicit-theme
seam. Test hostile old storage and live OS media plus actual SVG/PNG pixels.
A one-time `?theme=dark` is insufficient. Renderer package bytes stay pristine;
adapted/shared output hashes are separate from upstream receipts.
- **Technical backend:** explicit Graphviz 16.0.0 via `@viz-js/viz@3.30.0` handles
authored decisions/data with engine-specific receipts. Preserve native families;
never silently route a failing native story through Graphviz or call its
checks Archify certification. The exact embedded EPL-2.0 exception, backend
digest, build provenance and complete notices are enforced separately.
- **Language boundary:** normal core commands compose first-party parser-backed
Rust and Tauri evidence. Do not restore a private experimental CLI, infer
Rust semantics from spelling, or hide partial/unresolved coverage. Installed
`docs/rust-tauri.md` records durable operation and regression findings.

## Where the executable evidence lives

Expand Down
30 changes: 29 additions & 1 deletion .agents/skills/topo-story-authoring/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ npm exec --no -- topo story validate . stories/example.topo.json
```

Repair each reported `invalid-document`, `missing-file`, `missing-symbol`, or
`missing-pattern` failure by rereading the cited source and updating the
`missing-pattern` or `stale-source` failure by rereading the cited source and updating the
smallest affected authored fields. Repeat until validation succeeds. A success
lists every resolved source location but does **not** establish semantic
accuracy or complete explanation coverage; the author and human reviewer remain
Expand Down Expand Up @@ -90,3 +90,31 @@ small focused stories and short labels. For source moves, reread both sides,
repair only affected anchors and explanation, and retain IDs/unrelated intent.
The package includes executable before/after fixtures under
`node_modules/@jdylanmc/topo-code/examples/story-authoring/`.

## Rust/Tauri technical workflows

Read installed `node_modules/@jdylanmc/topo-code/docs/rust-tauri.md` and
`examples/rust-tauri/stories/` before using the extended contract.
Rust anchors support `language: "rust"`, an unambiguous lexical `symbol` and
exact `pattern`. Use `renderer: "graphviz", diagramFamily: "workflow"` explicitly
for decisions (`kind: "decision"`) or values (`kind: "data"`); native families
remain the default. Every technical anchor pins the complete file's SHA-256.
Every connection declares `classification: "source-traced"` or `"inferred"`,
`rationale` and `anchorIds`; source-traced connections require verified evidence.
Do not label an authored arrow source-derived or compiler control flow.

Hash changes require rereading and reconciling the explanation, not blindly
refreshing digests. Retain IDs when meaning is unchanged. Check exact node and
edge excerpts, cross-story/return links, Home inventory, shared app theme and
actual exports. Graphviz has its own layout receipt, not borrowed Archify
certification. A generic fixture is not evidence for another application's
behavior; disposable consumer diagrams/caches must not enter Topocode source.

Impl/trait methods are first-class source nodes. Repeated method names require
their structural qualified symbol, for example
`src/lib.rs::impl Engine#0::snapshot`, not an owner line/column. Comments and
blank lines change freshness/evidence but not these identities; preserve the
qualified symbol during comment-only hash repair. Tauri rest values and
spread-shifted argument positions remain unresolved, as do overwritten helpers
after dot or computed-member writes. Never promote those unresolved cases to
specific source-derived calls in a narrative.
15 changes: 13 additions & 2 deletions .agents/skills/topo/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,16 @@ Corepack, model service, account or renderer download is needed.
Both forms create a ready-to-serve diagram home without analysis, rendering
or browser/server launch, even in an empty/unborn repository. Repeated init
preserves authored context and the existing generated site.
2. Optionally run `npm exec --no -- topo scan .`. It scans TypeScript/JavaScript and renders
2. Optionally run `npm exec --no -- topo scan .`. It defaults to TypeScript/JavaScript and renders
committed stories plus Repository exploration. It never invokes a model.
Unsupported/unresolved source fails; an explicitly requested `--allow-partial`
preview is visibly partial and exits 2, not success.
For Rust/Tauri, first read installed
`node_modules/@jdylanmc/topo-code/docs/rust-tauri.md`. Explicitly configure
`analysis.languages: ["typescript", "rust"]` and `analysis.frameworks: ["tauri"]`
in durable `.topo/config.json`. The bridge requires both languages. Rust alone
is also supported. These parser-backed adapters remain partial; no Cargo,
rust-analyzer, proc-macro expansion or arbitrary plugin loader is implied.
3. Read [story authoring](../topo-story-authoring/SKILL.md). Author/refine a focused
explanation from source evidence. Validate drafts; commit only with the
repository owner's authority, then scan/preview the committed story.
Expand All @@ -32,7 +38,7 @@ Corepack, model service, account or renderer download is needed.
Serve the output with a static server. Hosting, access control and uploading
are separate owner decisions. Preserve all emitted license notices.

The init-first home is an unreleased source/local-candidate feature; public
The init-first home and Rust/Tauri support are unreleased source/local-candidate features; public
npm 0.1.0 predates it. Use a candidate containing this change, not a claim that
the existing registry version was updated.

Expand All @@ -42,3 +48,8 @@ Never execute an unknown enrichment command or claim inferred commentary is fact
Do not edit generated `.topo/cache` artifacts. Keep story IDs stable when source
moves. [Renderer maintenance](../topo-archify-maintenance/SKILL.md) is a maintainer
workflow, not an automatic consumer update or global skill installation.

After deleting only `.topo/cache`, regenerate with `topo scan . --allow-partial`
(exit 2 for Rust/Tauri), not edits to generated HTML. Preserve config, source,
stories and stable IDs. Bundles carry evidence, renderer assets and legal notices.
The synthetic installed `examples/rust-tauri/` demonstrates the portable workflow.
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Preserve upstream attribution bytes; the generated notices normalize whitespace.
licenses/third-party/* -text -whitespace
30 changes: 30 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,20 @@ publication remains a separate release-owner action.

### Added

- Support explicit first-party Rust language and Tauri bridge selection through
normal scan/preview/bundle commands, retaining JS/TS defaults, deterministic
source identities, lexical ownership, per-plugin partial/unresolved evidence
and conservative shadowing/mutation handling. No Cargo, proc-macro or model
execution is introduced.
- Add snapshot-bound technical Workflow stories with decision/data shapes,
exact node/edge excerpts and source-traced versus inferred connections.
Explicit Graphviz 16.0.0 rendering has engine-specific layout receipts and a
narrowly pinned embedded EPL-2.0 exception with full notices and source
availability. Native diagram families remain unchanged.
- Ship generic Rust/Tauri fixtures, installed authoring/operation guidance and
transferable parser, rendering, theme, publication and regeneration findings.
No consumer application's authored diagrams or caches are included.

- Create a ready-to-serve, branded diagram Home on plain or skills-enabled
`topo init`, including empty/unborn repositories without scanning. Reuse the
categorized inventory across Home and native story pages, keep Repository
Expand Down Expand Up @@ -128,6 +142,22 @@ publication remains a separate release-owner action.

### Fixed

- Retain Rust impl/trait methods through validated Repository publication,
preview, bundle and cache recreation. Structural impl/extern owner identities
keep named descendants and qualified anchors stable across comment-only moves.
- Reject uncertain Tauri helper positions across spreads/rest bindings and
invalidate obsolete helpers after equivalent dot/computed-member writes,
while preserving known scalar and unmodified-receiver controls.
- Preserve byte-pinned upstream license files through Git checkout conversion,
including Windows autocrlf, without weakening exact license digest gates.

- Make shell, evidence, authored/generated viewers and native default exports
share one app-owned theme across focus navigation, stored preferences, media
changes and native actions without altering pristine renderer package bytes.
- Preserve renderer-owned evidence/specification assets through scan and bundle,
distinguish native and adapted/shared-output hashes, and roll back reported
generation-replacement failures rather than leaving mixed generations.

- Publish explicit local tarball paths so npm cannot interpret `dist/filename.tgz`
as GitHub shorthand; verify both release modes with offline dry-run publication.
- Prevent static-bundle browser fixture cleanup from waiting on unused TCP
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,12 @@ Initialize a repository to create a ready-to-serve static diagram home in
`.topo/`. Add authored stories or scan supported source when needed.
No hosted service, no telemetry, no account.

Normal commands also support explicitly selected, parser-backed **Rust/Tauri**
and snapshot-bound technical workflows with decisions, exact node/edge source
evidence and an explicit Graphviz renderer. These capabilities are unreleased;
the existing registry 0.1.0 is unchanged. See [supported configuration, portable
examples and limits](./docs/rust-tauri.md).

The goal is to put a software engineer in the human-in-the-loop position: every
claim the tool makes about a codebase is backed by evidence you can follow, and
everything a human adds is recorded as such.
Expand Down
Loading
Loading