Turn Audit JSON into Self‑Contained Repair Branches

Audits end in a report, not in code

Teams run audit automation and receive a JSON file full of findings. The file lives in a ticket, a spreadsheet, or a Slack thread. Nothing ever touches the repository. The audit becomes a cost centre, not a source of improvement. Technical debt remains hidden, and code health does not improve.

The failure is clear: the audit output is not wired into the development workflow. The audit is an isolated artefact, and the repair work never materialises.

Turning the JSON into a repair branch

The remedy is to treat the audit JSON as a source of patches. A small script reads each finding, creates a minimal edit, and commits it on a dedicated branch. The branch contains only the changes required to fix the reported issue, no unrelated code.

// minimal‑repair.ts – a concrete example
import { readFileSync, writeFileSync } from 'fs';
import simpleGit from 'simple-git';

const audit = JSON.parse(readFileSync('audit.json', 'utf8'));
const git = simpleGit();

async function run() {
  const branch = `audit-repair/${Date.now()}`;
  await git.checkoutLocalBranch(branch);

  for (const f of audit.findings) {
    const src = readFileSync(f.file, 'utf8');
    const fixed = src.replace(f.pattern, f.replacement);
    writeFileSync(f.file, fixed);
    await git.add(f.file);
  }

  await git.commit('Audit‑driven repair');
  await git.push('origin', branch);
}
run();

The script assumes each finding supplies a file path, a regular‑expression pattern, and a replacement string. Those fields are the usual output of static‑analysis tools that power audit automation. The script does not attempt to infer intent beyond the supplied pattern; it respects the audit’s authority.

When the script finishes, the repository contains a branch named audit-repair/…. The branch can be opened as a pull request, reviewed, and merged. The change set is self‑contained, making the review lightweight and the merge low‑risk.

Embedding the flow in the CI pipeline

Running the script manually is useful for a one‑off fix, but the real value appears when the process is automated. Add a step to the CI pipeline after the audit stage:

1. Execute the audit tool, outputting audit.json.
2. Invoke the repair script.
3. Push the new branch.
4. Let the existing CI jobs test the branch automatically.

If the pipeline’s CI pipeline already blocks merges on failing tests, the repair branch will be validated before any human eyes see it. This closes the loop from audit to merged repair without additional coordination.

Because the script only touches files mentioned in the audit, the diff is tiny. The CI run therefore stays fast, and the risk of regressions stays low. The repository’s technical debt shrinks incrementally, and code health improves with each audit cycle.

The approach works with any repository that can be accessed via the plain HTTP API or the typed TypeScript client described on the /api-access page. The same method can be used in an offline run, reading the JSON from a file system snapshot.

Monday’s concrete action

Pick the most recent audit JSON you have. Copy the minimal‑repair.ts example into your repo’s tooling folder. Adjust the field names to match your audit format. Run the script locally, push the resulting branch, and open a pull request. Observe the CI run and the review feedback.

If the script succeeds, add it as a step in your CI configuration. If it fails, examine the INCONCLUSIVE cases where the audit pattern does not apply cleanly; those are the limits of automation and require manual judgement.

Closing the loop in this way is the practical step described in the pillar post /blog/closing-the-loop-from-repository-audit-to-merged-repair. By turning audit output into a repair branch, you convert a static report into an actionable improvement, reducing technical debt and raising code health with minimal overhead.