diffdevil v1.0.0

diffdevil v1.0.0

Publication standing: published from accepted release commit
0827485c9d3795ef58a7934cd7a4b8b3fb5cc9c5. npm
@wolfsblvt/diffdevil@1.0.0,
immutable v1.0.0,
maintained v1, the GitHub Marketplace listing,
a fresh outside-checkout npm consumer, and private live canaries through both
Action refs are read back. The canaries exercised all four entry points with
real provider reads and bounded effects; external-fork and live partial-write
behavior remain unobserved.

Measure changes. Match rules. Act on the result.

v1.0.0 is the first stable release of diffdevil: a portable diff-policy engine for the CLI, TypeScript, scripts, CI, GitHub Actions, saved reports, and coding-agent workflows.

It is useful as a one-file pull-request size labeler, but that is the entrance rather than the category. The same engine can answer scalar and file queries, preserve uncertain evidence, evaluate repository policy, produce inspectable effect plans, and reconcile only the GitHub labels and owned comments that policy selected.

What ships

One semantic engine

The package, CLI, TypeScript API, root Action, and three sub-actions share one implementation of:

• Git and unified-diff parsing;
• GitHub pull-request acquisition;
• raw additions/deletions/churn;
• replacement-aware added, deleted, modified, and changed lines;
• exact, bounded, unknown, incomplete, and unmeasurable evidence;
• rename-aware path selection and named scopes;
• metrics, queries, checks, bands, and rules;
• versioned reports and inspectable effect plans; and
• managed labels, label definitions, and owned-comment lifecycle.

A three-line replacement can therefore be reported as three modified positions while the six raw churn lines remain available. Convenience does not erase the underlying facts.

Useful without learning a language

Common routes do not require a policy file or the optional detail expression language.

# Analyze a patch.
diffdevil analyze --diff-file review.diff --format human

# Emit one machine-clean scalar.
diffdevil query --report report.json \
  --expr 'totals.lines.changed' --format value

# Use a condition through exit status.
diffdevil check --report report.json \
  --expr 'totals.lines.changed <= 250'

Presets and CLI/Action shortcuts lower into the same policy and expression semantics used by the full configuration surface. Growing into custom scopes, metrics, bands, rules, parameters, labels, or comments does not switch to a second simplified engine.

Four install-free GitHub Actions

The release contains executable Node 24 JavaScript and its exact runtime dependency closure. Consumers do not run npm install in the workflow.

Entry point	Purpose
Wolfsblvt/diffdevil@v1	Convenient default analysis and size@1 label reconciliation.
Wolfsblvt/diffdevil/actions/analyze@v1	Read-only report, metric, decision, and band outputs.
Wolfsblvt/diffdevil/actions/apply@v1	Freshly reacquire, re-evaluate, and apply selected effects.
Wolfsblvt/diffdevil/actions/sync-labels@v1	Verify or reconcile explicitly managed label definitions.

The smallest complete size-label workflow is:

name: Pull-request size
on:
  pull_request_target:
    types: [opened, reopened, synchronize, edited]
permissions:
  pull-requests: write
concurrency:
  group: diffdevil-size-${{ github.event.pull_request.number }}
  cancel-in-progress: false
jobs:
  size:
    runs-on: ubuntu-latest
    steps:
      - uses: Wolfsblvt/diffdevil@v1

It creates missing size/* definitions, maintains exactly one managed size label, preserves unrelated labels and existing definition presentation, posts no comment by default, and requires no checkout or personal token.

Security-sensitive consumers may pin the immutable v1.0.0 release or exact
commit 0827485c9d3795ef58a7934cd7a4b8b3fb5cc9c5 rather than the maintained
major alias.

Deliberate split credentials

Actions accept an optional policy-token for trusted base or immutable pinned policy files and relative templates. github-token continues to own pull-request acquisition and every label/comment effect.

This permits a read-only workflow credential to load repository policy while a narrowly scoped App token performs effects. The policy credential never becomes an alternate writer. Both values are masked and redacted, and omitting policy-token preserves the original single-token behavior.

Typed TypeScript surface

The package exports deliberate public subpaths instead of every internal module:

@wolfsblvt/diffdevil
@wolfsblvt/diffdevil/core
@wolfsblvt/diffdevil/language
@wolfsblvt/diffdevil/policy
@wolfsblvt/diffdevil/git
@wolfsblvt/diffdevil/github

Declarations, schemas, presets, package metadata, and the diffdevil executable ship in the installed artifact. Reports, plans, query results, typed values, and policy structure have versioned machine contracts.

Trust and effect model

A token does not turn analysis into mutation.

• /analyze rejects effect inputs and remains read-only.
• Privileged policy comes from the pull request's current base, an immutable pin, or an explicitly read-only workspace route; PR-head policy never authorizes writes.
• Pull-request, base, policy, comparison, and API-host identities are reacquired and checked before effects.
• The adapter verifies current state before each individual provider write.
• Saved reports and plans are validated against fresh acquisition rather than promoted to write authority.
• Managed-label reconciliation touches only declared group members.
• Owned comments require an expected author, diffdevil marker, policy identity, lifecycle sequence, and provider readback.
• Writes are never retried blindly after an ambiguous transport failure.
• Partial requests and readbacks remain visible in the effect observation journal.

GitHub content, paths, titles, bodies, branch names, patches, and provider payloads are treated as hostile data. diffdevil executes no pull-request JavaScript or shell merely because a privileged workflow is running.

Evidence instead of convenient fiction

Counts are not forced into exact numbers when the source cannot support them.

A result may be:

• exact, with one supported value;
• bounded, with supported lower and upper limits;
• unknown, with explicit reasons and any known bounds;
• unmeasurable, where the material cannot honestly produce the requested fact; or
• part of an incomplete file set, where provider ceilings prevent a complete aggregate.

Queries, conditions, collections, bands, and policy decisions preserve those distinctions. Unknown is not false, zero, empty, or a generic configuration error.

Compatibility and runtime

• npm package and CLI: Node.js 22 or later.
• GitHub Actions: committed Node 24 runtime.
• Configuration: JSON or YAML policy version 1.
• Expression language: diffdevil-expr/1.
• Replacement semantics: replacement-lines-v1.
• Path semantics: diffdevil-glob/1.
• Public reports and plans: schema version 1.0.

This is the first stable release, so there is no earlier stable API to migrate. Prerelease sub-action locations are intentionally not retained as duplicate wrappers; use /actions/analyze, /actions/apply, and /actions/sync-labels.

Qualification standing

The accepted 1.0.0 source tree was exercised through distinct boundaries rather than one green unit suite being promoted into everything:

• native Windows 11 with Node 24, npm, PowerShell, real npm launcher dispatch, and offline restoration of the exact lock;
• 474 ordinary behavioral tests and exact generated Action parity;
• 189 supplied conformance cases;
• an installed 486-file npm tarball outside the source checkout, including CLI, ESM API, declarations, schemas, presets, assets, and licence dispatch;
• 10 isolated executions covering all four install-free Actions;
• hosted Linux Node 22, Linux Node 24, and Windows Node 24 consumer matrices; and
• a private live GitHub canary for definition creation/readback, managed-label changes and no-op, trusted policy confinement, stale-plan refusal, owned-comment update, and split policy/effect credentials.

The maintained Qualification document binds exact evidence to source coordinates and preserves what remains unobserved. Native macOS, a genuine external-fork event, and a real live partial-write failure are not claimed by this release.

Licensing

No single licence describes every shipped file.

• Reusable engine, TypeScript API, npm/CLI, GitHub Action software, tools, and mapped runnable examples: MIT.
• Playground, website, managed App, hosted runtime, and service software when present: AGPL-3.0-only.
• Original documentation prose and reusable explanation: CC BY 4.0.
• Product name, slogans, logo, mascot, artwork, screenshots, and other visual identity: reserved unless separately licensed.
• Third-party dependencies retain their own licences and notices.

The installed npm package uses SEE LICENSE IN LICENSE.md and includes the component map. The separate Action runtime remains MIT software with retained third-party notices.

Security reporting

Use the repository's private vulnerability-reporting route described in SECURITY.md. Do not disclose a suspected vulnerability through a public issue before coordinated review.

Deliberately separate product surfaces

This release is the stable open package, CLI, API, and Action release. It does not claim that the following already exist:

• a publicly deployed PR playground;
• the managed diffdevil GitHub App;
• a hosted history or administration experience;
• a documentation website or custom domain; or
• a general repository-governance or AI-review platform.

The local read-only playground exists in source and uses the same engine. Hosted playground and managed-App work remain active product custody, not features silently dropped from the complete destination to make the release checklist shorter.

Start here

• README and first useful routes
• Auto-labeling quickstart
• Local automation
• Policy recipes
• GitHub Actions integration
• CLI integration
• TypeScript API
• detail language
• Qualification
• Security policy