DStyle

Warning: This is Vibe Coded. Tests are updated everytime an edge case is found. Tests codebases against my personal style of clean & fast code that both humans and machines can read easily. It tries to limit the vocabulary and the way things are done without hurting expressiveness.

Usage

Install:

using Pkg
Pkg.add(url = "https://github.com/D3MZ/DStyle.jl")

Run checks (Aqua.jl-like):

using Test
using DStyle
using YourPackageName

@testset "DStyle" begin
    DStyle.test_all(YourPackageName)
end

(YourPackageName is your package module name.) Per-check options follow Aqua style, e.g. DStyle.test_all(YourPackageName; kernel_function_barriers=(max_lines_from_signature=2,), julia_index_from_length=true, module_type_camel_case=true, function_name_lowercase=true, mutating_function_bang=true, field_name_type_repetition=true, simple_verb_redefinition=true, ignore=["DataFrame", "DataFrames.DataFrame"]) or disable checks with rule_name=false. This repository also runs DStyle.test_all(DStyle) in .github/workflows/dstyle.yml.

Repository layout

src/
  DStyle.jl                     # module entrypoint + includes
  core/                         # shared scanner, runner, reporting, path/string utilities
  rules/                        # one file per lint rule
  integrations/                 # CI/GitHub workflow helpers

test/
  runtests.jl                   # test entrypoint
  core/                         # runner-level behavior tests
  rules/                        # per-rule tests
  integrations/                 # workflow/badge tests

Generate a local (runtime) README badge:

using DStyle

badge = DStyle.readme_badge(
    paths = ["src/YourPackageName.jl"],
    link = "https://github.com/you/YourPackageName/actions",
)
println(badge)

Setup GitHub Actions once (recommended):

using DStyle

# run from your repo root
setup = DStyle.setupgithub!()
println(setup.badge)

Features (& TODO)

Note: Passing examples could still fail due to other checks. It's not a style guide, the code inconsistency is for clarity.

• Adds a cool badge to your README.md with status
• Adds DStyle under [extras] and [targets].test
• Separate kernel functions (aka, function barriers) - via Julia Docs
• Indexing with indices obtained from length, size etc is discouraged (JuliaIndexFromLength) - via Julia Docs
• Modules and type names use capitalization and camel case - via Julia Docs
• Functions are lowercase and use squashed words when readable - via Julia Docs
• Constructor exemptions include macro structs and const type aliases
• Do not add new verbs that are simple aliases of existing verbs
• Run checks on external codebases by path
• Cross-codebase style validation skill
• Warn mode emits style findings without failing
• test_all reads each source file once
• ignore list for external constructors in test_all/test_codebase
• Core rules refactored to AST parsing
• Functions that return Bool use approved predicate prefixes - via Julia Docs
• No abbreviation in function names - via Julia Docs
• Functions mutating at least one argument end in ! - via Julia Docs
• Field names do not repeat the type name - via Julia Docs
• Break functions into multiple definitions - via Julia Docs

Documentation

The detailed rule examples and implementation notes now live in the docs site:

• Getting Started
• Checks and Examples
• CI and Badge Integration
• API Reference

Adds DStyle under extras and targets.test

Use install_test_dependency! when you want DStyle to be test-only in your package:

using DStyle

result = DStyle.install_test_dependency!(project_path = "Project.toml")
println(result.project_path)
println(result.added_to_extras)
println(result.added_to_test_target)

setupgithub!() runs this by default and returns the metadata in setup.test_dependency.

Constructor exemptions include macro structs and const type aliases

function_name_lowercase and mutating_function_bang now treat these as constructor names:

@kwdef mutable struct GPAgent
    active::Bool = false
end

const Orders{T} = Vector{T}

GPAgent(x) = x
Orders(x) = x

These constructor names are exempt from lowercase and mutating-! name checks.

Do not add new verbs that are simple aliases of existing verbs

The simple_verb_redefinition check flags short aliases that only rename an existing verb while forwarding arguments unchanged.

Fail:

record!(history::History, s::State) = push!(history, s)

Prefer:

push!(history, s)

Run checks on external codebases by path

Use test_codebase when you want to run DStyle against another repository directory:

using DStyle

violations = test_codebase(
    "/path/to/another-project";
    throw = false,
)

println(length(violations))

Cross-codebase style validation skill

The repository includes a reusable skill at:

skills/cross-codebase-style-validation/SKILL.md

It defines a before/after workflow to run tests on all configured codebases, validate findings, and triage true positives versus edge cases.

test_all reads each source file once

test_all now caches file contents before running checks so each file is read a single time per run:

violations = DStyle.test_all(
    paths = ["src/MyPkg.jl", "src/extra.jl"];
    throw = false,
)

ignore list for external constructors in test_all/test_codebase

Use ignore to silence known external constructor or integration names:

violations = DStyle.test_codebase(
    "/path/to/repo";
    throw = false,
    ignore = ["DataFrame", "DataFrames.DataFrame"],
)

The same ignore argument is accepted by test_all(...).

Core rules refactored to AST parsing

Core rule checks now parse Julia AST instead of relying on regex matching:

source = """
DataFrames.DataFrame(xs) = xs
"""

violations = DStyle.check_function_name_lowercase(
    source;
    ignore = ["DataFrame", "DataFrames.DataFrame"],
)

Warn mode emits style findings without failing

Use warn=true with throw=false to emit @warn messages and still get back the violation vector:

using DStyle

violations = test_all(
    paths = ["src/MyPkg.jl"];
    warn = true,
    throw = false,
)