Skip to content

convert --strict ignores Asciidoctor errors: the playbook's failure_level never takes effect #1044

Description

@amondnet

Problem

convert.ts --strict ignores Asciidoctor errors, so a page with an unresolved include is published with a literal "Unresolved include directive" line and the build still exits 0.

buildPlaybookYaml in scripts/convert.ts writes this block:

runtime:
  log:
    level: warn
    failure_level: error

Nothing applies it. The pipeline drives Antora as a library (ADR-0002) and never runs the site generator, which is what calls @antora/logger's configure() and finalize(). Every conversion log therefore starts with:

WARN: logger not configured; creating logger with default settings

The default failureLevel is silent, so failOnExit is never set. --strict only gates on the converter's own warnings (convertDocument(...).warnings).

Evidence

data-relational-3.2.9 is published with this defect:

ERROR (asciidoctor): target of include not found: 3.2.9@data-commons::page$value-expressions.adoc

markdown/data-relational/3.2.9/value-expressions.md has title: "" and the unresolved-include line. The mistake is upstream's, and 3.2.10 removes the include. The pipeline still published the page without complaint.

Other known ERROR-level log lines from the #717 verification run:

  • data-redis 3.2.0–3.2.8 and 3.3.0–3.3.2: dropping cells from incomplete row detected end of table at redis-repositories/cluster.adoc:16, an upstream table that later tags fix.

Proposal

In convert.ts, configure the logger from the playbook before aggregating content:

configureLogger({ level: 'warn', failureLevel: 'error' })

After conversion, fail when --strict is set and await finalizeLogger() returns true. failure_level in the generated playbook then means what it says.

Open question: the blast radius

Some published versions log ERROR today, so turning this on would make a re-run of their tags fail. Before merging, scan the conversion logs of every catalogued version and decide per case:

  • fail, and exclude the version, as with data-relational-3.2.9; or
  • tolerate a known upstream error with a per-version allowlist, as with the Redis tables, whose content still renders; or
  • gate only on target of include not found, the one class that loses content.

Acceptance

  • --strict exits 1 on an unresolved include, with the ERROR line in the output.
  • The scan of existing versions is recorded, along with the decision for each version that fails.
  • There is a unit or integration test with a fixture page whose include target is missing.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    type:bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions