Archify
Archify: análisis de código desde el IR tipado al export validado
Usa una fixture mínima para seguir schema, layout, trazas de fuente, renderer, export y protección last-good.
Qué aprenderás
- Use typed IR as a source-analysis seam
- Trace validation and rendering boundaries
- Design a deterministic export regression fixture
Antes de empezar
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Conclusiones clave
- Typed JSON IR is the seam between agent output and deterministic code.
- Validation must precede rendering and protect last-good artifacts.
- Fixtures and export regression tests turn source reading into maintainable contributions.
Use the JSON IR as the seam
Empieza con una fixture de tres nodos y dos relaciones y localiza el esquema JSON tipado. Sigue validación, mapeo de errores, renderer, enlaces de fuente y exports autocontenidos; repite el render con una revisión fija para separar cambios topológicos de metadatos incidentales.
Record which fields are required, how identifiers are normalized, and whether unknown properties are rejected or ignored. A strict schema protects the renderer from plausible but malformed model output; a permissive schema needs an explicit warning path so missing semantics do not disappear silently.
Trace validation before rendering
Follow the call path from parsed JSON into schema, layout, and relationship validation. Note whether validation is pure, whether it mutates the input, and how errors map back to a node or edge. Then run the same fixture through the CLI or skill entry point and compare the receipt with the direct library path if both are documented.
Validation should run before any export side effect. A last-good preview or atomic output directory is valuable because a failed candidate cannot overwrite the artifact a reviewer trusts. Test malformed IDs, disconnected nodes, duplicate edges, and an empty diagram as separate fixtures.
Inspect renderer and interaction code
Once the IR passes, locate the renderer that produces self-contained HTML/SVG and the modules that add finite motion, themes, route tracing, or Before/Delta/After comparison. Check how source links are carried into the visual layer, how HTML is escaped, and whether external assets are fetched at build time or runtime.
Export behavior is part of correctness. For a fixed fixture, render HTML and SVG twice and compare normalized output or checksums. If timestamps or random IDs make output differ, isolate those fields so a visual diff reflects a topology change rather than incidental noise.
Contribution-sized findings
The safest first contribution is a fixture plus a regression test: preserve a source trace through rendering, reject a duplicate edge, keep last-good output on validation failure, or make an export self-contained. Include the input revision, expected validation result, and a redacted artifact in the issue.
Avoid inferring architecture from a screenshot or a marketing bullet. Separate README claims, observed call paths, and hypotheses, and measure performance with the same fixture and host before proposing a renderer optimization. That discipline keeps Archify's deterministic promise meaningful as its diagram features grow.
Cómo elegir
| Criterio | Opción A | Opción B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Pasos de implementación
- 1
Create a three-node fixture and locate its schema/types.
- 2
Trace validation, error mapping, and side-effect boundaries.
- 3
Inspect renderer, source links, interactions, and export determinism.
- 4
Submit a focused fixture/regression test with revision and receipt.
Ejemplo para copiar
agent prompt -> typed JSON IR -> schema/layout validation
-> renderer + source traces -> HTML/SVG/export
-> checksum + last-good artifactPreguntas frecuentes
Where should I begin in a large Archify checkout?
Begin at the typed JSON schema and a tiny fixture; it is the clearest seam between the agent skill and renderer code.
What proves an export is deterministic?
Render the same pinned fixture repeatedly, normalize intentional metadata, and compare output or visual checksums.
Fuentes
- Archify README (captured 2026-08-31)Fuente verificada 2026-08-31
- Archify repositoryFuente verificada 2026-08-31