whykit 0.3.1__py3-none-any.whl

whykit/rules.py

@@ -0,0 +1,274 @@
+"""Stable public catalog for WhyKit lint rule codes."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict, dataclass, replace
+from typing import Any
+
+from .console import emit_machine
+
+from .contract import CONTRACT_VERSION, emit_error
+
+
+@dataclass(frozen=True)
+class Rule:
+    code: str
+    default_level: str
+    summary: str
+    why: str
+    fix: str
+    # Security-relevant rules cannot be lowered or switched off in
+    # whykit.toml without a written reason, and every such override is
+    # reported with the lint and check output.
+    security: bool = False
+
+
+_RULES = (
+    Rule("agents.absent", "warning", "No AGENTS.md contract is present.", "Agents otherwise invent operating rules from context.", "Add AGENTS.md and state what agents may read, write, commit and escalate."),
+    Rule("agents.unconfigured", "warning", "AGENTS.md still contains an unanswered TODO.", "A placeholder contract looks authoritative while leaving a material choice undefined.", "Replace every contract TODO with an explicit operating rule."),
+    Rule("canonical.owner", "warning", "A canonical document has no real owner.", "A source of truth without ownership has no accountable reviewer.", "Set owner to a person or accountable role."),
+    Rule("canonical.unapproved", "error", "A draft or review document is marked source_of_truth.", "Unapproved material must not silently become canonical.", "Set source_of_truth: false until status is approved."),
+    Rule("date.filename_mismatch", "warning", "A dated filename and created date disagree.", "Point-in-time artifacts become hard to order and audit.", "Align the filename date with created, or correct the metadata."),
+    Rule("date.invalid", "error", "created or last_updated is not a real ISO date.", "Invalid dates break deterministic review and timeline logic.", "Use a real YYYY-MM-DD date."),
+    Rule("date.order", "error", "last_updated is earlier than created.", "The lifecycle metadata is internally contradictory.", "Correct one of the dates."),
+    Rule("date.placeholder", "error", "A non-template document still uses YYYY-MM-DD.", "A placeholder date is indistinguishable from missing lifecycle data.", "Replace it with the real date."),
+    Rule("decision.duplicate", "error", "A decision ID is reused.", "D-NNN identifiers are stable references and must be unique forever.", "Allocate a new decision ID; never recycle an old one."),
+    Rule("decision.id_filename", "error", "decision_id and filename number disagree.", "Humans and tools use both forms as identifiers.", "Rename the file or correct decision_id so they match."),
+    Rule("decision.id_missing", "error", "A decision record has no D-NNN identifier.", "Without an ID, citations and supersession cannot be stable.", "Add decision_id and a matching d-NNN-*.md filename."),
+    Rule("decision.placeholder", "warning", "A draft, in-review or approved decision record still holds template placeholder text.", "A record that still says \"State the choice in one sentence.\" passes every other shape check while recording no decision.", "Replace the prompt with the real context, decision and rationale, fill the alternatives table or say there was one option, and list the consequences."),
+    Rule("decision.review_missing", "warning", "An approved decision has no review_by date.", "Accepted decisions otherwise look current forever as assumptions change.", "Set a realistic review_by date."),
+    Rule("decision.unreviewed", "warning", "An approved decision's provenance denies human review.", "Approval contradicts the record's own declared review state.", "Keep the record draft or in_review until an authorized person reviews it; changing a boolean is not authentication."),
+    Rule("decision.superseded_by_missing", "warning", "A superseded decision has no newer record pointing back to it.", "The chain of reasoning is incomplete.", "Create or fix the newer decision's supersedes field."),
+    Rule("decision.superseded_by_format", "warning", "superseded_by is not a D-NNN identifier.", "Lifecycle metadata should point to the same stable decision namespace as supersedes.", "Use a D-NNN identifier or remove the convenience field."),
+    Rule("decision.superseded_by_mismatch", "warning", "superseded_by disagrees with the approved reverse supersedes edge.", "Two replacement pointers make the decision lineage ambiguous.", "Align superseded_by with the approved record whose supersedes field points here."),
+    Rule("decision.supersedes_format", "error", "supersedes is not a D-NNN identifier.", "Supersession must point to a stable decision ID.", "Use a value such as D-012."),
+    Rule("decision.supersedes_missing", "error", "supersedes points to a decision record that does not exist.", "A missing predecessor breaks decision history.", "Restore the record or correct the referenced ID."),
+    Rule("decision.supersedes_status", "warning", "A newer decision supersedes an older record not marked superseded.", "The two records disagree about which decision is current.", "Mark the older record superseded after the replacement is accepted."),
+    Rule("decision.supersession_fork", "error", "One decision has multiple approved replacements.", "Two accepted successors make the current decision lineage ambiguous.", "Resolve the conflict so only one approved decision supersedes the predecessor; preserve rejected alternatives as non-approved records."),
+    Rule("decision.supersession_cycle", "error", "The supersedes relation contains a cycle.", "A decision cannot ultimately supersede itself; cyclic lineage makes historical/current state impossible to resolve.", "Break the cycle and restore an acyclic predecessor chain."),
+    Rule("decision_log.ambiguous", "error", "A decision-log wikilink resolves to multiple records.", "The index must identify one decision record deterministically.", "Use the full vault-relative path in the wikilink."),
+    Rule("decision_log.date_mismatch", "warning", "Decision log date differs from record created date.", "Two timelines for one decision are confusing and hard to audit.", "Align the row date and record metadata."),
+    Rule("decision_log.duplicate", "error", "A D-NNN appears more than once in the decision log.", "The log must be a unique index.", "Keep one row and preserve history in the decision record."),
+    Rule("decision_log.id_mismatch", "error", "A log row points to a record with another decision_id.", "The index would direct readers to the wrong rationale.", "Fix the row ID or record link."),
+    Rule("decision_log.missing_record", "error", "A decision-log row points to a missing note.", "Indexed decisions must remain inspectable.", "Restore the record or repair the wikilink."),
+    Rule("decision_log.record", "error", "A populated decision row has no record wikilink.", "The log cannot substitute for the rationale itself.", "Link the row to its d-NNN-*.md record."),
+    Rule("decision_log.status_mismatch", "error", "Log status and record status disagree.", "Readers cannot tell which lifecycle state is authoritative.", "Update the log row to match the record."),
+    Rule("decision_log.unindexed", "error", "A decision record is missing from decision-log.md.", "Unindexed decisions disappear from the operating memory.", "Add one decision-log row for the record."),
+    Rule("config.invalid", "error", "whykit.toml is invalid.", "A repository-local policy must parse identically for humans, CI and agents.", "Fix the TOML structure or unsupported policy values."),
+    Rule("delivery_status.invalid", "error", "delivery_status has an unsupported value.", "Downstream systems need a small stable delivery state machine.", "Use draft, ready_to_send or sent."),
+    Rule("delivery_status.sent_at", "error", "A sent document has no sent_at timestamp/date field.", "Delivery history must distinguish drafted content from delivered content.", "Record sent_at when setting delivery_status: sent."),
+    Rule("evidence.date", "error", "An evidence date or accessed date is invalid.", "Freshness cannot be reasoned about without valid dates.", "Use real YYYY-MM-DD dates."),
+    Rule("evidence.sensitivity", "warning", "An explicit evidence Sensitivity cell is empty or invalid.", "Filtered readers cannot safely classify the row.", "Use public, internal, confidential or restricted; omit the column only for legacy inheritance."),
+    Rule("evidence.access_missing", "warning", "An active source covered by an access-age policy has no Accessed date.", "The policy cannot tell whether this source was revisited.", "Record when the source was last accessed, or remove the policy for historical source types."),
+    Rule("evidence.access_future", "warning", "An active source has an Accessed date after the lint date.", "A future date cannot establish that a source has already been checked.", "Correct the Accessed date or run lint with the intended --today date."),
+    Rule("evidence.access_stale", "warning", "An active source has not been accessed within its configured age window.", "Mutable sources may have changed since the last check.", "Revisit the source and update Accessed after review; do not treat access alone as claim approval."),
+    Rule("evidence.duplicate", "error", "An E-NNN identifier is reused.", "Evidence IDs are durable citations and cannot safely refer to two sources.", "Allocate a new E-NNN."),
+    Rule("evidence.id_format", "error", "source_ids contains a malformed evidence ID.", "Machine resolution relies on the E-NNN contract.", "Use E- followed by at least three digits."),
+    Rule("embed.missing", "error", "An Obsidian embed target cannot be resolved.", "Broken embeds render as missing media and hide the intended note.", "Fix the ![[target]] path or restore the note."),
+    Rule("hub.unlinked_workstream", "warning", "Home.md does not link into a top-level working directory.", "The map of content should reach every workstream folder so agents and people can navigate.", "Add a wikilink from Home.md into the folder, or remove an unused directory."),
+    Rule("evidence.missing", "error", "A cited E-NNN has no populated active or retired row.", "A citation without a source location is not auditable evidence.", "Populate the register row or correct the citation."),
+    Rule("evidence.replaced_by_format", "error", "A retired source has a malformed replacement ID.", "Replacement chains must use stable evidence identifiers.", "Use a valid E-NNN or leave the field empty."),
+    Rule("evidence.replaced_by_missing", "error", "A retired source points to an unknown replacement.", "The provenance chain ends at a dangling identifier.", "Register the replacement source or correct the ID."),
+    Rule("evidence.retired", "warning", "A document cites retired evidence.", "Historical citations may be valid, but current claims may need re-checking. Superseded and archived records are history and are not flagged.", "Review the claim and cite the replacement where appropriate."),
+    Rule("evidence.retired_date", "error", "A retired evidence row has an invalid retirement date.", "Retirement history must be chronologically auditable.", "Use a real YYYY-MM-DD date."),
+    Rule("fact.inline_evidence", "warning", "A fact callout has no inline E-NNN citation.", "Fact callouts visually claim verification, so the supporting source should be one click away.", "Add an E-NNN in the callout."),
+    Rule("fact.evidence_missing", "warning", "A fact callout cites an E-NNN with no populated register row.", "A citation that resolves nowhere looks verified while pointing at nothing.", "Register the source or correct the cited ID."),
+    Rule("frontmatter.invalid", "error", "YAML front matter cannot be parsed.", "Governance metadata is unavailable when parsing fails.", "Fix the front matter syntax."),
+    Rule("frontmatter.empty", "warning", "A required metadata key is present but has no value.", "An empty key passes the presence check while every value check skips it.", "Fill in the value, or use the documented placeholder in templates."),
+    Rule("frontmatter.missing", "error", "A governed note has no YAML front matter.", "Status, owner, sensitivity and provenance would be undefined.", "Add the standard WhyKit front matter block."),
+    Rule("frontmatter.required", "error", "A required metadata key is missing.", "Core lifecycle and handling fields must be explicit.", "Add the named key."),
+    Rule("markdown_link.missing", "warning", "A relative Markdown link or image points to a missing local file.", "WhyKit is editor-agnostic, so standard Markdown navigation should be as auditable as wikilinks.", "Fix the relative path or remove the stale link."),
+    Rule("markdown_link.outside", "warning", "A relative Markdown link or image resolves outside the vault.", "The governed knowledge graph should not silently depend on untracked local files.", "Keep the asset/note inside the vault or use an explicit external URL/evidence location."),
+    Rule("note.orphan", "warning", "Nothing in the vault links to this note.", "Unreachable notes become invisible operationally even though the file still exists.", "Link it from Home.md or a workstream map."),
+    Rule("review_log.date", "error", "A review-log row has an invalid date.", "Review history needs an auditable timeline.", "Use a real YYYY-MM-DD date."),
+    Rule("review_log.next_review", "error", "A review-log row has an invalid next-review date.", "Review scheduling cannot act on an invalid date.", "Use YYYY-MM-DD or an em dash when no next review applies."),
+    Rule("review_log.outcome", "error", "A review-log row has an unsupported outcome.", "Automation depends on a stable review outcome vocabulary.", "Use confirmed, update-required, supersede-required or archived."),
+    Rule("review_log.reviewer", "error", "A review-log row has no real reviewer.", "A review without accountable ownership is not an auditable review.", "Name the person or team that performed the review."),
+    Rule("review_log.row", "error", "A review-log row is malformed.", "Malformed review history cannot be parsed reliably.", "Restore all seven review-log columns."),
+    Rule("review_log.table", "error", "The review-log table is missing or malformed.", "Review events need one deterministic append-only structure.", "Restore the standard review-log table header."),
+    Rule("review_log.target", "error", "A review-log target is missing or ambiguous.", "A review event must point to one governed record.", "Use an unambiguous vault wikilink."),
+    Rule("path.case_collision", "warning", "Two notes have paths that differ only by letter case or Unicode normalization.", "macOS and Windows checkouts keep only one of them, so the vault silently differs between machines.", "Rename or merge one of the notes so every path is unique ignoring case."),
+    Rule("report.undated", "error", "A point-in-time report filename has no YYYY-MM-DD suffix.", "Reports need an immutable temporal identity.", "Rename it to end in -YYYY-MM-DD.md."),
+    Rule("review_by.invalid", "error", "review_by is not a real ISO date.", "Review automation cannot act on an invalid date.", "Use YYYY-MM-DD."),
+    Rule("review_by.overdue", "warning", "An approved document is past review_by.", "The document may still be correct, but its freshness promise expired.", "Re-review it, update the evidence, and set the next review date."),
+    Rule("secret.detected", "error", "Text resembles a credential or private key.", "A knowledge vault is not a secret manager.", "Remove the value, rotate it if real, and store only a secret-manager location."),
+    Rule("secret.scan_non_utf8", "error", "A secret-scan candidate is not valid UTF-8.", "Unverified credential-shaped files create false confidence.", "Convert the file to UTF-8, exclude it explicitly, or scan it externally."),
+    Rule("secret.scan_skipped_large_file", "error", "A text asset is larger than the built-in secret scanner limit.", "Silent skips create false confidence that a vault contains no credentials.", "Scan the file externally, exclude it explicitly, or split it into smaller governed assets."),
+    Rule("secret.scan_unreadable", "error", "A secret-scan candidate could not be read.", "Unreadable credential-shaped files create false confidence.", "Fix permissions or exclude the path explicitly after an external scan."),
+    Rule("sensitivity.invalid", "error", "sensitivity uses an unsupported label.", "Handling policy depends on a small shared vocabulary.", "Use public, internal, confidential or restricted."),
+    Rule("source_of_truth.invalid", "warning", "source_of_truth is not a boolean.", "Values such as yes or \"true\" bypass the canonical-document checks that only fire on a real true.", "Use source_of_truth: true or source_of_truth: false."),
+    Rule("status.invalid", "error", "status uses an unsupported lifecycle value.", "Tools and people need one state model.", "Use template, draft, in_review, approved, superseded or archived."),
+    Rule("type.invalid", "error", "type uses an unsupported document type.", "Stable types make indexes and integrations predictable.", "Use a documented WhyKit type."),
+    Rule("wikilink.ambiguous", "error", "A wikilink matches multiple notes.", "The same link would resolve differently as the vault changes.", "Use a vault-relative path rather than a bare stem/alias."),
+    Rule("wikilink.missing", "error", "A wikilink cannot be resolved.", "Broken knowledge edges hide context and make the graph unreliable.", "Fix the target or remove the stale link."),
+    Rule("wikilink.outside", "warning", "A wikilink tries to traverse outside the vault.", "Vault links must not silently depend on files outside the governed boundary.", "Copy/register the source inside the vault or record an external location as evidence."),
+)
+
+SECURITY_RULE_CODES = frozenset({
+    "decision.unreviewed",
+    "markdown_link.outside",
+    "secret.detected",
+    "secret.scan_non_utf8",
+    "secret.scan_skipped_large_file",
+    "secret.scan_unreadable",
+    "sensitivity.invalid",
+    "wikilink.outside",
+})
+RULES = tuple(replace(rule, security=rule.code in SECURITY_RULE_CODES) for rule in _RULES)
+RULE_BY_CODE = {rule.code: rule for rule in RULES}
+
+
+def _md_cell(value: str) -> str:
+    return value.replace("|", r"\|").replace("\n", " ").strip()
+
+
+def markdown_table() -> str:
+    lines = [
+        "| Code | Level | What it means | Default fix |",
+        "|---|---|---|---|",
+    ]
+    # The named anchor lets SARIF helpUri and annotation links address one
+    # rule: docs/rules.md#evidence.missing. Tables have no per-row headings.
+    lines.extend(
+        f'| <a name="{rule.code}"></a>`{rule.code}` | {rule.default_level} | {_md_cell(rule.summary)} | {_md_cell(rule.fix)} |'
+        for rule in RULES
+    )
+    return "\n".join(lines)
+
+
+def builtin_entry(rule: Rule) -> dict[str, Any]:
+    return {**asdict(rule), "custom": False}
+
+
+def _scope_text(applies_to: dict[str, list[str]]) -> str:
+    if not applies_to:
+        return "every governed note"
+    return "; ".join(f"{key}: {', '.join(values)}" for key, values in applies_to.items())
+
+
+def _checks_text(checks: dict[str, Any]) -> str:
+    parts = []
+    for key, value in checks.items():
+        if isinstance(value, dict):
+            shown = ", ".join(f"{k} = {' or '.join(v)}" for k, v in value.items())
+        elif isinstance(value, list):
+            shown = ", ".join(f"`{item}`" if key.endswith("patterns") else item for item in value)
+        else:
+            shown = str(value)
+        parts.append(f"{key}: {shown}")
+    return "; ".join(parts)
+
+
+def policy_markdown(policy: Any) -> str:
+    """Markdown tables for a vault's custom rules and overrides (empty when none)."""
+    blocks: list[str] = []
+    if policy.custom:
+        lines = [
+            "### Custom rules (whykit.toml)",
+            "",
+            "| Code | Level | What it means | Applies to | Checks |",
+            "|---|---|---|---|---|",
+        ]
+        lines.extend(
+            f"| `{rule.code}` | {rule.level} | {_md_cell(rule.summary)} | {_md_cell(_scope_text(rule.applies_to))} | {_md_cell(_checks_text(rule.checks))} |"
+            for rule in policy.custom
+        )
+        blocks.append("\n".join(lines))
+    if policy.overrides:
+        lines = [
+            "### Overrides (whykit.toml)",
+            "",
+            "| Rule | Level | Paths | Reason |",
+            "|---|---|---|---|",
+        ]
+        lines.extend(
+            f"| `{entry.rule}` | {entry.level} | {_md_cell(', '.join(entry.paths) or 'whole vault')} | {_md_cell(entry.reason or '')} |"
+            for entry in policy.overrides
+        )
+        blocks.append("\n".join(lines))
+    return "\n\n".join(blocks)
+
+
+def _override_entry(entry: Any) -> dict[str, Any]:
+    return {"rule": entry.rule, "level": entry.level, "paths": list(entry.paths), "reason": entry.reason, "security": entry.security}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="whykit rules", description="List WhyKit lint rules or explain one stable rule code.")
+    parser.add_argument("code", nargs="?", help="rule code, for example evidence.missing")
+    parser.add_argument("--root", help="vault whose whykit.toml custom rules and overrides are listed too (default: nearest vault, if any)")
+    parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    parser.add_argument("--markdown", action="store_true", help="emit the complete Markdown rule table")
+    args = parser.parse_args(argv)
+    if args.json and args.markdown:
+        parser.print_usage(sys.stderr)
+        return emit_error("usage", f"{parser.prog}: error: --json and --markdown are mutually exclusive", json_mode=args.json)
+    if args.code and args.markdown:
+        parser.print_usage(sys.stderr)
+        return emit_error("usage", f"{parser.prog}: error: --markdown renders the full catalog and does not accept a single code", json_mode=args.json)
+
+    from pathlib import Path
+
+    from .config import ConfigError, load_config
+    from .contract import vault_not_found
+    from .lint import find_vault_root, is_vault_root
+    from .rule_policy import EMPTY_POLICY, policy_from_config
+
+    policy = EMPTY_POLICY
+    root = Path(args.root).expanduser().resolve() if args.root else find_vault_root()
+    if args.root and (root is None or not is_vault_root(root)):
+        return vault_not_found(args.root, json_mode=args.json)
+    if root is not None:
+        try:
+            config, _ = load_config(root)
+            policy = policy_from_config(config)
+        except ConfigError as exc:
+            return emit_error("invalid_config", str(exc), json_mode=args.json)
+
+    entries = [builtin_entry(rule) for rule in RULES] + [rule.catalog_entry() for rule in policy.custom]
+    by_code = {entry["code"]: entry for entry in entries}
+
+    if args.code:
+        entry = by_code.get(args.code)
+        if entry is None:
+            return emit_error("invalid_argument", f"unknown rule code: {args.code}", json_mode=args.json)
+        if args.json:
+            emit_machine(json.dumps({"contract_version": CONTRACT_VERSION, **entry}, ensure_ascii=False, indent=2))
+        else:
+            tags = " security" if entry["security"] else (" custom" if entry["custom"] else "")
+            print(f"{entry['code']} [{entry['default_level']}{tags}]")
+            print(entry["summary"])
+            print(f"Why: {entry['why']}")
+            print(f"Fix: {entry['fix']}")
+            if entry["custom"]:
+                print(f"Applies to: {_scope_text(entry['applies_to'])}")
+                print(f"Checks: {_checks_text(entry['checks'])}")
+            for override in policy.overrides:
+                if override.rule == entry["code"]:
+                    print(f"Override: {override.describe().split(' (', 1)[0]}" + (f" — reason: {override.reason}" if override.reason else ""))
+        return 0
+
+    if args.json:
+        payload: dict[str, Any] = {"contract_version": CONTRACT_VERSION, "count": len(entries), "rules": entries}
+        if policy.overrides:
+            payload["overrides"] = [_override_entry(entry) for entry in policy.overrides]
+        emit_machine(json.dumps(payload, ensure_ascii=False, indent=2))
+    elif args.markdown:
+        extra = policy_markdown(policy)
+        print(markdown_table() + ("\n\n" + extra if extra else ""))
+    else:
+        for rule in RULES:
+            print(f"{rule.default_level:<7} {rule.code:<34} {rule.summary}")
+        if policy.custom:
+            print("\nCustom rules (whykit.toml)")
+            for custom in policy.custom:
+                print(f"{custom.level:<7} {custom.code:<34} {custom.summary}")
+        if policy.overrides:
+            print("\nOverrides (whykit.toml)")
+            for override in policy.overrides:
+                scope = ", ".join(override.paths) if override.paths else "whole vault"
+                reason = f"  reason: {override.reason}" if override.reason else ""
+                print(f"{override.level:<7} {override.rule:<34} {scope}{reason}")
+    return 0