Authored living-doc input checked before merge and while typing

Open
  • Is something wrong?
#111 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
12/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions, python, typescript, vscode
Domain
ci-cd, developer-experience, devtools, tooling

Research direction

This is a multi-repository design epic with owner decisions still open (repository names, fail-or-warn per code, issue-body checking, language server scope, publisher), so start by reading the owner-call list rather than code. The relevant files are tests/examples/examples_check.py in living-doc, docs/reference/authoring-formats.md (§ Indentation, § Required fields), and living-doc-utilities docs/authoring/parsers.md, normalisation.md and errors.md. Done means the owner calls are answered and the first child issue for living-doc-check exists.

Written by the indexing model from the issue text.

Description

type:epic
Background

The parsers in living-doc-utilities are lenient by design: a line they cannot place becomes a warning
(MISINDENTED_LINE, UNPARSED_AC_LINE, UNPARSED_BULLET_LINE, MALFORMED_AC, …), not a failure. Those warnings
appear only in a collector run's output after the merge, where nobody reads them at PR time. The fixes normalize()
applies in memory (changes) never reach the author. The only strict check is living-doc's corpus checker
(tests/examples/examples_check.py), which runs over this repository's own examples and keeps its own lists of
required keys (REQUIRED_FEATURE_KEYS, REQUIRED_PO_KEYS_FULL, REQUIRED_PO_KEYS_XREF).

One known shape already needs a check above the parser. A PageObject comment opened by a bare /*, with its === rule
on the next line, comes back as MISSING_ENTITY_ID ("banner carries no title line") although it has a title. The
canon's § Indentation calls the title "the first line after the opening rule", which for that shape points at the line
the parser does not take.

Goals
  • One engine: a living-doc-check command in living-doc-utilities that runs normalize and the matching parser
    over given files and reports each warning with file, line and code. It fails on errors, on the codes the owner lists
    and on a missing required key, read from one table the corpus checker uses too.
  • Before merge: a GitHub Action, in a new repository, that runs the command over the living-doc input a pull
    request changes. It fails or warns per code and offers changes as suggested fixes. Issue bodies are checked by an
    issue-event workflow, since an issue edit is not in a PR.
  • While typing: a VS Code extension, in a new repository. It completes header templates from the canon, shows the
    same warnings as live diagnostics, and offers changes as quick fixes. It drives the author's own
    living-doc-utilities through a process or language server; it never reimplements the rules in TypeScript.
  • The three can never disagree, because they run one command.
Subtasks

In landing order. Owner calls come first: the two repository names, fail or warn per code, how issue bodies are
checked, a full language server or completion only, and who publishes the extension under AbsaOSS.

  • living-doc-utilities: the living-doc-check command and the required-keys table (tech-debt issue, a child).
  • living-doc: the corpus checker reads the required-keys table instead of its own lists.
  • living-doc canon: the bare /* PageObject shape converted or rejected above the parser, and § Indentation
    saying that the opening line carries the rule.
  • New repository: the pull-request check action, with the issue-event workflow; README, tests and the fleet's
    repository conventions.
  • New repository: the VS Code extension, published to the marketplace.
  • living-doc agentic layer: migrate_pageobject_headers.py accepts the settled shapes (tech-debt issue, a
    child), and the skills run their drafts through the command.
  • living-doc: a guide page, "Check your living-doc input", with the action's workflow and the extension.
Related / References
  • docs/reference/authoring-formats.md § Indentation and § Required fields; tests/examples/examples_check.py.
  • living-doc-utilities docs/authoring/parsers.md, docs/authoring/normalisation.md, docs/contracts/errors.md.
  • Related issues: the keyword name a tag carries is not checked (living-doc-utilities); a template repository for new
    living-doc-* repositories (living-doc).
Dominant language
Python
Stars
0
Forks
0
Avg merge
6h 14m
Merged PRs (30d)
27

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from AbsaOSS/living-doc

All issues in AbsaOSS/living-doc

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.