@drafthq/draft 3.0.0 → 3.1.5

package/scripts/tools/okf-check.sh

@@ -1,137 +0,0 @@
-#!/usr/bin/env bash
-# okf-check.sh — validate a directory against the Open Knowledge Format v0.1 spec.
-#
-# Implements the §9 conformance criteria of OKF v0.1
-# (https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md):
-#
-#   §9.1  Every non-reserved .md file has a parseable YAML frontmatter block.
-#   §9.2  Every such frontmatter block has a non-empty `type` field.
-#   §9.3  Reserved files follow their structure when present:
-#           index.md  (§6)  — contains NO frontmatter, EXCEPT the bundle-root
-#                             index.md MAY carry frontmatter holding only
-#                             `okf_version` (§11).
-#           log.md    (§7)  — `## ` date headings MUST be ISO 8601 (YYYY-MM-DD).
-#
-# Consumers are required to be permissive, so this checker only enforces the
-# three hard rules above; everything else in the spec is soft guidance.
-#
-# Usage: scripts/tools/okf-check.sh [--dir DIR] [--quiet]
-# Exit codes: 0 conformant, 1 violations found, 2 dir missing.
-set -euo pipefail
-
-DIR="draft"
-QUIET=0
-
-usage() {
-    cat <<'EOF'
-okf-check.sh — validate a directory against Open Knowledge Format v0.1 (§9).
-
-Usage:
-  scripts/tools/okf-check.sh [--dir DIR] [--quiet]
-
-Flags:
-  --dir DIR  Bundle root to validate (default: draft).
-  --quiet    Print only the summary line, not per-file violations.
-  --help     Show this help.
-
-Exit 0 when conformant, 1 when violations are found, 2 when DIR is absent.
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        --dir) DIR="$2"; shift 2;;
-        --quiet) QUIET=1; shift;;
-        --help|-h) usage; exit 0;;
-        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
-        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
-    esac
-done
-
-[[ -d "$DIR" ]] || { echo "ERROR: --dir '$DIR' is not a directory" >&2; exit 2; }
-DIR="${DIR%/}"
-
-# fm_scan FILE -> "STATUS|TYPE|KEYS"  (pipe-delimited; '|' is not IFS-whitespace,
-# so empty TYPE/KEYS fields survive `read` instead of collapsing).
-#   STATUS: nofm (no frontmatter) | ok (closed block) | unterminated
-#   TYPE:   value of the top-level `type:` key, if any
-#   KEYS:   comma-separated top-level frontmatter keys
-fm_scan() {
-    awk '
-        NR==1 { if ($0 != "---") { print "nofm||"; exit } ; inblock=1; next }
-        inblock && /^---[[:space:]]*$/ { print "ok|" type "|" keys; closed=1; exit }
-        inblock {
-            if (match($0, /^[A-Za-z_][A-Za-z0-9_]*:/)) {
-                k = substr($0, 1, RLENGTH-1)
-                keys = keys (keys=="" ? "" : ",") k
-                if (k == "type") {
-                    v = substr($0, RLENGTH+1)
-                    gsub(/^[ \t]+|[ \t]+$/, "", v)
-                    gsub(/^"|"$/, "", v)
-                    type = v
-                }
-            }
-            next
-        }
-        END { if (inblock && !closed) print "unterminated|" type "|" keys }
-    ' "$1"
-}
-
-violations=0
-concepts=0
-reserved=0
-
-report() { # relpath  message
-    violations=$((violations + 1))
-    [[ "$QUIET" == "1" ]] || echo "FAIL  $1: $2" >&2
-}
-
-while IFS= read -r -d '' file; do
-    rel="${file#"$DIR"/}"
-    base="$(basename "$file")"
-
-    case "$base" in
-        index.md)
-            reserved=$((reserved + 1))
-            IFS='|' read -r status _ keys < <(fm_scan "$file")
-            if [[ "$status" != "nofm" ]]; then
-                if [[ "$rel" == "index.md" ]]; then
-                    # Bundle-root index.md: frontmatter allowed, but only okf_version (§11).
-                    IFS=',' read -ra ks <<< "$keys"
-                    for k in "${ks[@]}"; do
-                        [[ -z "$k" || "$k" == "okf_version" ]] && continue
-                        report "$rel" "root index.md frontmatter may only hold 'okf_version' (§11); found '$k'"
-                    done
-                else
-                    report "$rel" "index.md must not contain frontmatter (§6)"
-                fi
-            fi
-            ;;
-        log.md)
-            reserved=$((reserved + 1))
-            while IFS= read -r h; do
-                if ! [[ "$h" =~ ^##[[:space:]]+[0-9]{4}-[0-9]{2}-[0-9]{2} ]]; then
-                    report "$rel" "log.md date heading not ISO 8601 (§7): '$h'"
-                fi
-            done < <(grep -E '^## ' "$file" 2>/dev/null || true)
-            ;;
-        *)
-            concepts=$((concepts + 1))
-            IFS='|' read -r status type _ < <(fm_scan "$file")
-            case "$status" in
-                nofm)         report "$rel" "missing YAML frontmatter block (§9.1)";;
-                unterminated) report "$rel" "unterminated frontmatter block — no closing '---' (§9.1)";;
-                ok)
-                    [[ -n "$type" ]] || report "$rel" "frontmatter missing required non-empty 'type' (§9.2)"
-                    ;;
-            esac
-            ;;
-    esac
-done < <(find "$DIR" -type f -name '*.md' -print0 | sort -z)
-
-if [[ "$violations" -eq 0 ]]; then
-    echo "OKF v0.1 conformant — $concepts concept file(s), $reserved reserved file(s), 0 violations. ($DIR)"
-    exit 0
-fi
-echo "OKF v0.1 NON-CONFORMANT — $violations violation(s) across $concepts concept + $reserved reserved file(s). ($DIR)" >&2
-exit 1

package/scripts/tools/okf-emit.sh

@@ -1,161 +0,0 @@
-#!/usr/bin/env bash
-# okf-emit.sh — emit an Open Knowledge Format (OKF) bundle from a graph snapshot.
-#
-# OKF is an open, vendor-neutral spec (Google Cloud): a directory of markdown
-# files with YAML frontmatter, one file per concept, where the file path is the
-# concept's identity and concepts cross-link with normal markdown links. The
-# only required frontmatter field is `type`. This makes Draft's knowledge graph
-# portable — consumable by any OKF reader (visualizers, catalogs, other agents).
-# https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
-#
-# Reads a graph snapshot's architecture.json and writes a conformant bundle:
-#   index.md            type: Repository — bundle root + progressive disclosure
-#   modules/<slug>.md   type: Module     — one concept per package, cross-linked
-#
-# Degrades gracefully: with no packages/boundaries in the snapshot it still emits
-# index.md (counts, languages, hotspots) and an empty modules/ directory.
-#
-# Usage: scripts/tools/okf-emit.sh [--repo DIR] [--snapshot DIR] [--out DIR]
-# Exit codes: 0 OK, 1 invocation error, 2 snapshot/architecture.json unavailable.
-set -euo pipefail
-
-REPO="."
-SNAPSHOT=""
-OUT=""
-
-usage() {
-    cat <<'EOF'
-okf-emit.sh — emit an Open Knowledge Format (OKF) bundle from a graph snapshot.
-
-Usage:
-  scripts/tools/okf-emit.sh [--repo DIR] [--snapshot DIR] [--out DIR]
-
-Flags:
-  --repo DIR      Repository root (default: cwd).
-  --snapshot DIR  Snapshot dir holding architecture.json (default: <repo>/draft/graph).
-  --out DIR       Bundle output dir (default: <snapshot>/okf).
-  --help          Show this help.
-
-Writes index.md + modules/<slug>.md (OKF v0.1). Exit 0 on success, 2 when no
-architecture.json is available (nothing emitted).
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --snapshot) SNAPSHOT="$2"; shift 2;;
-        --out) OUT="$2"; shift 2;;
-        --help|-h) usage; exit 0;;
-        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
-        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
-    esac
-done
-
-[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
-REPO_ABS="$(cd "$REPO" && pwd)"
-SNAP="${SNAPSHOT:-$REPO_ABS/draft/graph}"
-ARCH="$SNAP/architecture.json"
-OUT="${OUT:-$SNAP/okf}"
-
-command -v jq >/dev/null 2>&1 || { echo "jq required for OKF emit" >&2; exit 2; }
-[[ -f "$ARCH" ]] || { echo "no architecture.json at $ARCH — nothing to emit" >&2; exit 2; }
-
-# slugify a concept name into a filesystem- and link-safe identifier.
-slug() {
-    local s
-    s="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]' \
-        | sed -e 's#[^a-z0-9]\{1,\}#-#g' -e 's#^-##' -e 's#-$##')"
-    [[ -n "$s" ]] || s="module"
-    printf '%s' "$s"
-}
-
-# escape a value for a YAML double-quoted scalar.
-yesc() {
-    local s="$1"
-    s="${s//\\/\\\\}"
-    s="${s//\"/\\\"}"
-    printf '%s' "$s"
-}
-
-TS="$(date -Iseconds 2>/dev/null || date)"
-PROJECT="$(jq -r '.project // "repository"' "$ARCH")"
-TOTAL_NODES="$(jq -r '.total_nodes // 0' "$ARCH")"
-TOTAL_EDGES="$(jq -r '.total_edges // 0' "$ARCH")"
-
-PKGS="$(jq -r '.packages[]? | [.name, (.node_count//0), (.fan_in//0), (.fan_out//0)] | @tsv' "$ARCH")"
-BOUNDS="$(jq -r '.boundaries[]? | [.from, .to, (.call_count//0)] | @tsv' "$ARCH")"
-
-mkdir -p "$OUT/modules"
-
-# --- One concept file per package, cross-linked via boundaries ---
-PKG_COUNT=0
-if [[ -n "$PKGS" ]]; then
-    while IFS=$'\t' read -r name nc fi fo; do
-        [[ -n "$name" ]] || continue
-        PKG_COUNT=$((PKG_COUNT + 1))
-        s="$(slug "$name")"
-        {
-            printf -- '---\n'
-            printf 'type: Module\n'
-            printf 'title: "%s"\n' "$(yesc "$name")"
-            printf 'description: "Code module %s: %s nodes, fan-in %s, fan-out %s."\n' \
-                "$(yesc "$name")" "$nc" "$fi" "$fo"
-            printf 'tags: [module, knowledge-graph]\n'
-            printf 'timestamp: "%s"\n' "$TS"
-            printf -- '---\n\n'
-            printf '# %s\n\n' "$name"
-            printf 'Structural module derived from the knowledge graph. Nodes: %s, fan-in: %s, fan-out: %s.\n' \
-                "$nc" "$fi" "$fo"
-
-            # Depends on (outbound boundaries)
-            outs="$(awk -F'\t' -v n="$name" '$1==n && $2!="" {print $2"\t"$3}' <<< "$BOUNDS")"
-            if [[ -n "$outs" ]]; then
-                printf '\n## Depends on\n\n'
-                while IFS=$'\t' read -r to cc; do
-                    [[ -n "$to" ]] || continue
-                    printf -- '- [%s](%s.md) — %s call(s)\n' "$to" "$(slug "$to")" "$cc"
-                done <<< "$outs"
-            fi
-
-            # Depended on by (inbound boundaries)
-            ins="$(awk -F'\t' -v n="$name" '$2==n && $1!="" {print $1"\t"$3}' <<< "$BOUNDS")"
-            if [[ -n "$ins" ]]; then
-                printf '\n## Depended on by\n\n'
-                while IFS=$'\t' read -r from cc; do
-                    [[ -n "$from" ]] || continue
-                    printf -- '- [%s](%s.md) — %s call(s)\n' "$from" "$(slug "$from")" "$cc"
-                done <<< "$ins"
-            fi
-        } > "$OUT/modules/$s.md"
-    done <<< "$PKGS"
-fi
-
-# --- Bundle index.md (reserved file: no frontmatter, §6 progressive disclosure) ---
-{
-    printf '# %s\n\n' "$PROJECT"
-    printf 'Open Knowledge Format bundle generated by Draft from the codebase-memory-mcp knowledge graph. Nodes: %s, edges: %s, modules: %s.\n' \
-        "$TOTAL_NODES" "$TOTAL_EDGES" "$PKG_COUNT"
-
-    langs="$(jq -r '.languages[]? | "* \(.language) - \(.file_count) file(s)"' "$ARCH")"
-    if [[ -n "$langs" ]]; then
-        printf '\n# Languages\n\n%s\n' "$langs"
-    fi
-
-    if [[ "$PKG_COUNT" -gt 0 ]]; then
-        printf '\n# Modules\n\n'
-        while IFS=$'\t' read -r name nc fi fo; do
-            [[ -n "$name" ]] || continue
-            printf -- '* [%s](modules/%s.md) - %s nodes, fan-in %s, fan-out %s\n' \
-                "$name" "$(slug "$name")" "$nc" "$fi" "$fo"
-        done < <(printf '%s\n' "$PKGS" | sort)
-    fi
-
-    hot="$(jq -r '.hotspots[:10][]? | "* \(.name) - fan-in \(.fan_in)"' "$ARCH")"
-    if [[ -n "$hot" ]]; then
-        printf '\n# Top hotspots\n\n%s\n' "$hot"
-    fi
-} > "$OUT/index.md"
-
-echo "OKF bundle written to $OUT (modules=$PKG_COUNT)"
-exit 0