@erclx/canon 5.8.0 → 5.9.0

package/scripts/docs/list.sh

@@ -1,184 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
-
-source "$PROJECT_ROOT/scripts/lib/ui.sh"
-source "$PROJECT_ROOT/scripts/lib/frontmatter.sh"
-
-DOCS_DIR="$PROJECT_ROOT/docs"
-CONTEXT_DIR="$PROJECT_ROOT/canon/context"
-
-INTERNAL_TOPICS=" ci development sandbox "
-
-show_help() {
-  echo -e "${GREY}┌${NC}"
-  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} canon docs list [options]"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
-  echo -e "${GREY}│${NC}    --json       ${GREY}# Emit machine-readable JSON${NC}"
-  echo -e "${GREY}│${NC}    -h, --help   ${GREY}# Show this help message${NC}"
-  echo -e "${GREY}└${NC}"
-  exit 0
-}
-
-is_target_facing() {
-  case "$1" in
-  "Agent surface" | "Domain references") return 0 ;;
-  *) return 1 ;;
-  esac
-}
-
-is_internal_topic() {
-  case "$INTERNAL_TOPICS" in
-  *" $1 "*) return 0 ;;
-  *) return 1 ;;
-  esac
-}
-
-# Emits `name<TAB>description<TAB>category<TAB>target` per target-facing doc,
-# sorted so a domain split into a folder lands in its alphabetical place rather
-# than after every file. A folder declares its category on its own index, since
-# the allowlist is what separates a target-facing doc from a workflow one and a
-# split domain is not exempt from it. A sub-area file declares its own, which is
-# what keeps a page's listing membership unchanged by the folder it moves into.
-collect_docs() {
-  local file name description category
-  {
-    while IFS= read -r file; do
-      name=$(basename "$file" .md)
-      [ "$name" = "index" ] && continue
-      category=$(read_frontmatter_field "$file" "category")
-      is_target_facing "$category" || continue
-      description=$(read_frontmatter_field "$file" "description")
-      printf '%s\t%s\t%s\t%s\n' "$name" "$description" "$category" "docs/$name.md"
-    done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md")
-
-    # A split domain is named by its folder and described by its generated
-    # index, which carries subtitle where a sibling file carries description
-    while IFS= read -r file; do
-      name=$(basename "$(dirname "$file")")
-      category=$(read_frontmatter_field "$file" "category")
-      is_target_facing "$category" || continue
-      description=$(read_frontmatter_field "$file" "subtitle")
-      printf '%s\t%s\t%s\t%s\n' "$name" "$description" "$category" "docs/$name/index.md"
-    done < <(find "$DOCS_DIR" -mindepth 2 -maxdepth 2 -type f -name "index.md")
-
-    # A sub-area file is named and described like a sibling file, and reaches a
-    # caller by that bare name, so the depth it sits at is not the listing's
-    # business. Only a folder carrying an index is walked, matching resolveTopic
-    while IFS= read -r file; do
-      name=$(basename "$file" .md)
-      [ "$name" = "index" ] && continue
-      [ -f "$(dirname "$file")/index.md" ] || continue
-      category=$(read_frontmatter_field "$file" "category")
-      is_target_facing "$category" || continue
-      description=$(read_frontmatter_field "$file" "description")
-      printf '%s\t%s\t%s\t%s\n' "$name" "$description" "$category" "docs/$(basename "$(dirname "$file")")/$name.md"
-    done < <(find "$DOCS_DIR" -mindepth 2 -maxdepth 2 -type f -name "*.md")
-  } | sort
-}
-
-# Emits `name<TAB>description<TAB>target` per context entry, sorted so a domain
-# split into a folder lands in its alphabetical place rather than after every
-# file, the way listTopics in src/docs/read.ts sorts both together.
-#
-# It stops at the folder where listTopics goes on to name each sub-area file.
-# This is the downstream catalog and that one answers what a caller could have
-# typed, so a reachable name absent here is the same divergence the internal
-# topics already carry, and `canon docs docs` states it.
-collect_context() {
-  local file name description
-  {
-    while IFS= read -r file; do
-      name=$(basename "$file" .md)
-      [ "$name" = "index" ] && continue
-      is_internal_topic "$name" && continue
-      description=$(read_frontmatter_field "$file" "description")
-      printf '%s\t%s\t%s\n' "$name" "$description" "canon/context/$name.md"
-    done < <(find "$CONTEXT_DIR" -maxdepth 1 -type f -name "*.md")
-
-    # A split domain is named by its folder and described by its generated
-    # index, which carries subtitle where a sibling file carries description
-    while IFS= read -r file; do
-      name=$(basename "$(dirname "$file")")
-      is_internal_topic "$name" && continue
-      description=$(read_frontmatter_field "$file" "subtitle")
-      printf '%s\t%s\t%s\n' "$name" "$description" "canon/context/$name/index.md"
-    done < <(find "$CONTEXT_DIR" -mindepth 2 -maxdepth 2 -type f -name "index.md")
-  } | sort
-}
-
-list_text() {
-  local name description category target
-  log_step "Docs"
-  while IFS=$'\t' read -r name description category target; do
-    log_info "$name : $description"
-  done < <(collect_docs)
-
-  # Absent in a registry install, which ships docs/ without .claude/
-  if [ -d "$CONTEXT_DIR" ]; then
-    log_step "Domain context"
-    while IFS=$'\t' read -r name description target; do
-      log_info "$name : $description"
-    done < <(collect_context)
-  fi
-}
-
-emit_json_entry() {
-  local name="$1" description="$2" category="$3" target="$4"
-  [ "$JSON_FIRST" -eq 0 ] && printf ','
-  jq -nc \
-    --arg name "$name" \
-    --arg description "$description" \
-    --arg category "$category" \
-    --arg target "$target" \
-    '{name: $name, description: $description, category: $category, target: $target}'
-  JSON_FIRST=0
-}
-
-list_json() {
-  local name description category target
-  JSON_FIRST=1
-  printf '['
-  while IFS=$'\t' read -r name description category target; do
-    emit_json_entry "$name" "$description" "$category" "$target"
-  done < <(collect_docs)
-
-  if [ -d "$CONTEXT_DIR" ]; then
-    while IFS=$'\t' read -r name description target; do
-      emit_json_entry "$name" "$description" "" "$target"
-    done < <(collect_context)
-  fi
-  printf ']'
-}
-
-main() {
-  local json=0
-
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-    -h | --help) show_help ;;
-    --json)
-      json=1
-      shift
-      ;;
-    *) log_error "Unknown option: $1" ;;
-    esac
-  done
-
-  trap close_timeline EXIT
-
-  if [ "$json" -eq 1 ]; then
-    printf '{"docs":'
-    list_json
-    printf '}\n'
-    exit 0
-  fi
-
-  list_text
-}
-
-main "$@"

package/scripts/lib/frontmatter.sh

@@ -1,30 +0,0 @@
-#!/usr/bin/env bash
-
-# Reads one frontmatter field from a markdown file.
-#
-# Kept in bash because the list commands call it once per field per file
-# inside a loop, where shelling into the CLI would cost a process per read.
-# Index logic is TypeScript, in src/indexes/, and does not belong here.
-read_frontmatter_field() {
-  local file="$1"
-  local key="$2"
-  awk -v key="$key" '
-    NR == 1 && /^---$/ { in_fm = 1; next }
-    in_fm && /^---$/ { exit }
-    in_fm {
-      prefix = key ": "
-      if (index($0, prefix) == 1) {
-        val = substr($0, length(prefix) + 1)
-        if (length(val) >= 2) {
-          first = substr(val, 1, 1)
-          last = substr(val, length(val), 1)
-          if ((first == "\"" && last == "\"") || (first == "'\''" && last == "'\''")) {
-            val = substr(val, 2, length(val) - 2)
-          }
-        }
-        print val
-        exit
-      }
-    }
-  ' "$file"
-}

package/scripts/standards/list.sh

@@ -1,115 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
-
-source "$PROJECT_ROOT/scripts/lib/ui.sh"
-source "$PROJECT_ROOT/scripts/lib/frontmatter.sh"
-
-STANDARDS_DIR="$PROJECT_ROOT/standards"
-
-show_help() {
-  echo -e "${GREY}┌${NC}"
-  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} canon standards list [options]"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
-  echo -e "${GREY}│${NC}    --json       ${GREY}# Emit machine-readable JSON${NC}"
-  echo -e "${GREY}│${NC}    -h, --help   ${GREY}# Show this help message${NC}"
-  echo -e "${GREY}└${NC}"
-  exit 0
-}
-
-json_escape() {
-  local s="$1"
-  s="${s//\\/\\\\}"
-  s="${s//\"/\\\"}"
-  printf '%s' "$s"
-}
-
-# Emits the paths a standard's `## Scope` statement declares, as a JSON array.
-# The declaration is prose, so the contract is narrow on purpose: backticked
-# paths in the first sentence of the statement, or `*` for an attribute standard,
-# which names no path and says so in the same statement. An empty array means the
-# statement did not parse, which consumers report rather than skip.
-read_applies_to() {
-  local file="$1"
-  local scope first paths
-
-  scope=$(awk '/^## Scope[[:space:]]*$/ {found = 1; next} found && NF {print; exit}' "$file")
-  first="${scope%%. *}"
-  paths=$(printf '%s' "$first" | grep -o '`[^`]*`' | tr -d '`' || true)
-
-  if [ -z "$paths" ] && [[ "$scope" == *"attribute standard"* ]]; then
-    paths="*"
-  fi
-
-  printf '%s\n' "$paths" | jq -Rnc '[inputs | select(length > 0)]'
-}
-
-list_text() {
-  log_step "Standards"
-  local file name title
-  while IFS= read -r file; do
-    name=$(basename "$file" .md)
-    [ "$name" = "index" ] && continue
-    title=$(read_frontmatter_field "$file" "description")
-    log_info "$name : $title"
-  done < <(find "$STANDARDS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
-}
-
-# No `target` field. It named where a standard installed, and nothing installs
-# one now, so every value it could carry is either a path only this repository
-# has or a duplicate of what `canon standards <name>` reports. `content` already
-# carries the document, which is what a consumer wanted the path for.
-list_json() {
-  local first=1
-  local file name title applies_to
-  printf '['
-  while IFS= read -r file; do
-    name=$(basename "$file" .md)
-    [ "$name" = "index" ] && continue
-    title=$(read_frontmatter_field "$file" "description")
-    applies_to=$(read_applies_to "$file")
-    if [ "$first" -eq 0 ]; then
-      printf ','
-    fi
-    jq -nc \
-      --arg name "$name" \
-      --arg description "$title" \
-      --argjson appliesTo "$applies_to" \
-      --rawfile content "$file" \
-      '{name: $name, description: $description, appliesTo: $appliesTo, content: $content}'
-    first=0
-  done < <(find "$STANDARDS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
-  printf ']'
-}
-
-main() {
-  local json=0
-
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-    -h | --help) show_help ;;
-    --json)
-      json=1
-      shift
-      ;;
-    *) log_error "Unknown option: $1" ;;
-    esac
-  done
-
-  trap close_timeline EXIT
-
-  if [ "$json" -eq 1 ]; then
-    printf '{"standards":'
-    list_json
-    printf '}\n'
-    exit 0
-  fi
-
-  list_text
-}
-
-main "$@"

package/src/commands/pass-through.ts

@@ -1,39 +0,0 @@
-import type { Command } from 'commander'
-import { execScript } from '@/exec'
-import { intro } from '@/ui'
-
-/**
- * Registers the verbs a domain has not migrated yet, each forwarding to
- * `scripts/<domain>/<verb>.sh`. Naming them instead of catching everything on
- * the parent gives each verb its own `--help` and lets a migrated sibling sit
- * alongside them.
- */
-export function registerPassThroughVerbs(
-  parent: Command,
-  domain: string,
-  verbs: readonly string[],
-): void {
-  for (const verb of verbs) {
-    parent
-      .command(verb)
-      .description(`Run the ${domain} ${verb} command`)
-      .allowUnknownOption()
-      .allowExcessArguments(true)
-      .passThroughOptions()
-      .helpOption(false)
-      .action(async (_opts: unknown, cmd: Command) => {
-        if (!isHelpRequest(cmd.args)) intro(`canon ${domain}`)
-        await execScript(`${domain}/${verb}.sh`, cmd.args)
-      })
-  }
-}
-
-/**
- * Commander resolves `--help` before an action runs, so a pass-through verb
- * that keeps the built-in help option prints a one-line stub instead of the
- * script's usage. Disabling it lets the flag reach the script, which owns the
- * real flag surface, and this guard keeps the frame from opening around it.
- */
-function isHelpRequest(args: readonly string[]): boolean {
-  return args.includes('-h') || args.includes('--help')
-}

package/tooling/go/configs/scripts/verify.sh

@@ -1,142 +0,0 @@
-#!/bin/bash
-set -e
-set -o pipefail
-
-GREEN='\033[0;32m'
-RED='\033[0;31m'
-WHITE='\033[1;37m'
-GREY='\033[0;90m'
-NC='\033[0m'
-
-NESTED="${VERIFY_NESTED:-false}"
-
-log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
-log_error() {
-  echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
-  exit 1
-}
-log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
-log_skip() { echo -e "${GREY}│ - $1${NC}"; }
-
-pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line"; done; }
-
-check_dependencies() {
-  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
-  command -v go >/dev/null 2>&1 || log_error "go is not installed"
-  command -v golangci-lint >/dev/null 2>&1 || log_error "golangci-lint is not installed. Run 'go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest'"
-}
-
-check_package() {
-  [ -f package.json ] || log_error "No package.json here. Run 'bun init', then sync the stack again"
-}
-
-has_script() {
-  bun -e 'process.exit(require(process.cwd() + "/package.json").scripts?.[process.argv[1]] ? 0 : 1)' "$1"
-}
-
-# A subfolder synced with --skip base declares none of base's scripts, since
-# the repository root owns them. Each base phase runs only where its script is
-# declared, so this script passes on its own in that subfolder.
-run_base_phase() {
-  local title=$1
-  local script=$2
-  local err_msg=$3
-  local pass_msg=$4
-
-  log_step "$title"
-  if ! has_script "$script"; then
-    log_skip "Skipped: $script is not declared here, so the repository root runs it"
-    return
-  fi
-  run_check "bun run $script" "$err_msg"
-  log_info "$pass_msg"
-}
-
-check_markdown_bans() {
-  if ! command -v canon >/dev/null 2>&1; then
-    log_info "Skipped: no canon binary on PATH. Install with \`bun install --global @erclx/canon\`."
-    return 0
-  fi
-
-  local files=()
-  while IFS= read -r file; do
-    files+=("$file")
-  done < <(git ls-files --cached --others --exclude-standard -- '*.md' ':(exclude)CHANGELOG.md' ':(exclude)**/CHANGELOG.md')
-
-  if [ ${#files[@]} -eq 0 ]; then
-    log_info "No markdown file to check outside the exclusion set."
-    return 0
-  fi
-
-  local output code
-  if output=$(canon markdown audit "${files[@]}" 2>&1); then
-    code=0
-  else
-    code=$?
-  fi
-
-  case "$code" in
-  0)
-    log_info "No banned character"
-    ;;
-  1)
-    log_info "Skipped: canon markdown audit refused and measured nothing."
-    ;;
-  2)
-    echo "$output" | pipe_output
-    log_error "Markdown prose carries a banned character, or a relative link resolves to nothing on disk"
-    ;;
-  3)
-    echo "$output" | pipe_output
-    log_error "The markdown audit shipped an empty ban set, so the corpus was walked and nothing was looked for"
-    ;;
-  *)
-    log_error "canon markdown audit exited $code, which is neither a pass nor a finding"
-    ;;
-  esac
-}
-
-run_check() {
-  local cmd=$1
-  local err_msg=$2
-  local output
-  if ! output=$(eval "$cmd" 2>&1); then
-    echo "$output" | pipe_output
-    log_error "$err_msg"
-  fi
-  echo "$output" | pipe_output
-}
-
-main() {
-  check_dependencies
-  check_package
-
-  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
-
-  echo -e "${GREY}├${NC} ${WHITE}Typecheck${NC}"
-  run_check "bun run typecheck" "Typecheck failed"
-  log_info "Typecheck passed"
-
-  log_step "Lint"
-  run_check "bun run lint" "Lint failed"
-  log_info "Lint passed"
-
-  run_base_phase "Formatting" "format" "Format failed" "Format applied"
-  run_base_phase "Format check" "check:format" "Format check failed" "Format check passed"
-  run_base_phase "Spelling" "check:spell" "Spell check failed" "Spell check passed"
-  run_base_phase "Shell" "check:shell" "Shell check failed" "Shell check passed"
-
-  log_step "Unit tests"
-  run_check "bun run test:run" "Unit tests failed"
-  log_info "Unit tests passed"
-
-  log_step "Markdown bans"
-  check_markdown_bans
-
-  if [ "$NESTED" = false ]; then
-    echo -e "${GREY}└${NC}\n"
-    echo -e "${GREEN}✓ Verification passed${NC}"
-  fi
-}
-
-main "$@"

package/tooling/php/configs/scripts/verify.sh

@@ -1,147 +0,0 @@
-#!/bin/bash
-set -e
-set -o pipefail
-
-GREEN='\033[0;32m'
-RED='\033[0;31m'
-WHITE='\033[1;37m'
-GREY='\033[0;90m'
-NC='\033[0m'
-
-NESTED="${VERIFY_NESTED:-false}"
-
-log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
-log_error() {
-  echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
-  exit 1
-}
-log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
-log_skip() { echo -e "${GREY}│ - $1${NC}"; }
-
-pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line"; done; }
-
-check_dependencies() {
-  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
-  command -v php >/dev/null 2>&1 || log_error "php is not installed"
-  command -v composer >/dev/null 2>&1 || log_error "composer is not installed"
-}
-
-check_package() {
-  [ -f package.json ] || log_error "No package.json here. Run 'bun init', then sync the stack again"
-}
-
-check_vendor() {
-  [ -x vendor/bin/phpunit ] || log_error "No vendor/bin/phpunit here. Run 'composer install'"
-}
-
-has_script() {
-  bun -e 'process.exit(require(process.cwd() + "/package.json").scripts?.[process.argv[1]] ? 0 : 1)' "$1"
-}
-
-# A subfolder synced with --skip base declares none of base's scripts, since
-# the repository root owns them. Each base phase runs only where its script is
-# declared, so this script passes on its own in that subfolder.
-run_base_phase() {
-  local title=$1
-  local script=$2
-  local err_msg=$3
-  local pass_msg=$4
-
-  log_step "$title"
-  if ! has_script "$script"; then
-    log_skip "Skipped: $script is not declared here, so the repository root runs it"
-    return
-  fi
-  run_check "bun run $script" "$err_msg"
-  log_info "$pass_msg"
-}
-
-check_markdown_bans() {
-  if ! command -v canon >/dev/null 2>&1; then
-    log_info "Skipped: no canon binary on PATH. Install with \`bun install --global @erclx/canon\`."
-    return 0
-  fi
-
-  local files=()
-  while IFS= read -r file; do
-    files+=("$file")
-  done < <(git ls-files --cached --others --exclude-standard -- '*.md' ':(exclude)CHANGELOG.md' ':(exclude)**/CHANGELOG.md')
-
-  if [ ${#files[@]} -eq 0 ]; then
-    log_info "No markdown file to check outside the exclusion set."
-    return 0
-  fi
-
-  local output code
-  if output=$(canon markdown audit "${files[@]}" 2>&1); then
-    code=0
-  else
-    code=$?
-  fi
-
-  case "$code" in
-  0)
-    log_info "No banned character"
-    ;;
-  1)
-    log_info "Skipped: canon markdown audit refused and measured nothing."
-    ;;
-  2)
-    echo "$output" | pipe_output
-    log_error "Markdown prose carries a banned character, or a relative link resolves to nothing on disk"
-    ;;
-  3)
-    echo "$output" | pipe_output
-    log_error "The markdown audit shipped an empty ban set, so the corpus was walked and nothing was looked for"
-    ;;
-  *)
-    log_error "canon markdown audit exited $code, which is neither a pass nor a finding"
-    ;;
-  esac
-}
-
-run_check() {
-  local cmd=$1
-  local err_msg=$2
-  local output
-  if ! output=$(eval "$cmd" 2>&1); then
-    echo "$output" | pipe_output
-    log_error "$err_msg"
-  fi
-  echo "$output" | pipe_output
-}
-
-main() {
-  check_dependencies
-  check_package
-  check_vendor
-
-  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
-
-  echo -e "${GREY}├${NC} ${WHITE}Typecheck${NC}"
-  run_check "bun run typecheck" "Typecheck failed"
-  log_info "Typecheck passed"
-
-  log_step "Lint"
-  run_check "bun run lint" "Lint failed"
-  log_info "Lint passed"
-
-  run_base_phase "Formatting" "format" "Format failed" "Format applied"
-  run_base_phase "Format check" "check:format" "Format check failed" "Format check passed"
-  run_base_phase "Spelling" "check:spell" "Spell check failed" "Spell check passed"
-  run_base_phase "Shell" "check:shell" "Shell check failed" "Shell check passed"
-
-  log_step "Unit tests"
-  run_check "bun run test:run" "Unit tests failed"
-  log_info "Unit tests passed"
-
-  log_step "Markdown bans"
-  check_markdown_bans
-
-  if [ "$NESTED" = false ]; then
-    echo -e "${GREY}└${NC}\n"
-    echo -e "${GREEN}✓ Verification passed${NC}"
-  fi
-}
-
-main "$@"