Archify Utilities for Repository Evidence and Location: Complete Developer Guide

The Archify utilities for repository evidence and location are located in the archify/scripts package, where four specialized modules handle evidence extraction, serialization, validation, and update verification.

The tt-a1i/archify repository provides a toolchain that embeds verifiable source code metadata directly into generated diagrams. These Archify utilities for repository evidence and location capture exact repository URLs, revision hashes, file paths, and line numbers, then surface this data as interactive beacons within SVG visualizations.

Core Evidence Utilities in archify/scripts

The repository evidence system relies on four primary modules that manage the entire lifecycle of source attribution, from initial capture to final rendering.

check-render-output.mjs – Evidence Extraction and Beacon Rendering

Located at archify/scripts/check-render-output.mjs, this utility runs both server-side and client-side. After diagram rendering completes, it extracts the JSON block archify-source-evidence-data to verify repository URLs, revision identifiers, and line references. It then injects visual beacons using the data-source-evidence-beacon attribute into the generated SVG elements, enabling users to trace diagram nodes back to specific source code locations.

render-examples.mjs – Evidence Serialization

The archify/scripts/render-examples.mjs module serializes example diagrams alongside their source-evidence metadata. It generates a hidden <script id="archify-source-evidence-data"> element containing the repository location payload, injecting it into the HTML document so downstream renderers can consume the evidence data.

generate-validators.mjs – Schema Validation Generation

Found at archify/scripts/generate-validators.mjs, this utility generates runtime validation code that enforces the shape of evidence payloads. It validates required fields including repository URL, revision strings, file paths, and line numbers, ensuring that only properly structured evidence enters the rendering pipeline.

check-update.mjs – Update Verification

The archify/scripts/check-update.mjs script prevents evidence drift during diagram updates. Before publishing new renders, it verifies that the diagram still points to the identical repository revision using the same evidence helpers, maintaining consistency between visual documentation and actual source code states.

Repository Evidence Workflow Implementation

The Archify utilities for repository evidence and location operate through a three-phase pipeline that bridges server-side generation with client-side interaction.

Server-Side Evidence Emission

The render-examples.mjs module constructs a structured evidence payload conforming to schemaVersion: 1, embedding repository metadata directly into the HTML output:

// archify/scripts/render-examples.mjs
const evidence = {
  schemaVersion: 1,
  verified: true,
  repository: {
    url: "https://github.com/example/repo",
    revision: "a1b2c3d4",
    shortRevision: "a1b2c3d"
  },
  referenceCount: 12,
  nodes: { /* file/path/line mappings */ }
};
document.body.insertAdjacentHTML(
  "beforeend",
  `<script id="archify-source-evidence-data" type="application/json">`+
  JSON.stringify(evidence)+
  `</script>`
);

Client-Side Evidence Consumption

When the page loads in the browser, the client-side portion of check-render-output.mjs reads the embedded evidence block and decorates diagram elements with traceability attributes:

// archify/scripts/check-render-output.mjs – browser execution context
const evidenceEl = document.getElementById('archify-source-evidence-data');
if (evidenceEl) {
  const evidence = JSON.parse(evidenceEl.textContent);
  evidence.nodes.forEach(node => {
    const el = document.querySelector(`[data-node-id="${node.id}"]`);
    if (el) {
      el.setAttribute('data-source-evidence-beacon', '');
      el.setAttribute('data-source-evidence-count', String(node.references));
    }
  });
}

Validation Before Publishing

The check-update.mjs utility imports validators from generate-validators.mjs to gate the publication pipeline:

// archify/scripts/check-update.mjs
import { validateEvidence } from "./generate-validators.mjs";

const newEvidence = /* extracted from new diagram */;
if (!validateEvidence(newEvidence)) {
  throw new Error("Invalid repository evidence – aborting update");
}

HTML Template Integration

The evidence workflow is orchestrated by HTML templates located at scripts/start-template.html and scripts/guide-template.html. These templates include the <script id="archify-source-evidence-data"> placeholder element that holds the repository evidence payload. When the documentation site loads, the templates automatically invoke check-render-output.mjs to process the embedded JSON and activate the visual evidence cues on the rendered diagrams.

Summary

• The archify/scripts package contains all utilities for handling repository evidence and location data in the Archify toolchain.
• check-render-output.mjs extracts evidence JSON and renders visual beacons that map diagram elements to source code lines.
• render-examples.mjs generates the hidden evidence payload embedded in every diagram page.
• generate-validators.mjs creates runtime validators ensuring evidence schema compliance for repository URLs, revisions, and line references.
• check-update.mjs verifies evidence consistency before allowing diagram updates to publish.
• HTML templates in scripts/ provide the integration points that load these utilities and embed the evidence data structure.

Frequently Asked Questions

Where exactly are the Archify utilities for repository evidence stored?

According to the tt-a1i/archify source code, the utilities reside in the archify/scripts directory. The four main files are check-render-output.mjs, render-examples.mjs, generate-validators.mjs, and check-update.mjs, which together handle evidence extraction, serialization, validation, and update verification.

How does check-render-output.mjs validate repository locations?

This utility extracts the archify-source-evidence-data JSON block from the rendered HTML and verifies that the repository.url and repository.revision fields match expected formats. It confirms that line references in the nodes object correspond to actual file paths before adding the data-source-evidence-beacon attributes to SVG elements.

What schema does the repository evidence payload follow?

The evidence payload uses schemaVersion: 1 and requires a repository object containing url, revision, and shortRevision strings, plus a nodes collection that maps diagram elements to specific file paths and line numbers. The generate-validators.mjs module enforces this schema at runtime to prevent malformed evidence from entering the rendering pipeline.

How does Archify ensure evidence consistency across diagram updates?

The check-update.mjs script runs before publishing any diagram update, using validators imported from generate-validators.mjs to compare the new evidence payload against the previous version. It specifically checks that the repository.revision remains consistent, throwing an error and aborting the update if the evidence references have changed or become invalid.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}