lgtm-specs 0.0.4

package/rules/laws/typescript/TS-00008-modules.md

@@ -0,0 +1,28 @@
+# Module Organization (TS-00008)
+
+**Source**: [The Law of TypeScript](../../../docs/meta/languages/typescript/04-design.md#3-module-organization)
+**Tags**: #structural #typescript #architecture
+**Related**: [Clean Packages](../go/GO-00006-packages.md)
+
+## Definition
+
+Organize code by Feature/Domain, not by technical type.
+
+## Requirements
+
+1.  **Feature Folders**: Group related components, styles, and tests in one folder.
+2.  **No `types/`**: Keep types co-located with the code that uses them.
+3.  **Barrels**: Use `index.ts` to export public API of a module.
+
+## Anti-Patterns
+
+- **Technical Split**: `src/components`, `src/utils`, `src/types` (MVC style).
+- **Deep Imports**: Importing `module/internal/helper` instead of `module`.
+
+## Examples
+
+**Bad:**
+`src/types/User.ts`, `src/controllers/UserController.ts`
+
+**Good:**
+`src/features/user/types.ts`, `src/features/user/controller.ts`

package/rules/policies/README.md

@@ -0,0 +1,12 @@
+# Project Policies
+
+This directory contains repository-specific configuration and style rules.
+
+## Usage
+
+- **Default**: `default.md` is used if no other policy matches.
+- **Custom**: Add `[project]-policy.md` for specific repos.
+
+## Index
+
+- [Default Policy](default.md)

package/rules/policies/default.md

@@ -0,0 +1,28 @@
+# Default Policy (POL-00000)
+
+**Source**: [Industry Best Practices](../../docs/meta/industry_best_practices.md#1-solid-principles)
+**Tags**: #operational #policy #default
+**Related**: [KISS](../constitution/CONS-00010-kiss.md)
+
+## Definition
+
+Baseline defaults for any project without specific configuration.
+
+## Requirements
+
+1.  **Format**: Use standard language formatters (`gofmt`, `prettier`).
+2.  **Lint**: Use standard linters (`golangci-lint`, `eslint`).
+3.  **Naming**: Idiomatic casing (camelCase for JS, snake_case for Python).
+
+## Anti-Patterns
+
+- **Custom Style**: Arguing about whitespace.
+- **No CI**: Merging without checks.
+
+## Examples
+
+**Bad:**
+Manually formatting JSON.
+
+**Good:**
+`bun run format`

package/scripts/README.md

@@ -0,0 +1,45 @@
+# Scripts
+
+## Index
+
+- `validate_specs.py`: Repository integrity checks (rules structure, indexing, capability registry).
+- `generate_release_notes.py`: Categorized release notes for GitHub releases.
+
+## Validation
+
+Run validation:
+
+```bash
+python3 scripts/validate_specs.py
+```
+
+Optional: validate external Markdown links (network-dependent):
+
+```bash
+python3 scripts/validate_specs.py --check-urls
+```
+
+Tune timeout if needed:
+
+```bash
+python3 scripts/validate_specs.py --check-urls --url-timeout 12
+```
+
+Ignore a specific external URL (repeatable):
+
+```bash
+python3 scripts/validate_specs.py --check-urls --url-ignore "https://example.com/badge.svg"
+```
+
+Run the full local check (validation + formatting):
+
+```bash
+bun run check
+```
+
+If the repo ever needs a temporary warnings baseline during a migration:
+
+```bash
+python3 scripts/validate_specs.py --write-baseline scripts/validate_baseline.txt
+python3 scripts/validate_specs.py --baseline scripts/validate_baseline.txt
+```

package/scripts/generate_release_notes.py

@@ -0,0 +1,376 @@
+"""Generate GitHub release notes for a semver tag.
+
+This script is intended to run in CI on tag push.
+
+Output goals:
+- Summary paragraph.
+- Highlights grouped by impacted repo area (Knowledge, Agents, Modes, Integration, Models, etc.).
+- Keep it scannable; omit long commit/PR listings.
+
+Inputs:
+- Tag name like "v0.0.2" (from GITHUB_REF_NAME).
+- Git history with tags available (checkout fetch-depth 0).
+
+Auth:
+- If GITHUB_TOKEN is set, the script fetches PR metadata and file lists via GitHub API.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+
+
+TYPE_RE = re.compile(r"^(?P<type>[a-z]+)(\((?P<scope>[^)]+)\))?:\s+(?P<rest>.+)$")
+MERGE_PR_RE = re.compile(r"^Merge pull request #(?P<num>\d+)\b")
+
+
+@dataclass(frozen=True)
+class PR:
+    number: int
+    title: str
+    url: str
+    type: str
+    keyword: str
+    files: tuple[str, ...] = ()
+
+
+def sh(*args: str) -> str:
+    out = subprocess.check_output(list(args), stderr=subprocess.STDOUT)
+    return out.decode("utf-8").strip()
+
+
+def git_tags() -> list[str]:
+    txt = sh("git", "tag", "-l", "v*", "--sort=-version:refname")
+    return [line.strip() for line in txt.splitlines() if line.strip()]
+
+
+def previous_tag(current: str) -> str | None:
+    for t in git_tags():
+        if t != current:
+            return t
+    return None
+
+
+def merged_pr_merges(prev: str | None, cur: str) -> list[tuple[int, str]]:
+    """Return (pr_number, merge_commit_sha) pairs."""
+
+    rev_range = f"{prev}..{cur}" if prev else cur
+    txt = sh(
+        "git",
+        "log",
+        "--merges",
+        "--first-parent",
+        "--pretty=%H %s",
+        rev_range,
+    )
+
+    out: list[tuple[int, str]] = []
+    seen: set[int] = set()
+    for line in txt.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        sha, subj = line.split(" ", 1)
+        m = MERGE_PR_RE.match(subj.strip())
+        if not m:
+            continue
+        n = int(m.group("num"))
+        if n in seen:
+            continue
+        seen.add(n)
+        out.append((n, sha))
+    return out
+
+
+def merge_pr_title_from_commit(sha: str) -> str | None:
+    """Extract PR title from a GitHub merge commit body."""
+
+    body = sh("git", "log", "-1", "--format=%b", sha)
+    for line in body.splitlines():
+        t = line.strip()
+        if t:
+            return t
+    return None
+
+
+def files_from_commit(sha: str) -> tuple[str, ...]:
+    # Merge commits require `-m` to surface per-parent file lists.
+    txt = sh("git", "diff-tree", "-m", "--no-commit-id", "--name-only", "-r", sha)
+    files = [line.strip() for line in txt.splitlines() if line.strip()]
+    return tuple(sorted({f for f in files if f}))
+
+
+def local_pr(repo: str, num: int, sha: str) -> PR:
+    url = f"https://github.com/{repo}/pull/{num}"
+    title = merge_pr_title_from_commit(sha) or f"PR #{num}"
+    return PR(
+        number=num,
+        title=title,
+        url=url,
+        type=infer_type_from_title(title),
+        keyword=infer_keyword_from_title(title),
+        files=files_from_commit(sha),
+    )
+
+
+def infer_type_from_title(title: str) -> str:
+    m = TYPE_RE.match(title.strip())
+    if not m:
+        return "other"
+    t = m.group("type")
+    return t.lower()
+
+
+def infer_keyword_from_title(title: str) -> str:
+    m = TYPE_RE.match(title.strip())
+    if not m:
+        return "other"
+    scope = m.group("scope")
+    t = m.group("type")
+    return (scope or t or "other").lower()
+
+
+def strip_type_prefix(title: str) -> str:
+    m = TYPE_RE.match(title.strip())
+    return m.group("rest") if m else title.strip()
+
+
+def github_api_get_json(url: str, token: str | None) -> dict:
+    req = urllib.request.Request(url)
+    req.add_header("User-Agent", "lgtm-specs-release-notes")
+    req.add_header("Accept", "application/vnd.github+json")
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def fetch_pr_files(repo: str, num: int, token: str | None) -> tuple[str, ...]:
+    if not token:
+        return ()
+
+    files: list[str] = []
+    page = 1
+    per_page = 100
+    while True:
+        api = f"https://api.github.com/repos/{repo}/pulls/{num}/files?per_page={per_page}&page={page}"
+        data = github_api_get_json(api, token)
+        if not isinstance(data, list):
+            break
+        batch = [str(item.get("filename")) for item in data if isinstance(item, dict) and item.get("filename")]
+        files.extend(batch)
+        if len(batch) < per_page:
+            break
+        page += 1
+
+    # Stable ordering.
+    return tuple(sorted({f for f in files if f}))
+
+
+def fetch_pr(repo: str, num: int, token: str | None) -> PR:
+    api = f"https://api.github.com/repos/{repo}/pulls/{num}"
+    data = github_api_get_json(api, token)
+    title = str(data.get("title") or f"PR #{num}")
+    url = str(data.get("html_url") or f"https://github.com/{repo}/pull/{num}")
+    return PR(
+        number=num,
+        title=title,
+        url=url,
+        type=infer_type_from_title(title),
+        keyword=infer_keyword_from_title(title),
+        files=fetch_pr_files(repo, num, token),
+    )
+
+
+def pr_areas(pr: PR) -> set[str]:
+    # Repo-area classification for highlights.
+    areas: set[str] = set()
+
+    for f in pr.files:
+        if f.startswith("rules/") or f.startswith("docs/meta/"):
+            areas.add("Knowledge")
+        if f.startswith("agents/modes/"):
+            areas.add("Modes")
+        elif f.startswith("agents/roles/"):
+            areas.add("Agents")
+        elif f.startswith("agents/"):
+            areas.add("Agents")
+        if f.startswith("integrate/"):
+            areas.add("Integration")
+        if f.startswith("models/"):
+            areas.add("Models")
+        if f.startswith(".github/workflows/"):
+            areas.add("CI")
+        if f.startswith("scripts/"):
+            areas.add("Tooling")
+        if f.startswith("contribute/"):
+            areas.add("Contributing")
+
+    if not areas:
+        # Fallback: infer from conventional scope/type.
+        kw = (pr.keyword or pr.type or "").lower()
+        if kw in ("agents", "review", "reviewers"):
+            areas.add("Agents")
+        elif kw in ("integrate", "integration"):
+            areas.add("Integration")
+        elif kw in ("models", "model"):
+            areas.add("Models")
+        elif kw in ("ci", "release"):
+            areas.add("CI")
+        elif kw in ("docs",):
+            areas.add("Knowledge")
+        else:
+            areas.add("Other")
+
+    return areas
+
+
+def keyword_search_url(repo: str, keyword: str) -> str:
+    # Search merged PR titles for a keyword or conventional prefix.
+    conventional = {
+        "feat",
+        "fix",
+        "docs",
+        "ci",
+        "chore",
+        "refactor",
+        "test",
+        "perf",
+        "build",
+        "style",
+    }
+    needle = f"{keyword}:" if keyword in conventional else keyword
+    q = f"is:pr is:merged in:title \"{needle}\""
+    return f"https://github.com/{repo}/pulls?q={urllib.parse.quote(q)}"
+
+
+def pr_link(pr: PR) -> str:
+    return f"[#${pr.number}]({pr.url})".replace("#$", "#")
+
+
+def summary_paragraph(tag: str, prev: str | None, prs: list[PR], areas_sorted: list[str]) -> str:
+    n = len(prs)
+    prev_txt = prev if prev else "the previous release"
+    if not areas_sorted or areas_sorted == ["Other"]:
+        return f"{tag} includes {n} merged PR(s) since {prev_txt}."
+
+    top = areas_sorted[:3]
+    if len(top) == 1:
+        focus = top[0]
+    elif len(top) == 2:
+        focus = f"{top[0]} and {top[1]}"
+    else:
+        focus = f"{top[0]}, {top[1]}, and {top[2]}"
+
+    return f"{tag} includes {n} merged PR(s) since {prev_txt}, focusing on {focus}."
+
+
+def compare_url(repo: str, prev: str | None, cur: str) -> str:
+    if not prev:
+        return f"https://github.com/{repo}/commits/{cur}"
+    return f"https://github.com/{repo}/compare/{prev}...{cur}"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(add_help=True)
+    ap.add_argument("--tag", type=str, default=os.environ.get("GITHUB_REF_NAME"))
+    ap.add_argument("--repo", type=str, default=os.environ.get("GITHUB_REPOSITORY"))
+    ap.add_argument("--output", type=str, required=True)
+    args = ap.parse_args()
+
+    tag = (args.tag or "").strip()
+    repo = (args.repo or "").strip()
+    if not tag:
+        print("ERROR: missing --tag (or GITHUB_REF_NAME)", file=sys.stderr)
+        return 2
+    if not repo:
+        print("ERROR: missing --repo (or GITHUB_REPOSITORY)", file=sys.stderr)
+        return 2
+
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    prev = previous_tag(tag)
+    pr_merges = merged_pr_merges(prev, tag)
+
+    prs: list[PR] = []
+    for n, sha in pr_merges:
+        if token:
+            try:
+                prs.append(fetch_pr(repo, n, token))
+                continue
+            except Exception:
+                pass
+        prs.append(local_pr(repo, n, sha))
+
+    # Group by impacted area.
+    by_area: dict[str, list[PR]] = {}
+    for pr in prs:
+        for area in pr_areas(pr):
+            by_area.setdefault(area, []).append(pr)
+
+    area_order = [
+        "Knowledge",
+        "Agents",
+        "Modes",
+        "Integration",
+        "Models",
+        "CI",
+        "Tooling",
+        "Contributing",
+        "Other",
+    ]
+
+    areas_sorted = [a for a in area_order if a in by_area]
+
+    lines: list[str] = []
+    lines.append(f"# {tag}")
+    lines.append("")
+    lines.append("## Summary")
+    lines.append("")
+    lines.append(summary_paragraph(tag, prev, prs, [a for a in areas_sorted if a != "Other"]))
+    lines.append("")
+
+    if prs:
+        lines.append("## Highlights")
+        lines.append("")
+
+        # Show up to 6 areas. If everything is "Other", show it anyway.
+        areas_to_show = [a for a in areas_sorted if a != "Other"]
+        if not areas_to_show and "Other" in areas_sorted:
+            areas_to_show = ["Other"]
+
+        for area in areas_to_show[:6]:
+            items = by_area.get(area, [])
+            if not items:
+                continue
+
+            # Prefer up to 2 representative PR titles to describe the area.
+            reps = items[:2]
+            titles = "; ".join(strip_type_prefix(p.title) for p in reps)
+            links = ", ".join(pr_link(p) for p in items[:4])
+            if len(items) > 4:
+                links = f"{links}, ..."
+
+            lines.append(f"- {area}: {titles} ({links})")
+
+        lines.append("")
+
+    lines.append(f"**Full Changelog**: {compare_url(repo, prev, tag)}")
+    lines.append("")
+
+    out = "\n".join(lines)
+    with open(args.output, "w", encoding="utf-8") as f:
+        f.write(out)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())