justfile

# Citum Project justfile
# See https://github.com/casey/just for documentation

# Default recipe: run the pre-commit gate
default: pre-commit

# Run the pre-commit gate (formatting check, clippy warnings as errors, and tests)
pre-commit:
    ./scripts/dev-env.sh cargo fmt --check
    ./scripts/dev-env.sh cargo clippy --all-targets --all-features -- -D warnings
    ./scripts/dev-env.sh cargo nextest run

# Run all tests via nextest
test:
    ./scripts/dev-env.sh cargo nextest run

# Validate tracked styles and locales against the published JSON schemas
schema-validate:
    node scripts/validate-schemas.js --scope=styles,locales

# Regenerate schemas when crates/citum-cli or schema crates change
schema-gen:
    ./scripts/dev-env.sh cargo run --bin citum --features schema -- schema --out-dir docs/schemas
    node scripts/build-data-model-reference.js
    git add docs/schemas/ docs/reference/

# Bootstrap the development environment (setup can be 'minimal' or 'full')
bootstrap setup="minimal":
    ./scripts/bootstrap.sh {{setup}}

# Build nodejs-target WASM bindings for local tooling (e.g. scripts/benchmark-wasm-workflow.js)
build-wasm-nodejs:
    wasm-pack build crates/citum-bindings --target nodejs --features full-wasm

# Regenerate docs/demo.html from docs/demo.djot (optionally override style)
demo style="styles/embedded/chicago-author-date-18th.yaml":
    ./scripts/build-demo.sh {{style}}

# Render bibliography references using a style
render-refs style="styles/embedded/apa-7th.yaml" refs="tests/fixtures/references-expanded.json":
    ./scripts/dev-env.sh cargo run --bin citum -- render refs -s {{style}} -b {{refs}}

# Validate a style YAML and reference library file
check-style style="styles/embedded/apa-7th.yaml" refs="tests/fixtures/references-expanded.json":
    ./scripts/dev-env.sh cargo run --bin citum -- check -s {{style}} -b {{refs}}

# Validate all production styles in the repository
validate-production-styles:
    ./scripts/validate-production-styles.sh

# Convert a bibliography reference library to another format (e.g. ris, csl-json)
convert-refs input output:
    ./scripts/dev-env.sh cargo run --bin citum -- convert refs {{input}} --output {{output}}

# Run the local oracle comparison for a specific style (e.g. styles-legacy/apa.csl)
oracle style:
    node scripts/oracle.js {{style}}

# Run the oracle + batch-impact workflow test on a legacy CSL file (e.g. styles-legacy/apa.csl)
workflow-test csl:
    ./scripts/workflow-test.sh {{csl}}

# Generate a core rendering report and validate it against baseline quality gates: fails if any
# gated style's fidelity drops below 1.0, or if any embedded-core style's exact-parity `passed`
# count drops below its recorded floor (see docs/architecture/audits/2026-07-31_EXACT_PARITY_REFOCUS.md).
check-core-quality:
    node scripts/report-core.js --all-features > /tmp/r.json
    node scripts/check-core-quality.js --report /tmp/r.json \
        --baseline scripts/report-data/core-quality-baseline.json \
        --parity-baseline scripts/report-data/embedded-parity-baseline.json \
        --parity-adjudication scripts/report-data/parity-adjudication.json

# Validate schemas, hashes, partitions, and byte-for-byte freshness for explicitly registered audits
check-style-coverage-audits:
    node scripts/check-style-coverage-audits.js

# Refresh the Top-10 oracle aggregate baseline: writes
# scripts/report-data/oracle-top10-baseline.json (previously this recipe never passed --save,
# so it measured but never refreshed anything). Reuses the style list already pinned in the
# baseline's own metadata.styles rather than --top 10, so the refreshed file stays in sync with
# the exact style set check-oracle-regression.js verifies against.
oracle-refresh:
    node scripts/oracle-batch-aggregate.js styles-legacy/ \
        --styles "$(node -e "process.stdout.write(require('./scripts/report-data/oracle-top10-baseline.json').metadata.styles.join(','))")" \
        --save scripts/report-data/oracle-top10-baseline.json

# Regenerate every artifact a tests/fixtures/ change invalidates (see
# docs/architecture/audits/2026-08-16_FIXTURE_CHANGE_FAN_OUT.md): oracle snapshots and
# registered coverage-audit manifests always; the two ratcheted CI-floor baselines
# (embedded-parity-baseline.json, oracle-top10-baseline.json) only when baselines=yes, since
# baselines/README.md restricts those refreshes to dedicated, reviewed baseline PRs. Concurrency
# defaults low — corpus-wide sweeps at default concurrency have crashed lower-memory machines.
# oracle-snapshot.js currently exits non-zero on 2 pre-existing, tracked-elsewhere failures
# (csl26-u87d); that's allowed to fail this line without aborting the rest of the fan-out, since
# neither failing style appears in any gated baseline below.
fixture-refresh baselines="no":
    node scripts/oracle-snapshot.js --all --concurrency 2 \
        || echo "warning: oracle-snapshot.js reported failures -- see csl26-u87d" >&2
    node scripts/refresh-style-coverage-audits.js
    if [ "{{baselines}}" = "yes" ]; then \
        node scripts/report-core.js --all-features > /tmp/fixture-refresh-report.json && \
        node scripts/derive-parity-baseline.js \
            --report /tmp/fixture-refresh-report.json \
            --out scripts/report-data/embedded-parity-baseline.json && \
        just oracle-refresh; \
    fi
    just check-core-quality
    node scripts/check-oracle-regression.js --baseline scripts/report-data/oracle-top10-baseline.json
    just check-style-coverage-audits

# Discover recurring per-concern config shapes across the legacy CSL corpus that no named
# preset covers (contributors, dates, titles, locators) — a worklist for citum-schema-style presets.
analyze-presets styles="styles-legacy":
    ./scripts/dev-env.sh cargo run --quiet --bin citum-analyze -- {{styles}} --config-presets --json \
        | jq '.concerns[] | {concern, matched_style_count, unmatched_style_count, \
              candidate_count: (.candidates|length), candidates: .candidates[:5]}'

# Validate YAML frontmatter for local contributor AI skills and commands
validate-frontmatter flags='--copilot-strict':
    ./scripts/validate-frontmatter.sh {{flags}}