ops-wiki-agent-kit 0.1.0

package/.github/skills/source-code-to-spec-tools/scripts/catalog_query.py

@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+import sys
+
+sys.dont_write_bytecode = True
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+
+PREFERRED_SECTIONS = {
+    "handoff": "Authoritative Target Source Handoff",
+    "direct": "Direct Target Rows",
+    "hardcoded": "Hardcoded Target Rows",
+    "coverage": "Coverage Review",
+}
+
+
+def configure_stdio():
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name, None)
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            reconfigure(encoding="utf-8")
+
+
+def normalize_text(value):
+    if value is None:
+        return ""
+    return re.sub(r"\s+", " ", str(value)).strip()
+
+
+def normalize_key(value):
+    return normalize_text(value).casefold()
+
+
+def split_markdown_row(line):
+    line = line.strip()
+    if not line.startswith("|") or not line.endswith("|"):
+        return []
+    cells = []
+    current = []
+    escaped = False
+    for char in line[1:-1]:
+        if escaped:
+            current.append(char)
+            escaped = False
+        elif char == "\\":
+            escaped = True
+        elif char == "|":
+            cells.append("".join(current).strip())
+            current = []
+        else:
+            current.append(char)
+    cells.append("".join(current).strip())
+    return cells
+
+
+def is_separator(cells):
+    return bool(cells) and all(re.fullmatch(r":?-{3,}:?", cell.strip()) for cell in cells)
+
+
+def markdown_escape(value):
+    return normalize_text(value).replace("|", "\\|")
+
+
+def iter_markdown_tables(lines):
+    current_heading = ""
+    current_level = 0
+    for index, line in enumerate(lines):
+        heading = re.match(r"^(#{1,6})\s+(.+?)\s*$", line)
+        if heading:
+            current_level = len(heading.group(1))
+            current_heading = heading.group(2).strip()
+            continue
+
+        header = split_markdown_row(line)
+        if not header or index + 1 >= len(lines):
+            continue
+        separator = split_markdown_row(lines[index + 1])
+        if len(separator) != len(header) or not is_separator(separator):
+            continue
+
+        rows = []
+        end_line = index + 2
+        for data_index in range(index + 2, len(lines)):
+            values = split_markdown_row(lines[data_index])
+            if len(values) != len(header):
+                break
+            rows.append(dict(zip(header, values)))
+            end_line = data_index + 1
+        yield {
+            "section": current_heading,
+            "section_level": current_level,
+            "columns": header,
+            "rows": rows,
+            "start_line": index + 1,
+            "end_line": end_line,
+        }
+
+
+def read_catalog(path):
+    path = Path(path)
+    lines = path.read_text(encoding="utf-8-sig").splitlines()
+    tables = list(iter_markdown_tables(lines))
+    if not tables:
+        raise SystemExit(f"No Markdown tables found in {path}")
+    return {"path": str(path), "tables": tables}
+
+
+def table_metadata(table):
+    return {
+        "section": table["section"],
+        "section_level": table["section_level"],
+        "columns": table["columns"],
+        "row_count": len(table["rows"]),
+        "start_line": table["start_line"],
+        "end_line": table["end_line"],
+    }
+
+
+def section_matches(actual, expected):
+    if not expected:
+        return True
+    return normalize_key(expected) in normalize_key(actual)
+
+
+def row_matches(row, query=None, column_filters=None):
+    if query and normalize_key(query) not in normalize_key(" ".join(row.values())):
+        return False
+    for column_name, expected in column_filters or []:
+        matched_key = None
+        for key in row.keys():
+            if normalize_key(key) == normalize_key(column_name):
+                matched_key = key
+                break
+        if matched_key is None:
+            return False
+        if normalize_key(expected) not in normalize_key(row.get(matched_key)):
+            return False
+    return True
+
+
+def parse_column_filters(values):
+    filters = []
+    for value in values or []:
+        if "=" not in value:
+            raise SystemExit(f"Invalid --where value: {value}. Expected column=value.")
+        column_name, expected = value.split("=", 1)
+        column_name = normalize_text(column_name)
+        expected = normalize_text(expected)
+        if not column_name:
+            raise SystemExit(f"Invalid --where value: {value}. Missing column name.")
+        filters.append((column_name, expected))
+    return filters
+
+
+def collect_rows(catalog, section=None, query=None, column_filters=None, limit=None):
+    results = []
+    for table in catalog["tables"]:
+        if not section_matches(table["section"], section):
+            continue
+        for row in table["rows"]:
+            if not row_matches(row, query=query, column_filters=column_filters):
+                continue
+            item = dict(row)
+            item["_section"] = table["section"]
+            item["_line"] = table["start_line"]
+            results.append(item)
+            if limit is not None and len(results) >= limit:
+                return results
+    return results
+
+
+def render_table(rows):
+    if not rows:
+        return "(no rows)"
+    columns = list(rows[0].keys())
+    for row in rows[1:]:
+        for column in row.keys():
+            if column not in columns:
+                columns.append(column)
+    lines = []
+    lines.append("| " + " | ".join(columns) + " |")
+    lines.append("| " + " | ".join("---" for _ in columns) + " |")
+    for row in rows:
+        lines.append("| " + " | ".join(markdown_escape(row.get(column, "")) for column in columns) + " |")
+    return "\n".join(lines)
+
+
+def print_output(payload, output_format):
+    if output_format == "json":
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return
+    if isinstance(payload, dict) and "rows" in payload:
+        print(render_table(payload["rows"]))
+        return
+    if isinstance(payload, dict) and "tables" in payload:
+        print(render_table(payload["tables"]))
+        return
+    if isinstance(payload, list):
+        print(render_table(payload))
+        return
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def command_tables(args):
+    catalog = read_catalog(args.catalog)
+    tables = [table_metadata(table) for table in catalog["tables"]]
+    if args.section:
+        tables = [table for table in tables if section_matches(table["section"], args.section)]
+    print_output({"catalog": catalog["path"], "count": len(tables), "tables": tables}, args.output)
+
+
+def command_rows(args):
+    catalog = read_catalog(args.catalog)
+    rows = collect_rows(
+        catalog,
+        section=args.section,
+        query=args.query,
+        column_filters=parse_column_filters(args.where),
+        limit=args.limit,
+    )
+    print_output({"catalog": catalog["path"], "count": len(rows), "rows": rows}, args.output)
+
+
+def command_handoff(args):
+    catalog = read_catalog(args.catalog)
+    filters = parse_column_filters(args.where)
+    if args.action:
+        filters.append(("target_queue_action", args.action))
+    if args.target_scope:
+        filters.append(("target_scope", args.target_scope))
+    if args.authority:
+        filters.append(("final_row_authority", args.authority))
+    rows = collect_rows(
+        catalog,
+        section=PREFERRED_SECTIONS["handoff"],
+        query=args.query,
+        column_filters=filters,
+        limit=args.limit,
+    )
+    print_output({"catalog": catalog["path"], "count": len(rows), "rows": rows}, args.output)
+
+
+def command_coverage(args):
+    catalog = read_catalog(args.catalog)
+    rows = collect_rows(
+        catalog,
+        section=PREFERRED_SECTIONS["coverage"],
+        query=args.query,
+        column_filters=parse_column_filters(args.where),
+        limit=args.limit,
+    )
+    print_output({"catalog": catalog["path"], "count": len(rows), "rows": rows}, args.output)
+
+
+def command_search(args):
+    catalog = read_catalog(args.catalog)
+    rows = collect_rows(catalog, query=args.query, limit=args.limit)
+    print_output({"catalog": catalog["path"], "count": len(rows), "rows": rows}, args.output)
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        description="Parse and query docs-target-catalog Markdown tables as reusable source handoff data."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    tables = subparsers.add_parser("tables", help="List Markdown tables with section, columns, row count, and lines.")
+    tables.add_argument("--catalog", default="docs/docs-target-catalog.md")
+    tables.add_argument("--section")
+    tables.add_argument("--output", choices=("json", "markdown"), default="json")
+    tables.set_defaults(func=command_tables)
+
+    rows = subparsers.add_parser("rows", help="Query rows from a named catalog section.")
+    rows.add_argument("--catalog", default="docs/docs-target-catalog.md")
+    rows.add_argument("--section", required=True)
+    rows.add_argument("--query")
+    rows.add_argument("--where", action="append", default=[], help="Column contains filter in column=value form.")
+    rows.add_argument("--limit", type=int)
+    rows.add_argument("--output", choices=("json", "markdown"), default="json")
+    rows.set_defaults(func=command_rows)
+
+    handoff = subparsers.add_parser("handoff", help="Query Authoritative Target Source Handoff rows.")
+    handoff.add_argument("--catalog", default="docs/docs-target-catalog.md")
+    handoff.add_argument("--query")
+    handoff.add_argument("--action", help="Filter target_queue_action, e.g. direct_rows or query/export.")
+    handoff.add_argument("--target-scope")
+    handoff.add_argument("--authority", help="Filter final_row_authority.")
+    handoff.add_argument("--where", action="append", default=[], help="Column contains filter in column=value form.")
+    handoff.add_argument("--limit", type=int)
+    handoff.add_argument("--output", choices=("json", "markdown"), default="json")
+    handoff.set_defaults(func=command_handoff)
+
+    coverage = subparsers.add_parser("coverage", help="Query catalog Coverage Review rows.")
+    coverage.add_argument("--catalog", default="docs/docs-target-catalog.md")
+    coverage.add_argument("--query")
+    coverage.add_argument("--where", action="append", default=[], help="Column contains filter in column=value form.")
+    coverage.add_argument("--limit", type=int)
+    coverage.add_argument("--output", choices=("json", "markdown"), default="json")
+    coverage.set_defaults(func=command_coverage)
+
+    search = subparsers.add_parser("search", help="Search every parsed catalog table row.")
+    search.add_argument("--catalog", default="docs/docs-target-catalog.md")
+    search.add_argument("--query", required=True)
+    search.add_argument("--limit", type=int)
+    search.add_argument("--output", choices=("json", "markdown"), default="json")
+    search.set_defaults(func=command_search)
+    return parser
+
+
+def main():
+    configure_stdio()
+    args = build_parser().parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except BrokenPipeError:
+        sys.exit(1)

package/.github/skills/source-code-to-spec-tools/scripts/queue_contract.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Shared documentation target queue schema and normalization helpers."""
+
+import sys
+
+sys.dont_write_bytecode = True
+
+import re
+
+
+MAIN_COLUMNS = [
+    "id",
+    "source_type",
+    "original_id",
+    "group",
+    "name",
+    "entrypoint",
+    "document_path",
+    "keyword",
+    "doc_profile",
+    "foundation_doc_status",
+    "architecture_doc_status",
+    "ops_doc_status",
+    "review_status",
+    "document_completed_flag(Y/N)",
+    "last_handoff",
+    "notes",
+]
+
+SUMMARY_COLUMNS = [
+    "target_scope",
+    "source_kind",
+    "authoritative_source",
+    "acquisition_method",
+    "selected_fields",
+    "filter_or_scope",
+    "raw_count",
+    "eligible_count",
+    "excluded_count",
+    "gap_count",
+    "validation_status",
+]
+
+SUMMARY_SCOPE_COLUMNS = [
+    "target_scope",
+    "source_kind",
+]
+
+COVERAGE_COLUMNS = [
+    "item",
+    "reason_not_in_table",
+    "evidence",
+    "recommended_next_step",
+]
+
+DOC_STATUSES = {"pending", "in_progress", "generated", "partial", "blocked", "failed", "n/a"}
+FOUNDATION_DOC_STATUSES = DOC_STATUSES
+ARCHITECTURE_DOC_STATUSES = DOC_STATUSES
+OPS_DOC_STATUSES = DOC_STATUSES
+REVIEW_STATUSES = {"not_started", "pending", "passed", "failed", "blocked", "waived"}
+DOC_PROFILES = {"lite", "standard", "full"}
+
+SOURCE_TYPE_REGISTRY = {
+    "Function": {
+        "prefix": "F",
+        "path_pattern": "docs/feature/{group}/{name}",
+        "default_doc_profile": "standard",
+        "scope_hints": ["function", "menu", "navigation", "screen", "ui"],
+        "use_for": "user-facing menu/navigation/business capabilities that are not better represented by a specific channel",
+    },
+    "Job": {
+        "prefix": "J",
+        "path_pattern": "docs/job/{name}",
+        "default_doc_profile": "standard",
+        "scope_hints": ["job", "batch", "scheduler", "worker", "cron"],
+        "use_for": "scheduled jobs, workers, batch jobs, DB jobs, background processors",
+    },
+    "API": {
+        "prefix": "A",
+        "path_pattern": "docs/api/{name}",
+        "default_doc_profile": "lite",
+        "scope_hints": ["api", "endpoint", "route", "servlet", "service"],
+        "use_for": "independently activated REST/SOAP/RPC/service endpoints or service operations",
+    },
+    "Report": {
+        "prefix": "R",
+        "path_pattern": "docs/report/{group}/{name}",
+        "default_doc_profile": "lite",
+        "scope_hints": ["report", "download", "export"],
+        "use_for": "independent reports, exports, dashboards, report scheduler identities",
+    },
+    "File": {
+        "prefix": "FI",
+        "path_pattern": "docs/file-process/{name}",
+        "default_doc_profile": "standard",
+        "scope_hints": ["file", "import", "export", "watcher", "etl"],
+        "use_for": "file import, export, watcher, transfer, archive processes",
+    },
+    "External": {
+        "prefix": "X",
+        "path_pattern": "docs/external/{name}",
+        "default_doc_profile": "standard",
+        "scope_hints": ["external", "integration", "webhook", "partner"],
+        "use_for": "external integrations, webhooks, partner/system interfaces, message contracts",
+    },
+    "ERP": {
+        "prefix": "E",
+        "path_pattern": "docs/erp/{group}/{name}",
+        "default_doc_profile": "standard",
+        "scope_hints": ["erp", "program", "responsibility", "form", "transaction"],
+        "use_for": "ERP or platform metadata, forms, responsibilities, programs, transactions",
+    },
+    "DatabaseProgram": {
+        "prefix": "DBP",
+        "path_pattern": "docs/database-program/{group}/{name}",
+        "default_doc_profile": "standard",
+        "scope_hints": [
+            "database program",
+            "stored procedure",
+            "stored function",
+            "routine",
+            "package",
+            "trigger",
+            "plsql",
+        ],
+        "use_for": "database-side packages, stored procedures/functions, triggers, routine tasks, and DB-owned program units",
+    },
+    "Command": {
+        "prefix": "C",
+        "path_pattern": "docs/command/{name}",
+        "default_doc_profile": "lite",
+        "scope_hints": ["command", "cli", "console", "script", "admin"],
+        "use_for": "CLI/operator commands, console tasks, scripted commands, admin commands",
+    },
+    "Workflow": {
+        "prefix": "W",
+        "path_pattern": "docs/workflow/{name}",
+        "default_doc_profile": "standard",
+        "scope_hints": ["workflow", "bpmn", "approval", "state", "process"],
+        "use_for": "BPMN/process definitions, approval flows, state-machine workflows, orchestrated business processes",
+    },
+    "MobileScreen": {
+        "prefix": "M",
+        "path_pattern": "docs/mobile/{group}/{name}",
+        "default_doc_profile": "standard",
+        "scope_hints": ["mobile", "screen", "tab", "activity", "fragment", "deep link"],
+        "use_for": "mobile screens, tabs, activities/fragments, deep links, mobile navigation destinations",
+    },
+    "DesktopAction": {
+        "prefix": "D",
+        "path_pattern": "docs/desktop/{group}/{name}",
+        "default_doc_profile": "standard",
+        "scope_hints": ["desktop", "menu", "toolbar", "shortcut", "window", "form"],
+        "use_for": "desktop menu/toolbar actions, shortcut commands, form/window actions, command bindings",
+    },
+    "LibraryAPI": {
+        "prefix": "L",
+        "path_pattern": "docs/library-api/{name}",
+        "default_doc_profile": "lite",
+        "scope_hints": ["library", "sdk", "package", "export", "module"],
+        "use_for": "public library/package APIs, SDK entrypoints, exported module contracts",
+    },
+    "DataPipeline": {
+        "prefix": "DP",
+        "path_pattern": "docs/data-pipeline/{name}",
+        "default_doc_profile": "standard",
+        "scope_hints": ["data", "pipeline", "dag", "etl", "elt", "stream"],
+        "use_for": "DAGs, ETL/ELT pipelines, stream processors, data product refreshes",
+    },
+}
+
+DEFAULT_PREFIXES = {source_type: values["prefix"] for source_type, values in SOURCE_TYPE_REGISTRY.items()}
+DEFAULT_PATH_PATTERNS = {
+    source_type: values["path_pattern"] for source_type, values in SOURCE_TYPE_REGISTRY.items()
+}
+DEFAULT_DOC_PROFILE_BY_SOURCE_TYPE = {
+    source_type: values["default_doc_profile"]
+    for source_type, values in SOURCE_TYPE_REGISTRY.items()
+    if values["default_doc_profile"] != "standard"
+}
+SOURCE_TYPE_SCOPE_HINTS = {
+    source_type.casefold(): values["scope_hints"] for source_type, values in SOURCE_TYPE_REGISTRY.items()
+}
+
+
+def normalize_text(value):
+    if value is None:
+        return ""
+    return re.sub(r"\s+", " ", str(value)).strip()
+
+
+def normalize_key(value):
+    return normalize_text(value).casefold()
+
+
+def normalize_status(value, allowed, default):
+    value = normalize_text(value).lower()
+    return value if value in allowed else default
+
+
+def normalize_completed_flag(value):
+    value = normalize_text(value).upper()
+    return value if value in {"Y", "N"} else "N"
+
+
+def normalize_doc_profile(value, source_type=""):
+    value = normalize_text(value).lower()
+    if value in DOC_PROFILES:
+        return value
+    return DEFAULT_DOC_PROFILE_BY_SOURCE_TYPE.get(normalize_text(source_type), "standard")