ubc¶

Tool: ubc TOOL_UBC

status: in_progress

style: blue_bar

part of: FE_UBC_LINTING, FE_UBC_FORMAT, FE_UBC_CACHE, FE_UBC_BUILD_JSON, FE_UBC_VALIDATE_JSON, FE_UBC_SCHEMA_VALIDATE, FE_UBC_DIFF_GIT, FE_UBC_AGENT_SKILL, FE_UBC_JSON_CROSSCHECK, UC_SW_REQ

Command-line tool for checking and formatting certain rules in sphinx and rst-based files.

Little brother of ubCode.

Commercial tool

Documentation:: https://ubcode.useblocks.com/ubc/introduction.html

Analysis¶

@startuml

' Nodes definition

file "<size:12>Artifact</size>\n**ubc needs.json**\n**file**\n<size:10>ART_UBC_NEEDS_JSON</size>" as ART_UBC_NEEDS_JSON [[../tools/ubc/artifacts.html#ART_UBC_NEEDS_JSON]] #LightBlue
rectangle "<size:12>Feature</size>\n**Check rst files**\n**for linting**\n**problems**\n<size:10>FE_UBC_LINTING</size>" as FE_UBC_LINTING [[../tools/ubc/features.html#FE_UBC_LINTING]] #Gold{
'child needs:
rectangle "<size:12>Fault</size>\n**Not covered**\n**format**\n<size:10>ER_UBC_LINTING_NOT_COVERED</size>" as ER_UBC_LINTING_NOT_COVERED [[../tools/ubc/features.html#ER_UBC_LINTING_NOT_COVERED]] #Pink
}
rectangle "<size:12>Feature</size>\n**Format rst**\n**files**\n<size:10>FE_UBC_FORMAT</size>" as FE_UBC_FORMAT [[../tools/ubc/features.html#FE_UBC_FORMAT]] #Gold{
'child needs:
rectangle "<size:12>Fault</size>\n**Format**\n**introduces**\n**errors**\n<size:10>ER_UBC_FORMAT_ERRORS</size>" as ER_UBC_FORMAT_ERRORS [[../tools/ubc/features.html#ER_UBC_FORMAT_ERRORS]] #Pink
}
rectangle "<size:12>Feature</size>\n**Clean internal**\n**caches**\n<size:10>FE_UBC_CACHE</size>" as FE_UBC_CACHE [[../tools/ubc/features.html#FE_UBC_CACHE]] #Gold
rectangle "<size:12>Feature</size>\n**Build**\n**needs.json**\n<size:10>FE_UBC_BUILD_JSON</size>" as FE_UBC_BUILD_JSON [[../tools/ubc/features.html#FE_UBC_BUILD_JSON]] #Gold{
'child needs:
rectangle "<size:12>Fault</size>\n**Incomplete data**\n<size:10>ER_UBC_JSON_INCOMPLETE</size>" as ER_UBC_JSON_INCOMPLETE [[../tools/ubc/features.html#ER_UBC_JSON_INCOMPLETE]] #Pink
}
rectangle "<size:12>Feature</size>\n**Validate**\n**needs.json**\n<size:10>FE_UBC_VALIDATE_JSON</size>" as FE_UBC_VALIDATE_JSON [[../tools/ubc/features.html#FE_UBC_VALIDATE_JSON]] #Gold{
'child needs:
rectangle "<size:12>Fault</size>\n**Unknown file**\n**format**\n<size:10>ER_UBC_VAL_FORMAT</size>" as ER_UBC_VAL_FORMAT [[../tools/ubc/features.html#ER_UBC_VAL_FORMAT]] #Pink
rectangle "<size:12>Fault</size>\n**Incomplete**\n**Validation**\n<size:10>ER_UBC_VAL_INCOMPLETE</size>" as ER_UBC_VAL_INCOMPLETE [[../tools/ubc/features.html#ER_UBC_VAL_INCOMPLETE]] #Pink
}
rectangle "<size:12>Feature</size>\n**Validate**\n**ontology schema**\n**(``ubc schema**\n**validate``)**\n<size:10>FE_UBC_SCHEMA_VALIDATE</size>" as FE_UBC_SCHEMA_VALIDATE [[../tools/ubc/features.html#FE_UBC_SCHEMA_VALIDATE]] #Gold{
'child needs:
rectangle "<size:12>Fault</size>\n**Schema rules**\n**not loaded**\n<size:10>ER_UBC_SCHEMA_NO_RULES</size>" as ER_UBC_SCHEMA_NO_RULES [[../tools/ubc/features.html#ER_UBC_SCHEMA_NO_RULES]] #Pink
rectangle "<size:12>Fault</size>\n**Schema rule set**\n**diverges from**\n**Sphinx-Needs**\n<size:10>ER_UBC_SCHEMA_DIVERGE</size>" as ER_UBC_SCHEMA_DIVERGE [[../tools/ubc/features.html#ER_UBC_SCHEMA_DIVERGE]] #Pink
rectangle "<size:12>Fault</size>\n**Safety**\n**violation**\n**reported only**\n**as warning**\n<size:10>ER_UBC_SCHEMA_EXIT_ZERO</size>" as ER_UBC_SCHEMA_EXIT_ZERO [[../tools/ubc/features.html#ER_UBC_SCHEMA_EXIT_ZERO]] #Pink
}
rectangle "<size:12>Feature</size>\n**Impact analysis**\n**on git changes**\n**(``ubc diff**\n**git``)**\n<size:10>FE_UBC_DIFF_GIT</size>" as FE_UBC_DIFF_GIT [[../tools/ubc/features.html#FE_UBC_DIFF_GIT]] #Gold{
'child needs:
rectangle "<size:12>Fault</size>\n**Impact depth**\n**truncates the**\n**graph**\n<size:10>ER_UBC_DIFF_DEPTH_CUT</size>" as ER_UBC_DIFF_DEPTH_CUT [[../tools/ubc/features.html#ER_UBC_DIFF_DEPTH_CUT]] #Pink
rectangle "<size:12>Fault</size>\n**Wrong direction**\n**omits incoming**\n**impact**\n<size:10>ER_UBC_DIFF_DIR_WRONG</size>" as ER_UBC_DIFF_DIR_WRONG [[../tools/ubc/features.html#ER_UBC_DIFF_DIR_WRONG]] #Pink
rectangle "<size:12>Fault</size>\n**Uncommitted**\n**local edits not**\n**covered**\n<size:10>ER_UBC_DIFF_DIRTY</size>" as ER_UBC_DIFF_DIRTY [[../tools/ubc/features.html#ER_UBC_DIFF_DIRTY]] #Pink
}
rectangle "<size:12>Feature</size>\n**Generate AI-**\n**agent skill for**\n**the project**\n**(``ubc agent-**\n**skill``)**\n<size:10>FE_UBC_AGENT_SKILL</size>" as FE_UBC_AGENT_SKILL [[../tools/ubc/features.html#FE_UBC_AGENT_SKILL]] #Gold{
'child needs:
rectangle "<size:12>Fault</size>\n**Skill out of**\n**sync with**\n**qualified**\n**configuration**\n<size:10>ER_UBC_AGENT_SKILL_STALE</size>" as ER_UBC_AGENT_SKILL_STALE [[../tools/ubc/features.html#ER_UBC_AGENT_SKILL_STALE]] #Pink
}
rectangle "<size:12>Feature</size>\n**Cross-check**\n**needs.json**\n**against an**\n**independent**\n**index (``ubc**\n**diff json``)**\n<size:10>FE_UBC_JSON_CROSSCHECK</size>" as FE_UBC_JSON_CROSSCHECK [[../tools/ubc/features.html#FE_UBC_JSON_CROSSCHECK]] #Gold{
'child needs:
rectangle "<size:12>Fault</size>\n**Divergence not**\n**detected (false**\n**negative)**\n<size:10>ER_UBC_CROSSCHECK_FALSE_NEG</size>" as ER_UBC_CROSSCHECK_FALSE_NEG [[../tools/ubc/features.html#ER_UBC_CROSSCHECK_FALSE_NEG]] #Pink
}
node "<size:12>Tool</size>\n**ubc**\n<size:10>TOOL_UBC</size>" as TOOL_UBC [[../tools/ubc/index.html#TOOL_UBC]] #0fbcf9
rectangle "<size:12>Restriction</size>\n**Do not use**\n**dynamic**\n**functions**\n<size:10>CHECK_UBC_NO_DYN</size>" as CHECK_UBC_NO_DYN [[../tools/ubc/restrictions.html#CHECK_UBC_NO_DYN]] #Orange
rectangle "<size:12>Restriction</size>\n**Do not use**\n**list2needs**\n<size:10>CHECK_UBC_NO_LIST2NEEDS</size>" as CHECK_UBC_NO_LIST2NEEDS [[../tools/ubc/restrictions.html#CHECK_UBC_NO_LIST2NEEDS]] #Orange
rectangle "<size:12>Restriction</size>\n**Do not**\n**use/reference**\n**rst files**\n**outside the**\n**ubproject**\n**workspace/scope**\n<size:10>CHECK_UBC_RST_WORKSPACE</size>" as CHECK_UBC_RST_WORKSPACE [[../tools/ubc/restrictions.html#CHECK_UBC_RST_WORKSPACE]] #Orange
rectangle "<size:12>Restriction</size>\n**Run needs.json**\n**cross-check in**\n**CI and fail on**\n**any diff**\n<size:10>RE_UBC_CROSSCHECK_CI</size>" as RE_UBC_CROSSCHECK_CI [[../tools/ubc/restrictions.html#RE_UBC_CROSSCHECK_CI]] #Orange
rectangle "<size:12>Restriction</size>\n**Run ``ubc**\n**format`` in**\n**check mode only**\n**in CI**\n<size:10>RE_UBC_FORMAT_CHECK_ONLY</size>" as RE_UBC_FORMAT_CHECK_ONLY [[../tools/ubc/restrictions.html#RE_UBC_FORMAT_CHECK_ONLY]] #Orange
rectangle "<size:12>Restriction</size>\n**Pin ``ubc`` and**\n**``sphinx-**\n**needs`` to**\n**compatible**\n**releases**\n<size:10>RE_UBC_VERSION_PIN</size>" as RE_UBC_VERSION_PIN [[../tools/ubc/restrictions.html#RE_UBC_VERSION_PIN]] #Orange
rectangle "<size:12>Restriction</size>\n**Schema**\n**violations must**\n**cause a non-**\n**zero exit code**\n<size:10>RE_UBC_SCHEMA_SEVERITY_ERROR</size>" as RE_UBC_SCHEMA_SEVERITY_ERROR [[../tools/ubc/restrictions.html#RE_UBC_SCHEMA_SEVERITY_ERROR]] #Orange
rectangle "<size:12>Restriction</size>\n**Run ``ubc diff**\n**git`` with**\n**sufficient**\n**impact depth**\n<size:10>RE_UBC_DIFF_MIN_DEPTH</size>" as RE_UBC_DIFF_MIN_DEPTH [[../tools/ubc/restrictions.html#RE_UBC_DIFF_MIN_DEPTH]] #Orange
rectangle "<size:12>Restriction</size>\n**Run ``ubc diff**\n**git`` with**\n**``--impact-**\n**direction**\n**both``**\n<size:10>RE_UBC_DIFF_DIRECTION_BOTH</size>" as RE_UBC_DIFF_DIRECTION_BOTH [[../tools/ubc/restrictions.html#RE_UBC_DIFF_DIRECTION_BOTH]] #Orange

' Connection definition

FE_UBC_LINTING -[#333333]-> TOOL_UBC
FE_UBC_FORMAT -[#333333]-> TOOL_UBC
FE_UBC_CACHE -[#333333]-> TOOL_UBC
FE_UBC_BUILD_JSON -[thickness=1,#0000AA]-> ART_UBC_NEEDS_JSON
FE_UBC_BUILD_JSON -[#333333]-> TOOL_UBC
FE_UBC_VALIDATE_JSON <-[thickness=1,#00AA00]- ART_UBC_NEEDS_JSON
FE_UBC_VALIDATE_JSON -[#333333]-> TOOL_UBC
FE_UBC_SCHEMA_VALIDATE <-[thickness=1,#00AA00]- ART_UBC_NEEDS_JSON
FE_UBC_SCHEMA_VALIDATE -[#333333]-> TOOL_UBC
FE_UBC_DIFF_GIT -[#333333]-> TOOL_UBC
FE_UBC_AGENT_SKILL -[thickness=1,#0000AA]-> ART_UBC_NEEDS_JSON
FE_UBC_AGENT_SKILL -[#333333]-> TOOL_UBC
FE_UBC_JSON_CROSSCHECK <-[thickness=1,#00AA00]- ART_UBC_NEEDS_JSON
FE_UBC_JSON_CROSSCHECK -[#333333]-> TOOL_UBC
CHECK_UBC_NO_DYN -[#FA8072]-> ER_UBC_JSON_INCOMPLETE
CHECK_UBC_NO_LIST2NEEDS -[#FA8072]-> ER_UBC_JSON_INCOMPLETE
CHECK_UBC_RST_WORKSPACE -[#FA8072]-> ER_UBC_JSON_INCOMPLETE
RE_UBC_CROSSCHECK_CI -[#FA8072]-> ER_UBC_CROSSCHECK_FALSE_NEG
RE_UBC_FORMAT_CHECK_ONLY -[#FA8072]-> ER_UBC_FORMAT_ERRORS
RE_UBC_VERSION_PIN -[#FA8072]-> ER_UBC_SCHEMA_DIVERGE
RE_UBC_SCHEMA_SEVERITY_ERROR -[#FA8072]-> ER_UBC_SCHEMA_EXIT_ZERO
RE_UBC_DIFF_MIN_DEPTH -[#FA8072]-> ER_UBC_DIFF_DEPTH_CUT
RE_UBC_DIFF_DIRECTION_BOTH -[#FA8072]-> ER_UBC_DIFF_DIR_WRONG

@enduml

ID	Title	Type
ART_UBC_NEEDS_JSON	ubc needs.json file	artifact
CHECK_UBC_NO_DYN	Do not use dynamic functions	restriction
CHECK_UBC_NO_LIST2NEEDS	Do not use list2needs	restriction
CHECK_UBC_RST_WORKSPACE	Do not use/reference rst files outside the ubproject workspace/scope	restriction
ER_UBC_AGENT_SKILL_STALE	Skill out of sync with qualified configuration	fault
ER_UBC_CROSSCHECK_FALSE_NEG	Divergence not detected (false negative)	fault
ER_UBC_DIFF_DEPTH_CUT	Impact depth truncates the graph	fault
ER_UBC_DIFF_DIR_WRONG	Wrong direction omits incoming impact	fault
ER_UBC_DIFF_DIRTY	Uncommitted local edits not covered	fault
ER_UBC_FORMAT_ERRORS	Format introduces errors	fault
ER_UBC_JSON_INCOMPLETE	Incomplete data	fault
ER_UBC_LINTING_NOT_COVERED	Not covered format	fault
ER_UBC_SCHEMA_DIVERGE	Schema rule set diverges from Sphinx-Needs	fault
ER_UBC_SCHEMA_EXIT_ZERO	Safety violation reported only as warning	fault
ER_UBC_SCHEMA_NO_RULES	Schema rules not loaded	fault
ER_UBC_VAL_FORMAT	Unknown file format	fault
ER_UBC_VAL_INCOMPLETE	Incomplete Validation	fault
FE_UBC_AGENT_SKILL	Generate AI-agent skill for the project (``ubc agent-skill``)	feature
FE_UBC_BUILD_JSON	Build needs.json	feature
FE_UBC_CACHE	Clean internal caches	feature
FE_UBC_DIFF_GIT	Impact analysis on git changes (``ubc diff git``)	feature
FE_UBC_FORMAT	Format rst files	feature
FE_UBC_JSON_CROSSCHECK	Cross-check needs.json against an independent index (``ubc diff json``)	feature
FE_UBC_LINTING	Check rst files for linting problems	feature
FE_UBC_SCHEMA_VALIDATE	Validate ontology schema (``ubc schema validate``)	feature
FE_UBC_VALIDATE_JSON	Validate needs.json	feature
RE_UBC_CROSSCHECK_CI	Run needs.json cross-check in CI and fail on any diff	restriction
RE_UBC_DIFF_DIRECTION_BOTH	Run ``ubc diff git`` with ``--impact-direction both``	restriction
RE_UBC_DIFF_MIN_DEPTH	Run ``ubc diff git`` with sufficient impact depth	restriction
RE_UBC_FORMAT_CHECK_ONLY	Run ``ubc format`` in check mode only in CI	restriction
RE_UBC_SCHEMA_SEVERITY_ERROR	Schema violations must cause a non-zero exit code	restriction
RE_UBC_VERSION_PIN	Pin ``ubc`` and ``sphinx-needs`` to compatible releases	restriction
TOOL_UBC	ubc	tool