feat: implement manifest parity with legacy JSON and fix nested collection

[sushant-suse]

Fixes: #183

Key Changes:

• Recursive Collection: Fixed a bug where metadata files (DC-*) were not collected from nested product subdirectories.
• Structural Parity: Updated the Manifest Pydantic model with hyphenated aliases (e.g., hide-productname) to align with existing portal expectations.
• Infrastructure: Added support for containerized DAPS execution, enabling development on macOS environments.
• Linguistic Drift Resolution: Implemented automated "parity fixes" to ensure consistency in HTML entities and instructional paragraphs across all translated descriptions.

Verification:

• Automated audit using DeepDiff confirms structural parity with legacy manifests.
• Passed all 660+ existing unit tests.
• Maintained 97.6% code coverage.
• Validated with ruff linting.

[github-actions]

Coverage Report

For commit 3deced6

Click to expand Coverage Report

  Name                                           Stmts   Miss Branch BrPart  Cover
  --------------------------------------------------------------------------------
+ src/docbuild/models/deliverable.py               180      1     22      0  99.5%
+ src/docbuild/cli/cmd_check/process.py             58      0     22      1  98.8%
+ src/docbuild/cli/cmd_cli.py                       93      1      8      1  98.0%
+ src/docbuild/utils/pidlock.py                     79      1     14      1  97.8%
+ src/docbuild/config/xml/stitch.py                 48      1     12      1  96.7%
+ src/docbuild/cli/cmd_validate/process.py         178      5     52      4  96.1%
+ src/docbuild/cli/callback.py                      35      0     10      2  95.6%
- src/docbuild/cli/cmd_config/__init__.py            9      1      0      0  88.9%
- src/docbuild/cli/cmd_metadata/metaprocess.py     209     22     66     13  83.6%
- src/docbuild/cli/cmd_check/__init__.py            18      5      2      0  65.0%
- src/docbuild/cli/cmd_build/__init__.py            13      5      0      0  61.5%
- src/docbuild/cli/cmd_metadata/__init__.py         27     10      2      0  58.6%
- src/docbuild/cli/cmd_config/environment.py        11      6      2      0  38.5%
  --------------------------------------------------------------------------------
+ TOTAL                                           2876     58    668     23  97.3%
  
  47 files skipped due to complete coverage.

[tomschr]

Thanks Sushant! 👍 Great work as always.

I've tried it with suse-ai/1.0/en-us as doctype and I get errors:

$ docbuild -vvv --env-config=env.devel.toml metadata 'suse-ai/1.0/en-us'
[...]
[2026-02-18 19:16:53] [ERROR] docbuild.cli.cmd_metadata.metaprocess: DAPS Error: ERROR: You either need to specify a DC-file or a MAIN file
[...]
Found 10 failed deliverables:
- suse-ai/1.0/main/en-us:DC-AI-intro
- suse-ai/1.0/main/en-us:DC-AI-requirements
- suse-ai/1.0/main/en-us:DC-AI-deployment
- suse-ai/1.0/main/en-us:DC-AI-deployment-airgapped
- suse-ai/1.0/main/en-us:DC-openwebui-using
- suse-ai/1.0/main/en-us:DC-AI-monitoring
- suse-ai/1.0/main/en-us:DC-openwebui-configuring
- suse-ai/1.0/main/en-us:DC-AI-preventing-hallucinations
- suse-ai/1.0/main/en-us:DC-AI-system-prompts
- suse-ai/1.0/main/en-us:DC-AI-data-integrity

I'm not sure what exactly caused it, but it's late and my brain is exhausted. 😆 So I leave that for another day, but I wanted to report it for you as soon as possible.

See my suggestions below. There is a related issue in regards of docker. You've practically worked on it already. 😄 Maybe we should discuss this personally how to proceed here.

[sushant-suse]

Thanks Sushant! 👍 Great work as always.

I've tried it with suse-ai/1.0/en-us as doctype and I get errors:

$ docbuild -vvv --env-config=env.devel.toml metadata 'suse-ai/1.0/en-us'
[...]
[2026-02-18 19:16:53] [ERROR] docbuild.cli.cmd_metadata.metaprocess: DAPS Error: ERROR: You either need to specify a DC-file or a MAIN file
[...]
Found 10 failed deliverables:
- suse-ai/1.0/main/en-us:DC-AI-intro
- suse-ai/1.0/main/en-us:DC-AI-requirements
- suse-ai/1.0/main/en-us:DC-AI-deployment
- suse-ai/1.0/main/en-us:DC-AI-deployment-airgapped
- suse-ai/1.0/main/en-us:DC-openwebui-using
- suse-ai/1.0/main/en-us:DC-AI-monitoring
- suse-ai/1.0/main/en-us:DC-openwebui-configuring
- suse-ai/1.0/main/en-us:DC-AI-preventing-hallucinations
- suse-ai/1.0/main/en-us:DC-AI-system-prompts
- suse-ai/1.0/main/en-us:DC-AI-data-integrity

I'm not sure what exactly caused it, but it's late and my brain is exhausted. 😆 So I leave that for another day, but I wanted to report it for you as soon as possible.

See my suggestions below. There is a related issue in regards of docker. You've practically worked on it already. 😄 Maybe we should discuss this personally how to proceed here.

Hi, I’ve investigated the DAPS error you encountered with suse-ai/1.0/en-us. The 'missing DC-file' error was caused by a path resolution issue within the temporary Git worktree.

I've updated the logic to pass an absolute path for the DC-file to the DAPS command. This ensures that even if DAPS is invoked from the worktree root, it can accurately locate the configuration file inside the product subdirectories. This should resolve the failures you saw with the suse-ai deliverables.

[sushant-suse]

Hi @tomschr, thanks for all your suggestions and ideas.

I have completed the refactoring based on your suggestions. All paths are now derived directly from the context object, and the function signatures have been simplified. To maintain a low complexity score (C901 < 10) and improve readability, I extracted the task execution logic into dedicated _run_tasks_fail_fast and _run_tasks_collect_all helpers. My local audit confirms 100% structural parity with the legacy files. The unit tests have also been updated to handle the new tuple[bool, Deliverable] return type, ensuring better failure traceability in the logs.

Can you please have a look at the changes?

[tomschr]

Thanks Sushant!

I see two discrepancies between manual and generated:

1. Unicode

   -          "title": "Melhores pr\u00e1ticas"
   +          "title": "Melhores práticas"

   This may be a small issue and could be fixed by using an encoding="utf-8" or something.

2. Missing dateModified and rank.

   Maybe that comes from our model that it doesn't serialize this correctly? For example, it happens when there seem to be no date available. In that case it should be dateModified: "". But that line is missing.
   Similar to rank.

[tomschr]

I have some minor suggestions for you. 😊

I think avoiding _ as a prefix in function names are better. We don't need to have them "private".

But overall, I really like the more modular approach. 👍

[tomschr]

Thank you! Two small issues, hopefully this is final. 😆

[sushant-suse]

Thank you! Two small issues, hopefully this is final. 😆

Done Toms, good catch as usual.
I hope it solves the issue.

[tomschr]

Thank you so much and sorry for the hassle.

🚢 it!